pi-supernova 0.8.2 → 0.9.0

package/src/fs/session-resource.js

@@ -0,0 +1,50 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import {isString} from '../shared/decode.js';
+
+function sessionUriParts(uri) {
+  const match = /^(agent|artifact):\/\/([^/?#]+)$/i.exec(uri);
+
+  if (!match) throw new Error("session resource reads support bare agent://<id> and artifact://<number>; use offset/limit for pagination");
+  const kind = match[1].toLowerCase();
+  const id = decodeURIComponent(match[2]);
+
+  if (!id || id === "." || id === ".." || (/[/\\]/u.test(id) || Array.from(id).some(char => char.charCodeAt(0) < 32)) || (kind === "artifact" && !/^\d+$/.test(id))) throw new Error("invalid session resource ID");
+
+  return { kind, id };
+}
+
+async function findArtifactFile(root, id, uri, signal) {
+  const matches = [];
+  let count = 0;
+
+  for await (const entry of await fs.opendir(root)) {
+    signal?.throwIfAborted();
+
+    if (++count > 4096) throw new Error("session artifact lookup exceeded its directory budget");
+
+    if (entry.name.startsWith(id + ".") && !entry.isDirectory()) matches.push(entry.name);
+  }
+
+  if (matches.length !== 1) throw new Error(matches.length ? "ambiguous session artifact: " + uri : "session artifact not found: " + uri);
+
+  return matches[0];
+}
+
+export async function resolveSessionResource(uri, signal, hooks) {
+  const { kind, id } = sessionUriParts(uri);
+  const dir = hooks.artifactsDir?.();
+
+  if (!isString(dir) || !dir) throw new Error("this host session does not expose an artifacts directory for " + uri);
+  signal?.throwIfAborted();
+  const root = await fs.realpath(dir);
+  const file = kind === "artifact" ? await findArtifactFile(root, id, uri, signal) : id + ".md";
+  const target = await fs.realpath(path.join(root, file));
+
+  if (!target.startsWith(root + path.sep)) throw new Error("session resource escapes its artifacts directory");
+
+  if (!(await fs.stat(target)).isFile()) throw new Error("session resource is not a file: " + uri);
+  signal?.throwIfAborted();
+
+  return target;
+}

package/src/fs/text-ops.js

@@ -1,3 +1,9 @@
+import { fileChunks } from "./file-io.js";
+export {MAX_DIRECTORY_ENTRIES,formatDirectoryEntry,formatLsEntry} from './directory.js';
+export {textResult,resultDiff} from '../shared/result.js';
+import {sliceLinesRaw,lineNumberAt,formatNumberedLine,numberedPreview,lineStartIndex,lineEndIndex,lineTextRange,contentLineInfo} from './lines.js';
+export * from './lines.js';
+export {jsonStringLength,maxJsonStringPrefix} from './json-size.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { homedir } from "node:os";
@@ -5,124 +11,6 @@ import { isString, isNumber, isObject } from "../shared/decode.js";
 import { assertFilesystemPath } from "./workspace.js";
 import { MAX_DIFF_MATCHES } from "./diff.js";
 
-const JSON_TWO_BYTE = new Set([0x22, 0x5c, 8, 9, 10, 12, 13]);
-
-function jsonAsciiWidth(c) {
-  if (JSON_TWO_BYTE.has(c)) return 2;
-
-  if (c < 32) return 6;
-
-  return 1;
-}
-
-function jsonUnitWidth(s, i) {
-  const c = s.charCodeAt(i);
-
-  if (c >= 0xD800 && c <= 0xDBFF && i + 1 < s.length) {
-    const d = s.charCodeAt(i + 1);
-
-    if (d >= 0xDC00 && d <= 0xDFFF) return { add: 2, skip: 2 };
-
-    return { add: 6, skip: 1 };
-  }
-
-  if (c >= 0xD800 && c <= 0xDFFF) return { add: 6, skip: 1 };
-
-  return { add: jsonAsciiWidth(c), skip: 1 };
-}
-
-/** UTF-16 length of JSON.stringify(s) for a string, without allocating the JSON. */
-export function jsonStringLength(s) {
-  let n = 2;
-
-  for (let i = 0; i < s.length; ) {
-    const unit = jsonUnitWidth(s, i);
-    n += unit.add;
-    i += unit.skip;
-  }
-
-  return n;
-}
-
-/** Largest prefix whose JSON.stringify length is <= limit. */
-export function maxJsonStringPrefix(s, limit) {
-  let used = 2;
-  let i = 0;
-
-  while (i < s.length) {
-    const unit = jsonUnitWidth(s, i);
-
-    if (used + unit.add > limit) break;
-    used += unit.add;
-    i += unit.skip;
-  }
-
-  return i;
-}
-
-export function textResult(text, details) {
-  return {
-    content: [{ type: "text", text: String(text ?? "") }],
-    details: details || {},
-  };
-}
-
-export function resultDiff(response) {
-  let details = response?.details;
-
-  if (isString(details)) {
-    try {
-      details = JSON.parse(details);
-    } catch {
-      return undefined;
-    }
-  }
-
-  return isObject(details) ? details.diff : undefined;
-}
-
-function totalContentLines(text) {
-  if (text === "") return 1;
-
-  return contentLineInfo(text).count + (text.endsWith("\n") ? 1 : 0);
-}
-
-function emptySliceInfo(text, totalLines) {
-  return { text: "", end: totalLines, total: totalLines, count: 0, eof: true, whole: totalLines === 1 && text === "" };
-}
-
-function sliceWindow(text, startIndex, count, totalLines) {
-  const endExclusive = Math.min(totalLines, startIndex + count);
-  const start = lineStartIndex(text, startIndex + 1);
-  const end = lineEndIndex(text, start, endExclusive - startIndex);
-  let selected = text.slice(start, end);
-  const eof = endExclusive >= totalLines || (endExclusive === totalLines - 1 && text.endsWith("\n"));
-
-  if (endExclusive < totalLines && !selected.endsWith("\n")) selected += "\n";
-
-  return { text: selected, end: endExclusive, total: totalLines, count: endExclusive - startIndex, eof, whole: startIndex === 0 && eof };
-}
-
-export function sliceLinesRawInfo(text, offset, limit) {
-  const totalLines = totalContentLines(text);
-
-  if (!isNumber(offset) && !isNumber(limit)) {
-    return { text, end: totalLines, total: totalLines, count: totalLines, eof: true, whole: true };
-  }
-
-  const startIndex = (isNumber(offset) ? Math.max(1, Math.floor(offset)) : 1) - 1;
-  const count = isNumber(limit) ? Math.max(0, Math.floor(limit)) : totalLines;
-
-  if (count === 0 || startIndex >= totalLines) return emptySliceInfo(text, totalLines);
-
-  return sliceWindow(text, startIndex, count, totalLines);
-}
-
-/** Read-window slicing preserves the selected lines' own line ending. */
-export function sliceLinesRaw(text, offset, limit) {
-  return sliceLinesRawInfo(text, offset, limit).text;
-}
-
 export function readLineParam(value, name) {
   if (value === undefined) return undefined;
   const number = isNumber(value) ? value : isString(value) && value.trim() !== "" ? Number(value) : NaN;
@@ -173,40 +61,6 @@ export async function probeExistingPath(cwd, targetParam, vfs) {
   }
 }
 
-export const EDIT_PREVIEW_LINES = 16;
-
-export const MAX_DIRECTORY_ENTRIES = 10000;
-
-export function sourceLines(content) {
-  const raw = content.split("\n");
-
-  if (raw.at(-1) === "") raw.pop();
-
-  return raw;
-}
-
-export function lineNumberAt(content, index) {
-  let line = 1;
-
-  for (let i = 0; i < index; i++) if (content.charCodeAt(i) === 10) line++;
-
-  return line;
-}
-
-export function formatNumberedLine(n, text) {
-  return String(n).padStart(5) + " " + text;
-}
-
-export function numberedPreview(content, cap = EDIT_PREVIEW_LINES) {
-  const { count, preview } = contentLineInfo(content, cap);
-
-  if (count === 0) return "0 lines";
-  const body = preview.map((line, i) => formatNumberedLine(i + 1, line)).join("\n");
-  const suffix = count + " lines total";
-
-  return body + "\n" + suffix;
-}
-
 function lineAt(content, n) {
   const range = lineTextRange(content, n);
 
@@ -283,38 +137,6 @@ export function applyReplacements(target, content, requestedEdits) {
   return { updated, matches };
 }
 
-export function lineStartIndex(content, line) {
-  let index = 0;
-
-  for (let current = 1; current < line; current++) {
-    const next = content.indexOf("\n", index);
-
-    if (next < 0) return content.length;
-    index = next + 1;
-  }
-
-  return Math.min(index, content.length);
-}
-
-export function lineEndIndex(content, startIndex, lineCount) {
-  let index = startIndex;
-
-  for (let i = 0; i < lineCount; i++) {
-    const next = content.indexOf("\n", index);
-
-    if (next < 0) return content.length;
-    index = next + 1;
-  }
-
-  return index;
-}
-
-export function lineTextRange(content, line) {
-  const start = lineStartIndex(content, line);
-
-  return { start, end: lineEndIndex(content, start, 1) };
-}
-
 export function shiftDiffLines(diff, delta) {
   if (!diff || delta === 0) return diff;
 
@@ -429,7 +251,7 @@ export async function countContentLines(target, signal) {
     let last = -1;
     let total = 0;
 
-    for await (const chunk of file.createReadStream({ autoClose: false, signal })) {
+    for await (const chunk of fileChunks(file, signal)) {
       for (let i = 0; i < chunk.length; i++) if (chunk[i] === 10) newlines++;
       last = chunk.at(-1);
       total += chunk.length;
@@ -439,26 +261,6 @@ export async function countContentLines(target, signal) {
   } finally { await file.close(); }
 }
 
-export function contentLineInfo(text, previewLimit = 0) {
-  if (text === "") return { count: 0, preview: [], newlines: 0 };
-  const preview = [];
-  let count = 0;
-  let start = 0;
-
-  while (start <= text.length) {
-    const newline = text.indexOf("\n", start);
-    const end = newline < 0 ? text.length : newline;
-
-    if (end === text.length && end === start && text.endsWith("\n")) break;
-    if (preview.length < previewLimit) preview.push(text.slice(start, end).replace(/\r$/, ""));
-    count++;
-    if (newline < 0) break;
-    start = newline + 1;
-  }
-
-  return { count, preview, newlines: count - Number(!text.endsWith("\n")) };
-}
-
 export function boundedEditDiff(target, original, matches) {
   const rendered = matches.slice(0, MAX_DIFF_MATCHES);
   const lines = [];
@@ -498,25 +300,3 @@ export function boundedWriteDiff(target, content, removed) {
     lines: added.preview.map((text, i) => ({ type: "add", lineNum: i + 1, text })),
   };
 }
-
-export function formatDirectoryEntry(name, type, size = 0) {
-  const sizeSuffix = size ? `, ${size} bytes` : "";
-
-  return `${name}${type === "dir" ? "/" : ""} (${type}${sizeSuffix})`;
-}
-
-export async function formatLsEntry(dirPath, entry) {
-  const isDir = entry.isDirectory();
-  const isSym = entry.isSymbolicLink();
-  const typeLabel = isDir ? "dir" : isSym ? "sym" : "file";
-  let size = 0;
-
-  try {
-    if (!isDir && !isSym) {
-      const st = await fs.stat(path.join(dirPath, entry.name));
-      size = st.size;
-    }
-  } catch {}
-
-  return formatDirectoryEntry(entry.name, typeLabel, size);
-}

package/src/fs/vfs.js

@@ -1,248 +1,14 @@
+import {textSignature,sameFileVersion,fileSignature,tooLargeRead,overlayOrThrow,assertReadableFile,readLimitedBytes,remapReadError} from './file-io.js';
+import {resolveCommitTarget,assertExpectedSignature,collectMissingAncestors,makeStageEntry,stageReplacement,installStaged,failCommit,cleanupStaged} from './commit.js';
+export {resolveCommitTarget} from './commit.js';
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { isString } from "../shared/decode.js";
 import { decodeUtf8Strict } from "../shared/utf8.js";
-import { createHash, randomUUID } from "node:crypto";
 
 // Serialize validation + replacement across Supernova transactions in this host.
 let commitTail = Promise.resolve();
 
-function textSignature(text) {
-  return { size: Buffer.byteLength(text, "utf8"), sha256: createHash("sha256").update(text, "utf8").digest("hex") };
-}
-
-function sameFileVersion(a, b) {
-  return ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every(key => a[key] === b[key]);
-}
-
-async function fileSignature(target, signal, observed) {
-  const file = await fs.open(target, fs.constants.O_RDONLY | (fs.constants.O_NONBLOCK ?? 0));
-
-  try {
-    const actual = await file.stat();
-
-    if (!actual.isFile()) throw new Error("read requires a regular file: " + target);
-    if (observed && !sameFileVersion(observed, actual)) throw new Error("file changed while reading: " + target);
-    const hash = createHash("sha256");
-
-    for await (const chunk of file.createReadStream({ autoClose: false, signal })) hash.update(chunk);
-    const after = await file.stat();
-
-    if (!after.isFile() || !sameFileVersion(actual, after)) throw new Error("file changed while signing: " + target);
-
-    return { size: actual.size, sha256: hash.digest("hex") };
-  } finally {
-    await file.close();
-  }
-}
-
-// realpath() cannot resolve a missing leaf. Canonicalize its nearest existing
-// ancestor so two symlink spellings still share one commit destination.
-async function canonicalNewPath(target) {
-  let ancestor = path.dirname(target);
-
-  for (;;) {
-    try { return path.join(await fs.realpath(ancestor), path.relative(ancestor, target)); }
-    catch (error) {
-      if (error.code !== "ENOENT") throw error;
-      const parent = path.dirname(ancestor);
-
-      if (parent === ancestor) throw error;
-      ancestor = parent;
-    }
-  }
-}
-
-function sameSignature(a, b) {
-  return a === b || (a !== null && b !== null && a.size === b.size && a.sha256 === b.sha256);
-}
-
-function tooLargeRead(label, maxBytes) {
-  return new Error(label + " exceeds " + maxBytes + " bytes; use a streaming parser through bash");
-}
-
-function overlayOrThrow(overlay, maxBytes, label) {
-  if (maxBytes !== undefined && Buffer.byteLength(overlay, "utf8") > maxBytes) throw tooLargeRead(label, maxBytes);
-
-  return overlay;
-}
-
-function assertReadableFile(stat, target) {
-  // Callers are reads, writes, edits and patch application: name the path, not the caller.
-  if (stat.isDirectory()) throw new Error("path is a directory, not a file: " + target);
-
-  if (!stat.isFile()) throw new Error("path is not a regular file: " + target);
-}
-
-async function readLimitedBytes(file, stat, maxBytes, label, signal) {
-  if (stat.size > maxBytes) throw tooLargeRead(label, maxBytes);
-  const chunks = [];
-  let size = 0;
-
-  for await (const chunk of file.createReadStream({ end: maxBytes, autoClose: false, signal })) {
-    size += chunk.length;
-
-    if (size > maxBytes) throw tooLargeRead(label, maxBytes);
-    chunks.push(chunk);
-  }
-
-  return Buffer.concat(chunks);
-}
-
-function remapReadError(err, target) {
-  if (err.code === "EISDIR") throw new Error("path is a directory, not a file: " + target);
-
-  if (err.code === "ENOTDIR") throw new Error("cannot use path: a parent component of " + target + " is a file, not a directory");
-  if (err.code === "EACCES" || err.code === "EPERM") throw new Error("permission denied reading " + target + ": check the file mode (for example bash chmod)");
-
-  if (err.code === "ENOENT") {
-    const missing = new Error("no such file: " + target + ' (locate it with read using a directory path or source question; use Promise.allSettled for optional reads to retain successful siblings)');
-    missing.code = "ENOENT";
-    throw missing;
-  }
-
-  throw err;
-}
-
-async function resolveExistingFile(logicalPath) {
-  const target = await fs.realpath(logicalPath);
-  const stat = await fs.stat(target);
-
-  if (!stat.isFile()) throw new Error("cannot write to a non-file: " + logicalPath);
-
-  return { target, stat };
-}
-
-async function resolveCommitTarget(logicalPath) {
-  try {
-    return await resolveExistingFile(logicalPath);
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-
-    return { target: await canonicalNewPath(logicalPath), stat: undefined };
-  }
-}
-
-async function collectMissingAncestors(parent) {
-  const missing = [];
-  let probe = parent;
-
-  for (;;) {
-    try { await fs.stat(probe); break; } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-      missing.push(probe);
-      probe = path.dirname(probe);
-    }
-  }
-
-  return missing;
-}
-
-async function writeTemporary(entry, content, stat) {
-  try {
-    await fs.writeFile(entry.temporary, content, { encoding: "utf8", flag: "wx", mode: stat ? stat.mode & 0o7777 : 0o666 });
-  } catch (error) {
-    // Never leak the temporary name: name the destination and the real cause.
-    if (error?.code === "EACCES" || error?.code === "EPERM") throw new Error("permission denied writing " + entry.target + ": the directory or file is not writable");
-    if (error?.code === "EROFS") throw new Error("cannot write " + entry.target + ": the file system is read-only");
-    if (error?.code === "ENOSPC") throw new Error("cannot write " + entry.target + ": no space left on device");
-
-    throw error;
-  }
-
-  if (stat) await fs.chmod(entry.temporary, stat.mode & 0o7777);
-}
-
-async function stageReplacement(entry, content, stat, target) {
-  const replacement = writeTemporary(entry, content, stat);
-  // 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;
-}
-
-function makeStageEntry(logicalPath, target, content, parent, stat) {
-  const token = ".supernova-" + randomUUID();
-
-  return { logicalPath, target, content, temporary: path.join(parent, token + ".new"), backup: path.join(parent, token + ".bak"), existed: !!stat, replaced: false };
-}
-
-async function recoverReplaced(staged) {
-  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);
-    } catch (err) {
-      // Keep the backup if recovery fails; never delete the remaining original.
-      entry.keepBackup = true;
-      recoveryErrors.push(entry.target + ": " + err.message + " (backup: " + entry.backup + ")");
-    }
-  }
-
-  return recoveryErrors;
-}
-
-async function cleanupStaged(staged, failed, createdDirs) {
-  for (const entry of staged) {
-    // 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(() => {});
-}
-
-async function assertExpectedSignature(vfs, logicalPath, target, stat) {
-  if (!vfs.expected.has(logicalPath)) return;
-  const current = stat ? await fileSignature(target, vfs.signal) : null;
-
-  if (!sameSignature(current, vfs.expected.get(logicalPath))) {
-    throw new Error("write conflict: file changed since it was read: " + logicalPath + "; read it again before retrying");
-  }
-}
-
-async function installStaged(vfs, staged) {
-  for (const entry of staged) {
-    vfs.signal?.throwIfAborted();
-    await fs.rename(entry.temporary, entry.target);
-    entry.replaced = true;
-  }
-
-  for (const entry of staged) {
-    vfs.expected.set(entry.logicalPath, textSignature(entry.content));
-  }
-
-  // Canonical commit destinations must not rewrite established event paths
-  // for newly created files, whose callers supplied a logical cwd spelling.
-  if (staged.length) vfs.onNewFile?.(staged.map(entry => entry.existed ? entry.target : entry.logicalPath));
-}
-
-async function failCommit(vfs, staged, error) {
-  const recoveryErrors = await recoverReplaced(staged);
-  // Keep CAS baselines: a failed commit must not forgive conflicts on files it
-  // never touched. If recovery left disk diverging from a baseline, the next
-  // write to that path fails loudly and forces a re-read instead of silently
-  // re-capturing unknown bytes as the new truth.
-
-  if (recoveryErrors.length) vfs.mutations.recoveryFailed = true;
-
-  if (recoveryErrors.length) vfs.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;
-}
-
 export class CausalVfs {
   constructor(onNewFile, validateWrite) {
     this.validateWrite = validateWrite;
@@ -275,7 +41,7 @@ export class CausalVfs {
   async read(target, { preserveRead = false, maxBytes, label = "read input", strict = true } = {}) {
     const overlay = this.getOverlay(target);
 
-    if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label);
+    if (overlay !== undefined) return overlayOrThrow(overlay, maxBytes, label, target);
 
     // External editors and captured tools can change a file between any two reads.
     // Open once with O_NONBLOCK so a FIFO or device cannot park a host I/O worker.
@@ -288,7 +54,7 @@ export class CausalVfs {
         assertReadableFile(stat, target);
         bytes = maxBytes === undefined
           ? await file.readFile({ signal: this.signal })
-          : await readLimitedBytes(file, stat, maxBytes, label, this.signal);
+          : await readLimitedBytes(file, stat, maxBytes, label, this.signal, () => tooLargeRead(label,maxBytes,target));
         if (!sameFileVersion(stat, await file.stat())) throw new Error("file changed while reading: " + target);
       } finally { await file.close(); }
 

package/src/fs/workspace.js

@@ -1,3 +1,4 @@
+import {remapReadError} from "./file-io.js";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { spawn } from "node:child_process";
@@ -44,7 +45,7 @@ async function realpathNearest(target) {
     try {
       return await fs.realpath(probe);
     } catch (err) {
-      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") throw err;
+      if (err?.code !== "ENOENT" && err?.code !== "ENOTDIR") remapReadError(err, target);
       const parent = path.dirname(probe);
 
       if (parent === probe) throw err;