melchizedek-agents 1.5.0 → 1.7.0

package/dist/lib/runtime/syndicateTurn.js

@@ -41,7 +41,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { DEFAULT_MAX_STEPS } from '../config.js';
-import { agentGates, compileEntrySpec, compileSpec, compileWorkflowSpec, workflowAgentSpecs } from '../compile.js';
+import { agentGates, compileEntrySpec, compileSpec, compileSubagentSpec, compileWorkflowSpec, withReasoning, workflowAgentSpecs } from '../compile.js';
 import { compileNative, compileNativeWorkflow, nativeAdapterFor } from '../compileNative.js';
 import { nativeMemory, refuseOnNative, runNativeAgent } from './nativeTurn.js';
 import { createTurnEvent, getFunctionCalls, getFunctionResponses } from './events.js';
@@ -77,6 +77,13 @@ import { INPUT_REQUEST } from '../workflowConfig.js';
 export { ASK_USER, pendingQuestion, questionAnswerPart } from './questions.js';
 export { approvalResponsePart, describeApproval, pendingApproval } from './approvals.js';
 import { RemoteA2AAgent, remoteContextId, remoteToolOutput } from '../a2a/remoteAgent.js';
+import { RUN_CODE } from '../tools/runCodeTool.js';
+import { resolveTools } from '../toolRegistry.js';
+import { capResult, createToolContext, toolOf } from '../tools/tool.js';
+import { isScriptSyndicate } from '../script/config.js';
+import { journalsEveryCall, openRun } from '../script/journal.js';
+import { toEngineAgent } from '../agentDialect.js';
+import { ScriptFatal, runScript } from '../script/run.js';
 import { createTurnControl, runWithTurnControl, stopCode, stopMessage } from './turnControl.js';
 const THOUGHTS_PREVIEW_CHARS = 600;
 const CLASSIFIER_PREAMBLE = `RECENT CONVERSATION, oldest first — context for your classification only. `
@@ -132,7 +139,10 @@ export async function drainAgentStream(stream, opts = {}) {
         eventCount: 0,
         inputRequests: [],
         nodeErrors: [],
+        codeRuns: [],
     };
+    /** run_code calls waiting for their result, by call id. */
+    const openCodeRuns = new Map();
     const grounding = newGroundingState();
     let groundingAnnounced = false;
     let streamed = false;
@@ -207,6 +217,8 @@ export async function drainAgentStream(stream, opts = {}) {
             if (!name)
                 continue;
             d.invokedToolNames.add(name);
+            if (name === RUN_CODE && call.id && typeof args.code === 'string')
+                openCodeRuns.set(call.id, { agent: e.author ?? 'unknown', code: args.code });
             if (opts.subagentNames?.has(name))
                 d.delegations.push(name);
             d.toolCalls.push({ agent: e.author ?? 'unknown', name, args });
@@ -221,6 +233,12 @@ export async function drainAgentStream(stream, opts = {}) {
             d.toolResponses++;
             if (name)
                 d.invokedToolNames.add(name);
+            const ran = name === RUN_CODE && r.id ? openCodeRuns.get(r.id) : undefined;
+            if (ran) {
+                openCodeRuns.delete(r.id);
+                const error = typeof content?.error === 'string' && content.error ? content.error : undefined;
+                d.codeRuns.push({ type: 'code_run', agent: ran.agent, code: ran.code, result: content?.result ?? null, ...(error ? { error } : {}) });
+            }
             const asString = typeof content === 'string' ? content : JSON.stringify(content);
             ev.log?.(`← Result: ${name || 'unknown'} — ${asString.length.toLocaleString()} chars`);
             // Only plain text results are relayable answers — a structured or
@@ -299,6 +317,10 @@ export async function runSyndicateTurn(opts) {
     });
     // A nested dispatch syndicate, wherever the turn reaches one, runs as a turn of its own under these controls (ADR 0120).
     control.nestedDispatch = (run) => runNestedDispatch(opts, control, runtime, run);
+    // Delegated runs report to the caller as they run (ADR 0135).
+    const onAgentEvent = opts.events?.onAgentEvent;
+    if (onAgentEvent)
+        control.agentEvents = (event, branch) => onAgentEvent.call(opts.events, event, branch);
     try {
         const run = () => runWithTurnControl(control, () => runTurnInner(opts, control, runtime));
         // A span a library opens through OpenTelemetry's own API (not the
@@ -403,7 +425,12 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         llmCalls: 0,
         usage: { llmCalls: 0, inputTokens: 0, outputTokens: 0, thinkingTokens: 0 },
     };
+    // run_code's attach (ADR 0137 item 3): the agents whose runs go on the reply.
+    const attaching = new Set([config.orchestrator, ...(config.subagents ?? [])].filter((a) => a?.run_code?.attach === true).map((a) => a.name));
     const finish = () => {
+        const attached = attaching.size ? (result.answer?.codeRuns ?? []).filter((run) => attaching.has(run.agent)) : [];
+        if (attached.length)
+            result.codeRuns = attached;
         result.llmCalls = control.llmCalls;
         result.usage = {
             llmCalls: control.llmCalls,
@@ -713,7 +740,7 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 taskId: trace.taskId,
                 stage: params.stage,
                 configHash: trace.configHash,
-                attributes: trace.attributes,
+                attributes: params.traceAttributes ? { ...trace.attributes, ...params.traceAttributes } : trace.attributes,
                 onSpanStart: trace.onSpanStart,
                 traceparent: trace.traceparent,
                 onEnd: () => ({
@@ -723,12 +750,30 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
                 }),
             });
         }
+        // A script's agent() call reports live, as a delegated run does (ADR 0135); an observer that throws is ignored.
+        const sink = params.branch ? control.agentEvents : undefined;
+        if (sink && params.branch) {
+            const source = stream;
+            const branch = params.branch;
+            stream = (async function* tap() {
+                for await (const event of source) {
+                    try {
+                        sink(event, branch);
+                    }
+                    catch {
+                        // ignored
+                    }
+                    yield event;
+                }
+            })();
+        }
         try {
+            const quiet = params.quiet ?? params.stage === 'classify';
             return await drainAgentStream(stream, {
-                events: params.stage === 'classify' ? { ...ev, onEvent: undefined } : ev,
+                events: quiet ? { ...ev, onEvent: undefined } : ev,
                 publishToolStatus: params.publishToolStatus,
                 subagentNames,
-                streamText: params.stage !== 'classify' && !guarded,
+                streamText: !quiet && !guarded,
                 errorPolicy: params.errorPolicy,
             });
         }
@@ -890,12 +935,348 @@ async function runTurnInner(opts, control, _runtime, nestedTurn) {
         }
         return { answer };
     };
+    /**
+     * A script syndicate's turn (ADR 0137 Part B). The host side of
+     * lib/script/run.ts: what agent() and tool() do, where the journal goes,
+     * and what the conversation keeps. Returns the finished result when the
+     * turn ends here (paused, waiting for an approval, or failed); otherwise
+     * result.text and result.answer are set and the guards run on them.
+     *
+     * agent(name, input, opts) runs a declared agent on its own throwaway
+     * session seeing only `input` (text, or JSON sent as its text; null sends
+     * the run's message), as a workflow node does; with `conversation: true`
+     * it runs as a dispatch route runs, on the conversation through the
+     * projection, its input and answer stored there, its reply streamed.
+     * `model` (one of script.models), `reasoning` and `temperature` change the
+     * call's agent, compiled once per turn per combination, every pairing
+     * checked before the run starts (item 7). It returns the parsed JSON when
+     * the agent has an output schema, else its text; a run that failed throws
+     * into the script, which may catch it (fail-static). A `yaml_reference` to
+     * a workflow, dispatch or script syndicate runs as a turn or walk of its
+     * own on a throwaway lane, and a pause inside it fails the turn by name
+     * (item 12). Its events reach events.onAgentEvent with the branch path
+     * [<script>, <agent>] (ADR 0135).
+     */
+    const runScriptTurn = async () => {
+        const script = config.script;
+        const scriptName = config.syndicate_name || config.orchestrator.name;
+        const key = { appName, userId, sessionId };
+        const before = existing?.events ?? [];
+        const invocationId = `e-${randomUUID()}`;
+        const appendHere = async (event) => {
+            const session = await sessionService.get(key);
+            if (!session)
+                throw new Error(`Session not found: ${sessionId} (appName=${appName}, userId=${userId})`);
+            await sessionService.append(session, event);
+        };
+        let userRecorded = false;
+        /** The person's message, once, unless a conversation call stored it. */
+        const recordUser = async () => {
+            if (userRecorded)
+                return;
+            userRecorded = true;
+            await appendHere(createTurnEvent({ invocationId, author: 'user', content: { role: 'user', parts } }));
+        };
+        // A durable run (ADR 0113) stores the message first and each call as it ends, so a restored checkpoint holds the
+        // run's journal; the restore answers that first append with the stored events, so the run is read after it.
+        const durable = journalsEveryCall(sessionService);
+        if (durable)
+            await recordUser();
+        const stored = durable ? ((await sessionService.get(key))?.events ?? before) : before;
+        const found = openRun(stored, scriptName);
+        // A run left mid-way resumes only under the durable store, whose retry is the same message; elsewhere the message is new.
+        const open = found && (found.state === 'paused' || durable) ? found : undefined;
+        const declared = new Map();
+        declared.set(config.orchestrator.name, { description: '', ...config.orchestrator });
+        for (const sub of config.subagents ?? [])
+            declared.set(sub.name, sub);
+        const models = new Set(script.models ?? []);
+        const allowedTools = new Set(script.tools ?? []);
+        const gatedTools = new Set(script.require_approval ?? []);
+        // Every agent × model pairing a call may ask for, checked before anything runs (item 7).
+        for (const model of models) {
+            try {
+                (compileOpts.resolveModel ?? ((m) => m))(model);
+                for (const yaml of declared.values()) {
+                    if (yaml.yaml_reference || yaml.a2a_agent_url)
+                        continue;
+                    withReasoning(toEngineAgent(yaml), model);
+                }
+            }
+            catch (err) {
+                result.status = 'failed';
+                result.failedStage = 'script';
+                result.error = { code: 'SCRIPT_MODEL_INVALID', message: `script.models: ${model}: ${err instanceof Error ? err.message : String(err)}` };
+                return finish();
+            }
+        }
+        // What the open run waits on decides what this message is (lib/script/journal.ts openRun).
+        let resume;
+        if (open?.state === 'paused' && open.pause?.kind === 'approval') {
+            const waiting = pendingApproval(before);
+            // A message that is not the decision repeats the request; nothing runs, as a workflow's gated node answers it.
+            if (!decision)
+                return waiting ? pause(waiting) : undefined;
+            resume = { run: open.pin.run, entries: open.entries, decision: { approved: decision.approved } };
+        }
+        else if (open?.state === 'paused') {
+            resume = { run: open.pin.run, entries: open.entries, answer: messageText };
+        }
+        else if (open) {
+            resume = { run: open.pin.run, entries: open.entries };
+        }
+        const runMessage = open ? open.pin.message : messageText;
+        const transcript = open ? open.pin.transcript : renderTranscriptDigest(before);
+        const compiled = new Map();
+        const aggregate = emptyRun();
+        let conversationAnswer;
+        const textOf = (value) => (value === null || value === undefined ? runMessage : typeof value === 'string' ? value : JSON.stringify(value));
+        const unfenced = (raw) => {
+            const fence = raw.trim().match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+            return fence ? fence[1].trim() : raw.trim();
+        };
+        const merge = (run) => {
+            aggregate.toolResultTexts.push(...run.toolResultTexts);
+            for (const name of run.invokedToolNames)
+                aggregate.invokedToolNames.add(name);
+            for (const name of run.agents)
+                aggregate.agents.add(name);
+            aggregate.toolCalls.push(...run.toolCalls);
+            aggregate.toolResponses += run.toolResponses;
+            aggregate.delegations.push(...run.delegations);
+            aggregate.codeRuns.push(...run.codeRuns);
+            aggregate.eventCount += run.eventCount;
+            aggregate.tokens.input = Math.max(aggregate.tokens.input, run.tokens.input);
+            aggregate.tokens.output += run.tokens.output;
+            aggregate.tokens.thinking += run.tokens.thinking;
+            if (run.lastToolResultText)
+                aggregate.lastToolResultText = run.lastToolResultText;
+            if (run.grounding) {
+                aggregate.grounding ??= { queries: [], sources: [] };
+                aggregate.grounding.queries.push(...run.grounding.queries);
+                aggregate.grounding.sources.push(...run.grounding.sources);
+            }
+        };
+        const stopped = () => {
+            if (control.stopReason)
+                throw new ScriptFatal(stopCode(control.stopReason), stopMessage(control.stopReason, control));
+        };
+        const OPTIONS = new Set(['model', 'reasoning', 'temperature', 'sampling', 'conversation']);
+        /** A called agent's failed run, thrown into the script; uncaught, the turn fails with the run's own code. */
+        const runFailed = (name, error) => {
+            const err = new Error(`${name} failed [${error.code}]: ${error.message}`);
+            err.name = 'AgentRunError';
+            return err;
+        };
+        const pausedInside = (name) => new ScriptFatal('PAUSE_INSIDE_AGENT', `${name} paused for a person inside an agent() call, which a script cannot resume in this version (ADR 0137 item 12); pause in the script with askUser.`);
+        /** A throwaway lane for one call: it sees only its input, and its journal entry is its record. */
+        const lane = async (site) => {
+            const sid = `${sessionId}::script:${site.run}.${site.seq}`;
+            const sessions = new InProcessSessionService();
+            await sessions.create({ appName, userId, sessionId: sid });
+            return { sid, sessions };
+        };
+        const outcome = await runScript({ source: open ? open.pin.source : script.source, message: runMessage, transcript, variables: script.variables ?? {}, ...(resume ? { resume } : {}) }, {
+            script: scriptName,
+            invocationId,
+            sessionId,
+            signal: control.signal,
+            journalEveryCall: durable,
+            gated: (name) => gatedTools.has(name),
+            log: (text) => {
+                ev.log?.(`⇢ ${scriptName}: ${text.length.toLocaleString()} chars of progress`);
+                ev.onProgress?.(text);
+            },
+            append: appendHere,
+            beforePause: recordUser,
+            agent: async (name, input, o, site) => {
+                stopped();
+                const yaml = declared.get(name);
+                if (!yaml)
+                    throw new Error(`agent: '${name}' is not an agent of this syndicate (declared: ${[...declared.keys()].join(', ')})`);
+                for (const k of Object.keys(o))
+                    if (!OPTIONS.has(k))
+                        throw new Error(`agent(${name}): unknown option '${k}' (model, reasoning, temperature or sampling.temperature, conversation)`);
+                const sampling = o.sampling;
+                if (sampling !== undefined && (typeof sampling !== 'object' || sampling === null || Object.keys(sampling).some((k) => k !== 'temperature'))) {
+                    throw new Error(`agent(${name}): sampling takes temperature only`);
+                }
+                const model = o.model;
+                if (model !== undefined && (typeof model !== 'string' || (!models.has(model) && model !== yaml.model))) {
+                    throw new Error(`agent(${name}): the model '${String(model)}' is not in script.models (${[...models].join(', ') || 'none listed'})`);
+                }
+                const temperature = o.temperature ?? sampling?.temperature;
+                if (temperature !== undefined && typeof temperature !== 'number')
+                    throw new Error(`agent(${name}): temperature must be a number`);
+                const reasoning = o.reasoning;
+                const conversation = o.conversation === true;
+                const nested = !!yaml.yaml_reference || !!yaml.a2a_agent_url;
+                if (nested && (model !== undefined || temperature !== undefined || reasoning !== undefined)) {
+                    throw new Error(`agent(${name}): a nested or remote agent sets its own model, reasoning and temperature`);
+                }
+                if (yaml.a2a_agent_url) {
+                    const remote = await runRemoteRoute(name, yaml.a2a_agent_url, textOf(input), sessionId, control, ev);
+                    stopped();
+                    merge(remote);
+                    if (remote.error)
+                        throw runFailed(name, remote.error);
+                    return remote.text;
+                }
+                const cacheKey = JSON.stringify([name, model ?? null, reasoning ?? null, temperature ?? null]);
+                let entry = compiled.get(cacheKey);
+                if (!entry) {
+                    entry = (async () => {
+                        let spec;
+                        if (yaml.yaml_reference) {
+                            const built = await compileEntrySpec(yaml, compileOpts);
+                            if (built.kind === 'workflow')
+                                return { agent: nativeWorkflowAgent(built.workflow, compileOpts), outputSchema: false };
+                            if (built.kind === 'dispatch')
+                                return { own: built.dispatch };
+                            spec = built.spec;
+                        }
+                        else {
+                            spec = await compileSubagentSpec({ ...yaml, ...(typeof model === 'string' ? { model } : {}) }, compileOpts);
+                        }
+                        if (reasoning !== undefined)
+                            spec.generateContentConfig = { ...spec.generateContentConfig, ...withReasoning({ name, reasoning, generateContentConfig: {} }, spec.modelId) };
+                        if (typeof temperature === 'number')
+                            spec.generateContentConfig = { ...spec.generateContentConfig, temperature };
+                        return { agent: nativeOf(spec), outputSchema: !!spec.outputSchema };
+                    })();
+                    compiled.set(cacheKey, entry);
+                }
+                const built = await entry;
+                const branch = { agent: name, path: [scriptName, name], callId: `${site.run}.${site.seq}` };
+                const traceAttributes = { 'script.name': scriptName, 'script.run': site.run, 'script.call.seq': site.seq };
+                // A nested dispatch or script syndicate: its own turn, on a throwaway conversation (ADR 0120, item 15).
+                if ('own' in built) {
+                    if (conversation)
+                        throw new Error(`agent(${name}): conversation: true applies to an agent; ${yaml.yaml_reference} runs as a syndicate of its own`);
+                    if (!control.nestedDispatch)
+                        throw new Error(`agent(${name}): nested syndicates need the turn's controls`);
+                    const { sid, sessions } = await lane(site);
+                    const end = await control.nestedDispatch({ config: built.own.config, compile: built.own.compile, name, sessions, appName, userId, sessionId: sid, parts: [{ text: textOf(input) }] });
+                    stopped();
+                    aggregate.agents.add(name);
+                    if (end.status === 'input-required')
+                        throw pausedInside(name);
+                    if (end.status === 'failed' || end.status === 'canceled')
+                        throw runFailed(name, end.error ?? { code: 'ROUTE_FAILED', message: `${name} failed.` });
+                    return end.text;
+                }
+                const { agent, outputSchema } = built;
+                const workflow = agent.runtime === 'native-workflow';
+                if (workflow && conversation)
+                    throw new Error(`agent(${name}): conversation: true applies to an agent; ${yaml.yaml_reference} runs as a workflow of its own`);
+                const userParts = conversation && input === null && !open ? parts : [{ text: textOf(input) }];
+                let sid = sessionId;
+                let sessions;
+                if (conversation) {
+                    // As a dispatch route answers: in the conversation, read through the projection (lib/session/transcript.ts).
+                    sessions = new ProjectedSessionService(sessionService, name, {});
+                    userRecorded = true;
+                }
+                else {
+                    ({ sid, sessions } = await lane(site));
+                }
+                let drained;
+                try {
+                    drained = await runAgent({ agent, sid, userParts, sessions, stage: 'script', publishToolStatus: true, quiet: !conversation, branch, traceAttributes, ...(workflow ? { errorPolicy: 'collect' } : {}) });
+                }
+                catch (err) {
+                    if (control.stopReason)
+                        throw new ScriptFatal(stopCode(control.stopReason), stopMessage(control.stopReason, control));
+                    // A workflow node that gave up ends its walk by throwing, as at the top.
+                    throw runFailed(name, { code: err instanceof NodeRunLimitError ? NODE_RUN_LIMIT : 'NODE_FAILED', message: err.message });
+                }
+                stopped();
+                merge(drained);
+                if (drained.error)
+                    throw runFailed(name, drained.error);
+                // A pause inside the call (a gate, a question, a consent request) cannot be replayed in this version (item 12).
+                const after = (await sessions.get({ appName, userId, sessionId: sid }))?.events ?? [];
+                if (drained.inputRequests.length || (!conversation && (pendingApproval(after) || pendingConsent(after))))
+                    throw pausedInside(name);
+                if (conversation)
+                    conversationAnswer = drained.text;
+                if (!outputSchema)
+                    return drained.text;
+                try {
+                    return JSON.parse(unfenced(drained.text));
+                }
+                catch {
+                    throw new Error(`${name} answered ${drained.text.trim().length} characters that are not the JSON its output schema asks for`);
+                }
+            },
+            tool: async (name, args) => {
+                stopped();
+                if (!allowedTools.has(name))
+                    throw new Error(`tool: '${name}' is not in script.tools (${[...allowedTools].join(', ') || 'none listed'})`);
+                const tool = toolOf(resolveTools([name], (n) => ev.warn?.(`Unknown tool '${n}' in script.tools`))[0]);
+                if (!tool)
+                    throw new Error(`tool: '${name}' is not a registry tool a script can run (a provider-side or instruction tool runs inside a model call)`);
+                if (tool.longRunning)
+                    throw new Error(`tool: '${name}' waits for a person; a script asks with askUser`);
+                ev.onProgress?.(`Invoking tool: ${name}`);
+                const ctx = createToolContext({ invocationId, agentName: scriptName, appName, userId, sessionId, signal: control.signal, ...(credentialStore ? { credentials: credentialStore } : {}) });
+                const out = await tool.execute((args && typeof args === 'object' ? args : {}), ctx);
+                stopped();
+                if (typeof out === 'string' && out.trim())
+                    aggregate.toolResultTexts.push(out.trim());
+                aggregate.invokedToolNames.add(name);
+                return capResult(out);
+            },
+        });
+        result.answer = aggregate;
+        if (outcome.logs)
+            ev.log?.(`⇢ ${scriptName}: console output, ${outcome.logs.length.toLocaleString()} chars`);
+        if (control.stopReason)
+            return finish();
+        if (outcome.status === 'failed') {
+            result.status = 'failed';
+            result.failedStage = 'script';
+            // An agent's failed run the script did not catch fails the turn as that run did, as a dispatch route's failure does.
+            const uncaught = outcome.error.code === 'SCRIPT_ERROR' ? /^AgentRunError: (\S+) failed \[([A-Za-z0-9_]+)\]: ([\s\S]*)$/.exec(outcome.error.message) : null;
+            result.error = uncaught ? { code: uncaught[2], message: uncaught[3] } : outcome.error;
+            ev.warn?.(`Script ${scriptName} failed [${outcome.error.code}]: ${outcome.error.message}`);
+            return finish();
+        }
+        if (outcome.status === 'paused')
+            return question(outcome.input);
+        if (outcome.status === 'approval')
+            return pause(outcome.approval);
+        const value = outcome.value;
+        result.text = typeof value === 'string' ? value : value === null || value === undefined ? '' : JSON.stringify(value, null, 2);
+        if (!result.text) {
+            ev.warn?.(`Script ${scriptName} returned no answer.`);
+            result.text = `${scriptName} returned no answer.`;
+        }
+        aggregate.text = result.text;
+        // The conversation keeps the exchange, as for any route: the message, and the answer unless a conversation call already stored it.
+        await recordUser();
+        if (result.text !== conversationAnswer) {
+            await appendHere(createTurnEvent({ invocationId, author: scriptName, content: { role: 'model', parts: [{ text: result.text }] } }));
+        }
+        return undefined;
+    };
     // While a route's walk waits on a gated call (ADR 0119), a message that is not its decision repeats the request: the
     // walk cannot move past the waiting node, so nothing is stored and nothing runs, as a workflow turn answers it.
     if (!decision && routePaused?.approval)
         return pause(routePaused.approval);
     let answer;
-    if (isDispatchSyndicate(config)) {
+    if (isScriptSyndicate(config)) {
+        // ══ SCRIPT ═══════════════════════════════════════════════════════════
+        // The orchestration is code (lib/script/, ADR 0137): one module in the
+        // sandbox calls the agents, the allowed tools and the person as
+        // functions, every call journaled here; a paused run resumes by
+        // replaying the journal on the source it pinned.
+        const ran = await runScriptTurn();
+        if (ran)
+            return ran;
+        answer = result.answer;
+    }
+    else if (isDispatchSyndicate(config)) {
         // ══ PLAN ═════════════════════════════════════════════════════════════
         // Deterministic overrides first: when the message itself decides the
         // route there is nothing to classify, and the classifier call is skipped.
@@ -1239,6 +1620,7 @@ function emptyRun(error) {
     return {
         inputRequests: [],
         nodeErrors: [],
+        codeRuns: [],
         text: '',
         lastToolResultText: '',
         toolResultTexts: [],

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

@@ -22,6 +22,7 @@
  *   to their provider SDK and a cancel or a deadline stops the HTTP call in
  *   flight, not just the loop around it.
  */
+import type { TurnEvent } from './events.ts';
 /** Why a turn was stopped before it finished on its own. */
 export type TurnStopReason = 'canceled' | 'deadline' | 'step_limit';
 export interface TurnControl {
@@ -53,6 +54,32 @@ export interface TurnControl {
      * which sit below the turn runner and cannot import it.
      */
     nestedDispatch?: (run: NestedDispatchRun) => Promise<NestedDispatchEnd>;
+    /**
+     * Receives every event a delegated run yields, as it yields it, with
+     * where that run sits (ADR 0135): set by the turn runner when the caller
+     * passed `events.onAgentEvent`, read where a delegated call runs
+     * (lib/runtime/native/delegate.ts), which sits below the turn runner.
+     * Its presence also makes each delegated run stream, so its thinking and
+     * text arrive as partial events.
+     */
+    agentEvents?: (event: TurnEvent, branch: AgentBranch) => void;
+}
+/**
+ * Where a delegated run sits in the turn (ADR 0135): the agent, the
+ * delegation path from the agent that took the call down to it, and the id
+ * of the call that started it.
+ */
+export interface AgentBranch {
+    /** The delegated agent: a subagent, or a nested workflow's name for an event its walk yielded. */
+    agent: string;
+    /**
+     * The agents from the caller at the top of the delegation down to this
+     * one, itself last: `['Boss', 'Researcher']`, `['Boss', 'Researcher',
+     * 'Fetcher']`. Below a nested workflow it starts again at the node's agent.
+     */
+    path: readonly string[];
+    /** The id of the function call, in the caller's event, that started this run: what pairs it with the caller's tool call. */
+    callId?: string;
 }
 /** One run of a nested dispatch syndicate (ADR 0120): what it is, where its conversation is filed, and the message. */
 export interface NestedDispatchRun {

package/dist/lib/sandbox/sandbox.d.ts

@@ -0,0 +1,121 @@
+/**
+ * lib/sandbox/sandbox.ts — run JavaScript the engine did not write, where
+ * it can reach nothing but what it is handed (ADR 0137 Part A).
+ *
+ * WHY this exists:
+ *   Two features need code to run on this host: the `run_code` tool, whose
+ *   code a model writes (lib/tools/runCodeTool.ts), and a syndicate's
+ *   `script:`, whose code an operator deploys (lib/script/). ADR 0033 refused
+ *   local execution because ADK's executors ran code on the host or needed a
+ *   Docker daemon. This is neither: QuickJS compiled to wasm, with no host
+ *   reach of any kind, on a worker thread (lib/sandbox/worker.ts) so a run's
+ *   compute never stalls the turns, streams and MCP calls of the process.
+ *
+ * WHAT A RUN GETS: a fresh runtime in a fresh Worker, a memory limit
+ * (default 64 MB), a stack limit, and a CPU budget (default 5 s) measured
+ * only while the code computes. Values cross as JSON both ways. The code is
+ * a module whose default export is called with the input (`mode: 'input'`)
+ * or with an API object (`mode: 'api'`): the caller's values, its host
+ * functions as async functions, and `parallel`.
+ *
+ * THE STOPS: the interrupt handler inside the worker stops the code at its
+ * CPU budget; a watchdog here terminates the worker when it computed past
+ * the budget without answering; the caller's signal terminates it; and a
+ * host function may throw SandboxHalt to end the run on purpose (a script
+ * pausing for a person). Runs are capped by a small pool, so the memory
+ * they hold is bounded: MELCHIZEDEK_CODE_SANDBOX_WORKERS, default 16.
+ *
+ * THE POSTURE: nothing runs unless the operator set
+ * MELCHIZEDEK_CODE_SANDBOX=on (codeSandboxEnabled). The sandbox grants no
+ * power the code's caller lacks, so the switch is a posture, not a
+ * boundary: a deployment that never meant to run code does not start
+ * because a YAML changed (ADR 0137 item 4, as ADR 0132 gates stdio MCP).
+ */
+/** The operator's switch for running code (ADR 0137 item 4). */
+export declare const CODE_SANDBOX_ENV = "MELCHIZEDEK_CODE_SANDBOX";
+/** True when the operator turned the sandbox on: MELCHIZEDEK_CODE_SANDBOX=on (or true, 1). */
+export declare function codeSandboxEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** The message a refusal carries when the switch is off. */
+export declare function codeSandboxOffMessage(what: string): string;
+/** A syndicate that needs the sandbox, refused while it is off: it names the variable that turns it on. */
+export declare class CodeSandboxOffError extends Error {
+    readonly code = "CODE_SANDBOX_OFF";
+    constructor(what: string);
+}
+/** What in a syndicate runs code: its `script:`, and each agent that lists `run_code`. */
+export declare function codeUsersOf(config: {
+    syndicate_name?: string;
+    script?: unknown;
+    orchestrator?: {
+        name?: string;
+        tools?: string[];
+    };
+    subagents?: Array<{
+        name?: string;
+        tools?: string[];
+    }>;
+}): string[];
+/** Throws CodeSandboxOffError when `config` runs code and the operator has not turned the sandbox on. */
+export declare function refuseWithoutSandbox(config: Parameters<typeof codeUsersOf>[0], env?: NodeJS.ProcessEnv): void;
+export interface SandboxLimits {
+    /** Heap the runtime may allocate. Default 64 MB. */
+    memoryBytes: number;
+    /** Stack the runtime may use. Default 1 MB. */
+    stackBytes: number;
+    /** Compute the code may spend, waits on the host not counted. Default 5,000 ms. */
+    cpuMs: number;
+    /** console output kept. Default 20,000 characters. */
+    maxLogChars: number;
+    /** The result's JSON text a run may return. Default 1,000,000 characters. */
+    maxResultChars: number;
+    /** The most calls `parallel` runs at once. Default 4 (32 at most). */
+    maxParallel: number;
+}
+export declare const DEFAULT_SANDBOX_LIMITS: Readonly<SandboxLimits>;
+/** What can end a run other than its own return. */
+export type SandboxErrorCode = 'CODE_ERROR' | 'CPU_LIMIT' | 'MEMORY_LIMIT' | 'STACK_LIMIT' | 'RESULT_TOO_LARGE' | 'CANCELED' | 'HALTED' | 'SANDBOX_CRASHED';
+/** A host function in `mode: 'api'`: its arguments as the code passed them, already parsed from JSON. */
+export type HostFunction = (args: unknown[]) => Promise<unknown> | unknown;
+export interface SandboxRunOptions {
+    /** A JavaScript module whose default export the run calls. */
+    source: string;
+    /** `input`: the export gets `value`. `api`: an object of `value`'s keys, the host functions and `parallel`. Default `input`. */
+    mode?: 'input' | 'api';
+    /** JSON-serializable. */
+    value?: unknown;
+    /** The host functions the code may call (`mode: 'api'`). */
+    functions?: Record<string, HostFunction>;
+    limits?: Partial<SandboxLimits>;
+    /** Terminates the run when aborted. */
+    signal?: AbortSignal;
+}
+export interface SandboxResult {
+    ok: boolean;
+    /** The export's return value, parsed from JSON (`undefined` came back as null). */
+    result?: unknown;
+    error?: {
+        code: SandboxErrorCode;
+        message: string;
+    };
+    /** What a host function threw as SandboxHalt, when the run was halted. */
+    halt?: SandboxHalt;
+    /** console output, bounded by maxLogChars. */
+    logs: string;
+    logsTruncated: boolean;
+    /** Compute the run spent inside the interpreter. */
+    cpuMs: number;
+}
+/**
+ * Thrown by a host function to end the run on purpose: the worker is
+ * terminated, nothing more of the code runs, and the result carries this
+ * error as `halt`. A script pausing for a person halts (lib/script/).
+ */
+export declare class SandboxHalt extends Error {
+    readonly detail: unknown;
+    constructor(message: string, detail?: unknown);
+}
+/**
+ * Run `source` in a fresh sandbox. Never throws for anything the code does:
+ * a thrown error, a limit, a cancel or a halt come back in the result.
+ */
+export declare function runInSandbox(opts: SandboxRunOptions): Promise<SandboxResult>;