pi-supernova 0.6.0 → 0.7.1

package/src/runtime/parallel.js

@@ -4,33 +4,91 @@ const READ_ONLY_TOOLS = new Set(["read", "grep", "glob", "find", "ls", "snap", "
 
 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);
+const NATIVE_TOOLS = ["read", "edit", "write", "bash"];
 
+const SPECIAL_MUTATION = {
+  todo: args => args.op !== "view",
+  hub: args => !["list", "ps", "logs", "describe"].includes(args.op),
+};
+
+function configuredMutating(name, config) {
   if ((config.mutatingTools ?? []).includes(name)) return true;
 
   if ((config.mutatingPrefixes ?? []).some(prefix => prefix && name.startsWith(prefix))) return true;
 
+  return false;
+}
+
+function lspMutates(args) {
+  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;
+}
+
+export function isMutatingTool(name, config = {}, args = {}, definition) {
+  if (!isObject(args)) args = {};
+  name = String(name);
+
+  if (configuredMutating(name, config)) return true;
+
   if (definition?.annotations?.readOnlyHint === true) return false;
 
-  if (name === "lsp") {
-    const action = args.action ?? args.operation;
+  if (name === "lsp") return lspMutates(args);
+  const special = SPECIAL_MUTATION[name];
+
+  if (special) return special(args);
 
-    if (READ_ONLY_LSP.has(action)) return false;
+  return !READ_ONLY_TOOLS.has(name);
+}
+
+function takeScheduledWave(queue, first, maxParallelReads) {
+  const wave = [first];
 
-    if (["rename", "rename_file"].includes(action)) return args.apply !== false;
+  if (first.name !== "read") return wave;
 
-    if (action === "code_actions") return args.apply === true;
+  while (wave.length < maxParallelReads && queue[0]?.name === "read") {
+    const next = queue.shift();
 
-    return true;
+    if (!next.cancelled) wave.push(next);
   }
 
-  if (name === "todo") return args.op !== "view";
+  return wave;
+}
 
-  if (name === "hub") return !["list", "ps", "logs", "describe"].includes(args.op);
+async function runScheduledJob(job) {
+  if (job.cancelled) return;
+  job.started = true;
+  job.signal?.removeEventListener("abort", job.abort);
+
+  try {
+    job.signal?.throwIfAborted();
+    const result = await job.run();
+    job.signal?.throwIfAborted();
+    job.resolve(result);
+  } catch (error) { job.reject(error); }
+}
 
-  return !READ_ONLY_TOOLS.has(name);
+function runScheduledWave(wave) {
+  // Settle each promise separately: one failed read must not discard its
+  // siblings or release a write barrier while other reads are still active.
+  return Promise.all(wave.map(runScheduledJob));
+}
+
+function attachJobAbort(job, signal, reject) {
+  job.abort = () => {
+    if (job.started) return;
+    job.cancelled = true;
+    signal.removeEventListener("abort", job.abort);
+    reject(signal.reason ?? new Error("aborted"));
+  };
+
+  signal?.addEventListener("abort", job.abort, { once: true });
 }
 
 /** FIFO read waves with mutation barriers; callers keep independent promises. */
@@ -46,33 +104,14 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
         const first = queue.shift();
 
         if (first.cancelled) continue;
-        const wave = [first];
+        const wave = takeScheduledWave(queue, first, maxParallelReads);
 
         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();
-            job.signal?.throwIfAborted();
-            job.resolve(result);
-          } catch (error) { job.reject(error); }
-        }));
+        await runScheduledWave(wave);
       }
     } finally { draining = false; }
   }
@@ -80,7 +119,7 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
   return {
     stats,
     schedule(name, run, signal) {
-      if (!["read", "edit", "write", "bash"].includes(name) || !isFunction(run)) {
+      if (!NATIVE_TOOLS.includes(name) || !isFunction(run)) {
         return Promise.reject(new Error("scheduler requires a native tool and an executor"));
       }
 
@@ -89,14 +128,7 @@ export function createNativeScheduler({ maxParallelReads = 8 } = {}) {
 
       return new Promise((resolve, reject) => {
         const job = { name, run, signal, resolve, reject, started: false, cancelled: false };
-        job.abort = () => {
-          if (job.started) return;
-          job.cancelled = true;
-          signal.removeEventListener("abort", job.abort);
-          reject(signal.reason ?? new Error("aborted"));
-        };
-
-        signal?.addEventListener("abort", job.abort, { once: true });
+        attachJobAbort(job, signal, reject);
         queue.push(job);
 
         if (!draining) {
@@ -116,26 +148,27 @@ function requireArray(value, name) {
   return value;
 }
 
-export async function runParallelWave(thunks, meta, options = {}) {
-  const list = requireArray(thunks, "parallel wave");
+function waveMutates(list, meta, config) {
+  const names = meta?.names ?? [];
 
-  if (list.some(item => !isFunction(item))) throw new TypeError("parallel wave requires functions");
+  return names.length !== list.length || names.some((name, i) => isMutatingTool(name, config, meta?.calls?.[i]?.args, meta?.definitions?.[i]));
+}
 
-  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]));
+function shouldRunParallel(mutating, mode, length) {
+  return !mutating && (mode === "parallel" || (mode === "auto" && length > 1));
+}
 
-  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");
+async function settleParallel(list) {
+  // 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;
+  if (failure) throw failure.reason;
 
-    return { results: settled.map(item => item.value), mode: "parallel", reason: "independent-reads" };
-  }
+  return { results: settled.map(item => item.value), mode: "parallel", reason: "independent-reads" };
+}
 
+async function runSerial(list, mutating) {
   const results = [];
 
   for (const thunk of list) results.push(await thunk());
@@ -143,16 +176,16 @@ export async function runParallelWave(thunks, meta, options = {}) {
   return { results, mode: "serial", reason: mutating ? "mutating" : "single-or-forced" };
 }
 
-export async function parallel(items) {
-  return Promise.all(requireArray(items, "parallel").map(item => isFunction(item) ? item() : item));
-}
+export async function runParallelWave(thunks, meta, options = {}) {
+  const list = requireArray(thunks, "parallel wave");
 
-export async function pipeline(items, ...stages) {
-  let current = requireArray(items, "pipeline");
+  if (list.some(item => !isFunction(item))) throw new TypeError("parallel wave requires functions");
 
-  if (stages.some(stage => !isFunction(stage))) throw new TypeError("pipeline stages must be functions");
+  if (!list.length) return { results: [], mode: "serial", reason: "empty" };
+  const { mode = "auto", config = {} } = options;
+  const mutating = waveMutates(list, meta, config);
 
-  for (const stage of stages) current = await Promise.all(current.map(item => stage(item)));
+  if (shouldRunParallel(mutating, mode, list.length)) return settleParallel(list);
 
-  return current;
+  return runSerial(list, mutating);
 }

package/src/runtime/program-batch.js

@@ -12,10 +12,15 @@ const mutationTotals = results => results.reduce((total, result) => {
   return total;
 }, {committed:0,rolledBack:0,external:0,pendingCommits:0,recoveryFailed:false});
 
-export function programBatchText(results, total, stopped = "") {
+export function programBatchText(results, total, stopped = "", failed = 0) {
   const m = mutationTotals(results);
+  const summary = stopped
+    ? "error: programs stopped: " + stopped + " " + results.length + "/" + total
+    : failed > 0
+      ? "error: programs " + results.length + "/" + total + " - " + failed + " failed"
+      : "ok: programs " + results.length + "/" + total;
 
-  return (stopped ? "error: programs stopped: " + stopped : "ok: programs") + " " + results.length + "/" + total +
+  return summary +
     (m.recoveryFailed || m.pendingCommits ? "; filesystem outcome uncertain: inspect disk" : "") + "\nresults (UTF-16 lengths):\n" + results.map((result,i) => {
       const text = textOf(result);
 
@@ -23,27 +28,23 @@ export function programBatchText(results, total, stopped = "") {
     }).join("");
 }
 
-function batchInputs(params, config) {
-  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");
-
-  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");
-    }
+function assertProgramEntry(p) {
+  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");
   }
+}
 
+function encodeBatchPayload(params) {
   const hasDefault = params.data !== undefined;
   let encoded;
 
   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");
-
-  const parsed = JSON.parse(encoded);
+  return { hasDefault, encoded };
+}
 
+function applyDefaultData(parsed, hasDefault) {
   if (!hasDefault) return parsed;
   if (!Object.hasOwn(parsed,"data")) throw new Error("data must be JSON-serializable; no programs ran");
 
@@ -52,72 +53,180 @@ function batchInputs(params, config) {
   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);
+function parseBatchPayload(params, config) {
+  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");
+
+  for (const p of params.programs) assertProgramEntry(p);
+  const { hasDefault, encoded } = encodeBatchPayload(params);
+
+  if (encoded.length > (config.maxCodeChars ?? 48000)) throw new Error("programs JSON exceeds the code character budget; no programs ran");
+
+  return applyDefaultData(JSON.parse(encoded), hasDefault);
+}
+
+function batchTimeoutMs(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 = requestedTimeout;
-  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;
+  return requestedTimeout;
+}
+
+const MAX_PARALLEL_PROGRAMS = 8;
+
+class ProgramBatch {
+  constructor(id, params, signal, onUpdate, ctx, config, execute, programs, timeout) {
+    this.id = id;
+    this.onUpdate = onUpdate;
+    this.ctx = ctx;
+    this.config = config;
+    this.execute = execute;
+    this.programs = programs;
+    this.timeout = timeout;
+    this.started = performance.now();
+    this.deadline = this.started + timeout;
+    this.controller = new AbortController();
+    this.combined = signal ? AbortSignal.any([signal, this.controller.signal]) : this.controller.signal;
+    this.timer = setTimeout(() => this.controller.abort(), Math.min(timeout, 2147483647));
+    this.budget = {calls:0,logLines:0};
+    this.parallel = params.parallel === true && programs.length > 1;
+    this.results = [];
+    this.images = [];
+    this.imageLabels = [];
+    this.trace = [];
+    this.live = programs.map(() => []);
+    this.imageSeq = programs.map(() => 0);
+    this.imageBytes = 0;
+    this.stopped = "";
+    this.imageDropped = false;
+  }
+
+  imageTextChars() {
+    return this.imageLabels.reduce((chars, label) => chars + label.length + 1, 0);
+  }
+
+  updateFor(i) {
+    return update => {
+      this.live[i] = update?.details?.trace ?? [];
+
+      try { this.onUpdate?.({...update,details:{...update?.details,trace:[...this.trace,...this.live.flat()]}}); } catch {}
+    };
+  }
+
+  runOne(program, i) {
+    return Promise.resolve()
+      .then(() => this.execute(this.id + ":" + i,{...program,timeoutMs:Math.max(1,Math.ceil(this.deadline-performance.now()))},this.combined,this.updateFor(i),this.ctx,this.budget,{parallel:this.parallel}))
+      .catch(error => error.supernovaResult ?? {content:[{type:"text",text:String(error?.message ?? error)}],details:{ok:false,error:String(error?.message ?? error)}});
+  }
 
-      for (const block of Array.isArray(result?.content) ? result.content : []) if (block?.type === "image" && isString(block.data)) {
-        imageBytes += Buffer.byteLength(block.data,"base64");
+  collectImages(result, i) {
+    for (const block of Array.isArray(result?.content) ? result.content : []) if (block?.type === "image" && isString(block.data)) {
+      this.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; }
+      if (this.images.length >= 16 || this.imageBytes > 20*1024*1024) { this.imageDropped = true; continue; }
 
-        images.push(block);
-        imageLabels.push("program " + (i+1) + " image " + (++image));
+      this.images.push(block);
+      this.imageLabels.push("program " + (i+1) + " image " + (++this.imageSeq[i]));
+    }
+  }
+
+  takeSettled(result, i) {
+    this.results.push(result);
+    this.trace.push(...(result.details?.trace ?? []));
+    this.collectImages(result, i);
+  }
+
+  async runParallel() {
+    const limit = Math.min(this.programs.length, MAX_PARALLEL_PROGRAMS);
+    const settled = Array.from({ length: this.programs.length });
+    let next = 0;
+
+    await Promise.all(Array.from({length: limit}, async () => {
+      while (next < this.programs.length && !this.combined.aborted && performance.now() < this.deadline) {
+        const i = next++;
+        settled[i] = await this.runOne(this.programs[i], i);
+        this.live[i] = [];
       }
+    }));
+
+    for (let i = 0; i < this.programs.length; i++) {
+      if (settled[i] === undefined) continue;
+      this.takeSettled(settled[i], i);
+    }
+
+    if (settled.includes(undefined) || this.combined.aborted || performance.now() >= this.deadline) this.stopped = "batch deadline or cancellation; earlier commits remain";
+  }
+
+  sequentialStop(result, i) {
+    let stopped = this.stopped;
+
+    if (this.imageDropped) stopped = "batch image budget exceeded; remaining programs did not run";
+
+    if (result.details?.ok === false) stopped = "program " + (i+1) + " failed; remaining programs did not run; earlier commits remain";
+    const text = programBatchText(this.results, this.programs.length, stopped);
 
-      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 + this.imageTextChars() > this.config.maxReturnChars || result.details?.returnTruncated) stopped ||= "batch output budget exceeded; remaining programs did not run; earlier commits remain";
 
-      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 (result.details?.logTruncated) stopped ||= "batch log budget exceeded; remaining programs did not run; earlier commits remain";
+    if (this.combined.aborted || performance.now() >= this.deadline) stopped ||= "batch deadline or cancellation; earlier commits remain";
 
-      if (combined.aborted || performance.now() >= deadline) stopped ||= "batch deadline or cancellation; earlier commits remain";
+    return stopped;
+  }
+
+  async runSequential() {
+    for (const [i, program] of this.programs.entries()) {
+      if (this.combined.aborted || performance.now() >= this.deadline) { this.stopped = "deadline or cancellation; remaining programs did not run"; break; }
 
-      if (stopped) break;
+      const result = await this.runOne(program, i);
+      this.live[i] = [];
+      this.takeSettled(result, i);
+      this.stopped = this.sequentialStop(result, i);
+
+      if (this.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)}};
+  }
+
+  failNote(failed) {
+    return this.stopped || (this.parallel && failed ? failed + " program" + (failed>1?"s":"") + " failed" : undefined);
+  }
+
+  boundedText(failed) {
+    const note = this.imageDropped && !this.stopped ? "some images dropped: batch image budget" : "";
+
+    return truncateChars(programBatchText(this.results,this.programs.length,this.stopped,this.parallel ? failed : 0) + (note ? "; " + note : ""),Math.max(0,this.config.maxReturnChars-this.imageTextChars()),"batch output");
+  }
+
+  finish() {
+    const failed = this.results.filter(result => result.details?.ok === false).length;
+    const bounded = this.boundedText(failed);
+    const content = [{type:"text",text:bounded.text}];
+    this.images.forEach((image,i) => content.push({type:"text",text:this.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:!!this.stopped || (this.parallel && failed>0),details:{ok:!this.stopped && !(this.parallel && failed),error:this.failNote(failed),wallMs:Math.round(performance.now()-this.started),
+      programs:this.results,attempted:this.results.length,total:this.programs.length,stopped:this.stopped,parallel:this.parallel,
+      result:bounded.truncated ? bounded.text : this.results.map(result=>result.details?.result),
+      returnTruncated:bounded.truncated || this.results.some(result=>result.details?.returnTruncated),
+      logTruncated:this.results.some(result=>result.details?.logTruncated),logs:this.results.flatMap(result=>result.details?.logs ?? []),trace:this.trace,mutations:mutationTotals(this.results)}};
+  }
+
+  async run() {
+    try {
+      if (this.parallel) await this.runParallel();
+      else await this.runSequential();
+    } finally { clearTimeout(this.timer); this.controller.abort(); }
+
+    return this.finish();
+  }
+}
+
+/** Explicit known continuations, not inferred plans, retries, or a shared heap. */
+export async function runProgramBatch(id, params, signal, onUpdate, ctx, config, execute) {
+  const programs = parseBatchPayload(params, config);
+
+  return new ProgramBatch(id, params, signal, onUpdate, ctx, config, execute, programs, batchTimeoutMs(params, config)).run();
 }

package/src/runtime/reference.js

@@ -1,18 +1,19 @@
-// 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.
+// Standing tool description: sent on every request. One nova call, four commands inside.
+export const REFERENCE = `JavaScript async body or arrow with read, write, edit, bash. file:path runs that program file instead. Put Markdown/scripts/argv in data. Guest has no fs/import/require.
 
-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|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], .items.length, quoted keys, or true; 16 MiB cap; no jq
+raw JSON or selections over budget return {status:"too_large",path,keys} (length for arrays); narrow with json:".field" or slices
+read("symbol or question") → same view as resolve:true
+read({query,resolve:true}) → {status,path,line,text,...}
 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
+write(path, text) → replace an unread file; write({path,content,append:true}) → append without a prior read. After read use edit; replace:true overrides.
+edit(path,oldText,newText) | edit({path,edits}) → numbered post-edit lines, checks, references
+edit(async () => {...}) → checkpoint: commit on success, rollback on throw
 bash(command,{cwd?,timeoutMs?}) → bounded output; nonzero throws
-bash({command,args}) → literal argv, no shell expansion of args
+bash({command,args}) → literal argv
 
-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.`;
+edit oldText is an exact substring of read(); a miss includes a numbered window. Found is a span, not the file. Check resolve:true status; edit(view,text) replaces that window; edit(view,old,new) is unique inside it. complete:true rejects partial files. Array reads reject failures. Edits stage until success; bash commits preceding writes. Batch known reads, edits, and tests in this program (Promise.all, or programs with parallel:true).
+programs:[{code|file,data?},...] sequential fresh guests, separate commits; top-level data defaults per entry. Stop on failure keeps earlier commits. parallel:true runs disjoint entries concurrently. Separate supernova calls only when the next step needs a model decision.
+`;