@evandu/super-pi 0.1.70 → 0.1.72

package/dist/server/session-repository.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Cuts a Pi session file down to the header plus everything up to and including `boundaryEntryId`.
+ *
+ * ============================ WHAT THIS DESTROYS ============================
+ * **Every entry written after the boundary is gone from disk, permanently, and there is no way to
+ * reconstruct it from this file.** That includes not only the messages a person can see but also Pi's
+ * `tool_call` records, `compaction` summaries, `model_change` and `thinking_level_change` markers, usage
+ * accounting, and anything a future Pi version adds. This is the step the whole revert design is built
+ * around (research §4.2) and the step that cannot be undone by the application - Super Pi has no undo,
+ * and adding one was explicitly left out of scope.
+ *
+ * It does NOT touch the workspace. No file the agent read or wrote is read, written or reverted here.
+ * =============================================================================
+ *
+ * WHY TRUNCATE RATHER THAN ASK PI. Pi's `SessionManager` is append-only by design
+ * (`session-manager.ts:1516-1519`: "Entries cannot be modified or deleted"), and its in-session rewind -
+ * `branch()`, `navigateTree()` - is IN-MEMORY ONLY (`:1573-1584`): `_buildIndex()` re-reads the whole
+ * file on every `open()` and sets the leaf to the last line unconditionally (`:1103-1122`). Super Pi
+ * spawns one Pi per turn and kills it afterwards, so a leaf pointer set in one turn is gone before the
+ * next one starts - a "call `branch()` once" solution would look correct for a turn and then silently
+ * forget (research §5 pitfall 2). Truncating the file is the only version of this that is a durable state
+ * change rather than per-turn bookkeeping that can be skipped exactly once.
+ *
+ * WHY THE FORMAT IS ASSUMED RATHER THAN GUESSED. The shape this relies on - line 0 is the one and only
+ * `type: "session"` header, every other line is one self-contained JSON entry, every entry's `parentId`
+ * already appears earlier in the file, no blank lines, and a trailing newline - was measured against
+ * real Pi by scripts/probe-revert-session-format.mjs, which also proves the `parentId` property that
+ * makes a prefix a VALID session rather than a fragment. That probe is the reason this function may
+ * index by line at all; every one of those claims is re-checked here before anything is written, so a
+ * Pi that changed the format fails loudly instead of producing a file Pi cannot open.
+ *
+ * WHY THE WRITE IS TEMP-THEN-RENAME. Pi appends with a bare `appendFileSync`
+ * (`session-manager.ts:1187`) and makes no atomicity guarantee of its own. Writing the truncated copy
+ * under a different name and renaming it over the original means a reader never observes a half-written
+ * file, and a failure before the rename leaves the original untouched.
+ *
+ * WHY A BACKUP IS KEPT. `.super-pi-revert-backup` is written next to the session file, deliberately not
+ * named `*.jsonl` so Pi's own discovery (`readdirSync` filtered on that suffix,
+ * `session-manager.ts:1881`) never lists it, and deliberately NOT surfaced anywhere as a feature:
+ * Super Pi has no undo and does not pretend to. It exists so that an irreversible, unrecoverable-by-code
+ * operation on a person's conversation history is at least recoverable by hand.
+ *
+ * EXPORTED so it can be tested against a fabricated session file in a temp directory, without Pi and
+ * without touching anybody's real transcript.
+ */
+export declare function truncateSessionFile(path: string, boundaryEntryId: string, expectedSessionId: string, beforeBoundary?: boolean): Promise<{
+    linesKept: number;
+    entriesDropped: number;
+}>;
+/**
+ * Writes a second Pi session file that begins as an EXACT copy of one, under a different session id.
+ *
+ * ============================ WHAT THIS DOES TO THE ORIGINAL ============================
+ * **Nothing.** The source file is read and never written, never truncated, never renamed. This is the
+ * whole difference from `truncateSessionFile`, and it is the reason a fork is the safe half of this pair
+ * of operations: a revert destroys entries permanently and keeps a hand-recovery backup, while a fork
+ * leaves both files whole and keeps no backup because there is nothing to recover.
+ * ========================================================================================
+ *
+ * WHY A COPY AND NOT PI'S `fork()`. Covered at length on `ClientCommand`'s `conversation.fork`: Pi's fork
+ * always tears down the runtime and switches to the new session (`agent-session-runtime.ts:299-307`), and
+ * Super Pi has no runtime to switch - it spawns one Pi per turn and kills it. The file is the only durable
+ * thing a fork has to produce here, so the file is what gets produced.
+ *
+ * ============================ WHAT THIS DOES TO PI's ENTRY IDS ============================
+ * **Nothing either, and this is a deliberate divergence from Pi's own `createBranchedSession`, which
+ * RENUMBERS `parentId` (`:1655-1666`).** Keeping every id verbatim means every cross-reference already
+ * inside the file stays valid, and research pitfall 6 is exactly why that matters: a Pi entry may point
+ * at other entries by id in ways this code has never enumerated - a `compaction` record carries a
+ * `firstKeptEntryId`, `branch_summary` carries the branch point - and renumbering ids means rewriting every
+ * one of those references correctly, with no way to find them all. Copying the bytes cannot break a
+ * reference because it changes nothing a reference points at. The cost is that the same entry id now
+ * exists in two files; that is safe because `_buildIndex` builds its `byId` map per file (`:1103-1122`),
+ * and Super Pi only ever opens one file per process.
+ *
+ * WHAT THE HEADER CHANGES, and it is two fields. `id` becomes the new conversation's id, because that is
+ * what Pi's lookup matches (`findLocalSessionByExactId` reads the header, probe B) and therefore what makes
+ * `--session-id <forked>` open THIS file rather than silently inventing an empty session with that id
+ * (`main.ts:436-448`, measured: `Warning: No project session found with id '...'`). And `parentSession`
+ * records the file this one came from, which is the same one-line lineage pointer Pi itself writes
+ * (`:1675-1682`) and is not a link - the files share nothing. `cwd`, `version` and `timestamp` are copied
+ * verbatim: `cwd` MUST be identical, because Pi's lookup requires the recorded cwd to equal the one it is
+ * asked from, and the fork always lives in the same workspace as its source.
+ *
+ * THE SAME FORMAT CHECKS AS TRUNCATE, AND FOR THE SAME REASON. Probe A measured this file's shape against
+ * real Pi (`scripts/probe-revert-session-format.mjs`); a Pi upgrade can invalidate any of those claims, so
+ * every one is re-checked before a byte is written and a failure names the shape actually found. Here the
+ * `parentId` property is checked across the WHOLE file rather than across a kept prefix, because the whole
+ * file is what is being copied.
+ *
+ * TEMP-THEN-RENAME, because Pi appends with a bare `appendFileSync` (`:1187`) and the target must never be
+ * observed half-written - a half-written file under the forked id is precisely the "Pi opens an empty
+ * session and the history has vanished with no error anywhere" outcome probe B was about.
+ *
+ * EXPORTED so it can be tested against fabricated session files in a temp directory, without Pi.
+ */
+export declare function forkSessionFile(sourcePath: string, targetPath: string, expectedSessionId: string, targetSessionId: string): Promise<{
+    entriesCopied: number;
+}>;

package/dist/server/session-repository.js

@@ -0,0 +1,245 @@
+import { readFile, rename, writeFile } from "node:fs/promises";
+/**
+ * Cuts a Pi session file down to the header plus everything up to and including `boundaryEntryId`.
+ *
+ * ============================ WHAT THIS DESTROYS ============================
+ * **Every entry written after the boundary is gone from disk, permanently, and there is no way to
+ * reconstruct it from this file.** That includes not only the messages a person can see but also Pi's
+ * `tool_call` records, `compaction` summaries, `model_change` and `thinking_level_change` markers, usage
+ * accounting, and anything a future Pi version adds. This is the step the whole revert design is built
+ * around (research §4.2) and the step that cannot be undone by the application - Super Pi has no undo,
+ * and adding one was explicitly left out of scope.
+ *
+ * It does NOT touch the workspace. No file the agent read or wrote is read, written or reverted here.
+ * =============================================================================
+ *
+ * WHY TRUNCATE RATHER THAN ASK PI. Pi's `SessionManager` is append-only by design
+ * (`session-manager.ts:1516-1519`: "Entries cannot be modified or deleted"), and its in-session rewind -
+ * `branch()`, `navigateTree()` - is IN-MEMORY ONLY (`:1573-1584`): `_buildIndex()` re-reads the whole
+ * file on every `open()` and sets the leaf to the last line unconditionally (`:1103-1122`). Super Pi
+ * spawns one Pi per turn and kills it afterwards, so a leaf pointer set in one turn is gone before the
+ * next one starts - a "call `branch()` once" solution would look correct for a turn and then silently
+ * forget (research §5 pitfall 2). Truncating the file is the only version of this that is a durable state
+ * change rather than per-turn bookkeeping that can be skipped exactly once.
+ *
+ * WHY THE FORMAT IS ASSUMED RATHER THAN GUESSED. The shape this relies on - line 0 is the one and only
+ * `type: "session"` header, every other line is one self-contained JSON entry, every entry's `parentId`
+ * already appears earlier in the file, no blank lines, and a trailing newline - was measured against
+ * real Pi by scripts/probe-revert-session-format.mjs, which also proves the `parentId` property that
+ * makes a prefix a VALID session rather than a fragment. That probe is the reason this function may
+ * index by line at all; every one of those claims is re-checked here before anything is written, so a
+ * Pi that changed the format fails loudly instead of producing a file Pi cannot open.
+ *
+ * WHY THE WRITE IS TEMP-THEN-RENAME. Pi appends with a bare `appendFileSync`
+ * (`session-manager.ts:1187`) and makes no atomicity guarantee of its own. Writing the truncated copy
+ * under a different name and renaming it over the original means a reader never observes a half-written
+ * file, and a failure before the rename leaves the original untouched.
+ *
+ * WHY A BACKUP IS KEPT. `.super-pi-revert-backup` is written next to the session file, deliberately not
+ * named `*.jsonl` so Pi's own discovery (`readdirSync` filtered on that suffix,
+ * `session-manager.ts:1881`) never lists it, and deliberately NOT surfaced anywhere as a feature:
+ * Super Pi has no undo and does not pretend to. It exists so that an irreversible, unrecoverable-by-code
+ * operation on a person's conversation history is at least recoverable by hand.
+ *
+ * EXPORTED so it can be tested against a fabricated session file in a temp directory, without Pi and
+ * without touching anybody's real transcript.
+ */
+export async function truncateSessionFile(path, boundaryEntryId, expectedSessionId, beforeBoundary = false) {
+    const raw = await readFile(path, "utf8");
+    // Split, then drop the empty segment a trailing newline leaves behind. Probe A measured that the file
+    // DOES end with a newline, so `split` yields one empty tail element; keeping it would append a blank
+    // line to the rewritten file and undo the property the probe just established.
+    const lines = raw.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (!lines.length)
+        throw new Error(`Pi 的会话文件是空的，拒绝回退：${path}`);
+    const parsed = lines.map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // Every claim probe A made, re-checked here because a Pi upgrade may invalidate any of them. Each
+    // failure names the shape that was actually found, because "revert failed" alone sends the reader
+    // looking for their own data instead of at the version mismatch that caused it.
+    // Checked BEFORE the JSON check, so the refusal names the actual defect: a blank line reads as "this
+    // file has a shape my line arithmetic cannot trust", which is what it is, and a bare "not valid JSON"
+    // would send the reader looking for a corrupted file instead.
+    const blank = lines.findIndex((line) => line.trim() === "");
+    if (blank >= 0)
+        throw new Error(`Pi 的会话文件第 ${blank} 行是空行，行号与 entry 号不再一一对应，拒绝回退：${path}`);
+    const unparseable = parsed.findIndex((entry) => entry === undefined);
+    if (unparseable >= 0)
+        throw new Error(`Pi 的会话文件第 ${unparseable} 行不是合法 JSON，这个文件的格式已经变了，拒绝回退以免损坏它：${path}`);
+    const headerLines = parsed.filter((entry) => entry?.type === "session");
+    if (headerLines.length !== 1)
+        throw new Error(`Pi 的会话文件里有 ${headerLines.length} 个 header（应为 1 个），格式已经变了，拒绝回退：${path}`);
+    if (parsed[0]?.type !== "session")
+        throw new Error(`Pi 的会话文件第一行不是 header（实际 type=${JSON.stringify(parsed[0]?.type ?? null)}），格式已经变了，拒绝回退：${path}`);
+    if (parsed[0]?.id !== expectedSessionId)
+        throw new Error(`Pi 的会话文件属于会话 ${JSON.stringify(parsed[0]?.id ?? null)}，不是要回退的会话 ${JSON.stringify(expectedSessionId)}。拒绝截断别人的会话。`);
+    if (!raw.endsWith("\n"))
+        throw new Error(`Pi 的会话文件末尾没有换行，格式已经变了，拒绝回退：${path}`);
+    let boundary = boundaryEntryId === "" ? 0 : parsed.findIndex((entry, index) => index > 0 && entry?.id === boundaryEntryId);
+    if (boundary < 0)
+        throw new Error(`在这份 Pi 会话记录里找不到要保留的那条消息（entry ${JSON.stringify(boundaryEntryId)}）。这条消息可能是更早的版本写的，Super Pi 当时没有记下它对应 Pi 的哪一条。`);
+    const expectedLastId = beforeBoundary ? parsed[boundary - 1]?.id : parsed[boundary]?.id;
+    if (beforeBoundary)
+        boundary -= 1;
+    // Fail closed: a boundary of -1 here means "revert to before the FIRST entry", which would write an
+    // empty session file. The verification below would pass vacuously (0 !== 0 is false), so the refusal
+    // must happen here rather than be trusted to a check that cannot fire.
+    if (boundary < 0)
+        throw new Error(`回退点在第一条消息之前，截断会得到一个空会话文件，拒绝回退：${path}`);
+    // The `parentId` property probe A measured, enforced at the boundary that matters: every entry still
+    // being KEPT must point at something also being kept. A prefix that violates this is not a session,
+    // and writing it would produce a file Pi either rejects or silently misreads.
+    const kept = new Set();
+    for (let index = 0; index <= boundary; index += 1) {
+        const parent = parsed[index]?.parentId;
+        if (parent !== undefined && parent !== null && !kept.has(parent))
+            throw new Error(`要保留的部分不是自洽的：第 ${index} 行引用了不在保留范围内的 ${JSON.stringify(parent)}，拒绝回退以免产出 Pi 打不开的会话。`);
+        kept.add(parsed[index]?.id);
+    }
+    const rewritten = `${lines.slice(0, boundary + 1).join("\n")}\n`;
+    const backupPath = `${path}.super-pi-revert-backup`;
+    const temporaryPath = `${path}.super-pi-revert-tmp`;
+    await writeFile(backupPath, raw, "utf8");
+    await writeFile(temporaryPath, rewritten, "utf8");
+    await rename(temporaryPath, path);
+    // Re-read rather than trust the write. The claim this whole mechanism rests on is "the file's last
+    // line is now the boundary entry", and `_buildIndex` derives the leaf from exactly that line - so if
+    // the write did not land, nothing downstream would say so until a turn produced wrong context.
+    const verified = (await readFile(path, "utf8")).split("\n").filter((line) => line !== "");
+    const last = verified[verified.length - 1];
+    let lastEntry;
+    try {
+        lastEntry = JSON.parse(last);
+    }
+    catch {
+        lastEntry = undefined;
+    }
+    if (verified.length !== boundary + 1 || lastEntry?.id !== expectedLastId || boundary + 1 < 1) {
+        throw new Error(`截断后的 Pi 会话文件没有以要保留的那条消息结尾（写到 ${verified.length} 行，期望 ${boundary + 1} 行，末行 id=${JSON.stringify(lastEntry?.id ?? null)}）。原始文件仍在 ${backupPath}。`);
+    }
+    return { linesKept: boundary + 1, entriesDropped: lines.length - (boundary + 1) };
+}
+/**
+ * Writes a second Pi session file that begins as an EXACT copy of one, under a different session id.
+ *
+ * ============================ WHAT THIS DOES TO THE ORIGINAL ============================
+ * **Nothing.** The source file is read and never written, never truncated, never renamed. This is the
+ * whole difference from `truncateSessionFile`, and it is the reason a fork is the safe half of this pair
+ * of operations: a revert destroys entries permanently and keeps a hand-recovery backup, while a fork
+ * leaves both files whole and keeps no backup because there is nothing to recover.
+ * ========================================================================================
+ *
+ * WHY A COPY AND NOT PI'S `fork()`. Covered at length on `ClientCommand`'s `conversation.fork`: Pi's fork
+ * always tears down the runtime and switches to the new session (`agent-session-runtime.ts:299-307`), and
+ * Super Pi has no runtime to switch - it spawns one Pi per turn and kills it. The file is the only durable
+ * thing a fork has to produce here, so the file is what gets produced.
+ *
+ * ============================ WHAT THIS DOES TO PI's ENTRY IDS ============================
+ * **Nothing either, and this is a deliberate divergence from Pi's own `createBranchedSession`, which
+ * RENUMBERS `parentId` (`:1655-1666`).** Keeping every id verbatim means every cross-reference already
+ * inside the file stays valid, and research pitfall 6 is exactly why that matters: a Pi entry may point
+ * at other entries by id in ways this code has never enumerated - a `compaction` record carries a
+ * `firstKeptEntryId`, `branch_summary` carries the branch point - and renumbering ids means rewriting every
+ * one of those references correctly, with no way to find them all. Copying the bytes cannot break a
+ * reference because it changes nothing a reference points at. The cost is that the same entry id now
+ * exists in two files; that is safe because `_buildIndex` builds its `byId` map per file (`:1103-1122`),
+ * and Super Pi only ever opens one file per process.
+ *
+ * WHAT THE HEADER CHANGES, and it is two fields. `id` becomes the new conversation's id, because that is
+ * what Pi's lookup matches (`findLocalSessionByExactId` reads the header, probe B) and therefore what makes
+ * `--session-id <forked>` open THIS file rather than silently inventing an empty session with that id
+ * (`main.ts:436-448`, measured: `Warning: No project session found with id '...'`). And `parentSession`
+ * records the file this one came from, which is the same one-line lineage pointer Pi itself writes
+ * (`:1675-1682`) and is not a link - the files share nothing. `cwd`, `version` and `timestamp` are copied
+ * verbatim: `cwd` MUST be identical, because Pi's lookup requires the recorded cwd to equal the one it is
+ * asked from, and the fork always lives in the same workspace as its source.
+ *
+ * THE SAME FORMAT CHECKS AS TRUNCATE, AND FOR THE SAME REASON. Probe A measured this file's shape against
+ * real Pi (`scripts/probe-revert-session-format.mjs`); a Pi upgrade can invalidate any of those claims, so
+ * every one is re-checked before a byte is written and a failure names the shape actually found. Here the
+ * `parentId` property is checked across the WHOLE file rather than across a kept prefix, because the whole
+ * file is what is being copied.
+ *
+ * TEMP-THEN-RENAME, because Pi appends with a bare `appendFileSync` (`:1187`) and the target must never be
+ * observed half-written - a half-written file under the forked id is precisely the "Pi opens an empty
+ * session and the history has vanished with no error anywhere" outcome probe B was about.
+ *
+ * EXPORTED so it can be tested against fabricated session files in a temp directory, without Pi.
+ */
+export async function forkSessionFile(sourcePath, targetPath, expectedSessionId, targetSessionId) {
+    const raw = await readFile(sourcePath, "utf8");
+    const lines = raw.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    if (!lines.length)
+        throw new Error(`Pi 的会话文件是空的，拒绝分叉：${sourcePath}`);
+    const parsed = lines.map((line) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch {
+            return undefined;
+        }
+    });
+    // The refusal messages name the shape actually found, and say "拒绝分叉" rather than reusing the revert
+    // wording: the reader is looking at a fork button, and a message about 回退 would send them to look for a
+    // control they did not press.
+    const blank = lines.findIndex((line) => line.trim() === "");
+    if (blank >= 0)
+        throw new Error(`Pi 的会话文件第 ${blank} 行是空行，无法安全复制，拒绝分叉：${sourcePath}`);
+    const unparseable = parsed.findIndex((entry) => entry === undefined);
+    if (unparseable >= 0)
+        throw new Error(`Pi 的会话文件第 ${unparseable} 行不是合法 JSON，这个文件的格式已经变了，拒绝分叉以免复制出一个 Pi 打不开的会话：${sourcePath}`);
+    const headerLines = parsed.filter((entry) => entry?.type === "session");
+    if (headerLines.length !== 1)
+        throw new Error(`Pi 的会话文件里有 ${headerLines.length} 个 header（应为 1 个），格式已经变了，拒绝分叉：${sourcePath}`);
+    if (parsed[0]?.type !== "session")
+        throw new Error(`Pi 的会话文件第一行不是 header（实际 type=${JSON.stringify(parsed[0]?.type ?? null)}），格式已经变了，拒绝分叉：${sourcePath}`);
+    // The one that matters most. Copying the wrong file would put one person's conversation into another's
+    // session, and unlike a wrong truncation it would be written as a brand-new file rather than destroying
+    // something - so this check is what stops a fork from being a disclosure.
+    if (parsed[0]?.id !== expectedSessionId)
+        throw new Error(`Pi 的会话文件属于会话 ${JSON.stringify(parsed[0]?.id ?? null)}，不是要分叉的会话 ${JSON.stringify(expectedSessionId)}。拒绝复制别人的会话。`);
+    if (!raw.endsWith("\n"))
+        throw new Error(`Pi 的会话文件末尾没有换行，格式已经变了，拒绝分叉：${sourcePath}`);
+    // Every kept entry must point at another kept entry. The whole file is being copied, so "kept" is all of
+    // it - and a file that violates this is not a session Pi can open.
+    const known = new Set();
+    for (let index = 0; index < parsed.length; index += 1) {
+        const parent = parsed[index]?.parentId;
+        if (parent !== undefined && parent !== null && !known.has(parent))
+            throw new Error(`这个 Pi 会话记录不自洽：第 ${index} 行引用了不存在的 ${JSON.stringify(parent)}，拒绝分叉以免复制出一个 Pi 打不开的会话：${sourcePath}`);
+        known.add(parsed[index]?.id);
+    }
+    // The header is REBUILT rather than string-patched, so the two changed fields are structural and
+    // everything else - including any field a future Pi adds - is carried across untouched. A regex over the
+    // first line would silently drop a field it did not recognise.
+    const header = { ...parsed[0], id: targetSessionId, parentSession: sourcePath };
+    const rewritten = [JSON.stringify(header), ...lines.slice(1)].join("\n") + "\n";
+    const temporaryPath = `${targetPath}.super-pi-fork-tmp`;
+    await writeFile(temporaryPath, rewritten, "utf8");
+    await rename(temporaryPath, targetPath);
+    // Re-read rather than trust the write. The claim this rests on is "a Pi spawned with the new id will
+    // open THIS file and find the whole history in it", and nothing downstream would report a failed write -
+    // the fork would simply appear to work and the model would start from nothing.
+    const verified = (await readFile(targetPath, "utf8")).split("\n").filter((line) => line !== "");
+    let verifiedHeader;
+    try {
+        verifiedHeader = JSON.parse(verified[0]);
+    }
+    catch {
+        verifiedHeader = undefined;
+    }
+    if (verified.length !== lines.length || verifiedHeader?.id !== targetSessionId) {
+        throw new Error(`写入后的 Pi 会话文件不是预期的样子（写到 ${verified.length} 行，期望 ${lines.length} 行，header id=${JSON.stringify(verifiedHeader?.id ?? null)}，期望 ${JSON.stringify(targetSessionId)}）。已放弃，没有创建任何会话。`);
+    }
+    return { entriesCopied: lines.length - 1 };
+}

package/dist/server/store.d.ts

@@ -223,6 +223,13 @@ export declare class Store {
         thinkingLevel?: string;
     }): Promise<Conversation>;
     beginAssistantMessage(conversationId: string, agentIdentity?: Message["agentIdentity"]): Promise<Message>;
+    /**
+     * Applies a streamed delta to the authoritative in-memory transcript without touching disk.
+     *
+     * The runtime must be able to drain Pi and publish the token before a disk transaction finishes.
+     * `checkpointMessage` below makes the same object durable on a bounded cadence and at turn boundaries.
+     */
+    appendAssistantDeltaLive(conversationId: string, messageId: string, delta: string): void;
     appendAssistantDelta(conversationId: string, messageId: string, delta: string): Promise<void>;
     /**
      * THE MODEL'S REASONING, APPENDED TO THE MESSAGE IT BELONGS TO.
@@ -234,7 +241,10 @@ export declare class Store {
      * to go back to. Persisting here rather than only in the browser is the point of its living on the
      * message: a reasoning stream that vanishes on reload was never a record of anything.
      */
+    appendThinkingDeltaLive(conversationId: string, messageId: string, delta: string, at?: number): void;
     appendThinkingDelta(conversationId: string, messageId: string, delta: string): Promise<void>;
+    /** Persists the message exactly as it stands now, including any live text, thinking and tool updates. */
+    checkpointMessage(conversationId: string, messageId: string): Promise<void>;
     /**
      * Appends one tool call to the message it belongs to, and returns the message's whole `toolCalls`
      * array so the caller can broadcast it as one snapshot.
@@ -308,6 +318,8 @@ export declare class Store {
      * one: it means the caller and the store disagree about the conversation, and guessing is worse.
      */
     setMessagePiEntryId(conversationId: string, messageId: string, piEntryId: string): Promise<void>;
+    /** Cache a locator Pi itself resolved while serving this conversation; never trust it as authorization. */
+    setConversationPiSessionFile(conversationId: string, path: string): Promise<void>;
     /**
      * Reverts the conversation to the state right after `messageId`, in `state.json` only.
      *

package/dist/server/store.js

@@ -879,14 +879,23 @@ export class Store {
         return structuredClone(conversation);
     }
     async beginAssistantMessage(conversationId, agentIdentity) { const conversation = this.requireConversation(conversationId); const message = { id: id("message"), role: "assistant", content: "", createdAt: now(), ...(agentIdentity ? { agentIdentity: structuredClone(agentIdentity) } : {}) }; conversation.messages.push(message); await this.persist(); return structuredClone(message); }
-    async appendAssistantDelta(conversationId, messageId, delta) {
+    /**
+     * Applies a streamed delta to the authoritative in-memory transcript without touching disk.
+     *
+     * The runtime must be able to drain Pi and publish the token before a disk transaction finishes.
+     * `checkpointMessage` below makes the same object durable on a bounded cadence and at turn boundaries.
+     */
+    appendAssistantDeltaLive(conversationId, messageId, delta) {
         const conversation = this.requireConversation(conversationId);
         const message = conversation.messages.find((item) => item.id === messageId);
         if (!message)
             throw new Error("Assistant message not found");
         message.content += delta;
         conversation.updatedAt = now();
-        await this.persistTransaction({ kind: "message.replace", conversationId, message: structuredClone(message), updatedAt: conversation.updatedAt });
+    }
+    async appendAssistantDelta(conversationId, messageId, delta) {
+        this.appendAssistantDeltaLive(conversationId, messageId, delta);
+        await this.checkpointMessage(conversationId, messageId);
     }
     /**
      * THE MODEL'S REASONING, APPENDED TO THE MESSAGE IT BELONGS TO.
@@ -898,13 +907,30 @@ export class Store {
      * to go back to. Persisting here rather than only in the browser is the point of its living on the
      * message: a reasoning stream that vanishes on reload was never a record of anything.
      */
-    async appendThinkingDelta(conversationId, messageId, delta) {
+    appendThinkingDeltaLive(conversationId, messageId, delta, at) {
         const conversation = this.requireConversation(conversationId);
         const message = conversation.messages.find((item) => item.id === messageId);
         if (!message)
             throw new Error("Assistant message not found");
         message.thinking = `${message.thinking ?? ""}${delta}`;
+        const blocks = (message.thinkingBlocks ??= []);
+        const last = blocks.at(-1);
+        if (last && last.at === (at ?? last.at))
+            last.text += delta;
+        else
+            blocks.push({ at: at ?? message.content.length, text: delta });
         conversation.updatedAt = now();
+    }
+    async appendThinkingDelta(conversationId, messageId, delta) {
+        this.appendThinkingDeltaLive(conversationId, messageId, delta);
+        await this.checkpointMessage(conversationId, messageId);
+    }
+    /** Persists the message exactly as it stands now, including any live text, thinking and tool updates. */
+    async checkpointMessage(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message)
+            throw new Error("Assistant message not found");
         await this.persistTransaction({ kind: "message.replace", conversationId, message: structuredClone(message), updatedAt: conversation.updatedAt });
     }
     /**
@@ -996,7 +1022,7 @@ export class Store {
         // full output a reader watched grow; the persisted `result` is a bounded 8KB tail of the same
         // stream. Deleting live would replace the watched text with a possibly-different 8KB slice, and a
         // finished tool block that vanishes the moment the call ends is a block that taught the reader
-        // nothing. The client renders `result` when present, falling back to `live` for the full preview.
+        // nothing. The client prefers `live` when both are present, falling back to `result`.
         conversation.updatedAt = now();
         await this.persist();
         return structuredClone(calls);
@@ -1036,8 +1062,14 @@ export class Store {
                 merged.set(arg.key, arg);
             call.args = [...merged.values()].slice(0, TOOL_ARG_CAP);
         }
+        // THE PREVIEW IS "THE TEXT SO FAR", SO IT REPLACES. Every writer sends the whole text: the runtime
+        // accumulates the model's argument fragments before this is called, and Pi sends
+        // `tool_execution_update.partialResult` already accumulated. Appending here would concatenate two
+        // "so far"s - the reader would watch the output print itself twice. The clear at the preparing ->
+        // running handoff (`live: ""`) is the same statement, once: the arguments that were on screen while
+        // the call was being written are gone by the time it runs.
         if (patch.live !== undefined)
-            call.live = (call.live ?? "") + patch.live;
+            call.live = patch.live;
         // The question rides on the call rather than beside it, so this is the only write it needs.
         if (patch.question !== undefined)
             call.question = patch.question;
@@ -1067,6 +1099,14 @@ export class Store {
         message.piEntryId = piEntryId;
         await this.persist();
     }
+    /** Cache a locator Pi itself resolved while serving this conversation; never trust it as authorization. */
+    async setConversationPiSessionFile(conversationId, path) {
+        const conversation = this.requireConversation(conversationId);
+        if (conversation.piSessionFile === path)
+            return;
+        conversation.piSessionFile = path;
+        await this.persistMetadata(conversationId);
+    }
     /**
      * Reverts the conversation to the state right after `messageId`, in `state.json` only.
      *

package/dist/server/subagents.js

@@ -4,7 +4,8 @@ import { mkdir, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { agentSpawnArgs, readAgents } from "./agents.js";
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
-import { buildExtensionUiResponse, describeExtensionUiRequest, killTree, RpcChannel, } from "./runtime.js";
+import { buildExtensionUiResponse, describeExtensionUiRequest, killTree, } from "./runtime.js";
+import { RpcChannel } from "./rpc-channel.js";
 import { describeToolCall, TOOL_DETAIL_CAP } from "./tool-calls.js";
 /**
  * The tool-call derivation now lives in `tool-calls.js`, because the primary agent's runtime needs the
@@ -497,7 +498,7 @@ export class SubagentSupervisor {
                     noteUnhandled(`type ${JSON.stringify(record.type ?? "(missing type)")}`);
                 }
                 // A dead child will never settle, so waiting out another poll would only delay the failure.
-                if (!settled && child.exitCode !== null)
+                if (!settled && channel.closed)
                     throw new Error(`sub-agent ${agentId} (${id}) exited before settling (code ${child.exitCode}). ${channel.stderr.trim()}`);
             }
             for (const [key, count] of repeats)

package/dist/server/tool-registry.d.ts

@@ -0,0 +1,35 @@
+export type MountedTool = {
+    id: string;
+    slug: string;
+    name: string;
+    description?: string;
+    workspaceId: string;
+    entrypoint: string;
+    source: "user" | "builtin";
+    enabled: boolean;
+    createdAt: string;
+    updatedAt: string;
+};
+export declare class ToolRegistry {
+    private readonly dataDir;
+    private readonly file;
+    private items;
+    private loaded;
+    constructor(dataDir: string);
+    private load;
+    private save;
+    list(): Promise<MountedTool[]>;
+    register(input: {
+        workspaceId: string;
+        slug: string;
+        name: string;
+        description?: string;
+        entrypoint: string;
+    }, workspaceRoot: string): Promise<MountedTool>;
+    remove(id: string): Promise<boolean>;
+    setEnabled(id: string, enabled: boolean): Promise<MountedTool | undefined>;
+    resolve(id: string, workspaceRoot: string, resource?: string): Promise<{
+        tool: MountedTool;
+        file: string;
+    } | undefined>;
+}

package/dist/server/tool-registry.js

@@ -0,0 +1,74 @@
+import { mkdir, readFile, rename, writeFile, access, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+const MAX_TOOLS = 128;
+const MAX_SLUG = 64;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+export class ToolRegistry {
+    dataDir;
+    file;
+    items = [];
+    loaded = false;
+    constructor(dataDir) {
+        this.dataDir = dataDir;
+        this.file = join(dataDir, "tools.json");
+    }
+    async load() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        try {
+            const parsed = JSON.parse(await readFile(this.file, "utf8"));
+            if (Array.isArray(parsed))
+                this.items = parsed.filter(isTool);
+        }
+        catch {
+            this.items = [];
+        }
+    }
+    async save() {
+        await mkdir(this.dataDir, { recursive: true });
+        const tmp = `${this.file}.${process.pid}.tmp`;
+        await writeFile(tmp, JSON.stringify(this.items, null, 2), "utf8");
+        await rename(tmp, this.file);
+    }
+    async list() { await this.load(); return this.items.map((x) => ({ ...x })); }
+    async register(input, workspaceRoot) {
+        await this.load();
+        const slug = input.slug.trim().toLowerCase();
+        if (!SLUG.test(slug))
+            throw new Error("slug 只能包含小写字母、数字和连字符");
+        if (!input.name.trim() || input.name.length > 120)
+            throw new Error("工具名称无效");
+        const entrypoint = safeRelative(input.entrypoint);
+        const root = resolve(workspaceRoot);
+        const file = resolve(root, entrypoint);
+        if (!isInside(root, file))
+            throw new Error("entrypoint 必须位于工作区内");
+        const info = await stat(file).catch(() => undefined);
+        if (!info?.isFile())
+            throw new Error("entrypoint 文件不存在");
+        if (!entrypoint.endsWith(".html"))
+            throw new Error("entrypoint 必须是 HTML 文件");
+        if (this.items.some((x) => x.workspaceId === input.workspaceId && x.slug === slug))
+            throw new Error("工具 slug 已存在");
+        if (this.items.length >= MAX_TOOLS)
+            throw new Error("工具数量已达到上限");
+        const now = new Date().toISOString();
+        const tool = { id: `tool_${crypto.randomUUID()}`, slug, name: input.name.trim(), description: input.description?.trim().slice(0, 500), workspaceId: input.workspaceId, entrypoint, source: "user", enabled: true, createdAt: now, updatedAt: now };
+        this.items.push(tool);
+        await this.save();
+        return { ...tool };
+    }
+    async remove(id) { await this.load(); const before = this.items.length; this.items = this.items.filter((x) => x.id !== id); if (this.items.length !== before)
+        await this.save(); return before !== this.items.length; }
+    async setEnabled(id, enabled) { await this.load(); const item = this.items.find((x) => x.id === id); if (!item)
+        return undefined; item.enabled = enabled; item.updatedAt = new Date().toISOString(); await this.save(); return { ...item }; }
+    async resolve(id, workspaceRoot, resource = "") { await this.load(); const tool = this.items.find((x) => x.id === id && x.enabled); if (!tool)
+        return undefined; const root = resolve(workspaceRoot); const entrypoint = resolve(root, tool.entrypoint); if (!isInside(root, entrypoint))
+        return undefined; const file = resource ? resolve(dirname(entrypoint), safeRelative(resource)) : entrypoint; if (!isInside(dirname(entrypoint), file))
+        throw new Error("工具资源必须位于工具目录内"); await access(file).catch(() => { throw new Error("工具文件不存在"); }); return { tool: { ...tool }, file }; }
+}
+function safeRelative(value) { const p = value.replace(/\\/g, "/").trim(); if (!p || p.startsWith("/") || p.includes("\0") || p.split("/").includes(".."))
+    throw new Error("路径必须是工作区内的相对路径"); return p; }
+function isInside(root, target) { const r = relative(root, target); return r === "" || (!r.startsWith(".." + sep) && r !== ".." && !r.includes(":")); }
+function isTool(value) { const x = value; return !!x && typeof x === "object" && typeof x.id === "string" && typeof x.slug === "string" && typeof x.workspaceId === "string" && typeof x.entrypoint === "string" && (x.source === "user" || x.source === "builtin"); }