@nodetool-ai/agents 0.7.0-rc.23 → 0.8.2

package/dist/js-sandbox.js

@@ -1,27 +1,79 @@
 /**
  * Shared sandboxed JavaScript execution engine.
  *
- * Used by both the MiniJSAgentTool (agent tool) and the CodeNode (workflow node).
+ * Used by the CodeAct executor (agent actions) and the CodeNode (workflow node).
  * Runs user code in an isolated QuickJS WebAssembly context — the guest has its
  * own heap inside the WASM instance, so there is a real memory/CPU boundary
  * between host and guest (unlike Node's `node:vm`, which shares the V8 heap).
  *
  * The exposed surface is a small curated one: vanilla JavaScript plus a handful
- * of bridge functions (`fetch`, `workspace`, `getSecret`, `uuid`, `sleep`,
- * `assetToSandbox`, `sandboxToAsset`, `console`). Library-powered helpers
- * (lodash, dayjs, cheerio, csv-parse,
- * validator) are intentionally NOT exposed here — use the dedicated workflow
- * nodes instead (lib.datetime.*, lib.html.*, lib.data.ParseCSV,
- * lib.validate.*, etc.). Keeping the sandbox lib-free makes snippet behaviour
- * identical between dev and packaged Electron, and avoids shipping those
- * packages into the user-code surface.
+ * of bridge functions (`fetch`, `workspace`, `getSecret`, `sleep`,
+ * `assetToSandbox`, `sandboxToAsset`, `crypto`, `console`, `progress`,
+ * `format`, `image`, `canvas`) and a few pure guest-side helpers
+ * (`toBase64`, `fromBase64`, `toHex`, `fromHex`,
+ * `parallelMap`, `createCanvas`). `crypto`
+ * covers `randomUUID`, `getRandomValues`, `digest`, and `hmac`
+ * (WebCrypto-backed); `workspace` covers text and binary reads/writes plus
+ * `stat`, `mkdir`, and `remove`; `progress` forwards a percentage and label to
+ * the host caller (rate-limited); `console.*` appends to the run's `logs`
+ * array and, when the caller set {@link RunSandboxOptions.onLog}, forwards
+ * each line live (capped); `format` exposes host `Intl` number, date,
+ * relative-time and list formatting, which QuickJS itself does not ship.
+ * Every quantitative limit (fetch calls, response body, output size,
+ * guest heap, stack, fetch timeout) is overridable per invocation through
+ * `RunSandboxOptions.limits`, clamped to hard ceilings.
+ *
+ * The guest imports nothing by default — without `RunSandboxOptions.modules`
+ * every specifier is denied by name, so user code cannot `import`/`require`
+ * anything. With it, the run's resolved sandbox packages and their intra-pack
+ * siblings are the only importable modules (see {@link createGuestModuleHost}),
+ * and dynamic `import()` stays denied.
+ *
+ * **Every library the sandbox offers is an importable module.** Some are guest
+ * modules the compiler admitted (js-yaml, date-fns); the rest are *host
+ * modules* — papaparse, cheerio, exceljs, fflate and friends — which run on the
+ * host behind a generated ESM facade over a per-run dispatcher
+ * (`host-modules/`), because they need Node builtins the guest lacks or carry a
+ * limit the guest could not enforce. Either way the guest writes `import`, and
+ * the pack has to be installed. The remaining globals — `fetch`,
+ * `workspace`, `getSecret`, the asset bridges, `format.*` (Intl), `crypto.*`
+ * (WebCrypto), `image.*`/`canvas.*` — are not libraries: they are the
+ * capabilities the node granted this run.
+ *
+ * The sandbox is fully asynchronous. Every host bridge call returns a real
+ * promise, and a bridge call starts its host-side work the moment it is
+ * invoked — not when it is awaited — so `Promise.all` (and `allSettled`,
+ * `race`, `any`) over bridge calls runs them in parallel on the host. Five
+ * fetches under `Promise.all` take one round trip, not five. `parallelMap`
+ * is the bounded form of that fan-out. `sleep` is the only timer: the
+ * timer globals (`setTimeout` and friends) are deleted inside the user-code
+ * module (see {@link wrapCode}), because timer callbacks would run outside
+ * the never-reject/abort-guard conventions every bridge follows.
  */
-import { addSerializer, expose, loadQuickJs } from "@sebastianwessel/quickjs";
-// The variant package uses a `default` export. With `esModuleInterop` this
-// typechecks as a namespace, so reach through `.default` explicitly.
+import { SANDBOX_CAPABILITY_DISPATCH_GLOBAL, SANDBOX_WASM_DISPATCH_GLOBAL } from "@nodetool-ai/protocol";
+import { createSandboxHostDispatcher } from "./host-modules/dispatcher.js";
+import { EXPOSED_BRIDGE_NAMES, MAX_ENGINE_TIMEOUT_MS, NO_INPUT_STREAM_MESSAGE, registerTypedArraySerializers, runInterpreter, SANDBOX_CAPABILITY_BRIDGE_BINDING, SANDBOX_INPUT_TAKE_BINDING, SANDBOX_STREAM_OPEN_BINDING, SANDBOX_WASM_BRIDGE_BINDING } from "./js-sandbox-worker/interpreter.js";
+import { SANDBOX_SERIALIZE_MAX_DEPTH, toGuestBytes, toGuestBytesDeep } from "./sandbox-bytes.js";
+import { isBoolean, isFunction, isNonEmptyString, isNumber, isObjectLike, isRecord, isString } from "./utils/type-guards.js";
+import { createSandboxMediaStore, isSandboxMediaHandle, MAX_RUN_MEDIA_BYTES } from "./sandbox-media-handle.js";
+import { createMediaRefBridge, looksLikeMediaRef, mimeForRef, remapMediaRef, resolveRefBytes } from "./sandbox-media-ref.js";
+import { createSandboxWasmDispatcher } from "./wasm-sandbox/host.js";
+import { runInWorker } from "./js-sandbox-worker/host.js";
+import { assertFetchUrlAllowed, assertResolvedHostAllowed } from "./network-guard.js";
+import { GUEST_GLOBALS_JSON_BINDING, GUEST_GLOBALS_SIDECAR_BINDING, GUEST_MARSHAL_GLOBAL } from "./sandbox-json-transport.js";
+import { MAX_RANDOM_BYTES } from "./sandbox-constants.js";
+import { deriveBridgeShape, precheckCloneSafety, SANDBOX_DISPATCHER_BINDINGS } from "./js-sandbox-worker/protocol.js";
 import * as quickJsVariantModule from "@jitl/quickjs-ng-wasmfile-release-sync";
+/**
+ * The variant package is CJS with a `default` export, so `ns.default` is the
+ * variant at runtime.
+ */
+// SAFETY: TypeScript's CJS interop synthesizes `default` as the whole module
+// object, contradicting the package's own `.d.ts`, which declares it as the
+// `QuickJSSyncVariant` this reads.
 const quickJsVariant = quickJsVariantModule.default;
-import { Scope } from "quickjs-emscripten-core";
+import { importNodeBuiltin } from "@nodetool-ai/config";
+import { loadSandboxEngine } from "./js-sandbox-worker/engine.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -34,77 +86,185 @@ export const MAX_RESPONSE_BODY_SIZE = 1_000_000;
 export const GUEST_MEMORY_LIMIT = 64 * 1024 * 1024;
 /** Guest stack cap — protects against deeply recursive code. */
 export const GUEST_STACK_LIMIT = 512 * 1024;
+/** Per-request wall-clock cap for the fetch bridge. */
+export const FETCH_TIMEOUT_MS = 15_000;
+/** Redirect hops the fetch bridge follows before giving up. */
+export const MAX_FETCH_REDIRECTS = 5;
+/** Locale used by the `format` bridge when the caller names none. */
+export const DEFAULT_FORMAT_LOCALE = "en-US";
+export { MAX_RANDOM_BYTES };
+/** Progress reports forwarded to the host per run; further calls are dropped. */
+export const MAX_PROGRESS_CALLS = 1000;
+/** Console lines forwarded to {@link RunSandboxOptions.onLog} per run. */
+export const MAX_CONSOLE_LOGS = 1000;
+/** Longest console line forwarded to the host. A collected line is not truncated on its own. */
+export const MAX_CONSOLE_LOG_CHARS = 4000;
+/**
+ * Console lines the run's `logs` array collects. Forwarding was capped and
+ * collection was not: guest strings are not charged to the QuickJS heap, so a
+ * `console.log` in a hot loop grew host memory for the length of the action.
+ */
+export const MAX_COLLECTED_CONSOLE_LOGS = 5000;
+/** Characters the run's `logs` array collects in total, across every line. */
+export const MAX_COLLECTED_CONSOLE_CHARS = 512 * 1024;
+/** The single line that closes a collected log the caps cut. */
+export const CONSOLE_LOGS_CUT_NOTICE = `[console output cut: at most ${MAX_COLLECTED_CONSOLE_LOGS} lines / ` +
+    `${MAX_COLLECTED_CONSOLE_CHARS} characters are kept per run]`;
+/**
+ * Emitted values a run may deliver. Unlike progress reports, emits are never
+ * dropped or rate-limited — every value reaches the host in call order — so the
+ * cap is enforced by throwing in the guest rather than by ignoring the call.
+ */
+export const MAX_EMIT_CALLS = 10_000;
+/** Minimum gap between two forwarded progress reports. */
+export const PROGRESS_MIN_INTERVAL_MS = 100;
+/** Longest progress message forwarded to the host. */
+export const MAX_PROGRESS_MESSAGE_CHARS = 500;
+/**
+ * Headroom added to the engine's own wall-clock abort when a {@link SandboxClock}
+ * is in play. The clock only stops the *guest's* budget; this bounds how long a
+ * run may stay suspended in total, so a prompt nobody ever answers still ends.
+ */
+export const DEFAULT_SUSPEND_ALLOWANCE_MS = 30 * 60 * 1000;
+/**
+ * Suspension allowance a run with an input stream gets by default.
+ *
+ * Effectively unbounded, deliberately: a streaming body legitimately lives as
+ * long as its upstream produces, and the run's own cancellation is the lifetime
+ * bound. A stream that never ends is the upstream's bug, surfaced by the
+ * runner — not a reason to kill a correct consumer. A caller that wants a
+ * shorter leash passes {@link RunSandboxOptions.suspendAllowanceMs}.
+ */
+export const INPUT_STREAM_SUSPEND_ALLOWANCE_MS = MAX_ENGINE_TIMEOUT_MS;
+/**
+ * What the guest is told when it calls `stream` in a run that has no input
+ * stream behind it. Shared by the host bridge and the guest prelude so both
+ * paths say the same thing — the prelude lives with the interpreter, so the
+ * message does too.
+ */
+export { NO_INPUT_STREAM_MESSAGE } from "./js-sandbox-worker/interpreter.js";
+/**
+ * Normalize a declared secret scope: a list of non-empty names, or `null` for
+ * an unscoped run. An empty declared list stays empty — it denies everything.
+ */
+function resolveSecretScope(scope) {
+    if (!Array.isArray(scope))
+        return null;
+    return scope
+        .filter((name) => typeof name === "string" && name !== "")
+        .map((name) => name.trim())
+        .filter((name) => name !== "");
+}
+function clampLimit(value, fallback, min, max) {
+    if (value == null || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+/** Apply defaults and ceilings to a caller-supplied {@link SandboxLimits}. */
+export function resolveSandboxLimits(limits) {
+    return {
+        maxFetchCalls: clampLimit(limits?.maxFetchCalls, MAX_FETCH_CALLS, 0, 100),
+        maxResponseBodyBytes: clampLimit(limits?.maxResponseBodyBytes, MAX_RESPONSE_BODY_SIZE, 1024, 50 * 1024 * 1024),
+        maxOutputSize: clampLimit(limits?.maxOutputSize, MAX_OUTPUT_SIZE, 1024, 10 * 1024 * 1024),
+        memoryLimitBytes: clampLimit(limits?.memoryLimitBytes, GUEST_MEMORY_LIMIT, 1024 * 1024, 512 * 1024 * 1024),
+        runMediaBytes: clampLimit(limits?.runMediaBytes, MAX_RUN_MEDIA_BYTES, 1024 * 1024, 2 * 1024 * 1024 * 1024),
+        stackLimitBytes: clampLimit(limits?.stackLimitBytes, GUEST_STACK_LIMIT, 16 * 1024, 8 * 1024 * 1024),
+        fetchTimeoutMs: clampLimit(limits?.fetchTimeoutMs, FETCH_TIMEOUT_MS, 100, 120_000),
+        // Not clamped — these are capability switches, not magnitudes. Both
+        // resolve to the restrictive value unless the host explicitly opts out.
+        allowPrivateNetwork: limits?.allowPrivateNetwork === true,
+        userAgent: limits?.userAgent ?? "",
+        filesystemAccess: limits?.filesystemAccess === "host" ? "host" : "workspace",
+        secretScope: resolveSecretScope(limits?.secretScope)
+    };
+}
 // ---------------------------------------------------------------------------
 // Engine bootstrap — one WASM module shared by every invocation.
 // ---------------------------------------------------------------------------
 let enginePromise = null;
-let serializersRegistered = false;
-function registerTypedArraySerializers() {
-    if (serializersRegistered)
-        return;
-    serializersRegistered = true;
-    // Map every typed-array class to a native Uint8Array on the host side.
-    // The guest returns `new Uint8Array([...])` (or friends); without this,
-    // the library's generic object serializer produces a plain object with
-    // numeric keys, which downstream code (CodeNode's normalizeOutput) would
-    // miss when detecting binary values.
-    const typedArrayNames = [
-        "Uint8Array",
-        "Int8Array",
-        "Uint8ClampedArray",
-        "Int16Array",
-        "Uint16Array",
-        "Int32Array",
-        "Uint32Array",
-        "Float32Array",
-        "Float64Array"
-    ];
-    for (const name of typedArrayNames) {
-        addSerializer(name, (ctx, handle) => {
-            const bufferHandle = ctx.getProp(handle, "buffer");
-            try {
-                const ab = ctx.getArrayBuffer(bufferHandle);
-                return Uint8Array.from(ab.value);
-            }
-            finally {
-                bufferHandle.dispose();
-            }
-        });
-    }
-}
 function getEngine() {
     registerTypedArraySerializers();
     if (!enginePromise) {
-        enginePromise = loadQuickJs(quickJsVariant);
+        enginePromise = loadSandboxEngine(quickJsVariant);
     }
     return enginePromise;
 }
 /**
- * Marker key placed on an object to signal a sandboxed error. A host async
- * function that would normally `throw` instead resolves with one of these
- * objects; a prelude inside the guest rewraps them as real guest-side errors.
+ * The guest engine can fail in two ways that never reach `runInSandbox`'s own
+ * `await`, and both used to end the same way: the host process died, the tool
+ * call it was serving returned *nothing*, and the agent driving it saw a turn
+ * that simply stopped. A missing result is worse than any error — there is
+ * nothing to read and nothing to retry.
+ *
+ * 1. An Emscripten `abort()` (the `list_empty(&rt->gc_obj_list)` assertion in
+ *    `JS_FreeRuntime`) surfaces as a `RuntimeError` from the WASM module.
+ * 2. A marshaling failure — most often guest OOM while a host return value is
+ *    being written into the guest — throws inside a promise continuation the
+ *    library created and never catches, so it lands as an unhandled rejection.
  *
- * This indirection exists because the current `@sebastianwessel/quickjs`
- * runtime leaks handles whenever a host-backed guest Promise is *rejected*,
- * tripping an internal assertion (`list_empty(&rt->gc_obj_list)`) in
- * quickjs-ng when the runtime is freed. Routing failures through a resolved
- * tagged value sidesteps the leak while preserving the guest-visible
- * behaviour (the user still gets a thrown Error with name + message).
+ * `guardHostProcess` races the run against those escapes. A rejection that
+ * looks like the engine's fails the run; anything else is re-thrown on the next
+ * tick so a genuine host bug still crashes the way it should.
  */
-const SANDBOX_ERROR_MARKER = "__nodetool_sandbox_error__";
-function neverReject(fn) {
-    return async (...args) => {
-        try {
-            return await fn(...args);
-        }
-        catch (e) {
-            return {
-                [SANDBOX_ERROR_MARKER]: true,
-                name: e instanceof Error ? e.name : "Error",
-                message: e instanceof Error ? e.message : String(e)
-            };
-        }
-    };
+function isEngineFailure(error) {
+    const name = error?.constructor?.name ?? "";
+    const message = String(error?.message ?? error);
+    const stack = String(error?.stack ?? "");
+    return (name.startsWith("QuickJS") ||
+        message.includes("Assertion failed") ||
+        message.includes("gc_obj_list") ||
+        /\bAborted\(/.test(message) ||
+        stack.includes("quickjs"));
+}
+/** The agent-facing translation of an engine failure. */
+export function describeEngineFailure(error) {
+    const message = String(error?.message ?? error);
+    if (/gc_obj_list|Assertion failed|\bAborted\(/.test(message)) {
+        return ("The JavaScript sandbox runtime aborted while cleaning up, so this " +
+            "action has no usable result. Host operations may already have completed. " +
+            "This is an internal sandbox cleanup failure. Inspect the execution " +
+            "before retrying any operation that writes data.");
+    }
+    if (/out of memory/i.test(message)) {
+        return ("The JavaScript sandbox ran out of guest memory, so this action " +
+            "produced no result. Retry with less data held live at once.");
+    }
+    return message;
+}
+async function guardHostProcess(run) {
+    // `process` is a Node global; the browser bundle (the in-process fallback
+    // path there) has none, and there is no host process to guard against an
+    // engine abort escaping as an unhandled rejection anyway.
+    const nodeProcess = globalThis.process;
+    if (!nodeProcess?.on || !nodeProcess?.off) {
+        return run;
+    }
+    let onRejection;
+    const escaped = new Promise((_resolve, reject) => {
+        onRejection = (reason) => {
+            if (isEngineFailure(reason)) {
+                reject(reason instanceof Error ? reason : new Error(String(reason)));
+                return;
+            }
+            // Not ours. Restore the default "unhandled rejection crashes the
+            // process" behaviour rather than silently swallowing someone's bug.
+            setImmediate(() => {
+                throw reason;
+            });
+        };
+        nodeProcess.on("unhandledRejection", onRejection);
+    });
+    try {
+        return await Promise.race([run, escaped]);
+    }
+    finally {
+        if (onRejection)
+            nodeProcess.off("unhandledRejection", onRejection);
+        // The loser of the race stays pending forever; make sure neither promise
+        // can later re-trigger the default handler.
+        void escaped.catch(() => { });
+        void run.then?.(() => { }, () => { });
+    }
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -114,12 +274,157 @@ export function truncate(text, max) {
         return text;
     return text.slice(0, max) + "\n...[truncated]";
 }
+/**
+ * Load `node:fs/promises` via a bundler-hidden import so a browser/edge bundle
+ * never tries to resolve it. The `workspace.*` bridge is wired only when a
+ * `ProcessingContext` is present, and these loaders run only when guest code
+ * actually calls `workspace.read/write/list` — off-Node that path throws
+ * (`importNodeBuiltin` resolves `null`), which `neverReject` surfaces to the
+ * guest as a normal error.
+ */
+async function loadFsPromises() {
+    const fs = await importNodeBuiltin("node:fs/promises");
+    if (!fs)
+        throw new Error("workspace file access requires a Node.js runtime");
+    return fs;
+}
+async function loadNodePath() {
+    const nodePath = await importNodeBuiltin("node:path");
+    if (!nodePath) {
+        throw new Error("workspace file access requires a Node.js runtime");
+    }
+    return nodePath;
+}
+/**
+ * Verify a workspace path's real (symlink-resolved) location stays within the
+ * real workspace root before an fs operation. resolveWorkspacePath only checks
+ * containment lexically, so an in-workspace symlink pointing outside the root
+ * would otherwise be dereferenced (arbitrary host file read/write). For a write
+ * to a not-yet-existing file, the parent directory is checked instead. Throws
+ * on an escape.
+ *
+ * TOCTOU: the realpath check and the fs op that follows it are separate awaits,
+ * and guest bridge calls run concurrently (Promise.all), so an in-workspace
+ * symlink could be swapped to point outside between this check and the caller's
+ * read/write. Keeping this the last step before the op narrows the window but
+ * does not close it — a full fix needs fd-based ops (O_NOFOLLOW / openat), which
+ * node:fs/promises does not expose. Accepted as low-risk: it needs a local
+ * attacker racing a symlink swap inside the workspace, and both surfaces here
+ * (Code node, CodeAct actions) run first-party or already-trusted code.
+ */
+async function assertWorkspaceContained(context, fs, nodePath, fullPath, isWrite) {
+    const within = async (root, candidate) => {
+        try {
+            const realRoot = await fs.realpath(root);
+            const realCandidate = await fs.realpath(candidate);
+            if (realRoot === realCandidate)
+                return true;
+            const rel = nodePath.relative(realRoot, realCandidate);
+            return rel !== "" && !rel.startsWith("..") && !nodePath.isAbsolute(rel);
+        }
+        catch {
+            return false;
+        }
+    };
+    const root = context.resolveWorkspacePath(".");
+    if (await within(root, fullPath))
+        return;
+    if (isWrite) {
+        // Target may not exist yet — lstat detects a dangling symlink entry, and
+        // otherwise the nearest existing ancestor must be inside the workspace.
+        // Walking up covers writes and mkdirs that create several levels at once;
+        // path segments that don't exist yet cannot be symlinks, so nothing along
+        // the way can redirect the write.
+        try {
+            await fs.lstat(fullPath);
+            // Exists (real file or symlink) but failed containment → outside root.
+        }
+        catch {
+            let dir = nodePath.dirname(fullPath);
+            for (;;) {
+                let exists = true;
+                try {
+                    await fs.lstat(dir);
+                }
+                catch {
+                    exists = false;
+                }
+                if (exists) {
+                    if (await within(root, dir))
+                        return;
+                    break;
+                }
+                const parent = nodePath.dirname(dir);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+        }
+    }
+    throw new Error(`workspace path resolves outside the workspace: ${fullPath}`);
+}
+/**
+ * The media engine behind the `image` and `canvas` bridges. Loaded on first
+ * use like the host modules, and for the same reasons — the canvas backend
+ * (Skia on Node) is heavy, and nothing that never draws should pay for it.
+ * Unlike those, the import is intra-package, so every bundler resolves it.
+ */
+async function loadSandboxMedia() {
+    return import("./sandbox-media.js");
+}
+/** Audio/video adapters are loaded only when a run uses those namespaces. */
+async function loadSandboxAvMedia() {
+    return import("./sandbox-av-media.js");
+}
+/**
+ * Read a fetch Response body into a Uint8Array bounded by `maxBytes`. Aborts the
+ * transfer via `controller` once the cap is exceeded so an oversized/fast
+ * response cannot buffer unbounded host memory.
+ */
+async function readBodyCapped(response, controller, maxBytes) {
+    if (!response.body) {
+        // No stream (e.g. empty body) — fall back, then clamp.
+        const buf = new Uint8Array(await response.arrayBuffer());
+        return buf.length > maxBytes ? buf.slice(0, maxBytes) : buf;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            chunks.push(value);
+            total += value.byteLength;
+            if (total >= maxBytes) {
+                controller.abort();
+                break;
+            }
+        }
+    }
+    catch {
+        // Aborted or network error mid-read — return what we have.
+    }
+    const out = new Uint8Array(Math.min(total, maxBytes));
+    let offset = 0;
+    for (const c of chunks) {
+        if (offset >= out.length)
+            break;
+        const take = Math.min(c.byteLength, out.length - offset);
+        out.set(c.subarray(0, take), offset);
+        offset += take;
+    }
+    return out;
+}
 function formatArg(arg) {
     if (arg === null)
         return "null";
     if (arg === undefined)
         return "undefined";
-    if (typeof arg === "string")
+    if (isString(arg))
         return arg;
     try {
         return JSON.stringify(arg, null, 2);
@@ -129,15 +434,20 @@ function formatArg(arg) {
     }
 }
 function isTypedArray(value) {
-    if (!value || typeof value !== "object")
+    if (!isObjectLike(value))
         return false;
     const name = value.constructor?.name;
-    return name === "Uint8Array" || name === "Buffer" ||
-        name === "Int8Array" || name === "Uint8ClampedArray" ||
-        name === "Int16Array" || name === "Uint16Array" ||
-        name === "Int32Array" || name === "Uint32Array" ||
-        name === "Float32Array" || name === "Float64Array" ||
-        name === "ArrayBuffer";
+    return (name === "Uint8Array" ||
+        name === "Buffer" ||
+        name === "Int8Array" ||
+        name === "Uint8ClampedArray" ||
+        name === "Int16Array" ||
+        name === "Uint16Array" ||
+        name === "Int32Array" ||
+        name === "Uint32Array" ||
+        name === "Float32Array" ||
+        name === "Float64Array" ||
+        name === "ArrayBuffer");
 }
 function toNativeUint8Array(value) {
     const v = value;
@@ -147,54 +457,128 @@ function toNativeUint8Array(value) {
         arr[i] = v[i] ?? 0;
     return arr;
 }
+const DIGEST_ALGORITHMS = {
+    "SHA-1": "SHA-1",
+    SHA1: "SHA-1",
+    "SHA-256": "SHA-256",
+    SHA256: "SHA-256",
+    "SHA-384": "SHA-384",
+    SHA384: "SHA-384",
+    "SHA-512": "SHA-512",
+    SHA512: "SHA-512"
+};
+function normalizeDigestAlgorithm(algorithm) {
+    const key = String(algorithm ?? "")
+        .trim()
+        .toUpperCase();
+    const resolved = DIGEST_ALGORITHMS[key];
+    if (!resolved) {
+        throw new Error(`crypto: unsupported algorithm "${String(algorithm)}" (use SHA-1, SHA-256, SHA-384 or SHA-512)`);
+    }
+    return resolved;
+}
+/** Accept a guest string or byte-like value as host bytes. */
+function coerceBytesInput(value, label) {
+    if (isString(value))
+        return new TextEncoder().encode(value);
+    if (value instanceof Uint8Array)
+        return Uint8Array.from(value);
+    if (isTypedArray(value))
+        return toNativeUint8Array(value);
+    if (Array.isArray(value))
+        return Uint8Array.from(value.map(Number));
+    if (isObjectLike(value) && isNumber(value.length)) {
+        return toNativeUint8Array(value);
+    }
+    throw new Error(`crypto: ${label} must be a string or Uint8Array`);
+}
+function webCryptoSubtle() {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new Error("crypto: WebCrypto (crypto.subtle) is not available");
+    }
+    return subtle;
+}
+/** Depth ceiling for the binary-preserving walk — guards pathological nesting. */
+const SERIALIZE_MAX_DEPTH = 32;
+/**
+ * True if a typed array sits anywhere inside `value`. Cycle-safe: a revisited
+ * object reports false, which drops the value onto the JSON path, where
+ * `JSON.stringify` throws on the cycle and the caller falls back to `String` —
+ * the behavior cyclic values already had.
+ */
+function containsTypedArray(value, depth = 0, seen = new WeakSet()) {
+    if (isTypedArray(value))
+        return true;
+    if (!isObjectLike(value))
+        return false;
+    if (depth >= SERIALIZE_MAX_DEPTH)
+        return false;
+    const obj = value;
+    if (seen.has(obj))
+        return false;
+    seen.add(obj);
+    const values = Array.isArray(value)
+        ? value
+        : Object.values(value);
+    return values.some((v) => containsTypedArray(v, depth + 1, seen));
+}
+/**
+ * Rebuild `value`, converting every typed array at any depth to a native
+ * Uint8Array and leaving everything else structurally intact.
+ */
+function convertTypedArraysDeep(value, depth = 0, seen = new WeakSet()) {
+    if (isTypedArray(value))
+        return toNativeUint8Array(value);
+    if (!isObjectLike(value))
+        return value;
+    if (depth >= SERIALIZE_MAX_DEPTH)
+        return value;
+    const obj = value;
+    if (seen.has(obj))
+        return null;
+    seen.add(obj);
+    if (Array.isArray(value)) {
+        return value.map((v) => convertTypedArraysDeep(v, depth + 1, seen));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = convertTypedArraysDeep(v, depth + 1, seen);
+    }
+    return out;
+}
 /**
  * Recursively serialize a value returned from the sandbox, converting typed
  * arrays to native Uint8Array and enforcing output size limits.
  */
-export function serializeResult(result) {
+export function serializeResult(result, maxOutputSize = MAX_OUTPUT_SIZE) {
     if (result === undefined)
         return null;
     if (result === null)
         return null;
-    if (typeof result === "string" ||
-        typeof result === "number" ||
-        typeof result === "boolean") {
-        if (typeof result === "string" && result.length > MAX_OUTPUT_SIZE) {
-            return truncate(result, MAX_OUTPUT_SIZE);
+    if (isString(result) || isNumber(result) || isBoolean(result)) {
+        if (isString(result) && result.length > maxOutputSize) {
+            return truncate(result, maxOutputSize);
         }
         return result;
     }
     if (isTypedArray(result)) {
         return toNativeUint8Array(result);
     }
-    if (typeof result === "object") {
-        let hasBinary = false;
-        if (Array.isArray(result)) {
-            hasBinary = result.some(isTypedArray);
-        }
-        else {
-            for (const v of Object.values(result)) {
-                if (isTypedArray(v)) {
-                    hasBinary = true;
-                    break;
-                }
-            }
-        }
-        if (hasBinary) {
-            if (Array.isArray(result)) {
-                return result.map(v => isTypedArray(v) ? toNativeUint8Array(v) : v);
-            }
-            const obj = result;
-            const out = {};
-            for (const [k, v] of Object.entries(obj)) {
-                out[k] = isTypedArray(v) ? toNativeUint8Array(v) : v;
-            }
-            return out;
+    if (isObjectLike(result)) {
+        // The scan and the rebuild are both deep. They used to look one level in,
+        // so a typed array nested any deeper fell through to the JSON path below —
+        // and `JSON.stringify(new Uint8Array([137, 80]))` is `{"0":137,"1":80}`,
+        // which is lossy and indistinguishable from a user's own integer map. The
+        // streaming path hit this every time: `genProcess` returns an array of
+        // yielded objects, so the bytes are always at depth 2.
+        if (containsTypedArray(result)) {
+            return convertTypedArraysDeep(result);
         }
         try {
             const json = JSON.stringify(result);
-            if (json.length > MAX_OUTPUT_SIZE) {
-                return truncate(json, MAX_OUTPUT_SIZE);
+            if (json.length > maxOutputSize) {
+                return truncate(json, maxOutputSize);
             }
             return JSON.parse(json);
         }
@@ -233,50 +617,253 @@ export function cleanStack(stack) {
  *
  * @param context  Optional ProcessingContext — when provided, enables
  *                 `workspace.*` and `getSecret()` APIs.
+ * @param signal   Optional external cancellation. Aborts in-flight host
+ *                 operations and makes `sleep` return immediately.
+ * @param limits   Optional per-invocation limit overrides, clamped by
+ *                 {@link resolveSandboxLimits}.
+ * @param onProgress Optional sink for guest `progress()` calls. Without one the
+ *                 guest function is a no-op.
+ * @param onLog    Optional sink for guest `console.*` calls. Without one the
+ *                 lines still land in {@link SandboxResult}'s `getLogs`.
+ * @param onEmit   Optional sink for guest `emit()` calls. Without one the values
+ *                 are collected and handed back through `getEmitted`.
+ * @param streams  Optional input bridges behind the guest `stream` global.
+ *                 Without an `onTakeInput` every `stream` call throws
+ *                 {@link NO_INPUT_STREAM_MESSAGE}.
+ * @param resolveMediaRef Optional host loader for media refs when this run
+ *                 has no ProcessingContext (chat). `image.*` uses it so a
+ *                 generation result can go straight into the next op.
  */
-export function buildSandbox(context) {
+export function buildSandbox(context, signal, limits, onProgress, onLog, onEmit, streams, resolveMediaRef, promoteMedia, resolveHost) {
     const logs = [];
+    const resolvedLimits = resolveSandboxLimits(limits);
     let fetchCount = 0;
+    let forwardedLogs = 0;
+    let collectedChars = 0;
+    let collectionCut = false;
+    // Bounded by count and by bytes; the cut is noted once, then nothing more
+    // is kept. A line that does not fit whole keeps the head that does.
+    const collectLog = (entry) => {
+        if (collectionCut)
+            return;
+        const remaining = MAX_COLLECTED_CONSOLE_CHARS - collectedChars;
+        if (logs.length < MAX_COLLECTED_CONSOLE_LOGS && entry.length <= remaining) {
+            logs.push(entry);
+            collectedChars += entry.length;
+            return;
+        }
+        if (logs.length < MAX_COLLECTED_CONSOLE_LOGS && remaining > 0) {
+            logs.push(entry.slice(0, remaining));
+        }
+        collectionCut = true;
+        logs.push(CONSOLE_LOGS_CUT_NOTICE);
+    };
+    const pushConsole = (level, prefix, args) => {
+        const line = args.map(formatArg).join(" ");
+        collectLog(prefix + line);
+        if (!onLog || signal?.aborted)
+            return;
+        if (forwardedLogs >= MAX_CONSOLE_LOGS)
+            return;
+        forwardedLogs++;
+        const message = line.length > MAX_CONSOLE_LOG_CHARS
+            ? line.slice(0, MAX_CONSOLE_LOG_CHARS)
+            : line;
+        try {
+            onLog(level, message);
+        }
+        catch {
+            // A failing host sink must not take the guest run down with it.
+        }
+    };
     const console = {
         log: (...args) => {
-            logs.push(args.map(formatArg).join(" "));
+            pushConsole("log", "", args);
         },
         warn: (...args) => {
-            logs.push("[warn] " + args.map(formatArg).join(" "));
+            pushConsole("warn", "[warn] ", args);
         },
         error: (...args) => {
-            logs.push("[error] " + args.map(formatArg).join(" "));
+            pushConsole("error", "[error] ", args);
         },
         info: (...args) => {
-            logs.push("[info] " + args.map(formatArg).join(" "));
+            pushConsole("info", "[info] ", args);
+        }
+    };
+    // The literal check above answers a hostname with "not an IP"; this one
+    // resolves it, so `metadata.example.com` → 169.254.169.254 is refused
+    // before a socket opens, on the first request and on every redirect hop.
+    // Node only: off Node the default resolver has no `dns` and answers
+    // nothing, and the browser's own network layer is the boundary there. One
+    // lookup per hostname per run — the guard is a layer, not the boundary (the
+    // socket resolves again), so re-resolving every call buys no rebinding
+    // protection and would cost a round trip per parallel fetch.
+    const onNodeHost = isString(globalThis.process?.versions?.node);
+    const resolvedHosts = new Map();
+    const assertHostResolvesAllowed = async (target) => {
+        if (!onNodeHost || resolvedLimits.allowPrivateNetwork)
+            return;
+        const host = new URL(target).hostname;
+        let pending = resolvedHosts.get(host);
+        if (pending === undefined) {
+            pending =
+                resolveHost === undefined
+                    ? assertResolvedHostAllowed(target, "fetch")
+                    : assertResolvedHostAllowed(target, "fetch", resolveHost);
+            resolvedHosts.set(host, pending);
         }
+        await pending;
     };
     const sandboxedFetch = async (url, options) => {
         fetchCount++;
-        if (fetchCount > MAX_FETCH_CALLS) {
-            throw new Error(`Fetch limit exceeded (max ${MAX_FETCH_CALLS} requests per execution)`);
+        if (fetchCount > resolvedLimits.maxFetchCalls) {
+            throw new Error(`Fetch limit exceeded (max ${resolvedLimits.maxFetchCalls} requests per execution)`);
         }
-        if (typeof url !== "string" || !url) {
+        if (!isNonEmptyString(url)) {
             throw new Error("fetch: url must be a non-empty string");
         }
+        // SSRF guard: untrusted guest code must not reach loopback, link-local
+        // (incl. cloud metadata 169.254.169.254), or private ranges, nor non-http
+        // schemes. This is the literal check; the resolved-address check follows.
+        // DNS rebinding between the check and the socket is out of scope.
+        // The host can waive the address check for a node that replaces a trusted
+        // `lib.http` node; the scheme check is never waived.
+        assertFetchUrlAllowed(url, resolvedLimits.allowPrivateNetwork);
+        await assertHostResolvesAllowed(url);
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 15_000);
+        const timer = setTimeout(() => controller.abort(), resolvedLimits.fetchTimeoutMs);
+        // Cancelling the run kills an in-flight request rather than waiting out
+        // the per-request timeout.
+        const onExternalAbort = () => controller.abort();
+        if (signal?.aborted)
+            controller.abort();
+        else
+            signal?.addEventListener("abort", onExternalAbort, { once: true });
         try {
             const fetchOptions = {
                 method: options?.method ?? "GET",
                 signal: controller.signal
             };
-            if (options?.headers && typeof options.headers === "object") {
-                fetchOptions.headers = options.headers;
+            const requestHeaders = {};
+            // Host default first so a guest-set User-Agent still wins.
+            if (resolvedLimits.userAgent) {
+                requestHeaders["User-Agent"] = resolvedLimits.userAgent;
+            }
+            if (isObjectLike(options?.headers)) {
+                Object.assign(requestHeaders, options.headers);
+            }
+            if (Object.keys(requestHeaders).length > 0) {
+                fetchOptions.headers = requestHeaders;
             }
             if (options?.body !== undefined) {
-                fetchOptions.body =
-                    typeof options.body === "string"
-                        ? options.body
-                        : JSON.stringify(options.body);
+                const body = options.body;
+                if (isString(body)) {
+                    fetchOptions.body = body;
+                }
+                else if (isTypedArray(body)) {
+                    // Binary request body. A guest Uint8Array reaches the host as a
+                    // native one via the typed-array serializers, but normalize anyway
+                    // so a numeric-keyed object is sent as raw bytes, not as JSON.
+                    // SAFETY: `BodyInit`'s view member is pinned to a plain
+                    // ArrayBuffer; these bytes are copied out of the guest heap by
+                    // `toNativeUint8Array`, never off a SharedArrayBuffer.
+                    fetchOptions.body = toNativeUint8Array(body);
+                }
+                else {
+                    fetchOptions.body = JSON.stringify(body);
+                }
+            }
+            // Follow redirects manually on Node so the SSRF guard runs on every hop's
+            // resolved Location, not just the initial URL — otherwise an allowed
+            // public URL that 302s to http://169.254.169.254/ or an internal host
+            // bypasses the guard entirely. In a browser redirect:"manual" yields an
+            // opaque response whose Location is unreadable, and cross-origin bodies
+            // are CORS-blocked anyway, so the browser keeps the single redirect:
+            // "follow" call with only the already-run initial-URL check.
+            const onNode = isString(globalThis.process?.versions?.node);
+            let response;
+            if (!onNode) {
+                response = await fetch(url, { ...fetchOptions, redirect: "follow" });
+            }
+            else {
+                const dropContentHeaders = (h) => {
+                    const out = {};
+                    for (const [k, v] of Object.entries(h)) {
+                        const lk = k.toLowerCase();
+                        if (lk === "content-length" || lk === "content-type")
+                            continue;
+                        out[k] = v;
+                    }
+                    return out;
+                };
+                // Credential headers must not cross to a different origin — this
+                // mirrors Node's native redirect:"follow", which strips them per the
+                // fetch spec. Guest code sets headers from getSecret(...), so a
+                // redirect to an attacker origin would otherwise exfiltrate them.
+                const dropSensitiveHeaders = (h) => {
+                    const out = {};
+                    for (const [k, v] of Object.entries(h)) {
+                        const lk = k.toLowerCase();
+                        if (lk === "authorization" ||
+                            lk === "cookie" ||
+                            lk === "proxy-authorization") {
+                            continue;
+                        }
+                        out[k] = v;
+                    }
+                    return out;
+                };
+                let currentUrl = url;
+                let method = fetchOptions.method ?? "GET";
+                let body = fetchOptions.body;
+                let headers = { ...requestHeaders };
+                let hops = 0;
+                for (;;) {
+                    response = await fetch(currentUrl, {
+                        ...fetchOptions,
+                        method,
+                        body,
+                        headers: Object.keys(headers).length ? headers : undefined,
+                        redirect: "manual"
+                    });
+                    const status = response.status;
+                    if (status < 300 || status >= 400)
+                        break;
+                    const location = response.headers.get("location");
+                    if (!location)
+                        break; // 3xx without Location — treat as final.
+                    if (hops++ >= MAX_FETCH_REDIRECTS) {
+                        throw new Error("fetch: too many redirects");
+                    }
+                    const nextUrl = new URL(location, currentUrl).toString();
+                    // Re-run the guard on the resolved target BEFORE the next request.
+                    assertFetchUrlAllowed(nextUrl, resolvedLimits.allowPrivateNetwork);
+                    await assertHostResolvesAllowed(nextUrl);
+                    // Strip credential headers on a cross-origin hop (origin includes
+                    // scheme, host and port); keep them on same-origin redirects.
+                    if (new URL(nextUrl).origin !== new URL(currentUrl).origin) {
+                        headers = dropSensitiveHeaders(headers);
+                    }
+                    // Method/body rewrite per the HTTP spec + browser behavior:
+                    // 303 always → GET; 301/302 on a non-GET/HEAD → GET (what browsers
+                    // do); 307/308 preserve method and body.
+                    if (status === 303 ||
+                        ((status === 301 || status === 302) &&
+                            method !== "GET" &&
+                            method !== "HEAD")) {
+                        method = "GET";
+                        body = undefined;
+                        headers = dropContentHeaders(headers);
+                    }
+                    // Free the redirect response's socket before the next hop.
+                    await response.body?.cancel().catch(() => { });
+                    currentUrl = nextUrl;
+                }
             }
-            const response = await fetch(url, fetchOptions);
-            const rawBytes = new Uint8Array(await response.arrayBuffer());
+            // Read the body under a hard byte cap so a large/fast response can't OOM
+            // the shared host heap (the guest's 64MB WASM limit does not apply to
+            // these host-side bytes). Aborts the transfer once the cap is exceeded.
+            const rawBytes = await readBodyCapped(response, controller, resolvedLimits.maxResponseBodyBytes);
             const ok = response.ok;
             const status = response.status;
             const statusText = response.statusText;
@@ -286,8 +873,9 @@ export function buildSandbox(context) {
                 if (cachedText === null) {
                     const decoded = new TextDecoder().decode(rawBytes);
                     cachedText =
-                        decoded.length > MAX_RESPONSE_BODY_SIZE
-                            ? decoded.slice(0, MAX_RESPONSE_BODY_SIZE) + "...[truncated]"
+                        decoded.length > resolvedLimits.maxResponseBodyBytes
+                            ? decoded.slice(0, resolvedLimits.maxResponseBodyBytes) +
+                                "...[truncated]"
                             : decoded;
                 }
                 return cachedText;
@@ -299,6 +887,11 @@ export function buildSandbox(context) {
             catch {
                 parsedJson = undefined;
             }
+            // Plain data only — no methods. A function in a bridge result cannot
+            // cross the worker boundary (`postMessage` refuses it), so the guest
+            // prelude's fetch wrapper builds `text()`/`bytes()`/`arrayBuffer()` over
+            // these fields instead. The body is already fully buffered and capped
+            // here, so shipping it eagerly costs no extra read.
             return {
                 ok,
                 status,
@@ -306,57 +899,342 @@ export function buildSandbox(context) {
                 headers,
                 body: getText(),
                 json: parsedJson,
-                text: async () => getText(),
-                arrayBuffer: async () => rawBytes.buffer.slice(rawBytes.byteOffset, rawBytes.byteOffset + rawBytes.byteLength),
-                bytes: async () => rawBytes
+                bodyBytes: toGuestBytes(rawBytes)
             };
         }
         finally {
             clearTimeout(timer);
+            signal?.removeEventListener("abort", onExternalAbort);
         }
     };
-    const uuid = () => crypto.randomUUID();
+    // WebCrypto exists in both Node >= 20 and browsers, so no node:crypto import
+    // is needed and the sandbox stays browser-safe. `getRandomValues` is the one
+    // synchronous member: it clamps instead of throwing, since a host throw does
+    // not go through the never-reject convention.
+    const sandboxCrypto = {
+        randomUUID: () => globalThis.crypto.randomUUID(),
+        getRandomValues: (length) => {
+            const requested = Number(length);
+            const size = Number.isFinite(requested)
+                ? Math.min(Math.max(Math.floor(requested), 0), MAX_RANDOM_BYTES)
+                : 0;
+            const bytes = new Uint8Array(size);
+            if (size > 0)
+                globalThis.crypto.getRandomValues(bytes);
+            return toGuestBytes(bytes);
+        },
+        digest: async (algorithm, data) => {
+            const algo = normalizeDigestAlgorithm(algorithm);
+            const bytes = coerceBytesInput(data, "data");
+            const digest = await webCryptoSubtle().digest(algo, bytes);
+            return toGuestBytes(new Uint8Array(digest));
+        },
+        hmac: async (algorithm, key, data) => {
+            const algo = normalizeDigestAlgorithm(algorithm);
+            const keyBytes = coerceBytesInput(key, "key");
+            const dataBytes = coerceBytesInput(data, "data");
+            const subtle = webCryptoSubtle();
+            const cryptoKey = await subtle.importKey("raw", keyBytes, { name: "HMAC", hash: algo }, false, ["sign"]);
+            const signature = await subtle.sign("HMAC", cryptoKey, dataBytes);
+            return toGuestBytes(new Uint8Array(signature));
+        }
+    };
+    /**
+     * The one place a secret leaves the host.
+     *
+     * The scope check sits here rather than in the guest prelude because a
+     * prelude is guest code: it can be shadowed, and a check the guest could
+     * remove is documentation, not a boundary. `nodetool.secrets.get` and the
+     * bare `getSecret` global both land here, so there is no second route.
+     */
+    const secretScope = resolvedLimits.secretScope;
+    const assertSecretInScope = (name) => {
+        if (secretScope === null)
+            return;
+        if (secretScope.includes(name))
+            return;
+        throw new Error(secretScope.length === 0
+            ? `getSecret("${name}"): this node declares no secrets, so it can read none`
+            : `getSecret("${name}"): this node may read only ${secretScope
+                .map((allowed) => `"${allowed}"`)
+                .join(", ")}`);
+    };
     const getSecret = context
         ? async (name) => {
+            assertSecretInScope(name);
             return (await context.getSecret(name)) ?? undefined;
         }
-        : async (_name) => {
+        : async (name) => {
+            assertSecretInScope(name);
             return undefined;
         };
-    const workspace = context
-        ? {
-            read: async (path) => {
-                const fullPath = context.resolveWorkspacePath(path);
-                const { readFile } = await import("node:fs/promises");
-                return readFile(fullPath, "utf-8");
-            },
-            write: async (path, content) => {
-                const fullPath = context.resolveWorkspacePath(path);
-                const { writeFile, mkdir } = await import("node:fs/promises");
-                const { dirname } = await import("node:path");
-                await mkdir(dirname(fullPath), { recursive: true });
-                await writeFile(fullPath, content, "utf-8");
-            },
-            list: async (path) => {
-                const fullPath = context.resolveWorkspacePath(path);
-                const { readdir } = await import("node:fs/promises");
-                return readdir(fullPath);
-            }
-        }
-        : {
-            read: async (_path) => {
-                throw new Error("workspace.read is not available without a context");
-            },
-            write: async (_path, _content) => {
-                throw new Error("workspace.write is not available without a context");
-            },
-            list: async (_path) => {
-                throw new Error("workspace.list is not available without a context");
+    /** What `workspace.stat` answers for a path that is not there. */
+    const MISSING_STAT = {
+        exists: false,
+        size: 0,
+        isDirectory: false,
+        isFile: false,
+        isSymlink: false,
+        modifiedMs: 0,
+        createdMs: 0,
+        accessedMs: 0
+    };
+    /**
+     * Resolve a guest path under the configured filesystem scope.
+     *
+     * `"workspace"` (the default) is the pre-existing behavior: resolve against
+     * the workspace root, then verify the symlink-resolved location is still
+     * inside it. `"host"` skips containment and expands `~`, matching what the
+     * `lib.os` nodes have always done. Host mode is reachable only when the host
+     * passes `filesystemAccess: "host"` — guest code cannot ask for it.
+     */
+    const resolveGuestPath = async (ctx, path, isWrite) => {
+        const nodePath = await loadNodePath();
+        if (resolvedLimits.filesystemAccess === "host") {
+            const os = await importNodeBuiltin("node:os");
+            if (!os) {
+                throw new Error("host filesystem access requires a Node.js runtime");
             }
-        };
+            const expanded = path === "~"
+                ? os.homedir()
+                : path.startsWith("~/")
+                    ? nodePath.join(os.homedir(), path.slice(2))
+                    : path;
+            return nodePath.resolve(expanded);
+        }
+        const fullPath = ctx.resolveWorkspacePath(path);
+        const fs = await loadFsPromises();
+        await assertWorkspaceContained(ctx, fs, nodePath, fullPath, isWrite);
+        return fullPath;
+    };
+    /**
+     * The guest's `workspace.*` API.
+     *
+     * Three shapes, picked once: no context at all (every call explains itself),
+     * `filesystemAccess: "host"` (the `lib.os` escape hatch — real paths, no
+     * containment, host opt-in only), and the normal case, which goes through
+     * `context.workspace` and therefore works the same whether the run's
+     * workspace is a folder or a prefix in object storage.
+     */
+    const hostFsWorkspace = (ctx) => ({
+        read: async (path) => {
+            const fs = await loadFsPromises();
+            return fs.readFile(await resolveGuestPath(ctx, path, false), "utf-8");
+        },
+        write: async (path, content) => {
+            const fs = await loadFsPromises();
+            const nodePath = await loadNodePath();
+            const fullPath = await resolveGuestPath(ctx, path, true);
+            await fs.mkdir(nodePath.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, content, "utf-8");
+        },
+        list: async (path) => {
+            const fs = await loadFsPromises();
+            return fs.readdir(await resolveGuestPath(ctx, path, false));
+        },
+        readBytes: async (path) => {
+            const fs = await loadFsPromises();
+            const fullPath = await resolveGuestPath(ctx, path, false);
+            return toGuestBytes(new Uint8Array(await fs.readFile(fullPath)));
+        },
+        writeBytes: async (path, data) => {
+            const bytes = data instanceof Uint8Array ? data : toNativeUint8Array(data);
+            const fs = await loadFsPromises();
+            const nodePath = await loadNodePath();
+            const fullPath = await resolveGuestPath(ctx, path, true);
+            await fs.mkdir(nodePath.dirname(fullPath), { recursive: true });
+            await fs.writeFile(fullPath, bytes);
+        },
+        stat: async (path) => {
+            const fs = await loadFsPromises();
+            const fullPath = await resolveGuestPath(ctx, path, true);
+            let info;
+            try {
+                info = await fs.lstat(fullPath);
+            }
+            catch {
+                return MISSING_STAT;
+            }
+            return {
+                exists: true,
+                size: info.size,
+                isDirectory: info.isDirectory(),
+                isFile: info.isFile(),
+                isSymlink: info.isSymbolicLink(),
+                modifiedMs: info.mtimeMs,
+                createdMs: info.birthtimeMs,
+                accessedMs: info.atimeMs
+            };
+        },
+        root: async () => ctx.resolveWorkspacePath("."),
+        copy: async (src, dest) => {
+            const fs = await loadFsPromises();
+            const nodePath = await loadNodePath();
+            const fullSrc = await resolveGuestPath(ctx, src, false);
+            const fullDest = await resolveGuestPath(ctx, dest, true);
+            await fs.mkdir(nodePath.dirname(fullDest), { recursive: true });
+            await fs.copyFile(fullSrc, fullDest);
+        },
+        move: async (src, dest) => {
+            const fs = await loadFsPromises();
+            const nodePath = await loadNodePath();
+            const fullSrc = await resolveGuestPath(ctx, src, true);
+            const fullDest = await resolveGuestPath(ctx, dest, true);
+            await fs.mkdir(nodePath.dirname(fullDest), { recursive: true });
+            await fs.rename(fullSrc, fullDest);
+        },
+        mkdir: async (path) => {
+            const fs = await loadFsPromises();
+            await fs.mkdir(await resolveGuestPath(ctx, path, true), {
+                recursive: true
+            });
+        },
+        remove: async (path) => {
+            const fs = await loadFsPromises();
+            const fullPath = await resolveGuestPath(ctx, path, true);
+            const info = await fs.lstat(fullPath);
+            if (info.isDirectory()) {
+                // rmdir refuses a non-empty directory, which is the point.
+                await fs.rmdir(fullPath);
+            }
+            else {
+                await fs.rm(fullPath, { recursive: false });
+            }
+        }
+    });
+    const backedWorkspace = (ws) => ({
+        read: async (path) => {
+            const text = await ws.readText(path);
+            if (text === null)
+                throw new Error(`ENOENT: no such file: ${path}`);
+            return text;
+        },
+        write: async (path, content) => {
+            await ws.write(path, content);
+        },
+        // Names only, like readdir — the guest joins them onto the path it asked
+        // about, which is how the pre-existing scripts use this.
+        list: async (path) => (await ws.list(path)).map((entry) => entry.name),
+        readBytes: async (path) => {
+            const bytes = await ws.read(path);
+            if (bytes === null)
+                throw new Error(`ENOENT: no such file: ${path}`);
+            return toGuestBytes(bytes);
+        },
+        writeBytes: async (path, data) => {
+            const bytes = data instanceof Uint8Array ? data : toNativeUint8Array(data);
+            await ws.write(path, bytes);
+        },
+        // A missing path is an answer, not a failure: guest code asking
+        // "does this exist?" should not have to wrap the call in try/catch.
+        stat: async (path) => {
+            let info;
+            try {
+                info = await ws.stat(path);
+            }
+            catch {
+                return MISSING_STAT;
+            }
+            if (!info)
+                return MISSING_STAT;
+            return {
+                exists: true,
+                size: info.size,
+                isDirectory: info.isDirectory,
+                isFile: !info.isDirectory,
+                // Nothing reachable through a workspace is a symlink: an object store
+                // cannot hold one, and the local backend refuses to follow one out of
+                // the root.
+                isSymlink: false,
+                modifiedMs: info.modifiedAt,
+                createdMs: info.modifiedAt,
+                accessedMs: info.modifiedAt
+            };
+        },
+        /**
+         * The base for relative paths. A real directory when the workspace has
+         * one; otherwise `/workspace`, which every workspace path accepts as its
+         * own root, so a script that joins onto it keeps working.
+         */
+        root: async () => ws.localDir ?? "/workspace",
+        copy: async (src, dest) => {
+            await ws.copy(src, dest);
+        },
+        move: async (src, dest) => {
+            await ws.move(src, dest);
+        },
+        mkdir: async (path) => {
+            await ws.mkdir(path);
+        },
+        remove: async (path) => {
+            // One file or one empty directory — guest code cannot delete a whole
+            // subtree in a single call, in any filesystem mode.
+            const info = await ws.stat(path);
+            if (info?.isDirectory) {
+                const children = await ws.list(path);
+                if (children.length > 0) {
+                    throw new Error(`ENOTEMPTY: directory not empty: ${path}`);
+                }
+                await ws.deleteAll(path);
+                return;
+            }
+            if (!(await ws.delete(path))) {
+                throw new Error(`ENOENT: no such file: ${path}`);
+            }
+        }
+    });
+    const unavailable = (api) => async () => {
+        throw new Error(`workspace.${api} is not available without a context`);
+    };
+    const workspace = !context
+        ? {
+            read: unavailable("read"),
+            write: unavailable("write"),
+            list: unavailable("list"),
+            readBytes: unavailable("readBytes"),
+            writeBytes: unavailable("writeBytes"),
+            stat: unavailable("stat"),
+            root: unavailable("root"),
+            copy: unavailable("copy"),
+            move: unavailable("move"),
+            mkdir: unavailable("mkdir"),
+            remove: unavailable("remove")
+        }
+        : resolvedLimits.filesystemAccess === "host"
+            ? hostFsWorkspace(context)
+            : context.workspace
+                ? backedWorkspace(context.workspace)
+                : {
+                    read: unavailable("read"),
+                    write: unavailable("write"),
+                    list: unavailable("list"),
+                    readBytes: unavailable("readBytes"),
+                    writeBytes: unavailable("writeBytes"),
+                    stat: unavailable("stat"),
+                    root: unavailable("root"),
+                    copy: unavailable("copy"),
+                    move: unavailable("move"),
+                    mkdir: unavailable("mkdir"),
+                    remove: unavailable("remove")
+                };
     const sleep = (ms) => {
         const capped = Math.min(ms, 5000);
-        return new Promise((resolve) => setTimeout(resolve, capped));
+        // Resolve immediately on cancellation: a sleeping script is the common
+        // case for "still running after Stop", and waiting out the nap before the
+        // next bridge call can reject it wastes up to 5s per sleep.
+        return new Promise((resolve) => {
+            if (signal?.aborted)
+                return resolve();
+            const timer = setTimeout(() => {
+                signal?.removeEventListener("abort", onAbort);
+                resolve();
+            }, capped);
+            function onAbort() {
+                clearTimeout(timer);
+                resolve();
+            }
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
     };
     const assetToSandbox = context
         ? async (assetId, path) => {
@@ -372,6 +1250,512 @@ export function buildSandbox(context) {
         : async (_path) => {
             throw new Error("sandboxToAsset is not available without a context");
         };
+    // Fire-and-forget progress reporting. Synchronous like console.log: it never
+    // throws, so it needs no never-reject wrapper. A guest that spams it cannot
+    // flood the host — reports closer together than PROGRESS_MIN_INTERVAL_MS are
+    // dropped, and the run has a lifetime cap.
+    let progressCalls = 0;
+    let lastProgressAt = 0;
+    const progress = (percent, message) => {
+        if (!onProgress || signal?.aborted)
+            return;
+        if (progressCalls >= MAX_PROGRESS_CALLS)
+            return;
+        const now = Date.now();
+        if (progressCalls > 0 && now - lastProgressAt < PROGRESS_MIN_INTERVAL_MS) {
+            return;
+        }
+        const raw = Number(percent);
+        const clamped = Number.isFinite(raw) ? Math.min(Math.max(raw, 0), 100) : 0;
+        const text = message === undefined || message === null
+            ? undefined
+            : String(message).slice(0, MAX_PROGRESS_MESSAGE_CHARS);
+        progressCalls++;
+        lastProgressAt = now;
+        try {
+            onProgress(clamped, text);
+        }
+        catch {
+            // A failing host sink must not take the guest run down with it.
+        }
+    };
+    // Output delivery. The opposite of `progress` in every respect: awaitable, so
+    // the guest gets backpressure from a slow consumer, and never rate-limited or
+    // dropped — an output value the host silently discards is data loss, not a
+    // missed progress tick. Both throw into the guest rather than failing quietly.
+    let emitCalls = 0;
+    const emitted = [];
+    const outputs = new Map();
+    const handleName = (fn, name) => {
+        if (!isString(name)) {
+            throw new TypeError(`${fn}: name must be a string`);
+        }
+        return name;
+    };
+    const emit = async (name, value) => {
+        const handle = handleName("emit", name);
+        if (emitCalls >= MAX_EMIT_CALLS) {
+            throw new Error(`emit: this run may emit at most ${MAX_EMIT_CALLS} values (MAX_EMIT_CALLS)`);
+        }
+        emitCalls++;
+        const marshaled = serializeResult(value, resolvedLimits.maxOutputSize);
+        if (onEmit) {
+            // Awaited, so the guest's promise resolves only once the host has taken
+            // the value — and a sink that throws unwinds the guest's `emit` call.
+            await onEmit(handle, marshaled);
+            return;
+        }
+        emitted.push({ name: handle, value: marshaled });
+    };
+    const output = async (name, value) => {
+        const handle = handleName("output", name);
+        if (outputs.has(handle)) {
+            throw new Error(`output "${handle}" was already set`);
+        }
+        outputs.set(handle, serializeResult(value, resolvedLimits.maxOutputSize));
+    };
+    // Input delivery, the mirror of `emit`: the guest pulls one value at a time
+    // and the host answers from the inbox it owns. Backpressure is free — an item
+    // nobody asked for stays upstream.
+    const takeInput = async (name) => {
+        if (!streams?.onTakeInput) {
+            throw new Error(NO_INPUT_STREAM_MESSAGE);
+        }
+        if (name !== null && !isString(name)) {
+            throw new TypeError("stream: name must be a string");
+        }
+        // Waiting on upstream is not the guest executing, so it must not spend the
+        // guest's timeout budget. The clock stops until the value (or EOS) lands.
+        const resume = streams.clock?.suspend();
+        try {
+            const take = await streams.onTakeInput(name);
+            if (take.done)
+                return { done: true };
+            return {
+                done: false,
+                handle: take.handle,
+                value: toGuestBytesDeep(take.value)
+            };
+        }
+        finally {
+            resume?.();
+        }
+    };
+    // Synchronous and never throwing, which is what lets the guest read it as a
+    // plain boolean: an awaitable answer would make `if (stream.open(h))` true on
+    // a pending promise. `null` is the one non-answer — this run has no input
+    // stream at all — and the prelude turns it into the thrown error.
+    const streamOpen = (name) => {
+        if (!streams?.onTakeInput)
+            return null;
+        if (!isString(name) || !streams.onStreamOpen)
+            return false;
+        try {
+            return streams.onStreamOpen(name) === true;
+        }
+        catch {
+            // A host probe that throws answers "closed" rather than taking the run
+            // down: the take itself is where a broken inbox must surface.
+            return false;
+        }
+    };
+    // QuickJS ships no Intl, so locale-aware formatting has to come from the
+    // host. Async + never-reject like the other bridges: a bad locale or option
+    // surfaces in the guest as a thrown Error with Intl's own message.
+    const format = {
+        number: async (value, options) => {
+            const num = Number(value);
+            if (!Number.isFinite(num)) {
+                throw new Error("format.number: value must be a finite number");
+            }
+            const opts = options ?? {};
+            return new Intl.NumberFormat(opts.locale ?? DEFAULT_FORMAT_LOCALE, {
+                style: opts.style,
+                currency: opts.currency,
+                minimumFractionDigits: opts.minimumFractionDigits,
+                maximumFractionDigits: opts.maximumFractionDigits,
+                useGrouping: opts.useGrouping
+            }).format(num);
+        },
+        date: async (epochMs, options) => {
+            const ms = Number(epochMs);
+            if (!Number.isFinite(ms)) {
+                throw new Error("format.date: epochMs must be a finite number of milliseconds");
+            }
+            const opts = options ?? {};
+            const dateStyle = opts.dateStyle;
+            const timeStyle = opts.timeStyle;
+            return new Intl.DateTimeFormat(opts.locale ?? DEFAULT_FORMAT_LOCALE, {
+                // Intl falls back to a date-only default when neither style is given.
+                dateStyle: dateStyle ?? (timeStyle ? undefined : "medium"),
+                timeStyle,
+                timeZone: opts.timeZone
+            }).format(new Date(ms));
+        },
+        relativeTime: async (value, unit, options) => {
+            const num = Number(value);
+            if (!Number.isFinite(num)) {
+                throw new Error("format.relativeTime: value must be a finite number");
+            }
+            const opts = options ?? {};
+            return new Intl.RelativeTimeFormat(opts.locale ?? DEFAULT_FORMAT_LOCALE).format(num, unit);
+        },
+        list: async (items, options) => {
+            if (!Array.isArray(items)) {
+                throw new Error("format.list: items must be an array of strings");
+            }
+            const opts = options ?? {};
+            return new Intl.ListFormat(opts.locale ?? DEFAULT_FORMAT_LOCALE, { type: opts.type }).format(items.map((i) => String(i)));
+        }
+    };
+    // Bytes media transforms produced and the guest only carries around. Lives for the
+    // run, then goes; nothing here is durable until something promotes it.
+    const mediaStore = createSandboxMediaStore(resolvedLimits.runMediaBytes);
+    let runAvMediaPromise;
+    const loadRunAvMedia = () => {
+        runAvMediaPromise ??= loadSandboxAvMedia().then((media) => ({
+            audioOps: media.createAudioBridge(signal, resolvedLimits.runMediaBytes),
+            videoOps: media.createVideoBridge(signal, resolvedLimits.runMediaBytes)
+        }));
+        return runAvMediaPromise;
+    };
+    // Media bridges. The engine (`sandbox-media.ts`) is imported on first use
+    // like every other library-backed bridge, and picks its canvas backend from
+    // the runtime — `@napi-rs/canvas` on Node, `OffscreenCanvas` in the browser
+    // runner. Bytes come back tagged for the guest prelude to revive, so the
+    // guest-visible API is `Uint8Array` in and `Uint8Array` out.
+    const withGuestBytes = (fn) => {
+        return async (...args) => toGuestBytesDeep(await fn(...args));
+    };
+    const mediaMember = (pick) => withGuestBytes(async (...args) => pick(await loadSandboxMedia())(...args));
+    // `image.*` trades in handles, not bytes. On the way in, every handle and
+    // every media ref buried anywhere in the arguments is replaced by the bytes
+    // it names — resolved host-side, so an `asset://` a generator produced goes
+    // straight into the next operation without being pulled through the guest.
+    // On the way out, encoded bytes become a handle instead of a base64 payload.
+    // A chain (resize → adjust → composite) therefore moves nothing across the
+    // boundary but small objects.
+    //
+    // `info` and `decode` are the deliberate exceptions: they exist to tell the
+    // guest what is *in* an image, so their results stay plain data. `decode`
+    // still hands over real pixels, which is the one call that has to.
+    const loadMediaRef = async (where, value, maxBytes = resolvedLimits.runMediaBytes) => {
+        const ref = remapMediaRef(value);
+        if (context) {
+            return resolveRefBytes(where, ref, context, (path) => resolveGuestPath(context, path, false), maxBytes);
+        }
+        if (resolveMediaRef) {
+            const bytes = await resolveMediaRef(where, ref);
+            if (bytes.length > maxBytes) {
+                throw new Error(`${where}: media input is ${bytes.length} bytes, over the ` +
+                    `${maxBytes} byte remaining run media limit`);
+            }
+            return bytes;
+        }
+        const label = ref.uri || ref.asset_id || "this media ref";
+        throw new Error(`${where}: cannot resolve ${label} in this run. Pass a media ` +
+            `handle or a generation result (its asset_uri).`);
+    };
+    const resolveMediaArgs = async (where, value, 
+    // `image.*` wants a ref flattened to bytes it can operate on. `media.*`
+    // takes refs *as* refs — that is its whole job — so it resolves handles
+    // only, or `media.bytes(assetRef)` would be handed bytes and no longer
+    // have a ref to read.
+    resolveRefs, depth = 0, expectedType, budget = { used: 0 }) => {
+        if (depth >= SANDBOX_SERIALIZE_MAX_DEPTH)
+            return value;
+        const accountBytes = (bytes) => {
+            if (bytes.byteLength > resolvedLimits.runMediaBytes - budget.used) {
+                throw new Error(`${where}: aggregate media input exceeds the ` +
+                    `${resolvedLimits.runMediaBytes} byte run media limit`);
+            }
+            budget.used += bytes.byteLength;
+            return bytes;
+        };
+        // Matched on the marker, not on store membership: a handle from an
+        // earlier run must report *that*, rather than falling through to the ref
+        // path and blaming the uri it happens to carry.
+        if (isSandboxMediaHandle(value)) {
+            const bytes = mediaStore.resolve(value, expectedType);
+            if (!bytes)
+                throw new Error(`${where}: media handle has no bytes`);
+            return accountBytes(bytes);
+        }
+        if (value instanceof Uint8Array || ArrayBuffer.isView(value)) {
+            return accountBytes(value);
+        }
+        if (Array.isArray(value)) {
+            const resolved = [];
+            for (const item of value) {
+                const result = await resolveMediaArgs(where, item, resolveRefs, depth + 1, expectedType, budget);
+                resolved.push(result);
+            }
+            return resolved;
+        }
+        if (resolveRefs && looksLikeMediaRef(value)) {
+            if (expectedType && isObjectLike(value)) {
+                const declared = value.type;
+                if ((declared === "image" ||
+                    declared === "audio" ||
+                    declared === "video") &&
+                    declared !== expectedType) {
+                    throw new Error(`${where}: expected ${expectedType} media, but received ${declared}`);
+                }
+            }
+            const remainingBytes = resolvedLimits.runMediaBytes - budget.used;
+            return accountBytes(await loadMediaRef(where, value, remainingBytes));
+        }
+        if (isObjectLike(value)) {
+            const record = value;
+            const out = {};
+            for (const [k, v] of Object.entries(record)) {
+                out[k] = await resolveMediaArgs(where, v, resolveRefs, depth + 1, expectedType, budget);
+            }
+            return out;
+        }
+        return value;
+    };
+    const defaultMediaMime = (type) => type === "image"
+        ? "image/png"
+        : type === "audio"
+            ? "audio/wav"
+            : "video/mp4";
+    const mediaMimeForValue = (value, expectedType) => {
+        if (isSandboxMediaHandle(value)) {
+            return (mediaStore.entry(value, expectedType)?.mimeType ??
+                defaultMediaMime(expectedType));
+        }
+        const record = isRecord(value) ? value : undefined;
+        const declared = record?.mimeType ?? record?.mime_type;
+        const ref = remapMediaRef(value);
+        if (isString(declared))
+            ref.mimeType = declared;
+        return mimeForRef(ref, defaultMediaMime(expectedType));
+    };
+    const sniffMediaMime = (type, bytes, fallback) => {
+        const ascii = (start, length) => String.fromCharCode(...bytes.subarray(start, start + length));
+        if (type === "image") {
+            if (bytes.length >= 8 && ascii(1, 3) === "PNG")
+                return "image/png";
+            if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8)
+                return "image/jpeg";
+            if (bytes.length >= 6 && ascii(0, 3) === "GIF")
+                return "image/gif";
+            if (bytes.length >= 12 &&
+                ascii(0, 4) === "RIFF" &&
+                ascii(8, 4) === "WEBP")
+                return "image/webp";
+            return fallback;
+        }
+        if (type === "audio") {
+            if (bytes.length >= 12 &&
+                ascii(0, 4) === "RIFF" &&
+                ascii(8, 4) === "WAVE")
+                return "audio/wav";
+            if (bytes.length >= 4 && ascii(0, 4) === "fLaC")
+                return "audio/flac";
+            if (bytes.length >= 4 && ascii(0, 4) === "OggS")
+                return "audio/ogg";
+            if ((bytes.length >= 3 && ascii(0, 3) === "ID3") ||
+                (bytes.length >= 2 && bytes[0] === 0xff && (bytes[1] & 0xe0) === 0xe0))
+                return "audio/mpeg";
+            if (bytes.length >= 12 && ascii(4, 4) === "ftyp")
+                return "audio/mp4";
+            return fallback;
+        }
+        if (bytes.length >= 12 && ascii(0, 4) === "RIFF" && ascii(8, 4) === "AVI ")
+            return "video/x-msvideo";
+        if (bytes.length >= 4 && bytes[0] === 0x1a && bytes[1] === 0x45) {
+            return ascii(0, Math.min(bytes.length, 64)).includes("webm")
+                ? "video/webm"
+                : "video/x-matroska";
+        }
+        if (bytes.length >= 12 && ascii(4, 4) === "ftyp") {
+            return ascii(8, 4) === "qt  " ? "video/quicktime" : "video/mp4";
+        }
+        return fallback;
+    };
+    /** An `image.*` op: handles/refs in, a handle out. */
+    const imageMember = (name, pick) => {
+        const where = `image.${name}`;
+        return async (...args) => {
+            const resolved = (await resolveMediaArgs(where, args, true, 0, "image"));
+            const result = await pick(await loadSandboxMedia())(...resolved);
+            if (result instanceof Uint8Array) {
+                const media = await loadSandboxMedia();
+                const info = (await media.imageOps.info(result));
+                const meta = {
+                    mimeType: info.format ? `image/${info.format}` : "image/png"
+                };
+                if (info.width !== undefined)
+                    meta.width = info.width;
+                if (info.height !== undefined)
+                    meta.height = info.height;
+                return mediaStore.put(result, meta);
+            }
+            return toGuestBytesDeep(result);
+        };
+    };
+    const image = {
+        /**
+         * The one door from a handle back to real bytes, and deliberately the only
+         * one. Every other op keeps the payload host-side, so a body that reaches
+         * for this is saying it will read the bytes itself — the cost is explicit
+         * at the call site instead of hidden in every hop. It needs no
+         * ProcessingContext, so a Code node that really does parse an encoded image
+         * works exactly as it did.
+         */
+        bytes: async (value) => {
+            const resolved = await resolveMediaArgs("image.bytes", value, true, 0, "image");
+            const media = await loadSandboxMedia();
+            return toGuestBytes(media.asImageBytes(resolved, "image.bytes"));
+        },
+        /**
+         * Handle → durable asset. Bytes stay on the host; the guest gets a ref.
+         */
+        toAsset: async (value, options) => {
+            const sourceMime = mediaMimeForValue(value, "image");
+            const resolved = await resolveMediaArgs("image.toAsset", value, true, 0, "image");
+            const media = await loadSandboxMedia();
+            const bytes = media.asImageBytes(resolved, "image.toAsset");
+            const mimeType = sniffMediaMime("image", bytes, sourceMime);
+            const assetOptions = { mimeType, ...options };
+            if (promoteMedia) {
+                return promoteMedia("image", bytes, assetOptions);
+            }
+            if (context) {
+                return mediaRefBridge.toImage(bytes, assetOptions);
+            }
+            throw new Error("image.toAsset: cannot save an asset in this run. Use " +
+                "nodetool.media.toImage from a chat action, or media.toImage " +
+                "from a Code node.");
+        },
+        info: imageMember("info", (m) => m.imageOps.info),
+        decode: imageMember("decode", (m) => m.imageOps.decode),
+        stats: imageMember("stats", (m) => m.imageOps.stats),
+        blank: imageMember("blank", (m) => m.imageOps.blank),
+        pad: imageMember("pad", (m) => m.imageOps.pad),
+        grid: imageMember("grid", (m) => m.imageOps.grid),
+        resize: imageMember("resize", (m) => m.imageOps.resize),
+        crop: imageMember("crop", (m) => m.imageOps.crop),
+        rotate: imageMember("rotate", (m) => m.imageOps.rotate),
+        flip: imageMember("flip", (m) => m.imageOps.flip),
+        adjust: imageMember("adjust", (m) => m.imageOps.adjust),
+        composite: imageMember("composite", (m) => m.imageOps.composite),
+        convert: imageMember("convert", (m) => m.imageOps.convert)
+    };
+    const requireMediaBytes = (where, value) => {
+        if (value instanceof Uint8Array)
+            return value;
+        if (ArrayBuffer.isView(value)) {
+            return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+        }
+        throw new Error(`${where}: expected media bytes, a media handle, or a media ref`);
+    };
+    const avMember = (namespace, name, inputTypes, outputType, pick) => {
+        const where = `${namespace}.${name}`;
+        return async (...args) => {
+            const budget = { used: 0 };
+            const resolved = [];
+            for (let index = 0; index < args.length; index += 1) {
+                resolved.push(await resolveMediaArgs(where, args[index], true, 0, inputTypes[index], budget));
+            }
+            const result = await pick(await loadRunAvMedia())(...resolved);
+            if (outputType && result instanceof Uint8Array) {
+                const sourceType = inputTypes[0] ?? outputType;
+                const sourceMime = mediaMimeForValue(args[0], sourceType);
+                return mediaStore.put(result, {
+                    type: outputType,
+                    mimeType: sniffMediaMime(outputType, result, outputType === sourceType
+                        ? sourceMime
+                        : defaultMediaMime(outputType))
+                });
+            }
+            return toGuestBytesDeep(result);
+        };
+    };
+    const avBytes = (namespace) => async (value) => {
+        const where = `${namespace}.bytes`;
+        const resolved = await resolveMediaArgs(where, value, true, 0, namespace);
+        return toGuestBytes(requireMediaBytes(where, resolved));
+    };
+    const avToAsset = (type) => async (value, options) => {
+        const where = `${type}.toAsset`;
+        const sourceMime = mediaMimeForValue(value, type);
+        const resolved = await resolveMediaArgs(where, value, true, 0, type);
+        const bytes = requireMediaBytes(where, resolved);
+        const mimeType = sniffMediaMime(type, bytes, sourceMime);
+        const assetOptions = { mimeType, ...options };
+        if (promoteMedia) {
+            return promoteMedia(type, bytes, assetOptions);
+        }
+        if (context) {
+            return type === "audio"
+                ? mediaRefBridge.toAudio(bytes, assetOptions)
+                : mediaRefBridge.toVideo(bytes, assetOptions);
+        }
+        throw new Error(`${where}: cannot save an asset in this run. Use media.to${type === "audio" ? "Audio" : "Video"} from a Code node.`);
+    };
+    const audio = {
+        bytes: avBytes("audio"),
+        toAsset: avToAsset("audio"),
+        info: avMember("audio", "info", ["audio"], undefined, (m) => m.audioOps.info),
+        normalize: avMember("audio", "normalize", ["audio"], "audio", (m) => m.audioOps.normalize),
+        trim: avMember("audio", "trim", ["audio"], "audio", (m) => m.audioOps.trim),
+        concat: avMember("audio", "concat", ["audio"], "audio", (m) => m.audioOps.concat),
+        mix: avMember("audio", "mix", ["audio"], "audio", (m) => m.audioOps.mix),
+        reverse: avMember("audio", "reverse", ["audio"], "audio", (m) => m.audioOps.reverse),
+        fadeIn: avMember("audio", "fadeIn", ["audio"], "audio", (m) => m.audioOps.fadeIn),
+        fadeOut: avMember("audio", "fadeOut", ["audio"], "audio", (m) => m.audioOps.fadeOut),
+        repeat: avMember("audio", "repeat", ["audio"], "audio", (m) => m.audioOps.repeat)
+    };
+    const video = {
+        bytes: avBytes("video"),
+        toAsset: avToAsset("video"),
+        info: avMember("video", "info", ["video"], undefined, (m) => m.videoOps.info),
+        trim: avMember("video", "trim", ["video"], "video", (m) => m.videoOps.trim),
+        resize: avMember("video", "resize", ["video"], "video", (m) => m.videoOps.resize),
+        rotate: avMember("video", "rotate", ["video"], "video", (m) => m.videoOps.rotate),
+        addAudio: avMember("video", "addAudio", ["video", "audio"], "video", (m) => m.videoOps.addAudio),
+        extractAudio: avMember("video", "extractAudio", ["video"], "audio", (m) => m.videoOps.extractAudio),
+        extractFrame: avMember("video", "extractFrame", ["video"], "image", (m) => m.videoOps.extractFrame)
+    };
+    const canvas = {
+        render: imageMember("render", (m) => m.renderCanvas),
+        measureText: mediaMember((m) => m.measureCanvasText)
+    };
+    // Media refs in and out. Unlike the transform namespaces, this one needs a
+    // ProcessingContext — it resolves `asset://`, storage keys and package assets
+    // through the host's own resolver — so without one every member throws.
+    // `media.*` reads files, so it resolves paths through the same
+    // `resolveGuestPath` `workspace.*` uses — one containment rule, one
+    // `filesystemAccess` scope, no second scheme to keep in step.
+    const mediaRefBridge = createMediaRefBridge(context, context
+        ? {
+            resolvePath: (path) => resolveGuestPath(context, path, false)
+        }
+        : {});
+    // A media handle is accepted wherever `media.*` takes a ref or bytes. The
+    // last step of a chain promotes the result with the matching `media.to*`
+    // call. Only this promotion writes to storage; intermediates never do. The
+    // wrapped members share one signature, so they are held under that type and
+    // only the assembled `media` object claims the bridge's shape.
+    const mediaMembers = Object.fromEntries(Object.entries(mediaRefBridge).map(([name, fn]) => [
+        name,
+        async (...args) => fn(...(await resolveMediaArgs(`media.${name}`, args, false)))
+    ]));
+    const promoteTypedHandle = (name, promote) => async (value, options) => {
+        if (isSandboxMediaHandle(value)) {
+            return promote(value, options);
+        }
+        return mediaMembers[name](value, options);
+    };
+    const media = {
+        ...mediaMembers,
+        toImage: promoteTypedHandle("toImage", image.toAsset),
+        toAudio: promoteTypedHandle("toAudio", audio.toAsset),
+        toVideo: promoteTypedHandle("toVideo", video.toAsset)
+    };
     const sandbox = {
         // Core JS globals are native in QuickJS; we still reflect them in the
         // descriptor so callers that inspect `sandbox.JSON` / `sandbox.Math`
@@ -412,33 +1796,81 @@ export function buildSandbox(context) {
         TextDecoder: globalThis.TextDecoder,
         URL: globalThis.URL,
         URLSearchParams: globalThis.URLSearchParams,
-        // Async primitives blocked — use sleep() instead.
+        // Timer globals blocked — use sleep() for delays and Promise.all /
+        // parallelMap for concurrency. The engine re-installs host-backed timers
+        // on every evaluation, so the real deletion happens in wrapCode; these
+        // entries keep the manifest's blocked list truthful.
         setTimeout: undefined,
+        clearTimeout: undefined,
         setInterval: undefined,
+        clearInterval: undefined,
+        setImmediate: undefined,
+        clearImmediate: undefined,
         // Bridge functions — the only non-native surface the sandbox exposes.
         fetch: sandboxedFetch,
-        uuid,
+        crypto: sandboxCrypto,
         sleep,
         getSecret,
         workspace,
         assetToSandbox,
         sandboxToAsset,
-        __maxIter: MAX_LOOP_ITERATIONS
+        progress,
+        emit,
+        output,
+        // Behind the `stream` global the prelude builds; never reachable by name,
+        // which is why they are not in EXPOSED_BRIDGE_NAMES.
+        [SANDBOX_INPUT_TAKE_BINDING]: takeInput,
+        [SANDBOX_STREAM_OPEN_BINDING]: streamOpen,
+        format,
+        image,
+        audio,
+        video,
+        canvas,
+        media,
+        __maxIter: MAX_LOOP_ITERATIONS,
+        // The run's declared secret scope, so `nodetool.secrets.list()` can answer
+        // without a host call. Reading it is not the check — `getSecret` is.
+        __secretScope: secretScope === null ? null : [...secretScope]
+    };
+    return {
+        sandbox,
+        getLogs: () => logs,
+        getOutputs: () => outputs.size > 0 ? Object.fromEntries(outputs) : undefined,
+        getEmitted: () => (emitted.length > 0 ? [...emitted] : undefined)
     };
-    return { sandbox, getLogs: () => logs };
 }
 // ---------------------------------------------------------------------------
 // Code execution
 // ---------------------------------------------------------------------------
 /**
- * Wrap user code as the default export of an ES module with a top-level-awaited
- * async IIFE body, so `return <value>` inside the snippet becomes the module's
- * default export and `await` at the top level works.
+ * User-code wrapping and the guest module loader live with the interpreter:
+ * the worker path evaluates the same entry module and resolves through the
+ * same loader, and a second copy of either would be a second security policy.
  */
-export function wrapCode(code) {
-    return `export default await (async () => {
-${code}
-})();`;
+export { BLOCKED_TIMER_GLOBALS, buildEntryModule, createGuestModuleHost, DELETED_GUEST_GLOBALS, EXPOSED_BRIDGE_NAMES, SANDBOX_CAPABILITY_BRIDGE_BINDING, SANDBOX_HOST_BRIDGE_BINDING, SANDBOX_INPUT_TAKE_BINDING, SANDBOX_STREAM_OPEN_BINDING, SANDBOX_WASM_BRIDGE_BINDING, wrapCode } from "./js-sandbox-worker/interpreter.js";
+export function createSandboxClock() {
+    let depth = 0;
+    let openedAt = 0;
+    let accumulated = 0;
+    return {
+        suspend() {
+            if (depth === 0)
+                openedAt = Date.now();
+            depth++;
+            let resumed = false;
+            return () => {
+                if (resumed)
+                    return;
+                resumed = true;
+                depth--;
+                if (depth === 0)
+                    accumulated += Date.now() - openedAt;
+            };
+        },
+        suspendedMs() {
+            return depth > 0 ? accumulated + (Date.now() - openedAt) : accumulated;
+        }
+    };
 }
 const IDENTIFIER_RE = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 /** Overwrite the contents of `target` with the contents of `source` in place. */
@@ -451,47 +1883,77 @@ function replaceInPlace(target, source) {
         }
         return;
     }
-    if (target && typeof target === "object") {
+    if (isObjectLike(target)) {
         const t = target;
         for (const key of Object.keys(t))
             delete t[key];
-        if (source && typeof source === "object" && !Array.isArray(source)) {
+        if (isRecord(source)) {
             const s = source;
             for (const [k, v] of Object.entries(s))
                 t[k] = v;
         }
     }
 }
+/**
+ * Globals the guest prelude defines rather than the host marshals. All but
+ * `stream` are pure — no host call behind them; `stream` is built here because
+ * an async iterable cannot cross the bridge, so the prelude wraps the two
+ * private input bindings into one.
+ */
+export const GUEST_HELPER_NAMES = [
+    "toBase64",
+    "fromBase64",
+    "toHex",
+    "fromHex",
+    "parallelMap",
+    "createCanvas",
+    "stream"
+];
+/**
+ * A dispatcher's entry point as a bare function, or nothing when the run
+ * declared no such modules — which is what decides whether the guest gets the
+ * binding at all.
+ */
+function dispatchCallOf(dispatcher) {
+    if (dispatcher === undefined)
+        return undefined;
+    return async (moduleKey, exportName, args) => dispatcher.call(moduleKey, exportName, args);
+}
 /** Names that should never be reassigned via `globals` — core sandbox APIs. */
-const RESERVED_SANDBOX_NAMES = new Set([
-    "console",
-    "fetch",
-    "uuid",
-    "sleep",
-    "getSecret",
-    "workspace",
-    "assetToSandbox",
-    "sandboxToAsset",
-    "__maxIter"
+export const RESERVED_SANDBOX_NAMES = new Set([
+    ...EXPOSED_BRIDGE_NAMES,
+    ...GUEST_HELPER_NAMES,
+    SANDBOX_WASM_BRIDGE_BINDING,
+    SANDBOX_WASM_DISPATCH_GLOBAL,
+    SANDBOX_CAPABILITY_BRIDGE_BINDING,
+    SANDBOX_CAPABILITY_DISPATCH_GLOBAL,
+    SANDBOX_INPUT_TAKE_BINDING,
+    SANDBOX_STREAM_OPEN_BINDING,
+    GUEST_MARSHAL_GLOBAL,
+    GUEST_GLOBALS_JSON_BINDING,
+    GUEST_GLOBALS_SIDECAR_BINDING
 ]);
 /**
- * Names injected as bridge bindings into the QuickJS guest. The rest of the
- * `buildSandbox` record (JSON, Math, Date, URL, etc.) is deliberately NOT
- * marshaled — QuickJS already provides native implementations, and re-exposing
- * host versions creates thousands of handles that slow execution and leak on
- * teardown.
+ * Combine a guest error's name and message the way the report reads best:
+ * include the name when it carries signal (`ExecutionTimeout`), drop it when
+ * it is `Error` or already inside the message.
  */
-const EXPOSED_BRIDGE_NAMES = [
-    "console",
-    "fetch",
-    "uuid",
-    "sleep",
-    "getSecret",
-    "workspace",
-    "assetToSandbox",
-    "sandboxToAsset",
-    "__maxIter"
-];
+function combineGuestError(name, message) {
+    return name &&
+        name !== "Error" &&
+        !message.toLowerCase().includes(name.toLowerCase())
+        ? `${name}: ${message}`
+        : message || name;
+}
+/** Warn once per process when the worker path silently falls back in-process. */
+let warnedWorkerFallback = false;
+function noteWorkerFallback(reason) {
+    if (warnedWorkerFallback)
+        return;
+    warnedWorkerFallback = true;
+    console.warn(`sandbox: running in-process (${reason}); a CPU-bound guest will block ` +
+        "this thread until its timeout");
+}
 /**
  * Execute JavaScript code inside a QuickJS WebAssembly sandbox.
  *
@@ -499,11 +1961,85 @@ const EXPOSED_BRIDGE_NAMES = [
  * handler / memory limiter, so runaway user code can't exhaust host resources.
  */
 export async function runInSandbox(options) {
-    const { code, context, timeoutMs = DEFAULT_TIMEOUT_MS, globals } = options;
+    const { code, context, timeoutMs = DEFAULT_TIMEOUT_MS, globals, signal, limits, onProgress, onLog, onEmit, onTakeInput, onStreamOpen, clock, modules, capabilities, wasmPool, resolveMediaRef, promoteMedia, resolveHost } = options;
+    if (options.hermetic && (capabilities || (globals && Object.keys(globals).length) ||
+        modules?.modules.some((module) => module.kind !== "js"))) {
+        return { success: false, error: "Hermetic execution accepts only guest JavaScript modules and literal program inputs", logs: [] };
+    }
+    const resolvedLimits = resolveSandboxLimits(limits);
+    // A streaming run needs a clock whether or not the caller brought one: the
+    // time it spends parked on upstream is not its own execution.
+    const activeClock = clock ?? (onTakeInput ? createSandboxClock() : undefined);
+    const suspendAllowanceMs = options.suspendAllowanceMs ??
+        (onTakeInput
+            ? INPUT_STREAM_SUSPEND_ALLOWANCE_MS
+            : DEFAULT_SUSPEND_ALLOWANCE_MS);
     if (!code.trim()) {
         return { success: false, error: "No code provided", logs: [] };
     }
-    const { sandbox, getLogs } = buildSandbox(context);
+    // The dispatcher is built first: it reads every declared WASM binary, so a
+    // module the catalog could not honour is reported here rather than as a
+    // broken facade the guest imports.
+    let wasm;
+    let hostModules;
+    const wasmOptions = {};
+    if (wasmPool !== undefined)
+        wasmOptions.pool = wasmPool;
+    if (signal !== undefined)
+        wasmOptions.signal = signal;
+    const hostOptions = {};
+    if (signal !== undefined)
+        hostOptions.signal = signal;
+    try {
+        wasm = modules && !options.hermetic
+            ? createSandboxWasmDispatcher(modules.modules, wasmOptions)
+            : undefined;
+        hostModules = modules && !options.hermetic
+            ? createSandboxHostDispatcher(modules.modules, hostOptions)
+            : undefined;
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : String(error),
+            logs: []
+        };
+    }
+    if (signal?.aborted) {
+        return { success: false, error: "Execution cancelled", logs: [] };
+    }
+    const streams = {};
+    if (onTakeInput !== undefined)
+        streams.onTakeInput = onTakeInput;
+    if (onStreamOpen !== undefined)
+        streams.onStreamOpen = onStreamOpen;
+    if (activeClock !== undefined)
+        streams.clock = activeClock;
+    const { sandbox, getLogs, getOutputs, getEmitted } = buildSandbox(options.hermetic ? undefined : context, signal, resolvedLimits, options.hermetic ? undefined : onProgress, options.hermetic ? undefined : onLog, options.hermetic ? undefined : onEmit, options.hermetic ? {} : streams, options.hermetic ? undefined : resolveMediaRef, options.hermetic ? undefined : promoteMedia, options.hermetic ? undefined : resolveHost);
+    if (options.hermetic) {
+        // Deny host bridge functions before either interpreter receives them.
+        // Only console collection survives. Native guest arithmetic is not a bridge.
+        const refuse = (path) => async () => {
+            throw new Error(`${path} is unavailable during hermetic construction`);
+        };
+        const restrict = (value, path) => {
+            if (typeof value === "function") {
+                return refuse(path);
+            }
+            if (value && typeof value === "object") {
+                return Object.fromEntries(Object.entries(value).map(([key, member]) => [key, restrict(member, `${path}.${key}`)]));
+            }
+            return value;
+        };
+        const hostBindings = sandbox;
+        for (const name of EXPOSED_BRIDGE_NAMES) {
+            if (name !== "console") {
+                hostBindings[name] = restrict(hostBindings[name], name);
+            }
+        }
+        hostBindings[SANDBOX_INPUT_TAKE_BINDING] = refuse("stream");
+        hostBindings[SANDBOX_STREAM_OPEN_BINDING] = () => false;
+    }
     // User-supplied globals (dynamic inputs from CodeNode etc.) layer on top of
     // the core surface, but must not clobber the bridge functions themselves.
     const userGlobals = {};
@@ -517,138 +2053,299 @@ export async function runInSandbox(options) {
         }
     }
     // Identify object-typed globals whose contents should be synced back to the
-    // host after the guest runs. Primitives are passed by value and need no sync.
+    // host after the guest runs. Primitives are passed by value and need no
+    // sync. A global holding a function anywhere inside it — a hermetic bake's
+    // `{ nodetool: { timelines: { edit() {...} } } }` stub — is excluded even
+    // though it is object-typed: nothing reads a synced-back copy of a stub
+    // (CodeNode's `state` object is the only real consumer, and it never holds
+    // functions), and extracting the guest's current value asks the engine to
+    // marshal a live function back out on every successful run, on top of the
+    // one it already crossed in as. That is reach the sync-back exists to
+    // avoid, not a capability it needs.
+    const objectGlobalHasFunction = (value, seen = new Set()) => {
+        if (typeof value === "function")
+            return true;
+        if (value === null || typeof value !== "object")
+            return false;
+        if (seen.has(value))
+            return false;
+        seen.add(value);
+        return Object.values(value).some((entry) => objectGlobalHasFunction(entry, seen));
+    };
     const syncTargetNames = Object.entries(userGlobals)
-        .filter(([, v]) => v !== null && typeof v === "object")
+        .filter(([, v]) => isObjectLike(v) && !objectGlobalHasFunction(v))
         .map(([k]) => k);
+    // Write the extracted object-global snapshots back into the caller's own
+    // objects. Both paths end here: node:vm shared the host heap, QuickJS does
+    // not, and a worker makes the separation literal. CodeNode relies on this to
+    // make its `state` object persist across invocations.
+    const writeBackGlobals = (extracted) => {
+        if (!extracted)
+            return;
+        for (const name of syncTargetNames) {
+            const hostValue = userGlobals[name];
+            const guestValue = extracted[name];
+            if (isObjectLike(hostValue) && isObjectLike(guestValue)) {
+                replaceInPlace(hostValue, guestValue);
+            }
+        }
+    };
+    // Off the main thread whenever possible. A CPU-bound guest blocks whichever
+    // thread runs it; on the server's main thread that freeze takes the whole
+    // event loop — including the websocket `stop` frame that would have
+    // cancelled the run — down with it. On a worker, abort is `terminate()`,
+    // immediate for spinning and parked guests alike; the logs and emitted
+    // values survive because they accumulate on this side of the port.
+    //
+    // Streaming runs stay in-process: the synchronous `stream.open` probe is
+    // served from a worker-local mirror that must be seeded with the handle
+    // names, which this signature does not carry. Those runs park on takes and
+    // yield the thread constantly, so the freeze this path exists for cannot
+    // build up there.
+    const env = typeof globalThis.process?.env === "object"
+        ? globalThis.process.env
+        : undefined;
+    const workerRequired = env?.NODETOOL_SANDBOX_WORKER === "require";
+    let workerUnavailable = null;
+    // A chosen or designed fallback is quiet; an environmental one warns once.
+    let fallbackByDesign = false;
+    if (env?.NODETOOL_SANDBOX_INPROC === "1") {
+        workerUnavailable = "NODETOOL_SANDBOX_INPROC=1";
+        fallbackByDesign = true;
+    }
+    else if (onTakeInput !== undefined || onStreamOpen !== undefined) {
+        workerUnavailable = "the run streams inputs";
+        fallbackByDesign = true;
+    }
+    else {
+        const safety = precheckCloneSafety(userGlobals);
+        if (!safety.ok) {
+            workerUnavailable = safety.reason;
+        }
+    }
+    if (workerUnavailable === null) {
+        const dispatcherKinds = [];
+        const dispatch = { ...sandbox };
+        const bindDispatcher = (kind, call) => {
+            if (call === undefined)
+                return;
+            dispatch[SANDBOX_DISPATCHER_BINDINGS[kind]] = call;
+            dispatcherKinds.push(kind);
+        };
+        bindDispatcher("wasm", dispatchCallOf(wasm));
+        bindDispatcher("host", dispatchCallOf(hostModules));
+        bindDispatcher("capability", dispatchCallOf(capabilities));
+        for (const [name, value] of Object.entries(userGlobals)) {
+            if (isFunction(value))
+                dispatch[name] = value;
+        }
+        const workerRun = {
+            runId: globalThis.crypto.randomUUID(),
+            code,
+            timeoutMs,
+            limits: resolvedLimits,
+            suspendAllowanceMs,
+            hasClock: activeClock !== undefined,
+            engineTimeoutMs: activeClock !== undefined
+                ? Math.min(timeoutMs + suspendAllowanceMs, MAX_ENGINE_TIMEOUT_MS)
+                : timeoutMs,
+            streamOpenSeed: null,
+            bridgeShape: deriveBridgeShape({
+                bridges: sandbox,
+                dispatchers: dispatcherKinds,
+                globals: userGlobals
+            })
+        };
+        if (modules !== undefined)
+            workerRun.modules = modules;
+        if (capabilities?.facades !== undefined) {
+            workerRun.capabilityFacades = capabilities.facades;
+        }
+        const workerOptions = {
+            run: workerRun,
+            dispatch,
+            // Console and progress already reach their accumulators through the
+            // RPC'd bridges; the push channel exists for a worker that has nothing
+            // else to say, which this integration does not use.
+            onLog: () => { },
+            onProgress: () => { }
+        };
+        if (signal !== undefined)
+            workerOptions.signal = signal;
+        if (activeClock !== undefined) {
+            workerOptions.suspendedMs = () => activeClock.suspendedMs();
+        }
+        const message = await runInWorker(workerOptions);
+        if (message === null) {
+            workerUnavailable = "no sandbox worker could be started here";
+        }
+        else {
+            writeBackGlobals(message.syncedGlobals);
+            const logs = getLogs();
+            // Cancellation wins over whatever the guest was doing when the interrupt
+            // handler cut it — the in-process race has the same rule. The interrupted
+            // guest's own error (`InternalError: interrupted`) is an implementation
+            // detail, not a result.
+            if (signal?.aborted === true) {
+                return {
+                    success: false,
+                    error: "Execution cancelled",
+                    logs,
+                    emitted: getEmitted()
+                };
+            }
+            if (message.failure === "cancelled") {
+                return {
+                    success: false,
+                    error: "Execution cancelled",
+                    logs,
+                    emitted: getEmitted()
+                };
+            }
+            if (message.failure === "worker") {
+                return {
+                    success: false,
+                    error: describeEngineFailure(new Error(message.errorMessage ?? "the sandbox worker failed")),
+                    logs: logs.length > 0 ? logs : undefined,
+                    emitted: getEmitted()
+                };
+            }
+            if (!message.evalOk) {
+                return {
+                    success: false,
+                    error: combineGuestError(message.errorName ?? "", message.errorMessage ?? ""),
+                    stack: message.errorStack
+                        ? cleanStack(message.errorStack)
+                        : undefined,
+                    logs: logs.length > 0 ? logs : undefined,
+                    emitted: getEmitted()
+                };
+            }
+            return {
+                success: true,
+                result: serializeResult(message.data, resolvedLimits.maxOutputSize),
+                logs: logs.length > 0 ? logs : undefined,
+                outputs: getOutputs(),
+                emitted: getEmitted()
+            };
+        }
+    }
+    if (workerRequired) {
+        return {
+            success: false,
+            error: `the sandbox worker path is required (NODETOOL_SANDBOX_WORKER=require) but unavailable: ${workerUnavailable}`,
+            logs: []
+        };
+    }
+    if (!fallbackByDesign) {
+        noteWorkerFallback(workerUnavailable);
+    }
     try {
         const { runSandboxed } = await getEngine();
-        const evalResponse = await runSandboxed(async ({ ctx, evalCode }) => {
-            const bridges = {};
-            for (const name of EXPOSED_BRIDGE_NAMES) {
-                bridges[name] = sandbox[name];
-            }
-            // Wrap every async bridge in a never-reject adapter (see
-            // SANDBOX_ERROR_MARKER above). The guest prelude rewraps them back into
-            // throwing functions before user code runs.
-            bridges.fetch = neverReject(bridges.fetch);
-            bridges.sleep = neverReject(bridges.sleep);
-            bridges.getSecret = neverReject(bridges.getSecret);
-            bridges.assetToSandbox = neverReject(bridges.assetToSandbox);
-            bridges.sandboxToAsset = neverReject(bridges.sandboxToAsset);
-            const ws = bridges.workspace;
-            bridges.workspace = {
-                read: neverReject(ws.read),
-                write: neverReject(ws.write),
-                list: neverReject(ws.list)
-            };
-            Object.assign(bridges, userGlobals);
-            // `expose` manages its own internal Scope; the second arg is unused.
-            const disposable = new Scope();
-            try {
-                expose(ctx, disposable, bridges);
-            }
-            finally {
-                disposable.dispose();
-            }
-            // Block dynamic code generation and re-wrap the never-reject bridges as
-            // throwing guest-side functions. Direct eval in QuickJS can't be neutered
-            // by overwriting `globalThis.eval` (QuickJS still resolves the builtin),
-            // but a plain `delete` removes the binding entirely so any reference
-            // throws ReferenceError — same for `Function`.
-            await evalCode(`const __marker = "${SANDBOX_ERROR_MARKER}";
-const __wrap = (fn) => async (...args) => {
-  const r = await fn(...args);
-  if (r && r[__marker]) {
-    const e = new Error(r.message);
-    e.name = r.name;
-    throw e;
-  }
-  return r;
-};
-globalThis.fetch = __wrap(globalThis.fetch);
-globalThis.sleep = __wrap(globalThis.sleep);
-globalThis.getSecret = __wrap(globalThis.getSecret);
-globalThis.assetToSandbox = __wrap(globalThis.assetToSandbox);
-globalThis.sandboxToAsset = __wrap(globalThis.sandboxToAsset);
-const __ws = globalThis.workspace;
-globalThis.workspace = {
-  read: __wrap(__ws.read),
-  write: __wrap(__ws.write),
-  list: __wrap(__ws.list)
-};
-delete globalThis.eval;
-delete globalThis.Function;
-export default true;`, "sandbox-init");
-            const userResult = await evalCode(wrapCode(code), "user-code");
-            // Sync mutable globals back to the host. node:vm shared the host heap,
-            // so `state.counter++` in user code mutated the caller's object directly.
-            // With QuickJS the guest heap is isolated, so after user code runs we
-            // extract the current values of the object-typed user globals and
-            // replace the contents of the host-side objects in place. CodeNode
-            // relies on this to make its `state` object persist across invocations.
-            if (userResult.ok && syncTargetNames.length > 0) {
-                const extractor = `export default {${syncTargetNames
-                    .map((n) => `${n}: (typeof ${n} !== 'undefined' && ${n} !== null) ? ${n} : null`)
-                    .join(", ")}};`;
-                const syncResp = await evalCode(extractor, "sandbox-sync");
-                if (syncResp.ok && syncResp.data && typeof syncResp.data === "object") {
-                    const extracted = syncResp.data;
-                    for (const name of syncTargetNames) {
-                        const hostValue = userGlobals[name];
-                        const guestValue = extracted[name];
-                        if (hostValue !== null &&
-                            typeof hostValue === "object" &&
-                            guestValue !== null &&
-                            typeof guestValue === "object") {
-                            replaceInPlace(hostValue, guestValue);
-                        }
-                    }
-                }
-            }
-            return userResult;
-        }, {
-            executionTimeout: timeoutMs,
-            memoryLimit: GUEST_MEMORY_LIMIT,
-            maxStackSize: GUEST_STACK_LIMIT
+        // The dispatchers stay on this side of the boundary — the interpreter only
+        // ever sees a call function, which is as true of a worker's RPC proxy as it
+        // is of the real dispatcher here.
+        const interpreterParams = {
+            runSandboxed,
+            code,
+            sandbox,
+            globals: userGlobals,
+            syncTargetNames,
+            timeoutMs,
+            limits: resolvedLimits,
+            suspendAllowanceMs,
+            hasClock: activeClock !== undefined,
+            wasmCall: dispatchCallOf(wasm),
+            hostCall: dispatchCallOf(hostModules),
+            capabilityCall: dispatchCallOf(capabilities),
+            modules,
+            capabilityFacades: capabilities?.facades
+        };
+        // The interpreter cannot hold either host object: neither an AbortSignal
+        // nor a clock survives a thread boundary, so both arrive as a probe.
+        if (signal !== undefined) {
+            interpreterParams.isAborted = () => signal.aborted;
+        }
+        if (activeClock !== undefined) {
+            interpreterParams.suspendedMs = () => activeClock.suspendedMs();
+        }
+        const sandboxRun = runInterpreter(interpreterParams).then((outcome) => {
+            // The write-back runs as soon as the guest is done, even when
+            // cancellation already won the race below — an orphaned run still owns
+            // the answer it computed.
+            writeBackGlobals(outcome.syncedGlobals);
+            return outcome;
+        });
+        // Return as soon as cancellation lands. The bridges above make a guest that
+        // awaits anything unwind almost immediately; this race additionally covers
+        // a CPU-bound guest, which QuickJS gives us no way to interrupt early — the
+        // orphaned run still winds down on its own execution timeout.
+        const cancellation = new Promise((resolve) => {
+            if (!signal)
+                return;
+            signal.addEventListener("abort", () => resolve(null), { once: true });
         });
+        const raced = await guardHostProcess(Promise.race([sandboxRun, cancellation]));
+        if (raced === null) {
+            return {
+                success: false,
+                error: "Execution cancelled",
+                logs: getLogs(),
+                emitted: getEmitted()
+            };
+        }
+        const evalResponse = raced;
         const logs = getLogs();
         if (!evalResponse.ok) {
-            // Include the error name alongside the message when the name carries
-            // useful signal (e.g. `ExecutionTimeout` for the library's wall-clock
-            // abort). `Error` is redundant, so omit it.
-            const name = evalResponse.error.name;
-            const message = evalResponse.error.message;
-            const combined = name && name !== "Error" && !message.toLowerCase().includes(name.toLowerCase())
-                ? `${name}: ${message}`
-                : message || name;
+            const combined = combineGuestError(evalResponse.error.name, evalResponse.error.message);
             return {
                 success: false,
                 error: combined,
                 stack: evalResponse.error.stack
                     ? cleanStack(evalResponse.error.stack)
                     : undefined,
-                logs: logs.length > 0 ? logs : undefined
+                logs: logs.length > 0 ? logs : undefined,
+                // Emitted values were delivered while the guest still ran, so they
+                // stand. Recorded `output` finals do not: the run has no answer.
+                emitted: getEmitted()
             };
         }
         return {
             success: true,
-            result: serializeResult(evalResponse.data),
-            logs: logs.length > 0 ? logs : undefined
+            result: serializeResult(evalResponse.data, resolvedLimits.maxOutputSize),
+            logs: logs.length > 0 ? logs : undefined,
+            outputs: getOutputs(),
+            emitted: getEmitted()
         };
     }
     catch (e) {
-        // Host-side failures (engine load error, marshaling bug, etc.). Guest-side
-        // errors go through evalResponse.ok=false above.
+        // Host-side failures (engine load error, marshaling bug, an aborted
+        // runtime). Guest-side errors go through evalResponse.ok=false above.
+        // An engine failure is reported in terms the caller can act on: the raw
+        // Emscripten assertion text tells an agent nothing it can retry against.
         const logs = getLogs();
-        const errorMessage = e instanceof Error ? e.message : String(e);
+        const errorMessage = describeEngineFailure(e);
         const errorStack = e instanceof Error ? cleanStack(e.stack ?? "") : undefined;
         return {
             success: false,
             error: errorMessage,
             stack: errorStack,
-            logs: logs.length > 0 ? logs : undefined
+            logs: logs.length > 0 ? logs : undefined,
+            emitted: getEmitted()
         };
     }
 }
+// ---------------------------------------------------------------------------
+// Guest preludes for tool-bridged hosts
+// ---------------------------------------------------------------------------
+/**
+ * Re-exported here because `./js-sandbox` is the one browser-safe subpath
+ * export of this package: `nodetool.code.Code` (packages/code-nodes) is
+ * bundled for the in-browser runner and must reach these prelude strings
+ * without importing the package index, which drags the whole toolbelt —
+ * native canvas, IMAP, execution — into a web build. Both modules are pure
+ * strings over leaf imports.
+ */
+export { TOOLS_PRELUDE } from "./codeact/tools-prelude.js";
+export { NODETOOL_API_PRELUDE_FULL } from "./codeact/nodetool-api.js";
 //# sourceMappingURL=js-sandbox.js.map