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

package/dist/js-sandbox.d.ts

@@ -1,21 +1,59 @@
 /**
  * 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 { type SandboxModuleResolution } from "@nodetool-ai/protocol";
+import { type WasmWorkerPool } from "./wasm-sandbox/host.js";
+import { type HostResolver } from "./network-guard.js";
+import { MAX_RANDOM_BYTES } from "./sandbox-constants.js";
 import type { ProcessingContext } from "@nodetool-ai/runtime";
 export declare const DEFAULT_TIMEOUT_MS = 30000;
 export declare const MAX_OUTPUT_SIZE = 100000;
@@ -26,12 +64,208 @@ export declare const MAX_RESPONSE_BODY_SIZE = 1000000;
 export declare const GUEST_MEMORY_LIMIT: number;
 /** Guest stack cap — protects against deeply recursive code. */
 export declare const GUEST_STACK_LIMIT: number;
+/** Per-request wall-clock cap for the fetch bridge. */
+export declare const FETCH_TIMEOUT_MS = 15000;
+/** Redirect hops the fetch bridge follows before giving up. */
+export declare const MAX_FETCH_REDIRECTS = 5;
+/** Locale used by the `format` bridge when the caller names none. */
+export declare const DEFAULT_FORMAT_LOCALE = "en-US";
+export { MAX_RANDOM_BYTES };
+/** Progress reports forwarded to the host per run; further calls are dropped. */
+export declare const MAX_PROGRESS_CALLS = 1000;
+/** Console lines forwarded to {@link RunSandboxOptions.onLog} per run. */
+export declare const MAX_CONSOLE_LOGS = 1000;
+/** Longest console line forwarded to the host. A collected line is not truncated on its own. */
+export declare 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 declare const MAX_COLLECTED_CONSOLE_LOGS = 5000;
+/** Characters the run's `logs` array collects in total, across every line. */
+export declare const MAX_COLLECTED_CONSOLE_CHARS: number;
+/** The single line that closes a collected log the caps cut. */
+export declare const CONSOLE_LOGS_CUT_NOTICE: string;
+/**
+ * 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 declare const MAX_EMIT_CALLS = 10000;
+/** Minimum gap between two forwarded progress reports. */
+export declare const PROGRESS_MIN_INTERVAL_MS = 100;
+/** Longest progress message forwarded to the host. */
+export declare 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 declare const DEFAULT_SUSPEND_ALLOWANCE_MS: number;
+/**
+ * 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 declare const INPUT_STREAM_SUSPEND_ALLOWANCE_MS = 2147483647;
+/** Host sink for guest `progress()` calls. */
+export type SandboxProgressCallback = (progress: number, message?: string) => void;
+/** Guest `console.*` method that produced a line. */
+export type SandboxLogLevel = "log" | "info" | "warn" | "error";
+/**
+ * Host sink for guest `console.*` calls. Synchronous and fire-and-forget:
+ * a failing sink does not take the guest down. At most
+ * {@link MAX_CONSOLE_LOGS} lines are forwarded, each truncated to
+ * {@link MAX_CONSOLE_LOG_CHARS}. The run's `logs` array collects lines up to
+ * {@link MAX_COLLECTED_CONSOLE_LOGS} / {@link MAX_COLLECTED_CONSOLE_CHARS},
+ * then one {@link CONSOLE_LOGS_CUT_NOTICE}. Without a callback the guest
+ * console still writes that array.
+ */
+export type SandboxLogCallback = (level: SandboxLogLevel, message: string) => void;
+/**
+ * Host sink for guest `emit(name, value)` calls. Awaited before the guest's
+ * promise resolves, so a slow consumer applies backpressure to the producer,
+ * and a sink that throws surfaces in the guest as a thrown error.
+ */
+export type SandboxEmitCallback = (name: string, value: unknown) => void | Promise<void>;
+/** One value a guest `emit(name, value)` call delivered. */
+export interface SandboxEmittedValue {
+    name: string;
+    value: unknown;
+}
+/**
+ * One answer to a guest take: the next value for a handle, or end-of-stream.
+ *
+ * `done: true` ends the iteration the guest is driving — for a named handle
+ * that upstream produced everything it will, for {@link SandboxTakeInputCallback}
+ * called with `null` that every handle has.
+ */
+export type SandboxInputTake = {
+    done: true;
+} | {
+    done: false;
+    handle: string;
+    value: unknown;
+};
+/**
+ * Host source behind the guest's `stream` global.
+ *
+ * `handle` names one input handle, or is `null` for `stream.any()` — "the next
+ * value on any handle, in arrival order". The host keeps the iteration state
+ * (one inbox iterator per handle plus one for `any`); the sandbox only relays
+ * the call and marshals the answer. The returned `value` must already be
+ * JSON-safe: the sandbox tags bytes for the guest prelude to revive but does
+ * not deep-copy, exactly as with `globals`.
+ */
+export type SandboxTakeInputCallback = (handle: string | null) => Promise<SandboxInputTake>;
+/**
+ * Host answer to `stream.open(name)`: could more arrive on this handle?
+ *
+ * Synchronous, because the guest call is — the value is inbox state the host
+ * already holds, and an awaitable answer would make `if (stream.open(h))` read
+ * true on a pending promise.
+ */
+export type SandboxStreamOpenCallback = (handle: string) => boolean;
+/**
+ * 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";
+/** The input-side bridges {@link buildSandbox} wires behind the `stream` global. */
+export interface SandboxInputStreams {
+    /** Source of values. Without it every `stream` call throws. */
+    onTakeInput?: SandboxTakeInputCallback;
+    /** Answer to `stream.open(name)`. Without it every handle reads closed. */
+    onStreamOpen?: SandboxStreamOpenCallback;
+    /**
+     * Clock suspended while a take is parked. Waiting on upstream is not guest
+     * execution, so it must not be charged to the run's timeout.
+     */
+    clock?: SandboxClock;
+}
+/**
+ * Per-invocation limit overrides. Every field defaults to the module constant
+ * above and is clamped to a hard ceiling, so a caller can tighten a limit or
+ * raise it within bounds but never switch a protection off.
+ */
+export interface SandboxLimits {
+    maxFetchCalls?: number;
+    maxResponseBodyBytes?: number;
+    maxOutputSize?: number;
+    memoryLimitBytes?: number;
+    /**
+     * Total bytes of media one run may hold host-side for its handles. The
+     * aggregate the per-call image/media ceilings never bounded.
+     */
+    runMediaBytes?: number;
+    stackLimitBytes?: number;
+    fetchTimeoutMs?: number;
+    /**
+     * Permit fetches to loopback, link-local and private address ranges.
+     *
+     * Off by default: guest code is untrusted, so the SSRF guard is the norm and
+     * this is the exception. It exists because the trusted `lib.http` nodes have
+     * always been able to reach a local service, and a Code node replacing one
+     * must be able to do the same — a workflow pointing at `http://localhost:8000`
+     * would otherwise silently stop working.
+     *
+     * Host-set only: it is read from {@link RunSandboxOptions.limits} and never
+     * exposed to the guest, so sandboxed code cannot turn it on for itself.
+     */
+    allowPrivateNetwork?: boolean;
+    /** `User-Agent` for bridge fetches. Guest-set headers still win. */
+    userAgent?: string;
+    /**
+     * `"workspace"` (default) confines every `workspace.*` call to the workspace
+     * root, symlinks included. `"host"` lifts that to the whole filesystem the
+     * process can reach, with `~` expanded.
+     *
+     * Off by default for the same reason as {@link allowPrivateNetwork}, and the
+     * stakes are higher — host mode can read credential files. It exists because
+     * roughly half the `lib.os` nodes already operate on arbitrary host paths
+     * (`expandUser` + raw `node:fs`), so a Code node replacing one needs the same
+     * reach. Host-set only, and the graph migration sets it only on nodes
+     * rewritten from such a node — a hand-written or model-authored Code node
+     * stays confined.
+     */
+    filesystemAccess?: "workspace" | "host";
+    /**
+     * The secret names this run may read, or `null`/absent for every secret the
+     * store holds.
+     *
+     * A script that talks to an external service needs one credential, and
+     * nothing about `getSecret` used to say so: a node written to send a Slack
+     * message could read the AWS keys. Declaring the scope makes the credential
+     * a node reaches part of the node, visible in the graph and refused at the
+     * bridge rather than trusted to the code.
+     *
+     * Host-set only, like {@link allowPrivateNetwork}. A run reads its own scope
+     * through `nodetool.secrets.list()` but cannot widen it, and an empty array
+     * means no secret at all — a stricter thing than an absent scope, not a
+     * looser one.
+     */
+    secretScope?: readonly string[] | null;
+}
+export type ResolvedSandboxLimits = Required<SandboxLimits>;
+/** Apply defaults and ceilings to a caller-supplied {@link SandboxLimits}. */
+export declare function resolveSandboxLimits(limits?: SandboxLimits): ResolvedSandboxLimits;
+/** The agent-facing translation of an engine failure. */
+export declare function describeEngineFailure(error: unknown): string;
 export declare function truncate(text: string, max: number): string;
+export type SandboxMediaModule = typeof import("./sandbox-media.js");
+export type SandboxAvMediaModule = typeof import("./sandbox-av-media.js");
 /**
  * Recursively serialize a value returned from the sandbox, converting typed
  * arrays to native Uint8Array and enforcing output size limits.
  */
-export declare function serializeResult(result: unknown): unknown;
+export declare function serializeResult(result: unknown, maxOutputSize?: number): any;
 /**
  * Trim engine/library frames from a stack trace so the user sees only their
  * own code. Keeps QuickJS frames (`user-code`, `<evalScript>`, `<anonymous>`)
@@ -41,6 +275,16 @@ export declare function cleanStack(stack: string): string;
 export interface SandboxResult {
     sandbox: Record<string, unknown>;
     getLogs: () => string[];
+    /**
+     * The final values guest `output(name, value)` calls recorded, or `undefined`
+     * when the guest called `output` never.
+     */
+    getOutputs: () => Record<string, unknown> | undefined;
+    /**
+     * Values guest `emit` calls produced while no host sink was set, in call
+     * order. `undefined` when a sink consumed them or nothing was emitted.
+     */
+    getEmitted: () => SandboxEmittedValue[] | undefined;
 }
 /**
  * Build a sandbox descriptor: a record of host-side bindings plus a `getLogs`
@@ -49,14 +293,63 @@ export interface SandboxResult {
  *
  * @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 declare function buildSandbox(context?: ProcessingContext, signal?: AbortSignal, limits?: SandboxLimits, onProgress?: SandboxProgressCallback, onLog?: SandboxLogCallback, onEmit?: SandboxEmitCallback, streams?: SandboxInputStreams, resolveMediaRef?: (where: string, ref: unknown) => Promise<Uint8Array>, promoteMedia?: (type: "image" | "audio" | "video", bytes: Uint8Array, options?: Record<string, unknown>) => Promise<unknown>, resolveHost?: HostResolver): SandboxResult;
+/**
+ * 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 declare function buildSandbox(context?: ProcessingContext): SandboxResult;
+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, type ExposedBridgeName, type GuestModuleHost } from "./js-sandbox-worker/interpreter.js";
 /**
- * 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.
+ * The platform modules one run mounts: guest specifier → generated facade
+ * source, plus the dispatcher every facade call lands on.
+ *
+ * Structural on purpose — `runInSandbox` knows how to mount a facade and
+ * nothing about capabilities; the mount is built where a `CapabilityRun`
+ * exists (`codeact/capability-modules.ts`).
+ */
+export interface SandboxCapabilityMount {
+    readonly facades: ReadonlyMap<string, string>;
+    call(moduleKey: unknown, exportName: unknown, args: unknown): Promise<unknown>;
+}
+/**
+ * A run's wall clock, which the host can stop while the guest waits on
+ * something outside its own control — above all a permission prompt, which is
+ * bounded only by how long a person takes to answer it.
+ *
+ * The timeout exists to bound *guest execution*: a runaway loop, a program that
+ * never returns. Time a program spends parked on a host round-trip it cannot
+ * hurry is not that, and charging it to the same budget kills the program
+ * mid-wait — the answer then resolves nothing, because the sandbox that asked
+ * is already gone.
+ *
+ * `suspend()` returns the matching resume; calls nest, and the clock restarts
+ * only when the last one resumes.
  */
-export declare function wrapCode(code: string): string;
+export interface SandboxClock {
+    /** Stop the guest's budget until the returned function is called. */
+    suspend(): () => void;
+    /** Milliseconds suspended so far, including a suspension still open. */
+    suspendedMs(): number;
+}
+export declare function createSandboxClock(): SandboxClock;
 export interface RunSandboxOptions {
     /** The JavaScript code to execute. */
     code: string;
@@ -66,6 +359,123 @@ export interface RunSandboxOptions {
     timeoutMs?: number;
     /** Extra variables to inject into the sandbox (e.g. dynamic inputs). */
     globals?: Record<string, unknown>;
+    /**
+     * External cancellation. On abort, in-flight host operations are aborted,
+     * `sleep` returns immediately, and every subsequent bridge call fails fast so
+     * the guest unwinds — a program that awaits anything stops within a bridge
+     * call, and `runInSandbox` returns the cancelled result at once.
+     *
+     * A purely CPU-bound guest is the exception, and only on the in-process path.
+     * The interrupt handler QuickJS polls reads the abort flag, but on this
+     * thread only the event loop the spinning guest is blocking can set it — so
+     * the guest runs to its deadline and `runInSandbox` returns ahead of it,
+     * leaving an orphaned run to wind down on its own. Running the interpreter
+     * off-thread is what makes that case abort promptly too.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-invocation limit overrides (fetch calls, response body, output size,
+     * guest heap, stack, fetch timeout). Each is clamped to a hard ceiling, so a
+     * caller can tune a limit but not disable a protection.
+     */
+    limits?: SandboxLimits;
+    /**
+     * Sink for guest `progress(percent, message?)` calls. Values are clamped to
+     * 0–100, messages truncated, and reports rate-limited to one per
+     * {@link PROGRESS_MIN_INTERVAL_MS} (at most {@link MAX_PROGRESS_CALLS} per
+     * run). Without a callback the guest function is a no-op.
+     */
+    onProgress?: SandboxProgressCallback;
+    /**
+     * Sink for guest `console.*` calls. Each line is forwarded as it happens,
+     * with {@link MAX_CONSOLE_LOGS} as the cap and
+     * {@link MAX_CONSOLE_LOG_CHARS} as the per-line ceiling. The run's `logs`
+     * array still collects every untruncated line. Without a callback the guest
+     * console is unchanged: lines land only in `logs`.
+     */
+    onLog?: SandboxLogCallback;
+    /**
+     * Sink for guest `emit(name, value)` calls. Every value reaches it, in call
+     * order, and the guest's `emit` promise resolves only after it does — so an
+     * `await emit(...)` blocks a producer the consumer cannot keep up with. A
+     * sink that throws surfaces in the guest as a thrown error. Without a sink
+     * the values are collected into {@link RunSandboxResult.emitted} instead.
+     */
+    onEmit?: SandboxEmitCallback;
+    /**
+     * Source behind the guest `stream` global: the host answers one take at a
+     * time, with `null` meaning "any handle, arrival order" (`stream.any()`).
+     * Without it the guest still has `stream`, and every call throws
+     * {@link NO_INPUT_STREAM_MESSAGE} — a body that streams must be run by a host
+     * that can feed it.
+     *
+     * A run with this set is metered differently: time parked on a take is
+     * clock-suspended, so the timeout bounds guest execution only, and the
+     * engine's own wall-clock backstop is widened to
+     * {@link INPUT_STREAM_SUSPEND_ALLOWANCE_MS} unless the caller names an
+     * allowance. A streaming body legitimately lives as long as its upstream;
+     * cancelling the run is what ends it.
+     */
+    onTakeInput?: SandboxTakeInputCallback;
+    /**
+     * Answer to `stream.open(name)`. Read synchronously, so the guest sees a
+     * boolean. Without it — even with {@link onTakeInput} set — every handle
+     * reads closed.
+     */
+    onStreamOpen?: SandboxStreamOpenCallback;
+    /**
+     * Wall clock the host can stop while the guest waits on a round-trip it
+     * cannot hurry (a permission prompt). Time suspended is added back to
+     * {@link timeoutMs}, so the guest keeps its full execution budget across the
+     * wait. Without a clock the timeout is plain wall-clock, as before.
+     */
+    clock?: SandboxClock;
+    /**
+     * Total suspension a run may accumulate before the engine aborts it anyway.
+     * Only consulted when {@link clock} is set. Defaults to
+     * {@link DEFAULT_SUSPEND_ALLOWANCE_MS}.
+     */
+    suspendAllowanceMs?: number;
+    /**
+     * Sandbox modules this run may import, already resolved by the catalog.
+     * Without it every guest `import` is denied by name. With it, these modules
+     * and their intra-pack siblings are the only importable ones — see
+     * {@link createGuestModuleHost}.
+     */
+    modules?: SandboxModuleResolution;
+    /**
+     * NodeTool's own modules — `@nodetool-ai/sandbox-nodetool/<namespace>` — and
+     * the dispatcher behind them. Host-declared: they never pass through the
+     * consent allowlist {@link modules} is resolved against, because consent
+     * gates third-party code and these are the platform's own surface, mounted
+     * only for a session whose host built a capability run.
+     */
+    capabilities?: SandboxCapabilityMount;
+    /**
+     * Worker pool for host WASM calls. Defaults to the process-wide pool of
+     * four, which is what production wants; a test passes its own to observe
+     * the pool without sharing it with every other test in the file.
+     */
+    wasmPool?: WasmWorkerPool;
+    /**
+     * Load a media ref when this run has no ProcessingContext. Chat uses this so
+     * media transforms can resolve generated results host-side and the guest
+     * only sees handles.
+     */
+    resolveMediaRef?: (where: string, ref: unknown) => Promise<Uint8Array>;
+    /**
+     * Save host-side media bytes as an asset. Backs each transform namespace's
+     * `toAsset` and `nodetool.media.toImage/toAudio/toVideo` in chat.
+     */
+    promoteMedia?: (type: "image" | "audio" | "video", bytes: Uint8Array, options?: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * How the fetch bridge turns a hostname into addresses for the resolved
+     * SSRF check. Defaults to `node:dns`; a test passes a fixed table so no
+     * lookup leaves the process.
+     */
+    resolveHost?: HostResolver;
+    /** Pure guest construction only. Host bridges and host-backed module mounts are refused. */
+    hermetic?: boolean;
 }
 export interface RunSandboxResult {
     success: boolean;
@@ -73,7 +483,29 @@ export interface RunSandboxResult {
     error?: string;
     stack?: string;
     logs?: string[];
+    /**
+     * Final values the guest recorded with `output(name, value)`, marshaled the
+     * way `result` is. Absent when the guest called `output` never, and dropped
+     * on a failed run — a run that died has no answer to post.
+     */
+    outputs?: Record<string, unknown>;
+    /**
+     * Values the guest passed to `emit(name, value)`, in call order. Present only
+     * when the caller passed no {@link RunSandboxOptions.onEmit} sink — with one,
+     * the values went there instead.
+     */
+    emitted?: SandboxEmittedValue[];
 }
+/**
+ * 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 declare const GUEST_HELPER_NAMES: readonly ["toBase64", "fromBase64", "toHex", "fromHex", "parallelMap", "createCanvas", "stream"];
+export type GuestHelperName = (typeof GUEST_HELPER_NAMES)[number];
+/** Names that should never be reassigned via `globals` — core sandbox APIs. */
+export declare const RESERVED_SANDBOX_NAMES: ReadonlySet<string>;
 /**
  * Execute JavaScript code inside a QuickJS WebAssembly sandbox.
  *
@@ -81,4 +513,14 @@ export interface RunSandboxResult {
  * handler / memory limiter, so runaway user code can't exhaust host resources.
  */
 export declare function runInSandbox(options: RunSandboxOptions): Promise<RunSandboxResult>;
+/**
+ * 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.d.ts.map

package/dist/js-sandbox.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"js-sandbox.d.ts","sourceRoot":"","sources":["../src/js-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAcH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAM9D,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,eAAO,MAAM,eAAe,SAAU,CAAC;AACvC,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAChD,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAmB,CAAC;AACnD,gEAAgE;AAChE,eAAO,MAAM,iBAAiB,QAAa,CAAC;AAoF5C,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG1D;AAgCD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CA+CxD;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAiBhD;AAOD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,MAAM,MAAM,EAAE,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAmNvE;AAMD;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,OAAO,CAAC,EAAE,iBAAiB,CAAC;IAC5B,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAuDD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,gBAAgB,CAAC,CAgL3B"}
+{"version":3,"file":"js-sandbox.d.ts","sourceRoot":"","sources":["../src/js-sandbox.ts"],"names":[],"mappings":"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"}