melchizedek-agents 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -6,6 +6,89 @@ 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

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. |

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/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.

package/dist/lib/compile.js

@@ -37,6 +37,7 @@
 import { relative } from 'node:path';
 import { isDispatchSyndicate } from './dispatch.js';
 import { isWorkflowSyndicate, nodeKind } from './workflowConfig.js';
+import { isScriptSyndicate } from './script/config.js';
 import { loadSyndicate, nestedLoader } from './loadSyndicate.js';
 import { REASONING_OLDER_SPELLING } from './syndicateSchema.js';
 import { reasoningConfig } from './models/reasoning.js';
@@ -134,7 +135,7 @@ function gateTools(tools, names, agentName) {
 }
 /** True when any agent of a syndicate may pause for approval: a gated tool, or skill scripts. */
 export function declaresApprovals(config) {
-    return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s));
+    return agentGates(config.orchestrator) || (config.subagents ?? []).some((s) => agentGates(s)) || !!config.script?.require_approval?.length;
 }
 /**
  * An agent's `examples:` as their InstructionTool (lib/tools/examples.ts):
@@ -398,8 +399,9 @@ export async function compileEntrySpec(subCfg, opts = {}, delegated = false) {
         if (isWorkflowSyndicate(nested)) {
             return { kind: 'workflow', workflow: await compileWorkflowSpec(nested, nestedOpts, subCfg.name, subCfg.description, subCfg.yaml_reference, delegated) };
         }
-        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs.
-        if (isDispatchSyndicate(nested))
+        // A nested dispatch syndicate classifies and routes as at the top (ADR 0120), wherever it runs; a nested script
+        // syndicate runs its whole script the same way, as a turn of its own (ADR 0137 item 15).
+        if (isDispatchSyndicate(nested) || isScriptSyndicate(nested))
             return { kind: 'dispatch', dispatch: compileDispatchEntry(subCfg, nested, nestedOpts) };
         return { kind: 'agent', spec: await compileSpec(nested, nestedOpts, subCfg.name, subCfg.description) };
     }
@@ -437,6 +439,9 @@ export async function compileSubagentSpec(subCfg, opts = {}) {
         if (isDispatchSyndicate(nested)) {
             throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a dispatch syndicate, which runs as its own turn (its classifier, then a route), not as one agent; compile the entry with compileEntrySpec (ADR 0120).`);
         }
+        if (isScriptSyndicate(nested)) {
+            throw new Error(`${subCfg.yaml_reference}: '${subCfg.name}' is a script syndicate, which runs as its own turn (its script), not as one agent; compile the entry with compileEntrySpec (ADR 0137).`);
+        }
         return compileSpec(nested, nestedOpts, subCfg.name, subCfg.description);
     }
     // YAML v2 (ADR 0115): the engine form, for a config built in code (a loaded one already is).

package/dist/lib/index.d.ts

@@ -28,6 +28,14 @@ export type { AgentBranch, DrainedRun, MessagePart, TurnUsage, RouteDecision, Sy
 export type { CompileOptions } from './compile.ts';
 export { isWorkflowSyndicate, describeInput } from './workflow.ts';
 export type { WorkflowConfig, WorkflowNodeYaml, EdgeElement, PendingInput } from './workflow.ts';
+export { isScriptSyndicate } from './script/config.ts';
+export type { ScriptConfig } from './script/config.ts';
+export { openRun, runScript, ScriptFatal, SCRIPT_CALL_LIMIT } from './script/run.ts';
+export type { JournalEntry, OpenRun, ScriptCallSite, ScriptHost, ScriptPauseRecord, ScriptPinRecord, ScriptRunInput, ScriptRunOutcome } from './script/run.ts';
+export { CODE_SANDBOX_ENV, CodeSandboxOffError, DEFAULT_SANDBOX_LIMITS, SandboxHalt, codeSandboxEnabled, runInSandbox } from './sandbox/sandbox.ts';
+export type { SandboxLimits, SandboxResult, SandboxRunOptions } from './sandbox/sandbox.ts';
+export { RUN_CODE, runCodeTool } from './tools/runCodeTool.ts';
+export type { CodeRun, RunCodeOutput } from './tools/runCodeTool.ts';
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.ts';
 export type { A2AApp, A2AAppOptions, RequestIdentity } from './a2a/app.ts';
 export type { A2AContext } from './a2a/executor.ts';

package/dist/lib/index.js

@@ -23,6 +23,11 @@ export { DEFAULT_RUNTIME, describeRuntime, RuntimeRemovedError, UnsupportedOnRun
 export { InProcessSessionService } from './runtime/sessions.js';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.js';
 export { isWorkflowSyndicate, describeInput } from './workflow.js';
+// SCRIPT orchestration and the code sandbox (ADR 0137).
+export { isScriptSyndicate } from './script/config.js';
+export { openRun, runScript, ScriptFatal, SCRIPT_CALL_LIMIT } from './script/run.js';
+export { CODE_SANDBOX_ENV, CodeSandboxOffError, DEFAULT_SANDBOX_LIMITS, SandboxHalt, codeSandboxEnabled, runInSandbox } from './sandbox/sandbox.js';
+export { RUN_CODE, runCodeTool } from './tools/runCodeTool.js';
 // ── Serve it over A2A, or call a remote A2A agent ───────────────────────────
 export { createA2AApp, compileAgentCard, currentRequestContext } from './a2a/app.js';
 export { callerTokens, firstOf, hashCallerToken, jwtIdentity, parseCallers, scopeSegment, sharedSecret, trustedHeader, } from './a2a/identity.js';

package/dist/lib/loadSyndicate.d.ts

@@ -11,6 +11,8 @@ export type { SkillsConfig } from './tools/skillToolset.ts';
 import type { WorkflowConfig } from './workflowConfig.ts';
 import type { ReasoningSetting } from './models/contract.ts';
 export type { WorkflowConfig } from './workflowConfig.ts';
+export type { ScriptConfig } from './script/config.ts';
+import type { ScriptConfig } from './script/config.ts';
 export interface ThinkingConfig {
     /** Token budget for internal reasoning. 0 = off, -1 = dynamic. */
     thinkingBudget?: number;
@@ -175,6 +177,10 @@ export interface AgentYamlConfig {
     openapi?: OpenApiConfig[];
     /** `gemini`: the model's Python runs in Gemini's server-side sandbox (ADR 0033). Gemini models only. */
     code_execution?: 'gemini';
+    /** How this agent's `run_code` tool behaves (ADR 0137): `attach` puts each run's code and result on the reply. Needs run_code in `tools`. */
+    run_code?: {
+        attach?: boolean;
+    };
     /** Compact a long conversation into a summary past a token threshold (ADR 0033). Delegate orchestrator only. */
     context?: ContextConfig;
     /** `task`: the agent works until it calls finish_task; its arguments are the node's output. Workflow nodes only. */
@@ -239,6 +245,13 @@ export interface SyndicateYamlConfig {
      * Contract: lib/workflow.ts.
      */
     workflow?: WorkflowConfig;
+    /**
+     * Opts this syndicate into SCRIPT orchestration (ADR 0137): one JavaScript
+     * module, run in the engine's sandbox, calls the agents, the allowed tools
+     * and a person as functions. Cannot be combined with `dispatch` or
+     * `workflow`. Needs MELCHIZEDEK_CODE_SANDBOX=on. Contract: lib/script/.
+     */
+    script?: ScriptConfig;
     /** Optional default variable definitions for {{token}} interpolation. */
     variables?: VariableMap;
     /** Defines the persistence and semantic memory layer for the syndicate. */

package/dist/lib/loadSyndicate.js

@@ -87,7 +87,12 @@ function resolveAndValidate(raw, label, options) {
         ...yamlVars,
         ...bindings,
     };
-    const interpolated = isPlainObject(raw) ? interpolateDeep(raw, merged) : raw;
+    // A script's source is code, not a template: `{{` is JavaScript there, and the script reads `variables` itself (ADR 0137 item 5).
+    const scriptSource = isPlainObject(raw) && isPlainObject(raw.script) && typeof raw.script.source === 'string' ? raw.script.source : undefined;
+    let interpolated = isPlainObject(raw) ? interpolateDeep(raw, merged) : raw;
+    if (scriptSource !== undefined && isPlainObject(interpolated) && isPlainObject(interpolated.script)) {
+        interpolated = { ...interpolated, script: { ...interpolated.script, source: scriptSource } };
+    }
     warnV1Spellings(interpolated, label, options.onWarning);
     const unresolved = findUnresolvedTokens(interpolated);
     if (unresolved.length > 0) {
@@ -96,6 +101,11 @@ function resolveAndValidate(raw, label, options) {
     const valid = validateSyndicateConfig(bundle !== undefined && isPlainObject(interpolated) ? { ...interpolated, bundled_references: bundle } : interpolated, label);
     const { variables: _stripped, ...clean } = valid;
     let config = clean;
+    // The script reads the bound variables (ADR 0137 item 6): the YAML's, then the caller's bindings, as {{token}} resolves them.
+    if (config.script) {
+        const yamlBound = isPlainObject(interpolated) && isPlainObject(interpolated.variables) ? interpolated.variables : {};
+        config = { ...config, script: { ...config.script, variables: { ...defaultBindings(), ...yamlBound, ...bindings } } };
+    }
     if (overrides) {
         config = applyOverrides(config, overrides);
     }

package/dist/lib/observability/supabaseSpanExporter.js

@@ -81,7 +81,8 @@ export function payloadDecision(policy, traceId, facts) {
 }
 // ── Span → row mapping (pure; tested offline) ───────────────────────────────
 const ROOT_PREFIX = 'Syndicate Execution: ';
-const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: )/;
+// A script's own spans (ADR 0137 item 16) carry its run, its calls' kinds, names, sequence and status, never an argument or a result.
+const EXPORTED_SPAN_NAMES = /^(llm\.request$|Syndicate Execution: |script\.(invoke|call) )/;
 function attrsOf(span) {
     return span.attributes;
 }

package/dist/lib/observability/tracer.d.ts

@@ -1,4 +1,4 @@
-import type { Span, SpanContext, SpanOptions } from '@opentelemetry/api';
+import type { Context, Span, SpanContext, SpanOptions } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
@@ -67,7 +67,7 @@ export declare function initializeTracing(): void;
  * the engine opens inside a turn goes through here or checks turnUntraced
  * itself.
  */
-export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions): Span;
+export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions, parent?: Context): Span;
 export interface TraceMetadata {
     syndicateName: string;
     bindings?: Record<string, any>;

package/dist/lib/observability/tracer.js

@@ -345,11 +345,11 @@ function nonRecordingSpan() {
  * the engine opens inside a turn goes through here or checks turnUntraced
  * itself.
  */
-export function startEngineSpan(tracerName, name, options) {
+export function startEngineSpan(tracerName, name, options, parent) {
     if (turnUntraced())
         return nonRecordingSpan();
     initializeTracing();
-    return trace.getTracer(tracerName).startSpan(name, options);
+    return trace.getTracer(tracerName).startSpan(name, options, parent);
 }
 /** Turn identity by trace id, so llm.request children can carry it too. */
 const turnContexts = new Map();

package/dist/lib/runtime/native/checkpoint.d.ts

@@ -15,7 +15,8 @@
  *   runner, unchanged, continues where the snapshot stood. runDurableTurn
  *   is runSyndicateTurn with that store and a sink.
  *
- * A STEP BOUNDARY is an append that carries function responses after which
+ * A STEP BOUNDARY is an append that carries function responses, or a
+ * script's journal event (ADR 0137 item 8), after which
  * every function call any session of the run holds has its response (calls
  * listed in their event's longRunningToolIds, which wait on a person, aside).
  * So a parent waiting on a delegated subagent is never at a boundary, the

package/dist/lib/runtime/native/checkpoint.js

@@ -15,7 +15,8 @@
  *   runner, unchanged, continues where the snapshot stood. runDurableTurn
  *   is runSyndicateTurn with that store and a sink.
  *
- * A STEP BOUNDARY is an append that carries function responses after which
+ * A STEP BOUNDARY is an append that carries function responses, or a
+ * script's journal event (ADR 0137 item 8), after which
  * every function call any session of the run holds has its response (calls
  * listed in their event's longRunningToolIds, which wait on a person, aside).
  * So a parent waiting on a delegated subagent is never at a boundary, the
@@ -75,6 +76,7 @@
  */
 import { createHash, randomUUID } from 'node:crypto';
 import { getFunctionCalls, getFunctionResponses, parseTurnEvents } from '../events.js';
+import { JOURNAL_EVERY_CALL, isJournalEvent } from '../../script/journal.js';
 import { InProcessSessionService } from '../sessions.js';
 import { runSyndicateTurn } from '../syndicateTurn.js';
 // ── Shapes ───────────────────────────────────────────────────────────────────
@@ -127,6 +129,8 @@ export function usableCheckpoint(cp, runId, parts) {
 /** Content compared as stored JSON. */
 const sameJson = (a, b) => JSON.stringify(a) === JSON.stringify(b);
 class CheckpointingStore {
+    /** A script run stores each call's journal event as it ends, and each is a step boundary (ADR 0137 item 8). */
+    [JOURNAL_EVERY_CALL] = true;
     inner;
     opts;
     openingParts;
@@ -250,7 +254,7 @@ class CheckpointingStore {
         if (stored.author !== 'user' && this.firstAgentSeq === undefined)
             this.firstAgentSeq = order;
         this.track(stored);
-        if (getFunctionResponses(stored).length > 0 && this.openCalls.size === 0)
+        if ((getFunctionResponses(stored).length > 0 || isJournalEvent(stored)) && this.openCalls.size === 0)
             await this.boundary();
         return stored;
     }

package/dist/lib/runtime/native/interrupts.js

@@ -163,6 +163,7 @@ import { approvalRequestOf, pendingApproval } from '../approvals.js';
 import { consentFrom, pendingConsent } from '../credentials.js';
 import { getFunctionCalls, getFunctionResponses } from '../events.js';
 import { ASK_USER, pendingQuestion } from '../questions.js';
+import { isJournalEvent, scriptPauseIn } from '../../script/journal.js';
 import { childAppName, entryAppName, legacyChild, legacyEntry } from './delegate.js';
 import { REQUEST_CONFIRMATION_CALL, REQUEST_CREDENTIAL_CALL, REQUEST_INPUT_CALL, isSegmentPrefix } from './history.js';
 import { isToolset } from './request.js';
@@ -516,6 +517,12 @@ async function conversationPause(key, child, name, id, depth, seen = new Set())
             ...(routed.consent ? { consent: { ...routed.consent, path } } : {}),
         };
     }
+    // A nested script syndicate's own pause (ADR 0137 item 15): its askUser or a gated tool() call, authored by the script.
+    const scripted = scriptPauseIn(child.events, id);
+    if (scripted) {
+        const path = scripted.asker === name ? [name] : down([scripted.asker]);
+        return { path, ...(scripted.approval ? { approval: { ...scripted.approval, path } } : {}), ...(scripted.question ? { question: { ...scripted.question, path } } : {}) };
+    }
     const approval = pendingApproval(child.events);
     if (approval && approval.agent && approval.agent !== 'user' && approval.agent !== name && wanted(approval.id)) {
         const path = down([approval.agent]);
@@ -543,8 +550,8 @@ async function conversationPause(key, child, name, id, depth, seen = new Set())
         ...(first.consent ? { consent: { ...first.consent, path } } : {}),
     };
 }
-/** A walk's session: its node events carry a dotted node path (`<workflow>.<node>`). */
-const isWalk = (session) => session.events.some((e) => typeof e.nodeInfo?.path === 'string' && e.nodeInfo.path.includes('.'));
+/** A walk's session: its node events carry a dotted node path (`<workflow>.<node>`); a script's journal events do not count. */
+const isWalk = (session) => session.events.some((e) => typeof e.nodeInfo?.path === 'string' && e.nodeInfo.path.includes('.') && !isJournalEvent(e));
 /**
  * The pause a nested workflow's walk holds in its child session (ADR 0111):
  * the workflow's own pause record, the last event, authored by the

package/dist/lib/runtime/nativeTurn.d.ts

@@ -18,7 +18,8 @@
  * feature (UnsupportedOnRuntimeError): a caller's `transformAgent` (it
  * transformed ADK agents, and ADK left in 1.0.0), and an `ask_user` tool on
  * a workflow's agent (the schema refuses it; a config that skipped
- * validation is refused here, ADR 0095). A workflow syndicate runs on the
+ * validation is refused here, ADR 0095), and a script or a `run_code`
+ * tool while MELCHIZEDEK_CODE_SANDBOX is off (CodeSandboxOffError, ADR 0137). A workflow syndicate runs on the
  * engine's scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an
  * approval resumes the call (lib/runtime/native/interrupts.ts), an answer
  * to a question resumes the agent that asked (lib/runtime/questions.ts, ADR

package/dist/lib/runtime/nativeTurn.js

@@ -18,7 +18,8 @@
  * feature (UnsupportedOnRuntimeError): a caller's `transformAgent` (it
  * transformed ADK agents, and ADK left in 1.0.0), and an `ask_user` tool on
  * a workflow's agent (the schema refuses it; a config that skipped
- * validation is refused here, ADR 0095). A workflow syndicate runs on the
+ * validation is refused here, ADR 0095), and a script or a `run_code`
+ * tool while MELCHIZEDEK_CODE_SANDBOX is off (CodeSandboxOffError, ADR 0137). A workflow syndicate runs on the
  * engine's scheduler (lib/workflow/turn.ts, ADR 0095). An answer to an
  * approval resumes the call (lib/runtime/native/interrupts.ts), an answer
  * to a question resumes the agent that asked (lib/runtime/questions.ts, ADR
@@ -30,6 +31,7 @@ import { createTurnEvent } from './events.js';
 import { runAgentLoop } from './native/agentLoop.js';
 import { ASK_USER } from './questions.js';
 import { unsupportedOnNative } from './runtimeFlag.js';
+import { refuseWithoutSandbox } from '../sandbox/sandbox.js';
 // ── What native refuses before a turn starts ─────────────────────────────────
 /**
  * Throws UnsupportedOnRuntimeError for a syndicate or a call the runtime
@@ -39,6 +41,8 @@ export function refuseOnNative(config, call) {
     const where = config.syndicate_name || config.orchestrator?.name || 'syndicate';
     if (call.transformAgent)
         throw unsupportedOnNative('transformAgent (it transformed ADK agents; the ADK runtime was removed in 1.0.0)', where);
+    // A script, or an agent listing run_code, runs code: only once the operator turned the sandbox on (ADR 0137 item 4).
+    refuseWithoutSandbox(config);
     if (call.isWorkflow) {
         // A pause inside an agent node cannot be resumed by the native walk (lib/workflow/resume.ts).
         const asking = [config.orchestrator, ...(config.subagents ?? [])].find((agent) => (agent?.tools ?? []).includes(ASK_USER));