@evandu/super-pi 0.1.105 → 0.1.106

package/dist/server/content-search.d.ts

@@ -0,0 +1,32 @@
+import type { FileIndexSnapshot } from "./file-index.js";
+export declare const MAX_CONTENT_RESULTS = 500;
+export declare const MAX_CONTENT_FILE_BYTES: number;
+export declare const MAX_CONTENT_DEPTH = 12;
+export declare const MAX_CONTENT_MS = 10000;
+export type ContentSearchCandidate = {
+    path: string;
+    kind: "file" | "directory";
+    text: boolean | null;
+    size: number | null;
+};
+export type ContentSearchHit = {
+    path: string;
+    name: string;
+    line: number;
+    text: string;
+};
+export type ContentSearchResult = {
+    hits: ContentSearchHit[];
+    truncated: boolean;
+    skipped: string[];
+    complete: boolean;
+    reasons: string[];
+};
+/**
+ * SDK probe: createGrepTool(root).execute(id, { pattern, path, literal: true }) works without a
+ * session or running turn (Pi 0.86). Use it for matching. Directory-wide SDK grep would walk a second
+ * tree and cannot accept FileIndex candidates or our per-file containment/size/depth policy.
+ * Instead give it one verified indexed file at a time; validate again before publishing any hit.
+ * The SDK owns ripgrep and its match/byte/line truncation; we expose those limits, never hide them.
+ */
+export declare function searchByContent(root: string, candidates: readonly ContentSearchCandidate[], query: string, indexStatus?: Pick<FileIndexSnapshot, "complete" | "skipped">): Promise<ContentSearchResult>;

package/dist/server/content-search.js

@@ -0,0 +1,155 @@
+import { open } from "node:fs/promises";
+import { basename } from "node:path";
+import { createGrepTool } from "@earendil-works/pi-coding-agent";
+import { isTextName, looksBinary, resolveInsideRoot } from "./files.js";
+export const MAX_CONTENT_RESULTS = 500;
+export const MAX_CONTENT_FILE_BYTES = 512 * 1024;
+export const MAX_CONTENT_DEPTH = 12;
+export const MAX_CONTENT_MS = 10000;
+/**
+ * SDK probe: createGrepTool(root).execute(id, { pattern, path, literal: true }) works without a
+ * session or running turn (Pi 0.86). Use it for matching. Directory-wide SDK grep would walk a second
+ * tree and cannot accept FileIndex candidates or our per-file containment/size/depth policy.
+ * Instead give it one verified indexed file at a time; validate again before publishing any hit.
+ * The SDK owns ripgrep and its match/byte/line truncation; we expose those limits, never hide them.
+ */
+export async function searchByContent(root, candidates, query, indexStatus = { complete: true, skipped: [] }) {
+    await resolveInsideRoot(root, "");
+    const hits = [];
+    const skipped = new Set(indexStatus.skipped);
+    const reasons = new Set(indexStatus.complete ? [] : ["index"]);
+    const needle = query.trim();
+    if (!needle)
+        return { hits, truncated: false, skipped: [...skipped], complete: indexStatus.complete, reasons: [...reasons] };
+    const tool = createGrepTool(root);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), MAX_CONTENT_MS);
+    try {
+        for (const candidate of candidates) {
+            if (candidate.kind !== "file")
+                continue;
+            if (controller.signal.aborted) {
+                reasons.add("time");
+                break;
+            }
+            // Validate even an excluded candidate: metadata and cached paths are not a security boundary.
+            let absolute;
+            try {
+                absolute = await resolveInsideRoot(root, candidate.path);
+            }
+            catch (error) {
+                const code = error.code;
+                if (code === "outside_workspace" || code === "bad_path" || code === "workspace_missing")
+                    throw error;
+                skipped.add(candidate.path);
+                reasons.add("unreadable");
+                continue;
+            }
+            if (candidate.path.replace(/\\/g, "/").split("/").length - 1 > MAX_CONTENT_DEPTH) {
+                skipped.add(candidate.path);
+                reasons.add("depth");
+                continue;
+            }
+            if (candidate.text === false || !isTextName(candidate.path)) {
+                skipped.add(candidate.path);
+                continue;
+            }
+            let bytes;
+            try {
+                // Read at most cap+1 bytes even if a file grows after stat; never allocate its untrusted size.
+                const handle = await open(absolute, "r");
+                try {
+                    const info = await handle.stat();
+                    if (!info.isFile()) {
+                        skipped.add(candidate.path);
+                        reasons.add("unreadable");
+                        continue;
+                    }
+                    if (info.size > MAX_CONTENT_FILE_BYTES) {
+                        skipped.add(candidate.path);
+                        reasons.add("size");
+                        continue;
+                    }
+                    const buffer = Buffer.alloc(MAX_CONTENT_FILE_BYTES + 1);
+                    let length = 0;
+                    while (length < buffer.length) {
+                        const read = await handle.read(buffer, length, buffer.length - length, null);
+                        if (!read.bytesRead)
+                            break;
+                        length += read.bytesRead;
+                    }
+                    if (length > MAX_CONTENT_FILE_BYTES) {
+                        skipped.add(candidate.path);
+                        reasons.add("size");
+                        continue;
+                    }
+                    bytes = buffer.subarray(0, length);
+                }
+                finally {
+                    await handle.close();
+                }
+            }
+            catch {
+                skipped.add(candidate.path);
+                reasons.add("unreadable");
+                continue;
+            }
+            if (looksBinary(bytes) || bytes.includes(0)) {
+                skipped.add(candidate.path);
+                continue;
+            }
+            try {
+                new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+            }
+            catch {
+                skipped.add(candidate.path);
+                continue;
+            }
+            let result;
+            try {
+                result = await tool.execute("content-search", {
+                    pattern: needle, path: absolute, literal: true, limit: MAX_CONTENT_RESULTS - hits.length,
+                }, controller.signal);
+            }
+            catch (error) {
+                if (controller.signal.aborted) {
+                    reasons.add("time");
+                    break;
+                }
+                // SDK/ripgrep failures are request failures, never a successful empty search.
+                throw error;
+            }
+            const prefix = basename(absolute) + ":";
+            const rows = [];
+            for (const block of result.content) {
+                if (block.type !== "text")
+                    continue;
+                for (const row of block.text.split("\n")) {
+                    if (!row.startsWith(prefix))
+                        continue;
+                    const match = /^(\d+): (.*)$/.exec(row.slice(prefix.length));
+                    if (!match)
+                        continue;
+                    rows.push({ path: candidate.path, name: basename(absolute), line: Number(match[1]), text: match[2] });
+                }
+            }
+            if (rows.length) {
+                await resolveInsideRoot(root, candidate.path);
+                hits.push(...rows.slice(0, MAX_CONTENT_RESULTS - hits.length));
+            }
+            const details = result.details;
+            if (details?.truncation?.truncated)
+                reasons.add("output");
+            if (details?.linesTruncated)
+                reasons.add("line");
+            if (details?.matchLimitReached || hits.length >= MAX_CONTENT_RESULTS) {
+                reasons.add("results");
+                break;
+            }
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { hits, truncated: reasons.size > 0, skipped: [...skipped], complete: indexStatus.complete, reasons: [...reasons] };
+}

package/dist/server/file-changes.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The tools whose arguments name a file the agent is about to WRITE.
+ *
+ * `edit` and `write` are Pi's two file-writing tools (`node_modules/@earendil-works/pi-coding-agent/
+ * dist/core/tools/`), and `notebookedit` is the third in the family that edits a notebook. The list is
+ * deliberately narrow: a `read` names a file too, and a `read` changes nothing, so treating it as a
+ * change would mark a file the agent merely LOOKED at as one it edited - and a marker that lies is worse
+ * than no marker, because the user's trust in every other marker goes with it.
+ *
+ * The names are matched case-insensitively and after trimming, because the name comes off a wire and a
+ * tool named "Edit" is the same tool.
+ */
+export declare const FILE_WRITING_TOOLS: Set<string>;
+/**
+ * The path an argument names, or `undefined` when the arguments name none.
+ *
+ * NOT a display string. `describeToolCall` collapses whitespace and caps the length, which is right for
+ * a card and wrong for a path that is about to be read off the disk - a path with a run of spaces in it
+ * would be reported as a path with one space, and the file would not be found. This returns the value
+ * as the tool spelled it, so the caller can resolve it properly.
+ *
+ * The value is NOT validated here. The caller resolves it against the workspace root and refuses
+ * anything that leaves it - the containment rule lives in `files.ts` and has exactly one owner, and this
+ * module does not get a second, weaker copy of it.
+ */
+export declare function toolTargetPath(name: string, args: unknown): string | undefined;
+/**
+ * One recorded change: a file the agent wrote, and what it looked like before.
+ *
+ * `before` is the content as it was on disk when the write was announced, or `null` when the file did
+ * not exist then - which is how a NEW file is told apart from an EDITED one, and the two are different
+ * things to a reader. `null` is also the honest value for a file this server never saw the contents of
+ * (too large, binary, unreadable), and `beforeUnknown` says which of those it was.
+ */
+export type RecordedChange = {
+    /** Workspace-relative, `/`-separated - the same spelling every other file path uses on the wire. */
+    path: string;
+    /** The content before the agent's write, or `null` when there was none (a new file, or unreadable). */
+    before: string | null;
+    /** True when `before` is `null` because the content could not be read, rather than because the file
+     *  did not exist. The difference matters to the diff view: "the file is new" and "we could not read
+     *  the old version" are different facts and the reader is told which one happened. */
+    beforeUnknown: boolean;
+    /**
+     * THE ETAG OF THE FILE AS IT WAS WHEN THE BASELINE WAS TAKEN.
+     *
+     * This is what makes the baseline TRUSTWORTHY rather than merely plausible. See `confirm` below.
+     */
+    etag?: string;
+    /** When the change was recorded, so the panel can order a turn's changes the way they happened. */
+    at: number;
+    /** The conversation the change belongs to, so a workspace's changes can be attributed to a session. */
+    conversationId?: string;
+};
+export declare class FileChangeTracker {
+    #private;
+    /**
+     * Records that the agent is about to write `path`, capturing the current content as the baseline.
+     *
+     * Called when the tool call is ANNOUNCED, not when it ends. The announcement is the last moment the
+     * old bytes are still on the disk: by the time the tool has finished, the file already holds the new
+     * content and the baseline is gone forever. This is the whole reason the tracker reads the disk at
+     * all.
+     *
+     * A file that is already tracked is NOT re-baselined. Re-baselining would set the "before" to the
+     * agent's own intermediate state, and the diff would then show only the LAST edit rather than
+     * everything the agent did to the file in this turn - which is the thing a reviewer needs to see.
+     *
+     * THE READ IS SYNCHRONOUS, and that is the whole reason this feature works.
+     *
+     * Pi announces a tool call and then RUNS it, and it does not wait for this server to acknowledge the
+     * announcement. So the tool may well have written the file by the time this server gets around to
+     * reading it - and an ASYNCHRONOUS read loses that race almost every time, because the read is queued
+     * behind the very write it is trying to get ahead of. The first version of this was asynchronous, and
+     * the symptom was a diff that said "+0 / -0": the baseline it captured was the file's NEW content,
+     * because by the time the read happened the agent had already written.
+     *
+     * A synchronous read cannot lose that race in the same way - it happens in the same tick the
+     * announcement was parsed, before anything else can run - and the cost is bounded by the size cap
+     * below. A blocked event loop for the length of one small file read, once per agent write, is a far
+     * better trade than a diff that shows nothing.
+     */
+    record(workspaceId: string, path: string, options: {
+        conversationId?: string;
+        root: string;
+    }): void;
+    /**
+     * CONFIRMS A BASELINE, once the agent's write has finished.
+     *
+     * The synchronous read makes the baseline correct in practice, but "in practice" is not a guarantee:
+     * if the tool somehow ran before the announcement was processed, the baseline would be the file's NEW
+     * content and the diff would show nothing at all - a diff that says "no change" about a file the
+     * agent just rewrote, which is the worst possible lie this feature could tell.
+     *
+     * So the baseline is CHECKED rather than trusted. The file's etag after the write must DIFFER from
+     * the etag the baseline was taken at - and if it does not, the baseline was taken after the write and
+     * is worthless. The change is then marked as having no usable "before", and the diff view says so
+     * instead of showing an empty diff.
+     *
+     * The one case this cannot tell apart is a write that changed nothing (the agent wrote identical
+     * bytes). There the baseline and the file agree, and the diff is empty - which is CORRECT, because
+     * nothing changed. The reader is told the before-version is unconfirmed, which is true in both cases.
+     */
+    confirm(workspaceId: string, path: string, root: string): void;
+    /**
+     * The changes recorded for a workspace, newest first.
+     *
+     * `dropped` says how many baselines were evicted, so the panel can say so rather than quietly showing
+     * a shorter list than the agent actually produced.
+     */
+    list(workspaceId: string): {
+        changes: RecordedChange[];
+        dropped: number;
+    };
+    /** The recorded change for one path, or `undefined` when there is none. */
+    get(workspaceId: string, path: string): RecordedChange | undefined;
+    /** Forgets a workspace's changes. Used when the workspace is deleted. */
+    forget(workspaceId: string): void;
+}

package/dist/server/file-changes.js

@@ -0,0 +1,278 @@
+/**
+ * WHAT THE AGENT CHANGED, AND WHAT IT LOOKED LIKE BEFORE.
+ *
+ * WHY THIS FILE EXISTS. The Files panel could show a file, but it could not show a CHANGE - and a panel
+ * that cannot show a change is a file browser, not a workbench. The user asked for the opposite of a
+ * browser: "看得到文件才能更好地支持 ai 的改动" - being able to SEE the files is what makes the agent's
+ * edits reviewable. Reviewing an edit means seeing two things: WHICH files were touched, and WHAT
+ * changed in them. Neither existed.
+ *
+ * THE SERVICE ALREADY KNEW THE FIRST HALF AND THREW IT AWAY. `tool-calls.ts` reads a tool's target path
+ * out of its arguments to draw one line on a card ("edit src/server/files.ts"). That line was the ONLY
+ * place the information existed, and it was never sent to the Files panel - the WS protocol had no file
+ * event at all, so a file the agent rewrote looked exactly like a file it had never touched.
+ *
+ * WHY THE PATHS ARE READ FROM THE ARGUMENTS RATHER THAN GUESSED FROM A WATCHER. A watcher sees bytes
+ * changing; it does not see WHO changed them, and it cannot distinguish the agent's edit from an
+ * unrelated build step. The tool call is the agent saying "I am about to change this path" in its own
+ * words - the most reliable source available, and one that costs nothing to read.
+ *
+ * WHY THE "BEFORE" CONTENT IS CAPTURED HERE RATHER THAN RECOVERED LATER. Once the agent has written the
+ * file, the old bytes are gone from the disk. A diff needs a baseline, and the baseline has to be taken
+ * BEFORE the write. So this file keeps a copy of the content as it was, taken when the agent's write
+ * tool was announced - the last moment the old content is still on disk.
+ *
+ * WHAT THIS FILE DOES NOT DO. It does not watch the disk. An external editor saving a file is noticed by
+ * the CLIENT's existing poll (`?meta=1` on open files), not here - and that asymmetry is deliberate: this
+ * file is about the agent's changes, which is the half only the server can see. It does not keep a full
+ * copy of every file: only the files the agent actually wrote, and only until the diff is read.
+ */
+import { readFileSync, statSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+/**
+ * The tools whose arguments name a file the agent is about to WRITE.
+ *
+ * `edit` and `write` are Pi's two file-writing tools (`node_modules/@earendil-works/pi-coding-agent/
+ * dist/core/tools/`), and `notebookedit` is the third in the family that edits a notebook. The list is
+ * deliberately narrow: a `read` names a file too, and a `read` changes nothing, so treating it as a
+ * change would mark a file the agent merely LOOKED at as one it edited - and a marker that lies is worse
+ * than no marker, because the user's trust in every other marker goes with it.
+ *
+ * The names are matched case-insensitively and after trimming, because the name comes off a wire and a
+ * tool named "Edit" is the same tool.
+ */
+export const FILE_WRITING_TOOLS = new Set(["edit", "write", "notebookedit", "multiedit"]);
+/**
+ * The argument fields that name the file, in the order the tools tend to spell them.
+ *
+ * The same list `tool-calls.ts` uses to draw its one-line summary, and deliberately the same ORDER: two
+ * tables that disagree about which field wins would make the card say "src/a.ts" and the change tracker
+ * say "src/b.ts" for the same call, and the user would have no way to tell which one is right.
+ *
+ * `notebook_path` is here because the notebook tools spell it that way, and it is checked before the
+ * generic `path` only because the notebook tools have no plain `path` field to collide with.
+ */
+const PATH_KEYS = ["path", "file_path", "filePath", "target_file", "filename", "file", "notebook_path"];
+/**
+ * The path an argument names, or `undefined` when the arguments name none.
+ *
+ * NOT a display string. `describeToolCall` collapses whitespace and caps the length, which is right for
+ * a card and wrong for a path that is about to be read off the disk - a path with a run of spaces in it
+ * would be reported as a path with one space, and the file would not be found. This returns the value
+ * as the tool spelled it, so the caller can resolve it properly.
+ *
+ * The value is NOT validated here. The caller resolves it against the workspace root and refuses
+ * anything that leaves it - the containment rule lives in `files.ts` and has exactly one owner, and this
+ * module does not get a second, weaker copy of it.
+ */
+export function toolTargetPath(name, args) {
+    if (typeof name !== "string")
+        return undefined;
+    if (!FILE_WRITING_TOOLS.has(name.trim().toLowerCase()))
+        return undefined;
+    if (args === null || typeof args !== "object" || Array.isArray(args))
+        return undefined;
+    const record = args;
+    for (const key of PATH_KEYS) {
+        const value = record[key];
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (trimmed)
+            return trimmed;
+    }
+    return undefined;
+}
+/**
+ * The changes recorded for one workspace, and the old contents they need.
+ *
+ * BOUNDED ON PURPOSE, in two directions. The number of entries is capped because a long session can
+ * touch a lot of files, and the copy of every old version is the memory cost of this feature. The size
+ * of ONE old version is capped because a single 5MB file would otherwise be the whole budget.
+ *
+ * When a cap is reached, the OLDEST entry is dropped, and `dropped` counts how many were dropped. That
+ * count is reported rather than hidden: a diff view that says "this file changed" and then cannot show
+ * the change because the baseline was evicted is a worse experience than one that says "the baseline for
+ * this file is no longer available", and the second is what the count makes possible.
+ */
+const MAX_TRACKED_CHANGES = 200;
+const MAX_BASELINE_BYTES = 1024 * 1024;
+/**
+ * The identity of a file's current bytes - the same formula `files.ts` uses, so the two agree.
+ *
+ * Size, nanosecond modification time and inode: the two fields together change on any edit a human
+ * would call an edit, and `bigint` is what makes the modification time exact - the millisecond float
+ * `stat` reports by default rounds two edits inside the same millisecond into one value, and a check
+ * that misses a change is worse than no check.
+ */
+function etagOf(size, mtimeNs, ino) {
+    return createHash("sha1").update(`${size}:${mtimeNs}:${ino}`).digest("hex").slice(0, 20);
+}
+export class FileChangeTracker {
+    /** Workspace id -> path -> the change recorded for it. A path is recorded once: the LAST change to a
+     *  file wins, because a file edited three times in a turn is one file with one final state, and the
+     *  reader wants the diff from before the FIRST change to after the LAST one. */
+    #byWorkspace = new Map();
+    /** How many changes were dropped because the cap was reached, per workspace. */
+    #dropped = new Map();
+    /**
+     * Records that the agent is about to write `path`, capturing the current content as the baseline.
+     *
+     * Called when the tool call is ANNOUNCED, not when it ends. The announcement is the last moment the
+     * old bytes are still on the disk: by the time the tool has finished, the file already holds the new
+     * content and the baseline is gone forever. This is the whole reason the tracker reads the disk at
+     * all.
+     *
+     * A file that is already tracked is NOT re-baselined. Re-baselining would set the "before" to the
+     * agent's own intermediate state, and the diff would then show only the LAST edit rather than
+     * everything the agent did to the file in this turn - which is the thing a reviewer needs to see.
+     *
+     * THE READ IS SYNCHRONOUS, and that is the whole reason this feature works.
+     *
+     * Pi announces a tool call and then RUNS it, and it does not wait for this server to acknowledge the
+     * announcement. So the tool may well have written the file by the time this server gets around to
+     * reading it - and an ASYNCHRONOUS read loses that race almost every time, because the read is queued
+     * behind the very write it is trying to get ahead of. The first version of this was asynchronous, and
+     * the symptom was a diff that said "+0 / -0": the baseline it captured was the file's NEW content,
+     * because by the time the read happened the agent had already written.
+     *
+     * A synchronous read cannot lose that race in the same way - it happens in the same tick the
+     * announcement was parsed, before anything else can run - and the cost is bounded by the size cap
+     * below. A blocked event loop for the length of one small file read, once per agent write, is a far
+     * better trade than a diff that shows nothing.
+     */
+    record(workspaceId, path, options) {
+        const relativePath = this.#relative(options.root, path);
+        if (!relativePath)
+            return;
+        const changes = this.#byWorkspace.get(workspaceId) ?? new Map();
+        this.#byWorkspace.set(workspaceId, changes);
+        if (changes.has(relativePath))
+            return;
+        let before = null;
+        let beforeUnknown = false;
+        let etag;
+        try {
+            const absolute = resolve(options.root, path);
+            // The size is checked BEFORE the read, so an oversized file costs one stat rather than a buffer.
+            const info = statSync(absolute, { bigint: true });
+            if (info.size > MAX_BASELINE_BYTES) {
+                // A baseline larger than the cap is not a baseline - it is a memory cost with no diff to show
+                // for it. The change is still recorded (the file WAS changed, and that fact is worth knowing);
+                // what is dropped is the ability to show what it was, which `beforeUnknown` says out loud.
+                beforeUnknown = true;
+            }
+            else {
+                before = readFileSync(absolute, "utf8");
+                etag = etagOf(info.size, info.mtimeNs, info.ino);
+            }
+        }
+        catch (error) {
+            const code = error?.code;
+            // ENOENT is the ordinary case of a NEW file, and it is a fact rather than a failure: the file did
+            // not exist before the agent created it, so there is no "before" to show. Anything else (a
+            // permission problem, a directory) means we simply do not know, and the two are told apart by
+            // `beforeUnknown`.
+            beforeUnknown = code !== "ENOENT" && code !== "ENOTDIR";
+        }
+        changes.set(relativePath, {
+            path: relativePath,
+            before,
+            beforeUnknown,
+            ...(etag ? { etag } : {}),
+            at: Date.now(),
+            ...(options.conversationId ? { conversationId: options.conversationId } : {}),
+        });
+        if (changes.size > MAX_TRACKED_CHANGES) {
+            // The OLDEST goes, because a reviewer is looking at the most recent work. `Map` preserves
+            // insertion order, so the first key is the oldest.
+            const oldest = changes.keys().next();
+            if (!oldest.done) {
+                changes.delete(oldest.value);
+                this.#dropped.set(workspaceId, (this.#dropped.get(workspaceId) ?? 0) + 1);
+            }
+        }
+    }
+    /**
+     * CONFIRMS A BASELINE, once the agent's write has finished.
+     *
+     * The synchronous read makes the baseline correct in practice, but "in practice" is not a guarantee:
+     * if the tool somehow ran before the announcement was processed, the baseline would be the file's NEW
+     * content and the diff would show nothing at all - a diff that says "no change" about a file the
+     * agent just rewrote, which is the worst possible lie this feature could tell.
+     *
+     * So the baseline is CHECKED rather than trusted. The file's etag after the write must DIFFER from
+     * the etag the baseline was taken at - and if it does not, the baseline was taken after the write and
+     * is worthless. The change is then marked as having no usable "before", and the diff view says so
+     * instead of showing an empty diff.
+     *
+     * The one case this cannot tell apart is a write that changed nothing (the agent wrote identical
+     * bytes). There the baseline and the file agree, and the diff is empty - which is CORRECT, because
+     * nothing changed. The reader is told the before-version is unconfirmed, which is true in both cases.
+     */
+    confirm(workspaceId, path, root) {
+        const changes = this.#byWorkspace.get(workspaceId);
+        if (!changes)
+            return;
+        // The path is spelled the way the tracker spells it - workspace-relative, `/`-separated - and the
+        // caller may hold the tool's own spelling, so both are tried.
+        const relativePath = this.#relative(root, path);
+        const change = (relativePath ? changes.get(relativePath) : undefined) ?? changes.get(path);
+        if (!change || !change.etag)
+            return;
+        try {
+            const info = statSync(resolve(root, change.path), { bigint: true });
+            const current = etagOf(info.size, info.mtimeNs, info.ino);
+            if (current === change.etag) {
+                // The file is byte-for-byte what the baseline says it was, so the baseline was taken AFTER the
+                // write - or nothing changed at all. Either way it cannot be shown as "before".
+                change.before = null;
+                change.beforeUnknown = true;
+            }
+        }
+        catch {
+            // The file is gone: the agent DELETED it, which is a change of its own. The baseline stands.
+        }
+    }
+    /**
+     * The changes recorded for a workspace, newest first.
+     *
+     * `dropped` says how many baselines were evicted, so the panel can say so rather than quietly showing
+     * a shorter list than the agent actually produced.
+     */
+    list(workspaceId) {
+        const changes = [...(this.#byWorkspace.get(workspaceId)?.values() ?? [])];
+        changes.reverse();
+        return { changes, dropped: this.#dropped.get(workspaceId) ?? 0 };
+    }
+    /** The recorded change for one path, or `undefined` when there is none. */
+    get(workspaceId, path) {
+        return this.#byWorkspace.get(workspaceId)?.get(path);
+    }
+    /** Forgets a workspace's changes. Used when the workspace is deleted. */
+    forget(workspaceId) {
+        this.#byWorkspace.delete(workspaceId);
+        this.#dropped.delete(workspaceId);
+    }
+    /**
+     * The path as the rest of the app spells it: workspace-relative, `/`-separated, no leading slash.
+     *
+     * REFUSES ANYTHING OUTSIDE THE ROOT, rather than clamping it. A tool that names `../outside.txt` is
+     * either broken or hostile, and a "relative path" that silently becomes `../outside.txt` would be a
+     * path the panel would then try to read. The containment decision itself belongs to `files.ts`; this
+     * is only about the SPELLING, and it declines to spell a path it cannot vouch for.
+     */
+    #relative(root, path) {
+        const base = resolve(root);
+        const absolute = isAbsolute(path) ? resolve(path) : resolve(base, path);
+        const rel = relative(base, absolute);
+        if (rel === "")
+            return null;
+        if (isAbsolute(rel))
+            return null;
+        if (rel === ".." || rel.startsWith(`..${sep}`) || rel.startsWith("../"))
+            return null;
+        return rel.split(sep).join("/");
+    }
+}

package/dist/server/file-diff.d.ts

@@ -0,0 +1,38 @@
+import type { FileChangeTracker } from "./file-changes.js";
+/**
+ * WHERE THE "BEFORE" CAME FROM. The client renders a different label for each, because they are
+ * different claims: "this is what the agent changed" and "this is what the repository had committed"
+ * are not the same sentence, and a diff shown without knowing which one it is against is a diff the
+ * reader has to guess about.
+ */
+export type DiffBaselineKind = "agent" | "git" | "none";
+export type FileDiff = {
+    /** The file, workspace-relative and `/`-separated. */
+    path: string;
+    /** Which baseline was used. */
+    baseline: DiffBaselineKind;
+    /** The content before, or `null` when there was none - which is how a NEW file is told from an
+     *  EDITED one. */
+    before: string | null;
+    /** True when the "before" could not be READ, as opposed to not existing. A diff against an empty
+     *  "before" for a file that existed would be a lie, and this is what keeps it from being one. */
+    beforeUnknown?: boolean;
+    /** The content now, or `null` when the file is gone. */
+    after: string | null;
+    /** A sentence naming the baseline, for the view to show. */
+    label: string;
+};
+/**
+ * The diff of one file, with the best baseline available.
+ *
+ * `preferred` says which baseline the caller wants. `auto` means "pick the best one", which is what
+ * the review view asks for; naming a specific baseline means the user has been told which comparison
+ * they are looking at and it must not silently become a different one.
+ */
+export declare function computeFileDiff(options: {
+    root: string;
+    path: string;
+    preferred?: "auto" | DiffBaselineKind;
+    tracker?: FileChangeTracker;
+    workspaceId?: string;
+}): Promise<FileDiff>;