Code mode script API

This page documents what a model receives inside a Code Mode exec call: the sandbox helpers, the cell lifetime, the per-call budget prefix and how deferred tools stay reachable from a script, while the user-facing switch and limits are in Code Mode.

Sandbox helpers

Inside a script, these helpers are available:

• text(value) adds text to the output. Objects are converted with JSON.stringify.
• image(value) and audio(value) add an image or an audio clip. Both accept a base64 data: URL.
• notify(value) sends a progress note to you and to the model. Progress notes reach the person at once, and the model receives them while the same person's turn is running. If no turn is running, they wait for the next turn, and they are dropped if the cell ends first.
• store(key, value) and load(key) keep JSON values for later scripts in the same conversation. Values belong to the conversation, and for a shared room to the person who wrote the message. Changed values survive an ordinary script failure.
• setTimeout(callback, delayMs) and clearTimeout(id) schedule and cancel callbacks.
• yield_control() returns the output so far while the script keeps running.
• ALL_TOOLS lists the tools the script can call, with their callable name and full TypeScript declaration.
• tools.tool_search({query, limit?}) ranks deferred tools through the shared SQL ranker: exact identifiers first, then lexical and configured semantic matches fused with reciprocal-rank weights 1:2. It returns {tools: [{name, description}]}. It exists only when the writer's view has deferred tools; limit defaults to 8. Its call is drawn in the transcript as a ToolSearch row, like a direct discovery call; only the row name differs, never the identifier or the exec declaration.
• exit() ends the script early and successfully. Nothing after it runs to any effect, including catch and finally blocks; values saved before it are kept.

Completed output stays available until it is collected.

Cell lifetime

Cells belong to the conversation that created them: another conversation cannot use their IDs, and only one observer can wait on a cell at a time.

In a shared chat room, a cell and its saved values also belong to the person who wrote the message, including members without a linked account, and another member cannot read them or wait on them.

Running cells stop when the person presses Stop, including cells started in earlier turns, and when the conversation is reset, switches model or the daemon restarts, and when its session is cleared, deleted or recreated. An ID from before then is reported as not found and never reaches a newer cell.

Per-call observation budget

A first line that starts with // @exec: changes the observation time and output budget for that one exec call. The JSON object after the prefix accepts yield_time_ms and max_output_tokens, and the script starts on the next line:

// @exec: {"yield_time_ms": 60000, "max_output_tokens": 2000}
text(await tools.ListDir({ path: "src" }));

The wait call takes its own yield_time_ms and max_tokens arguments and keeps its fixed 10 second default; the Default exec observation time setting does not change it.

Tool loading inside a script

The Tool loading settings apply to Code Mode as well. Only the core tools (Bash, Read, Edit, Grep and Write) are described in full. Deferred tool names and declarations are omitted from the initial prompt.

Deferred tools stay callable from a script. Use const result = await tools.tool_search({query: "calendar", limit: 1}); text(result); for ranked discovery, then inspect the returned declarations before calling tools[result.tools[0].name](args). Descriptions are identical to ALL_TOOLS, which can also be filtered directly. Search uses only the current writer's deferred tools, draws a nested transcript row and does not activate tools or change the spawn-fixed catalog. It adds one exec-description section only when deferred tools exist; without them the description is unchanged. Blank queries reject with query must not be empty; invalid limits reject with limit must be greater than zero. Code Mode does not use the separate top-level Tool Search tool.