@johnhenry/andbox 0.3.0 → 0.3.1

package/README.md

@@ -529,7 +529,8 @@ Evaluates JavaScript code in the sandbox. The code is wrapped in an async IIFE -
 |--------|------|-------------|
 | `timeoutMs` | `number` | Override default timeout |
 | `signal` | `AbortSignal` | Abort evaluation |
-| `onConsole` | `(level, ...args) => void` | Per-call console handler |
+| `onConsole` | `(level, ...args) => void` | Per-call console handler: gets this call's console output only |
+| `consoleId` | `string \| number` | A name for this call's console output: every console handler gets it as `this.consoleId` |
 
 **Inside sandbox code (Worker mode):**
 
@@ -537,6 +538,22 @@ Evaluates JavaScript code in the sandbox. The code is wrapped in an async IIFE -
 - `sandboxImport(name)` -- Import a virtual module
 - `console.log/warn/error/info` -- Forwarded to host `onConsole`
 
+**Console attribution (0.3.1).** Calls on one sandbox may overlap, and each call's console output goes to that call's own `onConsole` while it is running, never to whichever call started last ([andbox#41](https://github.com/johnhenry/andbox/issues/41)). Output from a call that passed no `onConsole`, and output that arrives after a call settled (a timer it left behind), goes to the sandbox-level `onConsole`. Every handler is called with `this.consoleId`, the `consoleId` of the call that logged (`undefined` if it gave none), so late output can still be credited (use a `function`, not an arrow):
+
+```js
+const sb = await createSandbox({
+  onConsole(level, ...args) { log(this.consoleId ?? 'sandbox', level, args); },
+});
+await Promise.all([
+  sb.evaluate(codeA, { consoleId: 'pane-a' }),
+  sb.evaluate(codeB, { consoleId: 'pane-b' }),
+]);
+```
+
+What it covers: the `console` andbox gives the evaluated code, including closures that keep it (a timer, a callback) after the call returns. It is attribution, not authentication: the runtime carries the id with each message, so code in the sandbox that holds another call's `console` logs as that call. Thread stdout/stderr (`node-worker`'s `captureStdio`) names no call and goes to the newest running call's handler, as before.
+
+**Errors keep the sandbox's stack (0.3.1).** A rejected `evaluate()` has the error's `name` and `message` (and `code`, when set); `err.stack` is the host's own stack, and `err.sandboxStack` is the stack as the sandbox saw it, with the evaluated code's frames, line numbers and any `//# sourceURL=` names ([andbox#41](https://github.com/johnhenry/andbox/issues/41)). Line numbers count from andbox's wrapper, which puts three lines before your code in the `new Function`-based modes: in V8 (Chrome, Node) line 1 of your code is reported as line 4; other engines may count differently. It is `undefined` when the sandbox reported no stack.
+
 ### `sandbox.defineModule(name, source)`
 
 Defines a virtual module that sandbox code can import via `sandboxImport(name)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnhenry/andbox",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "type": "module",
   "description": "Sandboxed JavaScript runtime with Worker isolation, RPC, import maps, timeouts, and an optional QuickJS-in-WebAssembly mode",
   "main": "./src/index.mjs",

package/src/index.d.ts

@@ -517,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. */
@@ -540,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. */
@@ -552,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

package/src/sandbox.mjs

@@ -552,8 +552,28 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
     ? (name) => (bridgeHost.isGateName(name) ? undefined : gateLookup(name))
     : gateLookup;
 
-  // Console handler — mutable so evaluate() can swap per-call
-  let activeConsoleHandler = onConsole || null;
+  // 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();
@@ -595,7 +615,7 @@ async function createWorkerSandbox(options = {}, kind = 'worker') {
       worker = workerFactory(source);
       openBridgeSession();
       attachWorkerHandlers();
-      worker.onstdio = (stream, text) => activeConsoleHandler?.(stream, text);
+      worker.onstdio = deliverStdio;
       return;
     }
     const blob = new Blob([source], { type: 'application/javascript' });
@@ -646,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);
             }
           }
@@ -658,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;
         }
       }
@@ -789,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 = {}) {
@@ -797,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();
 
@@ -811,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.
@@ -862,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);
   }
 
   /**

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

@@ -319,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)) {
@@ -328,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];
@@ -367,7 +367,7 @@ ${bridges ? `      if (msg.bridges) {
     }
 
     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