pi-supernova 0.4.0 → 0.6.0

package/src/runtime/guest-worker.js

@@ -1,6 +1,6 @@
 import { parentPort } from "node:worker_threads";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { isString, isObject, isFunction, toPlain } from "../shared/decode.js";
+import { isString, isObject, isFunction, isNumber, toPlain, looksLikePath } from "../shared/decode.js";
 import { truncateChars } from "../output/format.js";
 import { sessionJsonArgs, validateJsonRead } from "../fs/json-read.js";
 
@@ -94,7 +94,11 @@ function leanEnvelope(res) {
   return res;
 }
 
-function buildGuestApi(available, batchRead, runId, nativeArgv) {
+function quoteShellArg(value) {
+  return "'" + String(value).replaceAll("'", "'\\''") + "'";
+}
+
+function buildGuestApi(available, batchRead, runId, _nativeArgv) {
   const rpc = (method, args) => callRpc(runId, method, args);
   const availableSet = new Set(available);
   const checkpointScope = new AsyncLocalStorage();
@@ -106,20 +110,41 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     if (token ? token !== checkpoint : checkpoint !== null) throw new Error("await the active edit checkpoint before issuing other commands; completed checkpoints cannot issue commands");
   };
 
+  let operationTail = Promise.resolve();
+
+  const enqueueHost = operation => {
+    const next = operationTail.then(operation);
+    operationTail = next.then(() => {}, () => {});
+
+    return next;
+  };
+
   const nova = {
-    search: (query, limit) => rpc("search", [query, limit]),
-    describe: (name) => rpc("describe", [name]),
-    call: async (name, args) => leanEnvelope(await rpc("call", [name, args])),
-    async callMany(calls) {
-      const wave = await rpc("callMany", [calls]);
-      const results = Array.isArray(wave?.results) ? wave.results : Array.isArray(wave) ? wave : [];
-      Object.defineProperties(results, {
-        mode: { value: wave?.mode, enumerable: false },
-        reason: { value: wave?.reason, enumerable: false },
-        results: { value: results, enumerable: false },
+    call(name, args) {
+      assertScope(); flushReads();
+      const promise = enqueueHost(() => rpc("call", [name, args]).then(leanEnvelope));
+
+      promise.catch(() => {});
+
+      return promise;
+    },
+    callMany(calls) {
+      assertScope(); flushReads();
+      const promise = enqueueHost(async () => {
+        const wave = await rpc("callMany", [calls]);
+        const results = Array.isArray(wave?.results) ? wave.results : Array.isArray(wave) ? wave : [];
+        Object.defineProperties(results, {
+          mode: { value: wave?.mode, enumerable: false },
+          reason: { value: wave?.reason, enumerable: false },
+          results: { value: results, enumerable: false },
+        });
+
+        return results;
       });
 
-      return results;
+      promise.catch(() => {});
+
+      return promise;
     },
     async speculate(fn) {
       if (checkpoint) throw new Error("edit checkpoints cannot overlap or nest; await the current checkpoint");
@@ -128,30 +153,31 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
       let began = false;
 
       try {
-        flushReads();
-        await rpc("speculateBegin", []);
+        await drainReads();
+        await enqueueHost(() => rpc("speculateBegin", []));
         began = true;
         const value = await checkpointScope.run(token, fn);
-        flushReads();
-        await rpc("speculateCommit", []);
+        await drainReads();
+        await enqueueHost(() => rpc("speculateCommit", []));
 
         return { ok: true, committed: true, value };
       } catch (err) {
-        flushReads();
+        await drainReads();
 
-        if (began) await rpc("speculateRollback", []);
+        if (began) await enqueueHost(() => rpc("speculateRollback", []));
 
         return { ok: false, committed: false, error: err instanceof Error ? err.message : String(err) };
       } finally { checkpoint = null; }
     },
-    surface: async (filePath) => unwrapJsonValue(await rpc("call", ["surface", { path: filePath }])),
-    evidence: async (query, opts) => unwrapJsonValue(await rpc("call", ["evidence", { query, ...opts }])),
-    snap: async (query, targetPath) => unwrapJsonValue(await rpc("call", ["snap", { query, path: targetPath }])),
+    surface(filePath) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["surface", { path: filePath }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
+    evidence(query, opts) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["evidence", { query, ...opts }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
+    snap(query, targetPath) { assertScope(); flushReads(); const promise = enqueueHost(() => rpc("call", ["snap", { query, path: targetPath }]).then(unwrapJsonValue)); promise.catch(() => {}); return promise; },
     has: (name) => availableSet.has(name),
   };
 
   // Coalesce already-started compatible reads without rewriting JS control flow.
   let queuedReads = [];
+  const pendingReadWaves = new Set();
 
   function flushReads() {
     const pending = queuedReads;
@@ -161,13 +187,13 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
       const wave = pending.slice(start, start + 64);
       const args = { ...wave[0].args, path: wave.map(job => job.args.path), _independent: true };
 
-      const run = wave.length === 1
-        ? nova.call("read", wave[0].args).then(res => ({ values: [unwrapRead(res, wave[0].args)], errors: [] }))
-        : nova.call("read", args).then(res => { unwrapRead(res, args);
+      const run = enqueueHost(() => wave.length === 1
+        ? rpc("call", ["read", wave[0].args]).then(leanEnvelope).then(res => ({ values: [unwrapRead(res, wave[0].args)], errors: [] }))
+        : rpc("call", ["read", args]).then(leanEnvelope).then(res => { unwrapRead(res, args);
 
- return { values: res.items, errors: res.itemErrors ?? [] }; });
+ return { values: res.items, errors: res.itemErrors ?? [] }; }));
 
-      void run.then(({ values, errors }) => {
+      const delivery = run.then(({ values, errors }) => {
         if (!Array.isArray(values) || values.length !== wave.length) throw new Error("invalid batch read response");
 
         for (let i = 0; i < wave.length; i++) {
@@ -177,28 +203,80 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
           else wave[i].resolve(value);
         }
       }).catch(error => { for (const job of wave) job.reject(error); });
+
+      pendingReadWaves.add(delivery);
+      void delivery.finally(() => pendingReadWaves.delete(delivery));
     }
   }
 
-  const invoke = (name, args) => { assertScope(); flushReads();
+  async function drainReads() {
+    for (;;) {
+      flushReads();
+      const waves = [...pendingReadWaves];
 
- return nova.call(name, args); };
+      if (!waves.length) return;
+      await Promise.allSettled(waves);
+    }
+  }
+
+  const invoke = (name, args) => {
+    assertScope(); flushReads();
+    const promise = nova.call(name, args);
 
-  const readArgs = (p, a, b) => isObject(p) && !Array.isArray(p)
-    ? { ...p, path: p.path ?? p.query }
-    : isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+    promise.catch(() => {});
+
+    return promise;
+  };
+
+  const readArgs = (p, a, b) => {
+    if (isObject(p) && !Array.isArray(p)) {
+      const args = { ...p, path: p.path ?? p.target ?? p.query };
+
+      if (p.path === undefined && p.target !== undefined) delete args.target;
+
+      return args;
+    }
+
+    return isObject(a) && !Array.isArray(a) ? { path: p, ...a } : { path: p, offset: a, limit: b };
+  };
 
   const read = async (p, a, b) => {
     assertScope();
     const args = sessionJsonArgs(readArgs(p, a, b));
+    if (isString(args.path) && args.resolve === undefined && args.complete !== true && args.json === undefined && args.about === undefined && args.query === undefined && !looksLikePath(args.path) && !/^(?:agent|artifact):\/\//i.test(args.path)) {
+      args.resolve = true;
+    }
     validateJsonRead(args);
-    const decode = value => args.resolve || args.json !== undefined ? JSON.parse(value) : value;
 
-    if (args.complete === true && (args.outline || args.evidence || args.about)) throw new Error("complete:true requires a raw file read, not an outline or evidence view");
-    const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : args.about ? p : undefined;
+    for (const [key, value] of [["resolve", args.resolve], ["complete", args.complete], ["outline", args.outline], ["evidence", args.evidence]]) {
+      if (value !== undefined && typeof value !== "boolean") throw new Error("read " + key + " must be a boolean");
+    }
+
+    if (args.about !== undefined && !isString(args.about)) throw new Error("read about must be a string");
+    if (args.query !== undefined && !isString(args.query)) throw new Error("read query must be a string");
+    const focusModes = [args.about !== undefined, args.query !== undefined, args.outline === true].filter(Boolean).length;
+
+    if (focusModes > 1 || (args.outline === true && args.evidence === true)) throw new Error("read accepts only one of about, query, outline, or evidence");
+    if (args.resolve === true && args.complete === true) throw new Error("read accepts either resolve or complete, not both");
+    const decode = value => {
+      if ((!args.resolve && args.json === undefined) || !isString(value)) return value;
+
+      try {
+        return JSON.parse(value);
+      } catch (error) {
+        const selector = args.json === undefined ? "" : " (" + (Array.isArray(args.json) ? args.json.join(", ") : String(args.json)) + ")";
+        throw new Error("JSON read failed for " + String(args.path ?? args.target ?? "resource") + selector + ": " + (error instanceof Error ? error.message : String(error)));
+      }
+    };
+
+    if (args.complete === true && (args.outline || args.evidence || args.about || args.query)) throw new Error("complete:true requires a raw file read, not a source view");
+    const evidencePath = isObject(p) && !Array.isArray(p) ? p.path : (isString(p) && looksLikePath(p) ? p : undefined);
     p = args.path;
 
-    if (args.evidence) return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query: args.about ?? args.query ?? p }));
+    if (args.evidence) {
+      const query = args.about ?? args.query ?? (isString(p) ? p : undefined);
+      return unwrapJsonValue(await invoke("evidence", { ...args, path: evidencePath, query }));
+    }
 
     if (args.outline) return unwrapJsonValue(await invoke("surface", args));
 
@@ -206,9 +284,24 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
       if (p.length > 64) throw new Error("read accepts at most 64 paths per batch");
 
       for (const item of p) if (!isString(item) || !item.trim()) throw new Error("read paths must be non-empty strings");
-      const readEach = () => Promise.all(p.map(item => read({ ...args, path: item })));
+      const readEach = async () => {
+        const values = await Promise.all(p.map(item => read({ ...args, path: item })));
+        const missing = args.resolve ? values.findIndex((value, index) => value?.status === "not_found" && looksLikePath(p[index])) : -1;
+
+        if (missing >= 0) throw new Error(`read failed for ${p[missing]}: not_found; use Promise.allSettled(paths.map(path => read(path))) for per-path outcomes`);
+
+        return values;
+      };
+
+      const guardedReadEach = () => {
+        const promise = readEach();
+
+        promise.catch(() => {});
+
+        return promise;
+      };
 
-      if (!batchRead || args.resolve || p.some(item => /^(agent|artifact):\/\/.*\?/i.test(item))) return readEach();
+      if (!batchRead || args.resolve || p.some(item => /^(agent|artifact):\/\/.*\?/i.test(item))) return guardedReadEach();
       const res = await invoke("read", args);
       const failed = res?.itemErrors?.findIndex(error => error != null) ?? -1;
 
@@ -218,7 +311,7 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
       if (Array.isArray(res?.items)) return res.items.map(decode);
 
       // Captured host executor without batch support: fan out.
-      return readEach();
+      return guardedReadEach();
     }
 
     if (!batchRead) {
@@ -232,19 +325,44 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
 
     if (queuedReads.length && queuedReads[0].key !== key) flushReads();
 
-    return new Promise((resolve, reject) => {
+    const promise = new Promise((resolve, reject) => {
       queuedReads.push({ args, key, resolve, reject });
 
       if (queuedReads.length === 1) queueMicrotask(flushReads);
     }).then(decode);
+
+    promise.catch(() => {});
+
+    return promise;
   };
 
   const write = async (p, content) => unwrapValue(await invoke("write", isObject(p) ? p : { path: p, content }));
 
+  const viewSpan = (value) => {
+    const start = isNumber(value.start) ? value.start : Array.isArray(value.lines) ? value.lines[0] : value.line;
+    const end = isNumber(value.end) ? value.end : Array.isArray(value.lines) && value.lines.length > 1 ? value.lines[1] : start;
+
+    if (!isNumber(start) || !isNumber(end) || start < 1 || end < start) return null;
+
+    return { start: Math.floor(start), end: Math.floor(end) };
+  };
+
+  const isView = (value) => isObject(value) && !Array.isArray(value) && isString(value.path) && value.path.trim() && isString(value.text) && (value.status === undefined || value.status === "found") && viewSpan(value);
+
   const edit = async (p, oldText, newText) => {
     if (isFunction(p)) return nova.speculate(p);
     const usage = 'invalid edit signature; use edit(path,oldText,newText), edit({path,edits:[{oldText,newText}]}), or edit({path,patch:"@@ -1 +1 @@\n-old\n+new\n"})';
 
+    if (isView(p) && isString(oldText) && (newText === undefined || isString(newText))) {
+      if (isNumber(p.nextOffset)) throw new Error("edit view is incomplete");
+      const span = viewSpan(p);
+      const args = { path: p.path, viewStart: span.start, viewEnd: span.end, viewText: p.text, newText: newText === undefined ? oldText : newText };
+
+      if (newText !== undefined) args.oldText = oldText;
+
+      return unwrapValue(await invoke("edit", args));
+    }
+
     if (isObject(p) && (Array.isArray(p) || oldText !== undefined || newText !== undefined)) throw new Error(usage);
 
     if (!isObject(p) && isObject(oldText) && !Array.isArray(oldText)) throw new Error(usage);
@@ -268,19 +386,22 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     return unwrapValue(await invoke(args.patch === undefined ? "edit" : "apply_patch", args));
   };
 
-  const patch = async (p, diff) => unwrapValue(await nova.call("apply_patch", { path: p, patch: diff }));
-
   const bash = async (command, opts) => {
     const args = isObject(command) ? { ...command } : { command, ...opts };
 
     if (args.args !== undefined) {
-      if (!isString(args.command) || !Array.isArray(args.args) || args.args.some(arg => !isString(arg))) throw new Error("bash argv requires a command string and an array of string args");
+      if (!isString(args.command) || !Array.isArray(args.args)) throw new Error("bash argv requires a command string and an array of string args");
+
+      for (let i = 0; i < args.args.length; i++) if (!isString(args.args[i])) throw new Error("bash argv requires a command string and an array of string args");
+      args.args = args.args.map(String);
 
-      if (nativeArgv) args._directArgv = true;
-      else {
+      // Literal argv is a Supernova-owned contract. Host bash tools often ignore
+      // `args` and would run only `command` (bare `ssh`). Windows still needs a shell.
+      if (process.platform === "win32") {
         delete args._directArgv;
         args.command = [args.command, ...args.args].map(quoteShellArg).join(" ");
-      }
+        delete args.args;
+      } else args._directArgv = true;
     }
 
     command = args.command;
@@ -307,20 +428,7 @@ function buildGuestApi(available, batchRead, runId, nativeArgv) {
     return text;
   };
 
-  const quoteShellArg = (value) => "'" + String(value).replaceAll("'", "'\\''") + "'";
-
-  const exec = async (cmd, args, opts) => {
-    const command = String(cmd ?? "").trim();
-
-    if (!command) throw new Error("exec requires command");
-
-    // exec("git status") is a shell line; exec("git", ["status"]) is argv.
-    if (!Array.isArray(args) || args.length === 0) return bash(command, opts);
-
-    return bash([command, ...args].map(quoteShellArg).join(" "), opts);
-  };
-
-  return { nova, read, write, edit, patch, surface: nova.surface, snap: nova.snap, evidence: nova.evidence, bash, exec, speculate: nova.speculate };
+  return { read, write, edit, bash, nova };
 }
 
 function makeConsole(runId, limits) {
@@ -344,7 +452,10 @@ function makeConsole(runId, limits) {
         if (isString(a)) return a;
 
         try {
-          return JSON.stringify(toPlain(a));
+          const plain = toPlain(a);
+          const encoded = JSON.stringify(plain);
+
+          return encoded === undefined ? String(plain) : encoded;
         } catch {
           return String(a);
         }

package/src/runtime/parallel.js

@@ -1,10 +1,13 @@
-import { isFunction } from "../shared/decode.js";
+import { isFunction, isObject } 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 (!isObject(args)) args = {};
+  name = String(name);
+
   if ((config.mutatingTools ?? []).includes(name)) return true;
 
   if ((config.mutatingPrefixes ?? []).some(prefix => prefix && name.startsWith(prefix))) return true;

package/src/runtime/program-batch.js

@@ -1,7 +1,7 @@
 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 textOf = result => (Array.isArray(result?.content) ? 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;
@@ -24,7 +24,7 @@ export function programBatchText(results, total, stopped = "") {
 }
 
 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 (["code","file"].some(key => params[key] !== undefined)) throw new Error("programs cannot combine with top-level code or file; 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");
 
@@ -35,20 +35,31 @@ function batchInputs(params, config) {
     }
   }
 
+  const hasDefault = params.data !== undefined;
   let encoded;
 
-  try { encoded = JSON.stringify(params.programs); } catch { throw new Error("programs must be JSON-serializable; no programs ran"); }
+  try { encoded = JSON.stringify(hasDefault ? {programs:params.programs,data:params.data} : params.programs); } catch { throw new Error("programs and data 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);
+  const parsed = JSON.parse(encoded);
+
+  if (!hasDefault) return parsed;
+  if (!Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
+
+  // The runtime snapshots data separately for each fresh guest. An explicit
+  // entry replaces the default wholesale; falsy values are not missing values.
+  return parsed.programs.map(program => program.data === undefined ? {...program,data:parsed.data} : program);
 }
 
 /** 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 requestedTimeout = params.timeoutMs === undefined ? config.timeoutMs : Number(params.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) throw new Error("program batch timeoutMs must be a positive finite number");
   const started = performance.now();
-  const timeout = Number.isInteger(params.timeoutMs) ? params.timeoutMs : config.timeoutMs;
+  const timeout = requestedTimeout;
   const deadline = started + timeout;
   const controller = new AbortController();
   const combined = signal ? AbortSignal.any([signal,controller.signal]) : controller.signal;
@@ -76,7 +87,7 @@ export async function runProgramBatch(id, params, signal, onUpdate, ctx, config,
       trace.push(...(result.details?.trace ?? []));
       let image = 0;
 
-      for (const block of result.content) if (block.type === "image") {
+      for (const block of Array.isArray(result?.content) ? result.content : []) if (block?.type === "image" && isString(block.data)) {
         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; }

package/src/runtime/program-file.js

@@ -4,6 +4,9 @@ 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 chars = Number(maxChars);
+
+  if (!Number.isInteger(chars) || chars <= 0) throw new Error("program file maxChars must be a positive integer");
   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));
@@ -15,8 +18,8 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
     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");
+    const maxBytes = chars * 3;
+    const tooLarge = () => new Error("code exceeds " + chars + " characters; split the program");
 
     if (stat.size > maxBytes) throw tooLarge();
     const chunks = [];
@@ -33,7 +36,7 @@ export async function readProgramFile(file, cwd, maxChars, signal) {
     // 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();
+    if (code.length > chars) throw tooLarge();
 
     return code;
   } finally { await handle.close(); }

package/src/runtime/reference.js

@@ -1,25 +1,18 @@
 // Complete model-facing API reference; kept in every request, not moved into history.
-export const REFERENCE = `Run a JavaScript async body or arrow with read, write, edit and bash. Strings stay raw. Single program: exactly one of code or file; file rereads a workspace program with the same limits, bindings, calling-workspace cwd and fresh guest. Code and data character caps use UTF-16 units. Split large writes using append.
+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.
 
-Native commands (async):
-read(path|paths, offset?, limit?) → file text or text[]; read(directory) → directory entries
-read(imagePath) → image attachment when returned (PNG/JPEG/GIF/WebP/BMP); no browser needed
-read({path,json:".field"}) → parsed JSON field; supports .items[0:3], quoted keys, selector arrays, or true for the whole JSON value
-read("agent://id?q=.answer") → JSON field from a calling-session resource (when host artifacts are available)
-read("symbol or question") → locate and open source in one call, without an index; selected file text stays raw
-read({query, resolve:true}) → {status,path,line,lines,text,complete,nextOffset?} for a direct resolve→edit handoff
-read(path, {about: question}) → relevant file bodies, or source selection inside a directory
-read({query, evidence:true}) → ranked evidence; read({path, outline:true}) → structural declarations
-write(path, text) → write a file; write({path,content,append:true}) appends a chunk without a bounded read
-edit(path, oldText, newText) → post-edit lines, checks, and references
-edit(async () => {...}) → filesystem checkpoint: commit on success, rollback on throw; no shell commands, nesting, or concurrent outside commands
-bash(command, {cwd?, timeoutMs?}) → bounded output; throws on non-zero exit
-bash({command, args:[...]}) → literal argv without shell expansion of arguments
+read(path|paths, offset?, limit?) → raw text or text[]; read(directory) → entries[]; up to 64 paths
+read(imagePath) → image (PNG/JPEG/GIF/WebP/BMP); 20 MiB max, 16 attachments max
+read({path,json:".field"}) → parsed JSON; .items[0:3], quoted keys, 1-64 selectors, 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; source questions use at most 16 keywords
+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
 
-Start with a source question or scoped about read; do not redundantly reopen selected source. Only found selects and opens a file. Uncertain reads return ambiguous, not_found, or incomplete with no selected path. Use resolve:true to check status before editing its path; narrow the directory with path+about when uncertain.
-For read-modify-write, use read({path,complete:true}); it rejects partial output. JSON selectors parse the full document (16 MiB cap); selections must fit the read budget. No full jq; do not JSON.parse line windows. For large text audits use about or offset/limit, not complete:true. Prefer edit for large files. Array reads reject failures; use Promise.allSettled for per-path outcomes.
-Object arguments also work: read({path, offset?, limit?, about?, outline?, evidence?, resolve?, complete?}), edit({path, edits:[{oldText,newText}]}), edit({path,patch}), write({path,content}), bash({command,timeoutMs?}).
-File changes stage until program success; later errors roll them back. Shell calls commit preceding writes and cannot be rolled back. Outcomes report committed/rolledBack file versions and external-call attempts.
-Independent read starts batch automatically. Mutations preserve submission order. Plain reads remain self-contained; oversized reads provide continuation offsets. Return only what the model needs. console.log is captured.
-
-For known continuations use programs:[{code|file,data?},...]. Entries run sequentially in fresh guests with separate commits. The batch stops on failure and returns all attempted results, including a typed stop report; earlier commits remain. Deadlines, host calls, logs and output are shared across the batch. Use separate calls when the next action needs model reasoning.`;
+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; top-level data defaults per entry, explicit entry data replaces it. Stop on failure keeps earlier commits. Separate calls when the next step needs a model decision.`;

package/src/runtime/runtime.js

@@ -47,7 +47,7 @@ function prepareProgram(code) {
 
     if (candidate && FUNCTION_TYPES.has(candidate.type)) {
       expression = candidate;
-      expressionSource = code.slice(0, statement.end).replace(/;\s*$/, "");
+      expressionSource = code.slice(statement.start, statement.end).replace(/;\s*$/, "");
     }
   } catch (bodyError) {
     expressionSource = code.trimEnd().replace(/;+\s*$/, "");
@@ -154,8 +154,6 @@ const RPC_METHODS = {
 
     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(),
@@ -187,7 +185,10 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
 
   if (signal?.aborted) return fail(ABORT_MESSAGE);
   const runId = ++runSeq;
-  const timeoutMs = config.timeoutMs ?? 60000;
+  const requestedTimeout = Number(config.timeoutMs === undefined ? 60000 : config.timeoutMs);
+
+  if (!Number.isFinite(requestedTimeout) || requestedTimeout <= 0) return fail("timeoutMs must be a positive finite number");
+  const timeoutMs = Math.max(1, Math.min(2_147_483_647, Math.floor(requestedTimeout)));
   const rssLimit = rssBytes() + (config.maxHeapMb ?? 512) * MEMORY_SLACK * 1048576;
 
   return new Promise((resolve) => {
@@ -197,6 +198,7 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
     let completing = false;
     let hostError;
     let notifyingHost = false;
+    let aborting = false;
     const pending = new Set();
     const inputController = new AbortController();
 
@@ -226,11 +228,13 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
     };
 
     const abort = () => {
-      if (finished) return;
+      if (finished || aborting) return;
+      aborting = true;
       cancelHost();
 
       try { onTimeout?.(); } catch {}
 
+      aborting = false;
       finish(fail(ABORT_MESSAGE));
     };
 
@@ -269,8 +273,11 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
       handle?.worker.off("exit", onExit);
       void killWorker(handle);
 
-      if (!outcome.ok) cancelHost();
-      await Promise.allSettled(pending);
+      if (pending.size || !outcome.ok) cancelHost();
+      // A host tool that ignores cancellation must not keep the result unsettled
+      // after the guest worker is gone. Give it a brief drain window only.
+      await Promise.race([Promise.allSettled(pending), new Promise(resolve => setTimeout(resolve, 250))]);
+      if (pending.size && outcome.ok) hostError ??= "program completed with a host call still running";
 
       if (finished) return;
       finish(outcome.ok && hostError ? fail(hostError) : outcome);
@@ -341,7 +348,9 @@ export async function runGuestProgram({ code, file, cwd = process.cwd(), data, n
         await handle.ready;
 
         if (finished || signal?.aborted) return abort();
-        const available = isFunction(nova.names) ? await nova.names() : [];
+        let available = isFunction(nova.names) ? await nova.names() : [];
+
+        if (!Array.isArray(available)) available = [];
 
         if (finished || signal?.aborted) return abort();
         handle.worker.on("message", onMessage);