melchizedek-agents 1.6.0 → 1.7.0

package/dist/lib/script/run.js

@@ -0,0 +1,364 @@
+/**
+ * lib/script/run.ts — one run of a syndicate's `script:` (ADR 0137 Part B):
+ * the script in the sandbox, its calls journaled, a paused or interrupted
+ * run resumed by replaying them.
+ *
+ * WHAT THE SCRIPT IS PASSED (item 6): `message`, `transcript` and
+ * `variables`, and the functions `agent`, `tool`, `askUser`, `now`,
+ * `random`, `log`, plus the sandbox's `parallel`. Nothing else reaches it.
+ * The host (lib/runtime/syndicateTurn.ts) supplies what `agent` and `tool`
+ * do; this module owns the journal, the replay, the pauses and the spans.
+ *
+ * REPLAY (item 9). A paused run's next message runs the script again from
+ * the top, on the source, message and transcript the run pinned. Each call
+ * is answered from the journal while one is recorded for it: a call is
+ * matched on its kind, its name and the hash of its arguments, the first
+ * unconsumed entry that matches, so concurrency under `parallel` (whose
+ * calls start in an order that depends on what finished first) replays the
+ * same. The open pause takes the person's answer; the calls after it run
+ * live. A run that ends with recorded calls it never made again diverged:
+ * it fails SCRIPT_DIVERGED, naming the first. Replayed calls are never
+ * charged again, open no span, and log() lines are not repeated while the
+ * run replays.
+ *
+ * THE PAUSES (items 8 and 10). A live askUser, and a tool() call to a tool
+ * in `script.require_approval`, let the calls already in flight settle,
+ * store the run's journal and the pause, then halt the sandbox; a call
+ * started after it waits forever and dies with the run, so a second pause
+ * is reached only once the first is answered. A question's answer is the
+ * next message (a JSON reply to a question with a schema is parsed, plain
+ * text passes as is, as an ask_user node's). An approval's answer is the
+ * decision: approved, the pinned arguments run; refused, the script gets
+ * `{ error }`, as a refused tool node's output is.
+ *
+ * WHEN THE JOURNAL IS STORED. Only a paused run reads it, so by default it
+ * is stored with the pause and a run that finishes stores none (on the
+ * Supabase store every append rewrites the session's events). A durable
+ * run's store (JOURNAL_EVERY_CALL, lib/runtime/native/checkpoint.ts) takes
+ * each event as its call ends, the first carrying the pin, and treats each
+ * as a checkpoint boundary, so a worker killed mid-script resumes from its
+ * last call. A resumed run that ends, and a durable run that finishes,
+ * store an `end` marker.
+ *
+ * THE SPANS (item 16). `script.invoke <name>` around the run and
+ * `script.call <kind>:<name>` around each live call, in their own trace,
+ * with no argument and no result on them; each agent() call's own turn
+ * span carries `script.run` and `script.call.seq` (the host adds them), so
+ * a trace view pairs them.
+ */
+import { randomUUID } from 'node:crypto';
+import { ROOT_CONTEXT, SpanStatusCode, trace } from '@opentelemetry/api';
+import { getFunctionCalls } from '../runtime/events.js';
+import { approvalRequestOf } from '../runtime/approvals.js';
+import { RUNTIME_SPAN_SCOPE } from '../observability/lineage.js';
+import { startEngineSpan } from '../observability/tracer.js';
+import { SandboxHalt, runInSandbox } from '../sandbox/sandbox.js';
+import { APPROVAL_TEXTS } from '../tools/tool.js';
+import { inputRequestFrom } from '../workflowConfig.js';
+import { approvalEvent, callEvent, callHash, endEvent, pauseEvent, sourceHash } from './journal.js';
+// A paused run's journal, for a client that shows it (melch-app's journal view): the reader and its shapes.
+export { openRun, scriptPauseIn, SCRIPT_CALL, SCRIPT_PAUSE, SCRIPT_RUN } from './journal.js';
+/** The most calls one run may journal (item 13), as a walk has NODE_RUN_LIMIT. */
+export const SCRIPT_CALL_LIMIT = 1_000;
+/** Fatal: thrown by a host function to fail the turn with a code. */
+export class ScriptFatal extends SandboxHalt {
+    code;
+    constructor(code, message) {
+        super(message, { code });
+        this.code = code;
+    }
+}
+const never = () => new Promise(() => { });
+function replayed(outcome) {
+    if ('error' in outcome) {
+        const err = new Error(outcome.error.message);
+        err.name = outcome.error.name;
+        throw err;
+    }
+    return outcome.value;
+}
+function describe(entry) {
+    return `${entry.kind}(${JSON.stringify(entry.name)}) recorded as call ${entry.seq}`;
+}
+/** A question's reply: parsed when the question declared a schema and the reply is JSON, else the text. */
+function replyOf(answer, schema) {
+    if (!schema)
+        return answer;
+    const text = answer.trim();
+    if (!/^[[{"]|^-?\d|^(true|false|null)$/.test(text))
+        return answer;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return answer;
+    }
+}
+export async function runScript(input, host) {
+    const run = input.resume?.run ?? `r-${randomUUID()}`;
+    const pending = input.resume ? input.resume.entries.filter((e) => e.outcome || e.pause) : [];
+    let nextSeq = (input.resume?.entries ?? []).reduce((max, e) => Math.max(max, e.seq), 0) + 1;
+    const limit = input.callLimit ?? SCRIPT_CALL_LIMIT;
+    const inflight = new Set();
+    const askedIds = new Set();
+    const pin = { run, source: input.source, source_hash: sourceHash(input.source), message: input.message, transcript: input.transcript };
+    // A run stored call by call pins itself on its first event; a resumed one already did.
+    let pinStored = !!input.resume;
+    let calls = 0;
+    let replayedCalls = 0;
+    let pausing = false;
+    let paused;
+    let approval;
+    let answeredPause = false;
+    /** Journal events not yet stored: all of them until a pause, unless the host takes each as its call ends. */
+    const journal = [];
+    const flush = async () => {
+        for (const event of journal.splice(0))
+            await host.append(event);
+    };
+    const record = async (event) => {
+        journal.push(event);
+        if (host.journalEveryCall)
+            await flush();
+    };
+    const outcomeEvent = (call, outcome) => {
+        const withPin = host.journalEveryCall && !pinStored;
+        if (withPin)
+            pinStored = true;
+        return callEvent(host.script, host.invocationId, call, outcome, withPin ? pin : undefined);
+    };
+    // ── Spans ──────────────────────────────────────────────────────────────────
+    const invokeSpan = startEngineSpan(RUNTIME_SPAN_SCOPE, `script.invoke ${host.script}`, {
+        root: true,
+        attributes: {
+            'gen_ai.operation.name': 'invoke_script',
+            'syndicate.name': host.script,
+            'script.name': host.script,
+            'script.run': run,
+            'script.source_hash': pin.source_hash,
+            'script.resumed': !!input.resume,
+            'adk.invocation_id': host.invocationId,
+            ...(host.sessionId ? { 'session.id': host.sessionId, 'gen_ai.conversation.id': host.sessionId } : {}),
+        },
+    });
+    const parent = trace.setSpan(ROOT_CONTEXT, invokeSpan);
+    const callSpan = (call) => startEngineSpan(RUNTIME_SPAN_SCOPE, `script.call ${call.kind}:${call.name}`, {
+        attributes: {
+            'gen_ai.operation.name': 'execute_script_call',
+            'syndicate.name': host.script,
+            'script.name': host.script,
+            'script.run': run,
+            'script.call.kind': call.kind,
+            'script.call.name': call.name,
+            'script.call.seq': call.seq,
+            ...(host.sessionId ? { 'session.id': host.sessionId } : {}),
+        },
+    }, parent);
+    const endCall = (span, status) => {
+        span.setAttribute('script.call.status', status);
+        if (status === 'error')
+            span.setStatus({ code: SpanStatusCode.ERROR });
+        span.end();
+    };
+    /** The first recorded call with this kind, name and hash, removed from the journal still to replay. */
+    const take = (kind, name, hash) => {
+        const at = pending.findIndex((e) => e.kind === kind && e.name === name && e.hash === hash);
+        return at === -1 ? undefined : pending.splice(at, 1)[0];
+    };
+    const count = () => {
+        if (++calls > limit)
+            throw new ScriptFatal('SCRIPT_CALL_LIMIT', `The script made more than ${limit} calls in one run.`);
+    };
+    const track = (running) => {
+        inflight.add(running);
+        running.then(() => inflight.delete(running), () => inflight.delete(running));
+        return running;
+    };
+    /** Runs `exec` as a live call: its span, its journal event, its outcome thrown or returned into the script. */
+    const live = (record_, exec) => track((async () => {
+        const span = callSpan(record_);
+        let outcome;
+        try {
+            outcome = { value: (await exec()) ?? null };
+        }
+        catch (err) {
+            if (err instanceof SandboxHalt || host.signal.aborted) {
+                endCall(span, 'error');
+                throw err;
+            }
+            const e = err instanceof Error ? err : new Error(String(err));
+            outcome = { error: { name: e.name || 'Error', message: e.message } };
+        }
+        endCall(span, 'error' in outcome ? 'error' : 'completed');
+        await record(outcomeEvent(record_, outcome));
+        return replayed(outcome);
+    })());
+    /** A call: replayed from the journal when recorded, else run and journaled. */
+    const call = (kind, name, args, exec) => {
+        if (pausing)
+            return never();
+        count();
+        const hash = callHash(kind, name, args);
+        const recorded = take(kind, name, hash);
+        if (recorded?.outcome) {
+            replayedCalls++;
+            return Promise.resolve().then(() => replayed(recorded.outcome));
+        }
+        const rec = { run, seq: nextSeq++, kind, name, hash };
+        return live(rec, () => exec({ run, seq: rec.seq }));
+    };
+    /** The run pauses here: the calls in flight settle and are stored, then the journal and the pause, then the sandbox halts. */
+    const pause = async (rec, event) => {
+        pausing = true;
+        await Promise.allSettled([...inflight]);
+        const interruptId = (host.newInterruptId ?? randomUUID)();
+        await host.beforePause?.();
+        await flush();
+        const stored = event(interruptId);
+        await host.append(stored);
+        endCall(callSpan(rec), 'waiting');
+        throw new SandboxHalt('waiting for the person');
+    };
+    const askUser = async (id, question, opts) => {
+        if (typeof id !== 'string' || !id)
+            throw new TypeError('askUser(id, question, { payload?, schema? }): id must be a non-empty string, unique within the run');
+        if (typeof question !== 'string' || !question)
+            throw new TypeError('askUser(id, question, …): question must be a non-empty string');
+        const o = opts && typeof opts === 'object' ? opts : {};
+        const schema = o.schema && typeof o.schema === 'object' ? o.schema : undefined;
+        if (askedIds.has(id))
+            throw new Error(`askUser: the id '${id}' was already asked in this run; each question needs its own id`);
+        askedIds.add(id);
+        const args = { question, payload: o.payload ?? null, schema: schema ?? null };
+        const hash = callHash('askUser', id, args);
+        const recorded = take('askUser', id, hash);
+        if (recorded?.outcome) {
+            replayedCalls++;
+            return replayed(recorded.outcome);
+        }
+        if (recorded?.pause && input.resume?.answer !== undefined && recorded.pause.kind !== 'approval') {
+            // The question the run waits on: this turn's message is the answer.
+            const value = { reply: replyOf(input.resume.answer, schema), input: args.payload };
+            await record(callEvent(host.script, host.invocationId, { run, seq: recorded.seq, kind: 'askUser', name: id, hash }, { value }));
+            answeredPause = true;
+            return value;
+        }
+        if (pausing)
+            return never();
+        count();
+        const rec = { run, seq: nextSeq++, kind: 'askUser', name: id, hash };
+        return pause(rec, (interruptId) => {
+            const event = pauseEvent(host.script, host.invocationId, rec, { ...pin, interrupt_id: interruptId, kind: 'question' }, {
+                message: question,
+                ...(o.payload !== undefined ? { payload: o.payload } : {}),
+                ...(schema ? { schema } : {}),
+            });
+            const [request] = getFunctionCalls(event);
+            paused = inputRequestFrom(host.script, request);
+            return event;
+        });
+    };
+    const tool = async (name, args) => {
+        if (typeof name !== 'string' || !name)
+            throw new TypeError('tool(name, args): name must be a tool in script.tools');
+        const a = args ?? {};
+        if (!host.gated?.(name))
+            return call('tool', name, a, (site) => host.tool(name, a, site));
+        // A gated tool (`script.require_approval`): a person approves the exact call first.
+        if (pausing)
+            return never();
+        count();
+        const hash = callHash('tool', name, a);
+        const recorded = take('tool', name, hash);
+        if (recorded?.outcome) {
+            replayedCalls++;
+            return replayed(recorded.outcome);
+        }
+        if (recorded?.pause && input.resume?.decision && recorded.pause.kind === 'approval') {
+            answeredPause = true;
+            const rec = { run, seq: recorded.seq, kind: 'tool', name, hash };
+            if (input.resume.decision.approved)
+                return live(rec, () => host.tool(name, a, { run, seq: rec.seq }));
+            const refused = { error: APPROVAL_TEXTS.rejected };
+            endCall(callSpan(rec), 'refused');
+            await record(callEvent(host.script, host.invocationId, rec, { value: refused }));
+            return refused;
+        }
+        const rec = { run, seq: nextSeq++, kind: 'tool', name, hash };
+        return pause(rec, (interruptId) => {
+            const event = approvalEvent(host.script, host.invocationId, rec, { ...pin, interrupt_id: interruptId, kind: 'approval' }, { tool: name, args: a, hint: APPROVAL_TEXTS.hint(name) });
+            const [request] = getFunctionCalls(event);
+            approval = approvalRequestOf(event, request);
+            return event;
+        });
+    };
+    const sandboxed = await runInSandbox({
+        source: input.source,
+        mode: 'api',
+        value: { message: input.message, transcript: input.transcript, variables: input.variables },
+        signal: host.signal,
+        limits: { ...input.limits },
+        functions: {
+            agent: ([name, agentInput, opts]) => {
+                if (typeof name !== 'string' || !name)
+                    throw new TypeError('agent(name, input, opts?): name must be a declared agent\'s name');
+                const o = opts === undefined || opts === null ? {} : opts;
+                if (typeof o !== 'object' || Array.isArray(o))
+                    throw new TypeError('agent(name, input, opts?): opts must be an object');
+                return call('agent', name, { input: agentInput ?? null, opts: o }, (site) => host.agent(name, agentInput ?? null, o, site));
+            },
+            tool: ([name, args]) => tool(name, args),
+            askUser: ([id, question, opts]) => askUser(id, question, opts),
+            now: () => call('now', 'now', null, async () => Date.now()),
+            random: () => call('random', 'random', null, async () => Math.random()),
+            log: ([text]) => {
+                // A replayed run already said these.
+                if (!pending.length)
+                    host.log(typeof text === 'string' ? text : JSON.stringify(text));
+                return null;
+            },
+        },
+    });
+    const logs = sandboxed.logs;
+    const waiting = !!(paused || approval);
+    // A resumed run, or one stored call by call, that ended (not one the turn's signal stopped) is closed, so the next message starts a new one.
+    if (!waiting && !host.signal.aborted && (input.resume || (host.journalEveryCall && pinStored))) {
+        await flush();
+        await host.append(endEvent(host.script, host.invocationId, run, nextSeq++));
+    }
+    const unreplayed = () => {
+        const left = pending[0];
+        return left ? { code: 'SCRIPT_DIVERGED', message: `The resumed run did not make the call its journal holds: ${describe(left)}. A script must make the same calls, with the same arguments, on every run (ADR 0137 item 9).` } : undefined;
+    };
+    const finish = (outcome) => {
+        invokeSpan.setAttributes({ 'script.status': outcome.status, 'script.calls': calls, 'script.replayed_calls': replayedCalls });
+        if (outcome.status === 'failed') {
+            invokeSpan.setAttribute('script.error_code', outcome.error.code);
+            invokeSpan.setStatus({ code: SpanStatusCode.ERROR });
+        }
+        invokeSpan.end();
+        return outcome;
+    };
+    if (waiting) {
+        const diverged = unreplayed();
+        if (diverged)
+            return finish({ status: 'failed', run, error: diverged, logs });
+        return finish(approval ? { status: 'approval', run, approval, logs } : { status: 'paused', run, input: paused, logs });
+    }
+    if (sandboxed.halt) {
+        const code = sandboxed.halt instanceof ScriptFatal ? sandboxed.halt.code : 'SCRIPT_HALTED';
+        return finish({ status: 'failed', run, error: { code, message: sandboxed.halt.message }, logs });
+    }
+    if (!sandboxed.ok) {
+        const error = sandboxed.error;
+        return finish({ status: 'failed', run, error: { code: error.code === 'CODE_ERROR' ? 'SCRIPT_ERROR' : error.code, message: error.message }, logs });
+    }
+    const awaited = input.resume?.answer !== undefined || input.resume?.decision !== undefined;
+    if (awaited && !answeredPause) {
+        return finish({ status: 'failed', run, error: { code: 'SCRIPT_DIVERGED', message: 'The resumed run never reached the pause it was waiting on.' }, logs });
+    }
+    const diverged = unreplayed();
+    if (diverged)
+        return finish({ status: 'failed', run, error: diverged, logs });
+    return finish({ status: 'completed', run, value: sandboxed.result, logs });
+}

package/dist/lib/syndicateSchema.d.ts

@@ -225,6 +225,9 @@ export declare const agentSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
     code_execution: z.ZodOptional<z.ZodLiteral<"gemini">>;
+    run_code: z.ZodOptional<z.ZodObject<{
+        attach: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     context: z.ZodOptional<z.ZodObject<{
         compact_after_tokens: z.ZodNumber;
         keep_recent_events: z.ZodOptional<z.ZodNumber>;
@@ -439,6 +442,9 @@ export declare const subagentSchema: z.ZodObject<{
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
     code_execution: z.ZodOptional<z.ZodLiteral<"gemini">>;
+    run_code: z.ZodOptional<z.ZodObject<{
+        attach: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     context: z.ZodOptional<z.ZodObject<{
         compact_after_tokens: z.ZodNumber;
         keep_recent_events: z.ZodOptional<z.ZodNumber>;
@@ -462,6 +468,8 @@ export declare const subagentSchema: z.ZodObject<{
     yaml_reference: z.ZodOptional<z.ZodString>;
     a2a_agent_url: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
+/** The largest `script.source` a syndicate may carry. */
+export declare const MAX_SCRIPT_SOURCE_CHARS: number;
 export declare const syndicateSchema: z.ZodObject<{
     syndicate_name: z.ZodString;
     orchestrator: z.ZodObject<{
@@ -657,6 +665,9 @@ export declare const syndicateSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
         code_execution: z.ZodOptional<z.ZodLiteral<"gemini">>;
+        run_code: z.ZodOptional<z.ZodObject<{
+            attach: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
         context: z.ZodOptional<z.ZodObject<{
             compact_after_tokens: z.ZodNumber;
             keep_recent_events: z.ZodOptional<z.ZodNumber>;
@@ -865,6 +876,9 @@ export declare const syndicateSchema: z.ZodObject<{
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
         code_execution: z.ZodOptional<z.ZodLiteral<"gemini">>;
+        run_code: z.ZodOptional<z.ZodObject<{
+            attach: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
         context: z.ZodOptional<z.ZodObject<{
             compact_after_tokens: z.ZodNumber;
             keep_recent_events: z.ZodOptional<z.ZodNumber>;
@@ -921,6 +935,12 @@ export declare const syndicateSchema: z.ZodObject<{
         }, z.core.$strict>>>;
         max_concurrency: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
+    script: z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        models: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        require_approval: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
     retries: z.ZodOptional<z.ZodObject<{
         model_errors: z.ZodOptional<z.ZodNumber>;
         tool_errors: z.ZodOptional<z.ZodNumber>;

package/dist/lib/syndicateSchema.js

@@ -410,6 +410,12 @@ const agentFields = {
         .literal('gemini')
         .optional()
         .describe('"gemini": the model writes and runs Python in Gemini\'s server-side sandbox; nothing runs on this host. Gemini models only.'),
+    run_code: z
+        .strictObject({
+        attach: z.boolean().optional().describe('Put each run\'s code and result on the reply as a code_run data part. Default false.'),
+    })
+        .optional()
+        .describe('How this agent\'s run_code tool behaves (ADR 0137). Needs run_code in `tools`.'),
     context: z
         .strictObject({
         compact_after_tokens: z.number().int().min(1000).describe('Compact when the last request\'s prompt passed this many tokens.'),
@@ -533,6 +539,31 @@ const workflowSchema = z
     max_concurrency: z.number().int().positive().optional().describe('Nodes that may run at once. Default: unbounded.'),
 })
     .describe('Opts into a WORKFLOW: the syndicate as a graph (lib/workflow.ts). Cannot be combined with dispatch.');
+// ── Script (ADR 0137) ────────────────────────────────────────────────────────
+/** The largest `script.source` a syndicate may carry. */
+export const MAX_SCRIPT_SOURCE_CHARS = 64 * 1024;
+const scriptSchema = z
+    .strictObject({
+    source: z
+        .string()
+        .min(1)
+        .max(MAX_SCRIPT_SOURCE_CHARS)
+        .describe('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: z
+        .array(z.string().min(1))
+        .max(16)
+        .optional()
+        .describe('The models agent(name, input, { model }) may move a call to; each agent is compiled and checked on every one at load.'),
+    tools: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('The registry tools tool(name, args) may run; the only path from the script to the network or the host.'),
+    require_approval: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('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 }.'),
+})
+    .describe('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.');
 // ── Syndicate ────────────────────────────────────────────────────────────────
 export const syndicateSchema = z
     .strictObject({
@@ -544,6 +575,7 @@ export const syndicateSchema = z
         .describe('The orchestrator\'s team. Omit it (or write `subagents: []`) for a single-agent syndicate.'),
     dispatch: dispatchSchema.optional(),
     workflow: workflowSchema.optional(),
+    script: scriptSchema.optional(),
     retries: z
         .strictObject({
         model_errors: z.number().int().min(0).max(5).optional().describe('Retries of a malformed model reply. Default 2; 0 off.'),
@@ -667,6 +699,8 @@ function knownKeysAt(p) {
             return Object.keys(dispatchSchema.shape);
         case 'dispatch/route_overrides/#':
             return Object.keys(routeOverride.shape);
+        case 'script':
+            return Object.keys(scriptSchema.shape);
         case 'orchestrator/orchestration':
         case 'subagents/#/orchestration':
             return ['role', 'delegates'];
@@ -901,14 +935,23 @@ function crossFieldProblems(raw) {
         if (agent.code_execution !== undefined && model && !/^gemini-/.test(model)) {
             out.push({ path: [...path, 'code_execution'], message: `code_execution: gemini needs a gemini-* model (this agent's is ${model})` });
         }
-        if (agent.context !== undefined && (!isOrchestrator || isObj(raw.dispatch) || isObj(raw.workflow))) {
+        if (agent.context !== undefined && (!isOrchestrator || isObj(raw.dispatch) || isObj(raw.workflow) || isObj(raw.script))) {
             out.push({
                 path: [...path, 'context'],
-                message: 'context compaction applies to the orchestrator of a delegate syndicate: a dispatch route reads a bounded projection, a workflow node sees only its input, and a subagent starts fresh on every call',
+                message: 'context compaction applies to the orchestrator of a delegate syndicate: a dispatch route reads a bounded projection, a workflow node sees only its input, a script\'s agent() call starts fresh, and a subagent starts fresh on every call',
             });
         }
-        if (agent.mode !== undefined && !isObj(raw.workflow)) {
-            out.push({ path: [...path, 'mode'], message: 'mode: task applies to workflow nodes, whose output is the finish_task arguments' });
+        if (agent.mode !== undefined && !isObj(raw.workflow) && !isObj(raw.script)) {
+            out.push({ path: [...path, 'mode'], message: 'mode: task applies to workflow nodes and script agents, whose output is the finish_task arguments' });
+        }
+        // run_code (ADR 0137): the key configures the tool, so the tool must be listed; a nested or remote agent sets its own.
+        if (agent.run_code !== undefined) {
+            if (typeof agent.yaml_reference === 'string' || typeof agent.a2a_agent_url === 'string') {
+                out.push({ path: [...path, 'run_code'], message: 'applies to an inline agent; a nested syndicate (yaml_reference) or a remote agent (a2a_agent_url) sets its own' });
+            }
+            else if (!(Array.isArray(agent.tools) && agent.tools.includes('run_code'))) {
+                out.push({ path: [...path, 'run_code'], message: 'configures the run_code tool, which this agent\'s tools do not list; add run_code to tools' });
+            }
         }
         if (agent.mcp_tools !== undefined && typeof agent.mcp_server_url !== 'string') {
             out.push({ path: [...path, 'mcp_tools'], message: 'mcp_tools chooses among an MCP server\'s tools; it needs mcp_server_url' });
@@ -927,12 +970,14 @@ function crossFieldProblems(raw) {
     if (isObj(raw.orchestrator))
         executionProblems(raw.orchestrator, ['orchestrator'], true);
     // max_concurrency bounds an orchestrator's delegated calls (ADR 0116): a workflow bounds its nodes under workflow:, and a dispatch classifier delegates nothing.
-    if (raw.max_concurrency !== undefined && (isObj(raw.workflow) || isObj(raw.dispatch))) {
+    if (raw.max_concurrency !== undefined && (isObj(raw.workflow) || isObj(raw.dispatch) || isObj(raw.script))) {
         out.push({
             path: ['max_concurrency'],
             message: isObj(raw.workflow)
                 ? 'max_concurrency at the root bounds a delegate orchestrator\'s subagent calls; a workflow bounds its nodes with workflow.max_concurrency'
-                : 'max_concurrency bounds a delegate orchestrator\'s subagent calls; a dispatch syndicate\'s classifier delegates nothing (set it in a route\'s own syndicate file)',
+                : isObj(raw.script)
+                    ? 'max_concurrency at the root bounds a delegate orchestrator\'s subagent calls; a script bounds its own with parallel(thunks, { max })'
+                    : 'max_concurrency bounds a delegate orchestrator\'s subagent calls; a dispatch syndicate\'s classifier delegates nothing (set it in a route\'s own syndicate file)',
         });
     }
     for (const [i, sub] of (Array.isArray(raw.subagents) ? raw.subagents : []).entries())
@@ -1024,6 +1069,8 @@ function crossFieldProblems(raw) {
     });
     if (isObj(raw.workflow))
         out.push(...workflowProblems(raw, subs));
+    if (isObj(raw.script))
+        out.push(...scriptProblems(raw, subs));
     // Names must be unique across the tree this file declares: two AgentTools
     // with one name collide, and dispatch routes by name.
     const seen = new Map();
@@ -1210,6 +1257,51 @@ function workflowProblems(raw, subs) {
     return out;
 }
 /** Where an agent declares an authorization_code grant (mcp_auth, mcp_servers[].auth, openapi[].auth), by its path below the agent. */
+/**
+ * The rules a `script:` syndicate keeps (ADR 0137), which a JSON Schema
+ * cannot say: it is one orchestration method, not three; a pause inside a
+ * called agent cannot be replayed in this version (item 12), so the gates,
+ * the ask_user tool, skill scripts and per-user OAuth consent are refused on
+ * its agents by name, and the script's own askUser is its pause; and an
+ * agent that runs Gemini's code execution can be moved only to Gemini models.
+ */
+function scriptProblems(raw, subs) {
+    const out = [];
+    const script = raw.script;
+    if (isObj(raw.dispatch))
+        out.push({ path: ['script'], message: 'a syndicate orchestrates with a script or a plan-dispatch router, not both; remove `dispatch` (the script can route)' });
+    if (isObj(raw.workflow))
+        out.push({ path: ['script'], message: 'a syndicate orchestrates with a script or a workflow graph, not both; remove `workflow`' });
+    const allowed = Array.isArray(script.tools) ? script.tools : [];
+    (Array.isArray(script.require_approval) ? script.require_approval : []).forEach((name, j) => {
+        if (typeof name === 'string' && !allowed.includes(name))
+            out.push({ path: ['script', 'require_approval', j], message: `'${name}' is not in script.tools` });
+    });
+    const models = Array.isArray(script.models) ? script.models.filter((m) => typeof m === 'string') : [];
+    const agents = [];
+    if (isObj(raw.orchestrator))
+        agents.push([['orchestrator'], raw.orchestrator]);
+    subs.forEach((sub, i) => isObj(sub) && agents.push([['subagents', i], sub]));
+    const pausesInside = 'a pause inside an agent a script calls cannot be resumed in this version (ADR 0137 item 12); pause in the script with askUser';
+    for (const [path, agent] of agents) {
+        if (agent.require_approval !== undefined)
+            out.push({ path: [...path, 'require_approval'], message: pausesInside });
+        const tools = Array.isArray(agent.tools) ? agent.tools : [];
+        const asks = tools.indexOf('ask_user');
+        if (asks !== -1)
+            out.push({ path: [...path, 'tools', asks], message: pausesInside });
+        if (isObj(agent.skills) && agent.skills.scripts === 'local')
+            out.push({ path: [...path, 'skills', 'scripts'], message: `skill scripts pause for approval; ${pausesInside}` });
+        for (const grant of authorizationCodeGrants(agent))
+            out.push({ path: [...path, ...grant], message: `an authorization_code grant pauses for the person's consent; ${pausesInside}` });
+        if (agent.code_execution !== undefined) {
+            const other = models.find((m) => !/^gemini-/.test(m));
+            if (other)
+                out.push({ path: [...path, 'code_execution'], message: `code_execution: gemini needs a gemini-* model, and script.models lets agent() move this agent to ${other}` });
+        }
+    }
+    return out;
+}
 function authorizationCodeGrants(agent) {
     const out = [];
     const isCode = (auth) => isObj(auth) && isObj(auth.oauth2) && auth.oauth2.grant === 'authorization_code';

package/dist/lib/toolRegistry.js

@@ -24,6 +24,7 @@ import { SCIENCE_TOOL_CONTRACTS } from './tools/scienceTools.js';
 import { TASK_TOOL_CONTRACTS } from './tools/taskTools.js';
 import { askUserTool } from './runtime/questions.js';
 import { xApiSearchTool } from './tools/xApiSearchTool.js';
+import { runCodeTool } from './tools/runCodeTool.js';
 // Knowledge-bundle tools, derived from their contracts so the YAML names
 // can never drift from the definitions. The agentic composites
 // (wiki_query/wiki_garden) are deliberately absent: a syndicate reaches
@@ -79,6 +80,9 @@ const BUILTIN_TOOLS = {
     // Both reach the run's memory service, pinned to the root namespace.
     load_memory: asTool(loadMemoryTool),
     preload_memory: preloadMemoryTool,
+    // JavaScript in the engine's QuickJS sandbox (lib/tools/runCodeTool.ts,
+    // ADR 0137): any provider; runs only under MELCHIZEDEK_CODE_SANDBOX=on.
+    run_code: runCodeTool,
 };
 // Null-prototype copy (as GUARD_MAP is): resolution and registration go
 // through this map, never the literal above.

package/dist/lib/tools/runCodeTool.d.ts

@@ -0,0 +1,50 @@
+/**
+ * lib/tools/runCodeTool.ts — `run_code`: an agent runs JavaScript in the
+ * engine's sandbox and rests its answer on what the code returned
+ * (ADR 0137 items 2 to 4).
+ *
+ * WHY a registry tool: any agent on any provider can list it
+ * (`tools: [run_code]`), since the model only writes text, and it gets what
+ * every registry tool gets: `require_approval`, MCP exposure (ADR 0125), the
+ * result bound and `retries.tool_errors`. `code_execution: gemini` stays,
+ * for Python in Gemini's own sandbox on Gemini models (ADR 0033).
+ *
+ * THE CONTRACT: `{ code, input? }`. The code is a JavaScript module whose
+ * default export is called with `input`; the tool returns
+ * `{ result, logs, error }`: the export's JSON-serializable return, the
+ * `console.log` output, and what stopped it, if anything. Each is bounded at
+ * MAX_RESULT_CHARS. The code reaches nothing but `input` and `console`: no
+ * network, no host, no keys, no clock, no randomness (lib/sandbox/).
+ *
+ * THE SWITCH: nothing runs unless the operator set MELCHIZEDEK_CODE_SANDBOX=on;
+ * a syndicate listing run_code without it is refused at load (refuseOnNative),
+ * and a call that reaches here anyway answers with the reason.
+ *
+ * ATTACH: an agent's `run_code: { attach: true }` puts each run's code and
+ * result on the reply as a `code_run` data part (lib/runtime/syndicateTurn.ts
+ * collects them, the A2A executor publishes them). Off by default.
+ */
+import { z } from 'zod';
+/** The registry name. */
+export declare const RUN_CODE = "run_code";
+/** The largest program a call may send. */
+export declare const MAX_CODE_CHARS = 64000;
+/** What a call returns. */
+export interface RunCodeOutput {
+    result: unknown;
+    logs: string;
+    error: string | null;
+}
+export declare const runCodeTool: import("./toolContract.ts").DefinedTool<z.ZodObject<{
+    code: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>, RunCodeOutput>;
+/** One run an agent made, as a `code_run` data part carries it. */
+export interface CodeRun {
+    type: 'code_run';
+    /** The agent that ran it. */
+    agent: string;
+    code: string;
+    result: unknown;
+    error?: string;
+}