@johnhenry/andbox 0.2.0 → 0.3.1

package/src/index.d.ts

@@ -295,6 +295,141 @@ export interface SandboxNetworkOptions {
   credentials?: RequestCredentials;
 }
 
+// ── bridges (createSandbox({ bridges }), andbox#46) ──
+
+/** Per-sandbox limits of one bridge. 0 = unlimited. */
+export interface BridgeLimits {
+  /** Live handles at a time. Default 32 (chromeAI: 8). */
+  maxHandles?: number;
+  /** Open streams at a time. Default 8 (chromeAI: 4). */
+  maxStreams?: number;
+  /** Approximate size of one result or stream chunk (strings as UTF-8, binary by byteLength). Default 0. */
+  maxResultBytes?: number;
+  /** Wall-clock time for one call; for a stream method, until the stream ends. Default 0. */
+  timeoutMs?: number;
+}
+
+/** Defaults for {@link BridgeLimits}. */
+export declare const DEFAULT_BRIDGE_LIMITS: Readonly<Required<BridgeLimits>>;
+
+/** An opaque reference to a host object, from `ctx.handle()`. Return it (or put it in a result). */
+export interface BridgeHandleRef<T = unknown> {
+  readonly type: string;
+  readonly target: T;
+}
+
+/** What every bridge method receives as its first argument. */
+export interface BridgeContext<State = any, Target = any> {
+  /** The bridge's name (its global in the sandbox). */
+  bridge: string;
+  /** `'chat.create'` for an api method, `'Session.ask'` for a handle method. */
+  method: string;
+  /**
+   * Aborts when the sandbox's AbortSignal for this call fires, the call times
+   * out (`limits.timeoutMs`), its handle is destroyed, the stream is
+   * cancelled, or the sandbox's Worker/frame is terminated. Pass it on.
+   */
+  signal: AbortSignal;
+  /** Per-sandbox state from `createState()` (lives as long as the sandbox, across restarts). */
+  state: State;
+  /** Handle methods: the host object the sandbox's handle refers to. */
+  target: Target;
+  /** Wrap a host object so the sandbox gets a handle to it (type: a key of `handles`). */
+  handle<T>(type: string, target: T): BridgeHandleRef<T>;
+}
+
+/**
+ * A bridge method. Arguments arrive by structured clone, with sandbox
+ * functions replaced by async proxies (reverse calls into the sandbox),
+ * AbortSignals by `ctx.signal`, and handles by their host objects.
+ */
+export type BridgeMethodFn<State = any, Target = any> = (ctx: BridgeContext<State, Target>, ...args: any[]) => unknown;
+
+/** The activation a method needs: `true`/`'transient'` (a gesture in the last few seconds) or `'sticky'` (any gesture since load). */
+export type BridgeActivation = boolean | 'transient' | 'sticky';
+
+export interface BridgeMethodSpec<State = any, Target = any> {
+  call: BridgeMethodFn<State, Target>;
+  /** Returns a ReadableStream / (async) iterable; the sandbox gets a ReadableStream at once. */
+  stream?: boolean;
+  /** Returns a handle: `limits.maxHandles` is checked before the method runs. */
+  handle?: boolean;
+  /** Needs page user activation; a function decides per call (e.g. only when a download is needed). */
+  requiresUserActivation?: BridgeActivation | ((ctx: BridgeContext<State, Target>, ...args: any[]) => BridgeActivation | Promise<BridgeActivation>);
+}
+
+export type BridgeMethod<State = any, Target = any> = BridgeMethodFn<State, Target> | BridgeMethodSpec<State, Target>;
+
+/** A tree of namespaces and methods: `{ chat: { create, list } }` becomes `svc.chat.create()`. */
+export interface BridgeApi<State = any> {
+  [name: string]: BridgeMethod<State> | BridgeApi<State>;
+}
+
+/** A host object type the sandbox holds handles to. */
+export interface BridgeHandleType<State = any, Target = any> {
+  /** Methods callable on the sandbox's handle; `ctx.target` is the host object. */
+  methods?: Record<string, BridgeMethod<State, Target>>;
+  /** Properties copied to the sandbox (primitives and arrays of primitives) with the handle and after every call. */
+  props?: string[];
+  /** Release the host object: on handle.destroy(), and for every live handle when the sandbox is disposed, restarted or killed. */
+  destroy?: (target: Target) => void | Promise<void>;
+}
+
+/** What `onRequest` sees for every bridge method call (not for destroy/cancel/abort). */
+export interface BridgeRequest {
+  bridge: string;
+  /** `'chat.create'` or `'Session.ask'`; the gate name is `${bridge}.${method}`. */
+  method: string;
+  /** Decoded arguments (sandbox functions are proxies; signals are the call's signal). */
+  args: unknown[];
+  handle: { id: string; type: string } | null;
+  /** The activation the method needs for this call, or false. */
+  requiresUserActivation: false | 'transient' | 'sticky';
+  /** The page's `navigator.userActivation` now; null where the platform has none (Node). */
+  userActivation: { isActive: boolean; hasBeenActive: boolean } | null;
+  /** Aborts when the call does (the sandbox gave up, timed out or was terminated): close your consent UI. */
+  signal: AbortSignal;
+}
+
+export interface BridgeDefinition<State = any> {
+  /** Methods and namespaces of the sandbox global. */
+  api?: BridgeApi<State>;
+  /** Host object types, by name. A handle type cannot share a name with an api member. */
+  handles?: Record<string, BridgeHandleType<State>>;
+  limits?: BridgeLimits;
+  /**
+   * Consent hook, asked on the host before every method call. Only `true`
+   * (or a promise of it) allows; anything else, or a throw, rejects the call
+   * in the sandbox with `NotAllowedError`. It may wait for the user.
+   */
+  onRequest?: (request: BridgeRequest) => boolean | Promise<boolean>;
+  /** Per-sandbox state (`ctx.state`), created once per sandbox. */
+  createState?: () => State;
+  /** Extra fields for `sandbox.stats().bridges[name]`. */
+  stats?: (state: State) => Record<string, unknown>;
+  /**
+   * Sandbox-side adapter: a self-contained function (stringified; no outside
+   * references) called in the sandbox with the generated global and
+   * `clientOptions`; returns the global to install.
+   */
+  client?: ((api: any, options: any) => any) | string;
+  /** JSON passed to `client` in the sandbox. */
+  clientOptions?: unknown;
+  /** Extra sandbox globals aliasing paths of the api: `{ LanguageModel: 'languageModel' }`. */
+  globals?: Record<string, string>;
+}
+
+/** Check a bridge definition (throws a TypeError) and return it unchanged. */
+export declare function defineBridge<State = any>(definition: BridgeDefinition<State>): BridgeDefinition<State>;
+
+/** `sandbox.stats().bridges[name]`. */
+export interface BridgeStats {
+  handles: number;
+  streams: number;
+  pendingCalls: number;
+  [extra: string]: unknown;
+}
+
 // ── stdio ──
 
 /** An async iterable stdio stream with push/end controls. */
@@ -325,9 +460,11 @@ export declare function createStdio(): StdioStream;
  * @param options.networkFetch  Install the host-backed global `fetch` shim
  *   (what `createSandbox({ network })` uses). It calls the host's `fetch`
  *   capability. Default false: `fetch` is removed like the other network globals.
+ * @param options.bridges  Include the bridge client (`createSandbox({ bridges })`);
+ *   the globals are built from the manifests sent with `configure`. Default false.
  * @returns The complete Worker script source code as a string.
  */
-export declare function makeWorkerSource(options?: { networkFetch?: boolean }): string;
+export declare function makeWorkerSource(options?: { networkFetch?: boolean; bridges?: boolean }): string;
 
 // ── service-worker-source ──
 
@@ -380,8 +517,18 @@ export interface EvaluateOptions {
   timeoutMs?: number;
   /** AbortSignal to cancel the evaluation. */
   signal?: AbortSignal;
-  /** Console output handler for this evaluation (overrides sandbox-level handler). */
-  onConsole?: (level: string, ...args: string[]) => void;
+  /**
+   * Console output handler for this evaluation: it gets this call's console
+   * output only, while the call is pending (andbox#41). Output from a call
+   * without one, or after the call settled, goes to the sandbox-level handler.
+   */
+  onConsole?: (this: ConsoleContext, level: string, ...args: string[]) => void;
+  /**
+   * A name for this call's console output: every console handler (this call's
+   * or the sandbox-level one, for output after the call settled) is called
+   * with `this.consoleId` set to it. Attribution, not authentication.
+   */
+  consoleId?: string | number;
   /** `mode: 'wasm'` only: fuel for this call (overrides the sandbox option). */
   fuel?: number;
   /** `mode: 'wasm'` only: JS heap cap in bytes for this call. */
@@ -403,6 +550,25 @@ export interface CapabilityContext {
   name: string;
 }
 
+/**
+ * `this` inside an `onConsole` handler (use a `function`, not an arrow):
+ * `consoleId` is the `consoleId` option of the `evaluate()` call whose code
+ * logged, or `undefined` (none given, or thread stdio).
+ */
+export interface ConsoleContext {
+  readonly consoleId: string | number | undefined;
+}
+
+/**
+ * An error from a failed `evaluate()`. `sandboxStack` is the stack as the
+ * sandbox saw it (the evaluated code's frames, lines and `//# sourceURL=`
+ * names); `stack` is the host's own.
+ */
+export interface SandboxEvaluationError extends Error {
+  code?: string;
+  sandboxStack?: string;
+}
+
 /** Options for createSandbox(). */
 export interface SandboxOptions {
   /** Import map for module resolution inside the sandbox. */
@@ -415,8 +581,11 @@ export interface SandboxOptions {
   baseURL?: string;
   /** Rate limiting policy for capability calls. */
   policy?: GatePolicy;
-  /** Console output handler. Called when sandboxed code uses console.log/warn/error/etc. */
-  onConsole?: (level: string, ...args: string[]) => void;
+  /**
+   * Console output handler. Called when sandboxed code uses console.log/warn/error/etc.
+   * and no per-call `onConsole` is running for it; `this.consoleId` names the call.
+   */
+  onConsole?: (this: ConsoleContext, level: string, ...args: string[]) => void;
   /**
    * Worker mode selection. Omitted/`'worker'` uses a Web Worker, or
    * `node:worker_threads` automatically when run under Node with no global
@@ -505,6 +674,17 @@ export interface SandboxOptions {
    * capability named `fetch`.
    */
   network?: SandboxNetworkOptions;
+  /**
+   * `worker`, `node-worker` and `iframe` modes (throws in the others): one
+   * sandbox global per entry that proxies a host API (andbox#46). Host
+   * objects never cross: the sandbox holds opaque handles, gets structured
+   * clones, pulls streams chunk by chunk, and its functions run in the
+   * sandbox when the host calls them. Every method call goes through the
+   * capability gate as `${bridge}.${method}` (so `policy` limits it) and
+   * through the bridge's `onRequest`; every handle is destroyed when the
+   * sandbox is disposed, restarted or killed. See `@johnhenry/andbox/bridges/chrome-ai`.
+   */
+  bridges?: Record<string, BridgeDefinition>;
 }
 
 /** Options for the built-in Node worker_threads mode (`nodeWorker`). */
@@ -557,6 +737,8 @@ export interface SandboxStats {
   pendingEvaluations: number;
   virtualModules: string[];
   gate: GateStatsResult;
+  /** With `bridges`: live handles/streams/calls per bridge, plus the bridge's own `stats()`. */
+  bridges?: Record<string, BridgeStats>;
   /** `mode: 'wasm'` only: interrupt polls used by the most recent evaluate(). */
   fuelUsed?: number;
   /** `mode: 'wasm'` only: peak sampled JS heap bytes seen so far. */

package/src/index.mjs

@@ -10,6 +10,7 @@ export { createVirtualModuleRegistry } from './virtual-module-registry.mjs';
 export { gateCapabilities } from './capability-gate.mjs';
 export { createStdio } from './stdio.mjs';
 export { createNetworkFetch } from './network-policy.mjs';
+export { defineBridge, DEFAULT_BRIDGE_LIMITS } from './bridge-host.mjs';
 export { makeDeferred, makeAbortError, makeTimeoutError } from './deferred.mjs';
 export { DEFAULT_TIMEOUT_MS, DEFAULT_LIMITS, DEFAULT_CAPABILITY_LIMITS } from './constants.mjs';
 export { makeWorkerSource } from './worker-source.mjs';

package/src/sandbox.mjs

@@ -19,6 +19,7 @@ import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
 import { isNodeRuntime, createNodeWorkerFactory } from './node-worker.mjs';
 import { normalizeIframeOptions, createIframeFactory, makeIframeRuntimeSource } from './iframe-host.mjs';
 import { createFetchCapability, validateNetworkOptions } from './network-policy.mjs';
+import { normalizeBridges, createBridgeHost } from './bridge-host.mjs';
 
 const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
 
@@ -314,11 +315,14 @@ async function createServiceWorkerSandbox(options = {}) {
  * @property {boolean} [dangerouslyAllowSameOrigin] - mode: 'iframe': permit 'allow-same-origin' (removes the origin boundary)
  * @property {(iframe: HTMLIFrameElement) => void} [onFrame] - mode: 'iframe': called with every new frame before it is attached
  * @property {{ allowedHosts: string[] | '*' | ((url: URL) => boolean | Promise<boolean>), fetch?: Function, credentials?: RequestCredentials }} [network] - worker, node-worker and iframe modes: install a global `fetch` in the sandbox that goes through the host (andbox#39); `allowedHosts` is required (andbox#43)
+ * @property {Record<string, object>} [bridges] - worker, node-worker and iframe modes: one global per entry that proxies a host API (handles, streams, abort, callbacks, consent, budgets; andbox#46)
  */
 
 const SUPPORTED_MODES = ['worker', 'node-worker', 'wasm', 'iframe', 'inline', 'data-uri', 'service-worker'];
 /** Modes whose runtime can install the host-backed `fetch` (`network`, andbox#39). */
 const NETWORK_MODES = ['worker', 'node-worker', 'iframe'];
+/** Modes whose runtime can install bridges (`bridges`, andbox#46). */
+const BRIDGE_MODES = NETWORK_MODES;
 
 /**
  * Create a new sandboxed runtime.
@@ -359,6 +363,17 @@ export function createSandbox(options = {}) {
   }
   // Refuse a bad `network` (no allowedHosts, andbox#43) before starting anything.
   if (options.network !== undefined) validateNetworkOptions(options.network);
+  if (options.bridges !== undefined && !BRIDGE_MODES.includes(mode)) {
+    throw new Error(
+      `The bridges option applies to ${BRIDGE_MODES.map((m) => `mode: '${m}'`).join(', ')}, not mode: '${mode}'.` +
+      (mode === 'wasm'
+        ? ' The QuickJS guest has no ReadableStream, AbortSignal or EventTarget and only JSON crosses its boundary; ' +
+          'expose capabilities and call them with host.call().'
+        : '')
+    );
+  }
+  // Refuse a bad bridge definition before starting anything.
+  if (options.bridges !== undefined) normalizeBridges(options.bridges);
   if (mode === 'inline') return createInlineSandbox(options);
   if (mode === 'data-uri') return createDataUriSandbox(options);
   if (mode === 'service-worker') return createServiceWorkerSandbox(options);
@@ -451,6 +466,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     unref = false,
     allowedImportHosts,
     network,
+    bridges,
   } = options;
 
   // undefined = unset: remote imports allowed. An array (even empty) restricts.
@@ -517,11 +533,47 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
   }
   const networkFetch = network !== undefined;
 
-  // Gate capabilities with rate limits
-  const { lookup: lookupCapability, stats: gateStats } = gateCapabilities(gatedCapabilities, policy);
+  // `bridges` (andbox#46): every bridge method is also an entry in the gate,
+  // so `policy` limits and counts it, but `host.call()` cannot reach it.
+  const bridgeHost = bridges !== undefined ? createBridgeHost(normalizeBridges(bridges)) : null;
+  if (bridgeHost) {
+    for (const name of Object.keys(bridgeHost.gateEntries)) {
+      if (Object.prototype.hasOwnProperty.call(gatedCapabilities, name)) {
+        throw new Error(`The capability '${name}' has the same name as a bridge method; rename the capability.`);
+      }
+    }
+    gatedCapabilities = { ...gatedCapabilities, ...bridgeHost.gateEntries };
+  }
 
-  // Console handler — mutable so evaluate() can swap per-call
-  let activeConsoleHandler = onConsole || null;
+  // Gate capabilities with rate limits
+  const { lookup: gateLookup, stats: gateStats } = gateCapabilities(gatedCapabilities, policy);
+  bridgeHost?.useGate(gateLookup);
+  const lookupCapability = bridgeHost
+    ? (name) => (bridgeHost.isGateName(name) ? undefined : gateLookup(name))
+    : gateLookup;
+
+  // Console routing (andbox#41). Every console message names the evaluate()
+  // call it came from (its `evalId`), so it goes to that call's own
+  // `onConsole` while the call is pending, never to whichever call started
+  // last; otherwise (no per-call handler, or output after the call settled)
+  // to the sandbox-level one. Handlers get `this.consoleId`: the call's
+  // `consoleId` option. Thread stdio (node-worker `captureStdio`) carries no
+  // call, so it goes to the newest pending call's handler, as before.
+  function deliverConsole(evalId, carriedConsoleId, level, args) {
+    const entry = evalId == null ? undefined : pending.get(evalId);
+    const handler = entry?.onConsole ?? onConsole;
+    if (!handler) return;
+    // A pending call's id is the host's own copy; output after the call
+    // settled has only the id the runtime carried with it.
+    const consoleId = entry ? entry.consoleId : carriedConsoleId;
+    handler.call(Object.freeze({ consoleId }), level, ...args);
+  }
+  function deliverStdio(stream, text) {
+    let entry;
+    for (const e of pending.values()) if (e.onConsole) entry = e;
+    const handler = entry?.onConsole ?? onConsole;
+    handler?.call(Object.freeze({ consoleId: entry?.consoleId }), stream, text);
+  }
 
   // Track virtual modules for re-creation on restart
   const virtualModules = new Map();
@@ -530,6 +582,8 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
   let workerBlobURL = null;
   // Lifetime of the current Worker; aborted when it is terminated.
   let workerAbort = null;
+  // The current Worker's bridge session: its handles, streams and callbacks.
+  let bridgeSession = null;
 
   // `unref`: the thread only keeps the host process alive while work is in
   // flight (startup, evaluate, defineModule); idle, it lets the process exit.
@@ -554,21 +608,42 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     workerAbort = new AbortController();
     const source = isWasm
       ? makeWasmWorkerSource()
-      : isIframe ? makeIframeRuntimeSource({ networkFetch }) : makeWorkerSource({ networkFetch });
+      : isIframe
+        ? makeIframeRuntimeSource({ networkFetch, bridges: !!bridgeHost })
+        : makeWorkerSource({ networkFetch, bridges: !!bridgeHost });
     if (workerFactory) {
       worker = workerFactory(source);
+      openBridgeSession();
       attachWorkerHandlers();
-      worker.onstdio = (stream, text) => activeConsoleHandler?.(stream, text);
+      worker.onstdio = deliverStdio;
       return;
     }
     const blob = new Blob([source], { type: 'application/javascript' });
     workerBlobURL = URL.createObjectURL(blob);
     worker = new Worker(workerBlobURL, { type: 'classic' });
+    openBridgeSession();
     attachWorkerHandlers();
   }
 
+  /** Bind a bridge session to the Worker just created (and only to it). */
+  function openBridgeSession() {
+    if (!bridgeHost) return;
+    const target = worker;
+    const signal = workerAbort.signal;
+    bridgeSession = bridgeHost.openSession((message) => {
+      // Throws DataCloneError for an uncloneable value; the session reports it.
+      if (worker !== target || signal.aborted) return;
+      target.postMessage(message);
+    });
+  }
+
   function attachWorkerHandlers() {
+    const session = bridgeSession;
     worker.onmessage = ({ data: msg }) => {
+      if (session && typeof msg?.type === 'string' && msg.type.startsWith('bridge')) {
+        session.receive(msg);
+        return;
+      }
       switch (msg.type) {
         case 'configured':
         case 'moduleDefined':
@@ -591,6 +666,10 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
               const err = new Error(msg.error?.message || 'Evaluation failed');
               err.name = msg.error?.name || 'Error';
               if (msg.error?.code) err.code = msg.error.code;
+              // The stack as the sandbox saw it (andbox#41): its frames name
+              // the evaluated code (`//# sourceURL=` names included) and its
+              // line numbers, which the host-side `err.stack` cannot.
+              if (typeof msg.error?.stack === 'string') err.sandboxStack = msg.error.stack;
               entry.reject(err);
             }
           }
@@ -603,9 +682,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
         }
 
         case 'console': {
-          if (activeConsoleHandler) {
-            activeConsoleHandler(msg.level, ...msg.args);
-          }
+          deliverConsole(msg.evalId, msg.consoleId, msg.level, Array.isArray(msg.args) ? msg.args : []);
           break;
         }
       }
@@ -631,7 +708,9 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     const handler = ({ data }) => {
       if (data.type === 'configured') {
         worker.removeEventListener('message', handler);
-        if (data.error) {
+        if (data.error && !wasmConfig) {
+          reject(new Error(data.error.message));
+        } else if (data.error) {
           const err = new Error(`Failed to load the WASM engine: ${data.error.message}`);
           err.code = 'ERR_ANDBOX_ENGINE';
           reject(err);
@@ -647,6 +726,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
       baseURL,
       allowedImportHosts: importHosts,
       virtualModules: Object.fromEntries(virtualModules),
+      ...(bridgeHost ? { bridges: bridgeHost.manifests } : {}),
       ...(wasmConfig ? { wasm: { ...wasmConfig.engine, memoryBytes: wasmConfig.limits.memoryBytes } } : {}),
     });
     try {
@@ -697,6 +777,12 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
       workerAbort.abort(new Error('Sandbox worker terminated'));
       workerAbort = null;
     }
+    if (bridgeSession) {
+      // Destroy every host object the runtime held, cancel its streams and
+      // abort its in-flight bridge calls (andbox#46).
+      bridgeSession.close();
+      bridgeSession = null;
+    }
     if (worker) {
       worker.terminate();
       worker = null;
@@ -725,7 +811,11 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
    * Evaluate JavaScript code in the sandbox.
    *
    * @param {string} code - JavaScript code to execute (wrapped in async IIFE).
-   * @param {{ timeoutMs?: number, signal?: AbortSignal, onConsole?: (level: string, ...args: string[]) => void }} [opts]
+   * @param {{ timeoutMs?: number, signal?: AbortSignal, onConsole?: (level: string, ...args: string[]) => void, consoleId?: string | number }} [opts]
+   *   `onConsole` gets this call's console output only (andbox#41); every
+   *   console handler is called with `this.consoleId` set to the `consoleId`
+   *   of the call that logged, including output that arrives after the call
+   *   settled (which goes to the sandbox-level `onConsole`).
    * @returns {Promise<any>} The return value of the code.
    */
   async function evaluate(code, opts = {}) {
@@ -733,6 +823,10 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     if (wasmConfig) {
       for (const k of ['fuel', 'memoryBytes', 'stackBytes', 'deadlineMs']) checkLimit(k, opts[k]);
     }
+    const { consoleId } = opts;
+    if (consoleId !== undefined && typeof consoleId !== 'string' && !(typeof consoleId === 'number' && Number.isFinite(consoleId))) {
+      throw new TypeError('evaluate(): consoleId must be a string or a finite number');
+    }
     if (!worker || worker.dead) await restartWorker();
     beginOp();
 
@@ -747,12 +841,6 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs;
     const { promise, resolve, reject } = makeDeferred();
 
-    // Swap console handler for this evaluation if provided
-    const prevConsoleHandler = activeConsoleHandler;
-    if (opts.onConsole) {
-      activeConsoleHandler = opts.onConsole;
-    }
-
     // mode: 'wasm' -- limits travel with the call. The in-worker deadline
     // (default: this call's timeoutMs) ends a busy loop gracefully; the
     // host-side timer below becomes a hard-kill backstop a little later.
@@ -798,14 +886,19 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
       }, { once: true });
     }
 
-    pending.set(id, { resolve, reject, timer, nonce });
-    worker.postMessage({ type: 'evaluate', id, nonce, code, ...(wasmLimits ? { limits: wasmLimits } : {}) });
-
-    // Restore console handler when evaluation completes
-    return promise.finally(() => {
-      if (opts.onConsole) activeConsoleHandler = prevConsoleHandler;
-      endOp();
+    pending.set(id, { resolve, reject, timer, nonce, onConsole: opts.onConsole || null, consoleId });
+    worker.postMessage({
+      type: 'evaluate',
+      id,
+      nonce,
+      code,
+      // The runtime carries it on this call's console messages, so output
+      // after the call settled is still attributed (andbox#41).
+      ...(consoleId !== undefined ? { consoleId } : {}),
+      ...(wasmLimits ? { limits: wasmLimits } : {}),
     });
+
+    return promise.finally(endOp);
   }
 
   /**
@@ -860,6 +953,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
       pendingEvaluations: pending.size,
       virtualModules: [...virtualModules.keys()],
       gate: gateStats(),
+      ...(bridgeHost ? { bridges: bridgeHost.stats() } : {}),
       ...(wasmConfig ? { fuelUsed: wasmStats.fuelUsed, peakMemoryBytes: wasmStats.peakMemoryBytes, totalFuelUsed: wasmStats.totalFuelUsed } : {}),
     };
   }

package/src/wasm-worker-source.mjs

@@ -319,7 +319,7 @@ function wasmWorkerMain() {
           if (done) return;
           let args;
           try { args = JSON.parse(ctx.getString(argsH)); } catch { args = []; }
-          self.postMessage({ type: 'console', evalId: msg.id, level: ctx.getString(levelH), args });
+          self.postMessage({ type: 'console', evalId: msg.id, consoleId: msg.consoleId, level: ctx.getString(levelH), args });
         }));
 
         const nativeCall = own(ctx.newFunction('call', (nameH, argsH) => {

package/src/worker-source.mjs

@@ -7,6 +7,8 @@
  * host capabilities.
  */
 
+import { installBridges } from './bridge-client.mjs';
+
 /**
  * The in-sandbox half of `createSandbox({ network })` (andbox#39): installs a
  * global `fetch` that serializes the request, sends it to the host's `fetch`
@@ -134,14 +136,17 @@ function installNetworkFetch(callHost, getBaseURL) {
  * - `capabilityCall`: RPC request to host capability
  * - `console`: Forwarded console output
  *
- * @param {{ networkFetch?: boolean }} [options]
+ * @param {{ networkFetch?: boolean, bridges?: boolean }} [options]
  *   `networkFetch` (default false) installs a global `fetch` that forwards
  *   every request to the host's `fetch` capability (`createSandbox({ network })`,
  *   andbox#39) instead of leaving `fetch` locked.
+ *   `bridges` (default false) includes the bridge client
+ *   (`createSandbox({ bridges })`, andbox#46); the globals themselves are
+ *   built from the manifests the host sends with `configure`.
  * @returns {string} The Worker script source code.
  */
-export function makeWorkerSource({ networkFetch = false } = {}) {
-  return makeRuntimeSource({ lockdown: true, networkFetch });
+export function makeWorkerSource({ networkFetch = false, bridges = false } = {}) {
+  return makeRuntimeSource({ lockdown: true, networkFetch, bridges });
 }
 
 /**
@@ -162,7 +167,7 @@ export function makeWorkerSource({ networkFetch = false } = {}) {
  *   the lockdown list stays removed.
  * @returns {string}
  */
-export function makeRuntimeSource({ lockdown = true, networkFetch = false } = {}) {
+export function makeRuntimeSource({ lockdown = true, networkFetch = false, bridges = false } = {}) {
   const lockedGlobals = lockdown
     ? `[
   ${networkFetch ? '' : "'fetch', "}'XMLHttpRequest', 'WebSocket', 'WebSocketStream', 'WebTransport', 'EventSource',
@@ -204,6 +209,9 @@ ${networkFetch ? `// ── Host-backed fetch (andbox#39) ──
 // Replaces the global fetch: every request goes to the host's
 // gated \`fetch\` capability, which decides policy and credentials.
 (${installNetworkFetch.toString()})((name, args) => callCapability(name, args), () => baseURL);
+` : ''}${bridges ? `// ── Bridges (andbox#46) ──
+// Globals that proxy host APIs; installed from the host's manifests on configure.
+const bridgeClient = (${installBridges.toString()})(post);
 ` : ''}// Names shadowed lexically for evaluated code as well (covers environments
 // where a global could not be deleted).
 const SHADOWED = ${shadowed};
@@ -311,7 +319,7 @@ const host = {
 
 // ── Console Forwarding ──
 const originalConsole = { ...console };
-function makeForwardingConsole(evalId) {
+function makeForwardingConsole(evalId, consoleId) {
   return new Proxy(console, {
     get(target, prop) {
       if (['log', 'warn', 'error', 'info', 'debug'].includes(prop)) {
@@ -320,7 +328,7 @@ function makeForwardingConsole(evalId) {
             try { return typeof a === 'object' ? JSON.stringify(a) : String(a); }
             catch { return String(a); }
           });
-          post({ type: 'console', evalId, level: prop, args: serialized });
+          post({ type: 'console', evalId, consoleId, level: prop, args: serialized });
         };
       }
       return target[prop];
@@ -340,7 +348,15 @@ scope.onmessage = async ({ data: msg }) => {
           virtualModules.set(name, src);
         }
       }
-      post({ type: 'configured' });
+${bridges ? `      if (msg.bridges) {
+        try {
+          bridgeClient.install(msg.bridges);
+        } catch (e) {
+          post({ type: 'configured', error: { message: 'Failed to install bridges: ' + (e && e.message ? e.message : e) } });
+          break;
+        }
+      }
+` : ''}      post({ type: 'configured' });
       break;
     }
 
@@ -351,7 +367,7 @@ scope.onmessage = async ({ data: msg }) => {
     }
 
     case 'evaluate': {
-      const fwdConsole = makeForwardingConsole(msg.id);
+      const fwdConsole = makeForwardingConsole(msg.id, msg.consoleId);
       try {
         // Wrap in async function for top-level await. The newlines before and
         // after the user code matter: without the trailing one, code ending in
@@ -388,7 +404,12 @@ scope.onmessage = async ({ data: msg }) => {
       break;
     }
 
-    case 'dispose': {
+${bridges ? `    default: {
+      if (typeof msg.type === 'string' && msg.type.startsWith('bridge')) bridgeClient.receive(msg);
+      break;
+    }
+
+` : ''}    case 'dispose': {
       // Reject all pending RPCs
       for (const [id, { reject }] of pendingRpc) {
         reject(new Error('Sandbox disposed'));