@relay-harness/coding-agent 0.0.0-stage → 1.0.2

package/docs/cli-integration.md

@@ -0,0 +1,106 @@
+# CLI Integration
+
+By default, running `relay` opens the interactive terminal interface. When input or output is piped or redirected, Relay uses print mode instead. You can also select print, JSON, or RPC mode explicitly for scripts and applications.
+
+All four modes use the same agent, sessions, resources, and tools. The mode determines how input enters Relay, how output is exposed, and whether the process remains available for more commands.
+
+The SDK is not a CLI mode. It embeds the agent directly in a Node.js or Bun process. See the [SDK](sdk.md) when direct TypeScript access is preferable to a process boundary.
+
+## Choose a mode
+
+| Mode | Interface | Lifetime | Use it when |
+|---|---|---|---|
+| Interactive | Terminal UI | Until the user exits | A person is working with Relay directly |
+| Print | Final text on stdout | One invocation | A script needs the final assistant response |
+| JSON | JSONL events on stdout | One invocation | A process needs structured progress from a run |
+| RPC | JSONL commands, responses, and events | Long-lived | A process needs bidirectional control |
+
+CLI options still select the working directory, model, tools, resources, and session persistence independently of the mode. See [Command Line](cli.md) for the complete startup options.
+
+## Print to stdout
+
+Print mode runs the supplied prompts, writes the final assistant text to stdout, and exits:
+
+```bash
+relay --print "Summarize the changes in this repository"
+```
+
+Use print mode when only the final text is needed, including command substitution, pipelines, and one-shot jobs. Intermediate events are not exposed.
+
+Print mode writes errors to stderr. A final assistant response with an `error` or `aborted` stop reason produces a nonzero exit status.
+
+When no mode is selected explicitly, non-TTY stdin or stdout also selects print mode. This allows piped input and output without adding `--print`.
+
+## Stream JSON events
+
+JSON mode writes a session header followed by agent and session events as newline-delimited JSON:
+
+```bash
+relay --mode json "Review this repository" > events.jsonl
+```
+
+This is structured event output, not a single JSON result or a constraint on the format of the model’s response.
+
+All prompts are supplied when the process starts. The process streams events for that run and then exits; it does not accept later commands.
+
+A failed or aborted assistant response appears in the event stream but does not by itself produce a nonzero exit status. Inspect the events when success or failure matters. Relay still exits nonzero if the invocation throws an error.
+
+Streaming `message_update` records contain deltas rather than a growing message snapshot. Assemble live output from the delta events, then replace it with the authoritative message from `message_end`.
+
+`agent_end` can be followed by automatic recovery or queued work. `agent_settled` marks the end of automatic work for the current run.
+
+Stdout is reserved for JSONL. Diagnostics and application logging are written to stderr. See [JSON Event Stream](json.md) for framing, event shapes, and reconstruction rules.
+
+## Control Relay with RPC
+
+RPC mode keeps Relay running while another process sends commands and receives responses and events:
+
+```bash
+relay --mode rpc --no-session
+```
+
+Commands are JSON objects written to stdin. Responses and events are JSON objects written to stdout. Every record occupies one line.
+
+Add an `id` to commands that need correlation. The matching response repeats that ID. Events generally have no command ID because they describe session activity rather than one request.
+
+A successful `prompt` response means the prompt was accepted, queued, or handled. It does not mean the run completed. Continue consuming events through `agent_settled` when completion matters.
+
+RPC commands can change models, inspect state, manage sessions, run shell commands, and answer extension UI requests.
+
+Extension dialogs form a request-response subprotocol. Other extension UI updates are notifications that a client may display or ignore. TUI-only extension capabilities are unavailable or degraded outside interactive mode.
+
+For Node.js or TypeScript integrations, prefer `RpcClient` from `@relay-harness/coding-agent`. It starts a Relay RPC child process, correlates requests, exposes typed command methods, and delivers session events to listeners.
+
+The [RPC client example](../examples/rpc-client.ts) sends one prompt, streams text and tool activity, waits for `agent_settled`, and shuts down the child process. It is included in the repository’s TypeScript checks.
+
+`RpcClient.promptAndWait()` installs its event listener before sending the prompt, avoiding a race with fast completions. For separate operations, subscribe before calling `prompt()` and call `waitForIdle()` only while a run is active.
+
+The client requires a path to a runnable Relay CLI. The repository example points at `dist/cli.js`, so the package must be built before that example runs from a checkout.
+
+If you are building a client without `RpcClient`, start with [RPC Protocol](rpc.md), then use [RPC Commands](rpc-commands.md) and [JSON Event Stream](json.md) as the wire references.
+
+## Fork and rebrand Relay
+
+A source fork can change the CLI name and configuration directory through `package.json`:
+
+```json
+{
+  "relayConfig": {
+    "name": "my-agent",
+    "configDir": ".my-agent"
+  }
+}
+```
+
+Change the top-level `bin` field to set the executable name. These settings affect the CLI banner, configuration paths, and derived environment variable names.
+
+## Examples and references
+
+- [RPC client](../examples/rpc-client.ts): typed Node.js integration
+- [RPC extension UI](../examples/rpc-extension-ui.ts): custom terminal client with extension dialogs
+- [Command Line](cli.md): startup options and mode selection
+- [JSON Event Stream](json.md): JSON event reference
+- [RPC Protocol](rpc.md): RPC lifecycle, framing, errors, and shutdown
+- [RPC Commands](rpc-commands.md): command and response reference
+- [RPC Extension UI](rpc-extension-ui.md): extension interaction subprotocol
+- [SDK examples](../examples/sdk/): in-process TypeScript integrations

package/docs/cli.md

@@ -0,0 +1,316 @@
+<a id="cli-and-modes-reference"></a>
+
+# Command Line
+
+This page documents Relay's built-in command-line commands and options. Run `relay --help` or append `--help` to a command for the exact interface in your installed version. The top-level help also includes options registered by loaded extensions.
+
+```sh
+relay [options] [--] [@files...] [messages...]
+relay install <source> [options]
+relay remove <source> [options]
+relay uninstall <source> [options]
+relay update [target] [options]
+relay list
+relay config [options]
+relay auth <check|print-api-key|print-bearer-token> [options]
+relay mcp <list|login|logout> [options]
+```
+
+<a id="modes"></a>
+
+## Invocation and output
+
+```sh
+relay
+relay --print "Summarize this repository"
+git diff | relay --print "Review this change"
+relay --mode json "Inspect this repository" > events.jsonl
+```
+
+With terminal stdin and stdout, Relay opens the terminal UI unless `--print`, `--mode json`, or `--mode rpc` selects another interface. When either stream is redirected and neither JSON nor RPC mode is selected, Relay uses print mode. See [CLI Integration](cli-integration.md) for choosing between interactive, print, JSON, RPC, and SDK integration.
+
+| Input | Behavior |
+|---|---|
+| `message` | Provide an initial prompt |
+| `@path` | Include a text file or image in the first prompt |
+| Piped stdin | Prepend its contents to the first prompt |
+| `--` | Stop option parsing so a prompt can begin with `-` |
+
+Relay resolves `@path` from the current working directory. The working directory also controls project configuration, resource discovery, and session grouping.
+
+`--print` controls whether Relay runs once and exits. `--mode` selects the output interface. `--mode text` does not force one-shot execution when stdin and stdout are terminals; use `--print` for that behavior.
+
+| Option | Behavior |
+|---|---|
+| `-p`, `--print` | Run the supplied prompts, write the final assistant text to stdout, then exit |
+| `--mode text` | Select text output; still open the terminal UI when stdin and stdout are terminals |
+| `--mode json` | Run the supplied prompts, write JSONL events to stdout, then exit |
+| `--mode rpc` | Read JSONL commands from stdin and write responses and events to stdout until shutdown |
+| `--export <input> [output]` | Export a session file to HTML and exit; derive the destination when `output` is omitted |
+
+RPC mode rejects `@file` arguments. JSON and RPC modes reserve stdout for protocol records. See [JSON Event Stream](json.md) and [RPC Protocol](rpc.md).
+
+<a id="model-options"></a>
+
+## Models
+
+```sh
+relay --model sonnet:high
+```
+
+See [Choose a Model](models.md) for model selection and [Providers](providers.md) for credentials.
+
+- `--provider <name>`<br>
+  Restricts `--model` lookup to one provider. It requires `--model`.
+- `--model <pattern>`<br>
+  Selects by exact ID or fuzzy ID/name match. It accepts `provider/id` and an optional `:<thinking>` suffix.
+- `--api-key <key>`<br>
+  Uses a non-persistent API-key override. It requires a model selected through `--model` or `--models`.
+- `--thinking <level>`<br>
+  Sets `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`. It overrides a `--model` suffix and is clamped to the model's capabilities.
+- `--models <patterns>`<br>
+  Sets a comma-separated scope for startup and cycling. It accepts exact IDs, fuzzy matches, case-insensitive globs, and optional `:<thinking>` suffixes.
+- `--list-models [search]`<br>
+  Lists available models, optionally filtered by a fuzzy search, then exits.
+
+<a id="session-options"></a>
+
+## Sessions
+
+```sh
+relay --continue
+```
+
+See [Sessions and Context](sessions.md) for resuming, forking, naming, and storing sessions.
+
+- `-c`, `--continue`<br>
+  Continues the most recent session for the current project.
+- `-r`, `--resume`<br>
+  Opens the session selector.
+- `--session <path|id>`<br>
+  Opens by file path, exact ID, or partial ID. Relay searches the current project first and offers to fork a cross-project match.
+- `--session-id <id>`<br>
+  Opens the exact project session ID or creates it if absent. IDs accept letters, numbers, `.`, `_`, and `-`.
+- `--fork <path|id>`<br>
+  Forks an existing session into a new session for the current project.
+- `--session-dir <dir>`<br>
+  Overrides storage and lookup. It takes precedence over `RELAY_CODING_AGENT_SESSION_DIR` and the `sessionDir` setting.
+- `--no-session`<br>
+  Uses an in-memory session that is not persisted.
+- `-n`, `--name <name>`<br>
+  Sets the session display name.
+
+Constraints:
+
+- Session IDs must start and end with a letter or number.
+- `--fork` cannot be combined with `--session`, `--continue`, `--resume`, or `--no-session`.
+- `--session-id` cannot be combined with `--session`, `--continue`, or `--resume`. Combine it with `--fork` to choose the new ID.
+
+<a id="tool-options"></a>
+
+## Tools
+
+```sh
+relay --tools read,grep,find,ls --print "Review this project"
+```
+
+See [Settings](settings.md#tools) for configuring the default tool selection.
+
+- `-t`, `--tools <list>`<br>
+  Replaces the default selection with a comma-separated allowlist of built-in, extension, or custom tools.
+- `-xt`, `--exclude-tools <list>`<br>
+  Disables comma-separated tool names after all other selection options.
+- `-nbt`, `--no-builtin-tools`<br>
+  Disables default built-in tools while retaining extension and custom tools.
+- `-nt`, `--no-tools`<br>
+  Starts with all built-in, extension, and custom tools disabled.
+
+Default enabled tools are `read`, `bash`, `edit`, and `write`, unless `defaultTools` changes them. `--tools` replaces the whole selection, so name every tool you want; `defaultTools` also accepts `+name` and `-name` to change the defaults instead.
+
+| Built-in | Purpose |
+|---|---|
+| `read` | Read text files and supported images |
+| `bash` | Run shell commands |
+| `powershell` | Run PowerShell commands on Windows |
+| `edit` | Apply exact text replacements to an existing file |
+| `write` | Create or overwrite a file |
+| `grep` | Search file contents |
+| `find` | Find paths using glob patterns |
+| `ls` | List directory contents |
+
+Built-in extensions add two more tools. They are off by default; the MCP extension turns them on when an MCP server needs them (see [MCP](mcp.md#exposure)). To enable them yourself, name them in `--tools` or `defaultTools`.
+
+| Built-in extension | Purpose |
+|---|---|
+| `codemode` | Run JavaScript that calls the other tools, for example in parallel with `Promise.allSettled`; only the script's output reaches the model |
+| `tool_search` | Search tools that are not declared to the model (`codemode` and `deferred` exposure, such as MCP tools) and declare the matches for the next call |
+
+### Enable codemode
+
+To turn on `codemode` for every session, add it to the default tools in `~/.relay/agent/settings.json` or a project's `.relay/settings.json`:
+
+```json
+{
+  "defaultTools": ["+codemode"]
+}
+```
+
+This keeps `read`, `bash`, `edit`, and `write` and adds `codemode`. For one invocation, list every tool, since `--tools` replaces the selection:
+
+```sh
+relay --tools read,bash,edit,write,codemode
+```
+
+Codemode is useful without MCP: scripts can run several tool calls in parallel, filter large output before it reaches the model, call classifier models such as TypeSafe's Jev through `models.classify()` (see [Classifier models](models.md#use-classifier-models)), and generate images through `models.generateImages()` (see [Image models](models.md#use-image-models)).
+
+### How codemode works
+
+Scripts run in a QuickJS sandbox and reach the other tools through `tools.<name>(args)`. [Codemode](codemode.md) describes the script API, how tools are listed and found, the `store()` and `models` globals, and the limits.
+
+### Tool search
+
+`tool_search` is off by default; enable it with `"defaultTools": ["+tool_search"]` or `--tools`. It uses the same ranking as `searchTools()` over tools that are not declared yet and declares the matches for the next model call. Loaded tools are recorded in the session like other tool changes, so they stay declared on that branch.
+
+<a id="resource-options"></a>
+
+## Resources
+
+```sh
+relay --extension ./review.ts
+```
+
+See [Configuration](configuration.md) for conventional directories and project trust, [Settings](settings.md#resources) for configured paths, and [Relay Packages](packages.md) for package sources.
+
+- `-e`, `--extension <path>`<br>
+  Loads an extension file or directory, or a built-in extension such as `builtin:mcp`, and is repeatable.
+- `-ne`, `--no-extensions`<br>
+  Disables discovered, configured, and built-in extensions. Explicit `-e` paths still load, so `relay -ne -e builtin:mcp` keeps only the built-in MCP support.
+- `--skill <path>`<br>
+  Loads a skill file or directory and is repeatable.
+- `-ns`, `--no-skills`<br>
+  Disables discovered and configured skills. Explicit `--skill` paths still load.
+- `--prompt-template <path>`<br>
+  Loads a prompt-template file or directory and is repeatable.
+- `-np`, `--no-prompt-templates`<br>
+  Disables discovered and configured templates. Explicit `--prompt-template` paths still load.
+- `--theme <path>`<br>
+  Loads a theme file or directory and is repeatable.
+- `--use-theme <name[/name]>`<br>
+  Selects the initial interactive theme for this run.
+- `--no-themes`<br>
+  Disables discovered and configured themes. Explicit `--theme` paths still load.
+- `-nc`, `--no-context-files`<br>
+  Disables `AGENTS.md` and `CLAUDE.md` discovery.
+
+Resource paths apply only to the current process. Relative paths resolve from the current working directory.
+
+<a id="prompt-and-display-options"></a>
+
+## Prompts and process
+
+```sh
+relay --append-system-prompt ./instructions.md
+```
+
+See [Configuration](configuration.md) for saved configuration, [Security](security.md#understand-project-trust) for project trust, and [Environment Variables](environment-variables.md) for process controls.
+
+- `--system-prompt <text|path>`<br>
+  Replaces the default system prompt with text or the contents of an existing file.
+- `--append-system-prompt <text|path>`<br>
+  Appends text or an existing file to the system prompt and is repeatable.
+- `--tui-mode <mode>`<br>
+  Uses `fullscreen` (default) or `regular` terminal mode.
+- `--verbose`<br>
+  Shows verbose interactive startup information, overriding `quietStartup`.
+- `-a`, `--approve`<br>
+  Trusts project-local configuration and resources for this process.
+- `-na`, `--no-approve`<br>
+  Ignores trust-gated project-local configuration and resources for this process.
+- `--offline`<br>
+  Disables automatic network activity, including model catalog refreshes. Equivalent to `RELAY_OFFLINE=1`.
+- `-h`, `--help`<br>
+  Shows help, including flags registered by loaded extensions, then exits.
+- `-v`, `--version`<br>
+  Shows the Relay version, then exits.
+
+Extensions may register additional long-form options. Unknown short options are rejected.
+
+## Package commands
+
+```sh
+relay install npm:@scope/package
+```
+
+See [Relay Packages](packages.md) for source formats, filtering, installation, and project scope.
+
+### Common tasks
+
+| Task | Command |
+|---|---|
+| Install a package | `relay install <source>` |
+| List configured packages | `relay list` |
+| Remove a package and its settings entry | `relay remove <source>` |
+| Configure which package resources load | `relay config` |
+
+Add `--local` or `-l` to `install`, `remove`, `uninstall`, or `config` to use project settings instead of global settings.
+
+### Update packages
+
+Running `relay update` without a target updates all installed packages.
+
+| Task | Command |
+|---|---|
+| Update all installed packages | `relay update` |
+| Update one installed package | `relay update <source>` |
+| Refresh model catalogs | `relay update --models` |
+
+`relay update` never updates Relay itself. Relay is installed from source: pull the checkout, then run `npm install --ignore-scripts` and `npm run build`. With Nix, use `nix profile upgrade relay`.
+
+### Aliases and command options
+
+- `relay uninstall <source>` is an alias for `relay remove <source>`.
+- `relay update --extension <source>` is an alias for `relay update <source>`.
+- `-a`, `--approve` trusts project-local files for one command. `-na`, `--no-approve` ignores trust-gated project-local files.
+- Append `-h` or `--help` to a command for its exact usage and option constraints.
+
+## Credential commands
+
+```sh
+relay auth check --provider openai --json
+```
+
+Authentication commands require `--provider <provider>` or `--model <model>`. See [Providers](providers.md) for supported methods.
+
+| Command | Description |
+|---|---|
+| `relay auth check` | Print `ready`, `not_ready`, or `invalid`; exit with status `0`, `1`, or `2`, respectively |
+| `relay auth print-api-key` | Print the resolved API key |
+| `relay auth print-bearer-token` | Print a resolved OAuth bearer token |
+
+| Option | Applies to | Description |
+|---|---|---|
+| `--provider <provider>` | All | Resolve credentials for a provider |
+| `--model <model>` | All | Resolve credentials from a model; may be combined with `--provider` |
+| `--json` | `auth check` | Write the structured result as JSON |
+| `--credentials` | `auth check` | Emit the resolved credential when ready |
+| `--no-refresh` | `auth check` | Do not refresh expired OAuth credentials; refresh is the default |
+| `--min-expiry <duration>` | `print-bearer-token` | Require remaining token lifetime using `ms`, `s`, `m`, or `h`, such as `30m` |
+
+Credential-printing commands write secrets to stdout.
+
+## MCP commands
+
+These commands work outside a session, so agents can run them through `bash`. See [MCP Servers](mcp.md).
+
+| Command | Description |
+|---|---|
+| `relay mcp add <server> [options] -- <command> [args...]` | Add or replace a stdio server in `mcp.json`; `--env KEY=VALUE` (repeatable) and `--cwd <dir>` set its environment and working directory. Arguments after the command are passed to it |
+| `relay mcp add <server> [options] --url <url>` | Add or replace a streamable HTTP server; `--header KEY=VALUE` (repeatable), `--bearer-token-env-var <NAME>` (sends `Authorization: Bearer ${NAME}`), `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, and `--oauth-client-name` configure authentication |
+| `relay mcp remove <server>` | Remove a server from `mcp.json`; stored OAuth credentials are kept |
+| `relay mcp list [--json]` | Connect to every enabled server and print its state, tools, and errors; exit with `1` when a config entry is invalid or an enabled server is not connected |
+| `relay mcp login <server> [--timeout <seconds>]` | Sign in to an OAuth server: open the authorization page and wait for the browser (default 300 seconds); a terminal also accepts the pasted redirect URL |
+| `relay mcp logout <server>` | Delete the stored OAuth credentials of a server |
+
+`add` and `remove` change `~/.relay/agent/mcp.json`, or `.relay/mcp.json` in the current directory with `--local` (`-l`). `add` also takes `--exposure <mode>` (see [Exposure](mcp.md#exposure)) and `--description <text>` and does not connect; run `relay mcp list` to check the server.
+
+Project `.relay/mcp.json` files are only read for projects that are already trusted.

package/docs/codemode.md

@@ -0,0 +1,207 @@
+# Codemode
+
+The `codemode` tool lets the model write a JavaScript script that calls relay's other tools and runs non-LLM models, such as classifiers and image models. Only the script's output reaches the model, so a script can run calls in parallel and filter large results before the model sees them. To turn it on, see [Enable codemode](cli.md#enable-codemode).
+
+## Scripts
+
+The tool input is raw JavaScript source, not JSON and not a markdown code fence. It runs as the body of an async function in a QuickJS sandbox, so top-level `await` and `return` work. The sandbox has no Node APIs, file system, network, or timers; scripts reach the outside world only through tools and `models`.
+
+A script may start with an options line:
+
+```js
+// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
+```
+
+- `max_output_tokens` (default 10000) limits the output. Longer output keeps its start and end, and the full text is written to a temp file whose path is included in the result. A script fails when its output passes 16777216 characters of text and base64 image data or 100000 `text()`, `image()`, and `console` calls; write large data to a file with a tool instead.
+- `timeout_ms` is a hard deadline for the whole script. It is unset by default. Image generation can take minutes, so do not set a short deadline for scripts that generate images.
+
+The result starts with `Script completed` or `Script failed`, the wall time, and the output. A failed script keeps its partial output, followed by `Script error:` and the error. Tool calls are real: calls made before a failure are not undone. Calls still running when the script ends are cancelled, and unawaited promises are discarded.
+
+## Globals
+
+| Global | Purpose |
+|---|---|
+| `tools.<name>(args)` | Call a tool. See [Call tools](#call-tools). |
+| `text(value)` | Add a text item to the output. Strings are added as is, other values as JSON. |
+| `image(value)` | Add an image to the output: a base64 `data:` URL, an `{ image_url }` object, or an image block `{ type: "image", data, mimeType }` such as those returned by MCP tools and `models.generateImages()`. Remote URLs are not supported. PNG, JPEG, GIF, and WebP are accepted. Each image is also saved to a temp file, and the result names the path before the image. |
+| `console.log(...)` | Like `text()`; `info`, `warn`, `error`, and `debug` do the same. |
+| `return value` | A top-level `return` adds the value like `text()`. |
+| `exit()` | End the script successfully. |
+| `store(key, value)` / `load(key)` | Keep small JSON values across `codemode` calls. See [Store values](#store-values). |
+| `ALL_TOOLS` | Every callable tool as `{ name, description }`, including tools the description does not list. |
+| `searchTools(query, { limit?, namespace? })` | Rank callable tools by relevance (BM25, default limit 8). Resolves to `{ name, description }[]`. |
+| `describeTool(name)` | Resolves to a tool's description and TypeScript declaration, or `undefined`. |
+| `describeNamespace(name)` | Resolves to `{ name, description?, instructions?, tools }` for a namespace such as an MCP server, or `undefined`. |
+| `models` | List and run non-LLM models. See [Models](#models). |
+
+## Call tools
+
+Every tool the session can call is a method of `tools`, named by its identifier: characters that are not valid in a JavaScript identifier become `_`, so the MCP tool `mcp__dev-tools__search` is `tools.mcp__dev_tools__search`. Each method takes one object with the tool's arguments.
+
+What a call resolves to depends on the tool:
+
+- Tools with an output schema resolve to a structured value. `bash` resolves to `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exit codes. Its `output` is not limited to the 2000 lines or 50KB the model sees: it holds up to 1 MiB, and longer output keeps its first and last 512 KiB around an omission marker, with `truncated` set and the full output in `full_output_path`.
+- MCP tools resolve to their `CallToolResult`, including `isError` and `structuredContent`.
+- Other tools, such as `read`, `edit`, and `write`, resolve to their text output.
+
+A call that fails, is blocked, or gets invalid arguments rejects with an `Error` that carries the tool's error text. Use `Promise.allSettled()` to keep the results of the calls that succeed.
+
+The `codemode` description lists tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Tools with `deferred` exposure, which includes MCP tools with the default `codemode` exposure, are not listed, so the description stays the same while MCP servers connect. Listed declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools)). Scripts find the other tools with `searchTools()`, `describeTool()`, `describeNamespace()`, or by filtering `ALL_TOOLS`.
+
+While `codemode` is active, `codemode.mode` in [settings](settings.md#tools) decides how the other tools are presented. With `on` (default) declared tools stay declared, and their descriptions say how to call them from scripts. With `only` they are hidden from the model and listed in the `codemode` description instead, so the model calls them through scripts.
+
+## Store values
+
+`store(key, value)` keeps a JSON value under a string key for later `codemode` calls; storing `undefined` deletes the key. `load(key)` returns the value, or `undefined`. Writes are kept only when the script succeeds: each successful script that stores values appends a `codemode-store` custom entry to the session, so resumed sessions keep the values and each branch sees only the values written on its path.
+
+The store is for small state such as IDs, cursors, or summaries. One value may have at most 262144 characters of JSON and all values together at most 1048576. Do not store image data; show images with `image()`, which also saves them to a temp file.
+
+## Models
+
+`models` reaches the model catalog and runs non-LLM models with the session's credentials: classifiers, which answer typed questions about JSON state, and image models, which generate images. Chat models are listed but cannot be run from scripts. Which classifier and image models exist is described in [Use classifier models](models.md#use-classifier-models) and [Use image models](models.md#use-image-models).
+
+```ts
+type ModelType = "chat" | "image" | "classifier";
+
+/** A catalog entry. `provider` and `id` identify it; other fields depend on the type. */
+interface ModelInfo {
+  type?: ModelType;
+  provider: string;
+  id: string;
+  name: string;
+  api: string;
+  input: ("text" | "image")[];
+  contextWindow?: number;
+  [key: string]: unknown;
+}
+
+declare const models: {
+  /** Every known model of a type, optionally for one provider. */
+  getModelsOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** Models of a type whose provider has working credentials. */
+  getAvailableOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** One catalog entry, or undefined. */
+  getModelOfType(type: ModelType, provider: string, id: string): Promise<ModelInfo | undefined>;
+  /** Answer `context.questions` about `context.state`; answers are in `result.answers` by question ID. */
+  classify(model: ModelInfo, context: ClassifierContext): Promise<ClassifierResult>;
+  /** Generate images from `context.input` text and image blocks; show `result.output` blocks with image(). Can take minutes. */
+  generateImages(model: ModelInfo, context: ImagesContext): Promise<ImagesResult>;
+};
+```
+
+`classify()` and `generateImages()` use only the `provider` and `id` of `model`, so `{ provider, id }` works as well. They do not throw on provider errors: check `stopReason` and `errorMessage`. At most four such calls run at once per script; more calls wait for a free slot, so `Promise.all()` over many items is fine. Their usage is added to the `codemode` tool result and counts toward the session cost.
+
+Model IDs differ between providers, for example `typesafe/jev-latest` and `openrouter/typesafe/jev-1.13`. Use `models.getAvailableOfType(type)` to find the IDs that work with the current credentials.
+
+### Classify
+
+```ts
+interface ClassifierContext {
+  /** The data to classify. */
+  state: Record<string, unknown>;
+  /** Questions by ID. One call answers all of them. */
+  questions: Record<string, ClassifierQuestion>;
+}
+
+type ClassifierQuestion =
+  /** Pick one label. `criteria` maps each label to what it means. */
+  | { type: "choice"; instructions: string; criteria: Record<string, string> }
+  /** Score on an ordered scale. `criteria` describes each level, lowest first. */
+  | { type: "score"; instructions: string; criteria: string[] }
+  /** Yes or no. */
+  | { type: "bool"; instructions: string; criteria: { true: string; false: string } };
+
+interface ClassifierResult {
+  provider: string;
+  model: string;
+  /** Answers by question ID. */
+  answers: Record<string, ClassifierAnswer>;
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type ClassifierAnswer =
+  | { type: "choice"; choice: string; probabilities: Record<string, number>; confidence: number }
+  /** `score` is the expected level index, from 0 to `criteria.length - 1`. */
+  | { type: "score"; score: number; confidence: number }
+  /** Probability of `true`. */
+  | { type: "bool"; probability: number };
+
+/** Token counts and cost in USD, when the service reports them. */
+type ModelUsage = { input: number; output: number; totalTokens: number; cost: { total: number } };
+```
+
+Classify several items by calling `classify()` once per item. This script sorts feedback messages, for example ones a tool returned earlier in the script:
+
+```js
+const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
+const results = await Promise.all(
+  messages.map((message) =>
+    models.classify(jev, {
+      state: { message },
+      questions: {
+        sentiment: {
+          type: "choice",
+          instructions: "How does the user feel about the product?",
+          criteria: { positive: "Satisfied or happy", negative: "Unhappy or frustrated", neutral: "Neither" },
+        },
+        urgency: {
+          type: "score",
+          instructions: "How urgently does this need a reply?",
+          criteria: ["no reply needed", "reply this week", "reply today"],
+        },
+      },
+    }),
+  ),
+);
+return results.map((result, i) =>
+  result.stopReason === "stop"
+    ? { message: messages[i], sentiment: result.answers.sentiment.choice, urgency: result.answers.urgency.score }
+    : { message: messages[i], error: result.errorMessage },
+);
+```
+
+### Generate images
+
+```ts
+interface ImagesContext {
+  /** The prompt as text blocks, plus image blocks to edit or use as references. */
+  input: (TextBlock | ImageBlock)[];
+}
+
+interface ImagesResult {
+  provider: string;
+  model: string;
+  /** Generated images, and text blocks for models that also return text. */
+  output: (TextBlock | ImageBlock)[];
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type TextBlock = { type: "text"; text: string };
+/** `data` is base64. */
+type ImageBlock = { type: "image"; data: string; mimeType: string };
+```
+
+Show generated images with `image(block)`. Do not print `data` with `text()`, `console`, or `return`: it is large and the model cannot read it as text. `image()` also saves each image to a temp file and puts its path in the result, so a later turn can copy or move the file.
+
+```js
+// @options: {"timeout_ms": 300000}
+const painter = await models.getModelOfType("image", "openrouter", "google/gemini-2.5-flash-image");
+const result = await models.generateImages(painter, {
+  input: [{ type: "text", text: "A red fox in the snow, watercolor" }],
+});
+if (result.stopReason !== "stop") return result.errorMessage;
+for (const block of result.output) {
+  if (block.type === "image") image(block);
+  else text(block.text);
+}
+```
+
+## Limits
+
+- A script's VM has 256 MB of memory. Running out throws `InternalError: out of memory`; filter or aggregate large data instead of accumulating it.
+- A script that waits on a promise that can never settle (no tool call pending) fails immediately, since there are no timers.
+- Scripts cannot start other `codemode` scripts.