pi-supernova 0.3.1 → 0.4.0

package/src/fs/vfs.js

@@ -4,6 +4,7 @@ import { isString } from "../shared/decode.js";
 import { randomUUID } from "node:crypto";
 
 const VFS_CACHE_MAX = 1024;
+
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
@@ -16,6 +17,7 @@ export class CausalVfs {
     this.onNewFile = onNewFile;
     this.closed = false;
     this.signal = undefined;
+    this.mutations = { committed: 0, rolledBack: 0, external: 0, pendingCommits: 0, recoveryFailed: false };
   }
 
   assertWritable() {
@@ -38,60 +40,110 @@ export class CausalVfs {
     return [...new Set(this.overlays.flatMap(overlay => [...overlay.keys()]))];
   }
 
-  async read(target, { preserveRead = false } = {}) {
+  async read(target, { preserveRead = false, maxBytes } = {}) {
     const overlay = this.getOverlay(target);
-    if (overlay !== undefined) return overlay;
+
+    if (overlay !== undefined) {
+      if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+
+      return overlay;
+    }
+
     // External editors and captured tools can change a file between any two reads.
     try {
-      const text = await fs.readFile(target, "utf8");
+      let text;
+
+      if (maxBytes === undefined) text = await fs.readFile(target, "utf8");
+      else {
+        const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
+
+        try {
+          const stat = await file.stat();
+
+          if (!stat.isFile()) throw new Error("JSON read requires a regular file: " + target);
+          const tooLarge = () => new Error("JSON input exceeds " + maxBytes + " bytes; use a streaming parser through bash");
+
+          if (stat.size > maxBytes) throw tooLarge();
+          const chunks = [];
+          let size = 0;
+
+          for await (const chunk of file.createReadStream({ end: maxBytes, autoClose: false, signal: this.signal })) {
+            size += chunk.length;
+
+            if (size > maxBytes) throw tooLarge();
+            chunks.push(chunk);
+          }
+
+          text = Buffer.concat(chunks).toString("utf8");
+        } finally { await file.close(); }
+      }
+
       if (!preserveRead || !this.cache.has(target)) this.setCache(target, text);
+
       return text;
     } catch (err) {
       this.cache.delete(target);
+
       if (err.code === "EISDIR") throw new Error("read path is a directory, not a file: " + target);
+
       if (err.code === "ENOENT") {
         const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question)');
         missing.code = "ENOENT";
         throw missing;
       }
+
       throw err;
     }
   }
 
   async write(target, content) {
     this.assertWritable();
+
     if (!isString(content)) throw new Error("write requires string content");
+
     try {
       if ((await fs.stat(target)).isDirectory()) throw new Error("cannot write to a directory: " + target);
     } catch (err) {
       if (err.code !== "ENOENT") throw err;
     }
+
     this.assertWritable();
+
     if (this.getOverlay(target) === undefined) {
       let original;
+
       try { original = this.cache.has(target) ? this.cache.get(target) : await fs.readFile(target, "utf8"); }
       catch (error) { if (error.code !== "ENOENT") throw error; original = null; }
+
       this.expected.set(target, original);
     }
+
     this.assertWritable();
+
     if (this.overlays.length) {
       this.overlays.at(-1).set(target, content);
+
       return { speculative: true };
     }
+
     await this.flush(new Map([[target, content]]));
+
     return { speculative: false };
   }
 
   begin() {
     this.assertWritable();
     this.overlays.push(new Map());
+
     return this.overlays.length;
   }
 
   /** Stage every file and its backup before replacing any destination. */
   async flush(writes) {
-    const work = commitTail.then(() => this.flushWrites(writes));
+    this.mutations.pendingCommits++;
+    const work = commitTail.then(() => this.flushWrites(writes)).finally(() => { this.mutations.pendingCommits--; });
     commitTail = work.catch(() => {});
+
     return work;
   }
 
@@ -100,30 +152,39 @@ export class CausalVfs {
     const targets = new Set();
     const createdDirs = [];
     let failed = false;
+
     try {
       for (const [logicalPath, content] of writes) {
         this.signal?.throwIfAborted();
         let target = logicalPath;
         let stat;
+
         try {
           target = await fs.realpath(logicalPath);
           stat = await fs.stat(target);
+
           if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
         } catch (err) {
           if (err.code !== "ENOENT") throw err;
         }
+
         await this.validateWrite?.(logicalPath);
+
         if (targets.has(target)) throw new Error("conflicting write aliases: " + logicalPath);
         targets.add(target);
+
         if (this.expected.has(logicalPath)) {
           const current = stat ? await fs.readFile(target, "utf8") : null;
+
           if (current !== this.expected.get(logicalPath)) {
             throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
           }
         }
+
         const parent = path.dirname(target);
         const missing = [];
         let probe = parent;
+
         for (;;) {
           try { await fs.stat(probe); break; } catch (err) {
             if (err.code !== "ENOENT") throw err;
@@ -131,38 +192,50 @@ export class CausalVfs {
             probe = path.dirname(probe);
           }
         }
+
         await fs.mkdir(parent, { recursive: true });
         createdDirs.push(...missing.reverse());
         const token = ".supernova-" + randomUUID();
         const entry = { logicalPath, target, content, temporary: path.join(parent, token + ".new"), backup: path.join(parent, token + ".bak"), existed: !!stat, replaced: false };
         staged.push(entry);
+
         const replacement = (async () => {
           await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
+
           if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
         })();
+
         // These touch separate staging files. Settle both before cleanup, even
         // on failure: Promise.all could leave a late backup after rollback.
         const staging = [replacement];
+
         if (stat) staging.push(fs.copyFile(target, entry.backup, fs.constants.COPYFILE_EXCL));
         const outcomes = await Promise.allSettled(staging);
         const failure = outcomes.find(outcome => outcome.status === "rejected");
+
         if (failure) throw failure.reason;
       }
+
       for (const entry of staged) {
         this.signal?.throwIfAborted();
         await fs.rename(entry.temporary, entry.target);
         entry.replaced = true;
       }
+
       for (const entry of staged) {
         this.setCache(entry.logicalPath, entry.content);
         this.expected.delete(entry.logicalPath);
       }
-      if (staged.length) this.onNewFile?.();
+
+      if (staged.length) this.onNewFile?.(staged.map(entry => entry.target));
+      this.mutations.committed += staged.length;
     } catch (error) {
       failed = true;
       const recoveryErrors = [];
+
       for (const entry of staged.toReversed()) {
         if (!entry.replaced) continue;
+
         try {
           if (entry.existed) await fs.rename(entry.backup, entry.target);
           else await fs.unlink(entry.target);
@@ -172,7 +245,13 @@ export class CausalVfs {
           recoveryErrors.push(entry.target + ": " + err.message + " (backup: " + entry.backup + ")");
         }
       }
+
       this.invalidateCache();
+
+      if (recoveryErrors.length) this.mutations.recoveryFailed = true;
+
+      if (recoveryErrors.length) this.onNewFile?.(null);
+
       if (recoveryErrors.length) throw new AggregateError([error, ...recoveryErrors.map(message => new Error(message))], "commit failed: " + error.message + "; recovery failed: " + recoveryErrors.join("; "));
       throw error;
     } finally {
@@ -180,8 +259,10 @@ export class CausalVfs {
         // A successful rename consumed the temporary path. These are known
         // files, so unlink avoids rm's extra type probe; missing files stay benign.
         if (!entry.replaced) await fs.unlink(entry.temporary).catch(() => {});
+
         if (entry.existed && !entry.keepBackup) await fs.unlink(entry.backup).catch(() => {});
       }
+
       if (failed) for (const dir of createdDirs.toReversed()) await fs.rmdir(dir).catch(() => {});
     }
   }
@@ -189,32 +270,46 @@ export class CausalVfs {
   async commit() {
     if (!this.overlays.length) return { committed: 0, depth: 0 };
     const top = this.overlays.at(-1);
+
     if (this.overlays.length > 1) {
       const parent = this.overlays[this.overlays.length - 2];
+
       for (const [key, value] of top) parent.set(key, value);
     } else {
       await this.flush(top);
     }
+
     this.overlays.pop();
+
     return { committed: top.size, depth: this.overlays.length };
   }
 
   rollback() {
     const top = this.overlays.pop();
+    this.mutations.rolledBack += top?.size ?? 0;
+
     for (const target of top?.keys() ?? []) {
       if (this.getOverlay(target) === undefined) this.expected.delete(target);
     }
+
     return { rolledBack: top?.size ?? 0, depth: this.overlays.length };
   }
 
   async prepareExternalMutation(name) {
     this.assertWritable();
+
     if (this.overlays.length > 1) throw new Error(name + " cannot run inside an edit checkpoint because external mutations cannot be rolled back");
-    if (!this.overlays.length) return false;
+
+    if (!this.overlays.length) { this.mutations.external++;
+
+ return false; }
+
     const pending = this.overlays[0];
     await this.flush(pending);
     this.assertWritable();
     this.overlays[0] = new Map();
+    this.mutations.external++;
+
     return pending.size > 0;
   }
 

package/src/fs/workspace.js

@@ -5,10 +5,14 @@ import { constants } from "node:os";
 import { isString } from "../shared/decode.js";
 
 let cachedCwd = null;
+
 let cachedResolvedCwd = null;
+
 // realpath results per program: two syscalls per call otherwise dominate a cached read.
 const realRoots = new Map();
+
 const realNearest = new Map();
+
 const PATH_CACHE_MAX = 2048;
 
 export function clearPathCache() {
@@ -19,6 +23,7 @@ function getResolvedCwd(cwd) {
   if (cwd === cachedCwd && cachedResolvedCwd) return cachedResolvedCwd;
   cachedCwd = cwd;
   cachedResolvedCwd = path.resolve(cwd);
+
   return cachedResolvedCwd;
 }
 
@@ -30,12 +35,14 @@ function assertInside(rel, message) {
 
 async function realpathNearest(target) {
   let probe = target;
+
   while (true) {
     try {
       return await fs.realpath(probe);
     } catch (err) {
       if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
       const parent = path.dirname(probe);
+
       if (parent === probe) throw err;
       probe = parent;
     }
@@ -53,6 +60,7 @@ const TEST_SEGMENTS = new Set(["test", "tests", "__tests__", "spec"]);
 export function isTestPath(filePath) {
   const segments = filePath.split(/[\\/]/);
   const base = segments[segments.length - 1];
+
   return segments.some((s) => TEST_SEGMENTS.has(s)) || /\.(test|spec)\./.test(base);
 }
 
@@ -60,24 +68,34 @@ export async function resolveWorkspacePath(cwd, inputPath, opName, allowRoot = f
   if (inputPath == null || !isString(inputPath) || !inputPath.trim()) {
     throw new Error(`${opName} requires path`);
   }
+
+  if (/^(?:agent|artifact):\/\//i.test(inputPath.trim())) throw new Error(`${opName} requires a filesystem path; session resource URIs are read-only`);
   const resolvedCwd = getResolvedCwd(cwd);
   const target = path.resolve(resolvedCwd, inputPath.trim());
   assertInside(path.relative(resolvedCwd, target), `${opName} path escapes workspace: paths resolve relative to ${resolvedCwd}`);
+
   if (!allowRoot && target === resolvedCwd) {
     throw new Error(`${opName} path cannot be the workspace root directory`);
   }
+
   let realRoot = realRoots.get(resolvedCwd);
+
   if (!realRoot) {
     realRoot = await fs.realpath(resolvedCwd);
     realRoots.set(resolvedCwd, realRoot);
   }
+
   let probe = fresh ? undefined : realNearest.get(target);
+
   if (!probe) {
     probe = await realpathNearest(target);
+
     if (realNearest.size >= PATH_CACHE_MAX) realNearest.clear();
     realNearest.set(target, probe);
   }
+
   assertInside(path.relative(realRoot, probe), `${opName} path escapes workspace through symlink`);
+
   return target;
 }
 
@@ -86,21 +104,25 @@ export async function runCommand(argv, options = {}) {
   const cwd = options.cwd || process.cwd();
   const timeoutMs = options.timeoutMs ?? 60_000;
   const maxOutputChars = options.maxOutputChars ?? 2 * 1024 * 1024;
+
   return new Promise((resolve, reject) => {
     const child = spawn(argv[0], argv.slice(1), {
       cwd, env: options.env ?? process.env, stdio: ["ignore", "pipe", "pipe"], detached: process.platform !== "win32",
     });
+
     let stdout = "";
     let stderr = "";
     let settled = false;
     let outputTruncated = false;
     let terminationError;
     let escalation;
+
     const cleanup = () => {
       clearTimeout(timer);
       clearTimeout(escalation);
       options.signal?.removeEventListener("abort", onAbort);
     };
+
     const fail = error => {
       if (settled) return;
       settled = true;
@@ -110,12 +132,16 @@ export async function runCommand(argv, options = {}) {
       error.stderr = stderr;
       error.outputTruncated = outputTruncated;
       const output = [stdout, stderr].filter(Boolean).join("\n").trimEnd();
+
       if (output) error.message += "\n" + output;
+
       if (outputTruncated) error.message += "\n[output truncated]";
       reject(error);
     };
+
     const signalTree = signal => {
       if (!child.pid) return;
+
       if (process.platform === "win32") {
         const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], { stdio: "ignore" });
         killer.on("error", () => child.kill(signal));
@@ -123,6 +149,7 @@ export async function runCommand(argv, options = {}) {
         try { process.kill(-child.pid, signal); } catch (err) { if (err.code !== "ESRCH") child.kill(signal); }
       }
     };
+
     const terminate = error => {
       if (settled || terminationError) return;
       terminationError = error;
@@ -130,13 +157,18 @@ export async function runCommand(argv, options = {}) {
       // Keep ownership after the direct child exits: descendants may ignore SIGTERM.
       escalation = setTimeout(() => { signalTree("SIGKILL"); fail(error); }, 150);
     };
+
     const onAbort = () => terminate(new Error("aborted"));
     const timer = setTimeout(() => terminate(new Error("command timed out after " + timeoutMs + "ms: " + (options.commandLabel ?? argv.join(" ")))), timeoutMs);
+
     const append = (current, chunk) => {
       const remaining = Math.max(0, maxOutputChars - stdout.length - stderr.length);
+
       if (chunk.length > remaining) outputTruncated = true;
+
       return remaining ? current + chunk.slice(0, remaining) : current;
     };
+
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
     child.stdout.on("data", chunk => { stdout = append(stdout, chunk); });
@@ -144,6 +176,7 @@ export async function runCommand(argv, options = {}) {
     child.on("error", fail);
     child.on("close", (code, signal) => {
       if (settled) return;
+
       if (terminationError) {
         // A closed pipe alone says nothing about descendants. Only ESRCH proves
         // the owned POSIX group is gone; otherwise retain the escalation timer.
@@ -151,13 +184,16 @@ export async function runCommand(argv, options = {}) {
           try { process.kill(-child.pid, 0); }
           catch (error) { if (error.code === "ESRCH") fail(terminationError); }
         }
+
         return;
       }
+
       settled = true;
       cleanup();
       resolve({ stdout, stderr, exitCode: code ?? (128 + (constants.signals[signal] ?? 1)), signal, outputTruncated });
     });
     options.signal?.addEventListener("abort", onAbort, { once: true });
+
     if (options.signal?.aborted) onAbort();
   });
 }

package/src/output/bottleneck.js

@@ -7,61 +7,87 @@ import { truncateChars, formatReturn } from "./format.js";
 function json(value) {
   try { return JSON.stringify(value) ?? "null"; } catch { return JSON.stringify(String(value)); }
 }
+
 function detailsOf(raw) {
   const details = raw?.details;
+
   if (!isString(details)) return details;
+
   try { return JSON.parse(details); } catch { return details; }
 }
+
 export function hostResultFailed(raw) {
   const details = detailsOf(raw);
+
   return raw?.isError === true || details?.ok === false || (Number.isInteger(details?.exitCode) && details.exitCode !== 0);
 }
+
 function extractRawString(raw) {
   if (raw == null) return "";
+
   if (isString(raw)) return raw;
+
   if (!isObject(raw)) return String(raw);
+
   if (Array.isArray(raw.content)) return raw.content.filter(part => part?.type === "text" && isString(part.text)).map(part => part.text).join("\n");
+
   if (isString(raw.text)) return raw.text;
+
   return json(raw);
 }
 
 /** Bound JSON before serialization; preserve small scalar fields such as exitCode. */
 function summarizeDetails(value, budget = 2000) {
   const encoded = json(value);
+
   if (encoded.length <= budget) return encoded;
   const snapshot = JSON.parse(encoded);
+
   const fit = (input, limit) => {
     const serialized = json(input);
+
     if (serialized.length <= limit) return input;
+
     if (isString(input)) {
       let low = 0;
       let high = Math.min(input.length, limit);
+
       while (low < high) {
         const mid = Math.ceil((low + high) / 2);
+
         if (json(truncateChars(input, mid).text).length <= limit) low = mid;
         else high = mid - 1;
       }
+
       return truncateChars(input, low).text;
     }
+
     if (!isObject(input) && !Array.isArray(input)) return null;
     const out = Array.isArray(input) ? [] : { truncated: true };
     const entries = Object.entries(input);
+
     if (!Array.isArray(input)) entries.sort((a, b) => json(a[1]).length - json(b[1]).length);
+
     for (const [key, child] of entries) {
       const used = json(out).length;
       const overhead = Array.isArray(out) ? 1 : json(key).length + 2;
       const available = limit - used - overhead;
+
       if (available < 4) break;
       const bounded = fit(child, available);
+
       if (Array.isArray(out)) out.push(bounded);
       else Object.defineProperty(out, key, { value: bounded, enumerable: true, configurable: true });
+
       if (json(out).length > limit) {
         if (Array.isArray(out)) out.pop();
         else delete out[key];
       }
     }
+
     return out;
   };
+
   return json(fit(snapshot, budget));
 }
 
@@ -70,6 +96,7 @@ function spill(fullText, config) {
   fs.mkdirSync(config.spillDir, { recursive: true, mode: 0o700 });
   const file = path.join(config.spillDir, Date.now() + "-" + randomUUID().slice(0, 8) + ".txt");
   fs.writeFileSync(file, fullText, { encoding: "utf8", mode: 0o600, flag: "wx" });
+
   return file;
 }
 
@@ -82,7 +109,9 @@ export function packageHostResult(raw, config) {
   let truncated = capped.truncated || details?.outputTruncated === true;
   const image = raw?.content?.find(part => part?.type === "image");
   const result = { ok: !hostResultFailed(raw), value: image ?? capped.text, truncated };
+
   if (details !== undefined) result.details = summarizeDetails(batch ? { ...details, items: undefined } : details);
+
   if (batch) {
     result.itemErrors = (details.itemErrors ?? []).map(error => error == null ? null : truncateChars(String(error), Math.max(1, Math.floor(maxChars / batch.length)), "error").text);
     let remaining = maxChars;
@@ -91,16 +120,22 @@ export function packageHostResult(raw, config) {
       const bounded = truncateChars(item, details.independent === true ? maxChars : Math.floor(remaining / (batch.length - index)), "host-result");
       remaining -= bounded.text.length;
       truncated ||= bounded.truncated;
+
       return bounded.text;
     });
   }
+
   result.truncated = truncated;
+
   if (truncated) {
     result.originalChars = batch ? batch.reduce((sum, item) => sum + String(item).length, 0) : text.length;
+
     if (config.spillDir) {
       const pointer = spill(batch ? batch.join("\n---\n") : text, config);
+
       if (pointer) {
         result.spill = pointer;
+
         if (!batch) {
           const footer = "\n[full output spilled to " + pointer + "]";
           result.value = footer.length <= maxChars
@@ -110,32 +145,43 @@ export function packageHostResult(raw, config) {
       }
     }
   }
+
   return result;
 }
 
 export function packageFinalReturn(value, logs, config) {
   const images = [];
   let imageBytes = 0;
+
   const collect = input => {
     if (input?.type === "image" && isString(input.data) && isString(input.mimeType) && input.mimeType.startsWith("image/")) {
       imageBytes += Buffer.byteLength(input.data, "base64");
+
       if (images.length >= 16 || imageBytes > 20 * 1024 * 1024) throw new Error("returned images exceed 16 attachments or 20 MiB; return fewer or smaller images");
       images.push({ type: "image", data: input.data, mimeType: input.mimeType });
+
       return `[image ${images.length}: ${input.mimeType}]`;
     }
+
     if (Array.isArray(input)) return input.map(collect);
+
     if (isObject(input)) return Object.fromEntries(Object.entries(input).map(([key, child]) => [key, collect(child)]));
+
     return input;
   };
+
   value = collect(value);
   const serialized = truncateChars(formatReturn(value), config.maxReturnChars ?? 32000, "return");
   const maxLines = config.maxLogLines ?? 100;
   let logTruncated = logs.length > maxLines;
+
   const clipped = logs.slice(0, maxLines).map(line => {
     const result = truncateChars(line, config.maxLogLineChars ?? 4096, "log");
     logTruncated ||= result.truncated;
+
     return result.text;
   });
+
   return { returnValue: serialized.truncated ? serialized.text : value, returnText: serialized.text,
     returnTruncated: serialized.truncated, logs: clipped, logTruncated, images };
 }