@evandu/super-pi 0.1.105 → 0.1.107

package/dist/client/index.html

@@ -8,8 +8,8 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-tBfBUY_8.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-UiqTcZca.css">
+    <script type="module" crossorigin src="/assets/index-B1K1OA_6.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-Aa8KN3IB.css">
   </head>
   <body>
     <div id="root"></div>

package/dist/server/application/provider-service.d.ts

@@ -51,6 +51,20 @@ export declare class ProviderService {
     set(input: unknown): Promise<PublicProvider[]>;
     /** Removes a provider Super Pi manages, and only one it manages. */
     remove(providerId: string): Promise<PublicProvider[]>;
+    /**
+     * Removes ONE model from a provider, leaving the provider and its other models alone.
+     *
+     * WHY THIS IS NOT JUST A DELETE-AND-RE-ADD. A provider is a group of models sharing one address,
+     * one API type and one key, so removing a model must not touch any of those - and the key in
+     * particular is not something to re-type. The provider's entry in Pi's file is rewritten with the
+     * remaining models, and its credential stays exactly where it was.
+     *
+     * THE LAST MODEL GOES WITH THE PROVIDER. A provider with no models offers nothing, and Pi's file
+     * would keep an entry that can never be selected - so the provider is removed, and with it the
+     * credential, because a credential for a provider that no longer exists is a secret left lying in
+     * a file for nothing.
+     */
+    removeModel(providerId: string, modelId: string): Promise<PublicProvider[]>;
     /**
      * What has to happen after the files are written, for the change to be REAL rather than pending.
      *

package/dist/server/application/provider-service.js

@@ -106,6 +106,35 @@ export class ProviderService {
         await this.afterChange();
         return publicProviders(next);
     }
+    /**
+     * Removes ONE model from a provider, leaving the provider and its other models alone.
+     *
+     * WHY THIS IS NOT JUST A DELETE-AND-RE-ADD. A provider is a group of models sharing one address,
+     * one API type and one key, so removing a model must not touch any of those - and the key in
+     * particular is not something to re-type. The provider's entry in Pi's file is rewritten with the
+     * remaining models, and its credential stays exactly where it was.
+     *
+     * THE LAST MODEL GOES WITH THE PROVIDER. A provider with no models offers nothing, and Pi's file
+     * would keep an entry that can never be selected - so the provider is removed, and with it the
+     * credential, because a credential for a provider that no longer exists is a secret left lying in
+     * a file for nothing.
+     */
+    async removeModel(providerId, modelId) {
+        const previous = await this.registry.load();
+        const existing = previous.find((provider) => provider.id === providerId);
+        if (!existing)
+            throw new Error(`Super Pi 没有管理供应商「${providerId}」`);
+        const remaining = existing.models.filter((model) => model.id !== modelId);
+        if (remaining.length === existing.models.length)
+            throw new Error(`供应商「${providerId}」里没有模型「${modelId}」`);
+        if (!remaining.length)
+            return this.remove(providerId);
+        const next = previous.map((provider) => (provider.id === providerId ? { ...provider, models: remaining } : provider));
+        await this.registry.applyToPi(previous, next);
+        await this.registry.save(next);
+        await this.afterChange();
+        return publicProviders(next);
+    }
     /**
      * What has to happen after the files are written, for the change to be REAL rather than pending.
      *

package/dist/server/application/run-service.d.ts

@@ -5,6 +5,7 @@ import type { Conversation, Message, MessageImage, PiQueueSnapshot, QuestionAnsw
 import type { EventBroadcaster } from "../server-context.js";
 import type { ExtensionUiService } from "./extension-ui-service.js";
 import type { WorkflowEngine } from "../workflow-engine.js";
+import { FileChangeTracker } from "../file-changes.js";
 export interface SubagentDispatchRequestBody {
     conversationId?: string;
     subagent_type?: string;
@@ -62,6 +63,16 @@ export declare class RunService {
     private readonly workflows;
     private memory?;
     setMemory(memory: import("../active-memory.js").ActiveMemory): void;
+    /**
+     * WHAT THE AGENT CHANGED, and what each file looked like before.
+     *
+     * The tracker is a SETTER rather than a constructor argument, for the same reason `memory` is: it is
+     * optional, and a service that must be handed one cannot be built before the thing that builds it.
+     */
+    private fileChanges?;
+    private fileIndexes?;
+    setFileChanges(tracker: FileChangeTracker): void;
+    setFileIndexes(indexes: Map<string, import("../file-index.js").FileIndex>): void;
     reviewMemoryBoundary(conversationId: string): void;
     private readonly activeRuns;
     /**
@@ -122,6 +133,16 @@ export declare class RunService {
      * transcript - so a `role: "user"` is never impersonated.
      */
     enqueueExecResult(sessionId: string, exitCode: number, stdout: string, stderr: string): void;
+    /**
+     * Stops an active background task (spawned process or detached subagent) on user request.
+     *
+     * 1. Kills the underlying PTY child process if one exists in `execService`.
+     * 2. If the task originated from a tool call in a conversation transcript, marks the tool
+     *    call as failed with a clear message and broadcasts `message.tools`.
+     * 3. Removes the task from `state.backgroundTasks` and broadcasts `state` so the sidebar
+     *    updates immediately.
+     */
+    stopBackgroundTask(taskId: string): Promise<void>;
     /** Per-conversation command lane.  All queue mutations and run claims use the same lane, so
      * two browser tabs cannot both observe an idle conversation and start duplicate turns. */
     private readonly conversationOps;
@@ -129,6 +150,14 @@ export declare class RunService {
     private readonly detached;
     constructor(store: Store, runtime: AgentRuntime, subagents: SubagentRunRecorder, broadcaster: EventBroadcaster, extensionUiService: ExtensionUiService, agentsDir: string | string[], workflows: WorkflowEngine);
     setAgentsDir(dir: string | string[]): void;
+    /**
+     * TELLS THE BROWSER WHICH FILES THE AGENT CHANGED.
+     *
+     * The whole list goes every time rather than just the newest file, because the event is a SNAPSHOT
+     * (like `state` and `subagent.event`): a browser that missed one rebuilds the list from the next
+     * one, instead of holding a list assembled from a partial sequence of deltas.
+     */
+    broadcastFileChanges(workspaceId: string): void;
     /**
      * RECORDS WHAT THE PERSON CHOSE, ON THE `question` CALL THAT ASKED.
      *

package/dist/server/application/run-service.js

@@ -137,6 +137,16 @@ export class RunService {
     workflows;
     memory;
     setMemory(memory) { this.memory = memory; }
+    /**
+     * WHAT THE AGENT CHANGED, and what each file looked like before.
+     *
+     * The tracker is a SETTER rather than a constructor argument, for the same reason `memory` is: it is
+     * optional, and a service that must be handed one cannot be built before the thing that builds it.
+     */
+    fileChanges;
+    fileIndexes;
+    setFileChanges(tracker) { this.fileChanges = tracker; }
+    setFileIndexes(indexes) { this.fileIndexes = indexes; }
     reviewMemoryBoundary(conversationId) {
         const conversation = this.store.snapshot().conversations.find(c => c.id === conversationId);
         if (conversation)
@@ -300,6 +310,37 @@ export class RunService {
             }
         })());
     }
+    /**
+     * Stops an active background task (spawned process or detached subagent) on user request.
+     *
+     * 1. Kills the underlying PTY child process if one exists in `execService`.
+     * 2. If the task originated from a tool call in a conversation transcript, marks the tool
+     *    call as failed with a clear message and broadcasts `message.tools`.
+     * 3. Removes the task from `state.backgroundTasks` and broadcasts `state` so the sidebar
+     *    updates immediately.
+     */
+    async stopBackgroundTask(taskId) {
+        const tasks = this.store.snapshot().backgroundTasks ?? [];
+        const task = tasks.find((t) => t.id === taskId);
+        if (this.execService) {
+            try {
+                this.execService.kill(taskId);
+            }
+            catch { /* ignore if already exited */ }
+        }
+        if (task && task.originMessageId !== undefined && task.originCallRow !== undefined) {
+            const conv = this.store.snapshot().conversations.find((c) => c.id === task.conversationId);
+            const msg = conv?.messages.find((m) => m.id === task.originMessageId);
+            if (msg?.toolCalls?.[task.originCallRow]?.backgroundTask) {
+                const toolCalls = await this.store.updateToolCall(task.conversationId, task.originMessageId, task.originCallRow, {
+                    backgroundTask: { id: taskId, status: "failed", output: "已由用户手动终止" },
+                });
+                this.broadcaster.broadcast({ type: "message.tools", conversationId: task.conversationId, messageId: task.originMessageId, toolCalls });
+            }
+        }
+        await this.store.removeBackgroundTask(taskId);
+        this.broadcaster.broadcastState();
+    }
     /** Per-conversation command lane.  All queue mutations and run claims use the same lane, so
      * two browser tabs cannot both observe an idle conversation and start duplicate turns. */
     conversationOps = new Map();
@@ -317,6 +358,31 @@ export class RunService {
     setAgentsDir(dir) {
         this.agentsDir = dir;
     }
+    /**
+     * TELLS THE BROWSER WHICH FILES THE AGENT CHANGED.
+     *
+     * The whole list goes every time rather than just the newest file, because the event is a SNAPSHOT
+     * (like `state` and `subagent.event`): a browser that missed one rebuilds the list from the next
+     * one, instead of holding a list assembled from a partial sequence of deltas.
+     */
+    broadcastFileChanges(workspaceId) {
+        const tracker = this.fileChanges;
+        if (!tracker)
+            return;
+        const { changes, dropped } = tracker.list(workspaceId);
+        this.broadcaster.broadcast({
+            type: "files.changed",
+            workspaceId,
+            dropped,
+            changes: changes.map((change) => ({
+                path: change.path,
+                baseline: change.before,
+                ...(change.beforeUnknown ? { baselineUnknown: true } : {}),
+                ...(change.conversationId ? { conversationId: change.conversationId } : {}),
+                at: change.at,
+            })),
+        });
+    }
     /**
      * RECORDS WHAT THE PERSON CHOSE, ON THE `question` CALL THAT ASKED.
      *
@@ -867,6 +933,36 @@ export class RunService {
             }));
             preparingRows.set(call.contentIndex, { row, name: call.name });
         };
+        /**
+         * THE AGENT IS ABOUT TO WRITE A FILE.
+         *
+         * The baseline is captured HERE, at the announcement, because this is the last moment the old content
+         * is still on the disk. By the time the tool has finished, the file holds the new content and the
+         * "before" is gone - which is why a diff cannot be reconstructed afterwards from the file itself.
+         *
+         * The read inside `record` is SYNCHRONOUS on purpose (see `file-changes.ts` for the race it
+         * closes), and it is bounded by a size cap, so it costs a fraction of a millisecond for an
+         * ordinary source file.
+         */
+        /**
+         * THE PATHS THE AGENT IS WRITING, keyed by tool call id.
+         *
+         * The key is what lets the tool's END confirm the baseline of the right file. The alternative - the
+         * tool card's one-line summary - is a DISPLAY string: whitespace-collapsed and length-capped, so
+         * it is not a path the server can read a file by, and a path with a run of spaces in it would come
+         * back as a path with one space.
+         */
+        const fileWritePaths = new Map();
+        const onFileWrite = (path, _toolName, toolCallId) => {
+            const tracker = this.fileChanges;
+            if (!tracker)
+                return;
+            tracker.record(workspace.id, path, { root: workspace.path, conversationId: conversation.id });
+            void this.fileIndexes?.get(workspace.id)?.refresh(path);
+            if (toolCallId)
+                fileWritePaths.set(toolCallId, path);
+            this.broadcastFileChanges(workspace.id);
+        };
         const onToolCall = (call) => {
             const at = spoken;
             // THE PLACEHOLDER THAT BELONGS TO THIS CALL, IF ONE IS ON SCREEN.
@@ -920,6 +1016,18 @@ export class RunService {
             enqueueTools("a tool call update", () => this.store.updateToolCall(conversation.id, assistant.id, index, { ...(call.args ? { args: call.args } : {}), ...(call.live !== undefined ? { live: call.live } : {}) }));
         };
         const onToolEnd = (call) => {
+            // THE WRITE IS FINISHED, so the baseline can be CHECKED. The tracker recorded the file's etag when
+            // the write was announced; if the file's etag now differs, the baseline really is the content
+            // from before the write. If it does not, the baseline was taken too late to be shown, and the
+            // tracker says so rather than letting the diff view claim two identical versions are the same.
+            const writtenPath = call.id ? fileWritePaths.get(call.id) : undefined;
+            if (writtenPath) {
+                this.fileChanges?.confirm(workspace.id, writtenPath, workspace.path);
+                void this.fileIndexes?.get(workspace.id)?.refresh(writtenPath);
+                if (call.id)
+                    fileWritePaths.delete(call.id);
+                this.broadcastFileChanges(workspace.id);
+            }
             const index = call.id ? rowByToolCallId.get(call.id) : undefined;
             if (index === undefined)
                 return;
@@ -992,6 +1100,7 @@ export class RunService {
                 onUserEntry: (entryId) => this.store.setMessagePiEntryId(conversation.id, userMessageId, entryId),
                 onSessionFile: (path) => this.store.setConversationPiSessionFile(conversation.id, path),
                 onToolCall,
+                onFileWrite,
                 onToolPreparing,
                 onToolUpdate,
                 onToolEnd,

package/dist/server/command-handler.js

@@ -95,6 +95,12 @@ export class CommandHandler {
             await this.providerService.remove(command.providerId);
             return;
         }
+        if (command.type === "providers.removeModel") {
+            if (!this.providerService)
+                throw new Error("供应商功能不可用");
+            await this.providerService.removeModel(command.providerId, command.modelId);
+            return;
+        }
         if (command.type === "providers.fetch") {
             if (!this.providerService)
                 throw new Error("供应商功能不可用");
@@ -102,6 +108,10 @@ export class CommandHandler {
                 sendToSocket({ type: "providers.list", providers: await this.providerService.list(), apis: [...KNOWN_APIS] });
             return;
         }
+        if (command.type === "backgroundTask.stop") {
+            await this.runService.stopBackgroundTask(command.taskId);
+            return;
+        }
         if (command.type === "workspace.create") {
             return await this.workspaceService.createWorkspace(command.name, command.path);
         }

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;
+}