@nexusbloom/cli 0.3.4 → 0.9.0

package/src/pipelines.js

@@ -0,0 +1,76 @@
+/**
+ * pipelines.js — Named pipelines stored as plain files.
+ *
+ * Deliberately not a database: pipelines are small, shareable, diffable text,
+ * so they live in the user's config directory where git and rsync reach them.
+ */
+
+import fs from "fs";
+import path from "path";
+
+import { PIPELINES_DIR, ensurePipelinesDir } from "./paths.js";
+
+const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,63}$/;
+
+export function pipelinePath(name) {
+  // Require a string outright rather than coercing: `["ok"]` and `123` would
+  // otherwise pass the charset check by way of String(), so the guard would be
+  // a string check pretending to be a type check. Coercion is not exploitable
+  // here — the coerced value is what gets validated *and* what builds the path
+  // — but accepting a non-string here means a caller's type mistake surfaces as
+  // a confusingly-named file instead of an error.
+  if (typeof name !== "string" || !SAFE_NAME.test(name)) {
+    throw new Error(`Invalid pipeline name "${String(name)}". Use letters, digits, dots, dashes and underscores.`);
+  }
+  return path.join(PIPELINES_DIR, `${name}.json`);
+}
+
+/** Write a pipeline definition. Returns the file path. */
+export function savePipeline(name, definition) {
+  ensurePipelinesDir();
+  const file = pipelinePath(name);
+  const record = { name, ...definition, savedAt: new Date().toISOString() };
+  fs.writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf-8", mode: 0o600 });
+  return file;
+}
+
+export function loadPipeline(name) {
+  const file = pipelinePath(name);
+  if (!fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function listPipelines() {
+  if (!fs.existsSync(PIPELINES_DIR)) return [];
+  return fs
+    .readdirSync(PIPELINES_DIR)
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => f.replace(/\.json$/, ""))
+    // The directory is shared with anything the user drops there. A stray
+    // `.json` whose stem is not a legal name (a dotfile, a partial download)
+    // must be skipped, not allowed to make `nxb pipeline list` throw.
+    .filter((name) => {
+      try {
+        pipelinePath(name);
+        return true;
+      } catch {
+        return false;
+      }
+    })
+    .map((name) => {
+      const def = loadPipeline(name);
+      return { name, pipeline: def?.pipeline || "", steps: def?.steps?.length || 0, savedAt: def?.savedAt };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function deletePipeline(name) {
+  const file = pipelinePath(name);
+  if (!fs.existsSync(file)) return false;
+  fs.unlinkSync(file);
+  return true;
+}

package/src/run.js

@@ -14,10 +14,14 @@ import path from "path";
 import chalk from "chalk";
 import QRCode from "qrcode";
 
+import { execInSandbox } from "./sandbox.js";
+import { validateInput } from "./types.js";
+
 import {
   fetchTools,
   fetchToolSource,
   resolveToolSlug,
+  filterTools,
   configGet,
   API_BASE,
   readStdin,
@@ -30,18 +34,43 @@ import {
   promptInput,
   promptConfirm,
   promptNumber,
+  isInteractive,
+  PAGE_SIZE,
 } from "./ui.js";
 
+// ─── Telemetry ────────────────────────────────────────────────────────────────
+
+/**
+ * Fire-and-forget run counter. Opt out with `nxb config set telemetry false`
+ * or NEXUSBLOOM_TELEMETRY=false. Only the slug is ever sent — never the input
+ * payload, the API key, or the result.
+ */
+function trackRun(slug, source) {
+  const enabled = process.env.NEXUSBLOOM_TELEMETRY || configGet("telemetry");
+  if (String(enabled).toLowerCase() === "false") return;
+  const headers = { "Content-Type": "application/json" };
+  const apiKey = process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  // AbortSignal keeps the fire-and-forget request from holding the event
+  // loop open — an unbounded pending fetch delays process exit.
+  fetch(`${API_BASE}/api/track-run`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ slug, source }),
+    signal: AbortSignal.timeout(1500),
+  }).catch(() => {});
+}
+
 // ─── Remote execution ────────────────────────────────────────────────────────
 
-export async function runRemote(slug, body, { apiKey, jsonMode, slugResolved }) {
+export async function runRemote(slug, body, { apiKey, jsonMode, slugResolved, quiet } = {}) {
   const key = apiKey || process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
   if (!key) {
-    if (!jsonMode) console.log(chalk.dim("  No API key — falling back to local execution..."));
-    return runLocal(slug, body, { jsonMode, slugResolved });
+    if (!quiet) log(chalk.dim("  No API key — falling back to local execution..."));
+    return runLocal(slug, body, { jsonMode, slugResolved, quiet });
   }
 
-  if (!jsonMode) console.log(chalk.dim(`  Running ${slug}...`));
+  if (!quiet) log(chalk.dim(`  Running ${slug} remotely...`));
 
   try {
     const res = await fetch(`${API_BASE}/api/run/${slug}`, {
@@ -51,74 +80,80 @@ export async function runRemote(slug, body, { apiKey, jsonMode, slugResolved })
     });
 
     if (!res.ok && !res.headers.get("content-type")?.includes("json")) {
-      if (!jsonMode) console.log(chalk.dim("  API not deployed — falling back to local"));
-      return runLocal(slug, body, { jsonMode, slugResolved });
+      if (!quiet) log(chalk.dim("  API not deployed — falling back to local"));
+      return runLocal(slug, body, { jsonMode, slugResolved, quiet });
     }
 
     const data = await res.json();
 
-    if (data.success) {
-      if (!jsonMode) console.log(chalk.green(`  ✓ ${slug} completed`));
-      if (data.data && typeof data.data === "object" && data.data.svg) {
-        await renderQRCode(body.data || body.text || JSON.stringify(body), slug);
-      }
-      if (jsonMode) return console.log(JSON.stringify({ success: true, data: data.data }, null, 2));
-      console.log(chalk.green("\n  Result:"));
-      console.log(`  ${JSON.stringify(data.data, null, 2)}`);
-      return;
+    if (!data.success) {
+      return reportError(jsonMode, data.error || "Unknown error");
     }
 
-    if (!jsonMode) console.log(chalk.red(`  ✗ ${slug} failed`));
-    if (jsonMode) return console.log(JSON.stringify({ success: false, error: data.error || "Unknown error" }, null, 2));
-    console.error(chalk.red(`\n  Error: ${data.error || "Unknown error"}`));
-    process.exitCode = 1;
-  } catch (err) {
-    if (!jsonMode) console.log(chalk.dim("  API unreachable — falling back to local"));
-    return runLocal(slug, body, { jsonMode, slugResolved });
+    const result = data.data;
+    if (!quiet) log(chalk.green(`  ✓ ${slug} completed`));
+    if (result && typeof result === "object" && result.svg) {
+      await renderQRCode(result.data || result.text || JSON.stringify(result), slug);
+    }
+
+    trackRun(slug, "remote");
+
+    if (jsonMode) {
+      console.log(JSON.stringify({ success: true, data: result }, null, 2));
+    } else {
+      log(chalk.green("\n  Result:"));
+      log(`  ${JSON.stringify(result, null, 2)}`);
+    }
+    return { ok: true, result };
+  } catch {
+    if (!quiet) log(chalk.dim("  API unreachable — falling back to local"));
+    return runLocal(slug, body, { jsonMode, slugResolved, quiet });
   }
 }
 
 // ─── Local execution ────────────────────────────────────────────────────────
 
-export async function runLocal(slug, input, { jsonMode, slugResolved, source: src } = {}) {
+export async function runLocal(slug, input, { jsonMode, slugResolved, quiet } = {}) {
   const toolInfo = await fetchToolSource(slug);
   if (!toolInfo) {
-    if (jsonMode) return console.log(JSON.stringify({ error: `Tool "${slug}" not found.` }));
-    console.error(chalk.red(`Tool "${slug}" not found. Set NEXUSBLOOM_SUPABASE_ANON_KEY or deploy the API.`));
-    process.exitCode = 1;
-    return;
+    return reportError(jsonMode, `Tool "${slug}" not found. Run \`nxb search ${slug}\` to see available tools.`);
   }
 
   const { manifest, coreLogicSource } = toolInfo;
+  // Where the code came from: "local" | "cache" | "api" | "supabase".
+  const src = toolInfo.source;
+
   if (!coreLogicSource) {
-    if (jsonMode)
-      return console.log(JSON.stringify({ error: "No v2 source available for local execution." }));
-    console.error(chalk.yellow("No v2 source available for local execution. Set NEXUSBLOOM_SUPABASE_ANON_KEY or deploy the API."));
-    process.exitCode = 1;
-    return;
+    return reportError(
+      jsonMode,
+      `No runnable source published for "${slug}" — try \`nxb run ${slug}\` without --local.`
+    );
   }
 
-  if (!jsonMode) console.log(chalk.dim(`  Using ${slugResolved ? "local" : src || "cached"} tool: ${slug}`));
-
-  // Strip imports/exports, wrap in IIFE that returns coreLogic
-  const cleanSource = coreLogicSource
-    .replace(/^import\s+.*?;?\s*$/gm, "")
-    .replace(/^export\s+/gm, "");
-  const wrappedSource = `(function() {\n${cleanSource}\nreturn coreLogic;\n})()`;
-  const coreLogicFn = new Function("return " + wrappedSource)();
-  const isAsync = /export\s+async\s+function\s+coreLogic/.test(coreLogicSource);
+  // All human-facing output goes to stderr so `--json` and `transform` piping
+  // get clean stdout.
+  if (!quiet) {
+    log(`  Using ${slugResolved ? "local" : src || "cached"} tool: ${slug}`);
+    if (src && src !== "local") {
+      log(
+        chalk.yellow(
+          `  ⚠ About to run ${src === "cache" ? "previously downloaded" : "downloaded"} code for "${slug}" on this machine.`
+        )
+      );
+    }
+  }
 
   const schema = manifest.input_schema || {};
   const required = schema.required || [];
   const missing = required.filter((k) => input[k] === undefined || input[k] === null);
   if (missing.length > 0) {
-    if (jsonMode) return console.log(JSON.stringify({ error: `Missing required fields: ${missing.join(", ")}` }));
-    console.error(chalk.red(`Missing required fields: ${missing.join(", ")}`));
-    process.exitCode = 1;
-    return;
+    const message = `Missing required fields: ${missing.join(", ")}`;
+    // A quiet caller reports this itself; doing it here too would print the
+    // identical line twice in a row.
+    if (quiet) return { ok: false, error: message };
+    return reportError(jsonMode, message);
   }
 
-  // Apply defaults
   if (schema.properties) {
     for (const [key, prop] of Object.entries(schema.properties)) {
       if (input[key] === undefined && prop.default !== undefined) {
@@ -127,36 +162,73 @@ export async function runLocal(slug, input, { jsonMode, slugResolved, source: sr
     }
   }
 
+  // Type-check against the declared schema before spending a process on it.
+  const typeProblems = validateInput(input, schema);
+  if (typeProblems.length) {
+    const detail = typeProblems
+      .map((p) => `${p.field}: ${p.error}${p.suggestion ? ` (${p.suggestion})` : ""}`)
+      .join("; ");
+    return reportError(jsonMode, `Invalid input for "${slug}" — ${detail}`);
+  }
+
   const timeoutMs = manifest.timeout_ms || 5000;
-  let result;
+  if (!quiet) log(chalk.dim(`  Executing ${slug} in sandbox (${timeoutMs}ms budget)...`));
 
-  try {
-    if (!jsonMode) console.log(chalk.dim(`  Executing ${slug} (local)...`));
-    if (isAsync) {
-      result = await Promise.race([
-        coreLogicFn(input),
-        new Promise((_, reject) => setTimeout(() => reject(new Error(`Timed out after ${timeoutMs}ms`)), timeoutMs)),
-      ]);
+  // Execution happens in a child process: a tool that loops forever, allocates
+  // without bound, or calls process.exit() cannot take the CLI with it.
+  const res = await execInSandbox({ source: coreLogicSource, input, timeoutMs });
+
+  if (!res.ok) {
+    return reportError(jsonMode, `Execution failed for "${slug}": ${res.error}`);
+  }
+
+  if (!quiet) log(chalk.green(`  ✓ ${slug} completed`));
+  trackRun(slug, "cli");
+
+  // `quiet` means the caller renders the result itself. `transform` relies on
+  // this: it owns stdout, because its whole purpose is to be piped. Printing
+  // here as well would put the payload on stderr and stdout both, and a
+  // `transform | jq` would see it twice.
+  if (!quiet) {
+    if (jsonMode) {
+      console.log(JSON.stringify({ success: true, data: res.result }, null, 2));
     } else {
-      result = coreLogicFn(input);
+      log(chalk.green("\n  Result (local):"));
+      log(`  ${JSON.stringify(res.result, null, 2)}`);
     }
-    if (!jsonMode) console.log(chalk.green(`  ✓ ${slug} completed`));
-
-    // Fire-and-forget telemetry
-    const apiKey = process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
-    const trackHeaders = { "Content-Type": "application/json" };
-    if (apiKey) trackHeaders["Authorization"] = `Bearer ${apiKey}`;
-    fetch(`${API_BASE}/api/track-run`, { method: "POST", headers: trackHeaders, body: JSON.stringify({ slug, source: "cli" }) }).catch(() => {});
-
-    if (jsonMode) return console.log(JSON.stringify({ success: true, data: result }, null, 2));
-    console.log(chalk.green("\n  Result (local):"));
-    console.log(`  ${JSON.stringify(result, null, 2)}`);
-  } catch (err) {
-    if (!jsonMode) console.log(chalk.red(`  ✗ Execution error`));
-    if (jsonMode) return console.log(JSON.stringify({ error: err.message }));
-    console.error(chalk.red(`\n  Local execution error: ${err.message}`));
-    process.exitCode = 1;
   }
+  return { ok: true, result: res.result, durationMs: res.durationMs };
+}
+
+/**
+ * True when an error is inquirer's "the user pressed Ctrl+C" signal.
+ *
+ * @inquirer/core rejects with an `ExitPromptError` from inside a readline
+ * `SIGINT` handler. Because the CLI parses with `program.parse()` — which does
+ * not await the async action handlers — that rejection used to escape as an
+ * unhandled rejection and dump an inquirer stack trace over the user's
+ * terminal. The class is not exported from `@inquirer/prompts`, and importing
+ * `@inquirer/core` directly would tie us to a transitive dependency, so it is
+ * matched by name.
+ */
+export function isExitPromptError(err) {
+  return Boolean(err) && err.name === "ExitPromptError";
+}
+
+/** Print an error on stderr (or as JSON) and set a non-zero exit code. */
+export function reportError(jsonMode, message) {
+  if (jsonMode) {
+    console.log(JSON.stringify({ success: false, error: message }));
+  } else {
+    console.error(chalk.red(`  ✗ ${message}`));
+  }
+  process.exitCode = 1;
+  return { ok: false, error: message };
+}
+
+/** Progress output belongs on stderr so stdout stays machine-readable. */
+function log(line) {
+  console.error(line);
 }
 
 // ─── Input building ─────────────────────────────────────────────────────────
@@ -221,9 +293,9 @@ export async function buildInputBody(opts, args) {
 async function renderQRCode(data, slug) {
   try {
     const qr = await QRCode.toString(data, { type: "terminal", small: true });
-    console.log(chalk.cyan("\n  QR Code:"));
-    console.log(qr);
-    console.log(chalk.dim(`  Data: ${data.slice(0, 80)}${data.length > 80 ? "..." : ""}`));
+    console.error(chalk.cyan("\n  QR Code:"));
+    console.error(qr);
+    console.error(chalk.dim(`  Data: ${data.slice(0, 80)}${data.length > 80 ? "..." : ""}`));
   } catch {
     /* silently skip */
   }
@@ -234,20 +306,72 @@ async function renderQRCode(data, slug) {
 /**
  * `nxb run` with no slug: interactively select a tool and its inputs,
  * then auto-build & execute the exact command.
+ *
+ * With `-s/--search`, the list is filtered first (search matches slug, name,
+ * description, category and abbreviation). Without a TTY there is nothing to
+ * prompt with, so the tool list is printed as a plain searchable dump and the
+ * command exits — it never hangs a pipe or a CI job.
  */
 export async function runInteractive(opts = {}) {
-  const { json: jsonMode } = opts;
-  const tools = await fetchTools({ offline: true });
+  const { json: jsonMode, search } = opts;
+  const tools = await fetchTools({ offline: false });
 
   if (!tools || tools.length === 0) {
-    console.log(chalk.yellow("  No tools available. Set NEXUSBLOOM_SUPABASE_ANON_KEY or deploy the API."));
+    console.log(chalk.yellow("  No tools available. Check your connection, or run `nxb cache list`."));
+    return;
+  }
+
+  // ── Non-interactive: print the (optionally filtered) list and stop ──
+  if (!isInteractive()) {
+    const filtered = search ? filterTools(tools, search) : tools;
+
+    if (jsonMode) {
+      console.log(JSON.stringify({ tools: filtered, ...(search ? { query: search } : {}) }, null, 2));
+      return;
+    }
+
+    if (filtered.length === 0) {
+      console.log(chalk.yellow(`  No tools matching "${search}".`));
+      return;
+    }
+
+    console.log(chalk.bold(`\n  Available tools  (${filtered.length})${search ? ` matching "${search}"` : ""}\n`));
+    for (const t of filtered) {
+      const desc = (t.short_description || t.description || "").slice(0, 60);
+      console.log(`  ${(t.icon || "🔧")}  ${chalk.cyan((t.slug || "").padEnd(30))} ${chalk.dim(desc)}`);
+    }
+    console.log(chalk.dim(`\n  Run a tool with:  nxb run <slug> [key=value ...]`));
+    console.log(chalk.dim(`  Narrow the list:  nxb run -s <query>   ·   nxb search <query>`));
+    console.log();
     return;
   }
 
-  renderHeader("NexusBloom — Interactive Runner", { subtitle: "Select a tool to run" });
+  // ── Interactive: optional search, then the tool picker ──
+  let pool = tools;
+  let query = search;
+
+  // Long catalogue + no explicit query → offer search before the picker,
+  // since scrolling a plain select through hundreds of tools is unusable.
+  if (!query && tools.length > PAGE_SIZE) {
+    const answer = await promptInput(
+      chalk.cyan(`  Search ${tools.length} tools (blank to browse):`)
+    );
+    if (answer && answer.trim()) query = answer.trim();
+  }
+
+  if (query) {
+    pool = filterTools(tools, query);
+    if (pool.length === 0) {
+      console.log(chalk.yellow(`  No tools matching "${query}".`));
+      console.log(chalk.dim("  Try a broader query, or run `nxb list` to browse everything."));
+      return;
+    }
+    renderHeader("Search Results", { subtitle: `${pool.length} matching "${query}"` });
+  } else {
+    renderHeader("NexusBloom — Interactive Runner", { subtitle: "Select a tool to run" });
+  }
 
-  // 1. Select a tool
-  const choices = tools.map((t) => ({
+  const choices = pool.map((t) => ({
     name: `${t.icon || "🔧"}  ${t.name || t.slug}  ${typeBadge(t)}`,
     value: t,
     description: t.short_description || t.description || "",
@@ -256,15 +380,30 @@ export async function runInteractive(opts = {}) {
   const selected = await promptSelect("Choose a tool:", choices, { pageSize: 15 });
   if (!selected) return;
 
-  const slug = selected.slug;
-  const resolved = await resolveToolSlug(slug, tools);
+  return await runInteractiveFor(selected.slug, { ...opts, json: jsonMode, tools });
+}
+
+/**
+ * Interactive configuration for a slug that is already known.
+ *
+ * Shared by the tool picker above and by `nxb run <slug>` with no input of any
+ * kind: a bare `nxb run text-statistics` has nothing to send, so asking for the
+ * fields is the useful behaviour rather than failing schema validation with
+ * "Missing required fields: text".
+ *
+ * Returns the executed slug, or undefined when the user backs out or the tool
+ * has no schema to configure.
+ */
+export async function runInteractiveFor(slug, opts = {}) {
+  const { json: jsonMode, tools: knownTools } = opts;
+  const resolved = await resolveToolSlug(slug, knownTools);
 
   // 2. Fetch manifest / schema
   const toolInfo = await fetchToolSource(resolved);
   if (!toolInfo?.manifest) {
     console.log(chalk.yellow(`  No schema available for "${resolved}". Falling back to raw input.`));
-    await runCommand(resolved, {}, { ...opts, jsonMode });
-    return;
+    await runCommand(resolved, {}, { ...opts, json: jsonMode });
+    return resolved;
   }
 
   const { manifest } = toolInfo;
@@ -278,12 +417,7 @@ export async function runInteractive(opts = {}) {
   const required = schema.required || [];
 
   for (const [key, prop] of Object.entries(props)) {
-    const req = required.includes(key);
-    const hint = prop.description || "";
-    const suffix = req ? chalk.red(" *required") : chalk.dim(" (optional)");
-    const label = `${key}${suffix}${hint ? chalk.dim(` — ${hint}`) : ""}`;
-
-    const val = await promptField(key, prop);
+    const val = await promptField(key, prop, required.includes(key));
     if (val !== undefined) body[key] = val;
   }
 
@@ -315,42 +449,43 @@ export async function runInteractive(opts = {}) {
   if (!runIt) {
     console.log(chalk.dim("  Command copied to clipboard (if available):"));
     console.log(chalk.gray(`  ${fullCommand}`));
-    return;
+    return resolved;
   }
 
-  // Execute directly via the same path
-  await runCommand(resolved, body, { ...opts, jsonMode, resolved });
+  await runCommand(resolved, body, { ...opts, json: jsonMode, resolved });
+  return resolved;
 }
 
 /** Prompt for a single schema field based on its type. */
-async function promptField(key, prop) {
+async function promptField(key, prop, required = false) {
   const { type, enum: enumVals, default: def } = prop;
+  const label = `${key}${required ? chalk.red(" *required") : chalk.dim(" (optional)")}`;
 
   // Enum → select
   if (enumVals && Array.isArray(enumVals) && enumVals.length > 0) {
     const choices = enumVals.map((v) => ({
       name: String(v),
       value: v,
-      ...(v === def && { checked: true }),
+      ...(v === def ? { checked: true } : {}),
     }));
     if (def !== undefined) choices.unshift({ name: chalk.gray("(default)"), value: def });
-    return promptSelect(`${key}:`, choices);
+    return promptSelect(`${label}:`, choices);
   }
 
   // Number / integer
   if (type === "number" || type === "integer") {
-    return promptNumber(`${key}:`, { min: prop.minimum, max: prop.maximum, default: def });
+    return promptNumber(`${label}:`, { min: prop.minimum, max: prop.maximum, default: def });
   }
 
   // Boolean
   if (type === "boolean") {
-    return promptConfirm(`${key}:`, { default: def ?? true });
+    return promptConfirm(`${label}:`, { default: def ?? true });
   }
 
   // Object / array → JSON string input
   if (type === "object" || type === "array") {
-    const defaultStr = def !== undefined ? JSON.stringify(def) : [];
-    const raw = await promptInput(`${key}: (JSON)`, { defaultValue: defaultStr });
+    const defaultStr = def !== undefined ? JSON.stringify(def) : "";
+    const raw = await promptInput(`${label}: (JSON)`, { defaultValue: defaultStr });
     if (!raw) return def;
     try {
       return JSON.parse(raw);
@@ -361,7 +496,7 @@ async function promptField(key, prop) {
   }
 
   // Default: string input
-  return promptInput(`${key}:`, { defaultValue: def });
+  return promptInput(`${label}:`, { defaultValue: def });
 }
 
 /** Execute a resolved slug+body, choosing local vs remote. */
@@ -370,8 +505,7 @@ async function runCommand(slug, body, opts = {}) {
   const apiKey = opts.key || process.env.NEXUSBLOOM_API_KEY || configGet("apiKey") || configGet("key");
 
   if (local || !apiKey) {
-    await runLocal(slug, body, { jsonMode, slugResolved: resolved });
-    return;
+    return runLocal(slug, body, { jsonMode, slugResolved: resolved });
   }
-  await runRemote(slug, body, { apiKey, jsonMode, slugResolved: resolved });
+  return runRemote(slug, body, { apiKey, jsonMode, slugResolved: resolved });
 }

package/src/runner.js

@@ -0,0 +1,89 @@
+/**
+ * runner.js — Sandbox child process for a single tool execution.
+ *
+ * Never run directly. `sandbox.js` forks this file, sends one `run` message,
+ * and hard-kills the process when the timeout expires.
+ *
+ * Living in a separate process is what makes a hostile tool survivable:
+ *   - an infinite loop can be killed (it cannot be interrupted in-process)
+ *   - an OOM kills only this child, not the CLI
+ *   - a crash or process.exit() in the tool does not take the CLI down
+ *
+ * This is isolation, not a security sandbox: the child runs with the same
+ * user and filesystem permissions as the CLI. Treat downloaded tool source as
+ * trusted-but-unverified, and prefer remote execution for untrusted tools.
+ */
+
+import { compileCoreLogic } from "./compile.js";
+
+/** Serialise a value for IPC, tolerating cycles and non-JSON values. */
+function safe(value, depth = 0) {
+  if (value === undefined) return { __undefined: true };
+  if (value === null) return null;
+  const t = typeof value;
+  if (t === "number") {
+    if (Number.isNaN(value)) return { __nan: true };
+    if (!Number.isFinite(value)) return { __inf: value > 0 ? 1 : -1 };
+    return value;
+  }
+  if (t === "string" || t === "boolean") return value;
+  if (t === "bigint") return { __bigint: value.toString() };
+  if (t === "function") return { __function: true };
+  if (t === "symbol") return { __symbol: String(value) };
+  if (depth > 12) return null;
+  if (Array.isArray(value)) return value.map((v) => safe(v, depth + 1));
+  if (value instanceof Date) return { __date: value.toISOString() };
+  if (value instanceof Error) return { __error: value.message };
+  if (typeof value.toJSON === "function") {
+    try {
+      return safe(value.toJSON(), depth + 1);
+    } catch {
+      /* fall through to plain object handling */
+    }
+  }
+  if (t === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[k] = safe(v, depth + 1);
+    }
+    return out;
+  }
+  return String(value);
+}
+
+function reply(message) {
+  try {
+    process.send?.(message);
+  } catch {
+    /* parent went away — nothing useful to do */
+  }
+}
+
+process.on("message", async (msg) => {
+  if (!msg || msg.type !== "run") return;
+
+  try {
+    const coreLogic = compileCoreLogic(msg.source);
+    const result = await coreLogic(msg.input);
+    reply({ type: "result", ok: true, result: safe(result) });
+  } catch (err) {
+    reply({ type: "result", ok: false, error: err?.message || String(err) });
+  } finally {
+    // Exit explicitly: a tool may have left timers/handles open, and we do
+    // not want to wait for them — the parent's timeout is the real deadline.
+    process.exit(0);
+  }
+});
+
+// If the parent dies, do not linger.
+process.on("disconnect", () => process.exit(0));
+
+// An unhandled rejection or fatal error must still report back, not vanish.
+process.on("uncaughtException", (err) => {
+  reply({ type: "result", ok: false, error: err?.message || String(err) });
+  process.exit(0);
+});
+process.on("unhandledRejection", (err) => {
+  reply({ type: "result", ok: false, error: err?.message || String(err) });
+  process.exit(0);
+});