@desplega.ai/agent-swarm 1.165.0 → 1.167.0

package/src/scripts-runtime/executors/quickjs.ts

@@ -0,0 +1,196 @@
+import type { QuickJSWorkerMessage, QuickJSWorkerRequest } from "./quickjs-worker";
+import type { ExecutorInput, ExecutorOutput, ScriptExecutor, ScriptExecutorError } from "./types";
+
+/**
+ * Opt-in executor (`SCRIPT_EXECUTOR=quickjs`) that evaluates scripts in
+ * QuickJS compiled to WASM, inside a small pool of worker threads. There is
+ * no process spawn per run, so a short script costs about a millisecond
+ * instead of the native floor (~10 ms on Linux, ~35 ms on macOS).
+ *
+ * The sandbox has no filesystem, no process APIs, and no network except the
+ * host calls that the quickjs runner exposes (ctx.swarm, ctx.api, ctx.mcp,
+ * fetch). Every value crosses as JSON. See quickjs-runner.ts for the limits.
+ */
+
+// Each worker keeps one QuickJS WASM module (~25 ms to load) and runs one job
+// at a time. Jobs beyond the pool size wait in a queue.
+const POOL_SIZE = 4;
+// The worker enforces the wall clock itself. This margin only catches a
+// worker that stopped answering, for example a host call that never settles.
+const UNRESPONSIVE_GRACE_MS = 5_000;
+// A worker's WASM memory keeps the peak of its largest job (up to memoryMb).
+// Recycle a worker that grew past this, so idle workers stay small.
+const RECYCLE_WASM_HEAP_BYTES = 64 * 1024 * 1024;
+
+type Slot = { worker: Worker; ready: Promise<void>; busy: boolean };
+
+/**
+ * In the compiled API binary every module's `import.meta.url` is the binary
+ * itself, and the extra worker entrypoint lives at its path relative to the
+ * entrypoints' common root (`src/`). See the Dockerfile compile step.
+ */
+function workerSpecifier(): string {
+  if (import.meta.url.includes("/$bunfs/")) return "./scripts-runtime/executors/quickjs-worker.ts";
+  return new URL("./quickjs-worker.ts", import.meta.url).href;
+}
+
+function emptyOutput(error: ScriptExecutorError, stderr = ""): ExecutorOutput {
+  return {
+    result: undefined,
+    stdout: "",
+    stderr,
+    truncated: { stdout: false, stderr: false },
+    durationMs: 0,
+    exitCode: 1,
+    error,
+  };
+}
+
+class QuickJSWorkerPool {
+  private readonly slots: Slot[] = [];
+  private readonly waiters: Array<(slot: Slot) => void> = [];
+
+  constructor(private readonly size: number) {}
+
+  private spawn(): Slot {
+    const worker = new Worker(workerSpecifier());
+    // Idle workers must not keep the API process (or a test run) alive.
+    (worker as Worker & { unref?: () => void }).unref?.();
+    const ready = new Promise<void>((resolve, reject) => {
+      const onMessage = (event: MessageEvent<QuickJSWorkerMessage>) => {
+        if (event.data.type === "ready") resolve();
+        else if (event.data.type === "fatal" && event.data.id === undefined) {
+          reject(new Error(event.data.message));
+        } else return;
+        worker.removeEventListener("message", onMessage);
+      };
+      worker.addEventListener("message", onMessage);
+      worker.addEventListener("error", (event) => reject(new Error(event.message)), { once: true });
+    });
+    // A failed boot is reported to the job that waits on `ready`.
+    ready.catch(() => {});
+    const slot: Slot = { worker, ready, busy: true };
+    this.slots.push(slot);
+    return slot;
+  }
+
+  acquire(): Promise<Slot> {
+    const idle = this.slots.find((slot) => !slot.busy);
+    if (idle) {
+      idle.busy = true;
+      return Promise.resolve(idle);
+    }
+    if (this.slots.length < this.size) return Promise.resolve(this.spawn());
+    return new Promise((resolve) => this.waiters.push(resolve));
+  }
+
+  release(slot: Slot): void {
+    const waiter = this.waiters.shift();
+    if (waiter) waiter(slot);
+    else slot.busy = false;
+  }
+
+  /** Terminate a worker that is in an unknown state and hand its place to a waiter. */
+  get workerCount(): number {
+    return this.slots.length;
+  }
+
+  discard(slot: Slot): void {
+    slot.worker.terminate();
+    const index = this.slots.indexOf(slot);
+    if (index !== -1) this.slots.splice(index, 1);
+    const waiter = this.waiters.shift();
+    if (waiter) waiter(this.spawn());
+  }
+}
+
+let sharedPool: QuickJSWorkerPool | undefined;
+
+/** Number of live workers in the shared pool. For tests and diagnostics. */
+export function quickJSWorkerCount(): number {
+  return sharedPool?.workerCount ?? 0;
+}
+let requestSeq = 0;
+
+export class QuickJSScriptExecutor implements ScriptExecutor {
+  readonly name = "quickjs";
+
+  async run(input: ExecutorInput): Promise<ExecutorOutput> {
+    if (input.fsMode === "workspace-rw") {
+      return emptyOutput("executor_error", "workspace-rw not supported by quickjs executor");
+    }
+    if (input.signal?.aborted) return emptyOutput("killed");
+
+    sharedPool ??= new QuickJSWorkerPool(POOL_SIZE);
+    const pool = sharedPool;
+    const slot = await pool.acquire();
+    if (input.signal?.aborted) {
+      pool.release(slot);
+      return emptyOutput("killed");
+    }
+    try {
+      await slot.ready;
+    } catch (error) {
+      pool.discard(slot);
+      return emptyOutput(
+        "executor_error",
+        `quickjs worker failed to start: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+
+    const id = ++requestSeq;
+    const start = performance.now();
+    return await new Promise<ExecutorOutput>((resolve) => {
+      let settled = false;
+      const settle = (output: ExecutorOutput, healthy: boolean) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(watchdog);
+        slot.worker.removeEventListener("message", onMessage);
+        slot.worker.removeEventListener("error", onError);
+        input.signal?.removeEventListener("abort", onAbort);
+        if (healthy) pool.release(slot);
+        else pool.discard(slot);
+        resolve(output);
+      };
+      const elapsed = () => Math.round(performance.now() - start);
+      const onMessage = (event: MessageEvent<QuickJSWorkerMessage>) => {
+        const message = event.data;
+        if (message.type === "result" && message.id === id) {
+          // Reuse the worker only if every host call settled and its memory stayed small.
+          const reusable =
+            message.leakedHostCalls === 0 &&
+            (message.wasmHeapBytes ?? 0) <= RECYCLE_WASM_HEAP_BYTES;
+          settle(message.output, reusable);
+        } else if (message.type === "fatal" && message.id === id) {
+          settle(
+            { ...emptyOutput("executor_error", message.message), durationMs: elapsed() },
+            false,
+          );
+        }
+      };
+      const onError = (event: ErrorEvent) => {
+        settle({ ...emptyOutput("executor_error", event.message), durationMs: elapsed() }, false);
+      };
+      // Terminating the worker is the hard kill: it also stops a busy loop.
+      const onAbort = () => settle({ ...emptyOutput("killed"), durationMs: elapsed() }, false);
+      const watchdog = setTimeout(
+        () => settle({ ...emptyOutput("timeout"), exitCode: 124, durationMs: elapsed() }, false),
+        input.resources.wallClockMs + UNRESPONSIVE_GRACE_MS,
+      );
+
+      slot.worker.addEventListener("message", onMessage);
+      slot.worker.addEventListener("error", onError);
+      input.signal?.addEventListener("abort", onAbort, { once: true });
+      slot.worker.postMessage({
+        id,
+        job: {
+          source: input.source,
+          args: input.args,
+          configPayload: input.configPayload,
+          resources: input.resources,
+        },
+      } satisfies QuickJSWorkerRequest);
+    });
+  }
+}

package/src/scripts-runtime/executors/registry.ts

@@ -1,8 +1,10 @@
 import { NativeScriptExecutor } from "./native";
+import { QuickJSScriptExecutor } from "./quickjs";
 import type { ScriptExecutor } from "./types";
 
 const EXECUTORS: Record<string, () => ScriptExecutor> = {
   native: () => new NativeScriptExecutor(),
+  quickjs: () => new QuickJSScriptExecutor(),
 };
 
 export function getScriptExecutor(name = process.env.SCRIPT_EXECUTOR ?? "native"): ScriptExecutor {

package/src/scripts-runtime/executors/sourcemap.ts

@@ -0,0 +1,79 @@
+/**
+ * Minimal source map v3 reader for the quickjs executor. It maps a
+ * generated (line, column) back to the original source position so runtime
+ * errors point at the user's TypeScript, not at the bundled JavaScript.
+ *
+ * Lines and columns are 1-based on input and output, to match stack frames.
+ */
+
+type Segment = { genColumn: number; source: number; line: number; column: number };
+
+export type OriginalPosition = { source: string; line: number; column: number };
+
+const BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const BASE64_INDEX = new Map([...BASE64].map((char, index) => [char, index]));
+
+function decodeVlq(segment: string): number[] {
+  const values: number[] = [];
+  let value = 0;
+  let shift = 0;
+  for (const char of segment) {
+    const digit = BASE64_INDEX.get(char);
+    if (digit === undefined) throw new Error(`invalid source map VLQ character: ${char}`);
+    value += (digit & 31) << shift;
+    if (digit & 32) {
+      shift += 5;
+      continue;
+    }
+    const negative = value & 1;
+    value >>>= 1;
+    values.push(negative ? -value : value);
+    value = 0;
+    shift = 0;
+  }
+  return values;
+}
+
+export class SourceMapReader {
+  private readonly sources: string[];
+  private readonly lines: Segment[][];
+
+  constructor(map: { sources: string[]; mappings: string }) {
+    this.sources = map.sources;
+    this.lines = [];
+    let source = 0;
+    let line = 0;
+    let column = 0;
+    for (const generatedLine of map.mappings.split(";")) {
+      const segments: Segment[] = [];
+      let genColumn = 0;
+      for (const raw of generatedLine.split(",")) {
+        if (!raw) continue;
+        const fields = decodeVlq(raw);
+        genColumn += fields[0] ?? 0;
+        if (fields.length < 4) continue;
+        source += fields[1] ?? 0;
+        line += fields[2] ?? 0;
+        column += fields[3] ?? 0;
+        segments.push({ genColumn, source, line, column });
+      }
+      this.lines.push(segments);
+    }
+  }
+
+  /** Look up the closest mapping at or before (line, column) on that line. */
+  originalPositionFor(line: number, column: number): OriginalPosition | undefined {
+    const segments = this.lines[line - 1];
+    if (!segments || segments.length === 0) return undefined;
+    let match: Segment | undefined;
+    for (const segment of segments) {
+      if (segment.genColumn > column - 1) break;
+      match = segment;
+    }
+    match ??= segments[0];
+    if (!match) return undefined;
+    const source = this.sources[match.source];
+    if (source === undefined) return undefined;
+    return { source, line: match.line + 1, column: match.column + 1 };
+  }
+}

package/src/scripts-runtime/script-error-hints.ts

@@ -0,0 +1,14 @@
+// Matches runtime errors that look like a swapped/misused (args, ctx) signature,
+// e.g. destructuring `ctx.api`/`ctx.kv`/`ctx.fetchJson`/`ctx.log` off `undefined`/`null`
+// because the script read them off `args` instead.
+const CTX_UNDEFINED_ACCESS_RE = /cannot read propert(?:y|ies)(?: .*)? of (?:undefined|null)/i;
+const CTX_MEMBER_RE = /\b(api|kv|fetchJson|log)\b/i;
+const CTX_SIGNATURE_HINT =
+  "Hint: swarm scripts export default async function (args, ctx) — args comes first, ctx second.";
+
+/** Shared by every script executor so structured errors carry the same hint. */
+export function ctxSignatureHintFor(message: string): string | undefined {
+  return CTX_UNDEFINED_ACCESS_RE.test(message) && CTX_MEMBER_RE.test(message)
+    ? CTX_SIGNATURE_HINT
+    : undefined;
+}

package/src/server.ts

@@ -196,6 +196,7 @@ import {
   registerTriggerWorkflowTool,
   registerUpdateWorkflowTool,
 } from "./tools/workflows";
+import { parseEnabledTools } from "./utils/enabled-tools";
 import { resolveScriptsOnlyMode } from "./utils/scripts-only-mode";
 
 // Every known capability, including the ones disabled by default. Exported for
@@ -293,18 +294,75 @@ export function isScriptsOnlyMcp(): boolean {
   return resolveScriptsOnlyMode({ env: process.env.SCRIPTS_ONLY_MCP });
 }
 
+const loggedToolAllowlistWarnings = new Set<string>();
+
+function warnToolAllowlistOnce(message: string): void {
+  if (loggedToolAllowlistWarnings.has(message)) return;
+  loggedToolAllowlistWarnings.add(message);
+  console.warn(message);
+}
+
+/**
+ * SWARM_ENABLED_TOOLS: an optional explicit allowlist for the externally
+ * exposed MCP surface. Returns undefined (capability-driven surface) when the
+ * value is unset, blank, or invalid. Never logs the raw value.
+ */
+function resolveToolAllowlist(value: string | undefined): string[] | undefined {
+  if (value === undefined) return undefined;
+  try {
+    const tools = parseEnabledTools(value);
+    if (!tools) {
+      warnToolAllowlistOnce("[MCP] SWARM_ENABLED_TOOLS is set but lists no tools; ignoring it");
+    }
+    return tools;
+  } catch {
+    warnToolAllowlistOnce("[MCP] Invalid SWARM_ENABLED_TOOLS; ignoring it");
+    return undefined;
+  }
+}
+
+/** Drop every registered tool the allowlist does not name; warn on unknown names. */
+function applyToolAllowlist(server: McpServer, allowlist: readonly string[]): void {
+  const tools = (server as unknown as { _registeredTools: Record<string, { remove(): void }> })
+    ._registeredTools;
+  const allowed = new Set(allowlist);
+  for (const [name, tool] of Object.entries(tools)) {
+    if (!allowed.has(name)) tool.remove();
+  }
+  const unknown = allowlist.filter((name) => !Object.hasOwn(tools, name));
+  if (unknown.length > 0) {
+    warnToolAllowlistOnce(
+      `[MCP] SWARM_ENABLED_TOOLS names unknown tools, ignoring them: ${unknown.join(", ")}`,
+    );
+  }
+}
+
 export async function createServer(
-  opts: { scriptsOnly?: boolean; fullSurface?: boolean; preloadedTools?: readonly string[] } = {},
+  opts: {
+    scriptsOnly?: boolean;
+    fullSurface?: boolean;
+    preloadedTools?: readonly string[];
+    /** Raw SWARM_ENABLED_TOOLS value for this session; defaults to the env. */
+    enabledTools?: string;
+  } = {},
 ) {
   // Reload env
   await loadGlobalConfigsIntoEnv(true);
 
+  // The tool allowlist replaces CAPABILITIES and SCRIPTS_ONLY_MCP when set.
+  // Full-surface consumers (the scripts SDK bridge) ignore it.
+  const toolAllowlist =
+    opts.fullSurface === true
+      ? undefined
+      : resolveToolAllowlist(opts.enabledTools ?? process.env.SWARM_ENABLED_TOOLS);
+
   // Capability flags shape the externally exposed MCP tool list only. Internal
   // full-surface consumers (the scripts SDK bridge, drift-check tests) pass
   // fullSurface to register every tool group regardless of CAPABILITIES.
+  // An allowlist also registers every group, then prunes to the listed names.
   // This shadows the module-level hasCapability for the registrations below.
   const hasCapability = (cap: CAPABILITIES_T): boolean =>
-    opts.fullSurface === true || getCapabilities().has(cap);
+    opts.fullSurface === true || toolAllowlist !== undefined || getCapabilities().has(cap);
 
   // Initialize database with WAL mode
   // Uses DATABASE_PATH env var for Docker volume compatibility (WAL needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
@@ -355,7 +413,7 @@ export async function createServer(
   // Scripts-only surface (experimental code-mode): register just the script
   // catalog tools and stop. script-connections / script-apis stay out — they
   // are lead-only security admin and excluded from the scripts SDK too.
-  if (opts.scriptsOnly ?? isScriptsOnlyMcp()) {
+  if (toolAllowlist === undefined && (opts.scriptsOnly ?? isScriptsOnlyMcp())) {
     registerScriptSearchTool(server);
     registerScriptRunTool(server);
     registerScriptUpsertTool(server);
@@ -392,7 +450,9 @@ export async function createServer(
     registerResolveUserTool(server);
     registerManageUserTool(server); // self-guards with lead check
 
-    // Debug tools (self-guard with lead check)
+    // Debug tools. Neither has a lead check: both are open to every
+    // authenticated agent. db-query refuses credential tables and its results
+    // are scrubbed; get-oauth-access-token returns tokens by design.
     registerDbQueryTool(server);
     registerGetOauthAccessTokenTool(server);
 
@@ -628,5 +688,7 @@ export async function createServer(
     registerUpdateServiceStatusTool(server);
   }
 
+  if (toolAllowlist) applyToolAllowlist(server, toolAllowlist);
+
   return server;
 }