pi-supernova 0.3.2 → 0.5.0

package/src/runtime/parallel.js

@@ -1,21 +1,32 @@
 import { isFunction } from "../shared/decode.js";
 
 const READ_ONLY_TOOLS = new Set(["read", "grep", "glob", "find", "ls", "snap", "evidence", "surface", "asgrep_search", "asgrep_status", "ast_grep", "web_search"]);
+
 const READ_ONLY_LSP = new Set(["definition", "references", "hover", "symbols", "diagnostics", "implementation", "type_definition", "incoming_calls", "outgoing_calls"]);
 
 export function isMutatingTool(name, config = {}, args = {}, definition) {
   if ((config.mutatingTools ?? []).includes(name)) return true;
+
   if ((config.mutatingPrefixes ?? []).some(prefix => prefix && name.startsWith(prefix))) return true;
+
   if (definition?.annotations?.readOnlyHint === true) return false;
+
   if (name === "lsp") {
     const action = args.action ?? args.operation;
+
     if (READ_ONLY_LSP.has(action)) return false;
+
     if (["rename", "rename_file"].includes(action)) return args.apply !== false;
+
     if (action === "code_actions") return args.apply === true;
+
     return true;
   }
+
   if (name === "todo") return args.op !== "view";
+
   if (name === "hub") return !["list", "ps", "logs", "describe"].includes(args.op);
+
   return !READ_ONLY_TOOLS.has(name);
 }
 
@@ -30,22 +41,28 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
     try {
       while (queue.length) {
         const first = queue.shift();
+
         if (first.cancelled) continue;
         const wave = [first];
+
         if (first.name === "read") {
           while (wave.length < maxParallelReads && queue[0]?.name === "read") {
             const next = queue.shift();
+
             if (!next.cancelled) wave.push(next);
           }
+
           stats.readWaves++;
           stats.peakParallelReads = Math.max(stats.peakParallelReads, wave.length);
         }
+
         // Settle each promise separately: one failed read must not discard its
         // siblings or release a write barrier while other reads are still active.
         await Promise.all(wave.map(async job => {
           if (job.cancelled) return;
           job.started = true;
           job.signal?.removeEventListener("abort", job.abort);
+
           try {
             job.signal?.throwIfAborted();
             const result = await job.run();
@@ -63,8 +80,10 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
       if (!["read", "edit", "write", "bash"].includes(name) || !isFunction(run)) {
         return Promise.reject(new Error("scheduler requires a native tool and an executor"));
       }
+
       if (signal?.aborted) return Promise.reject(signal.reason ?? new Error("aborted"));
       stats.calls++;
+
       return new Promise((resolve, reject) => {
         const job = { name, run, signal, resolve, reject, started: false, cancelled: false };
         job.abort = () => {
@@ -73,8 +92,10 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
           signal.removeEventListener("abort", job.abort);
           reject(signal.reason ?? new Error("aborted"));
         };
+
         signal?.addEventListener("abort", job.abort, { once: true });
         queue.push(job);
+
         if (!draining) {
           draining = true;
           // Pi submits sibling tools in the same turn without model-side code.
@@ -88,25 +109,34 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
 
 function requireArray(value, name) {
   if (!Array.isArray(value)) throw new TypeError(name + " requires an array");
+
   return value;
 }
 
 export async function runParallelWave(thunks, meta, options = {}) {
   const list = requireArray(thunks, "parallel wave");
+
   if (list.some(item => !isFunction(item))) throw new TypeError("parallel wave requires functions");
+
   if (!list.length) return { results: [], mode: "serial", reason: "empty" };
   const { mode = "auto", config = {} } = options;
   const names = meta?.names ?? [];
   const mutating = names.length !== list.length || names.some((name, i) => isMutatingTool(name, config, meta?.calls?.[i]?.args, meta?.definitions?.[i]));
+
   if (!mutating && (mode === "parallel" || (mode === "auto" && list.length > 1))) {
     // Do not finish a wave while its already-started host calls are still running.
     const settled = await Promise.allSettled(list.map(thunk => Promise.resolve().then(thunk)));
     const failure = settled.find(item => item.status === "rejected");
+
     if (failure) throw failure.reason;
+
     return { results: settled.map(item => item.value), mode: "parallel", reason: "independent-reads" };
   }
+
   const results = [];
+
   for (const thunk of list) results.push(await thunk());
+
   return { results, mode: "serial", reason: mutating ? "mutating" : "single-or-forced" };
 }
 
@@ -116,7 +146,10 @@ export async function parallel(items) {
 
 export async function pipeline(items, ...stages) {
   let current = requireArray(items, "pipeline");
+
   if (stages.some(stage => !isFunction(stage))) throw new TypeError("pipeline stages must be functions");
+
   for (const stage of stages) current = await Promise.all(current.map(item => stage(item)));
+
   return current;
 }

package/src/runtime/program-batch.js

@@ -0,0 +1,112 @@
+import { isObject, isString } from "../shared/decode.js";
+import { truncateChars } from "../output/format.js";
+
+const textOf = result => result.content.filter(block => block.type === "text").map(block => block.text).join("\n");
+
+const mutationTotals = results => results.reduce((total, result) => {
+  const m = result.details?.mutations;
+
+  for (const key of ["committed","rolledBack","external","pendingCommits"]) total[key] += m?.[key] ?? 0;
+  total.recoveryFailed ||= !m || m.recoveryFailed === true;
+
+  return total;
+}, {committed:0,rolledBack:0,external:0,pendingCommits:0,recoveryFailed:false});
+
+export function programBatchText(results, total, stopped = "") {
+  const m = mutationTotals(results);
+
+  return (stopped ? "error: programs stopped: " + stopped : "ok: programs") + " " + results.length + "/" + total +
+    (m.recoveryFailed || m.pendingCommits ? "; filesystem outcome uncertain: inspect disk" : "") + "\nresults (UTF-16 lengths):\n" + results.map((result,i) => {
+      const text = textOf(result);
+
+      return "[" + i + "] " + text.length + "\n" + text + "\n";
+    }).join("");
+}
+
+function batchInputs(params, config) {
+  if (["code","file","data"].some(key => params[key] !== undefined)) throw new Error("programs cannot combine with top-level code, file or data; no programs ran");
+
+  if (!Array.isArray(params.programs) || !params.programs.length || params.programs.length > 32) throw new Error("programs requires 1..32 entries; no programs ran");
+
+  for (const p of params.programs) {
+    if (!isObject(p) || Array.isArray(p) || Object.keys(p).some(key => !["code","file","data"].includes(key)) ||
+        ((p.code === undefined) === (p.file === undefined)) || !isString(p.code ?? p.file) || !(p.code ?? p.file).trim()) {
+      throw new Error("each program requires code OR file, with optional data; no nested batches or per-entry timeouts; no programs ran");
+    }
+  }
+
+  let encoded;
+
+  try { encoded = JSON.stringify(params.programs); } catch { throw new Error("programs must be JSON-serializable; no programs ran"); }
+
+  if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget; no programs ran");
+
+  return JSON.parse(encoded);
+}
+
+/** Explicit known continuations, not inferred plans, retries, or a shared heap. */
+export async function runProgramBatch(id, params, signal, onUpdate, ctx, config, execute) {
+  const programs = batchInputs(params,config);
+  const started = performance.now();
+  const timeout = Number.isInteger(params.timeoutMs) ? params.timeoutMs : config.timeoutMs;
+  const deadline = started + timeout;
+  const controller = new AbortController();
+  const combined = signal ? AbortSignal.any([signal,controller.signal]) : controller.signal;
+  const timer = setTimeout(() => controller.abort(),Math.min(timeout,2147483647));
+  const budget = {calls:0,logLines:0};
+  const results = [], images = [], imageLabels = [], trace = [];
+  const imageTextChars = () => imageLabels.reduce((chars,label)=>chars+label.length+1,0);
+  let imageBytes = 0, stopped = "";
+
+  try {
+    for (const [i, program] of programs.entries()) {
+      if (combined.aborted || performance.now() >= deadline) { stopped = "deadline or cancellation; remaining programs did not run"; break; }
+
+      let result;
+
+      try {
+        result = await execute(id + ":" + i,{...program,timeoutMs:Math.max(1,Math.ceil(deadline-performance.now()))},combined,update => {
+          try { onUpdate?.({...update,details:{...update.details,trace:[...trace,...(update.details?.trace ?? [])]}}); } catch {}
+        },ctx,budget);
+      } catch (error) {
+        result = error.supernovaResult ?? {content:[{type:"text",text:String(error.message ?? error)}],details:{ok:false,error:String(error.message ?? error)}};
+      }
+
+      results.push(result);
+      trace.push(...(result.details?.trace ?? []));
+      let image = 0;
+
+      for (const block of result.content) if (block.type === "image") {
+        imageBytes += Buffer.byteLength(block.data,"base64");
+
+        if (images.length >= 16 || imageBytes > 20*1024*1024) { stopped = "batch image budget exceeded; remaining programs did not run"; break; }
+
+        images.push(block);
+        imageLabels.push("program " + (i+1) + " image " + (++image));
+      }
+
+      if (result.details?.ok === false) stopped = "program " + (i+1) + " failed; remaining programs did not run; earlier commits remain";
+      const text = programBatchText(results,programs.length,stopped);
+
+      if (text.length + imageTextChars() > config.maxReturnChars || result.details?.returnTruncated) stopped ||= "batch output budget exceeded; remaining programs did not run; earlier commits remain";
+
+      if (result.details?.logTruncated) stopped ||= "batch log budget exceeded; remaining programs did not run; earlier commits remain";
+
+      if (combined.aborted || performance.now() >= deadline) stopped ||= "batch deadline or cancellation; earlier commits remain";
+
+      if (stopped) break;
+    }
+  } finally { clearTimeout(timer); controller.abort(); }
+
+  const bounded = truncateChars(programBatchText(results,programs.length,stopped),Math.max(0,config.maxReturnChars-imageTextChars()),"batch output");
+  const content = [{type:"text",text:bounded.text}];
+  images.forEach((image,i) => content.push({type:"text",text:imageLabels[i]},image));
+
+  // Return a typed stop report instead of throwing away earlier results/images.
+  // Single-program errors retain their existing throwing behavior.
+  return {content,isError:!!stopped,details:{ok:!stopped,error:stopped || undefined,wallMs:Math.round(performance.now()-started),
+    programs:results,attempted:results.length,total:programs.length,stopped,
+    result:bounded.truncated ? bounded.text : results.map(result=>result.details?.result),
+    returnTruncated:bounded.truncated || results.some(result=>result.details?.returnTruncated),
+    logTruncated:results.some(result=>result.details?.logTruncated),logs:results.flatMap(result=>result.details?.logs ?? []),trace,mutations:mutationTotals(results)}};
+}

package/src/runtime/program-file.js

@@ -0,0 +1,40 @@
+import * as fs from "node:fs/promises";
+import { resolveWorkspacePath } from "../fs/workspace.js";
+
+/** Explicit source reuse, never a cached program or a persistent guest heap. */
+export async function readProgramFile(file, cwd, maxChars, signal) {
+  signal?.throwIfAborted();
+  const target = await resolveWorkspacePath(cwd, file, "program file", false, true);
+  // A FIFO must fail without waiting for a writer or occupying an I/O worker.
+  const handle = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+  try {
+    signal?.throwIfAborted();
+    const stat = await handle.stat();
+
+    if (!stat.isFile()) throw new Error("program file requires a regular file");
+    // Every UTF-16 unit needs at most three UTF-8 bytes. Also check streamed size:
+    // another editor can grow the file after stat. No prefix-only execution.
+    const maxBytes = maxChars * 3;
+    const tooLarge = () => new Error("code exceeds " + maxChars + " characters; split the program");
+
+    if (stat.size > maxBytes) throw tooLarge();
+    const chunks = [];
+    let bytes = 0;
+
+    for await (const chunk of handle.createReadStream({ end: maxBytes, autoClose: false, signal })) {
+      bytes += chunk.length;
+
+      if (bytes > maxBytes) throw tooLarge();
+      chunks.push(chunk);
+    }
+
+    signal?.throwIfAborted();
+    // Do not silently replace invalid bytes in executable source. Preserve BOMs.
+    const code = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Buffer.concat(chunks));
+
+    if (code.length > maxChars) throw tooLarge();
+
+    return code;
+  } finally { await handle.close(); }
+}

package/src/runtime/reference.js

@@ -0,0 +1,18 @@
+// Complete model-facing API reference; kept in every request, not moved into history.
+export const REFERENCE = `JavaScript async body or arrow with read, write, edit, bash. Strings stay raw. Exactly one of code or file; file rereads that program (same limits, cwd, fresh guest). Caps are UTF-16. Put Markdown/scripts/argv in data.
+
+read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries
+read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP)
+read({path,json:".field"}) → parsed JSON; .items[0:3], quoted keys, selector arrays, or true; 16 MiB cap; no jq
+read("agent://id?q=.answer") → JSON field from session artifacts
+read("symbol or question") → same view as resolve:true
+read({query,resolve:true}) → {status,path,line,lines,text,complete,nextOffset?}
+read(path,{about}) → matching windows; read({query,evidence:true}) → ranked evidence; read({path,outline:true}) → declarations
+write(path, text) → replace; write({path,content,append:true}) → append without a prior read
+edit(path,oldText,newText) | edit({path,edits}) | edit({path,patch}) → numbered post-edit lines, checks, references
+edit(async () => {...}) → checkpoint: commit on success, rollback on throw; no shell, nesting, or outside commands
+bash(command,{cwd?,timeoutMs?}) → bounded output; nonzero throws
+bash({command,args}) → literal argv, no shell expansion of args
+
+edit oldText is an exact substring of read(); a miss includes a numbered window. Found is a span, not the file; uncertain returns ambiguous, not_found, or incomplete. Check resolve:true status; edit(view,text) replaces that window; edit(view,old,new) is unique inside it. complete:true rejects partial files; use about or offset/limit for large audits. Array reads reject failures; Promise.allSettled for per-path outcomes. Edits stage until success; bash commits preceding writes.
+programs:[{code|file,data?},...] sequential fresh guests, separate commits; stop on failure keeps earlier commits. Separate calls when the next step needs a model decision.`;

package/src/runtime/runtime.js

@@ -1,4 +1,5 @@
 import { Worker } from "node:worker_threads";
+import { readProgramFile } from "./program-file.js";
 import { parse } from "acorn";
 import { performance } from "node:perf_hooks";
 import { packageFinalReturn } from "../output/bottleneck.js";
@@ -6,20 +7,30 @@ import { truncateChars } from "../output/format.js";
 import { isFunction, isObject, isString } from "../shared/decode.js";
 
 const WORKER_URL = new URL("./guest-worker.js", import.meta.url);
+
 const ABORT_MESSAGE = "supernova timed out or aborted: pass timeoutMs to allow longer runs, or split the program";
+
 const MEMORY_POLL_MS = 50;
+
 const MEMORY_SLACK = 1.5;
+
 const rssBytes = isFunction(process.memoryUsage?.rss) ? () => process.memoryUsage.rss() : () => process.memoryUsage().rss;
+
 let idleWorker = null;
+
 let runSeq = 0;
 
 const PARSE_OPTIONS = { ecmaVersion: "latest", sourceType: "module", allowReturnOutsideFunction: true, allowAwaitOutsideFunction: true };
+
 const FUNCTION_TYPES = new Set(["FunctionDeclaration", "FunctionExpression", "ArrowFunctionExpression"]);
 
 function hasReturn(node) {
   if (!isObject(node)) return false;
+
   if (node.type === "ReturnStatement") return true;
+
   if (FUNCTION_TYPES.has(node.type)) return false;
+
   return Object.values(node).some(value => Array.isArray(value) ? value.some(hasReturn) : hasReturn(value));
 }
 
@@ -27,27 +38,34 @@ function prepareProgram(code) {
   let program;
   let expression;
   let expressionSource;
+
   try {
     program = parse(code, PARSE_OPTIONS);
     const statements = program.body.filter(node => node.type !== "EmptyStatement");
     const statement = statements.length === 1 ? statements[0] : undefined;
     const candidate = statement?.type === "ExpressionStatement" ? statement.expression : statement;
+
     if (candidate && FUNCTION_TYPES.has(candidate.type)) {
       expression = candidate;
       expressionSource = code.slice(0, statement.end).replace(/;\s*$/, "");
     }
   } catch (bodyError) {
     expressionSource = code.trimEnd().replace(/;+\s*$/, "");
+
     try {
       const wrapped = parse("(" + expressionSource + "\n)", PARSE_OPTIONS);
       expression = wrapped.body[0]?.expression;
+
       if (!expression || !FUNCTION_TYPES.has(expression.type)) throw bodyError;
     } catch { throw bodyError; }
   }
+
   const body = expression ? "return await (" + expressionSource + "\n)();" : code;
+
   const returns = expression
     ? expression.type === "ArrowFunctionExpression" && expression.body.type !== "BlockStatement" || hasReturn(expression.body)
     : hasReturn(program);
+
   return { body, hasReturn: returns };
 }
 
@@ -62,6 +80,7 @@ function spawnWorker(config) {
   worker.on("error", () => { handle.dead = true; });
   worker.on("exit", () => {
     handle.dead = true;
+
     if (idleWorker === handle) idleWorker = null;
   });
   handle.ready = new Promise((resolve, reject) => {
@@ -70,27 +89,33 @@ function spawnWorker(config) {
       worker.off("error", onFail);
       worker.off("exit", onFail);
     };
+
     const onMessage = (msg) => {
       if (msg?.op !== "ready") return;
       cleanup();
       resolve();
     };
+
     const onFail = (err) => {
       cleanup();
       reject(err instanceof Error ? err : new Error("guest worker exited before ready (code " + err + ")"));
     };
+
     worker.on("message", onMessage);
     worker.on("error", onFail);
     worker.on("exit", onFail);
   });
   handle.ready.catch(() => {});
+
   return handle;
 }
 
 function killWorker(handle) {
   if (!handle) return;
+
   if (idleWorker === handle) idleWorker = null;
   handle.dead = true;
+
   return handle.worker.terminate();
 }
 
@@ -98,9 +123,11 @@ function acquireWorker(config) {
   const candidate = idleWorker;
   idleWorker = null;
   const reusable = candidate && !candidate.dead && candidate.maxHeapMb === (config.maxHeapMb ?? 512);
+
   if (candidate && !reusable) void killWorker(candidate);
   const handle = reusable ? candidate : spawnWorker(config);
   handle.worker.ref?.();
+
   return handle;
 }
 
@@ -112,6 +139,7 @@ export function warmGuestWorker(config = {}) {
   handle.ready.then(() => {
     if (idleWorker === handle) handle.worker.unref?.();
   }, () => {});
+
   return handle.ready;
 }
 
@@ -123,23 +151,38 @@ const RPC_METHODS = {
   call: (nova, args) => nova.call(args[0], args[1]),
   callMany: async (nova, args) => {
     const wave = await nova.callMany(args[0]);
+
     return Array.isArray(wave) ? { results: [...wave], mode: wave.mode, reason: wave.reason } : wave;
   },
-  search: (nova, args) => nova.search(args[0], args[1]),
-  describe: (nova, args) => nova.describe(args[0]),
   speculateBegin: (nova) => nova.speculateBegin(),
   speculateCommit: (nova) => nova.speculateCommit(),
   speculateRollback: (nova) => nova.speculateRollback(),
 };
 
-export async function runGuestProgram({ code, nova = {}, config = {}, signal, onTimeout }) {
+export async function runGuestProgram({ code, file, cwd = process.cwd(), data, nova = {}, config = {}, signal, onTimeout }) {
   const started = performance.now();
   const wall = () => Math.round(performance.now() - started);
   const logs = [];
   const fail = (error) => ({ ok: false, error: truncateChars(String(error), config.maxReturnChars ?? 32000, "error").text, logs, logTruncated, wallMs: wall() });
   let logTruncated = false;
-  if (!isString(code) || !code.trim()) return fail("code must be a non-empty string");
-  if (code.length > (config.maxCodeChars ?? 48000)) return fail("code exceeds " + (config.maxCodeChars ?? 48000) + " characters; split large writes into write({path,content,append:true}) chunks");
+
+  if ((code === undefined) === (file === undefined)) return fail("supply exactly one of code or file; no commands ran");
+
+  if (file === undefined && (!isString(code) || !code.trim())) return fail("code must be a non-empty string");
+
+  if (file === undefined && code.length > (config.maxCodeChars ?? 48000)) return fail("code exceeds " + (config.maxCodeChars ?? 48000) + " characters; split large writes into write({path,content,append:true}) chunks");
+
+  if (data !== undefined) {
+    try {
+      const encoded = JSON.stringify(data);
+
+      if (encoded === undefined) return fail("data must be JSON-serializable");
+
+      if (encoded.length > (config.maxCodeChars ?? 48000)) return fail("data exceeds " + (config.maxCodeChars ?? 48000) + " characters; split literal inputs across invocations");
+      data = JSON.parse(encoded);
+    } catch { return fail("data must be JSON-serializable"); }
+  }
+
   if (signal?.aborted) return fail(ABORT_MESSAGE);
   const runId = ++runSeq;
   const timeoutMs = config.timeoutMs ?? 60000;
@@ -153,7 +196,10 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
     let hostError;
     let notifyingHost = false;
     const pending = new Set();
+    const inputController = new AbortController();
+
     const cleanup = () => {
+      inputController.abort();
       clearTimeout(timer);
       clearInterval(memTimer);
       signal?.removeEventListener("abort", signalAbort);
@@ -161,6 +207,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
       handle?.worker.off("error", onError);
       handle?.worker.off("exit", onExit);
     };
+
     const finish = (outcome) => {
       if (finished) return;
       finished = true;
@@ -169,27 +216,37 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
       void killWorker(handle);
       resolve({ ...outcome, wallMs: wall() });
     };
+
     const cancelHost = () => {
       notifyingHost = true;
+
       try { nova.cancel?.(); } catch {} finally { notifyingHost = false; }
     };
+
     const abort = () => {
       if (finished) return;
       cancelHost();
+
       try { onTimeout?.(); } catch {}
+
       finish(fail(ABORT_MESSAGE));
     };
+
     const signalAbort = () => { if (!notifyingHost) abort(); };
+
     const timer = setTimeout(abort, Math.min(timeoutMs, 2147483647));
+
     const memTimer = setInterval(() => {
       if (rssBytes() <= rssLimit) return;
       cancelHost();
       finish(fail("guest exceeded memory limit (maxHeapMb=" + (config.maxHeapMb ?? 512) + ")"));
     }, MEMORY_POLL_MS);
+
     signal?.addEventListener("abort", signalAbort, { once: true });
 
     const postResult = (message) => {
       if (!accepting || finished) return;
+
       try {
         handle.worker.postMessage({ ...message, runId });
       } catch (err) {
@@ -200,6 +257,7 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
         }
       }
     };
+
     const complete = async (outcome) => {
       if (finished || completing) return;
       completing = true;
@@ -208,15 +266,21 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
       handle?.worker.off("error", onError);
       handle?.worker.off("exit", onExit);
       void killWorker(handle);
+
       if (!outcome.ok) cancelHost();
       await Promise.allSettled(pending);
+
       if (finished) return;
       finish(outcome.ok && hostError ? fail(hostError) : outcome);
     };
+
     const onError = (err) => { void complete(fail("guest crashed: " + err.message)); };
+
     const onExit = (exitCode) => { void complete(fail("guest exited (code " + exitCode + ")")); };
+
     const onMessage = (msg) => {
       if (finished || !accepting || !isObject(msg) || msg.runId !== runId) return;
+
       if (msg.op === "log") {
         if (logs.length < (config.maxLogLines ?? 100)) logs.push(msg.line);
         else logTruncated = true;
@@ -225,10 +289,13 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
         logTruncated = true;
       } else if (msg.op === "rpc") {
         const method = Object.hasOwn(RPC_METHODS, msg.method) && RPC_METHODS[msg.method];
+
         const work = Promise.resolve().then(() => {
           if (!method) throw new Error("unknown nova method: " + msg.method);
+
           return method(nova, msg.args);
         });
+
         pending.add(work);
         work.then(
           value => postResult({ op: "rpc:result", id: msg.id, ok: true, value }),
@@ -256,23 +323,38 @@ export async function runGuestProgram({ code, nova = {}, config = {}, signal, on
     void (async () => {
       try {
         if (signal?.aborted) return abort();
+
+        if (file !== undefined) code = await readProgramFile(file, cwd, config.maxCodeChars ?? 48000, inputController.signal);
+
+        if (finished) return;
+
+        if (!code.trim()) return finish(fail("code must be a non-empty string; no commands ran"));
+        let prepared;
+
+        try { prepared = prepareProgram(code); }
+        catch (error) { return finish(fail("JavaScript syntax error: " + error.message + "; no commands ran. Put literal file/script content in the tool's data parameter and use write(data.path,data.content) or bash({command,args:data.args}).")); }
+
+        if (wall() >= timeoutMs) return abort();
         handle = acquireWorker(config);
         await handle.ready;
+
         if (finished || signal?.aborted) return abort();
         const available = isFunction(nova.names) ? await nova.names() : [];
+
         if (finished || signal?.aborted) return abort();
         handle.worker.on("message", onMessage);
         handle.worker.on("error", onError);
         handle.worker.on("exit", onExit);
-        const prepared = prepareProgram(code);
+
         if (wall() >= timeoutMs) return abort();
-        handle.worker.postMessage({ op: "run", runId, prepared, available,
+        handle.worker.postMessage({ op: "run", runId, prepared, data, available,
           batchRead: nova.batchRead !== false,
           nativeArgv: nova.nativeArgv === true,
           limits: { maxLogLines: config.maxLogLines ?? 100, maxLogLineChars: config.maxLogLineChars ?? 4096 } });
       } catch (err) {
+        if (finished) return;
         cancelHost();
-        finish(fail("guest worker failed to start: " + err.message));
+        finish(fail("program failed to start: " + err.message + "; no commands ran"));
       }
     })();
   });