feat(graph): codemode — a node whose action space is code, not tool calls

[drewstone]

Answers "can an agent easily do code mode on agent-runtime, or is it a profile + skill?" — with the short answer being no, and here is why, and here is the piece that was missing.

What code mode is

An agent node acts one JSON tool call per turn: N steps cost N model round trips, and every tool's schema occupies context. Code mode changes the action space — the model writes a program against a typed API of the tools it is allowed to use, and the runtime runs it. Loops, branches and fan-out happen inside one turn; intermediates live in program memory instead of the transcript.

examples/engine/codemode.ts runs one job both ways over the same operations table:

  code mode : 1 model turn ,  7 operation calls  → {"total":45}
  tool calls: 8 model turns,  7 operation calls  → {"total":45}

What agent-runtime already had

One instance, hard-wired. src/runtime/strategy-author.ts has an LLM read a contract, write an optimization strategy as a TS module, lints it against banned constructs, writes it to disk, imports it and runs it. It is safe for a reason worth naming: the authored body composes shot()/critique(), so everything it spends goes through the Supervisor's conserved pool. Code that calls tools outside the seams makes the budget and the journal lie — that is the actual hazard, not the code execution.

Why a profile + skill cannot get you there

A skill can describe an API. Three things must be runtime-owned, and codemodeKind() owns them:

1. The API is projected from the grant. renderCodeApi generates what the model is shown from the same operations table the runner binds. A documented-but-ungranted call cannot exist; a granted-but-undocumented one cannot hide. Prose drifts from the grant; generated text cannot.
2. The host owns the execution boundary. The kind declares a codeRunner effect and executes nothing itself — the engine refuses before spending when no runner was supplied (tested). A host picks in-process or jailed, and the graph is identical either way. inlineCodeRunner() is offered for development and labelled honestly: assertAuthoredCode is a lint, not a sandbox, and in-process code reaches whatever the process reaches.
3. Accounting passes through the kernel. The node is an ordinary Executor under Scope.spawn, so reservation, settlement, journal record, completion gate and replay are the kernel's. Each operation reports its spend and the node totals it. The test asserts this off the journal, not the return value: 100 input tokens from the one model call plus 1 from each of three metered operation calls arrive as 103 in the kernel's settled record.

Where it sits

codemode is a sibling of script in the same registry: script is developer-authored code as a node, codemode is model-authored code as a node. Both inherit the executor contract, the conserved pool, the journal, onCrash and the deliverable gate for free — which is the argument for it being a node kind rather than a new subsystem.

assertAuthoredCode(code, { allowedImports }) is strategy-author.ts's contract check, generalized and exported rather than duplicated: same banned constructs, with the allowed-import list a parameter instead of one hardcoded specifier.

Verification

pnpm tsx examples/engine/codemode.ts output above · tests/graph/codemode.test.ts 7/7 (grant projection, one-turn loop, journal-backed spend, pre-execution refusal of fetch with zero operation calls made, missing-runner refusal, config refusals, lint behaviour) · full affected suites 1119 passed, 1 failed (the 127.0.0.53 bind, macOS baseline) · typecheck 0 · lint clean · docs:api 0/0 · docs:freshness green · 0.169.0.

Not done, deliberately

No codemode executor for plain supervise() leaves, and no MCP-tools-to-operations projection. Both are real and both are speculative until something asks for them; the node kind is the smallest thing that proves the shape end to end.

[tangletools]

✅ Auto-approved drewstone PR — bfac142c

This PR was opened by the trusted drewstone account.

This approval is provisional and was applied by the local stand-in because the pr-reviewer webhook host is unreachable (2026-08-21). CI on this head is fully green. The full PR reviewer audit re-runs via the resweep when the service returns and will publish findings if it detects issues.