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

CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.169.0
+
+### `codemode`: a node whose action space is code, not tool calls
+
+An `agent` node acts one JSON tool call per turn, so N steps cost N model round trips and every tool's schema sits in context. A `codemode` node asks the model once for a program written against the operations that node grants, then runs it: loops and branches happen inside the program and only the answer returns. `examples/engine/codemode.ts` runs one job both ways over the same operations table — **1 model turn against 8**, same 7 operation calls, same answer.
+
+The runtime already did this once, hard-wired: `strategy-author.ts` has an LLM write an optimization strategy against a fixed contract, lints it, imports it, and runs it — safe because the authored body composes `shot()`/`critique()` and therefore spends through the Supervisor's pool. `codemodeKind()` generalizes that, and the three properties it keeps are exactly the ones a prompt-and-skill version cannot have:
+
+- **The API is projected from the grant.** `renderCodeApi` generates what the model is shown from the same `operations` table the runner binds, so a documented-but-ungranted call cannot exist and a granted-but-undocumented one cannot hide.
+- **The host owns the execution boundary.** The kind declares a `codeRunner` effect and executes nothing itself; the engine refuses before spending when the host supplied none. `inlineCodeRunner()` is offered for development and documented as what it is — `assertAuthoredCode` is a LINT, not a sandbox, and in-process code reaches whatever the process reaches.
+- **Accounting passes through the kernel.** The node is an ordinary `Executor` under `Scope.spawn`; each operation reports its spend and the node totals it into the settlement. A 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.
+
+`assertAuthoredCode(code, { allowedImports })` is the strategy-author contract check, generalized and exported: same banned constructs (`require`, dynamic `import`, `eval`, `new Function`, `process`, `globalThis`, `fetch`, node builtins), with the allowed-import list now a parameter instead of one hardcoded specifier.
+
 ## 0.168.0
 
 ### The first example authored against the ENGINE, and the wart it found

api-surface.json

@@ -757,6 +757,11 @@
       "AnyNodeKind": "type 55f4a92edcad",
       "BudgetMode": "type 5b16bf1d103a",
       "CONDITION_OPS": "value 373728f5643d",
+      "CodeAuthor": "type f2c77ef685ed",
+      "CodeModeConfig": "type f381531c19d8",
+      "CodeOperation": "type 88e128a77b2c",
+      "CodeOperationResult": "type 3c234c1e334c",
+      "CodeRunner": "type 7f317b0dcb2c",
       "CompiledEdge": "type c827cc9cfb25",
       "CompiledGraph": "type 0e82bdc88bed",
       "CompiledNode": "type f9930b816a7f",
@@ -815,6 +820,8 @@
       "applyGraphFoldEvent": "value 70e27348ccf1",
       "applyProjection": "value b94c8e122df4",
       "assembleGraphResult": "value d678cca36560",
+      "assertAuthoredCode": "value e378262245dd",
+      "codemodeKind": "value fa5f8401493b",
       "compileGraph": "value a6503da455bc",
       "createEdgeLedger": "value d963f2a8b1ed",
       "createGraphEngine": "value 2a8488b90184",
@@ -823,9 +830,11 @@
       "decideJoin": "value 5253c2cc8e3d",
       "emptyFoldState": "value ebbfa661aaf6",
       "evaluateCondition": "value 0515a05e4feb",
+      "extractCodeBlock": "value 2be00a4bf33b",
       "foldGraphJournal": "value 911d89f93bf6",
       "formatRegistryHandle": "value ce839c080bdc",
       "graphFromRunGraph": "value 51b7777a2802",
+      "inlineCodeRunner": "value ed1ceb9b55bf",
       "isEngineFired": "value 7d67a953ae50",
       "isSuspensionRequest": "value 0db839d7dce4",
       "kindHandle": "value 8735aafbd0b1",
@@ -834,6 +843,7 @@
       "narrowEffects": "value 572325974365",
       "openGraphRun": "value b5200af46abc",
       "parseRegistryHandle": "value b438d6db0ace",
+      "renderCodeApi": "value 1fed5a98cc33",
       "runEngineGraph": "value cae4cbd93ff0",
       "schemaAccepts": "value 9583fc0fec82",
       "scriptKind": "value ad87af04535a",

docs/api/primitive-catalog.md

@@ -7,7 +7,7 @@
 
 # Primitive catalog — the never-stale anti-reinvention inventory
 
-> **GENERATED** from `@tangle-network/agent-runtime@0.168.0` and `@tangle-network/agent-eval@0.170.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
+> **GENERATED** from `@tangle-network/agent-runtime@0.169.0` and `@tangle-network/agent-eval@0.170.0` by `scripts/gen-primitive-catalog.mjs`. Do NOT hand-edit — run `pnpm run docs:api`. This is the mechanical companion to the JUDGMENT in `canonical-api.md` (§2 decision table + §1.5 AgentProfile law): that doc says WHICH primitive to reach for and what NOT to build; this catalog proves WHAT exists. Per-symbol signatures + `file:line` live in the per-module pages under `docs/api/`.
 
 ## 1. agent-runtime — own public surface
 
@@ -1246,7 +1246,7 @@ Import from `@tangle-network/agent-runtime/kernel` — 836 exports.
 
 ### Graph engine — node kinds, registries, host effects; the four core kinds
 
-Import from `@tangle-network/agent-runtime/graph` — 92 exports.
+Import from `@tangle-network/agent-runtime/graph` — 102 exports.
 
 | Symbol | Kind | Summary |
 |---|---|---|
@@ -1255,6 +1255,8 @@ Import from `@tangle-network/agent-runtime/graph` — 92 exports.
 | `applyGraphFoldEvent` | function | Apply ONE journal event. The live scheduler calls this right after each append; the restart path |
 | `applyProjection` | function | Apply a validated projection to an admitted payload. Collection operators over a non-array |
 | `assembleGraphResult` | function | Turn a finished run into its result: rehydrate, reduce the terminals, classify a no-winner. |
+| `assertAuthoredCode` | function | Refuse the obvious escapes in authored source. A LINT, not a sandbox: it reads text and cannot |
+| `codemodeKind` | function | A node that asks a model for a program and runs it. Declares the two effects it cannot supply |
 | `compileGraph` | function | Lower an authored graph against an engine's kind registry into the schedulable form, refusing |
 | `createEdgeLedger` | function | Open a ledger for one run; its ordinals continue past whatever a prior process recorded. |
 | `createGraphEngine` | function | Build one engine: a kind registry seeded with the core kinds plus the host's, and the host's |
@@ -1263,9 +1265,11 @@ Import from `@tangle-network/agent-runtime/graph` — 92 exports.
 | `decideJoin` | function | Decide whether a node's gating edges release it, and which of them the release consumes. |
 | `emptyFoldState` | function | The reducer's zero: every node unvisited, every edge pending, nothing suspended. |
 | `evaluateCondition` | function | Walk a validated condition over a context to a boolean. Never throws on data shape. |
+| `extractCodeBlock` | function | Pull the first fenced block out of a model reply; the whole reply if it carries no fence. |
 | `foldGraphJournal` | function | Fold a loaded journal (append order) into scheduler state. |
 | `formatRegistryHandle` | function | `<id>/v<n>` — the only spelling a handle has on the wire, in a journal, or in an error. |
 | `graphFromRunGraph` | function | Compile an `AgentGraph` into the engine graph that describes it. Pure: nothing runs, nothing is |
+| `inlineCodeRunner` | function | An in-process `codeRunner`: builds the authored body as a function with the granted API in |
 | `isEngineFired` | function | `delegates` is the one MODEL-fired edge kind (agent-runtime#971): its payload is a directive and |
 | `isSuspensionRequest` | function | Whether a node's output is a park request rather than its result. |
 | `kindHandle` | function | The handle a graph writes to name this kind. |
@@ -1274,6 +1278,7 @@ Import from `@tangle-network/agent-runtime/graph` — 92 exports.
 | `narrowEffects` | function | Narrow a host's effect table to exactly what one kind declared. Anything the kind did not |
 | `openGraphRun` | function | Begin or resume a run's journaled tree, pool, scope and folded state. |
 | `parseRegistryHandle` | function | Parse the wire spelling back. Refuses anything that is not exactly `<id>/v<n>`. |
+| `renderCodeApi` | function | The API doc the model is shown — generated from the grant, so the two cannot disagree. |
 | `runEngineGraph` | function | Run a graph to its result: `createGraphRun` awaited — the one-call form for a run that needs no |
 | `schemaAccepts` | function | Bounded structural acceptance: does a value of `source`'s shape fit `target`? Schemas with no |
 | `scriptKind` | function | Caller code as a node. The one kind with no kernel primitive behind it: the kernel has no |
@@ -1291,6 +1296,10 @@ Import from `@tangle-network/agent-runtime/graph` — 92 exports.
 | `JOIN_RULES` | const | Which gating-edge outcomes release a node (adopted from ADC, agent-runtime#968). |
 | `MAX_MAX_NODE_VISITS` | const | The hard ceiling an author's `maxVisits`/`maxNodeVisits` override may reach. |
 | `RUN_GRAPH_ROOT_KIND` | const | The kind id the root node carries: a supervisor holding the whole `AgentGraph`. |
+| `CodeAuthor` | interface | What a host's `model` effect must do: answer one prompt with text. |
+| `CodeOperation` | interface | One operation the authored program may call, and the line the model is shown about it. |
+| `CodeOperationResult` | interface | An operation's answer. `spend` is optional; an operation that costs nothing omits it. |
+| `CodeRunner` | interface | What a host's `codeRunner` effect must do: run authored source with `api` in scope, and answer |
 | `GraphEdgeTraversal` | interface | One ledgered edge firing (or refusal) — the run's observable data flow. |
 | `GraphHost` | interface | What a nesting kind needs from its host: run one graph, on the host's own kinds and effects. |
 | `GraphNodeSettle` | interface | One node settlement as the graph result reports it. |
@@ -1309,7 +1318,7 @@ Import from `@tangle-network/agent-runtime/graph` — 92 exports.
 | `OnCrash` | type | What happens to a node that was IN FLIGHT when the process died. A settled node is never a |
 | `ScriptBody` | type | The caller code a `script` node runs. Receives the resolved inputs; returns the output. |
 
-**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AgentKindConfig`, `CompiledEdge`, `CompiledGraph`, `CompiledNode`, `ConditionLeaf`, `EdgeLedger`, `EngineGraphEdge`, `EngineGraphNode`, `EngineGraphSpec`, `FoldEdge`, `FoldInstance`, `FoldNode`, `FoldSuspension`, `GatingEdge`, `GraphEngine`, `GraphEngineOptions`, `GraphFoldState`, `GraphRunContext`, `GraphRunOptions`, `JoinDecision`, `Registry`, `ScriptKindConfig`, `SupervisorKindConfig`, `Condition`, `ConditionOp`, `EffectContext`, `EffectName`, `FinalizerChoice`, `FoldEdgeState`, `FoldInstanceStatus`, `GraphEdgeKind`, `GraphRunResult`, `JoinRule`, `Projection`.
+**Undocumented supporting types** (add a TSDoc line at the declaration to earn a table row): `AgentKindConfig`, `CodeModeConfig`, `CompiledEdge`, `CompiledGraph`, `CompiledNode`, `ConditionLeaf`, `EdgeLedger`, `EngineGraphEdge`, `EngineGraphNode`, `EngineGraphSpec`, `FoldEdge`, `FoldInstance`, `FoldNode`, `FoldSuspension`, `GatingEdge`, `GraphEngine`, `GraphEngineOptions`, `GraphFoldState`, `GraphRunContext`, `GraphRunOptions`, `JoinDecision`, `Registry`, `ScriptKindConfig`, `SupervisorKindConfig`, `Condition`, `ConditionOp`, `EffectContext`, `EffectName`, `FinalizerChoice`, `FoldEdgeState`, `FoldInstanceStatus`, `GraphEdgeKind`, `GraphRunResult`, `JoinRule`, `Projection`.
 
 ### Environment provider adapters — generic sandbox/compute bridge