melchizedek-agents 1.6.0 → 1.7.0

package/dist/lib/sandbox/sandbox.js

@@ -0,0 +1,276 @@
+/**
+ * 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).
+ */
+import { Worker } from 'node:worker_threads';
+/** The operator's switch for running code (ADR 0137 item 4). */
+export const CODE_SANDBOX_ENV = 'MELCHIZEDEK_CODE_SANDBOX';
+/** True when the operator turned the sandbox on: MELCHIZEDEK_CODE_SANDBOX=on (or true, 1). */
+export function codeSandboxEnabled(env = process.env) {
+    return /^(on|true|1)$/i.test((env[CODE_SANDBOX_ENV] ?? '').trim());
+}
+/** The message a refusal carries when the switch is off. */
+export function codeSandboxOffMessage(what) {
+    return `${what} runs code in the engine's sandbox, which is off; the operator turns it on with ${CODE_SANDBOX_ENV}=on (ADR 0137)`;
+}
+/** A syndicate that needs the sandbox, refused while it is off: it names the variable that turns it on. */
+export class CodeSandboxOffError extends Error {
+    code = 'CODE_SANDBOX_OFF';
+    constructor(what) {
+        super(codeSandboxOffMessage(what));
+        this.name = 'CodeSandboxOffError';
+    }
+}
+/** What in a syndicate runs code: its `script:`, and each agent that lists `run_code`. */
+export function codeUsersOf(config) {
+    const out = [];
+    if (config.script)
+        out.push(`${config.syndicate_name || 'the syndicate'}'s script`);
+    for (const agent of [config.orchestrator, ...(config.subagents ?? [])]) {
+        if (agent?.tools?.includes('run_code'))
+            out.push(`${agent.name ?? 'an agent'}'s run_code tool`);
+    }
+    return out;
+}
+/** Throws CodeSandboxOffError when `config` runs code and the operator has not turned the sandbox on. */
+export function refuseWithoutSandbox(config, env = process.env) {
+    if (codeSandboxEnabled(env))
+        return;
+    const users = codeUsersOf(config);
+    if (users.length)
+        throw new CodeSandboxOffError(users.join(' and '));
+}
+export const DEFAULT_SANDBOX_LIMITS = Object.freeze({
+    memoryBytes: 64 * 1024 * 1024,
+    stackBytes: 1024 * 1024,
+    cpuMs: 5_000,
+    maxLogChars: 20_000,
+    maxResultChars: 1_000_000,
+    maxParallel: 32,
+});
+/**
+ * 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 class SandboxHalt extends Error {
+    detail;
+    constructor(message, detail) {
+        super(message);
+        this.name = 'SandboxHalt';
+        this.detail = detail;
+    }
+}
+// ── The pool ─────────────────────────────────────────────────────────────────
+const DEFAULT_POOL_SIZE = 16;
+function poolSize() {
+    const n = Number(process.env.MELCHIZEDEK_CODE_SANDBOX_WORKERS);
+    return Number.isInteger(n) && n > 0 ? Math.min(n, 256) : DEFAULT_POOL_SIZE;
+}
+let running = 0;
+const waiting = [];
+async function acquire(signal) {
+    if (running >= poolSize()) {
+        await new Promise((resolve, reject) => {
+            const go = () => {
+                signal?.removeEventListener('abort', cancel);
+                resolve();
+            };
+            const cancel = () => {
+                const at = waiting.indexOf(go);
+                if (at !== -1)
+                    waiting.splice(at, 1);
+                reject(new Error('canceled'));
+            };
+            waiting.push(go);
+            signal?.addEventListener('abort', cancel, { once: true });
+        });
+    }
+    running++;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        running--;
+        waiting.shift()?.();
+    };
+}
+// ── One run ──────────────────────────────────────────────────────────────────
+/** The worker file beside this one: `.ts` when the engine runs from source, `.js` from the package. */
+function workerUrl() {
+    return new URL(import.meta.url.endsWith('.ts') ? './worker.ts' : './worker.js', import.meta.url);
+}
+/** How long past its CPU budget a worker that stopped answering is given before it is terminated. */
+const WATCHDOG_GRACE_MS = 1_000;
+/**
+ * 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 async function runInSandbox(opts) {
+    const limits = { ...DEFAULT_SANDBOX_LIMITS, ...opts.limits };
+    const empty = { logs: '', logsTruncated: false, cpuMs: 0 };
+    if (opts.signal?.aborted)
+        return { ok: false, error: { code: 'CANCELED', message: 'The run was canceled.' }, ...empty };
+    let valueJson;
+    try {
+        valueJson = JSON.stringify(opts.value ?? null) ?? 'null';
+    }
+    catch (err) {
+        return { ok: false, error: { code: 'CODE_ERROR', message: `The input is not JSON-serializable: ${err.message}` }, ...empty };
+    }
+    let release;
+    try {
+        release = await acquire(opts.signal);
+    }
+    catch {
+        return { ok: false, error: { code: 'CANCELED', message: 'The run was canceled.' }, ...empty };
+    }
+    const functions = opts.functions ?? {};
+    const worker = new Worker(workerUrl(), {
+        // Source runs need type stripping in the worker; the package runs compiled JS.
+        execArgv: import.meta.url.endsWith('.ts') ? ['--experimental-strip-types', '--disable-warning=ExperimentalWarning'] : [],
+        // The wasm heap is held by setMemoryLimit; this bounds the JS around it.
+        resourceLimits: { maxOldGenerationSizeMb: 96, maxYoungGenerationSizeMb: 16 },
+        stdout: true,
+        stderr: true,
+    });
+    return new Promise((resolve) => {
+        let settled = false;
+        let outstanding = 0;
+        let idleSince = performance.now();
+        let idleTotal = 0;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearInterval(watchdog);
+            opts.signal?.removeEventListener('abort', onAbort);
+            void worker.terminate();
+            release();
+            resolve(result);
+        };
+        const onAbort = () => finish({ ok: false, error: { code: 'CANCELED', message: 'The run was canceled.' }, ...empty });
+        opts.signal?.addEventListener('abort', onAbort, { once: true });
+        // The watchdog: compute is what the worker does while no host call is outstanding.
+        const watchdog = setInterval(() => {
+            const computing = outstanding === 0 ? idleTotal + (performance.now() - idleSince) : idleTotal;
+            if (computing > limits.cpuMs + WATCHDOG_GRACE_MS) {
+                finish({ ok: false, error: { code: 'CPU_LIMIT', message: `The code ran past its ${limits.cpuMs} ms CPU budget and was stopped.` }, ...empty });
+            }
+        }, 250);
+        watchdog.unref?.();
+        const startCall = () => {
+            if (outstanding === 0)
+                idleTotal += performance.now() - idleSince;
+            outstanding++;
+        };
+        const endCall = () => {
+            outstanding--;
+            if (outstanding === 0)
+                idleSince = performance.now();
+        };
+        worker.on('message', (message) => {
+            if (settled)
+                return;
+            if (message?.type === 'call') {
+                const fn = Object.prototype.hasOwnProperty.call(functions, message.name) ? functions[message.name] : undefined;
+                startCall();
+                void (async () => {
+                    try {
+                        if (!fn)
+                            throw new Error(`${message.name} is not a function the host passed in`);
+                        const args = JSON.parse(message.args);
+                        const value = await fn(Array.isArray(args) ? args : []);
+                        const json = value === undefined ? undefined : JSON.stringify(value);
+                        if (!settled)
+                            worker.postMessage({ type: 'reply', id: message.id, ok: true, value: json });
+                    }
+                    catch (err) {
+                        if (err instanceof SandboxHalt) {
+                            finish({ ok: false, halt: err, error: { code: 'HALTED', message: err.message }, ...empty });
+                            return;
+                        }
+                        const e = err instanceof Error ? err : new Error(String(err));
+                        if (!settled)
+                            worker.postMessage({ type: 'reply', id: message.id, ok: false, error: { name: e.name || 'Error', message: e.message } });
+                    }
+                    finally {
+                        endCall();
+                    }
+                })();
+                return;
+            }
+            if (message?.type === 'done') {
+                const base = { logs: String(message.logs ?? ''), logsTruncated: !!message.logsTruncated, cpuMs: Number(message.cpuMs ?? 0) };
+                if (!message.ok) {
+                    finish({ ok: false, error: message.error, ...base });
+                    return;
+                }
+                const text = String(message.result ?? 'null');
+                if (text.length > limits.maxResultChars) {
+                    finish({ ok: false, error: { code: 'RESULT_TOO_LARGE', message: `The result is ${text.length.toLocaleString('en-US')} characters of JSON; the limit is ${limits.maxResultChars.toLocaleString('en-US')}.` }, ...base });
+                    return;
+                }
+                let result;
+                try {
+                    result = JSON.parse(text);
+                }
+                catch {
+                    result = null;
+                }
+                finish({ ok: true, result, ...base });
+            }
+        });
+        worker.on('error', (err) => {
+            const oom = err.code === 'ERR_WORKER_OUT_OF_MEMORY';
+            finish({ ok: false, error: { code: oom ? 'MEMORY_LIMIT' : 'SANDBOX_CRASHED', message: oom ? 'The code ran out of memory.' : `The sandbox failed: ${err.message}` }, ...empty });
+        });
+        worker.on('exit', (code) => {
+            finish({ ok: false, error: { code: 'SANDBOX_CRASHED', message: `The sandbox exited (${code}) before the code finished.` }, ...empty });
+        });
+        worker.postMessage({
+            type: 'run',
+            source: opts.source,
+            mode: opts.mode ?? 'input',
+            value: valueJson,
+            functions: Object.keys(functions),
+            limits: {
+                memoryBytes: limits.memoryBytes,
+                stackBytes: limits.stackBytes,
+                cpuMs: limits.cpuMs,
+                maxLogChars: limits.maxLogChars,
+                maxParallel: Math.max(1, Math.min(limits.maxParallel, 32)),
+            },
+        });
+    });
+}

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

@@ -0,0 +1,29 @@
+/**
+ * lib/sandbox/worker.ts — one sandbox run, on its own worker thread
+ * (ADR 0137 item 1). lib/sandbox/sandbox.ts starts it, one Worker per run,
+ * and talks to it in messages; nothing else imports this file.
+ *
+ * WHAT RUNS HERE: QuickJS compiled to wasm (the release sync build), in a
+ * fresh runtime with a memory limit, a stack limit and an interrupt
+ * handler that stops the code after its CPU budget. The budget counts only
+ * the time this thread spends inside the interpreter, so a run awaiting the
+ * host (an agent, a tool) is not charged for the wait.
+ *
+ * WHAT THE CODE CAN REACH: the argument its default export is called with,
+ * `console.log` (captured, bounded), and nothing else. There is no fetch,
+ * no timer, no file system, no `process`, no environment; `Date.now`, the
+ * current-time `Date` constructor and `Math.random` throw, naming the
+ * function to use instead when the host passes one. The host functions the
+ * caller names arrive as async functions on the argument; their arguments
+ * and results cross as JSON, both ways.
+ *
+ * THE PROTOCOL (parent ↔ worker):
+ *   run   → { type: 'run', source, mode, value, functions, limits }
+ *   call  ← { type: 'call', id, name, args }     a host function was called
+ *   reply → { type: 'reply', id, ok, value | error }
+ *   done  ← { type: 'done', ok, result | error, logs, logsTruncated, cpuMs }
+ * The parent terminates the worker after `done`, on the turn's signal, and
+ * when it ran past its budget without answering, a harder stop than the
+ * interrupt handler, which QuickJS consults only between bytecodes.
+ */
+export {};

package/dist/lib/sandbox/worker.js

@@ -0,0 +1,280 @@
+/**
+ * lib/sandbox/worker.ts — one sandbox run, on its own worker thread
+ * (ADR 0137 item 1). lib/sandbox/sandbox.ts starts it, one Worker per run,
+ * and talks to it in messages; nothing else imports this file.
+ *
+ * WHAT RUNS HERE: QuickJS compiled to wasm (the release sync build), in a
+ * fresh runtime with a memory limit, a stack limit and an interrupt
+ * handler that stops the code after its CPU budget. The budget counts only
+ * the time this thread spends inside the interpreter, so a run awaiting the
+ * host (an agent, a tool) is not charged for the wait.
+ *
+ * WHAT THE CODE CAN REACH: the argument its default export is called with,
+ * `console.log` (captured, bounded), and nothing else. There is no fetch,
+ * no timer, no file system, no `process`, no environment; `Date.now`, the
+ * current-time `Date` constructor and `Math.random` throw, naming the
+ * function to use instead when the host passes one. The host functions the
+ * caller names arrive as async functions on the argument; their arguments
+ * and results cross as JSON, both ways.
+ *
+ * THE PROTOCOL (parent ↔ worker):
+ *   run   → { type: 'run', source, mode, value, functions, limits }
+ *   call  ← { type: 'call', id, name, args }     a host function was called
+ *   reply → { type: 'reply', id, ok, value | error }
+ *   done  ← { type: 'done', ok, result | error, logs, logsTruncated, cpuMs }
+ * The parent terminates the worker after `done`, on the turn's signal, and
+ * when it ran past its budget without answering, a harder stop than the
+ * interrupt handler, which QuickJS consults only between bytecodes.
+ */
+import { parentPort } from 'node:worker_threads';
+import { newQuickJSWASMModuleFromVariant } from 'quickjs-emscripten-core';
+import variant from '@jitl/quickjs-wasmfile-release-sync';
+const port = parentPort;
+if (!port)
+    throw new Error('lib/sandbox/worker.ts runs as a worker thread (lib/sandbox/sandbox.ts starts it)');
+/**
+ * Runs before the code: captures the host bridge and removes it from the
+ * global object, masks the clock and randomness, and installs `console`.
+ * It returns the function the host calls the default export through.
+ */
+const PRELUDE = String.raw `(() => {
+  const host = globalThis.__host;
+  const writeLog = globalThis.__log;
+  const config = JSON.parse(globalThis.__config);
+  delete globalThis.__host;
+  delete globalThis.__log;
+  delete globalThis.__config;
+  const has = (name) => config.functions.includes(name);
+  const blocked = (what, instead) => function () {
+    throw new Error(what + ' is not available in the sandbox' + (instead && has(instead) ? '; use ' + instead + '()' : ''));
+  };
+  Math.random = blocked('Math.random', 'random');
+  const RealDate = Date;
+  class SandboxDate extends RealDate {
+    constructor(...args) {
+      if (args.length === 0) throw new Error('new Date() with no arguments reads the clock, which is not available in the sandbox' + (has('now') ? '; use now()' : ''));
+      super(...args);
+    }
+  }
+  SandboxDate.now = blocked('Date.now', 'now');
+  globalThis.Date = SandboxDate;
+  const show = (v) => {
+    if (typeof v === 'string') return v;
+    try { const s = JSON.stringify(v); return s === undefined ? String(v) : s; } catch { return String(v); }
+  };
+  const print = (...args) => writeLog(args.map(show).join(' '));
+  globalThis.console = Object.freeze({ log: print, info: print, warn: print, error: print, debug: print });
+  const call = (name) => (...args) => host(name, JSON.stringify(args)).then((r) => (r === undefined ? undefined : JSON.parse(r)));
+  const parallel = async (thunks, opts) => {
+    if (!Array.isArray(thunks)) throw new TypeError('parallel takes an array of functions');
+    const asked = opts && typeof opts.max === 'number' ? Math.floor(opts.max) : 4;
+    const max = Math.max(1, Math.min(asked, config.maxParallel));
+    const results = new Array(thunks.length);
+    let next = 0;
+    const lane = async () => {
+      while (next < thunks.length) {
+        const i = next++;
+        if (typeof thunks[i] !== 'function') throw new TypeError('parallel: item ' + i + ' is not a function');
+        results[i] = await thunks[i]();
+      }
+    };
+    await Promise.all(Array.from({ length: Math.min(max, thunks.length) }, lane));
+    return results;
+  };
+  return (fn, valueJson) => {
+    const value = JSON.parse(valueJson);
+    let arg = value;
+    if (config.mode === 'api') {
+      arg = { ...(value && typeof value === 'object' ? value : {}) };
+      for (const name of config.functions) arg[name] = call(name);
+      arg.parallel = parallel;
+      Object.freeze(arg);
+    }
+    return Promise.resolve()
+      .then(() => fn(arg))
+      .then((r) => {
+        const json = JSON.stringify(r);
+        return json === undefined ? 'null' : json;
+      });
+  };
+})()`;
+function post(message) {
+    port.postMessage(message);
+}
+port.once('message', (message) => {
+    run(message).catch((err) => {
+        post({ type: 'done', ok: false, error: { code: 'SANDBOX_CRASHED', message: err instanceof Error ? err.message : String(err) }, logs: '', logsTruncated: false, cpuMs: 0 });
+    });
+});
+async function run(message) {
+    const { limits } = message;
+    // The package's typings describe its CommonJS shape; under ESM the default import is the variant itself.
+    const mod = await newQuickJSWASMModuleFromVariant(variant);
+    const runtime = mod.newRuntime();
+    runtime.setMemoryLimit(limits.memoryBytes);
+    runtime.setMaxStackSize(limits.stackBytes);
+    // CPU: time inside the interpreter only.
+    let used = 0;
+    let segmentStart = 0;
+    let cpuExceeded = false;
+    runtime.setInterruptHandler(() => {
+        if (segmentStart && used + (performance.now() - segmentStart) > limits.cpuMs) {
+            cpuExceeded = true;
+            return true;
+        }
+        return false;
+    });
+    const compute = (fn) => {
+        segmentStart = performance.now();
+        try {
+            return fn();
+        }
+        finally {
+            used += performance.now() - segmentStart;
+            segmentStart = 0;
+        }
+    };
+    let logs = '';
+    let logsTruncated = false;
+    let finished = false;
+    const finish = (outcome) => {
+        if (finished)
+            return;
+        finished = true;
+        post({ type: 'done', ...outcome, logs, logsTruncated, cpuMs: Math.round(used) });
+    };
+    const vm = runtime.newContext();
+    const pending = new Map();
+    let nextId = 1;
+    const hostFn = vm.newFunction('__host', (nameHandle, argsHandle) => {
+        const name = vm.getString(nameHandle);
+        const args = vm.getString(argsHandle);
+        const deferred = vm.newPromise();
+        const id = nextId++;
+        pending.set(id, deferred);
+        post({ type: 'call', id, name, args });
+        return deferred.handle;
+    });
+    vm.setProp(vm.global, '__host', hostFn);
+    hostFn.dispose();
+    const logFn = vm.newFunction('__log', (lineHandle) => {
+        if (logsTruncated)
+            return;
+        const line = vm.getString(lineHandle);
+        const room = limits.maxLogChars - logs.length;
+        if (line.length + 1 > room) {
+            logs += line.slice(0, Math.max(0, room));
+            logsTruncated = true;
+        }
+        else {
+            logs += (logs ? '\n' : '') + line;
+        }
+    });
+    vm.setProp(vm.global, '__log', logFn);
+    logFn.dispose();
+    const configHandle = vm.newString(JSON.stringify({ functions: message.functions, mode: message.mode, maxParallel: limits.maxParallel }));
+    vm.setProp(vm.global, '__config', configHandle);
+    configHandle.dispose();
+    /** An error the VM threw or rejected with, as the parent reports it. */
+    const describe = (handle) => {
+        const dumped = vm.dump(handle);
+        if (cpuExceeded)
+            return { code: 'CPU_LIMIT', message: `The code ran past its ${limits.cpuMs} ms CPU budget.` };
+        // Out of memory, QuickJS can have no room left for an error object and throws null instead.
+        if (dumped === null || dumped === undefined) {
+            return { code: 'CODE_ERROR', message: `The code threw ${String(dumped)}; code that builds large values throws null when it reaches the ${Math.round(limits.memoryBytes / 1048576)} MB memory limit.` };
+        }
+        const err = dumped && typeof dumped === 'object' ? dumped : { message: String(dumped) };
+        const name = typeof err.name === 'string' ? err.name : 'Error';
+        const text = typeof err.message === 'string' ? err.message : String(dumped);
+        if (/out of memory/i.test(text))
+            return { code: 'MEMORY_LIMIT', message: `The code ran past its ${Math.round(limits.memoryBytes / 1048576)} MB memory limit.` };
+        if (/stack overflow/i.test(text))
+            return { code: 'STACK_LIMIT', message: 'The code overflowed its stack.' };
+        return { code: 'CODE_ERROR', message: `${name}: ${text}` };
+    };
+    const pump = () => {
+        const jobs = compute(() => runtime.executePendingJobs());
+        if (jobs.error) {
+            const error = describe(jobs.error);
+            jobs.error.dispose();
+            finish({ ok: false, error });
+            return false;
+        }
+        if (cpuExceeded) {
+            finish({ ok: false, error: { code: 'CPU_LIMIT', message: `The code ran past its ${limits.cpuMs} ms CPU budget.` } });
+            return false;
+        }
+        return true;
+    };
+    port.on('message', (reply) => {
+        if (finished || reply.type !== 'reply')
+            return;
+        const deferred = pending.get(reply.id);
+        if (!deferred)
+            return;
+        pending.delete(reply.id);
+        if (reply.ok) {
+            if (reply.value === undefined)
+                deferred.resolve();
+            else {
+                const value = vm.newString(reply.value);
+                deferred.resolve(value);
+                value.dispose();
+            }
+        }
+        else {
+            const error = vm.newError({ name: reply.error?.name ?? 'Error', message: reply.error?.message ?? 'the host call failed' });
+            deferred.reject(error);
+            error.dispose();
+        }
+        deferred.dispose();
+        pump();
+    });
+    const prelude = compute(() => vm.evalCode(PRELUDE, 'prelude.js'));
+    if (prelude.error) {
+        finish({ ok: false, error: { code: 'SANDBOX_CRASHED', message: `prelude: ${JSON.stringify(vm.dump(prelude.error))}` } });
+        return;
+    }
+    const invoke = prelude.value;
+    const evaluated = compute(() => vm.evalCode(message.source, 'code.js', { type: 'module' }));
+    if (evaluated.error) {
+        finish({ ok: false, error: describe(evaluated.error) });
+        return;
+    }
+    // A module evaluates to a promise of its namespace (top-level await may hold it open);
+    // resolvePromise attaches its handlers in the VM, which run as pending jobs.
+    const loading = vm.resolvePromise(evaluated.value);
+    if (!pump())
+        return;
+    const loaded = await loading;
+    if (finished)
+        return;
+    if (loaded.error) {
+        finish({ ok: false, error: describe(loaded.error) });
+        return;
+    }
+    const exported = vm.getProp(loaded.value, 'default');
+    if (vm.typeof(exported) !== 'function') {
+        finish({ ok: false, error: { code: 'CODE_ERROR', message: 'The code must `export default` a function; it is called with the input.' } });
+        return;
+    }
+    const valueHandle = vm.newString(message.value);
+    const called = compute(() => vm.callFunction(invoke, vm.undefined, exported, valueHandle));
+    valueHandle.dispose();
+    if (called.error) {
+        finish({ ok: false, error: describe(called.error) });
+        return;
+    }
+    const settling = vm.resolvePromise(called.value);
+    if (!pump())
+        return;
+    const settled = await settling;
+    if (finished)
+        return;
+    if (settled.error) {
+        finish({ ok: false, error: describe(settled.error) });
+        return;
+    }
+    finish({ ok: true, result: vm.getString(settled.value) });
+}

package/dist/lib/script/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * lib/script/config.ts — the `script:` block's shape (ADR 0137 Part B), a
+ * leaf the loader, the schema's types and the runner share.
+ *
+ * The fourth orchestration method: DELEGATE, PLAN-DISPATCH and WORKFLOW
+ * decide the order agents run in, and none can hold logic. A script is one
+ * JavaScript module, run in the engine's sandbox (lib/sandbox/), that calls
+ * the syndicate's own agents, its allowed tools and a person as functions,
+ * so the routing, the per-call model and the pauses live in the syndicate
+ * document and change with a deploy, not an engine release. The runner is
+ * lib/script/run.ts.
+ */
+/** The `script:` block. */
+export interface ScriptConfig {
+    /** One module whose default export is an async function of the script API. Not interpolated. */
+    source: string;
+    /** The models agent(…, { model }) may move a call to; every agent is compiled on each. */
+    models?: string[];
+    /** The registry tools tool(name, args) may run. */
+    tools?: string[];
+    /** Tools from `tools` whose every call waits for a person's approval. */
+    require_approval?: string[];
+    /**
+     * The syndicate's `variables`, bound as the loader bound them (the YAML's
+     * defaults, then the caller's bindings): what the script reads as
+     * `variables`. Written by the loader, never by hand.
+     */
+    variables?: Record<string, string | number | boolean>;
+}
+/** True when this syndicate orchestrates with a script. */
+export declare function isScriptSyndicate(config: {
+    script?: unknown;
+}): config is {
+    script: ScriptConfig;
+};

package/dist/lib/script/config.js

@@ -0,0 +1,17 @@
+/**
+ * lib/script/config.ts — the `script:` block's shape (ADR 0137 Part B), a
+ * leaf the loader, the schema's types and the runner share.
+ *
+ * The fourth orchestration method: DELEGATE, PLAN-DISPATCH and WORKFLOW
+ * decide the order agents run in, and none can hold logic. A script is one
+ * JavaScript module, run in the engine's sandbox (lib/sandbox/), that calls
+ * the syndicate's own agents, its allowed tools and a person as functions,
+ * so the routing, the per-call model and the pauses live in the syndicate
+ * document and change with a deploy, not an engine release. The runner is
+ * lib/script/run.ts.
+ */
+/** True when this syndicate orchestrates with a script. */
+export function isScriptSyndicate(config) {
+    const script = config.script;
+    return !!script && typeof script === 'object' && typeof script.source === 'string';
+}