runline 0.16.1 → 0.17.0

package/dist/config/types.d.ts

@@ -5,5 +5,11 @@ export interface RunlineConfig {
     timeoutMs: number;
     /** Memory limit for QuickJS in bytes. Default 64MB. */
     memoryLimitBytes: number;
+    /**
+     * Bodies one pooled worker may run before being retired. Bounds cross-run
+     * global contamination; memory is a per-thread cost so this does not
+     * meaningfully affect it. Default 50.
+     */
+    maxRunsPerWorker?: number;
 }
 export declare const DEFAULT_CONFIG: RunlineConfig;

package/dist/core/engine.d.ts

@@ -28,13 +28,47 @@ export declare function shouldArmRssWatchdog(versions?: Partial<Record<string, s
  * - timeout: worker.terminate() — interrupts even `while(true){}`
  * - memory: resourceLimits.maxOldGenerationSizeMb (node) + an RSS-delta
  *   watchdog fallback; both surface as a clean "Memory limit exceeded" error
- * - crash containment: a dead worker never takes the host process down, and
- *   each execute() gets a fresh worker, so the engine stays usable
+ * - crash containment: a dead worker never takes the host process down
+ *
+ * ## Why the worker is pooled
+ *
+ * Spawning a worker per execution leaks ~175KB of RSS per call under bun
+ * (~55KB under node): the runtime does not return a dead thread's arena to
+ * the OS, and there is no handle to free from JS — awaiting `terminate()`,
+ * dropping listeners, and letting the worker exit naturally all still leak.
+ * The only lever is to stop creating threads, so one worker serves many runs
+ * (measured 187KB/run -> 4KB/run).
+ *
+ * Reuse is given up the moment it could be unsafe. A worker is retired on
+ * timeout, crash, memory kill, plugin-surface change, leftover timers, or
+ * after `maxRunsPerWorker` bodies. A run that arrives while the pooled worker
+ * is busy gets its own throwaway worker, so concurrency semantics are
+ * unchanged.
  */
 export declare class ExecutionEngine {
     private registry;
     private config;
+    private pooled;
+    private readonly maxRunsPerWorker;
     constructor(registry: PluginRegistry, config: RunlineConfig);
+    /** Retire the pooled worker, if any. Safe to call repeatedly. */
+    dispose(): void;
+    /**
+     * Hand back a worker to run one body in.
+     *
+     * Prefers the pooled worker when it is idle and shaped correctly. Anything
+     * else — wrong shape, quota spent, or already busy — gets a fresh worker.
+     * A worker created because the pool was occupied stays private to that run
+     * (`pooled` is false) and is destroyed when the run ends, so overlapping
+     * callers keep the parallelism they had before pooling existed.
+     */
+    private acquire;
+    /**
+     * Finish with a worker. `retire` means the worker is no longer trustworthy
+     * — anything other than a clean completion. Private (non-pooled) workers
+     * are always destroyed.
+     */
+    private release;
     execute(code: string, options?: EngineOptions): Promise<ExecuteResult>;
     private invokeAction;
     /**
@@ -47,3 +81,11 @@ export declare class ExecutionEngine {
     private selfPrefixHint;
     private resolveConnection;
 }
+/**
+ * Normalize a caller's code into a function body. Kept host-side so the
+ * worker source carries no user code and can therefore be reused.
+ *
+ * Exported for tests: this is the one place the "bare expression vs arrow
+ * function" calling convention is decided.
+ */
+export declare function buildRunBody(code: string): string;

package/dist/core/engine.js

@@ -1,7 +1,42 @@
+import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { Worker } from "node:worker_threads";
 import { applyEnvOverrides, updateConnectionConfig } from "../config/loader.js";
 import { formatValidationError, helpInputs, isTypedInputSchema, validateTypedInput, } from "../plugin/schema.js";
+/**
+ * How many bodies one worker may run before it is retired.
+ *
+ * This is a memory dial, not a safety dial. Every recycle spawns a thread
+ * whose arena the runtime never returns (~190KB), so the cap sets a floor on
+ * the residual leak: measured over 100k executions, 50 costs 3.85 KB/run and
+ * never plateaus, while an unbounded worker settles at 0.06 KB/run.
+ *
+ * It is not what keeps runs isolated. A body that leaves a timer, an
+ * undeletable global, or a touched intrinsic retires its worker immediately
+ * (see `dirty` in the worker source), so contamination never survives the run
+ * that caused it. The cap only bounds hazards the detector cannot see, which
+ * after descriptor-level intrinsic checking is a narrow set: prototype-chain
+ * surgery and mutation of objects reachable but not enumerated.
+ *
+ * 500 keeps that backstop while cutting the residual leak ~10x.
+ */
+const DEFAULT_MAX_RUNS_PER_WORKER = 500;
+/**
+ * Identity of a worker's immutable configuration.
+ *
+ * Must be a real digest, not a length or a count: a collision hands a run a
+ * worker whose action surface or memory ceiling is not the one it asked for.
+ */
+function workerShape(pluginNames, helpData, memoryLimitMb) {
+    const surface = JSON.stringify([pluginNames, helpData]);
+    // FNV-1a: no dependency, stable across processes, ample for a cache key.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < surface.length; i++) {
+        hash ^= surface.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193) >>> 0;
+    }
+    return `${hash.toString(36)}:${surface.length}:${memoryLimitMb}`;
+}
 /**
  * Whether to arm the host-side RSS watchdog for a worker run.
  *
@@ -26,51 +61,137 @@ const RSS_WATCHDOG_SLACK_BYTES = 128 * 1024 * 1024;
  * - timeout: worker.terminate() — interrupts even `while(true){}`
  * - memory: resourceLimits.maxOldGenerationSizeMb (node) + an RSS-delta
  *   watchdog fallback; both surface as a clean "Memory limit exceeded" error
- * - crash containment: a dead worker never takes the host process down, and
- *   each execute() gets a fresh worker, so the engine stays usable
+ * - crash containment: a dead worker never takes the host process down
+ *
+ * ## Why the worker is pooled
+ *
+ * Spawning a worker per execution leaks ~175KB of RSS per call under bun
+ * (~55KB under node): the runtime does not return a dead thread's arena to
+ * the OS, and there is no handle to free from JS — awaiting `terminate()`,
+ * dropping listeners, and letting the worker exit naturally all still leak.
+ * The only lever is to stop creating threads, so one worker serves many runs
+ * (measured 187KB/run -> 4KB/run).
+ *
+ * Reuse is given up the moment it could be unsafe. A worker is retired on
+ * timeout, crash, memory kill, plugin-surface change, leftover timers, or
+ * after `maxRunsPerWorker` bodies. A run that arrives while the pooled worker
+ * is busy gets its own throwaway worker, so concurrency semantics are
+ * unchanged.
  */
 export class ExecutionEngine {
     registry;
     config;
+    pooled = null;
+    maxRunsPerWorker;
     constructor(registry, config) {
         this.registry = registry;
         this.config = config;
+        this.maxRunsPerWorker =
+            config.maxRunsPerWorker ?? DEFAULT_MAX_RUNS_PER_WORKER;
+    }
+    /** Retire the pooled worker, if any. Safe to call repeatedly. */
+    dispose() {
+        const entry = this.pooled;
+        if (!entry)
+            return;
+        this.pooled = null;
+        destroyWorker(entry.worker);
+    }
+    /**
+     * Hand back a worker to run one body in.
+     *
+     * Prefers the pooled worker when it is idle and shaped correctly. Anything
+     * else — wrong shape, quota spent, or already busy — gets a fresh worker.
+     * A worker created because the pool was occupied stays private to that run
+     * (`pooled` is false) and is destroyed when the run ends, so overlapping
+     * callers keep the parallelism they had before pooling existed.
+     */
+    acquire(shape, build) {
+        const idle = this.pooled && !this.pooled.busy ? this.pooled : null;
+        if (idle && (idle.shape !== shape || idle.runs >= this.maxRunsPerWorker)) {
+            this.dispose();
+        }
+        else if (idle) {
+            return { entry: idle, pooled: true };
+        }
+        const entry = {
+            worker: build(),
+            shape,
+            runs: 0,
+            busy: false,
+        };
+        // An idle pooled worker must not hold the host's event loop open, or a
+        // one-shot CLI would never exit. The per-run timeout timer keeps the loop
+        // alive for the duration of an actual run.
+        entry.worker.unref?.();
+        if (!this.pooled) {
+            this.pooled = entry;
+            return { entry, pooled: true };
+        }
+        return { entry, pooled: false };
+    }
+    /**
+     * Finish with a worker. `retire` means the worker is no longer trustworthy
+     * — anything other than a clean completion. Private (non-pooled) workers
+     * are always destroyed.
+     */
+    release(entry, pooled, retire) {
+        entry.busy = false;
+        if (!pooled || retire) {
+            if (this.pooled === entry)
+                this.pooled = null;
+            destroyWorker(entry.worker);
+        }
     }
     async execute(code, options) {
         const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs;
         const memoryLimitBytes = options?.memoryLimitBytes ?? this.config.memoryLimitBytes;
         const logs = [];
         const plugins = this.registry.listPlugins();
-        const source = buildWorkerSource(code, plugins.map((p) => p.name), buildHelpData(plugins));
+        const pluginNames = plugins.map((p) => p.name);
+        const helpData = buildHelpData(plugins);
+        const memoryLimitMb = Math.max(8, Math.floor(memoryLimitBytes / (1024 * 1024)));
+        // resourceLimits are fixed at construction, so a run asking for a
+        // different ceiling must not inherit an existing worker's.
+        const shape = workerShape(pluginNames, helpData, memoryLimitMb);
+        const body = buildRunBody(code);
+        let acquired;
+        try {
+            acquired = this.acquire(shape, () => new Worker(buildWorkerSource(pluginNames, helpData), {
+                eval: true,
+                resourceLimits: { maxOldGenerationSizeMb: memoryLimitMb },
+            }));
+        }
+        catch (err) {
+            return { result: null, error: formatError(err), logs };
+        }
+        const { entry, pooled } = acquired;
         return new Promise((resolve) => {
-            const memoryLimitMb = Math.max(8, Math.floor(memoryLimitBytes / (1024 * 1024)));
-            let worker;
-            try {
-                worker = new Worker(source, {
-                    eval: true,
-                    resourceLimits: { maxOldGenerationSizeMb: memoryLimitMb },
-                });
-            }
-            catch (err) {
-                resolve({ result: null, error: formatError(err), logs });
-                return;
-            }
+            const worker = entry.worker;
+            const runId = newRunId();
+            entry.busy = true;
+            entry.runs++;
             let settled = false;
-            const finish = (r) => {
+            const finish = (r, retire) => {
                 if (settled)
                     return;
                 settled = true;
                 clearTimeout(timeoutTimer);
                 clearInterval(rssTimer);
-                void worker.terminate();
+                worker.off("message", onMessage);
+                worker.off("error", onError);
+                worker.off("exit", onExit);
+                this.release(entry, pooled, retire);
                 resolve(r);
             };
+            // A spinning body blocks the worker's event loop, so it can never be
+            // asked to stop — terminate is the only remedy and the worker is gone.
             const timeoutTimer = setTimeout(() => {
                 finish({
                     result: null,
                     error: `Execution timed out after ${timeoutMs}ms`,
                     logs,
-                });
+                }, true);
             }, timeoutMs);
             let rssTimer;
             if (shouldArmRssWatchdog()) {
@@ -82,7 +203,7 @@ export class ExecutionEngine {
                             result: null,
                             error: `Memory limit exceeded (${memoryLimitMb}MB)`,
                             logs,
-                        });
+                        }, true);
                     }
                 }, 100);
                 rssTimer.unref?.();
@@ -100,9 +221,12 @@ export class ExecutionEngine {
                     // worker already gone
                 }
             };
-            worker.on("message", (msg) => {
+            const onMessage = (msg) => {
                 if (settled)
                     return;
+                // Straggler from an earlier body on this same worker.
+                if (msg.runId !== runId)
+                    return;
                 if (msg.t === "log") {
                     logs.push(`[${msg.level}] ${msg.line}`);
                 }
@@ -115,16 +239,24 @@ export class ExecutionEngine {
                         catch (err) {
                             reply({
                                 t: "result",
+                                runId,
                                 id: msg.id,
                                 ok: false,
                                 error: `Action result not JSON-serializable: ${err instanceof Error ? err.message : String(err)}`,
                             });
                             return;
                         }
-                        reply({ t: "result", id: msg.id, ok: true, value: serialized });
+                        reply({
+                            t: "result",
+                            runId,
+                            id: msg.id,
+                            ok: true,
+                            value: serialized,
+                        });
                     }, (err) => {
                         reply({
                             t: "result",
+                            runId,
                             id: msg.id,
                             ok: false,
                             error: err instanceof Error ? err.message : String(err),
@@ -132,27 +264,33 @@ export class ExecutionEngine {
                     });
                 }
                 else if (msg.t === "done") {
+                    // A body that left timers running keeps consuming the worker's
+                    // event loop and can post into later runs: never reuse it.
                     finish(msg.ok
                         ? { result: msg.result, logs }
-                        : { result: null, error: msg.error ?? "Unknown error", logs });
+                        : { result: null, error: msg.error ?? "Unknown error", logs }, msg.dirty === true);
                 }
-            });
-            worker.on("error", (err) => {
+            };
+            const onError = (err) => {
                 finish({
                     result: null,
                     error: err.code === "ERR_WORKER_OUT_OF_MEMORY"
                         ? `Memory limit exceeded (${memoryLimitMb}MB)`
                         : formatError(err),
                     logs,
-                });
-            });
-            worker.on("exit", (exitCode) => {
+                }, true);
+            };
+            const onExit = (exitCode) => {
                 finish({
                     result: null,
                     error: `Worker exited unexpectedly (code ${exitCode})`,
                     logs,
-                });
-            });
+                }, true);
+            };
+            worker.on("message", onMessage);
+            worker.on("error", onError);
+            worker.on("exit", onExit);
+            reply({ t: "run", runId, body });
         });
     }
     async invokeAction(path, args) {
@@ -213,7 +351,19 @@ export class ExecutionEngine {
         return applyEnvOverrides(base, plugin.connectionConfigSchema);
     }
 }
-// ── Helpers ──────────────────────────────────────────────
+// ── Helpers ──────────────────────────────
+/**
+ * Drop every listener before terminating: a worker being torn down can still
+ * emit `exit`, and a stale handler would resolve a run that already settled.
+ */
+function destroyWorker(worker) {
+    worker.removeAllListeners();
+    void worker.terminate();
+}
+/** Unguessable per-run token. See the WorkerMessage comment for why. */
+function newRunId() {
+    return randomUUID();
+}
 /**
  * JSON round-trip to (a) guarantee structured-clone compatibility and
  * (b) preserve the previous engine's value semantics, where every action
@@ -255,13 +405,35 @@ function buildHelpData(plugins) {
     }
     return data;
 }
-function buildWorkerSource(code, pluginNames = [], helpData = {}) {
+/**
+ * Normalize a caller's code into a function body. Kept host-side so the
+ * worker source carries no user code and can therefore be reused.
+ *
+ * Exported for tests: this is the one place the "bare expression vs arrow
+ * function" calling convention is decided.
+ */
+export function buildRunBody(code) {
     const trimmed = code.trim();
     const looksLikeArrow = (trimmed.startsWith("async") || trimmed.startsWith("(")) &&
         trimmed.includes("=>");
-    const body = looksLikeArrow
+    return looksLikeArrow
         ? `const __fn = (${trimmed});\nif (typeof __fn !== 'function') throw new Error('Code must evaluate to a function');\nreturn await __fn();`
         : code;
+}
+function buildWorkerSource(pluginNames = [], helpData = {}) {
+    // Injected into every body's scope. `require` is here because bodies are
+    // compiled with `new Function`, whose scope is the worker's *global* object
+    // — not the module scope that used to hold the inlined body. Without it,
+    // pooling would silently revoke a documented capability ("agent code gets
+    // the full host JS runtime") as a side effect of a memory fix.
+    const injectNames = [
+        ...pluginNames,
+        "actions",
+        "console",
+        "fetch",
+        "require",
+        "MiniSearch",
+    ];
     const wrapped = `"use strict";
 const { parentPort: __port } = require("node:worker_threads");
 
@@ -272,29 +444,62 @@ process.exit = (code) => {
   throw new Error('process.exit(' + (code ?? 0) + ') is not available in the runline sandbox; return a value instead');
 };
 
+// ── run state ──
+// This worker outlives any single body, so everything the host correlates
+// on is scoped to __runId, an unguessable token supplied by the host.
+let __runId = null;
+
+// ── timer tracking ──
+// A body that leaves a timer behind keeps consuming this worker's event
+// loop and can fire into a later run. Count outstanding handles so the host
+// can retire the worker instead of reusing it.
+let __liveTimers = 0;
+const __realSetTimeout = setTimeout;
+const __realSetInterval = setInterval;
+const __realClearTimeout = clearTimeout;
+const __realClearInterval = clearInterval;
+const __timerHandles = new Set();
+globalThis.setTimeout = function (fn, ms, ...rest) {
+  let h;
+  const wrapped = (...a) => {
+    if (__timerHandles.delete(h)) __liveTimers--;
+    return fn(...a);
+  };
+  h = __realSetTimeout(wrapped, ms, ...rest);
+  __timerHandles.add(h);
+  __liveTimers++;
+  return h;
+};
+globalThis.setInterval = function (fn, ms, ...rest) {
+  const h = __realSetInterval(fn, ms, ...rest);
+  __timerHandles.add(h);
+  __liveTimers++;
+  return h;
+};
+globalThis.clearTimeout = function (h) {
+  if (__timerHandles.delete(h)) __liveTimers--;
+  return __realClearTimeout(h);
+};
+globalThis.clearInterval = function (h) {
+  if (__timerHandles.delete(h)) __liveTimers--;
+  return __realClearInterval(h);
+};
+
 // ── host bridge ──
 let __seq = 0;
 const __pending = new Map();
-__port.on("message", (m) => {
-  if (!m || m.t !== "result") return;
-  const p = __pending.get(m.id);
-  if (!p) return;
-  __pending.delete(m.id);
-  if (m.ok) p.resolve(m.value);
-  else p.reject(new Error(m.error));
-});
 const __invoke = (path, args) => new Promise((resolve, reject) => {
   const id = ++__seq;
   __pending.set(id, { resolve, reject });
   try {
-    __port.postMessage({ t: "invoke", id, path, args });
+    __port.postMessage({ t: "invoke", runId: __runId, id, path, args });
   } catch (e) {
     __pending.delete(id);
     reject(e);
   }
 });
 const __log = (level, line) => {
-  try { __port.postMessage({ t: "log", level, line }); } catch {}
+  try { __port.postMessage({ t: "log", runId: __runId, level, line }); } catch {}
 };
 
 const __fmt = (v) => {
@@ -478,20 +683,192 @@ const console = {
 
 const fetch = () => { throw new Error('fetch is disabled in runline sandbox'); };
 
-(async () => {
-${body}
-})().then(
-  (v) => {
+// Stable identity for this worker instance. Set before the baseline snapshot
+// so the scrub never removes it. Thread ids are recycled by the runtime and
+// cannot be used to tell one worker from the next; this can.
+globalThis.__runlineWorkerId =
+  Date.now().toString(36) + "-" + Math.random().toString(36).slice(2, 10);
+
+// ── cross-run contamination ──
+//
+// Two shapes, one policy: anything a body leaves behind that the next body
+// could observe makes this worker untrustworthy. Removable state is removed;
+// unremovable state retires the worker. Nothing is left for the next run to
+// trip over.
+
+// 1. Own properties added to globalThis. Removable — delete them.
+const __baselineGlobals = new Set(Object.getOwnPropertyNames(globalThis));
+
+// 2. Mutations to shared intrinsics (Array.prototype.push = ..., a new own
+//    property on Object, etc). NOT removable: restoring an arbitrary mutation
+//    would mean snapshotting every descriptor of every intrinsic. Instead
+//    fingerprint their own-property names and compare — a change means the
+//    body reshaped something shared and the worker must not be reused.
+const __intrinsics = [
+  Object, Object.prototype, Array, Array.prototype, Function.prototype,
+  String.prototype, Number.prototype, Boolean.prototype, Promise,
+  Promise.prototype, Map.prototype, Set.prototype, Date.prototype,
+  RegExp.prototype, Error.prototype, JSON, Math, Reflect,
+];
+// Snapshot of every intrinsic's own data properties, by reference. Taken
+// once; compared after each run. Catches BOTH shapes of tampering:
+//   - additions/removals  (the own-name set changes)
+//   - replacements        (Array.prototype.push = fn — same name, new value)
+// A name-only fingerprint misses the second, which is the more likely
+// monkey-patch. Descriptors are read rather than the properties themselves so
+// accessor getters are never invoked here.
+const __snapshot = [];
+for (const target of __intrinsics) {
+  let names;
+  try { names = Object.getOwnPropertyNames(target); } catch { continue; }
+  for (const n of names) {
+    let d;
+    try { d = Object.getOwnPropertyDescriptor(target, n); } catch { continue; }
+    if (!d) continue;
+    // Accessors are recorded by their get/set identity, data props by value.
+    __snapshot.push([target, n, "value" in d ? d.value : d.get, names.length]);
+  }
+}
+
+const __intrinsicsIntact = () => {
+  for (let i = 0; i < __snapshot.length; i++) {
+    const [target, name, expected] = __snapshot[i];
+    let d;
+    try { d = Object.getOwnPropertyDescriptor(target, name); } catch { return false; }
+    if (!d) return false;
+    if (("value" in d ? d.value : d.get) !== expected) return false;
+  }
+  // Additions are caught by the own-name count, which is recorded per target
+  // alongside each of its entries.
+  for (let i = 0; i < __snapshot.length; i++) {
+    const [target, , , count] = __snapshot[i];
+    let names;
+    try { names = Object.getOwnPropertyNames(target); } catch { return false; }
+    if (names.length !== count) return false;
+  }
+  return true;
+};
+
+/**
+ * Returns true when this worker is still safe to reuse. Removes what it can;
+ * reports what it cannot.
+ */
+const __scrubGlobals = () => {
+  let clean = true;
+
+  // Assigning parentPort.onmessage is a setter-based route to the host
+  // channel; restore it and distrust the worker. See __bodyRequire.
+  if (__port.onmessage !== __baselineOnMessage) {
+    __port.onmessage = __baselineOnMessage;
+    clean = false;
+  }
+  for (const k of Object.getOwnPropertyNames(globalThis)) {
+    if (__baselineGlobals.has(k)) continue;
     try {
-      __port.postMessage({ t: "done", ok: true, result: __toJson(v) });
-    } catch (e) {
-      __port.postMessage({ t: "done", ok: false, error: __fmtErr(e) });
+      delete globalThis[k];
+    } catch {
+      clean = false;
     }
-  },
-  (e) => {
-    __port.postMessage({ t: "done", ok: false, error: __fmtErr(e) });
-  },
-);
+    // A non-configurable property survives a silent delete: verify, don't
+    // assume the absence of a throw means success.
+    if (Object.prototype.hasOwnProperty.call(globalThis, k)) clean = false;
+  }
+  if (!__intrinsicsIntact()) clean = false;
+  return clean;
+};
+
+// The host channel is the one capability a body must not hold.
+//
+// A body can require("node:worker_threads"). Before pooling that was
+// harmless: anything it attached died with the worker after a single run.
+// Under reuse a surviving listener sees the {t:"run", runId} of EVERY later
+// body and can post a forged "done" for it, handing that run attacker-chosen
+// output. Randomising the run id does not help — the listener is simply told
+// what it is.
+//
+// Bun's MessagePort exposes no listenerCount/removeAllListeners, so listeners
+// cannot be enumerated and stripped after the fact. Instead the route in is
+// closed: the require handed to bodies returns a worker_threads module with
+// the port fields blanked. Every other module, and everything else about this
+// one, is untouched.
+const __bodyRequire = (id) => {
+  const mod = require(id);
+  if (id === "worker_threads" || id === "node:worker_threads") {
+    return Object.freeze({
+      ...mod,
+      parentPort: null,
+      receiveMessageOnPort: undefined,
+    });
+  }
+  return mod;
+};
+
+// Names injected into every body's scope. Passing them as parameters gives
+// each run a fresh function scope, so top-level declarations in user code
+// cannot collide across runs.
+const __injectNames = ${JSON.stringify(injectNames)};
+const __injectValues = __injectNames.map((n) => {
+  switch (n) {
+    case "actions": return actions;
+    case "console": return console;
+    case "fetch": return fetch;
+    case "require": return __bodyRequire;
+    case "MiniSearch": return MiniSearch;
+    default: return __makeProxy([n]);
+  }
+});
+
+// One body, start to finish. Never throws: every outcome is a "done".
+const __baselineOnMessage = __port.onmessage;
+
+const __run = async (runId, body) => {
+  __runId = runId;
+  __pending.clear();
+  let msg;
+  try {
+    const fn = new Function(
+      ...__injectNames,
+      '"use strict"; return (async () => {\\n' + body + '\\n})();',
+    );
+    const v = await fn(...__injectValues);
+    msg = { t: "done", runId, ok: true, result: __toJson(v) };
+  } catch (e) {
+    msg = { t: "done", runId, ok: false, error: __fmtErr(e) };
+  }
+  // Scrub before reporting so the host's reuse decision and the worker's
+  // actual state agree. Dirty means "do not reuse me": a leftover timer, a
+  // global that would not delete, or a mutated shared intrinsic.
+  const __clean = __scrubGlobals();
+  msg.dirty = __liveTimers > 0 || !__clean;
+  try {
+    __port.postMessage(msg);
+  } catch (e) {
+    __port.postMessage({
+      t: "done",
+      runId,
+      ok: false,
+      error: __fmtErr(e),
+      dirty: true,
+    });
+  }
+};
+
+function __hostMessageHandler(m) {
+  if (!m) return;
+  if (m.t === "run") {
+    void __run(m.runId, m.body);
+    return;
+  }
+  if (m.t !== "result") return;
+  // Replies for a superseded run are dropped: its promises are gone.
+  if (m.runId !== __runId) return;
+  const p = __pending.get(m.id);
+  if (!p) return;
+  __pending.delete(m.id);
+  if (m.ok) p.resolve(m.value);
+  else p.reject(new Error(m.error));
+}
+__port.on("message", __hostMessageHandler);
 `;
     return wrapped;
 }

package/dist/plugins/linear/src/issues.js

@@ -1,5 +1,15 @@
 import * as t from "typebox";
 import { assertIssueInScope, buildConnArgs, COMMENT_FIELDS, ensureScopeLabelsOnCreateOrReplace, forbidScopeLabelRemoval, gql, ISSUE_FIELDS, ISSUE_LITE, issueHasScope, key, LIST_INPUT_SCHEMA, mergeIssueScopeFilter, } from "./shared.js";
+/**
+ * Linear's IssueUpdateInput accepts explicit null for clearable relations
+ * (e.g. cycleId: null removes the issue from its cycle). Omitted = leave
+ * unchanged, null = clear — the schema must express both.
+ */
+function clearable(schema, description) {
+    return t.Optional(t.Union([schema, t.Null()], {
+        description: `${description}. Pass null to clear`,
+    }));
+}
 export function registerIssueActions(rl) {
     rl.registerAction("issue.create", {
         access: "write",
@@ -86,7 +96,7 @@ export function registerIssueActions(rl) {
             ...LIST_INPUT_SCHEMA,
             teamId: t.Optional(t.String({ description: "Convenience: filter by team" })),
             assigneeId: t.Optional(t.String({ description: "Convenience: filter by assignee" })),
-        }),
+        }, { additionalProperties: false }),
         async execute(input, ctx) {
             const opts = (input ?? {});
             // Merge convenience filters into `filter`
@@ -111,9 +121,7 @@ export function registerIssueActions(rl) {
             }),
             title: t.Optional(t.String({ description: "The issue title" })),
             description: t.Optional(t.String({ description: "The issue description in markdown format" })),
-            assigneeId: t.Optional(t.String({
-                description: "The identifier of the user to assign the issue to",
-            })),
+            assigneeId: clearable(t.String(), "The identifier of the user to assign the issue to"),
             stateId: t.Optional(t.String({ description: "The team workflow state of the issue" })),
             priority: t.Optional(t.Number({
                 description: "Priority. 0=No priority, 1=Urgent, 2=High, 3=Medium, 4=Low",
@@ -127,23 +135,15 @@ export function registerIssueActions(rl) {
             removedLabelIds: t.Optional(t.Array(t.Unknown(), {
                 description: "The identifiers of issue labels to be removed from this issue",
             })),
-            projectId: t.Optional(t.String({ description: "The project associated with the issue" })),
-            projectMilestoneId: t.Optional(t.String({
-                description: "The project milestone associated with the issue",
-            })),
-            cycleId: t.Optional(t.String({ description: "The cycle associated with the issue" })),
-            parentId: t.Optional(t.String({
-                description: "The identifier of the parent issue. UUID or issue identifier (e.g., 'LIN-123')",
-            })),
+            projectId: clearable(t.String(), "The project associated with the issue"),
+            projectMilestoneId: clearable(t.String(), "The project milestone associated with the issue"),
+            cycleId: clearable(t.String(), "The cycle associated with the issue"),
+            parentId: clearable(t.String(), "The identifier of the parent issue. UUID or issue identifier (e.g., 'LIN-123')"),
             teamId: t.Optional(t.String({
                 description: "The identifier of the team associated with the issue (move issue to a different team)",
             })),
-            estimate: t.Optional(t.Number({
-                description: "The estimated complexity of the issue (Int)",
-            })),
-            dueDate: t.Optional(t.String({
-                description: "The date at which the issue is due (TimelessDate, YYYY-MM-DD)",
-            })),
+            estimate: clearable(t.Number(), "The estimated complexity of the issue (Int)"),
+            dueDate: clearable(t.String(), "The date at which the issue is due (TimelessDate, YYYY-MM-DD)"),
             subscriberIds: t.Optional(t.Array(t.Unknown(), {
                 description: "The identifiers of the users subscribing to this ticket",
             })),
@@ -153,9 +153,7 @@ export function registerIssueActions(rl) {
             subIssueSortOrder: t.Optional(t.Number({
                 description: "The position of the issue in its parent's sub-issue list (Float)",
             })),
-            snoozedUntilAt: t.Optional(t.String({
-                description: "The time until which the issue will be snoozed in Triage view (DateTime)",
-            })),
+            snoozedUntilAt: clearable(t.String(), "The time until which the issue will be snoozed in Triage view (DateTime)"),
             releaseIds: t.Optional(t.Array(t.Unknown(), {
                 description: "The identifiers of the releases associated with this issue (replaces all)",
             })),

package/dist/plugins/linear/src/shared.js

@@ -112,7 +112,7 @@ export const ISSUE_FIELDS = `id identifier title description url priority estima
   projectMilestone { id name } parent { id identifier }
   labels { nodes { id name color } }
   createdAt updatedAt completedAt canceledAt archivedAt`;
-export const ISSUE_LITE = `id identifier title url priority state { id name type } assignee { id name } team { key } updatedAt`;
+export const ISSUE_LITE = `id identifier title url priority state { id name type } assignee { id name } team { key } cycle { id number name } updatedAt`;
 export const COMMENT_FIELDS = `id body url issue { id identifier } user { id name } parent { id } createdAt updatedAt editedAt resolvedAt`;
 export const STATE_FIELDS = `id name type color position description team { id key }`;
 export const LABEL_FIELDS = `id name color description isGroup parent { id name } team { id key } createdAt`;
@@ -180,7 +180,9 @@ export function buildConnArgs(opts, filterTypeName) {
     };
 }
 export const LIST_INPUT_SCHEMA = {
-    limit: t.Optional(t.Number({ description: "Max results (default 50, max 250)" })),
+    limit: t.Optional(t.Number({
+        description: "Max results per page (default 50, max 250). For more, paginate with `after` = pageInfo.endCursor",
+    })),
     filter: t.Optional(t.Object({}, { description: "Linear filter object (see schema for the resource)" })),
     includeArchived: t.Optional(t.Boolean({ description: "Include archived items" })),
     orderBy: t.Optional(t.String({ description: "createdAt | updatedAt" })),

package/dist/sdk.d.ts

@@ -6,6 +6,11 @@ export interface RunlineOptions {
     connections?: ConnectionConfig[];
     timeoutMs?: number;
     memoryLimitBytes?: number;
+    /**
+     * Bodies one pooled worker may run before it is retired. See
+     * `ExecutionEngine` — this bounds cross-run contamination, not memory.
+     */
+    maxRunsPerWorker?: number;
 }
 export interface RunlineExecuteOptions {
     timeoutMs?: number;
@@ -14,9 +19,22 @@ export interface RunlineExecuteOptions {
 export declare class Runline {
     private _registry;
     private _config;
+    /**
+     * One engine per Runline instance, so its pooled worker survives across
+     * `execute()` calls. Constructing an engine per call would spawn (and
+     * leak) a fresh worker every time — the exact bug pooling exists to fix.
+     */
+    private _engine;
     private constructor();
+    private engine;
+    /**
+     * Retire the pooled worker. Idempotent. Callers holding a long-lived
+     * Runline should call this on shutdown; an idle pooled worker is unref'd
+     * so it will not by itself keep a process alive.
+     */
+    dispose(): void;
     static create(options?: RunlineOptions): Runline;
-    /** Execute JavaScript code in the QuickJS runtime. */
+    /** Execute JavaScript code in a pooled worker. */
     execute(code: string, options?: RunlineExecuteOptions): Promise<ExecuteResult>;
     /** Register an additional plugin after creation. */
     addPlugin(pluginOrFn: PluginDef | PluginFunction, connections?: ConnectionConfig[]): void;

package/dist/sdk.js

@@ -8,6 +8,12 @@ import { PluginRegistry } from "./plugin/registry.js";
 export class Runline {
     _registry;
     _config;
+    /**
+     * One engine per Runline instance, so its pooled worker survives across
+     * `execute()` calls. Constructing an engine per call would spawn (and
+     * leak) a fresh worker every time — the exact bug pooling exists to fix.
+     */
+    _engine = null;
     constructor(options) {
         this._registry = new PluginRegistry();
         for (const pluginOrFn of options.plugins ?? []) {
@@ -18,15 +24,32 @@ export class Runline {
             connections: options.connections ?? [],
             timeoutMs: options.timeoutMs ?? DEFAULT_CONFIG.timeoutMs,
             memoryLimitBytes: options.memoryLimitBytes ?? DEFAULT_CONFIG.memoryLimitBytes,
+            ...(options.maxRunsPerWorker !== undefined
+                ? { maxRunsPerWorker: options.maxRunsPerWorker }
+                : {}),
         };
     }
+    engine() {
+        if (!this._engine) {
+            this._engine = new ExecutionEngine(this._registry, this._config);
+        }
+        return this._engine;
+    }
+    /**
+     * Retire the pooled worker. Idempotent. Callers holding a long-lived
+     * Runline should call this on shutdown; an idle pooled worker is unref'd
+     * so it will not by itself keep a process alive.
+     */
+    dispose() {
+        this._engine?.dispose();
+        this._engine = null;
+    }
     static create(options = {}) {
         return new Runline(options);
     }
-    /** Execute JavaScript code in the QuickJS runtime. */
+    /** Execute JavaScript code in a pooled worker. */
     async execute(code, options) {
-        const engine = new ExecutionEngine(this._registry, this._config);
-        return engine.execute(code, options);
+        return this.engine().execute(code, options);
     }
     /** Register an additional plugin after creation. */
     addPlugin(pluginOrFn, connections) {
@@ -38,6 +61,9 @@ export class Runline {
                 connections: [...this._config.connections, ...connections],
             };
         }
+        // The pooled worker baked in the old plugin surface and the engine holds
+        // the old config object: both are stale now.
+        this.dispose();
     }
     /** List all available actions across all plugins. */
     actions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runline",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Code mode for agents — turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",