The REPL is a Node vm context that the investigator runs JavaScript cells in. It holds the
domain’s globals, the toolkit helpers and the script library, keeps its variables between cells,
and writes every cell to the journal. What a cell prints goes to the investigator’s model and
stays in its session. It is the inner face of src/server.mjs.
Files
| File | What is in it |
|---|---|
| src/server.mjs | runCell, newContext, safeJson, snapshot, restoreFrom, mayRestore, refreshScripts, the scripts object, helpText, and the repl, help, reset and load tools. |
| src/core/rewrite.mjs | rewriteCell: turns a cell into an async script whose top-level names become globals. |
| src/core/toolkit.mjs | The toolkit object: clip, shape, pick, omit, table, top, groupBy, countBy, sumBy, since, minutes. |
| src/domains.mjs | loadDomain: where makeGlobals, scriptsDir, apiDoc and beforeCell come from. |
| domains/code/repo.mjs | makeRepo: the read-only repo global (GIT_ALLOWED, GIT_DENIED, path checks). |
| src/transcripts/index.mjs | makeHistory: the history global of the sessions domain. |
| test/repl.mjs | The REPL over MCP with no model. |
How a server becomes a REPL
src/server.mjs starts as either face. With ASK_KIT_INNER=1 it registers four tools through
replTool. Without it, replTool is a no-op and the server registers only ask
(see Life of one ask).
| Tool | What it does |
|---|---|
repl |
Runs a cell. Inputs: code, maxChars (200 to 100000, default 4000), timeoutSeconds (1 to 600, default 120). |
help |
Returns the script list with parameters and results, the domain’s api.d.ts and the current variables. |
reset |
Builds a fresh context and deletes the snapshot. Drafts and the journal stay. |
load |
Copies the saved variables of another session’s REPL into this one, if mayRestore allows it. |
At start-up the server calls loadDomain(ASK_KIT_DOMAIN), then DOMAIN.makeGlobals({ push, config }).
push is how a domain global reports each call it makes (a ripgrep run, a transcript read) so it
appears in the cell’s journal entry. newContext() then builds the context.
What a cell can see
newContext creates the context with vm.createContext from these names and nothing else
added on purpose:
vm.createContext({
...GLOBALS, // the domain's globals: repo for code, history and cite for sessions
scripts, // run, list, show, draft
tk: toolkit, // the same helpers, namespaced
...toolkit, // and as plain globals
console: { log, info, warn, error }, // captured, returned with the result
});
A fresh vm context has the JavaScript built-ins (JSON, Math, Map, Promise, Date) and
none of Node’s: there is no require, process, fs, fetch or import. The investigator
reaches data and the network only through the domain’s globals. baseline records the names
present after creation, and userNames() is everything added since, which is what gets
snapshotted.
The same helpers and domain globals are passed to scripts, as ({ ...GLOBALS, tk: toolkit }, params).
The toolkit
src/core/toolkit.mjs has no state. Each helper returns data the investigator prints or keeps.
| Helper | What it returns |
|---|---|
shape(x, depth = 3) |
Keys, types and array lengths of a value. safeJson uses it to describe a clipped result. |
table(rows, cols, { width = 60 }) |
A text table; cols defaults to the first row’s keys; cells are cut at width. |
top(rows, key, n = 10) |
The n rows with the highest key (a field name or a function). |
groupBy(rows, key) |
An object of arrays. |
countBy(rows, key) |
Counts per key, most frequent first. |
sumBy(rows, key) |
A number; non-numbers count as 0. |
pick(rows, ...keys), omit(rows, ...keys) |
Rows with only, or without, those keys. Works on one object too. |
clip(v, max = 400) |
A string cut with … [+N chars]; null for null or undefined. |
since(hours) |
An ISO time that many hours ago. |
minutes(ms) |
Minutes, one decimal. |
The repl tool description names the helpers shape, pick, table, top, groupBy, countBy, sumBy, since; omit, clip and minutes also exist but are not in that text. A domain’s own helper
(cite in the sessions domain) is a domain global, not part of the toolkit.
The script library
refreshScripts runs before every cell and on help. It lists the .mjs files in the domain’s
scriptsDir and in the session’s drafts folder (STATE_DIR/drafts/<session>), builds a signature
from each file’s path and mtime, and does nothing if the signature has not changed. Otherwise it
clears the registry and re-imports each file with ?v=<mtime> so Node does not serve a cached
module. A script must export a default function and may export meta (purpose, params,
returns, example). A file that fails to load is reported in the next result as
[scripts that failed to load: ...].
scripts.run(name, params) calls the function with ({ ...GLOBALS, tk: toolkit }, params) and
records { name, draft, ok, ms } in cellScripts. scripts.draft(name, source) writes a draft
file (name: lowercase letters, digits and dashes) that loads before the next cell.
Add a script covers writing one.
How a cell runs
runCell(code, maxChars, timeoutSeconds) in src/server.mjs, in order:
- Queue. The
replhandler chains each call ontoqueue, so cells in one REPL run one at a time. - Refresh.
refreshScripts(), resetcellCalls,cellScriptsandlogs, and call the domain’s optionalbeforeCell(GLOBALS). - Rewrite.
rewriteCell(code)returns{ script, declared }. - Run.
vm.runInContext(script, context, { filename: "cell.js" })returns a promise. It is raced against a timer that rejects withcell timed out after Ns. - On error. The first 8 lines of the stack are kept. The cell’s declared names that now have
a value are shown with
shape(value, 2)(“What this cell’s values look like”), because a model that guessed a result’s shape tends to send the same cell again. If the code equals the last failed cell, the result says so. - Snapshot.
snapshot()saves the variables (see below). - Result text. Parts joined by blank lines: a start-up note on the first cell after a restore,
script load errors, captured
consoleoutput (first 4000 characters), the result throughsafeJson(value, maxChars), a repeat warning, a note of variables that could not be saved, and a closing[<ms> ms, <n> calls]. - Journal. One line in
STATE_DIR/<session>.jsonl:ts,session,ok,ms,code,declared,resultChars,repeat,error,scripts,calls,snapshot,restored.
Why the cell is rewritten
The investigator writes const hits = await repo.rg("foo") in one cell and uses hits in the
next. If the cell ran as written, inside the async function that gives it await, hits would be
local to that function and gone. rewriteCell in src/core/rewrite.mjs fixes that by parsing the
cell with acorn (ecmaVersion: "latest", allowAwaitOutsideFunction,
allowReturnOutsideFunction) and editing the top-level statements as text:
| Top-level statement | Becomes |
|---|---|
const x = v / let / var |
globalThis.x = (v); |
const { a, b } = v |
globalThis.a = undefined; globalThis.b = undefined; ({ a, b } = (v)); |
function f() {} |
globalThis.f = (function f() {}); |
class C {} |
globalThis.C = (class C {}); |
| a last expression statement | return (expr); |
The result is wrapped as (async () => {\n...\n})(). declared lists every name the cell
defined, which runCell uses for the error hints and for spotting repeats. Only top-level
statements are rewritten; a const inside a block, a function or a loop stays local. A const
becomes an assignment, so a later cell can declare the same name again without an error.
Two consequences to know:
- A cell that ends in a statement other than an expression (a
forloop, anif) returnsundefined. The investigator has to end with the value it wants back. - A syntax error throws from
acorn.parse, whichrunCellreports as the cell’s error.
Clipping a result
safeJson(value, max) returns strings as they are (cut at max), and anything else as JSON with
a replacer that prints Map and Set contents, bigints, [Function name] and [Circular].
When the text is longer than max, it is cut and followed by … [clipped: N of M chars. Shape of the whole value: ... Keep it in a variable and return only the fields you need.]. Every character
returned stays in the investigator’s context, so maxChars is the main lever on cost. The API
loop in askApi always passes 4000.
Repeated cells
seenCells keys each cell by its code with the names it declares replaced by _ and whitespace
collapsed, so the same search under a new variable name is caught. A repeat that returns the
same result gets “Running it again finds nothing new”; a repeat with a different result gets “Use
the earlier variables”.
Timeouts
Three limits apply to a cell:
- The REPL’s own
timeoutSeconds(default 120, maximum 600). - The API loop’s value:
min(CELL_MAX_S = 60, time left - 2s), and the MCP call to the REPL gets that plus 5 seconds. - The CLI investigators’ tool timeout. Codex’s config sets
mcp_servers.repl.tool_timeout_sec=180(incodexArgs).
The timer only rejects the promise. It does not stop the code. A cell that is waiting on
something (a slow subprocess) is abandoned and the REPL moves on, but the work behind it keeps
running, and a synchronous loop that never yields blocks the whole server, since vm.runInContext
is called with no timeout option. Domain globals bound their own work: exec in repo.mjs has a
60 second timeout and a 32 MB output limit per command.
Saved state between cells and for follow-ups
After every cell, snapshot() writes STATE_DIR/<session>.snapshot. For each name in userNames():
- A function is stored as its source text (
v.toString()) and rebuilt on restore. A function that uses a variable from the cell’s closure loses it. - Anything else goes through
v8.serialize. A value that cannot be serialised (a class instance with a native handle, say) is dropped and named in[not kept across restarts: ...]. - The total is capped at 64 MB (
SNAPSHOT_MAX_BYTES); a variable that would go over is dropped.
The file is written to a temporary name and renamed, so a crash leaves the old snapshot. It
records the session, the caller (the asking agent’s session) and savedAt.
On start-up the server calls restoreFrom(SESSION); if that finds nothing and ASK_KIT_INHERIT is
set, restoreFrom(INHERIT, { neutral: true }). The first cell’s result then begins with
[restored N name(s) ... : a, b]. This is what makes the three cases work:
| Case | Session id the REPL uses | What it restores |
|---|---|---|
| API follow-up | ask-<askId>, reused on continue |
its own snapshot |
| Fork of a warm CLI session | the CLI’s own session id (see below) | nothing of its own, so the warm session’s snapshot, via INHERIT |
| CLI follow-up | the same CLI session id as the earlier ask | its own snapshot |
mayRestore decides who may read a snapshot. A snapshot made for a caller (record.caller set)
is restored only by a REPL started for the same caller (ASK_KIT_CALLER). A snapshot with no
caller is restored by the session that made it, or by a REPL started with neutral, which is how a
fork reads the warm session. Another asking session’s REPL is refused with
that REPL belongs to another session's ask. Variables from one agent’s investigation do not
leak into another’s.
replEnv in src/ask.mjs is where these environment variables are set for the investigator’s
server: ASK_KIT_INNER, ASK_KIT_DOMAIN, the domain’s childEnv(), the ASK_KIT_CONFIG and
ASK_KIT_STATE overrides, ASK_KIT_INHERIT and ASK_KIT_CALLER (the warm session’s id and the
asking session) when forking, and ASK_KIT_SESSION when the loop picks the id itself.
What is and is not allowed
Everything the investigator can do goes through the domain’s globals, so “read-only” is a property of those globals:
code:makeReporunsrgand a fixed list of git subcommands (GIT_ALLOWED:log,show,blame,diff,ls-files,grep,rev-parse,status,shortlog,branch,tag) throughexecFilewith no shell, rejects options that write or run programs (GIT_DENIED), and checks that every path stays inside the repository (inside).sessions:makeHistoryreads transcript files and keeps its own index under the state folder (src/transcripts/common.mjswrites it); it never writes to the transcripts.- Scripts and drafts are the exception:
scripts.draftwrites a.mjsfile to the session’s drafts folder, and the REPL’s own snapshot and journal are written by the server, not the cell.
The vm module is not a security boundary. The context has no Node globals, but code that
reaches the host through an object passed in could escape it. The limits are guard rails for a
model that is trying to answer a question; don’t run untrusted code in it. The CLI
investigators have a second layer of limits (see Backends).
What to look at when changing it
- A new global for the REPL: a domain’s
makeGlobals, notserver.mjs. See Domain API and Write a domain. - A new toolkit helper: add it to
src/core/toolkit.mjsand to thetoolkitobject at the bottom. It is also a fingerprint file, so adding one re-warms the CLI investigators. Add it to the domains’api.d.ts(the “Toolkit” section) or the investigator will not know it exists. - A problem with a cell that “does nothing”: print what
rewriteCellreturns for it. The usual causes are a last statement that is not an expression, or a name declared inside a block. - Result size and clipping:
DEFAULT_MAX_CHARS,safeJson, and themaxCharsthe API loop passes. - Snapshot behaviour:
snapshot,restoreFrom,mayRestore. A change to the record format needs old snapshots to still read, or to be refused cleanly. - The text the investigator sees after each cell is part of its behaviour (the error hints, the repeat warnings, the clip note). Change them the way you would change instructions: run the benchmark (Run the benchmark).
Tests: test/repl.mjs starts the inner server with a throwaway config and checks that help lists
the sessions scripts, that a script runs, that a variable (r) is still there in the next cell, and
that a restarted server restores it (restored .*r). It also checks the outer face lists only
ask. test/fixtures.mjs covers the transcript adapters that the history global reads. There is
no unit test for rewriteCell or the toolkit on their own; Testing
says how to add one.