codemode@earendil-works/pi-codemode

要点Key points

• 最大的文件是 runtime/prelude-source.ts：它是一段字符串形式的 JavaScript，在 VM 里搭出 tools、text()、store() 等全部脚本 API。The largest file is runtime/prelude-source.ts: JavaScript held in a string that builds the whole script API — tools, text(), store() and the rest — inside the VM.
• ./declarations 与 ./source 不加载 wasm，宿主可以只用它们生成工具描述或校验脚本，而不启动沙箱。./declarations and ./source do not load wasm, so a host can generate tool descriptions or validate scripts without starting a sandbox.
• ./worker 单独导出，是为了打包场景：打包后的宿主把它作为独立入口，再通过 workerUrl 传给沙箱。./worker is exported separately for bundling: a bundled host makes it a separate entry and passes it to the sandbox as workerUrl.

工作原理How it works

1. new CodemodeSandbox({ tools, globals, timeoutMs, memoryLimitBytes })。new CodemodeSandbox({ tools, globals, timeoutMs, memoryLimitBytes }).
2. renderDeclarations({ tools, globals }) 生成放进工具描述的 TypeScript。renderDeclarations({ tools, globals }) produces the TypeScript that goes into the tool description.
3. parseCodemodeSource(input) 拆出可选的 // @options: 行，再 sandbox.execute(code, { signal, store })。parseCodemodeSource(input) splits off an optional // @options: line, then sandbox.execute(code, { signal, store }).

要点Key points

• worker 的存在是为了不让空转的脚本卡住宿主线程；每次执行都用新 worker，失控的脚本直接被 terminate()，不会影响下一次。The worker exists so that a spinning script never blocks the host thread; a fresh worker per run means a runaway script is simply terminate()d and cannot affect the next run.
• 结束时宿主先把共享的 4 字节 interrupt 置 1，再 terminate()：VM 的中断处理器会轮询它，因为 Bun 的 worker.terminate() 停不住在 wasm 里空转的线程（见 runtime/protocol.ts）。On finish the host sets the shared 4-byte interrupt to 1 before terminate(): the VM's interrupt handler polls it, because Bun's worker.terminate() cannot stop a thread spinning in wasm (see runtime/protocol.ts).
• maxStackSize 让深递归变成可捕获的 RangeError 而不是 wasm 陷阱；QuickJS 自己写到 fd 1/2 的诊断被丢弃，不会弄乱宿主的 TUI。maxStackSize turns deep recursion into a catchable RangeError instead of a wasm trap; QuickJS's own diagnostics on fd 1/2 are discarded so they never garble the host's TUI.
• prelude 在脚本运行前冻结所有内建对象，因为它和脚本共用这些对象：被篡改的 toJSON 否则可能让 prelude 向宿主发出错误的数据。The prelude freezes every built-in before the script runs because it shares them with the script: a patched toJSON could otherwise make the prelude send the host malformed data.

工作原理How it works

1. 宿主：new Worker(workerUrl, { workerData })，workerData 带上编译好的 wasm 模块（结构化克隆时共享代码）。Host: new Worker(workerUrl, { workerData }); workerData carries the compiled wasm module (structured clone shares the code).
2. worker：QuickJS.create({ memoryLimit, maxStackSize, interruptHandler, wasi }) → vm.newFunction("bridge") → 求值 prelude。Worker: QuickJS.create({ memoryLimit, maxStackSize, interruptHandler, wasi }) → vm.newFunction("bridge") → evaluate the prelude.
3. prelude 返回 { settle, run, stalled }，worker 用它们驱动脚本。The prelude returns { settle, run, stalled }, which the worker uses to drive the script.

要点Key points

• VM 里没有计时器和 I/O：如果脚本没结束、又没有挂起的工具调用，它就永远不会结束——stalled() 在每次 drain 后检查这种情况并立即判失败。The VM has no timers or I/O: if the script has not finished and no tool call is pending, it never will — stalled() checks for this after every drain and fails it at once.
• 脚本包装成 (async (tools, console) => {<code>\n})，前缀和脚本同在第一行，所以报错的行号与脚本原文一致。The script is wrapped as (async (tools, console) => {<code>\n}), with the prefix on the script's first line so reported line numbers match the script as written.
• execute() 不会因为脚本失败而 reject，失败以 { ok: false } 返回，并保留失败前的 output 与 calls。execute() never rejects for script failures; they come back as { ok: false } with the output and calls up to the failure.
• loadQuickJSWasm() 每个路径只读取并编译一次；加载失败的 Promise 会被移出缓存，下次重试。loadQuickJSWasm() reads and compiles once per path; a failed load is evicted from the cache and retried next time.

工作原理How it works

1. execute(code, { signal, timeoutMs, store }) → new Execution(…)：计时器、abort 监听、等待 wasm。execute(code, { signal, timeoutMs, store }) → new Execution(…): timer, abort listener, wait for wasm.
2. start() → new Worker()；监听 message / error / exit。start() → new Worker(); listen for message / error / exit.
3. 收到 done 后先解码值与 store 写入，再 finish()：中止 pending 调用 → 置 interrupt → terminate → resolve。On done, decode the value and store writes first, then finish(): abort pending calls → set interrupt → terminate → resolve.

要点Key points

• 工具抛出的错误在脚本里变成同一条消息的 Error；返回值必须可 JSON 序列化。An error thrown by a tool becomes an Error with the same message in the script; return values must be JSON-serializable.
• result.calls 记录每次工具调用：先记为 cancelled，完成后改成 ok 或 error 并记下耗时——脚本结束时仍未完成的调用保持 cancelled。result.calls records every tool call: it starts as cancelled and becomes ok or error with its duration — calls still running when the script ends stay cancelled.
• tools 是一个代理：访问不存在的工具名会抛 TypeError，列出相近的名字（或在不超过 20 个工具时列出全部）。tools is a proxy: an unknown tool name throws a TypeError that lists near misses (or, with 20 tools or fewer, all of them).
• globals（如 searchTools）走同一条路径，只是 target: "global"，且不记入 calls。Globals (such as searchTools) take the same path with target: "global" and are not recorded in calls.

工作原理How it works

1. prelude：caller("call", name) 生成函数 → JSON.stringify 参数 → bridge() → 返回挂进 pending 的 Promise。Prelude: caller("call", name) builds the function → JSON.stringify the args → bridge() → return a Promise kept in pending.
2. 宿主：handleCall() → tool.execute(JSON.parse(args), { signal }) → post({ type: "result", id, ok, payload })。Host: handleCall() → tool.execute(JSON.parse(args), { signal }) → post({ type: "result", id, ok, payload }).
3. worker：settle(id, ok, payload) → drain()。Worker: settle(id, ok, payload) → drain().

要点Key points

• image() 接受 base64 的 data: URL、{ image_url } 对象或 MCP 的 ImageContent 块，并且只认 PNG、JPEG、GIF、WebP。image() accepts a base64 data: URL, an { image_url } object or an MCP ImageContent block, and only takes PNG, JPEG, GIF or WebP.
• store() / load() 作用于传入的 JSON 快照；成功的执行把写入作为 storeWrites 交还宿主，持久化由宿主决定。store() / load() work on the JSON snapshot passed in; successful runs hand writes back as storeWrites, and persisting them is up to the host.
• 冻结内建对象会破坏“在实例上覆盖原型属性”的普通写法，所以 name、message、toJSON 等常见属性被改成访问器，this.name = … 依然可用。Freezing built-ins would break ordinary code that overrides prototype properties on instances, so common ones such as name, message and toJSON become accessors and this.name = … still works.

工作原理How it works

1. 宿主注册 globals 时，名字必须是标识符或 ns.member，且不能与保留名冲突。When the host registers globals, names must be identifiers or ns.member, and may not clash with the reserved names.
2. ns.member 形式的 globals 被收进一个冻结的 ns 对象。Globals named ns.member are grouped into a frozen ns object.
3. spread: true 的 global 收到全部参数组成的数组，而不是第一个参数。A spread: true global receives all arguments as an array instead of the first one.

要点Key points

• @options 只认 max_output_tokens 与 timeout_ms 两个字段；该行被替换为空行，行号不变。@options accepts only max_output_tokens and timeout_ms; the line is replaced with a blank one so line numbers stay put.
• CODEMODE_SOURCE_GRAMMAR 是一份 Lark 语法，给支持语法约束采样的模型：脚本可以直接按原文生成，而不是转义成 JSON 字符串。CODEMODE_SOURCE_GRAMMAR is a Lark grammar for models with grammar-constrained sampling: the script is generated as raw text instead of an escaped JSON string.
• 工具的 signal 在脚本结束（包括没被 await 的调用）、超时、调用方中止或沙箱关闭时触发。A tool's signal fires when the script finishes (including unawaited calls), times out, the caller aborts, or the sandbox closes.

工作原理How it works

1. parseCodemodeSource(input) → { code, options }；坏的 options → CodemodeSourceError。parseCodemodeSource(input) → { code, options }; bad options → CodemodeSourceError.
2. 把 options.timeoutMs 传给 execute()，maxOutputTokens 由宿主自己执行截断。Pass options.timeoutMs to execute(); maxOutputTokens is enforced by the host's own truncation.
3. 检查 result.ok，再读 value / error、output 与 calls。Check result.ok, then read value / error, output and calls.

要点Key points

• 工具名中不合法的标识符字符变成 _（toCodemodeIdentifier），所以 my-tool 在脚本里是 tools.my_tool；原名 tools["my-tool"] 同样可用。Characters that are not valid in identifiers become _ (toCodemodeIdentifier), so my-tool is tools.my_tool in scripts; the original tools["my-tool"] works too.
• 渲染有上限：输入类型超过 16,000 个字符整个变成 unknown；本地 $ref 每个 schema 最多展开 32 次，递归引用变成 unknown。Rendering is bounded: an input type over 16,000 characters becomes unknown; local $refs expand at most 32 times per schema, and recursive references become unknown.
• 用到 CallToolResult<T> 时要把 MCP_TYPESCRIPT_PREAMBLE（MCP 结果类型的定义）一起放进描述。When CallToolResult<T> is used, MCP_TYPESCRIPT_PREAMBLE (the MCP result type definitions) must go into the description too.

工作原理How it works

1. renderToolSignature(tool)：输入类型 + renderToolOutputType(outputSchema)。renderToolSignature(tool): the input type + renderToolOutputType(outputSchema).
2. mcpStructuredContentSchema() 识别 MCP 结果 schema（content 数组、布尔 isError、对象 _meta）。mcpStructuredContentSchema() recognises MCP result schemas (a content array, boolean isError, object _meta).
3. renderToolSample() 输出“描述 + 单个工具的声明”，用于工具列表与 ALL_TOOLS 条目。renderToolSample() outputs “description + that tool's declaration”, used for tool listings and ALL_TOOLS entries.

要点Key points

• 脚本可调用 loadout 中所有可调用的工具（包括 deferred 与 codemode 曝光的工具——MCP 工具默认在此），只有 codemode 自己除外。它是 model-only，脚本不能再启动脚本。Scripts can call every callable tool in the loadout (deferred and codemode-exposure tools included — where MCP tools go by default), except codemode itself. It is model-only: scripts cannot start scripts.
• 嵌套结果交给脚本时：有 outputSchema 的工具给 structuredContent（带 isError 的 MCP 结果也一样），其他工具给文本，失败则 reject。Nested results reach the script as: structuredContent for tools with an outputSchema (MCP results with isError too), text for other tools, and a rejection on failure.
• store() 写入成为 codemode-store 自定义条目；下次执行前从根到当前叶子重放，所以每个分支只看到自己路径上的值。store() writes become codemode-store custom entries; before the next run they are replayed from root to the current leaf, so each branch sees only values from its own path.
• 沙箱在第一次调用时才加载（worker 与 wasm），启动时没有成本；超时只来自脚本的 timeout_ms，否则不限。The sandbox (worker and wasm) loads on the first call, so start-up pays nothing; the only timeout is the script's timeout_ms, otherwise none.

工作原理How it works

1. createCodemodeExtension() 注册不激活的 codemode 工具；--tools、defaultTools、setActiveTools() 或 MCP 扩展激活它。createCodemodeExtension() registers the inactive codemode tool; --tools, defaultTools, setActiveTools() or the MCP extension activate it.
2. 激活时 prepareCodemodeLoadout() 用可调用工具的声明替换描述（inlineBudget 控制内联多少；mode: "only" 列出全部可调用工具，并从请求中去掉激活的 direct 工具的声明）。On activation, prepareCodemodeLoadout() replaces the description with the callable tools' declarations (inlineBudget limits how much is inlined; mode: "only" lists every callable tool and leaves active direct tools' declarations out of requests).
3. executeCodemode()：解析源码 → new CodemodeSandbox({ tools, globals }) → execute(code, { signal, store }) → 截断输出、追加 store 条目。executeCodemode(): parse the source → new CodemodeSandbox({ tools, globals }) → execute(code, { signal, store }) → truncate output, append store entries.