@evandu/super-pi 0.1.105 → 0.1.106

package/dist/server/file-diff.js

@@ -0,0 +1,97 @@
+/**
+ * THE DIFF BETWEEN WHAT A FILE WAS AND WHAT IT IS NOW.
+ *
+ * WHY THE SERVER SENDS TWO TEXTS RATHER THAN A DIFF. The difference between two texts is computed by
+ * an algorithm, and there are good ones (jsdiff, on the client). Sending a diff instead would mean the
+ * server owns a second implementation of that algorithm, and the two would disagree at the edges - a
+ * hunk boundary, an empty file, a file with no trailing newline. Sending the two TEXTS means there is
+ * exactly ONE implementation of "what is the difference between these two strings" in the whole
+ * product, and the server's job is reduced to the one thing only it can do: produce the "before".
+ *
+ * WHERE THE "BEFORE" COMES FROM, in the order the user cares about.
+ *
+ * 1. THE AGENT'S OWN BASELINE. The server captured the file's content at the moment the agent's write
+ *    tool was announced (`file-changes.ts`), so this is the exact content the agent started from. It is
+ *    the right answer for "what did the agent just do", and it works in a directory that is not a git
+ *    repository - which is most of them, for a user who has not initialised a repo.
+ * 2. GIT'S COMMITTED VERSION. For a file in a git repository, `HEAD` is a baseline that exists even
+ *    when the server was not running when the change was made, and it is the baseline a reviewer
+ *    already has in mind.
+ * 3. NOTHING. When neither exists - a brand new file in a directory that is not a repository, with no
+ *    agent change to reconstruct - the answer is that there is no baseline, and the view says so
+ *    rather than showing a diff against nothing.
+ *
+ * The BUFFER is the fourth baseline and it does not come from the server: the "before" of a buffer is
+ * the file on disk and the "after" is what the user has typed, and the client already holds both. So
+ * the client computes that one itself and never asks.
+ */
+import { readFile } from "node:fs/promises";
+import { gitHeadContent, isGitRepository } from "./git.js";
+import { FilesError, resolveInsideRoot } from "./files.js";
+/**
+ * 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 async function computeFileDiff(options) {
+    const { root, path, preferred = "auto", tracker, workspaceId } = options;
+    const after = await readAfter(root, path);
+    // The agent's baseline. It is the RIGHT one whenever it exists, because it is the content the agent
+    // actually started from - which is not necessarily HEAD, and not necessarily what the file looked
+    // like when the server started.
+    const agentChange = tracker && workspaceId ? tracker.get(workspaceId, path) : undefined;
+    if ((preferred === "auto" || preferred === "agent") && agentChange) {
+        return {
+            path,
+            baseline: "agent",
+            before: agentChange.before,
+            ...(agentChange.beforeUnknown ? { beforeUnknown: true } : {}),
+            after,
+            label: agentChange.before === null && !agentChange.beforeUnknown
+                ? "这个文件是 agent 新建的"
+                : "agent 改动前",
+        };
+    }
+    if (preferred === "auto" || preferred === "git") {
+        if (await isGitRepository(root)) {
+            const head = await gitHeadContent(root, path);
+            if (head !== null) {
+                return { path, baseline: "git", before: head, after, label: "Git 已提交的版本" };
+            }
+        }
+    }
+    if (preferred === "agent" && !agentChange) {
+        // The caller ASKED for the agent's baseline and there is none. Saying so is the honest answer; a
+        // silent fall-back to git would show the user a comparison they did not ask for.
+        return { path, baseline: "none", before: null, after, label: "没有 agent 改动前的版本可比较" };
+    }
+    return { path, baseline: "none", before: null, after, label: "没有可比较的基线" };
+}
+/**
+ * The file's content now, or `null` when it is gone.
+ *
+ * A MISSING FILE IS NOT AN ERROR. The agent deleting a file is a change the user needs to see, and a
+ * diff view that refused to open because the file no longer exists would refuse to show exactly the
+ * change that matters most.
+ *
+ * THE PATH GOES THROUGH `resolveInsideRoot`, like every other path this server reads. The path arrives
+ * from a browser, so it is untrusted, and the question "does this resolve to somewhere inside the
+ * workspace" has exactly one owner in this codebase (`files.ts`). A second, weaker copy of the check
+ * here would be a check that is correct once.
+ */
+async function readAfter(root, path) {
+    try {
+        const target = await resolveInsideRoot(root, path);
+        return await readFile(target, "utf8");
+    }
+    catch (error) {
+        // A file that is GONE is a fact the diff reports; a path that ESCAPES the workspace is a refusal
+        // the route turns into a 403. They are told apart here so the route can do the right thing with
+        // each, rather than both becoming "no content".
+        if (error instanceof FilesError && (error.status === 403 || error.code === "outside_workspace"))
+            throw error;
+        return null;
+    }
+}

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

@@ -0,0 +1,56 @@
+import { type FileMeta } from "./files.js";
+export type IndexedFile = {
+    path: string;
+    kind: "file" | "directory";
+    size: number | null;
+    mtimeMs: number | null;
+    etag: string | null;
+    text: boolean | null;
+};
+export type FileIndexEvent = {
+    type: "files.index";
+    workspaceId: string;
+    version: number;
+    changed: IndexedFile[];
+    removed: string[];
+    complete: boolean;
+    skipped: string[];
+};
+export type FileIndexSnapshot = {
+    version: number;
+    builtAt: number;
+    complete: boolean;
+    changed: IndexedFile[];
+    removed: string[];
+    skipped: string[];
+};
+/**
+ * Per-workspace index. The background pass uses readdir only because measurements on this repository
+ * show directory enumeration under a second while stat for every entry costs 2-3 seconds. Most entries
+ * deliberately have no etag: an etag belongs to a file a user has opened or a known write has touched,
+ * where the existing read/write metadata already paid for it. The client polls only those open files.
+ */
+export declare class FileIndex {
+    readonly workspaceId: string;
+    private readonly broadcast;
+    readonly entries: Map<string, IndexedFile>;
+    private readonly history;
+    private root;
+    private queue;
+    private building;
+    private skipped;
+    version: number;
+    builtAt: number;
+    complete: boolean;
+    constructor(workspaceId: string, broadcast: (event: FileIndexEvent) => void);
+    start(root: string): void;
+    stop(): void;
+    snapshot(since?: number): FileIndexSnapshot;
+    refresh(path: string): Promise<void>;
+    /** Record metadata already obtained by opening, saving, or polling an open file. No second stat: the
+     * caller's file API operation has already passed the sole containment guard and read this metadata. */
+    recordFile(path: string, meta: FileMeta, mtimeMs?: number): void;
+    remove(path: string): void;
+    private scan;
+    private publish;
+}

package/dist/server/file-index.js

@@ -0,0 +1,150 @@
+import { readdir, stat } from "node:fs/promises";
+import { SEARCH_SKIP_DIRS, createRootGuard, fileMeta, isTextName, toRelative } from "./files.js";
+const MAX_DIRECTORIES = 4000;
+const MAX_FILES = 30000;
+const MAX_MS = 4000;
+/**
+ * Per-workspace index. The background pass uses readdir only because measurements on this repository
+ * show directory enumeration under a second while stat for every entry costs 2-3 seconds. Most entries
+ * deliberately have no etag: an etag belongs to a file a user has opened or a known write has touched,
+ * where the existing read/write metadata already paid for it. The client polls only those open files.
+ */
+export class FileIndex {
+    workspaceId;
+    broadcast;
+    entries = new Map();
+    history = [];
+    root = "";
+    queue = [];
+    building = false;
+    skipped = [];
+    version = 0;
+    builtAt = 0;
+    complete = false;
+    constructor(workspaceId, broadcast) {
+        this.workspaceId = workspaceId;
+        this.broadcast = broadcast;
+    }
+    start(root) {
+        if (this.building || this.builtAt)
+            return;
+        this.root = root;
+        this.building = true;
+        this.queue = [""];
+        void this.scan();
+    }
+    stop() { }
+    snapshot(since) {
+        const valid = Number.isFinite(since) && since !== undefined;
+        const deltas = valid ? this.history.filter((item) => item.version > since) : [];
+        return { version: this.version, builtAt: this.builtAt, complete: this.complete, skipped: this.skipped,
+            changed: valid ? deltas.flatMap((item) => item.changed) : [...this.entries.values()],
+            removed: valid ? deltas.flatMap((item) => item.removed) : [] };
+    }
+    async refresh(path) {
+        if (!this.root)
+            return;
+        const guard = createRootGuard(this.root);
+        try {
+            const absolute = await guard(path);
+            const info = await stat(absolute);
+            const rel = toRelative(this.root, absolute);
+            if (info.isDirectory())
+                this.publish([{ path: rel, kind: "directory", size: null, mtimeMs: null, etag: null, text: null }], []);
+            else {
+                const meta = await fileMeta(absolute);
+                this.recordFile(rel, meta, info.mtimeMs);
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code === "ENOENT" || code === "ENOTDIR")
+                this.remove(path);
+            else
+                throw error;
+        }
+    }
+    /** Record metadata already obtained by opening, saving, or polling an open file. No second stat: the
+     * caller's file API operation has already passed the sole containment guard and read this metadata. */
+    recordFile(path, meta, mtimeMs = Date.parse(meta.modifiedAt)) {
+        const previous = this.entries.get(path);
+        if (previous?.kind === "file" && previous.etag === meta.etag)
+            return;
+        this.publish([{ path, kind: "file", size: meta.size, mtimeMs, etag: meta.etag, text: isTextName(path) }], []);
+    }
+    remove(path) { if (this.entries.delete(path))
+        this.publish([], [path]); }
+    async scan() {
+        const started = Date.now();
+        let dirs = 0;
+        let files = 0;
+        let incomplete = false;
+        const changed = [];
+        const guard = createRootGuard(this.root);
+        scan: while (this.queue.length) {
+            if (dirs >= MAX_DIRECTORIES || files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                incomplete = true;
+                break;
+            }
+            const directory = this.queue.shift();
+            let listed;
+            try {
+                listed = await readdir(await guard(directory), { withFileTypes: true });
+            }
+            catch {
+                this.skipped.push(directory || "/");
+                incomplete = true;
+                continue;
+            }
+            dirs += 1;
+            for (const entry of listed) {
+                const path = directory ? directory + "/" + entry.name : entry.name;
+                if (entry.isSymbolicLink()) {
+                    this.skipped.push(path);
+                    continue;
+                }
+                if (entry.isDirectory()) {
+                    if (SEARCH_SKIP_DIRS.has(entry.name)) {
+                        this.skipped.push(path);
+                        continue;
+                    }
+                    this.queue.push(path);
+                    changed.push({ path, kind: "directory", size: null, mtimeMs: null, etag: null, text: null });
+                }
+                else if (entry.isFile()) {
+                    if (files >= MAX_FILES || Date.now() - started >= MAX_MS) {
+                        incomplete = true;
+                        break scan;
+                    }
+                    files += 1;
+                    changed.push({ path, kind: "file", size: null, mtimeMs: null, etag: null, text: isTextName(path) });
+                }
+            }
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        this.building = false;
+        this.complete = !incomplete;
+        this.builtAt = Date.now();
+        // Quick Open does not need per-directory progress. One final batch bounds WS traffic and keeps the
+        // existing on-demand tree interactive throughout the scan (including dependency directories).
+        this.publish(changed, [], true);
+    }
+    publish(changed, removed, force = false) {
+        changed = changed.map((entry) => {
+            // A targeted stat may race the cheap directory walk. Do not let the later readdir-only result erase
+            // metadata that was already paid for and verified.
+            const previous = this.entries.get(entry.path);
+            const merged = previous?.kind === entry.kind && entry.size === null ? { ...entry, size: previous.size, mtimeMs: previous.mtimeMs, etag: previous.etag } : entry;
+            this.entries.set(entry.path, merged);
+            return merged;
+        });
+        if (!changed.length && !removed.length && !force)
+            return;
+        this.version += 1;
+        const event = { type: "files.index", workspaceId: this.workspaceId, version: this.version, changed, removed, complete: this.complete, skipped: this.skipped };
+        this.history.push({ version: this.version, changed, removed });
+        if (this.history.length > 128)
+            this.history.shift();
+        this.broadcast(event);
+    }
+}

package/dist/server/files.d.ts

@@ -15,6 +15,14 @@ export declare const MAX_SEARCH_RESULTS = 500;
 /** How deep the recursive search walks. Twelve levels is past any real source tree; the cap is what
  *  turns a pathologically deep dependency tree from a hang into a result. */
 export declare const MAX_SEARCH_DEPTH = 12;
+/** Directories the recursive search skips. The TREE does not skip them - a directory the user cannot
+ *  browse is a directory they cannot inspect a file in, and the binary handling below is only reachable
+ *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
+ *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
+ *  reported in the response rather than being invisible. */
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export declare const SEARCH_SKIP_DIRS: Set<string>;
 /**
  * Extensions this panel OPENS without needing a sniff. It is a hint used only to label a file in the tree
  * before it is read, and never as a permission: a `.png` is refused by name even if a sniffing pass would

package/dist/server/files.js

@@ -52,7 +52,9 @@ export const MAX_SEARCH_DEPTH = 12;
  *  if `node_modules` is reachable. A recursive filename search, by contrast, returns thousands of matches
  *  from these and nothing a person searched for, so they are excluded from the scan and the exclusion is
  *  reported in the response rather than being invisible. */
-const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
+/** Shared exclusion list for recursive search and the quick-open index. The directory tree intentionally
+ * does not use it: users may still browse dependencies on demand. */
+export const SEARCH_SKIP_DIRS = new Set([".git", "node_modules", "dist", "build", ".super-pi", ".next", ".cache", "coverage", ".venv"]);
 /**
  * Extensions that are binary by definition, checked BEFORE any bytes are read.
  *

package/dist/server/git.d.ts

@@ -35,3 +35,20 @@ export declare function gitDiff(root: string, path: string, staged: boolean): Pr
     diff: string;
     kind: "text";
 }>;
+/**
+ * The content of a file AS IT WAS COMMITTED, or `null` when there is no such version.
+ *
+ * WHY THIS EXISTS ALONGSIDE `gitDiff`. `gitDiff` answers "what changed relative to HEAD" as a PATCH -
+ * which is a good thing to read and a bad thing to diff against: a patch is a set of hunks, and
+ * reconstructing the "before" text from it is a lossy operation that a review view should not depend on.
+ * The review view needs the two TEXTS, so that the difference between them is computed by one
+ * well-tested algorithm rather than by two different ones.
+ *
+ * `null` covers three different situations, and the caller must not confuse them: the repository has no
+ * commits yet (`unborn`), the file was never committed (it is new or untracked), or the file is not in
+ * this repository at all. The first two are the same answer for a review - "there is no committed
+ * version to compare against" - and the third is a refusal, which the caller reports.
+ */
+export declare function gitHeadContent(root: string, path: string): Promise<string | null>;
+/** Whether the directory is a git repository at all. The review view asks before it offers a git baseline. */
+export declare function isGitRepository(root: string): Promise<boolean>;

package/dist/server/git.js

@@ -28,3 +28,42 @@ export async function gitLog(root, limit) { const hasHead = await git(root, ["re
 export async function gitDiff(root, path, staged) { const safe = resolve(root, path); if (!safe.startsWith(resolve(root) + sep) || !existsSync(safe))
     throw Object.assign(new Error("文件路径无效"), { code: "path" }); const check = await git(root, ["ls-files", "--error-unmatch", "--", path]).then(() => true).catch(() => false); if (!check)
     return { path, staged, diff: null, kind: "untracked" }; const out = await git(root, ["diff", ...(staged ? ["--cached"] : []), "--", path]); return { path, staged, diff: out.stdout, kind: "text" }; }
+/**
+ * The content of a file AS IT WAS COMMITTED, or `null` when there is no such version.
+ *
+ * WHY THIS EXISTS ALONGSIDE `gitDiff`. `gitDiff` answers "what changed relative to HEAD" as a PATCH -
+ * which is a good thing to read and a bad thing to diff against: a patch is a set of hunks, and
+ * reconstructing the "before" text from it is a lossy operation that a review view should not depend on.
+ * The review view needs the two TEXTS, so that the difference between them is computed by one
+ * well-tested algorithm rather than by two different ones.
+ *
+ * `null` covers three different situations, and the caller must not confuse them: the repository has no
+ * commits yet (`unborn`), the file was never committed (it is new or untracked), or the file is not in
+ * this repository at all. The first two are the same answer for a review - "there is no committed
+ * version to compare against" - and the third is a refusal, which the caller reports.
+ */
+export async function gitHeadContent(root, path) {
+    const safe = resolve(root, path);
+    if (!safe.startsWith(resolve(root) + sep))
+        throw Object.assign(new Error("文件路径无效"), { code: "path" });
+    const hasHead = await git(root, ["rev-parse", "--verify", "HEAD"]).then(() => true).catch(() => false);
+    if (!hasHead)
+        return null;
+    const tracked = await git(root, ["ls-files", "--error-unmatch", "--", path]).then(() => true).catch(() => false);
+    if (!tracked)
+        return null;
+    try {
+        const out = await git(root, ["show", `HEAD:${path}`]);
+        return out.stdout;
+    }
+    catch {
+        // The file is tracked but `HEAD:path` does not resolve - a path with characters git quotes, or a
+        // repository in a state this server does not model. Treated as "no committed version", which is the
+        // honest answer rather than a crash.
+        return null;
+    }
+}
+/** Whether the directory is a git repository at all. The review view asks before it offers a git baseline. */
+export async function isGitRepository(root) {
+    return git(root, ["rev-parse", "--git-dir"]).then(() => true).catch(() => false);
+}

package/dist/server/http-server.js

@@ -8,9 +8,12 @@ import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES
 import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
 import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
+import { computeFileDiff } from "./file-diff.js";
 import { MAX_KNOWLEDGE_REQUEST_BYTES } from "./knowledge.js";
 import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
+import { FileIndex } from "./file-index.js";
+import { MAX_CONTENT_DEPTH, MAX_CONTENT_FILE_BYTES, MAX_CONTENT_RESULTS, searchByContent } from "./content-search.js";
 const MIME_TYPES = {
     ".css": "text/css; charset=utf-8",
     ".html": "text/html; charset=utf-8",
@@ -952,6 +955,118 @@ export function createHttpServer(options) {
             }
             return;
         }
+        if (url.pathname === "/api/files/diff") {
+            const json = (status, body) => {
+                response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+            };
+            try {
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: `Workspace ${workspaceId ?? "(missing)"} not found`, code: "no_workspace" });
+                    return;
+                }
+                const path = url.searchParams.get("path")?.trim() ?? "";
+                if (!path) {
+                    json(400, { error: "需要 path 参数", code: "bad_request" });
+                    return;
+                }
+                const requested = url.searchParams.get("base")?.trim();
+                const preferred = requested === "git" || requested === "agent" ? requested : "auto";
+                // The baseline is chosen by the server, but the client can name one - and when it names one, that
+                // is the one it gets. A silent fall-back would show the user a comparison they did not ask for.
+                const diff = await computeFileDiff({
+                    root: workspace.path,
+                    path,
+                    preferred,
+                    tracker: context.fileChanges,
+                    workspaceId,
+                });
+                json(200, diff);
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
+        if (url.pathname === "/api/files/search") {
+            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
+            try {
+                if (request.method !== "GET") {
+                    json(405, { error: "Content search requires GET", code: "method" });
+                    return;
+                }
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const query = url.searchParams.get("q")?.trim() ?? "";
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: "workspace not found", code: "no_workspace" });
+                    return;
+                }
+                await resolveInsideRoot(workspace.path, "");
+                if (query.length > 256 || /[\r\n]/.test(query)) {
+                    json(400, { error: "Search query must be one line, at most 256 characters", code: "bad_query" });
+                    return;
+                }
+                if (!query) {
+                    json(200, { mode: "content", query, hits: [], truncated: false, skipped: [], complete: true, reasons: [], maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
+                    return;
+                }
+                const indexes = context.fileIndexes ?? new Map();
+                if (!context.fileIndexes)
+                    context.fileIndexes = indexes;
+                let index = indexes.get(workspaceId);
+                if (!index) {
+                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                    indexes.set(workspaceId, index);
+                }
+                index.start(workspace.path);
+                const deadline = Date.now() + 4500;
+                while (!index.builtAt && Date.now() < deadline)
+                    await new Promise((resolve) => setTimeout(resolve, 25));
+                const snapshot = index.snapshot();
+                const result = await searchByContent(workspace.path, [...index.entries.values()], query, snapshot);
+                json(200, { mode: "content", query, ...result, maxResults: MAX_CONTENT_RESULTS, maxFileBytes: MAX_CONTENT_FILE_BYTES, maxDepth: MAX_CONTENT_DEPTH });
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
+        if (url.pathname === "/api/files/index") {
+            const json = (status, body) => { response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body)); };
+            try {
+                if (request.method !== "GET") {
+                    json(405, { error: "File index requires GET", code: "method" });
+                    return;
+                }
+                const workspaceId = url.searchParams.get("workspaceId")?.trim();
+                const workspace = store.snapshot().workspaces.find((item) => item.id === workspaceId);
+                if (!workspaceId || !workspace) {
+                    json(404, { error: `Workspace ${workspaceId ?? "(missing)"} not found`, code: "no_workspace" });
+                    return;
+                }
+                const indexes = context.fileIndexes ?? new Map();
+                if (!context.fileIndexes)
+                    context.fileIndexes = indexes;
+                let index = indexes.get(workspaceId);
+                if (!index) {
+                    index = new FileIndex(workspaceId, (event) => broadcaster.broadcast(event));
+                    indexes.set(workspaceId, index);
+                }
+                index.start(workspace.path);
+                const sinceRaw = url.searchParams.get("since");
+                const since = sinceRaw === null ? undefined : Number(sinceRaw);
+                json(200, index.snapshot(Number.isSafeInteger(since) && since >= 0 ? since : undefined));
+            }
+            catch (error) {
+                const described = describeFilesError(error);
+                json(described.status, described.body);
+            }
+            return;
+        }
         if (url.pathname === "/api/files" || url.pathname === "/api/file") {
             const json = (status, body) => {
                 response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
@@ -983,10 +1098,14 @@ export function createHttpServer(options) {
                     const rel = url.searchParams.get("path") ?? "";
                     if (url.searchParams.get("meta") === "1") {
                         const resolved = await resolveInsideRoot(root, rel);
-                        json(200, { path: toRelative(root, resolved), ...(await fileMeta(resolved)) });
+                        const meta = await fileMeta(resolved);
+                        const path = toRelative(root, resolved);
+                        context.fileIndexes?.get(workspaceId)?.recordFile(path, meta);
+                        json(200, { path, ...meta });
                         return;
                     }
                     const file = await readWorkspaceFile(root, rel);
+                    context.fileIndexes?.get(workspaceId)?.recordFile(file.path, file.meta);
                     json(200, { path: file.path, content: file.content, eol: file.eol, bom: file.bom, meta: file.meta, maxBytes: MAX_FILE_BYTES });
                     return;
                 }
@@ -1018,6 +1137,7 @@ export function createHttpServer(options) {
                         return;
                     }
                     const outcome = await writeWorkspaceFile(root, parsed.path, parsed.content, parsed.baseEtag);
+                    context.fileIndexes?.get(workspaceId)?.recordFile(outcome.path, outcome.meta);
                     json(200, outcome);
                     return;
                 }

package/dist/server/index.js

@@ -19,6 +19,7 @@ import { CatalogService } from "./application/catalog-service.js";
 import { ProviderService } from "./application/provider-service.js";
 import { ProviderRegistry } from "./providers.js";
 import { RunService } from "./application/run-service.js";
+import { FileChangeTracker } from "./file-changes.js";
 import { ConversationService } from "./application/conversation-service.js";
 import { WorkspaceService } from "./application/workspace-service.js";
 import { CommandHandler } from "./command-handler.js";
@@ -191,6 +192,18 @@ const providerRegistry = new ProviderRegistry(dataDir);
 const providerService = new ProviderService(providerRegistry, runtime, broadcaster, catalogService, store);
 const runService = new RunService(store, runtime, subagents, broadcaster, extensionUiService, initialAgentDirs, workflows);
 runService.setMemory(memory);
+/**
+ * WHAT THE AGENT CHANGED, and what each file looked like before.
+ *
+ * The tracker is created here rather than inside the service because it outlives one run: the changes a
+ * session produced are the session's record, and a tracker that died with the run would take the answer
+ * to "what did you just change" with it. It is handed to the run service as a setter, the same shape
+ * `memory` uses.
+ */
+const fileChanges = new FileChangeTracker();
+runService.setFileChanges(fileChanges);
+const fileIndexes = new Map();
+runService.setFileIndexes(fileIndexes);
 const conversationService = new ConversationService(store, runtime, subagents, broadcaster, catalogService, runService, extensionUiService, initialAgentDirs);
 conversationService.setMemory(memory);
 const workspaceService = new WorkspaceService(store, runtime, broadcaster, catalogService, runService, extensionUiService, uploadsDir, initialAgentDirs);
@@ -232,6 +245,8 @@ const serverContext = {
     toolRegistry,
     toolRunner,
     toolLlm,
+    fileChanges,
+    fileIndexes,
     terminalEnabled: () => terminalService.enabled,
     terminalDisabledReason: () => terminalDisabledReason(),
 };

package/dist/server/pi-session-events.d.ts

@@ -60,6 +60,15 @@ export type TurnItem =
 /** The callbacks a turn supplies. The names match the RPC runtime's, so the two paths behave alike. */
 export interface TurnEventHandlers {
     onToolCall?(call: ToolCallNotice): void;
+    /**
+     * Called when a tool that WRITES A FILE is announced, with the path it is about to write.
+     *
+     * The same hook the RPC runtime has, and for the same reason: the announcement is the last moment
+     * the old content is still on the disk, so it is the only moment a diff baseline can be taken. The two
+     * paths (SDK session and spawned RPC) must agree on WHEN this fires, or the same edit would be
+     * baselined on one path and not on the other.
+     */
+    onFileWrite?(path: string, toolName: string, toolCallId?: string): void;
     onToolUpdate?(call: ToolCallNotice): void;
     onToolPreparing?(call: ToolCallPreparing): void;
     onToolEnd?(call: ToolCallNotice): void;

package/dist/server/pi-session-events.js

@@ -17,6 +17,7 @@
  * from, not what they mean.
  */
 import { describeToolCall, describeToolCallArgs, extractPartialResultText } from "./tool-calls.js";
+import { toolTargetPath } from "./file-changes.js";
 /** Keeps only real strings, so a malformed queue snapshot cannot put objects into a broadcast. */
 const textList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
 /**
@@ -258,6 +259,17 @@ export function handleSessionEvent(event, queue, handlers, report, failure) {
             catch (error) {
                 console.warn(`PiRpcRuntime: the tool call handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
             }
+            // The file-writing call, announced before it runs - the only moment the old content is still on
+            // the disk. Fired and forgotten: the listener does its own I/O, off this handler's path.
+            const writePath = toolTargetPath(name, record.args);
+            if (writePath) {
+                try {
+                    handlers.onFileWrite?.(writePath, name, id);
+                }
+                catch (error) {
+                    console.warn(`PiRpcRuntime: the file-write handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                }
+            }
             return true;
         }
         case "tool_execution_update": {