melchizedek-agents 1.5.0 → 1.7.0

package/CHANGELOG.md

@@ -6,6 +6,121 @@ the starter pack and the templates), not the repo's full history.
 
 ## Unreleased
 
+## 1.7.0 — 2026-10-17
+
+A minor release that lets a syndicate hold code (ADR 0137). A `script:`
+block is the fourth orchestration method: one JavaScript module, run in
+a QuickJS sandbox on a worker thread, calls the syndicate's agents, its
+allowed tools and the person as functions, so routing, per-call models
+and human-in-the-loop change with a YAML deploy instead of an engine
+release. Agents on any provider get `run_code`, the same sandbox as a
+registry tool. Both are off until the operator sets
+`MELCHIZEDEK_CODE_SANDBOX=on`; nothing changes for a deployment that
+does not.
+
+### Added
+
+- **`script:` orchestration (ADR 0137 Part B).** `script: { source,
+  models?, tools? }` at the root; cannot be combined with `dispatch` or
+  `workflow`. The default export is called with `{ message, transcript,
+  variables, agent, tool, askUser, parallel, now, random, log }` and its
+  return is the answer; guards run on it once. `agent(name, input, {
+  model?, reasoning?, temperature?, conversation? })` runs a declared
+  agent (parsed JSON when it has an output schema, else text; a failed run
+  throws into the script); `conversation: true` answers in the
+  conversation as a dispatch route does. `askUser(id, question, {
+  payload?, schema? })` pauses the turn `input-required` with the same
+  `result.input` an `ask_user` node writes; the next message resumes the
+  run by replaying its journal (one content-less event per call, stored in
+  the conversation only when the run pauses) on the source the pause pinned, so a redeploy never breaks
+  a waiting conversation. A resume whose calls no longer match fails
+  `SCRIPT_DIVERGED`; a run past 1,000 calls fails `SCRIPT_CALL_LIMIT`.
+  The schema refuses `require_approval`, the `ask_user` tool, local skill
+  scripts and authorization_code grants on a script's agents (a pause
+  inside a called agent cannot be replayed yet), `context:` and root
+  `max_concurrency`; `mode: task` is allowed (a pause reached inside a
+  called agent anyway fails `PAUSE_INSIDE_AGENT`). `{{token}}`
+  interpolation skips `script.source`; the script reads the bound
+  `variables`. `script.require_approval` gates `tool()` calls with the
+  standard approval request (`result.approval`). Every `script.models`
+  pairing is checked before the run (`SCRIPT_MODEL_INVALID`). Under
+  `runDurableTurn` each call's journal event is a checkpoint boundary, so
+  a stopped worker resumes mid-script. `agent()` calls report through
+  `events.onAgentEvent`; spans `script.invoke` and `script.call`
+  (exported to `adk_telemetry`, no arguments or results) trace a run, and
+  each agent call's turn span carries `script.run` and `script.call.seq`.
+  A `yaml_reference` to a script syndicate runs its whole script as a
+  subagent, route or node, its pauses reaching the turn; `agent()` may
+  call nested workflow, dispatch and script syndicates.
+  `startEngineSpan` takes an optional parent context.
+  `TurnStage` gains `'script'`; `SyndicateTurnResult.failedStage` may be
+  `'script'`.
+- **`run_code` (ADR 0137 Part A).** A registry tool: `{ code, input? }`,
+  an ES module whose default export is called with `input`, returning
+  `{ result, logs, error }`, each bounded at 20,000 characters. No
+  network, files, host, clock or randomness. An agent's
+  `run_code: { attach: true }` puts each run on the reply:
+  `SyndicateTurnResult.codeRuns` and, on the A2A server, a `code_runs`
+  artifact of `code_run` data parts. `DrainedRun` gains `codeRuns`.
+- **The sandbox.** QuickJS (`quickjs-emscripten-core` and
+  `@jitl/quickjs-wasmfile-release-sync`, both pinned at 0.32.0) on a
+  worker thread per run: 64 MB memory, 1 MB stack, 5 s of compute (waits
+  on the host not counted), a watchdog and the turn's signal terminate
+  it; `MELCHIZEDEK_CODE_SANDBOX_WORKERS` (default 16) caps concurrent
+  runs. A syndicate with a script or a `run_code` agent is refused with
+  `CodeSandboxOffError` when a turn starts while the switch is off.
+- **Package surface.** New subpaths `melchizedek-agents/script`
+  (`runScript`, `ScriptFatal`, `SCRIPT_CALL_LIMIT`, and the journal reader
+  `openRun` / `scriptPauseIn` with the `SCRIPT_*` marker keys and the
+  `JournalEntry`, `OpenRun`, `ScriptCallRecord`, `ScriptPauseRecord`,
+  `ScriptPinRecord` types) and
+  `melchizedek-agents/sandbox` (`runInSandbox`, `codeSandboxEnabled`,
+  `refuseWithoutSandbox`, `CodeSandboxOffError`, `SandboxHalt`,
+  `DEFAULT_SANDBOX_LIMITS`). The barrel adds those plus
+  `isScriptSyndicate`, `openRun`, `runCodeTool`, `RUN_CODE` and the types
+  `ScriptConfig`, `ScriptHost`, `ScriptCallSite`, `JournalEntry`, `OpenRun`,
+  `ScriptPauseRecord`, `ScriptPinRecord`, `ScriptRunInput`, `ScriptRunOutcome`,
+  `SandboxLimits`, `SandboxResult`, `SandboxRunOptions`, `CodeRun`,
+  `RunCodeOutput`.
+
+### For melch-app
+
+- An Electron build must list `quickjs-emscripten-core`,
+  `@jitl/quickjs-wasmfile-release-sync` and `melchizedek-agents/dist/lib/sandbox`
+  in `asarUnpack`: the wasm file and the worker script load from disk.
+
+## 1.6.0 — 2026-10-15
+
+A minor release for applications that show a turn as it runs and account
+for what it costs. Delegated subagents report live through
+`events.onAgentEvent`, with their path and the call that started them
+(ADR 0135), and the ledger records dollars: `model_pricing` and `cost_usd`
+on every turn and model-call row, computed at write time (ADR 0136).
+Nothing changes for a consumer that passes no new callback; a ledger
+deployment re-runs `npx melchizedek-db apply --telemetry` to get the
+column.
+
+### Added
+
+- **Live events from delegated subagents (ADR 0135).** `TurnEvents` gains
+  `onAgentEvent(event, branch)`: every event a delegated run yields, as it
+  yields it (thinking and text partials, tool calls, results, the answer),
+  at any depth, with `branch.agent`, `branch.path` (the delegation path from
+  the caller at the top) and `branch.callId` (the caller's call that started
+  it). New type export `AgentBranch` from the barrel and
+  `melchizedek-agents/runtime`; `TurnControl` gains the optional
+  `agentEvents` it is carried on. Passing the callback makes delegated runs
+  stream; the stored sessions, `onEvent` and `onTextDelta` are unchanged.
+
+- **Cost in the ledger (ADR 0136).** Migration `0015_model_pricing` adds
+  `model_pricing` (USD per million tokens, `verified_at` per row, seeded
+  from melch-obs's `pricing.toml`, `ollama/*` at zero) and the functions
+  `melchizedek_cost_usd` and `melchizedek_usage_cost`. `db/telemetry.sql`
+  adds `cost_usd` to `adk_turns` and `adk_telemetry`, filled at write time by
+  a trigger (NULL for a model with no row), and `cost_usd` to
+  `adk_kpi_daily`. The root span gains `syndicate.usage` (each model's
+  calls and tokens). Re-run `npx melchizedek-db apply --telemetry`.
+
 ## 1.5.0 — 2026-10-15
 
 A minor release that makes the engine embeddable in a single-process

package/DOCUMENTATION.md

@@ -35,6 +35,8 @@ lib/tools/mcpToolFactory.ts  MCP client: remote tools → the engine's own Tools
 scripts/demo_mcp_server.ts   demo MCP server (library catalog, SSE)
 lib/runtime/native/…      the native loop: steps, delegation, compaction, interrupts
 lib/workflow/…            the workflow scheduler for `workflow:` syndicates
+lib/script/…              the runner for `script:` syndicates: journal, replay, pause (ADR 0137)
+lib/sandbox/…             the QuickJS code sandbox on a worker thread (run_code, script:)
 lib/session/…             Supabase-backed session service
 lib/memory/…              pgvector long-term memory service
 lib/observability/…       OpenTelemetry run tracing
@@ -63,7 +65,7 @@ agent. The native runtime is the only runtime
 ([ADR 0107](./wiki/decisions/0107-release-1-0-0-removes-adk.md)): it owns the
 loop, the model contract and its adapters, the tools, the sessions and
 the workflow scheduler, and runs a single-agent, delegating,
-plan-dispatch or `workflow:` syndicate, `context:` compaction
+plan-dispatch, `workflow:` or `script:` syndicate, `context:` compaction
 ([ADR 0078](./wiki/decisions/0078-native-compaction-ports-adk-compactor.md)),
 `mode: task`, and pause and resume included
 ([ADR 0095](./wiki/decisions/0095-native-workflow-turn-drains-through-the-adk-reader.md)).
@@ -130,11 +132,13 @@ Field reference:
 | `memory_retention_days` | root | Days a fact in this syndicate's namespace is kept; the server deletes older facts when it loads the syndicate and daily after. Requires `memory_namespace` (never applied to the shared default namespace). |
 | `dispatch` | root | Switches the syndicate from DELEGATE to PLAN-DISPATCH routing (§6). `default_route` (required) names the fail-static subagent; `route_key` / `reason_key` name the router's JSON properties (defaults `route` / `reason`). Honoured by every surface (the CLI, the server, the worker, evals). |
 | `workflow` | root | Switches the syndicate to a WORKFLOW (§6): a graph whose nodes are its agents plus declared `join`, `map`, `tool` and `ask_user` nodes, and whose `edges` say what runs after what and on which route. The orchestrator is a node like any other; nothing delegates. Cannot be combined with `dispatch`. Contract: `lib/workflow.ts`; worked example: `examples/pipeline.yaml`. |
+| `script` | root | Switches the syndicate to a SCRIPT ([ADR 0137](./wiki/decisions/0137-script-orchestration-and-sandboxed-code.md)): `source` is one JavaScript module, run in the engine's QuickJS sandbox, whose default export gets `{ message, transcript, variables, agent, tool, askUser, parallel, now, random, log }` and returns the answer. `models` lists the models `agent(name, input, { model })` may move a call to; `tools` the registry tools `tool(name, args)` may run. `askUser` pauses the turn; the next message replays the run's journal on the source it pinned. Needs `MELCHIZEDEK_CODE_SANDBOX=on`; cannot be combined with `dispatch` or `workflow`; the agents may not pause inside themselves (no `require_approval`, `ask_user` tool, local skill scripts or authorization_code grants). `{{token}}` does not touch `source`. |
 | `retries` | root | Self-correction, on by default ([ADR 0034](./wiki/decisions/0034-self-correction.md)): `model_errors` (default 2) retries a model reply marked malformed (`MALFORMED_FUNCTION_CALL`) instead of failing the turn; `tool_errors` (default 3) answers a tool that threw with structured reflection guidance and caps its retries. `0` turns either off. Every retry is a model call under `max_steps`. |
 | `guards` | root | Optional list of post-answer guard NAMES (`lib/guards/index.ts`). Each runs after the answering turn and before the reply publishes, receiving the final text plus every tool-result text of that turn, and rewrites in place rather than re-asking the model; its notes land in the `[STATUS]` stream. Guards declared by a syndicate reached through `yaml_reference:` count too — the server resolves the union via `collectGuards()`. Resolved by name, never by module path, so adding one is a deliberate act in code; **the published registry ships one, `science`** (citation checks for `research.yaml`); `registerGuard()` adds your own from code, and an unregistered name is warned about and skipped. |
 | `name` / `model` / `instruction` | agent | The agent triple. Any Gemini id, `claude-*`, or `ollama/*` for open-weight local models (see §5). |
 | `description` | subagent | **The delegation API.** The orchestrator reads this when deciding to hand off — write it like a function signature ("Use this subagent to…, pass it…"). |
 | `tools` | agent | Names resolved by the tool registry (§3). Long-term memory agents add `preload_memory` / `load_memory`. |
+| `run_code` | agent | With `run_code` in `tools`, the agent runs JavaScript in the engine's sandbox on any provider (`{ code, input? }` → `{ result, logs, error }`; no network, host, clock or randomness; needs `MELCHIZEDEK_CODE_SANDBOX=on`, [ADR 0137](./wiki/decisions/0137-script-orchestration-and-sandboxed-code.md)). `run_code: { attach: true }` puts each run's code and result on the reply as a `code_run` data part (`result.codeRuns`). |
 | `reasoning` | agent | How hard the agent reasons, on any provider: `none`, `low`, `medium`, `high`, `xhigh`, `max`, or `{ budget_tokens: <int> }`. The compiler sends each provider the field it reads: a thinking level on Gemini 3, a thinking budget on Claude 4.6 and earlier (2,048 / 8,192 / 16,384 tokens for low / medium / high), adaptive thinking with that effort on later Claude models ([ADR 0049](./wiki/decisions/0049-claude-requests-by-model-generation.md)), an effort word on GPT, Grok, Kimi, Ollama and the gateway ([ADR 0047](./wiki/decisions/0047-provider-neutral-reasoning-key.md)). `xhigh` and `max` reach the models that take them (both on Claude from Opus 4.7 and Sonnet 5, `max` on Kimi K3, `xhigh` on GPT-5.2 and later and grok-4.7); elsewhere the model's highest setting is sent and the span carries `llm.reasoning.weakened` (`npm run doctor -- --matrix` lists each path, [ADR 0117](./wiki/decisions/0117-tool-choice-and-effort-above-high-in-v2.md)). Unset, each adapter keeps its own default. |
 | `sampling` | agent | `{ temperature, top_p, max_output_tokens, stop }`, the fields the engine sends to every provider; each adapter sends the ones its API takes ([ADR 0115](./wiki/decisions/0115-yaml-schema-v2-provider-neutral-keys.md)). |
 | `output` | agent | `{ schema, mime }`. `mime` is `application/json` (JSON mode, with or without a schema) or `text/plain` (the default). `schema` is the structured-JSON contract: the agent ends its turn on one JSON object matching it. An orchestrator may hold one beside its subagents: it delegates first, then answers in the schema itself. The schema travels in the provider's own structured-output field beside the tools on Claude from Opus 4.8, Sonnet 5 and Haiku 5.5, on OpenAI, and on Gemini 2+ through Vertex AI, and as a `set_model_response` tool elsewhere (the capability matrix's `structured_output_with_tools`, [ADR 0109](./wiki/decisions/0109-structured-output-beside-tools.md)). Worked example: `examples/structured_critic.yaml`. A leaf that holds the schema (`critic.yaml`) and plan-dispatch remain the choices when the answer should be a specialist's. |
@@ -634,7 +638,17 @@ a clean call's row comes from `model.call` and holds the request and the
 adapter's response in the contract's shapes. Rows written before 1.0.0
 under ADK's `invoke_agent`, `call_llm` and `execute_tool` spans hold ADK's
 request, and the ledger still reads them (ADR 0076). The view `adk_turns_production` excludes
-eval and classifier turns. Operate it with `npm run telemetry:stats`,
+eval and classifier turns. `adk_turns.cost_usd` and `adk_telemetry.cost_usd`
+are filled at write time by a trigger from `model_pricing` (migration 0015,
+USD per million tokens, seeded from melch-obs's `pricing.toml` with a
+`verified_at` per row; NULL means unchecked): a model call from its model and
+tokens, a turn from its per-model usage (`syndicate.usage` on the root span,
+input summed per call), thinking at the output rate unless the row sets
+`thinking_per_mtok`. A model with no row leaves the call and its turn NULL,
+never a partial sum; `ollama/*` costs zero. Add or change a rate with an
+`INSERT … ON CONFLICT (model) DO UPDATE` on `model_pricing`; rows already
+written keep the rate in force when they were written (ADR 0136).
+Operate it with `npm run telemetry:stats`,
 `telemetry:prune` and `telemetry:replay` (the exporter spools failed
 batches to `outputs/telemetry-deadletter.ndjson`).
 
@@ -847,6 +861,18 @@ in flight, and the task ends `canceled`. Final states: `completed`,
 capacity). Message parts may be `text` or `data` (sent to the model as
 JSON); `file` parts are refused.
 
+In code, `runSyndicateTurn`'s `events` follow a turn as it runs:
+`onProgress` (the `[STATUS]` lines), `onEvent` (every event of the
+answering agent), `onTextDelta`/`onTextReset` (its reply as it is written,
+with `streaming: true`), and `onAgentEvent(event, branch)` for delegated
+runs (ADR 0135). The last receives every event a delegated subagent yields
+while it runs: its thinking and text as partial events, then its tool
+calls, their results and its answer, at any depth. `branch.agent` names the
+subagent, `branch.path` lists the agents from the caller at the top down to
+it, and `branch.callId` is the id of the caller's call that started it, so
+calls running at once can be told apart. Passing it makes delegated runs
+stream; the sessions store the same events either way.
+
 #### Approval gates (`require_approval`)
 
 A skill script run (`skills.scripts: local`) pauses the same way, without being listed: every `run_skill_script` call waits for the person's answer.

package/README.md

@@ -104,7 +104,7 @@ const result = await runSyndicateTurn({
 console.log(result.status, result.text);
 ```
 
-`runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. It runs every syndicate on the engine's own agent loop and, for a workflow, its own scheduler (the `native` runtime, the only one). `MELCHIZEDEK_RUNTIME=adk` is an error that names 1.0.0; `npx melchizedek-doctor` prints the runtime in use (ADR 0107). To read syndicates from somewhere else, pass `loadSyndicate(file, { agentsDir })` or set `MELCHIZEDEK_AGENTS_DIR`. To serve inside your own Express app, mount `(await createA2AApp({ defaultSyndicate: 'mine.yaml', serverSecret })).app`.
+`runSyndicateTurn` is the same runtime the server, CLI, and eval harness use. It runs every syndicate on the engine's own agent loop and, for a workflow, its own scheduler (the `native` runtime, the only one). `MELCHIZEDEK_RUNTIME=adk` is an error that names 1.0.0; `npx melchizedek-doctor` prints the runtime in use (ADR 0107). To read syndicates from somewhere else, pass `loadSyndicate(file, { agentsDir })` or set `MELCHIZEDEK_AGENTS_DIR`. To serve inside your own Express app, mount `(await createA2AApp({ defaultSyndicate: 'mine.yaml', serverSecret })).app`. `events.onEvent` and `events.onTextDelta` follow the answering agent; `events.onAgentEvent(event, branch)` follows every delegated subagent live, its thinking, text and tool calls, with `branch.path` and `branch.callId` saying where it runs (ADR 0135).
 
 The example syndicates ship inside the package at `node_modules/melchizedek-agents/config/agents/examples/`; copy one out as a starting point.
 

package/config/agents/syndicate.schema.json

@@ -943,6 +943,17 @@
           "type": "string",
           "const": "gemini"
         },
+        "run_code": {
+          "description": "How this agent's run_code tool behaves (ADR 0137). Needs run_code in `tools`.",
+          "type": "object",
+          "properties": {
+            "attach": {
+              "description": "Put each run's code and result on the reply as a code_run data part. Default false.",
+              "type": "boolean"
+            }
+          },
+          "additionalProperties": false
+        },
         "context": {
           "description": "Summarize a long conversation instead of overflowing the window. The orchestrator of a delegate syndicate only.",
           "type": "object",
@@ -1967,6 +1978,17 @@
             "type": "string",
             "const": "gemini"
           },
+          "run_code": {
+            "description": "How this agent's run_code tool behaves (ADR 0137). Needs run_code in `tools`.",
+            "type": "object",
+            "properties": {
+              "attach": {
+                "description": "Put each run's code and result on the reply as a code_run data part. Default false.",
+                "type": "boolean"
+              }
+            },
+            "additionalProperties": false
+          },
           "context": {
             "description": "Summarize a long conversation instead of overflowing the window. The orchestrator of a delegate syndicate only.",
             "type": "object",
@@ -2302,6 +2324,47 @@
       "additionalProperties": false,
       "description": "Opts into a WORKFLOW: the syndicate as a graph (lib/workflow.ts). Cannot be combined with dispatch."
     },
+    "script": {
+      "type": "object",
+      "properties": {
+        "source": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 65536,
+          "description": "One JavaScript module whose default export is an async function of { message, variables, agent, tool, askUser, parallel, now, random, log }: the orchestration. Its return value is the answer. {{token}} interpolation does not touch it; it reads `variables`."
+        },
+        "models": {
+          "description": "The models agent(name, input, { model }) may move a call to; each agent is compiled and checked on every one at load.",
+          "maxItems": 16,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "tools": {
+          "description": "The registry tools tool(name, args) may run; the only path from the script to the network or the host.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "require_approval": {
+          "description": "Tools from script.tools whose every call waits for a person to approve the exact call (ADR 0028): the turn ends input-required; approved, the pinned arguments run, refused, the script gets { error }.",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "required": [
+        "source"
+      ],
+      "additionalProperties": false,
+      "description": "Opts into SCRIPT orchestration (lib/script/): the syndicate's logic as code run in the engine's sandbox. Needs MELCHIZEDEK_CODE_SANDBOX=on. Cannot be combined with dispatch or workflow."
+    },
     "retries": {
       "description": "Self-correction on model and tool errors: the engine's reflect-and-retry. On by default.",
       "type": "object",

package/config/agents/syndicateSchema.yaml

@@ -190,6 +190,48 @@ dispatch:
 #     Confirm: { ask_user: "Publish? Reply yes, or say what to change." }
 #   max_concurrency: 4
 
+# [optional] Switches this syndicate to a SCRIPT (ADR 0137): one
+# JavaScript module, run in the engine's QuickJS sandbox, is the
+# orchestration. It calls the agents below, the tools it lists and the
+# person as functions, so routing, per-call models and pauses live here
+# and change with a deploy. Needs MELCHIZEDEK_CODE_SANDBOX=on. Cannot be
+# combined with `dispatch` or `workflow`. Contract: lib/script/.
+#
+#   - The default export is called with { message, transcript, variables,
+#     agent, tool, askUser, parallel, now, random, log }; its return (text,
+#     or JSON) is the answer, and `guards` run on it once.
+#   - agent(name, input, { model?, reasoning?, temperature?,
+#     conversation? }) runs a declared agent seeing only `input` (null:
+#     the message); it returns parsed JSON when the agent has an output
+#     schema, else its text, and throws when the run fails. With
+#     `conversation: true` it answers in the conversation, as a dispatch
+#     route does. `model` must be in script.models.
+#   - tool(name, args) runs a registry tool listed in script.tools; one
+#     also in script.require_approval waits for a person to approve the
+#     exact call (refused, the script gets { error }).
+#   - askUser(id, question, { payload?, schema? }) pauses the turn
+#     input-required; the next message resumes it, returning
+#     { reply, input }. The run replays its journal from the top, so a
+#     script must make the same calls on every run: use now() and
+#     random(), never Date or Math.random (they throw), and never
+#     Promise.race.
+#   - require_approval, the ask_user tool, skills.scripts: local and
+#     authorization_code grants are refused on a script's agents in this
+#     version (a pause inside a called agent cannot be replayed).
+#   - {{token}} interpolation does not touch `source`; read `variables`.
+#   - A yaml_reference to a script syndicate runs its whole script as a
+#     subagent, a route or a node, its pauses reaching the turn.
+# script:
+#   models: ["gemini-3.8-flash", "claude-opus-5-5"]
+#   tools: ["web_extract", "publish"]
+#   require_approval: ["publish"]
+#   source: |
+#     export default async ({ message, agent, askUser, log }) => {
+#       const triage = await agent("OrchestratorName", message);
+#       log(`Routed to ${triage.route}`);
+#       return agent(triage.route, null, { conversation: true });
+#     };
+
 # ── Orchestrator ────────────────────────────────────────────
 # The turn's root agent: the engine's agent loop runs it. Its keys are
 # spelled after ADK's LlmAgentConfig.
@@ -293,6 +335,14 @@ orchestrator:
   # Google's server-side sandbox; nothing runs on this host. Gemini only.
   # code_execution: "gemini"
 
+  # [optional] With `run_code` in tools, the agent runs JavaScript in the
+  # engine's QuickJS sandbox on any provider and rests its answer on the
+  # result (no network, no host, no clock; needs MELCHIZEDEK_CODE_SANDBOX=on,
+  # ADR 0137). `attach: true` puts each run's code and result on the reply
+  # as a code_run data part. Default off.
+  # run_code:
+  #   attach: true
+
   # [optional] Summarize a long conversation instead of overflowing the
   # window: past `compact_after_tokens` (the last request's prompt), earlier
   # turns become one summary and the last `keep_recent_events` stay

package/db/hardening.sql

@@ -75,7 +75,8 @@ DO $$
 DECLARE t text;
 BEGIN
   FOREACH t IN ARRAY ARRAY['adk_telemetry', 'adk_turns', 'adk_payloads', 'adk_verdicts', 'adk_labels',
-                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit'] LOOP
+                            'adk_session_events', 'adk_a2a_tasks', 'melchizedek_usage', 'melchizedek_audit',
+                            'model_pricing'] LOOP
     IF to_regclass('public.' || t) IS NOT NULL THEN
       EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', t);
       PERFORM pg_temp.melchizedek_revoke_api(format('%I', t));
@@ -163,7 +164,9 @@ BEGIN
                         'melchizedek_registry_versions_immutable', 'melchizedek_registry_publish',
                         'melchizedek_registry_activate', 'melchizedek_memory_commit',
                         'melchizedek_memory_dimensions', 'melchizedek_prune_memory_ingest',
-                        'melchizedek_prune_memory', 'melchizedek_prune_audit')
+                        'melchizedek_prune_memory', 'melchizedek_prune_audit',
+                        'melchizedek_cost_usd', 'melchizedek_usage_cost', 'melchizedek_usage_text_cost',
+                        'melchizedek_turns_cost', 'melchizedek_telemetry_cost')
   LOOP
     EXECUTE format('REVOKE ALL ON FUNCTION %s FROM PUBLIC', fn);
     PERFORM pg_temp.melchizedek_revoke_api(format('FUNCTION %s', fn));

package/db/migrations/0015_model_pricing.sql

@@ -0,0 +1,107 @@
+-- ============================================================================
+-- 0015_model_pricing — what a model call costs, so the ledger records dollars
+--                      (ADR 0136)
+-- ============================================================================
+-- model_pricing: USD per million tokens, one row per model id as the YAML
+-- declares it (`claude-opus-5`, `gemini-3.8-flash`, `grok-4.7`). A row whose
+-- id ends in `/*` prices every id under that prefix (`ollama/*`: local
+-- models cost nothing). `thinking_per_mtok` NULL means thinking bills at the
+-- output rate, as every provider here bills it. `verified_at` NULL means
+-- nobody has checked the row against the vendor's price list: spend built on
+-- it is a steering estimate (the convention ymir_model_pricing set).
+--
+-- Seeded from melch-obs's pricing.toml (2026-10). The seed never overwrites a
+-- row: an operator's own rates survive a re-run. A rate change ships as a
+-- later migration that UPDATEs the row and its verified_at.
+--
+-- The cost functions below are what db/telemetry.sql's ledger trigger calls
+-- to fill adk_turns.cost_usd and adk_telemetry.cost_usd at write time:
+--   melchizedek_cost_usd(model, input, output, thinking)  one call's cost,
+--       NULL for a model with no row
+--   melchizedek_usage_cost(usage)  a turn's cost from its per-model usage
+--       ({"<model>": {"input": n, "output": n, "thinking": n}}), NULL when
+--       any model in it has no row: a partial sum would read as the total.
+-- Ledger output_tokens exclude thinking (genaiMapping's usage meaning), so
+-- thinking is priced on top of output.
+--
+-- Nothing secret, nothing personal; hardening.sql closes it to the API roles
+-- like every other table. Idempotent; safe to re-run.
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS model_pricing (
+  model              TEXT PRIMARY KEY,
+  input_per_mtok     NUMERIC NOT NULL CHECK (input_per_mtok >= 0),
+  output_per_mtok    NUMERIC NOT NULL CHECK (output_per_mtok >= 0),
+  thinking_per_mtok  NUMERIC CHECK (thinking_per_mtok >= 0),
+  verified_at        TIMESTAMPTZ,
+  source             TEXT,
+  note               TEXT,
+  updated_at         TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+INSERT INTO model_pricing (model, input_per_mtok, output_per_mtok, verified_at, source, note) VALUES
+  -- Anthropic first-party rates; pricing.toml dates the check to the month (2026-06).
+  ('claude-fable-5-1',      10.00, 50.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-fable-5',        10.00, 50.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-5',          5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-8',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-7',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-opus-4-6',        5.00, 25.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-sonnet-5',        2.00, 10.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-sonnet-4-6',      3.00, 15.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('claude-haiku-4-5',       1.00,  5.00, '2026-06-01', 'melch-obs/pricing.toml', 'Anthropic first-party, checked 2026-06'),
+  ('gemini-3.5-flash-lite',  0.30,  2.50, '2026-10-01', 'melch-obs/pricing.toml', 'Gemini API standard tier, checked 2026-10-01'),
+  -- Carried over from ymir_model_pricing, never checked against a vendor list.
+  ('gemini-3.1-flash-lite',  0.10,  0.40, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('gemini-3.7-flash',       0.30,  2.50, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('gemini-3.8-flash',       0.30,  2.50, NULL, 'melch-obs/pricing.toml', 'placeholder at 3.7''s rate, unverified'),
+  ('grok-4.5',               3.00, 15.00, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  ('grok-4.7',               3.00, 15.00, NULL, 'melch-obs/pricing.toml', 'unverified estimate'),
+  -- A local model bills nothing; that needs no vendor list.
+  ('ollama/*',               0,     0,    '2026-10-15', 'engine', 'local models: no provider charge')
+ON CONFLICT (model) DO NOTHING;
+
+-- The row that prices `model`: its own, else its prefix's `<prefix>/*`.
+CREATE OR REPLACE FUNCTION melchizedek_cost_usd(model TEXT, input BIGINT, output BIGINT, thinking BIGINT)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT (coalesce(input, 0) * p.input_per_mtok
+          + coalesce(output, 0) * p.output_per_mtok
+          + coalesce(thinking, 0) * coalesce(p.thinking_per_mtok, p.output_per_mtok)) / 1000000
+  FROM model_pricing p
+  WHERE p.model = melchizedek_cost_usd.model
+     OR (position('/' IN melchizedek_cost_usd.model) > 0
+         AND p.model = split_part(melchizedek_cost_usd.model, '/', 1) || '/*')
+  ORDER BY (p.model = melchizedek_cost_usd.model) DESC
+  LIMIT 1
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_usage_cost(usage JSONB)
+RETURNS NUMERIC
+LANGUAGE sql
+STABLE
+SET search_path = public
+AS $$
+  SELECT CASE
+    WHEN usage IS NULL OR jsonb_typeof(usage) <> 'object' THEN NULL
+    -- bool_and over no rows is NULL: a turn that made no model call costs nothing.
+    WHEN coalesce(bool_and(c.cost IS NOT NULL), true) THEN coalesce(sum(c.cost), 0)
+    ELSE NULL
+  END
+  FROM (
+    SELECT melchizedek_cost_usd(
+             e.key,
+             CASE WHEN jsonb_typeof(e.value->'input') = 'number' THEN (e.value->>'input')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'output') = 'number' THEN (e.value->>'output')::numeric::bigint END,
+             CASE WHEN jsonb_typeof(e.value->'thinking') = 'number' THEN (e.value->>'thinking')::numeric::bigint END
+           ) AS cost
+    FROM jsonb_each(CASE WHEN jsonb_typeof(usage) = 'object' THEN usage ELSE '{}'::jsonb END) e
+  ) c
+$$;
+
+INSERT INTO melchizedek_schema_version (version, name)
+VALUES (15, '0015_model_pricing')
+ON CONFLICT (version) DO NOTHING;

package/db/telemetry.sql

@@ -163,6 +163,83 @@ CREATE INDEX IF NOT EXISTS idx_adk_turns_surface_user
 -- at CREATE time. It does not gain these columns until it is re-created, so
 -- run the whole file, in order.
 
+-- ── Cost: dollars per turn and per model call (ADR 0136) ─────────────────
+-- cost_usd is filled at write time by the trigger below from model_pricing
+-- (db/migrations/0015_model_pricing.sql), so both sinks and a replayed
+-- dead-letter spool get it, and the price table is the one source:
+--   adk_telemetry  an llm.request row: its model and tokens. A root row: the
+--                  turn's per-model usage on the span (syndicate.usage).
+--   adk_turns      the turn's per-model usage (attributes->'syndicate.usage',
+--                  the tracer sums each model's calls), so a turn that used
+--                  two models is priced per model, input summed per call.
+-- NULL when a model has no price row (a partial sum would read as the
+-- total), or when the row carries no usage (a row written before this
+-- column). A value the writer set itself is kept. The rate in force at
+-- write time is the rate recorded: a later price change does not rewrite
+-- history. Re-price on purpose with an UPDATE ... SET cost_usd = ... .
+ALTER TABLE adk_turns     ADD COLUMN IF NOT EXISTS cost_usd NUMERIC;
+ALTER TABLE adk_telemetry ADD COLUMN IF NOT EXISTS cost_usd NUMERIC;
+
+-- SECURITY DEFINER: the inserting role (service_role, or an application's
+-- own role) need not be able to execute the pricing functions or read
+-- model_pricing. Each reads only NEW and the price table. Unreadable usage
+-- leaves the cost NULL; it never fails the insert.
+CREATE OR REPLACE FUNCTION melchizedek_usage_text_cost(usage_text TEXT)
+RETURNS NUMERIC
+LANGUAGE plpgsql
+STABLE
+SET search_path = public
+AS $$
+BEGIN
+  IF usage_text IS NULL OR to_regclass('model_pricing') IS NULL THEN
+    RETURN NULL;
+  END IF;
+  RETURN melchizedek_usage_cost(usage_text::jsonb);
+EXCEPTION WHEN others THEN
+  RETURN NULL;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_turns_cost()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  IF NEW.cost_usd IS NULL THEN
+    NEW.cost_usd := melchizedek_usage_text_cost(NEW.attributes->>'syndicate.usage');
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION melchizedek_telemetry_cost()
+RETURNS trigger
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  IF NEW.cost_usd IS NOT NULL OR to_regclass('model_pricing') IS NULL THEN
+    RETURN NEW;
+  END IF;
+  IF NEW.model IS NOT NULL THEN
+    NEW.cost_usd := melchizedek_cost_usd(NEW.model, NEW.input_tokens, NEW.output_tokens, NEW.thinking_tokens);
+  ELSE
+    NEW.cost_usd := melchizedek_usage_text_cost(NEW.span->'attributes'->>'syndicate.usage');
+  END IF;
+  RETURN NEW;
+END;
+$$;
+
+DROP TRIGGER IF EXISTS melchizedek_turns_cost ON adk_turns;
+CREATE TRIGGER melchizedek_turns_cost BEFORE INSERT ON adk_turns
+  FOR EACH ROW EXECUTE FUNCTION melchizedek_turns_cost();
+DROP TRIGGER IF EXISTS melchizedek_telemetry_cost ON adk_telemetry;
+CREATE TRIGGER melchizedek_telemetry_cost BEFORE INSERT ON adk_telemetry
+  FOR EACH ROW EXECUTE FUNCTION melchizedek_telemetry_cost();
+
 -- ── adk_payloads: full prompt/response per model call, by policy, expiring ─
 CREATE TABLE IF NOT EXISTS adk_payloads (
   id              BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
@@ -360,7 +437,8 @@ CREATE OR REPLACE VIEW adk_kpi_daily AS
          sum(output_tokens)                                 AS output_tokens,
          sum(thinking_tokens)                               AS thinking_tokens,
          avg(llm_calls)                                     AS avg_llm_calls,
-         avg(tool_calls)                                    AS avg_tool_calls
+         avg(tool_calls)                                    AS avg_tool_calls,
+         sum(cost_usd)                                      AS cost_usd
   FROM adk_turns_production
   GROUP BY 1, 2;
 

package/dist/lib/a2a/executor.js

@@ -375,6 +375,24 @@ export function approvalAnswer(rawParts, pending) {
     }
     return undefined;
 }
+/** The `code_runs` artifact: one `code_run` data part per run an attaching agent made (ADR 0137 item 3). */
+function publishCodeRuns(eventBus, taskId, contextId, runs) {
+    eventBus.publish(AgentEvent.artifactUpdate({
+        taskId,
+        contextId,
+        artifact: {
+            artifactId: 'code_runs',
+            name: 'code_runs',
+            description: 'The code the answer rests on, and what it returned',
+            parts: runs.map((run) => ({ content: { $case: 'data', value: run }, metadata: undefined, filename: '', mediaType: 'application/json' })),
+            metadata: undefined,
+            extensions: [],
+        },
+        append: false,
+        lastChunk: true,
+        metadata: undefined,
+    }));
+}
 function publishFinal(eventBus, taskId, contextId, state, text) {
     eventBus.publish(AgentEvent.statusUpdate({
         taskId,
@@ -687,6 +705,9 @@ export class SyndicateExecutor {
                 return;
             }
             log(`✓ Task ${short} complete — ${result.text.length.toLocaleString()} chars, ${spent}`);
+            // run_code's attach (ADR 0137): the code an answer rests on, and its result, as data parts beside it.
+            if (result.codeRuns?.length)
+                publishCodeRuns(eventBus, taskId, contextId, result.codeRuns);
             publishFinal(eventBus, taskId, contextId, 'completed', result.text || undefined);
             await report(ctx, 'completed', undefined, u);
             // Long-term memory: there is no "session end" on a server, so ingest

package/dist/lib/compile.d.ts

@@ -115,9 +115,10 @@ export type SpecTool = {
     dispatch: DispatchSpec;
 };
 /**
- * A nested dispatch (plan-dispatch) syndicate (ADR 0120): it runs as it
- * runs at the top, as a turn of its own on its own conversation (its
- * classifier picks a route, the route answers), so what it compiles to is
+ * A nested dispatch (plan-dispatch) syndicate (ADR 0120), or a nested
+ * script syndicate (ADR 0137 item 15): it runs as it runs at the top, as a
+ * turn of its own on its own conversation (its classifier picks a route and
+ * the route answers, or its script runs), so what it compiles to is
  * the file and the options its turn loads its routes with. The turn runner
  * runs it (lib/runtime/syndicateTurn.ts, TurnControl.nestedDispatch), as a
  * delegated call, a dispatch route or a workflow node.