melchizedek-agents 1.5.0 → 1.7.0

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

@@ -24,10 +24,18 @@ export type { MemoryEntry, MemoryIngestOptions, MemorySearchRequest, MemorySearc
 export type { TurnEvent } from './runtime/events.ts';
 export { approvalResponsePart, pendingApproval, APPROVAL_REQUEST } from './runtime/approvals.ts';
 export type { PendingApproval } from './runtime/approvals.ts';
-export type { DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
+export type { AgentBranch, DrainedRun, MessagePart, TurnUsage, RouteDecision, SyndicateTurnOptions, SyndicateTurnResult, TraceOptions, TurnEvents, TurnStage, } from './runtime/syndicateTurn.ts';
 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';
@@ -45,8 +45,17 @@ interface TraceStats {
     toolMs: number;
     llmCalls: number;
     models: Set<string>;
+    /** Each model's calls and tokens, input summed per call (what a provider bills), for `syndicate.usage` (ADR 0136). */
+    usage: Map<string, ModelUsage>;
     startedAt: number;
 }
+/** One model's share of a turn: what the ledger prices it from (model_pricing, ADR 0136). */
+export interface ModelUsage {
+    calls: number;
+    input: number;
+    output: number;
+    thinking: number;
+}
 /** Read-and-forget the stats for a finished trace. */
 export declare function takeTraceStats(traceId: string): TraceStats | undefined;
 /** Name of the agent of the nearest enclosing agent span (ADK's `invoke_agent`, the loop's `agent.invoke`), or null. */
@@ -58,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

@@ -194,7 +194,7 @@ const TRACE_STATS_TTL_MS = 60 * 60 * 1000;
 function statsFor(traceId) {
     let s = traceStats.get(traceId);
     if (!s) {
-        s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), startedAt: Date.now() };
+        s = { modelMs: 0, toolMs: 0, llmCalls: 0, models: new Set(), usage: new Map(), startedAt: Date.now() };
         traceStats.set(traceId, s);
         if (traceStats.size > 2_000) {
             const cutoff = Date.now() - TRACE_STATS_TTL_MS;
@@ -244,8 +244,19 @@ class SpanLineageProcessor {
             s.modelMs += spanDurationMs(span);
             s.llmCalls += 1;
             const model = span.attributes['llm.model'];
-            if (typeof model === 'string' && model)
+            if (typeof model === 'string' && model) {
                 s.models.add(model);
+                const tokens = (key) => {
+                    const v = span.attributes[key];
+                    return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : 0;
+                };
+                const u = s.usage.get(model) ?? { calls: 0, input: 0, output: 0, thinking: 0 };
+                u.calls += 1;
+                u.input += tokens('llm.tokens.input');
+                u.output += tokens('llm.tokens.output');
+                u.thinking += tokens('llm.tokens.thinking');
+                s.usage.set(model, u);
+            }
         }
         else if (isToolSpanName(span.name)) {
             statsFor(traceId).toolMs += spanDurationMs(span);
@@ -334,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();
@@ -546,6 +557,8 @@ export async function* traceAgentRun(stream, metadata) {
             span.setAttribute('syndicate.latency.tool_ms', Math.round(stats.toolMs));
             span.setAttribute('syndicate.llm_calls', stats.llmCalls);
             span.setAttribute('syndicate.models', [...stats.models].sort().join(','));
+            // The ledger prices the turn from this, per model (melchizedek_usage_cost, ADR 0136).
+            span.setAttribute('syndicate.usage', JSON.stringify(Object.fromEntries([...stats.usage].sort(([a], [b]) => a.localeCompare(b)))));
         }
         try {
             for (const [key, value] of Object.entries(metadata.onEnd?.() ?? {})) {

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

@@ -182,6 +182,12 @@ export interface AgentLoopContext extends Omit<ModelStepOptions, 'agent' | 'adap
      * its own delegations are filed below that path. Set by runChild only.
      */
     delegated?: boolean;
+    /**
+     * A delegated run's place in the turn: the agents from the caller at the
+     * top of the delegation down to this one, itself last (ADR 0135). Its own
+     * delegations extend it. Set by runChild only.
+     */
+    agentPath?: readonly string[];
 }
 /** How the run ended. */
 export type AgentLoopEndReason = 

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

@@ -394,9 +394,31 @@ export function runSubagent(agent, args, context, scope) {
 export function resumeSubagent(agent, answer, context, scope) {
     return runChild(agent, { role: 'user', parts: answer }, context, scope, true);
 }
+/**
+ * Where a delegated call's run sits (ADR 0135): the path below the caller's,
+ * `name` last, and the call's id. A top-level caller's path is its name.
+ */
+function branchOf(name, context, scope) {
+    const path = [...(scope.ctx.agentPath ?? [scope.caller]), name];
+    return { agent: name, path, ...(context.functionCallId ? { callId: context.functionCallId } : {}) };
+}
+/** Hands one event to the turn's observer (ADR 0135). An observer that throws never breaks the run. */
+function observe(sink, event, branch) {
+    if (!sink)
+        return;
+    try {
+        sink(event, branch);
+    }
+    catch {
+        /* the observer is the caller's; the turn goes on */
+    }
+}
 async function runChild(agent, content, context, scope, resuming) {
     const { ctx, signal } = scope;
     const { sessions } = ctx;
+    // With an observer the child streams, so its thinking and text reach it as partials (ADR 0135); partials are stored nowhere.
+    const sink = currentTurnControl()?.agentEvents;
+    const branch = branchOf(agent.name, context, scope);
     const session = await childSession(agent.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
@@ -409,9 +431,10 @@ async function runChild(agent, content, context, scope, resuming) {
         sessions,
         invocationId,
         userContent: content,
-        stream: false,
+        stream: sink !== undefined,
         // Its own delegations are filed below its path (childAppName, ADR 0111).
         delegated: true,
+        agentPath: branch.path,
         // ADK's AgentTool builds its sub-runner without the reflect-and-retry
         // plugins, so a subagent's own errors are not retried (ADR 0075).
         selfCorrection: new SelfCorrection({ model_errors: 0, tool_errors: 0 }),
@@ -438,6 +461,9 @@ async function runChild(agent, content, context, scope, resuming) {
             await loop.return(undefined);
             break;
         }
+        observe(sink, next.value, branch);
+        if (next.value.partial)
+            continue;
         recordState(next.value, context);
         last = next.value;
     }
@@ -469,6 +495,8 @@ export function resumeWorkflowSubagent(workflow, answer, context, scope) {
 }
 async function walkChild(workflow, userParts, context, scope, resuming) {
     const { ctx, signal } = scope;
+    const sink = currentTurnControl()?.agentEvents;
+    const branch = branchOf(workflow.name, context, scope);
     const session = await childSession(workflow.name, context, scope, resuming);
     if (signal?.aborted)
         return '';
@@ -503,6 +531,7 @@ async function walkChild(workflow, userParts, context, scope, resuming) {
             break;
         }
         const event = next.value;
+        observe(sink, event, branch);
         if (event.partial)
             continue;
         recordState(event, context);

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));

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

@@ -64,7 +64,10 @@ export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.ts';
 import type { PendingApproval } from './approvals.ts';
 export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.ts';
 export type { PendingApproval } from './approvals.ts';
-import type { TurnStopReason } from './turnControl.ts';
+import type { CodeRun } from '../tools/runCodeTool.ts';
+export type { CodeRun } from '../tools/runCodeTool.ts';
+import type { AgentBranch, TurnStopReason } from './turnControl.ts';
+export type { AgentBranch } from './turnControl.ts';
 /** One part of the user's message. Text is the common case; the genai part
  *  shapes (inlineData, fileData) pass through to the model unchanged. */
 export type MessagePart = {
@@ -86,6 +89,18 @@ export interface TurnEvents {
     onTextDelta?(delta: string): void;
     /** The text streamed so far was narration before a tool call: discard it. */
     onTextReset?(): void;
+    /**
+     * Every event of a delegated run, live, with where it runs (ADR 0135): a
+     * subagent's thinking and text as partial events, then each event it
+     * stores (its tool calls, their results, its answer), and a nested
+     * workflow's events; at any depth, parallel calls interleaved and told
+     * apart by `branch.callId` and `branch.path`. The answering agent's
+     * events stay on onEvent and onTextDelta, which this does not change.
+     * Passing it makes each delegated run stream; what the sessions store is
+     * the same. Fires for a syndicate with guards too: a delegated run's text
+     * is never the answer a guard rewrites. An observer that throws is ignored.
+     */
+    onAgentEvent?(event: TurnEvent, branch: AgentBranch): void;
     /** Diagnostic lines (the server prefixes and prints them). */
     log?(message: string): void;
     warn?(message: string): void;
@@ -209,8 +224,10 @@ export interface DrainedRun {
         code: string;
         message: string;
     }>;
+    /** Every run_code call that got its result, with the agent that made it (ADR 0137). */
+    codeRuns: CodeRun[];
 }
-export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow';
+export type TurnStage = 'classify' | 'dispatch' | 'delegate' | 'workflow' | 'script';
 export interface RouteDecision extends RouteResolution {
     /** `approval`: the turn resumed the route that asked for an approval (ADR 0028).
      *  `answer`: the message answered the route's open `ask_user` question.
@@ -259,6 +276,12 @@ export interface SyndicateTurnResult {
     usage: TurnUsage;
     /** Set when a control (cancel, deadline, step limit) stopped the turn. */
     stopReason?: TurnStopReason;
+    /**
+     * The run_code runs of agents whose YAML sets `run_code: { attach: true }`
+     * (ADR 0137 item 3), in order: the reply's `code_run` data parts. Absent
+     * when there are none.
+     */
+    codeRuns?: CodeRun[];
 }
 /** A turn's spend: model calls and the tokens the providers reported. */
 export interface TurnUsage {