@johnhenry/andbox 0.2.0 → 0.3.0

package/src/bridges/chrome-ai.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `@johnhenry/andbox/bridges/chrome-ai`: Chrome's built-in AI APIs, bridged
+ * into a sandbox (andbox#46). See the README section "Chrome AI bridge".
+ */
+import type { BridgeDefinition, BridgeLimits, BridgeRequest } from '../index.js';
+
+/** The API keys `chromeAI({ apis })` accepts; each is a namespace of the sandbox global. */
+export type ChromeAIApi =
+  | 'languageModel'
+  | 'summarizer'
+  | 'writer'
+  | 'rewriter'
+  | 'translator'
+  | 'languageDetector'
+  | 'proofreader';
+
+export declare const CHROME_AI_APIS: readonly ChromeAIApi[];
+
+export interface ChromeAIBudgets {
+  /**
+   * Model input tokens per sandbox lifetime, measured with
+   * `measureContextUsage()` (or `measureInputUsage()`) before each
+   * prompt/append/summarize/write/rewrite/translate/detect/proofread call,
+   * plus the tokens `initialPrompts` use at create(). Output tokens are not
+   * counted. A call over budget rejects with QuotaExceededError before it
+   * reaches the model. 0 = unlimited.
+   */
+  maxInputTokens?: number;
+  /** Model input tokens of a single call. 0 = unlimited. */
+  maxInputTokensPerCall?: number;
+}
+
+export interface ChromeAIOptions {
+  /** Which APIs to expose (default: all). Missing ones on the host report 'unavailable'. */
+  apis?: ChromeAIApi[];
+  /**
+   * Consent hook for every model call (`method` is e.g. 'languageModel.create'
+   * or 'LanguageModel.prompt'). Only `true` allows. When
+   * `requiresUserActivation` is 'sticky' (the model must be downloaded),
+   * resolve from a click handler so the page has activation.
+   */
+  onRequest?: (request: BridgeRequest) => boolean | Promise<boolean>;
+  budgets?: ChromeAIBudgets;
+  /** Bridge limits. Default { maxHandles: 8, maxStreams: 4 }. */
+  limits?: BridgeLimits;
+  /** Also install LanguageModel, Summarizer, ... in the sandbox as aliases of `ai.languageModel`, ... */
+  globals?: boolean;
+  /** Where the platform constructors are looked up (default globalThis). For tests and polyfills. */
+  scope?: Record<string, unknown>;
+}
+
+/** The Chrome built-in AI bridge: `createSandbox({ bridges: { ai: chromeAI() } })`. */
+export declare function chromeAI(options?: ChromeAIOptions): BridgeDefinition<{ inputTokens: number }>;

package/src/bridges/chrome-ai.mjs

@@ -0,0 +1,424 @@
+/**
+ * Chrome built-in AI bridge (andbox#46).
+ *
+ *   import { chromeAI } from '@johnhenry/andbox/bridges/chrome-ai';
+ *   const sandbox = await createSandbox({ bridges: { ai: chromeAI({ onRequest }) } });
+ *   await sandbox.evaluate(`
+ *     const session = await ai.languageModel.create();
+ *     return session.prompt('Hello');
+ *   `);
+ *
+ * Chrome exposes its built-in AI APIs (LanguageModel, Summarizer, Writer,
+ * Rewriter, Translator, LanguageDetector, Proofreader) to Window contexts only:
+ * not to Workers, and not to a sandboxed opaque-origin iframe (permissions
+ * policy features default to 'self'). So sandboxed code reaches them only
+ * through the page, which is what this bridge does: the page owns every model
+ * session; the sandbox holds handles to them.
+ *
+ * Zero dependencies. The sandbox-side surface mirrors the platform's names
+ * and shapes (see README "Chrome AI bridge" for the differences).
+ */
+
+import { defineBridge } from '../bridge-host.mjs';
+
+/**
+ * The APIs this bridge knows. `global` is the platform constructor on the
+ * host; `methods` are instance methods (`input`: argument 0 is the model
+ * input, counted by token budgets; `opts`: index of the options argument,
+ * which gets the call's AbortSignal).
+ */
+const API_TABLE = {
+  languageModel: {
+    global: 'LanguageModel',
+    methods: {
+      prompt: { input: true, opts: 1 },
+      promptStreaming: { input: true, opts: 1, stream: true },
+      append: { input: true, opts: 1 },
+      measureContextUsage: { opts: 1, alias: 'measureInputUsage' },
+      measureInputUsage: { opts: 1, alias: 'measureContextUsage' },
+      clone: { opts: 0, handle: true },
+    },
+    props: ['contextUsage', 'contextWindow', 'inputUsage', 'inputQuota', 'samplingMode', 'topK', 'temperature'],
+  },
+  summarizer: {
+    global: 'Summarizer',
+    methods: {
+      summarize: { input: true, opts: 1 },
+      summarizeStreaming: { input: true, opts: 1, stream: true },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['sharedContext', 'type', 'format', 'length', 'expectedInputLanguages', 'expectedContextLanguages', 'outputLanguage', 'inputQuota'],
+  },
+  writer: {
+    global: 'Writer',
+    methods: {
+      write: { input: true, opts: 1 },
+      writeStreaming: { input: true, opts: 1, stream: true },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['sharedContext', 'tone', 'format', 'length', 'expectedInputLanguages', 'expectedContextLanguages', 'outputLanguage', 'inputQuota'],
+  },
+  rewriter: {
+    global: 'Rewriter',
+    methods: {
+      rewrite: { input: true, opts: 1 },
+      rewriteStreaming: { input: true, opts: 1, stream: true },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['sharedContext', 'tone', 'format', 'length', 'expectedInputLanguages', 'expectedContextLanguages', 'outputLanguage', 'inputQuota'],
+  },
+  translator: {
+    global: 'Translator',
+    methods: {
+      translate: { input: true, opts: 1 },
+      translateStreaming: { input: true, opts: 1, stream: true },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['sourceLanguage', 'targetLanguage', 'inputQuota'],
+  },
+  languageDetector: {
+    global: 'LanguageDetector',
+    methods: {
+      detect: { input: true, opts: 1 },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['expectedInputLanguages', 'inputQuota'],
+  },
+  proofreader: {
+    global: 'Proofreader',
+    methods: {
+      proofread: { input: true, opts: 1 },
+      measureInputUsage: { opts: 1 },
+    },
+    props: ['includeCorrectionTypes', 'includeCorrectionExplanations', 'expectedInputLanguages', 'correctionExplanationLanguage', 'inputQuota'],
+  },
+};
+
+/** Every API key `chromeAI({ apis })` accepts, in order. */
+export const CHROME_AI_APIS = Object.freeze(Object.keys(API_TABLE));
+
+/** Create-option keys that never reach the platform's `availability()`. */
+const NOT_FOR_AVAILABILITY = new Set(['signal', 'monitor', 'onDownloadProgress', 'initialPrompts', 'sharedContext']);
+
+const DEFAULT_LIMITS = Object.freeze({ maxHandles: 8, maxStreams: 4 });
+
+function domError(message, name) {
+  return new DOMException(message, name);
+}
+
+function isObject(v) {
+  return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+
+function checkBudget(where, key, value) {
+  if (value === undefined) return;
+  if (!(typeof value === 'number' && Number.isFinite(value) && value >= 0)) {
+    throw new TypeError(`${where}.${key} must be a non-negative number (0 = unlimited)`);
+  }
+}
+
+/**
+ * The sandbox-side adapter, stringified into the sandbox (no outside
+ * references). Chrome's `monitor` is a synchronous callback that receives an
+ * EventTarget; a function cannot cross, so the adapter calls `monitor` with a
+ * local EventTarget and passes the host a progress callback instead, whose
+ * calls it turns into `downloadprogress` events.
+ */
+function chromeAIClient(api) {
+  const G = globalThis;
+  const EventTargetCtor = G.EventTarget;
+  const EventCtor = G.Event;
+  const ProgressEventCtor = G.ProgressEvent;
+  const defineProperty = Object.defineProperty;
+  const keys = Object.keys;
+
+  function progressEvent(p) {
+    const init = {
+      lengthComputable: true,
+      loaded: p && typeof p.loaded === 'number' ? p.loaded : 0,
+      total: p && typeof p.total === 'number' ? p.total : 1,
+    };
+    if (typeof ProgressEventCtor === 'function') return new ProgressEventCtor('downloadprogress', init);
+    const e = new EventCtor('downloadprogress');
+    for (const k of keys(init)) defineProperty(e, k, { value: init[k], enumerable: true });
+    return e;
+  }
+
+  function makeMonitor() {
+    const target = new EventTargetCtor();
+    let handler = null;
+    defineProperty(target, 'ondownloadprogress', {
+      enumerable: true,
+      get() { return handler; },
+      set(fn) {
+        if (handler) target.removeEventListener('downloadprogress', handler);
+        handler = typeof fn === 'function' ? fn : null;
+        if (handler) target.addEventListener('downloadprogress', handler);
+      },
+    });
+    return target;
+  }
+
+  for (const key of keys(api)) {
+    const ns = api[key];
+    if (!ns || typeof ns.create !== 'function') continue;
+    const create = ns.create;
+    ns.create = function create_(options) {
+      if (options !== null && typeof options === 'object' && typeof options.monitor === 'function') {
+        const monitor = makeMonitor();
+        options.monitor(monitor);
+        const rest = {};
+        for (const k of keys(options)) if (k !== 'monitor') rest[k] = options[k];
+        rest.onDownloadProgress = (p) => { monitor.dispatchEvent(progressEvent(p)); };
+        options = rest;
+      }
+      return create(options);
+    };
+    defineProperty(ns.create, 'name', { value: 'create' });
+  }
+  return api;
+}
+
+/**
+ * Tool-use content (`tool-call` / `tool-response`) holds platform objects
+ * (LanguageModelToolCall, LanguageModelToolSuccess, LanguageModelToolError)
+ * that cannot be cloned. In the sandbox they are plain objects with the same
+ * fields; the host converts in both directions.
+ */
+function toPlatformContent(item, scope) {
+  if (!isObject(item) || !isObject(item.value)) return item;
+  const v = item.value;
+  if (item.type === 'tool-call' && typeof scope.LanguageModelToolCall === 'function') {
+    return { ...item, value: new scope.LanguageModelToolCall(v) };
+  }
+  if (item.type === 'tool-response') {
+    if (v.errorMessage !== undefined && typeof scope.LanguageModelToolError === 'function') {
+      return { ...item, value: new scope.LanguageModelToolError(v) };
+    }
+    if (typeof scope.LanguageModelToolSuccess === 'function') {
+      return { ...item, value: new scope.LanguageModelToolSuccess(v) };
+    }
+  }
+  return item;
+}
+
+function toPlatformPrompt(input, scope) {
+  if (!Array.isArray(input)) return input;
+  return input.map((msg) => (isObject(msg) && Array.isArray(msg.content)
+    ? { ...msg, content: msg.content.map((c) => toPlatformContent(c, scope)) }
+    : msg));
+}
+
+function toPlainContent(item) {
+  if (!isObject(item) || item.value === null || typeof item.value !== 'object') return item;
+  const v = item.value;
+  if (item.type === 'tool-call') {
+    return { type: item.type, value: { callId: v.callId, name: v.name, arguments: v.arguments ?? null } };
+  }
+  if (item.type === 'tool-response') {
+    return {
+      type: item.type,
+      value: v.errorMessage !== undefined
+        ? { callId: v.callId, name: v.name, errorMessage: v.errorMessage }
+        : { callId: v.callId, name: v.name, result: v.result ? [...v.result] : [] },
+    };
+  }
+  return item;
+}
+
+function toPlainResult(value) {
+  return Array.isArray(value) ? value.map(toPlainContent) : value;
+}
+
+/**
+ * Create the Chrome built-in AI bridge.
+ *
+ * @param {object} [options]
+ * @param {string[]} [options.apis]  which APIs to expose (default: all of CHROME_AI_APIS)
+ * @param {(request: object) => boolean | Promise<boolean>} [options.onRequest]  consent hook; only `true` allows
+ * @param {{ maxInputTokens?: number, maxInputTokensPerCall?: number }} [options.budgets]  token budgets per sandbox
+ * @param {object} [options.limits]  bridge limits (default { maxHandles: 8, maxStreams: 4 })
+ * @param {boolean} [options.globals]  also install LanguageModel, Summarizer, ... as sandbox globals
+ * @param {object} [options.scope]  where the platform constructors live (default globalThis; tests pass fakes)
+ */
+export function chromeAI(options = {}) {
+  if (!isObject(options)) throw new TypeError('chromeAI(options): options must be an object');
+  for (const k of Object.keys(options)) {
+    if (!['apis', 'onRequest', 'budgets', 'limits', 'globals', 'scope'].includes(k)) {
+      throw new TypeError(`chromeAI: '${k}' is not a known option (apis, onRequest, budgets, limits, globals, scope)`);
+    }
+  }
+  const { apis = CHROME_AI_APIS, onRequest, budgets = {}, limits = {}, globals = false, scope = globalThis } = options;
+  if (!Array.isArray(apis) || !apis.every((a) => CHROME_AI_APIS.includes(a))) {
+    throw new TypeError(`chromeAI: apis must be an array of ${CHROME_AI_APIS.map((a) => `'${a}'`).join(', ')}`);
+  }
+  if (!isObject(budgets)) throw new TypeError('chromeAI: budgets must be an object');
+  for (const k of Object.keys(budgets)) {
+    if (!['maxInputTokens', 'maxInputTokensPerCall'].includes(k)) {
+      throw new TypeError(`chromeAI: budgets.${k} is not a known budget (maxInputTokens, maxInputTokensPerCall)`);
+    }
+    checkBudget('chromeAI: budgets', k, budgets[k]);
+  }
+  if (!isObject(scope)) throw new TypeError('chromeAI: scope must be an object');
+  const maxTotal = budgets.maxInputTokens ?? 0;
+  const maxPerCall = budgets.maxInputTokensPerCall ?? 0;
+
+  /** Count model input against the budgets before it reaches the model. */
+  async function charge(ctx, target, typeName, input, opts) {
+    if (!maxTotal && !maxPerCall) return;
+    const measure = typeof target.measureContextUsage === 'function'
+      ? target.measureContextUsage
+      : typeof target.measureInputUsage === 'function' ? target.measureInputUsage : null;
+    if (!measure) {
+      throw domError(`${typeName} cannot measure its input in this browser, so the token budget cannot be enforced`, 'NotSupportedError');
+    }
+    const { signal, ...measureOpts } = opts;
+    const n = Number(await measure.call(target, input, { ...measureOpts, signal }));
+    const tokens = Number.isFinite(n) ? n : 0;
+    if (maxPerCall > 0 && tokens > maxPerCall) {
+      throw Object.assign(domError(`Input is ${tokens} tokens, over budgets.maxInputTokensPerCall (${maxPerCall})`, 'QuotaExceededError'), { requested: tokens, quota: maxPerCall });
+    }
+    if (maxTotal > 0 && ctx.state.inputTokens + tokens > maxTotal) {
+      throw Object.assign(
+        domError(`Input of ${tokens} tokens would exceed budgets.maxInputTokens (${ctx.state.inputTokens} of ${maxTotal} used)`, 'QuotaExceededError'),
+        { requested: tokens, quota: maxTotal - ctx.state.inputTokens }
+      );
+    }
+    ctx.state.inputTokens += tokens;
+  }
+
+  const api = {};
+  const handles = {};
+  const aliases = {};
+  for (const key of apis) {
+    const info = API_TABLE[key];
+    const typeName = info.global;
+    const getAPI = () => {
+      const C = scope[typeName];
+      return typeof C === 'function' || isObject(C) ? C : null;
+    };
+    const coreOptions = (opts) => {
+      if (!isObject(opts)) return opts;
+      const out = {};
+      for (const k of Object.keys(opts)) if (!NOT_FOR_AVAILABILITY.has(k)) out[k] = opts[k];
+      return out;
+    };
+
+    const ns = {
+      async availability(ctx, opts) {
+        const C = getAPI();
+        if (!C || typeof C.availability !== 'function') return 'unavailable';
+        return C.availability(coreOptions(opts));
+      },
+      create: {
+        handle: true,
+        // Chrome needs a user gesture when the model still has to be
+        // downloaded (sticky activation is enough in shipping Chrome).
+        async requiresUserActivation(ctx, opts) {
+          const C = getAPI();
+          if (!C || typeof C.availability !== 'function') return false;
+          try {
+            return (await C.availability(coreOptions(opts))) === 'downloadable' ? 'sticky' : false;
+          } catch {
+            return false;
+          }
+        },
+        async call(ctx, opts) {
+          const C = getAPI();
+          if (!C || typeof C.create !== 'function') {
+            throw domError(`${typeName} is not available in this browser`, 'NotSupportedError');
+          }
+          let createOpts = opts;
+          if (isObject(opts)) {
+            const { monitor, onDownloadProgress, signal, ...rest } = opts;
+            if (Array.isArray(rest.tools) && rest.tools.some((t) => isObject(t) && typeof t.execute === 'function')) {
+              throw domError(
+                "Prompt API tools have no execute() callback: tool use is open-loop (prompt() returns 'tool-call' content " +
+                "and you append a 'tool-response'). Drop execute from the tool declarations.",
+                'NotSupportedError'
+              );
+            }
+            createOpts = { ...rest, signal: ctx.signal };
+            if (Array.isArray(rest.initialPrompts)) createOpts.initialPrompts = toPlatformPrompt(rest.initialPrompts, scope);
+            if (typeof onDownloadProgress === 'function') {
+              createOpts.monitor = (m) => {
+                m.addEventListener('downloadprogress', (e) => {
+                  onDownloadProgress({ loaded: e.loaded, total: e.total }).catch(() => {});
+                });
+              };
+            }
+          } else if (opts === undefined) {
+            createOpts = { signal: ctx.signal };
+          }
+          const instance = await C.create(createOpts);
+          // The tokens initial prompts already used count against the budget.
+          if (maxTotal > 0 && key === 'languageModel') {
+            const used = Number(instance?.contextUsage ?? instance?.inputUsage ?? 0);
+            if (Number.isFinite(used) && used > 0) {
+              if (ctx.state.inputTokens + used > maxTotal) {
+                try { instance.destroy?.(); } catch {}
+                throw Object.assign(
+                  domError(`initialPrompts use ${used} tokens, over budgets.maxInputTokens (${ctx.state.inputTokens} of ${maxTotal} used)`, 'QuotaExceededError'),
+                  { requested: used, quota: maxTotal - ctx.state.inputTokens }
+                );
+              }
+              ctx.state.inputTokens += used;
+            }
+          }
+          return ctx.handle(typeName, instance);
+        },
+      },
+    };
+    if (key === 'languageModel' && typeof scope.LanguageModel?.params === 'function') {
+      // Extension contexts only; LanguageModelParams is a platform object.
+      ns.params = async () => {
+        const p = await scope.LanguageModel.params();
+        return p == null ? null : {
+          defaultTopK: p.defaultTopK, maxTopK: p.maxTopK, defaultTemperature: p.defaultTemperature, maxTemperature: p.maxTemperature,
+        };
+      };
+    }
+    api[key] = ns;
+
+    const methods = {};
+    for (const [name, m] of Object.entries(info.methods)) {
+      const call = async (ctx, ...args) => {
+        const target = ctx.target;
+        let fn = target[name];
+        if (typeof fn !== 'function' && m.alias) fn = target[m.alias];
+        if (typeof fn !== 'function') {
+          throw domError(`${typeName}.${name}() is not available in this browser`, 'NotSupportedError');
+        }
+        const a = args.slice();
+        while (a.length <= m.opts) a.push(undefined);
+        const opts = isObject(a[m.opts]) ? { ...a[m.opts] } : {};
+        opts.signal = ctx.signal;
+        a[m.opts] = opts;
+        if (key === 'languageModel' && m.opts === 1) a[0] = toPlatformPrompt(a[0], scope);
+        if (m.input) await charge(ctx, target, typeName, a[0], opts);
+        const result = fn.apply(target, a);
+        if (m.stream) return result;
+        if (m.handle) return ctx.handle(typeName, await result);
+        return toPlainResult(await result);
+      };
+      methods[name] = { call, stream: m.stream === true, handle: m.handle === true };
+    }
+    handles[typeName] = {
+      methods,
+      props: info.props,
+      destroy: (target) => target.destroy?.(),
+    };
+    aliases[typeName] = key;
+  }
+
+  return defineBridge({
+    api,
+    handles,
+    limits: { ...DEFAULT_LIMITS, ...limits },
+    ...(onRequest !== undefined ? { onRequest } : {}),
+    createState: () => ({ inputTokens: 0 }),
+    stats: (state) => ({ inputTokens: state.inputTokens }),
+    client: chromeAIClient,
+    ...(globals ? { globals: aliases } : {}),
+  });
+}

package/src/iframe-host.mjs

@@ -29,11 +29,12 @@ const OWNED_ATTRIBUTES = new Set(['srcdoc', 'src', 'sandbox']);
 
 /**
  * The runtime script the frame runs: Worker mode's, minus the global lockdown.
- * @param {{ networkFetch?: boolean }} [options]  `networkFetch`: replace the
- *   frame's `fetch` with the host-backed one (`createSandbox({ network })`).
+ * @param {{ networkFetch?: boolean, bridges?: boolean }} [options]  `networkFetch`: replace the
+ *   frame's `fetch` with the host-backed one (`createSandbox({ network })`);
+ *   `bridges`: include the bridge client (`createSandbox({ bridges })`).
  */
-export function makeIframeRuntimeSource({ networkFetch = false } = {}) {
-  return makeRuntimeSource({ lockdown: false, networkFetch });
+export function makeIframeRuntimeSource({ networkFetch = false, bridges = false } = {}) {
+  return makeRuntimeSource({ lockdown: false, networkFetch, bridges });
 }
 
 /**

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 ──
 
@@ -505,6 +642,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 +705,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';