wave-agent-sdk 1.2.0 → 1.3.0

package/dist/exec/catalogAnnouncement.js

@@ -0,0 +1,293 @@
+/**
+ * The MCP catalog, announced in the conversation instead of the `Exec` tool
+ * description. opencode only made this move on its v2 line (v1 shipped the catalog
+ * inside `execute`'s description, which is what this repo did until now).
+ *
+ * Why it cannot stay in the description: `tools[]` sits inside the cached prefix,
+ * and the catalog is a function of the pool. Every server that connects, drops, or
+ * changes its `tools/list` would rewrite the declaration and take the whole cached
+ * prefix with it. The description is a pool-independent constant now; the catalog is
+ * appended at the tail, where an addition invalidates nothing that already went out.
+ *
+ * State lives in the history, not in the process (same rule as
+ * `utils/mcpInstructions.ts`): each announcement leads with a marker line carrying
+ * the hash of a full catalog body. Three consequences, all deliberate:
+ *  - Once the marker is gone (compaction, rewind), the next turn announces the full
+ *    catalog again. A duplicate is better than a loss.
+ *  - A delta is only emitted while the full catalog it is relative to is still in
+ *    the history. The marker carries that baseline's hash (`bh`) so the check stays
+ *    local: a delta is relative, and without its basis it says nothing.
+ *  - The hash covers rendered text, so editing the renderer re-announces the catalog
+ *    once for existing sessions. That is what buys the invariant "same hash ⇒ the
+ *    same bytes the model read". It is also why a full catalog carries no "this
+ *    supersedes the previous one" preamble: such a line would depend on history, and
+ *    a history-dependent body can never compare equal to a freshly rendered one —
+ *    the session would re-announce on every single turn.
+ */
+import { createHash } from "node:crypto";
+import { renderSearchSignature } from "./catalog.js";
+/** Marks an announcement so the history scan can find it. */
+export const EXEC_CATALOG_MARKER_PREFIX = "<!-- exec-catalog ";
+export const EXEC_CATALOG_MARKER_SUFFIX = " -->";
+/** Opens a full catalog body; the entries follow. */
+const CATALOG_HEADER = "MCP tools reachable inside a sandbox script, called as `tools.<name>` (no other name resolves):";
+/**
+ * What the model is told when a pool it has seen empties. It names no tool on purpose:
+ * with an empty pool `Exec` is not even declared, so naming it would point at something
+ * the model cannot call.
+ *
+ * This text is only ever reached by a session that already read a catalog, which is why
+ * it says "updates may add or remove tools" rather than introducing the concept: to a
+ * session that never had one, "no MCP tools are available" describes a capability it had
+ * no reason to expect (see the `last === null` branch).
+ */
+const EMPTY_POOL_NOTE = "No MCP tools are currently available. Later catalog updates may add or remove tools.";
+/**
+ * What the model is told when the channel closes: `Exec` was switched off, excluded
+ * or denied, so the catalog's calling form no longer exists and the flat
+ * declarations are back. The listed tools are not gone — the way they were listed is.
+ */
+const REMOVED_NOTE = "The MCP tool catalog is no longer available, so the tools an earlier catalog listed cannot be called this way any more. The tool declarations of this session are the current source of truth.";
+const DELTA_HEADER = "The MCP tool catalog has changed:";
+/**
+ * A full catalog body: the header, the rendered entries, and — only when the budget
+ * truncated them — how to reach the rest.
+ *
+ * The search section is the single place the call form is taught (the entry point
+ * stays registered either way, it is merely not advertised). Making it conditional
+ * is what keeps the two statements from drifting: while the catalog is complete,
+ * nothing anywhere claims a search is needed.
+ */
+export function renderFullCatalogNote(catalog) {
+    if (catalog.total === 0)
+        return EMPTY_POOL_NOTE;
+    const parts = [CATALOG_HEADER, catalog.text];
+    if (catalog.truncated) {
+        parts.push("", "The catalog above is partial. Call this to list or search the complete pool:", "", ...renderSearchSignature()
+            .split("\n")
+            .map((line) => `  ${line}`));
+    }
+    return parts.join("\n");
+}
+/** `h` in the marker payload, and the value `bh` points back at. */
+function hashNote(note) {
+    return createHash("sha256").update(note).digest("hex").slice(0, 12);
+}
+/** `{ k, h, t, ns, bh }` — the marker, as one line. */
+function renderMarker(marker) {
+    const payload = { k: marker.kind };
+    if (marker.hash !== undefined)
+        payload.h = marker.hash;
+    if (marker.truncated !== undefined)
+        payload.t = marker.truncated;
+    if (marker.namespaces !== undefined)
+        payload.ns = marker.namespaces;
+    if (marker.base !== undefined)
+        payload.bh = marker.base;
+    return `${EXEC_CATALOG_MARKER_PREFIX}${JSON.stringify(payload)}${EXEC_CATALOG_MARKER_SUFFIX}`;
+}
+/**
+ * Read the announcement state out of the history.
+ *
+ * Only this module's own messages are read: a marker quoted anywhere else — a reply
+ * explaining the mechanism, a hook echoing one — is prose *about* a marker, not a
+ * statement about the pool. Counting it would invent an announcement, and the
+ * invented state then misleads every later turn. A marker that cannot be parsed is
+ * skipped for the same reason (worst case: one duplicate announcement).
+ */
+export function collectExecCatalogState(messages) {
+    const fullHashes = new Set();
+    let last = null;
+    for (const message of messages) {
+        if (message.isMeta !== true)
+            continue;
+        for (const block of message.blocks) {
+            if (block.type !== "text")
+                continue;
+            for (const line of block.content.split("\n")) {
+                const marker = parseMarkerLine(line);
+                if (!marker)
+                    continue;
+                last = marker;
+                if (marker.kind === "full" && marker.hash)
+                    fullHashes.add(marker.hash);
+            }
+        }
+    }
+    return { last, fullHashes };
+}
+function parseMarkerLine(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith(EXEC_CATALOG_MARKER_PREFIX) ||
+        !trimmed.endsWith(EXEC_CATALOG_MARKER_SUFFIX)) {
+        return null;
+    }
+    const payload = trimmed.slice(EXEC_CATALOG_MARKER_PREFIX.length, trimmed.length - EXEC_CATALOG_MARKER_SUFFIX.length);
+    try {
+        const parsed = JSON.parse(payload);
+        const kind = parsed.k;
+        if (kind !== "full" && kind !== "delta" && kind !== "removed")
+            return null;
+        return {
+            kind,
+            hash: typeof parsed.h === "string" ? parsed.h : undefined,
+            truncated: parsed.t === 1 ? 1 : 0,
+            namespaces: readNamespaceCounts(parsed.ns),
+            base: typeof parsed.bh === "string" ? parsed.bh : undefined,
+        };
+    }
+    catch {
+        // A marker we cannot read (hand-edited or truncated history) must not take the
+        // turn down; the worst case is announcing the catalog once more.
+        return null;
+    }
+}
+function readNamespaceCounts(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const counts = {};
+    for (const [name, count] of Object.entries(value)) {
+        if (typeof count !== "number" || !Number.isFinite(count))
+            return undefined;
+        counts[name] = count;
+    }
+    return counts;
+}
+/**
+ * The next announcement for this turn, or null when there is nothing to say.
+ *
+ * The decision table, in order: a channel that was never open says nothing; a closed
+ * channel is announced once; a session that has announced nothing (or whose last word
+ * was the closing notice) gets the full catalog; an unchanged hash says nothing; a
+ * changed pool with its basis still present may go out as a namespace-level delta;
+ * anything else is the full catalog.
+ */
+export function buildExecCatalogAnnouncement(state, current) {
+    const last = state.last;
+    if (current === undefined) {
+        // Nothing was ever announced, so there is nothing to retract: most sessions have
+        // no `Exec` at all, and a closing notice there would be a message about a channel
+        // the model never saw. Silence, not "observed absence".
+        if (last === null)
+            return null;
+        // `removed` carries no hash: the channel is not a catalog, so there is nothing
+        // to compare. Re-opening it therefore always re-announces in full, even when the
+        // pool never moved — going by content here would leave the session mute forever
+        // after a switch was flipped off and back on.
+        if (last.kind === "removed")
+            return null;
+        return envelope({ kind: "removed" }, REMOVED_NOTE);
+    }
+    const note = renderFullCatalogNote(current);
+    const hash = hashNote(note);
+    const namespaces = namespaceCounts(current);
+    const full = {
+        kind: "full",
+        hash,
+        truncated: current.truncated ? 1 : 0,
+        namespaces,
+    };
+    if (last === null) {
+        // A session that never had a catalog has nothing to learn from "there is nothing":
+        // with an empty pool `Exec` is not even declared, so the note points at no tool the
+        // model can see or call. It is announced only to a session that has already seen a
+        // catalog, where "the catalog is now empty" is a change rather than a first word.
+        return current.total === 0 ? null : envelope(full, note);
+    }
+    if (last.kind === "removed")
+        return envelope(full, note);
+    if (last.hash === hash) {
+        // The pool renders identically, so an unchanged turn stays silent — unless the
+        // last word was a delta whose basis has since been compacted away: nothing the
+        // model can still see describes the catalog then, so it is re-announced in full.
+        if (last.kind === "delta" && !hasBasis(last, state)) {
+            return envelope(full, note);
+        }
+        return null;
+    }
+    if (!hasBasis(last, state))
+        return envelope(full, note);
+    const changed = chooseChangedAnnouncement(last, current, note, namespaces, hash);
+    return changed;
+}
+/**
+ * Is the full catalog a delta would be relative to still in the history? For a
+ * `full` last word that is the message itself; for a delta it is the anchor it
+ * passed along its chain.
+ */
+function hasBasis(last, state) {
+    const anchor = last.kind === "full" ? last.hash : last.base;
+    return anchor !== undefined && state.fullHashes.has(anchor);
+}
+/**
+ * Delta or full catalog, for a pool that changed while the basis is still present.
+ *
+ * Namespace counts are all a marker carries, so a delta can only say "this server
+ * appeared / changed size / went away" — never a signature. That is enough only
+ * while the catalog is truncated (the model already has the entries it can see) and
+ * only when some count actually moved. Otherwise the entries themselves are what
+ * changed, and only the full catalog can say how.
+ */
+function chooseChangedAnnouncement(last, current, note, namespaces, hash) {
+    const full = {
+        kind: "full",
+        hash,
+        truncated: current.truncated ? 1 : 0,
+        namespaces,
+    };
+    const truncated = current.truncated ? 1 : 0;
+    if (last.truncated !== truncated || !current.truncated) {
+        return envelope(full, note);
+    }
+    const delta = renderDeltaNote(last, current);
+    // A delta is a means, not an end: when it is no longer the shorter of the two
+    // (a wholesale server swap, say) the full catalog wins.
+    if (delta === null || delta.length >= note.length) {
+        return envelope(full, note);
+    }
+    return envelope({
+        kind: "delta",
+        hash,
+        truncated,
+        namespaces,
+        base: last.kind === "full" ? last.hash : last.base,
+    }, delta);
+}
+/**
+ * The namespace-level differences between two snapshots, or null when the counts
+ * are identical (nothing a delta could say).
+ */
+function renderDeltaNote(last, current) {
+    const before = last.namespaces;
+    if (!before)
+        return null;
+    const after = namespaceCounts(current);
+    const lines = [];
+    for (const [name, count] of Object.entries(after)) {
+        const previous = before[name];
+        if (previous === undefined) {
+            lines.push(`- \`mcp__${name}\` is now available (${tools(count)}). Search it for signatures.`);
+        }
+        else if (previous !== count) {
+            lines.push(`- \`mcp__${name}\` now has ${tools(count)} (was ${previous}). ` +
+                "Search it again before relying on results from before this change.");
+        }
+    }
+    for (const name of Object.keys(before)) {
+        if (after[name] === undefined) {
+            lines.push(`- \`mcp__${name}\` is no longer available and must not be used.`);
+        }
+    }
+    if (lines.length === 0)
+        return null;
+    return [DELTA_HEADER, ...lines].join("\n");
+}
+function tools(count) {
+    return `${count} tool${count === 1 ? "" : "s"}`;
+}
+function namespaceCounts(catalog) {
+    return Object.fromEntries(catalog.namespaces.map((namespace) => [namespace.name, namespace.count]));
+}
+function envelope(marker, body) {
+    return `${renderMarker(marker)}\n${body}`;
+}

package/dist/exec/constants.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Exec sandbox constants.
+ *
+ * Almost everything here is a tunable default, not a contract. In particular no
+ * *knob* may be rendered into model-visible text: the catalog has to stay
+ * byte-identical for an unchanged MCP pool, so changing a budget must not change
+ * what the model reads (see `Exec`'s description and
+ * `exec/catalogAnnouncement.ts`).
+ *
+ * The exception is `EXEC_RESERVED_NAMESPACE`: it is part of the sandbox API
+ * surface, so the tool description has to name it (and it is derived from the
+ * same constant, so the two cannot drift).
+ */
+/**
+ * Wall-clock budget for one Exec script. The parent terminates the sandbox
+ * worker when it expires, so a script blocked in `await` is killed instead of
+ * spinning on the host event loop forever.
+ */
+export declare const EXEC_DEFAULT_TIMEOUT_MS = 60000;
+/** Maximum number of sandbox -> host tool calls per Exec script. */
+export declare const EXEC_DEFAULT_MAX_TOOL_CALLS = 50;
+/** Maximum number of `console` output characters returned to the model. */
+export declare const EXEC_DEFAULT_MAX_LOG_CHARS = 8000;
+/**
+ * Maximum number of characters of the *script return value* handed back to the
+ * model. Mirrors the `DEFAULT_MAX_RESULT_SIZE_CHARS` bound that the flat MCP and
+ * Bash paths apply to their own results: without it a script could return a
+ * payload far larger than the call it replaced would have produced.
+ */
+export declare const EXEC_DEFAULT_MAX_RESULT_CHARS = 100000;
+/** Maximum number of images propagated from nested MCP calls. */
+export declare const EXEC_DEFAULT_MAX_IMAGES = 4;
+/**
+ * Maximum size of the MCP catalog, in estimated tokens (a plain `chars / 4`; see
+ * `estimateCatalogTokens`).
+ *
+ * Provenance: opencode's `catalogBudget` — `defaultCatalogBudget = 2_000` in
+ * `packages/codemode/src/tool-runtime.ts`. Deliberately not CJK-aware: MCP tool
+ * descriptions are overwhelmingly English. Tunable, not a contract.
+ */
+export declare const EXEC_DEFAULT_CATALOG_TOKENS = 2000;
+/**
+ * Reserved property on the sandbox `tools` object hosting search. The `$`
+ * prefix cannot collide with an MCP tool name (`[A-Za-z0-9_.-]`).
+ */
+export declare const EXEC_RESERVED_NAMESPACE = "$codemode";
+/**
+ * Internal name the sandbox uses to reach host-side catalog search. Matches the
+ * sandbox path `tools.$codemode.search` but never appears in model-visible text.
+ */
+export declare const EXEC_SEARCH_CALL = "$codemode.search";

package/dist/exec/constants.js

@@ -0,0 +1,51 @@
+/**
+ * Exec sandbox constants.
+ *
+ * Almost everything here is a tunable default, not a contract. In particular no
+ * *knob* may be rendered into model-visible text: the catalog has to stay
+ * byte-identical for an unchanged MCP pool, so changing a budget must not change
+ * what the model reads (see `Exec`'s description and
+ * `exec/catalogAnnouncement.ts`).
+ *
+ * The exception is `EXEC_RESERVED_NAMESPACE`: it is part of the sandbox API
+ * surface, so the tool description has to name it (and it is derived from the
+ * same constant, so the two cannot drift).
+ */
+/**
+ * Wall-clock budget for one Exec script. The parent terminates the sandbox
+ * worker when it expires, so a script blocked in `await` is killed instead of
+ * spinning on the host event loop forever.
+ */
+export const EXEC_DEFAULT_TIMEOUT_MS = 60000;
+/** Maximum number of sandbox -> host tool calls per Exec script. */
+export const EXEC_DEFAULT_MAX_TOOL_CALLS = 50;
+/** Maximum number of `console` output characters returned to the model. */
+export const EXEC_DEFAULT_MAX_LOG_CHARS = 8000;
+/**
+ * Maximum number of characters of the *script return value* handed back to the
+ * model. Mirrors the `DEFAULT_MAX_RESULT_SIZE_CHARS` bound that the flat MCP and
+ * Bash paths apply to their own results: without it a script could return a
+ * payload far larger than the call it replaced would have produced.
+ */
+export const EXEC_DEFAULT_MAX_RESULT_CHARS = 100000;
+/** Maximum number of images propagated from nested MCP calls. */
+export const EXEC_DEFAULT_MAX_IMAGES = 4;
+/**
+ * Maximum size of the MCP catalog, in estimated tokens (a plain `chars / 4`; see
+ * `estimateCatalogTokens`).
+ *
+ * Provenance: opencode's `catalogBudget` — `defaultCatalogBudget = 2_000` in
+ * `packages/codemode/src/tool-runtime.ts`. Deliberately not CJK-aware: MCP tool
+ * descriptions are overwhelmingly English. Tunable, not a contract.
+ */
+export const EXEC_DEFAULT_CATALOG_TOKENS = 2000;
+/**
+ * Reserved property on the sandbox `tools` object hosting search. The `$`
+ * prefix cannot collide with an MCP tool name (`[A-Za-z0-9_.-]`).
+ */
+export const EXEC_RESERVED_NAMESPACE = "$codemode";
+/**
+ * Internal name the sandbox uses to reach host-side catalog search. Matches the
+ * sandbox path `tools.$codemode.search` but never appears in model-visible text.
+ */
+export const EXEC_SEARCH_CALL = "$codemode.search";

package/dist/exec/execRuntime.d.ts

@@ -0,0 +1,55 @@
+import type { ToolContext } from "../tools/types.js";
+import type { ExecPoolEntry } from "./catalog.js";
+export interface RunExecOptions {
+    code: string;
+    /** Every MCP tool the sandbox may call. Also the allowlist for nested calls. */
+    pool: ExecPoolEntry[];
+    context: ToolContext;
+    /**
+     * Called as each nested call is issued, before it is dispatched, in the order
+     * the script issues them. Lets the caller show live progress; a call that is
+     * refused afterwards (over the limit) still reports.
+     */
+    onToolCall?: (name: string) => void;
+    timeoutMs?: number;
+    maxToolCalls?: number;
+    maxLogChars?: number;
+    maxResultChars?: number;
+}
+export interface ExecCallResult {
+    /**
+     * What the script's `await` resolves to — the tool's structured output, else its
+     * text, else `null` (the rule `renderToolSignature` promises in the catalog).
+     * Plain JSON only: it crosses the worker boundary and is deep-cloned inside the
+     * sandbox.
+     */
+    output: unknown;
+    /**
+     * Images to hoist onto the `Exec` result. Never seen by the script: a nested call
+     * resolves to the tool's output, and an image is not something a script composes
+     * with.
+     */
+    images?: Array<{
+        data: string;
+        mediaType?: string;
+    }>;
+}
+export interface ExecRunResult {
+    ok: boolean;
+    /** Serialized script return value. Only set when `ok`. */
+    value?: string;
+    error?: string;
+    logs: string[];
+    toolCalls: number;
+    images: Array<{
+        data: string;
+        mediaType?: string;
+    }>;
+}
+/**
+ * Run one Exec script in a terminable sandbox worker.
+ *
+ * Never rejects: every failure mode (script throw, budget, abort, worker crash)
+ * comes back as `{ ok: false, error }` so the model gets a result to act on.
+ */
+export declare function runExecScript(options: RunExecOptions): Promise<ExecRunResult>;

package/dist/exec/execRuntime.js

@@ -0,0 +1,217 @@
+/**
+ * Parent-side driver for the Exec sandbox worker.
+ *
+ * Owns everything the sandbox must not: the MCP pool, the permission context,
+ * the wall-clock budget and termination. The sandbox only ever sends plain
+ * JSON (`{ name, args }`) and only ever receives plain JSON back.
+ */
+import { Worker } from "node:worker_threads";
+import { logger } from "../utils/globalLogger.js";
+import { EXEC_DEFAULT_MAX_IMAGES, EXEC_DEFAULT_MAX_LOG_CHARS, EXEC_DEFAULT_MAX_RESULT_CHARS, EXEC_DEFAULT_MAX_TOOL_CALLS, EXEC_DEFAULT_TIMEOUT_MS, EXEC_RESERVED_NAMESPACE, EXEC_SEARCH_CALL, } from "./constants.js";
+import { EXEC_WORKER_SOURCE } from "./workerSource.js";
+import { renderSearchCallForm, renderToolSignature, resolveSearchQuery, } from "./catalog.js";
+const DYNAMIC_IMPORT_PATTERN = /dynamic import callback/i;
+/**
+ * Rewrite engine-internal messages the model cannot act on into something it
+ * can. `node:vm` refuses `import()` with an internal-sounding message that
+ * mentions a callback the model has no way to know about.
+ */
+function humanizeError(message) {
+    if (DYNAMIC_IMPORT_PATTERN.test(message)) {
+        return "import() is not available inside Exec";
+    }
+    return message;
+}
+async function handleExecCall(name, args, pool, context) {
+    if (name === EXEC_SEARCH_CALL) {
+        // The shape is validated against the schema the tool description renders from,
+        // not by hand — see `resolveSearchQuery`.
+        const query = resolveSearchQuery(args);
+        const matches = [...pool.values()].filter((entry) => {
+            if (query.length === 0)
+                return true;
+            return (entry.name.toLowerCase().includes(query) ||
+                (entry.description ?? "").toLowerCase().includes(query));
+        });
+        // Return the same rendered signature the catalog shows, not the raw schema,
+        // so a hit can be copied verbatim into a call. Rendering is done on the
+        // matched entries only, never the whole pool. The value is the array itself,
+        // not its JSON text — same rule as an MCP call: a script composes values, and
+        // making it parse a string first is the kind of extra step a signature should
+        // not have to mention.
+        return {
+            output: matches.map((entry) => ({
+                name: entry.name,
+                description: entry.description,
+                signature: renderToolSignature(entry),
+            })),
+        };
+    }
+    if (!pool.has(name)) {
+        throw new Error(`Unknown tool "${name}". Only MCP tools are reachable from Exec. ` +
+            `Use ${renderSearchCallForm()} to find one.`);
+    }
+    const mcpManager = context.mcpManager;
+    if (!mcpManager) {
+        throw new Error("MCP manager is not available in the Exec context");
+    }
+    // The single MCP funnel: it runs the permission/approval check internally and
+    // keys it on the flattened name, so a nested call is approved exactly like a
+    // flat MCP call.
+    const result = await mcpManager.executeMcpTool(name, args, context);
+    return { output: result.output, images: result.images };
+}
+function terminate(worker) {
+    worker.terminate().catch(() => {
+        /* already gone */
+    });
+}
+/**
+ * Run one Exec script in a terminable sandbox worker.
+ *
+ * Never rejects: every failure mode (script throw, budget, abort, worker crash)
+ * comes back as `{ ok: false, error }` so the model gets a result to act on.
+ */
+export function runExecScript(options) {
+    const timeoutMs = options.timeoutMs ?? EXEC_DEFAULT_TIMEOUT_MS;
+    const maxToolCalls = options.maxToolCalls ?? EXEC_DEFAULT_MAX_TOOL_CALLS;
+    const maxLogChars = options.maxLogChars ?? EXEC_DEFAULT_MAX_LOG_CHARS;
+    const maxResultChars = options.maxResultChars ?? EXEC_DEFAULT_MAX_RESULT_CHARS;
+    const pool = new Map(options.pool.map((entry) => [entry.name, entry]));
+    const images = [];
+    return new Promise((resolve) => {
+        const worker = new Worker(EXEC_WORKER_SOURCE, { eval: true });
+        let settled = false;
+        let toolCalls = 0;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(budget);
+            options.context.abortSignal?.removeEventListener("abort", onAbort);
+            terminate(worker);
+            resolve(result);
+        };
+        const budget = setTimeout(() => {
+            finish({
+                ok: false,
+                error: `Exec script exceeded the ${timeoutMs}ms budget and was terminated. ` +
+                    `Tool calls that already completed still apply.`,
+                logs: [],
+                toolCalls,
+                images,
+            });
+        }, timeoutMs);
+        const onAbort = () => {
+            finish({
+                ok: false,
+                error: "Exec script was aborted.",
+                logs: [],
+                toolCalls,
+                images,
+            });
+        };
+        if (options.context.abortSignal?.aborted) {
+            onAbort();
+            return;
+        }
+        options.context.abortSignal?.addEventListener("abort", onAbort, {
+            once: true,
+        });
+        worker.on("message", (message) => {
+            if (settled)
+                return;
+            if (message.kind === "call") {
+                const call = message;
+                toolCalls += 1;
+                options.onToolCall?.(call.name);
+                if (toolCalls > maxToolCalls) {
+                    worker.postMessage({
+                        kind: "result",
+                        id: call.id,
+                        ok: false,
+                        error: `Exec tool-call limit reached (${maxToolCalls}).`,
+                    });
+                    return;
+                }
+                handleExecCall(call.name, call.args, pool, options.context).then((result) => {
+                    if (result.images?.length) {
+                        for (const image of result.images) {
+                            if (images.length < EXEC_DEFAULT_MAX_IMAGES)
+                                images.push(image);
+                        }
+                    }
+                    if (settled)
+                        return;
+                    worker.postMessage({
+                        kind: "result",
+                        id: call.id,
+                        ok: true,
+                        value: result.output,
+                    });
+                }, (error) => {
+                    if (settled)
+                        return;
+                    worker.postMessage({
+                        kind: "result",
+                        id: call.id,
+                        ok: false,
+                        error: humanizeError(error instanceof Error ? error.message : String(error)),
+                    });
+                });
+                return;
+            }
+            if (message.kind === "done") {
+                const done = message;
+                const logs = Array.isArray(done.logs) ? done.logs : [];
+                if (done.ok) {
+                    finish({
+                        ok: true,
+                        value: done.value,
+                        logs,
+                        toolCalls,
+                        images,
+                    });
+                }
+                else {
+                    finish({
+                        ok: false,
+                        error: humanizeError(done.error ?? "Exec script failed"),
+                        logs,
+                        toolCalls,
+                        images,
+                    });
+                }
+            }
+        });
+        worker.on("error", (error) => {
+            logger.error(`[Exec] sandbox worker error: ${error.message}`);
+            finish({
+                ok: false,
+                error: humanizeError(error.message),
+                logs: [],
+                toolCalls,
+                images,
+            });
+        });
+        worker.on("exit", (code) => {
+            finish({
+                ok: false,
+                error: `Exec sandbox exited unexpectedly (code ${code})`,
+                logs: [],
+                toolCalls,
+                images,
+            });
+        });
+        worker.postMessage({
+            kind: "run",
+            code: options.code,
+            toolNames: options.pool.map((entry) => entry.name),
+            searchName: EXEC_SEARCH_CALL,
+            reservedNamespace: EXEC_RESERVED_NAMESPACE,
+            timeoutMs,
+            maxLogChars,
+            maxResultChars,
+        });
+    });
+}