@evandu/super-pi 0.1.70 → 0.1.72

package/dist/server/rpc-channel.d.ts

@@ -0,0 +1,109 @@
+import type { ChildProcessWithoutNullStreams } from "node:child_process";
+/** Open-ended Pi RPC record; consumers validate fields before use. */
+export type RpcRecord = {
+    type?: string;
+    id?: string;
+    success?: boolean;
+    error?: string;
+    /** Every `response` record's payload. Kept opaque: only the catalog reader knows these shapes. */
+    data?: unknown;
+    /**
+     * `tool_execution_end` carries the tool's OUTPUT. Declared so it can be REDUCED by
+     * extractToolResultText and then dropped: the raw object must never travel past this record, and that
+     * reduction is the whole reason the result is safe to persist. Kept opaque for the same reason `data` is.
+     */
+    result?: unknown;
+    /** The tool_execution_update record's running output. Reduced by the same function as `result`, never carried raw. */
+    partialResult?: unknown;
+    /**
+     * The inner event of a `message_update`. `message` rides on `done` - the authoritative final
+     * assistant message, with its text content, its stop reason and its model (pi-ai AssistantMessageEvent).
+     */
+    assistantMessageEvent?: {
+        type?: string;
+        delta?: string;
+        contentIndex?: number;
+        partial?: unknown;
+        reason?: string;
+        message?: {
+            role?: string;
+            content?: unknown;
+            stopReason?: string;
+            model?: string;
+        };
+    };
+    /**
+     * Cumulative usage of the CURRENT assistant message, repeated on every one of that message's updates
+     * (modes/json-event.ts:56-59). Reading it anywhere but on `done` counts the same tokens per token.
+     */
+    usage?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        cost?: {
+            total?: number;
+        };
+    };
+    toolCallId?: string;
+    toolName?: string;
+    args?: unknown;
+    /**
+     * tool_execution_end payload. `result` is NOT declared: it is deliberately never read, because for a
+     * `read` it is the file's contents and this type is the one place a reader would reach for it. The two
+     * numbers below are the whole of what a human-readable tool row can honestly report.
+     */
+    isError?: boolean;
+    durationMs?: number;
+    method?: string;
+    title?: string;
+    options?: unknown;
+    message?: string;
+    placeholder?: string;
+    prefill?: string;
+    timeout?: number;
+    notifyType?: string;
+    statusKey?: string;
+    statusText?: string;
+    widgetKey?: string;
+    widgetLines?: unknown;
+    widgetPlacement?: string;
+    text?: string;
+    extensionPath?: string;
+    event?: string;
+    steering?: unknown;
+    followUp?: unknown;
+};
+/** One Pi child, its stdout reader, and the single writer to its stdin. */
+export declare class RpcChannel {
+    private readonly child;
+    private readonly records;
+    /** See `stash`: a drain loop must not discard another command's response. */
+    private readonly stashed;
+    private readonly waiters;
+    private buffer;
+    private exited;
+    private exitReason;
+    /** stderr is kept only to explain an early exit; a well-behaved Pi writes nothing here. */
+    stderr: string;
+    constructor(child: ChildProcessWithoutNullStreams);
+    get exitCode(): number | null;
+    get closed(): boolean;
+    private wake;
+    /** Waits for stdout or process exit without adding a fixed polling delay to every record. */
+    private changed;
+    /** Writes one JSONL command. Throws rather than silently dropping: a command Pi never sees is a lie the caller would act on. */
+    write(command: object): void;
+    /** Returns a response to its waiter after the drain loop encountered it. */
+    stash(record: RpcRecord): void;
+    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    next(timeoutMs?: number): Promise<RpcRecord | undefined>;
+    /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
+    request(command: {
+        id: string;
+        type: string;
+    } & Record<string, unknown>, timeoutMs: number): Promise<RpcRecord>;
+    private take;
+    /** Waits for one correlated response while leaving every unrelated record in order. */
+    waitFor(id: string, timeoutMs: number, what?: string): Promise<RpcRecord>;
+}

package/dist/server/rpc-channel.js

@@ -0,0 +1,117 @@
+/** One Pi child, its stdout reader, and the single writer to its stdin. */
+export class RpcChannel {
+    child;
+    records = [];
+    /** See `stash`: a drain loop must not discard another command's response. */
+    stashed = new Map();
+    waiters = new Set();
+    buffer = "";
+    exited = false;
+    exitReason = "";
+    /** stderr is kept only to explain an early exit; a well-behaved Pi writes nothing here. */
+    stderr = "";
+    constructor(child) {
+        this.child = child;
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (chunk) => { this.stderr += chunk.toString(); });
+        child.stdout.on("data", (chunk) => {
+            this.buffer += chunk.toString("utf8");
+            let changed = false;
+            let newline;
+            while ((newline = this.buffer.indexOf("\n")) >= 0) {
+                const line = this.buffer.slice(0, newline).replace(/\r$/, "");
+                this.buffer = this.buffer.slice(newline + 1);
+                if (!line)
+                    continue;
+                try {
+                    this.records.push(JSON.parse(line));
+                    changed = true;
+                }
+                catch { /* Pi stdout must be JSONL */ }
+            }
+            if (changed)
+                this.wake();
+        });
+        child.once("exit", (code, signal) => {
+            this.exited = true;
+            this.exitReason = signal ? `signal ${signal}` : `code ${code}`;
+            this.wake();
+        });
+        child.once("error", (error) => {
+            this.exited = true;
+            this.exitReason = error.message;
+            this.wake();
+        });
+    }
+    get exitCode() { return this.child.exitCode; }
+    get closed() { return this.exited || this.child.exitCode !== null; }
+    wake() {
+        for (const resolve of this.waiters)
+            resolve();
+        this.waiters.clear();
+    }
+    /** Waits for stdout or process exit without adding a fixed polling delay to every record. */
+    changed(timeoutMs) {
+        if (timeoutMs <= 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const finish = () => { clearTimeout(timer); this.waiters.delete(finish); resolve(); };
+            const timer = setTimeout(finish, timeoutMs);
+            this.waiters.add(finish);
+        });
+    }
+    /** Writes one JSONL command. Throws rather than silently dropping: a command Pi never sees is a lie the caller would act on. */
+    write(command) {
+        if (this.child.killed || this.child.stdin.destroyed)
+            throw new Error(`Pi RPC stdin is closed, so ${JSON.stringify(command)} was not sent`);
+        this.child.stdin.write(`${JSON.stringify(command)}\n`);
+    }
+    /** Returns a response to its waiter after the drain loop encountered it. */
+    stash(record) {
+        if (record.type === "response" && typeof record.id === "string") {
+            this.stashed.set(record.id, record);
+            this.wake();
+        }
+    }
+    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
+    async next(timeoutMs = 100) {
+        const deadline = performance.now() + timeoutMs;
+        for (;;) {
+            if (this.records.length)
+                return this.records.shift();
+            if (this.exited || this.child.exitCode !== null || performance.now() >= deadline)
+                return undefined;
+            await this.changed(deadline - performance.now());
+        }
+    }
+    /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
+    async request(command, timeoutMs) {
+        this.write(command);
+        return this.waitFor(command.id, timeoutMs, command.type);
+    }
+    take(id) {
+        const index = this.records.findIndex((record) => record.type === "response" && record.id === id);
+        if (index >= 0)
+            return this.records.splice(index, 1)[0];
+        const stashed = this.stashed.get(id);
+        if (!stashed)
+            return undefined;
+        this.stashed.delete(id);
+        return stashed;
+    }
+    /** Waits for one correlated response while leaving every unrelated record in order. */
+    async waitFor(id, timeoutMs, what = id) {
+        const deadline = performance.now() + timeoutMs;
+        for (;;) {
+            const record = this.take(id);
+            if (record)
+                return record;
+            if (this.exited || this.child.exitCode !== null)
+                throw new Error(`Pi RPC exited (${this.exitReason || `code ${this.child.exitCode}`}) while waiting for ${what}. ${this.stderr.trim()}`);
+            if (performance.now() >= deadline)
+                throw new Error(`Pi did not answer ${what} within ${timeoutMs}ms`);
+            await this.changed(deadline - performance.now());
+        }
+    }
+}

package/dist/server/runtime.d.ts

@@ -1,5 +1,7 @@
-import { type ChildProcessWithoutNullStreams } from "node:child_process";
+import { type RpcRecord } from "./rpc-channel.js";
+export { RpcChannel, type RpcRecord } from "./rpc-channel.js";
 import type { ActiveMemory } from "./active-memory.js";
+export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 import { type AgentDefinition, type Conversation, type ExtensionUiAnswer, type ExtensionUiRequest, type MessageImage, type ModelCatalog, type ModelOption, type ModelSelection, type PiQueueSnapshot, type ToolCallNotice, type ToolCallPreparing } from "./types.js";
 /**
  * Who answers Pi's Extension UI questions. The runtime never invents an answer: a blocking method
@@ -56,6 +58,8 @@ export interface AnswerInput {
      * revert boundary, which the revert handler reports in words.
      */
     onUserEntry?: (entryId: string) => void | Promise<void>;
+    /** Session file Pi resolved for the live worker. A host may cache it as a locator for a later revert. */
+    onSessionFile?: (path: string) => void | Promise<void>;
     /**
      * Called once per `tool_execution_start`, with the tool's name and the bounded label naming what it was
      * aimed at.
@@ -263,80 +267,6 @@ export declare class WelcomeRuntime implements AgentRuntime {
  * through the same channel instead of writing a second JSONL reader. Every field below is optional, so
  * a reader must check before using one.
  */
-export type RpcRecord = {
-    type?: string;
-    id?: string;
-    success?: boolean;
-    error?: string;
-    /** Every `response` record's payload. Kept opaque: only the catalog reader knows these shapes. */
-    data?: unknown;
-    /**
-     * `tool_execution_end` carries the tool's OUTPUT. Declared so it can be REDUCED by
-     * extractToolResultText and then dropped: the raw object must never travel past this record, and that
-     * reduction is the whole reason the result is safe to persist. Kept opaque for the same reason `data` is.
-     */
-    result?: unknown;
-    /** The tool_execution_update record's running output. Reduced by the same function as `result`, never carried raw. */
-    partialResult?: unknown;
-    /**
-     * The inner event of a `message_update`. `message` rides on `done` - the authoritative final
-     * assistant message, with its text content, its stop reason and its model (pi-ai AssistantMessageEvent).
-     */
-    assistantMessageEvent?: {
-        type?: string;
-        delta?: string;
-        contentIndex?: number;
-        partial?: unknown;
-        reason?: string;
-        message?: {
-            role?: string;
-            content?: unknown;
-            stopReason?: string;
-            model?: string;
-        };
-    };
-    /**
-     * Cumulative usage of the CURRENT assistant message, repeated on every one of that message's updates
-     * (modes/json-event.ts:56-59). Reading it anywhere but on `done` counts the same tokens per token.
-     */
-    usage?: {
-        input?: number;
-        output?: number;
-        cacheRead?: number;
-        cacheWrite?: number;
-        cost?: {
-            total?: number;
-        };
-    };
-    toolCallId?: string;
-    toolName?: string;
-    args?: unknown;
-    /**
-     * tool_execution_end payload. `result` is NOT declared: it is deliberately never read, because for a
-     * `read` it is the file's contents and this type is the one place a reader would reach for it. The two
-     * numbers below are the whole of what a human-readable tool row can honestly report.
-     */
-    isError?: boolean;
-    durationMs?: number;
-    method?: string;
-    title?: string;
-    options?: unknown;
-    message?: string;
-    placeholder?: string;
-    prefill?: string;
-    timeout?: number;
-    notifyType?: string;
-    statusKey?: string;
-    statusText?: string;
-    widgetKey?: string;
-    widgetLines?: unknown;
-    widgetPlacement?: string;
-    text?: string;
-    extensionPath?: string;
-    event?: string;
-    steering?: unknown;
-    followUp?: unknown;
-};
 /**
  * Reads Pi's `queue_update` payload, or returns undefined when the record is not one.
  *
@@ -366,58 +296,6 @@ export declare function describeExtensionUiRequest(record: RpcRecord): Extension
  * cannot produce a response Pi would read as a missing field.
  */
 export declare function buildExtensionUiResponse(request: ExtensionUiRequest, answer: ExtensionUiAnswer): ExtensionUiResponse;
-/** One Pi child, its stdout reader, and the single writer to its stdin. */
-export declare class RpcChannel {
-    private readonly child;
-    private readonly records;
-    /**
-     * Responses a drain loop pulled off the queue before the waiter that wanted them looked.
-     *
-     * THE RACE THIS EXISTS TO SETTLE, and it is not a rare one - it cost this file an intermittent test
-     * failure. One queue serves two kinds of reader: `waitFor`, which is after a specific command's answer by
-     * id, and `next`, which is a turn's drain loop reading whatever arrives first. The loop does not know
-     * which ids someone is waiting for, so it used to take the first record of any kind - including the answer
-     * to a `get_entries` written moments earlier - and the waiter then waited out its whole timeout for a
-     * response that had already been consumed and discarded.
-     *
-     * So the drain loop no longer decides an unmatched response is garbage: it HANDS IT BACK here, and the
-     * waiter finds it whether it got there first or second. Nothing is dropped, and nothing is waited for
-     * twice.
-     */
-    private readonly stashed;
-    private buffer;
-    /** stderr is kept only to explain an early exit; a well-behaved Pi writes nothing here. */
-    stderr: string;
-    constructor(child: ChildProcessWithoutNullStreams);
-    get exitCode(): number | null;
-    /** Writes one JSONL command. Throws rather than silently dropping: a command Pi never sees is a lie the caller would act on. */
-    write(command: object): void;
-    /**
-     * Returns one record to whoever is waiting for it, after a drain loop read it.
-     *
-     * Called for every response the loop does not consume itself. See `RpcChannel`'s note on `stashed` for why
-     * this is not the same as discarding it - discarding it silently cost a turn its revert boundary.
-     */
-    stash(record: RpcRecord): void;
-    /** Removes and returns the next record, or undefined after `timeoutMs` with nothing to read. */
-    next(timeoutMs?: number): Promise<RpcRecord | undefined>;
-    /** Sends a command and waits for its response. For one command; use write()+waitFor() to overlap several. */
-    request(command: {
-        id: string;
-        type: string;
-    } & Record<string, unknown>, timeoutMs: number): Promise<RpcRecord>;
-    /**
-     * Returns one response by id, from the queue if it is still there and from the stash if a drain loop got
-     * there first. Removing it from the stash is what keeps a single answer from being handed out twice.
-     */
-    private take;
-    /**
-     * Waits for the response to one command id. Every record that is not that response stays QUEUED in
-     * order, so a caller can have three requests in flight and still read all three answers: whoever
-     * asks first takes its own record and leaves the rest for the drain loop.
-     */
-    waitFor(id: string, timeoutMs: number, what?: string): Promise<RpcRecord>;
-}
 /**
  * The commands a freshly spawned Pi must be told before it runs a conversation's turn.
  *
@@ -446,105 +324,6 @@ export declare function sessionCommands(conversation: Pick<Conversation, "model"
  * only the shim, which is the exact failure this function exists to prevent.
  */
 export declare function killTree(pid: number): Promise<void>;
-/**
- * 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;
-}>;
 /**
  * Reads Pi's `steer` disposition out of its response payload.
  *
@@ -712,7 +491,7 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * own address, so it is the same string on every turn and is read once from the constructor's options.
      */
     private taskExtensionEnv;
-    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, images, memoryReview, memorySourceConversationId }: AnswerInput): AsyncIterable<string>;
+    answer({ conversation, prompt, signal, cwd, host, onPiQueue, onUserEntry, onSessionFile, onToolCall, onToolUpdate, onToolPreparing, onToolEnd, onThinking, images, memoryReview, memorySourceConversationId }: AnswerInput): AsyncIterable<string>;
     /**
      * Reads back the id of the user message this turn just created, and hands it to the caller.
      *