@evandu/super-pi 0.1.94 → 0.1.96

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

@@ -0,0 +1,291 @@
+/**
+ * THE EVENT BRIDGE: turns a Pi session's event stream into the turn-shaped stream Super Pi consumes.
+ *
+ * WHY A BRIDGE AND NOT AN INLINE LOOP. The old design read a child's stdout in a `while` loop and
+ * dispatched records inline. The new design has no child and no stdout: Pi emits EVENTS through a
+ * subscription. A subscription is a push, and Super Pi's turn is a pull - `answer()` is an async
+ * generator that yields text deltas to its caller.
+ *
+ * A push has to become a pull somewhere, and this is where. The bridge keeps a queue of pending items
+ * and hands them out one at a time; the generator awaits the next item when the queue is empty. The
+ * ordering that matters is preserved exactly: the subscription callback pushes, and the queue is FIFO,
+ * so the order the reader sees is the order Pi emitted.
+ *
+ * THE BOUNDARY IS THE SAME AS BEFORE. Only the events Super Pi already consumed are routed; everything
+ * else is counted and reported once, exactly as the old `noteUnhandled` did. A record type that used to
+ * be announced as unhandled is still announced as unhandled - this bridge changes WHERE the events come
+ * from, not what they mean.
+ */
+import { describeToolCall, describeToolCallArgs, extractPartialResultText } from "./tool-calls.js";
+/** Keeps only real strings, so a malformed queue snapshot cannot put objects into a broadcast. */
+const textList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
+/**
+ * Reads a `queue_update` payload, or returns undefined when the record is not one.
+ *
+ * The same recogniser the RPC drain loop uses, and deliberately so: Pi's RPC mode forwards the session's
+ * own events verbatim, so a `queue_update` from a persistent SDK session and one from a child's stdout
+ * are the same fact in the same shape - Pi reporting what its in-memory steering/follow-up queues hold
+ * (`agent-session.ts:_emitQueueUpdate`). It is the ONLY proof that a steer was actually picked up: Pi
+ * removes the entry from its queue and emits this snapshot BEFORE it emits the delivered `message_start`,
+ * so a host that ignored it would have no way to tell "queued in Pi" from "delivered to the model".
+ */
+export function describePiQueue(record) {
+    const event = record;
+    if (event?.type !== "queue_update")
+        return undefined;
+    return { steering: textList(event.steering) ?? [], followUp: textList(event.followUp) ?? [] };
+}
+/**
+ * Reads the text of a steer Pi has just delivered, or undefined when this record is not one.
+ *
+ * A `message_start` carrying a `user` message is exactly that, and nothing else is: the prompt that
+ * opened the turn is never re-announced this way, and `assistant` messages are not deliveries.
+ *
+ * Content is joined with a newline rather than taken from the first block, so a multi-block steer comes
+ * back as the text the user actually wrote instead of its first paragraph. The text is a MATCHING HINT
+ * only - Pi identifies its own queued entry by `indexOf` on this string (`agent-session.ts:1123`) and so
+ * cannot tell two identical messages apart either, which is why the caller resolves a delivery by
+ * position and not by comparing this.
+ */
+export function describeDeliveredUserMessage(record) {
+    const event = record;
+    if (event?.type !== "message_start")
+        return undefined;
+    const message = event.message;
+    if (!message || typeof message !== "object" || message.role !== "user")
+        return undefined;
+    const content = message.content;
+    if (!Array.isArray(content))
+        return undefined;
+    const parts = content
+        .map((block) => (block && typeof block === "object" && typeof block.text === "string" ? block.text : undefined))
+        .filter((part) => part !== undefined);
+    return parts.length ? parts.join("\n") : undefined;
+}
+/**
+ * A queue of turn items, with the waiters that are blocked on it.
+ *
+ * The `settled` flag matters: a turn that ends must release every waiter, including one that is
+ * waiting for text that will never arrive. A generator awaiting an item on a queue nobody will ever
+ * push to is a turn that hangs forever, and a hung turn is a conversation that never answers.
+ */
+export class TurnQueue {
+    items = [];
+    waiters = [];
+    settled = false;
+    /**
+     * Resolves when Pi has SETTLED the turn, which is the real end of a turn.
+     *
+     * The distinction matters: Pi's `prompt()` resolves when the message has been accepted, which is
+     * long before the agent has settled. A caller that treats the prompt's resolution as the end of the
+     * turn would release the reader while the model was still producing - and the next turn would then
+     * arrive at a session Pi considers busy, which Pi refuses outright.
+     */
+    settledSignal;
+    markSettled;
+    constructor() {
+        this.settledSignal = new Promise((resolvePromise) => { this.markSettled = resolvePromise; });
+    }
+    push(item) {
+        if (this.settled)
+            return;
+        if (item.kind === "end" || item.kind === "error") {
+            this.settled = true;
+            // THE TERMINATING ITEM GOES AFTER THE TEXT THAT IS ALREADY QUEUED. The model produced those
+            // deltas, they are part of the answer, and dropping them would truncate the reply at exactly
+            // the moment the turn ended - which is the moment the answer is longest. So the terminal item is
+            // APPENDED, and a consumer reads the text first and the end second.
+            //
+            // A waiter that is already blocked is released immediately, because it is waiting for the NEXT
+            // item and the queue is finished - there will never be another one.
+            if (this.items.length === 0) {
+                const waiter = this.waiters.shift();
+                if (waiter) {
+                    waiter(item);
+                    this.markSettled();
+                    return;
+                }
+            }
+            this.items.push(item);
+            // Any waiter still blocked gets the terminal item, so a consumer that is behind by one wake-up
+            // still terminates rather than hanging.
+            while (this.waiters.length)
+                this.waiters.shift()?.(item);
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter)
+            waiter(item);
+        else
+            this.items.push(item);
+    }
+    /** Settles the queue with an error, for a turn that failed before it produced anything. */
+    fail(error) {
+        this.push({ kind: "error", error });
+    }
+    async next() {
+        // The queue is drained BEFORE the settled flag is consulted: the terminal item was APPENDED after
+        // the text, so a settled queue can still have text in it, and that text is the model's answer.
+        const item = this.items.shift();
+        if (item) {
+            // The settled signal fires when the terminal item is TAKEN, not when it is queued. A caller
+            // waiting for "the turn is over" must not be released while the answer is still unread.
+            if (item.kind === "end" || item.kind === "error")
+                this.markSettled();
+            return item;
+        }
+        if (this.settled) {
+            this.markSettled();
+            return { kind: "end" };
+        }
+        return new Promise((resolve) => { this.waiters.push(resolve); });
+    }
+    get isSettled() { return this.settled; }
+}
+/**
+ * Handles one Pi event, routing it to the queue and to the turn's callbacks.
+ *
+ * Returns whether the event was consumed. An unconsumed event is reported once per distinct type and
+ * then counted - the same policy the RPC loop applied, and for the same reason: an event type nobody
+ * understands is worth saying out loud exactly once.
+ */
+export function handleSessionEvent(event, queue, handlers, report) {
+    const record = event;
+    if (!record || typeof record.type !== "string")
+        return false;
+    switch (record.type) {
+        case "message_update": {
+            const assistant = record.assistantMessageEvent;
+            if (!assistant)
+                return false;
+            if (assistant.type === "text_delta") {
+                queue.push({ kind: "text", delta: assistant.delta ?? "" });
+                return true;
+            }
+            if (assistant.type === "thinking_delta") {
+                handlers.onThinking?.(assistant.delta ?? "");
+                return true;
+            }
+            if (assistant.type === "thinking_end") {
+                handlers.onThinkingEnd?.();
+                return true;
+            }
+            if (assistant.type === "toolcall_start" && typeof assistant.contentIndex === "number") {
+                handlers.onToolPreparing?.({ contentIndex: assistant.contentIndex, name: toolNameOf(assistant) });
+                return true;
+            }
+            if (assistant.type === "toolcall_end") {
+                // The name is announced with the START, and the end is what says the arguments are complete.
+                return true;
+            }
+            return false;
+        }
+        case "tool_execution_start": {
+            const id = record.toolCallId ?? "";
+            if (!id)
+                return true;
+            const name = record.toolName ?? "unknown";
+            try {
+                handlers.onToolCall?.({ id, name, detail: describeToolCall(name, record.args), args: describeToolCallArgs(record.args) });
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the tool call handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return true;
+        }
+        case "tool_execution_update": {
+            const id = record.toolCallId ?? "";
+            if (!id)
+                return true;
+            const name = record.toolName ?? "unknown";
+            const live = extractPartialResultText(record.partialResult);
+            try {
+                handlers.onToolUpdate?.({ id, name, detail: describeToolCall(name, record.args), args: describeToolCallArgs(record.args), ...(live ? { live } : {}) });
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the tool update handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return true;
+        }
+        case "tool_execution_end": {
+            const id = record.toolCallId ?? "";
+            if (!id)
+                return true;
+            const name = record.toolName ?? "unknown";
+            try {
+                handlers.onToolEnd?.({
+                    id,
+                    name,
+                    status: record.isError === true ? "error" : "ok",
+                    ...(typeof record.durationMs === "number" && Number.isFinite(record.durationMs) ? { durationMs: Math.max(0, Math.round(record.durationMs)) } : {}),
+                });
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the tool end handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return true;
+        }
+        case "queue_update": {
+            // Pi's own queue, pushed as a full snapshot whenever it changes. This is the only proof that a
+            // steer was really picked up - Pi removes the entry and emits this BEFORE the delivered
+            // `message_start` below - so it is routed, not dropped.
+            const snapshot = describePiQueue(record);
+            if (!snapshot)
+                return false;
+            try {
+                handlers.onPiQueue?.(snapshot);
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the pi queue handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return true;
+        }
+        case "message_start": {
+            // A STEER THIS TURN DELIVERED. Pi announces the moment a queued message stops waiting and starts
+            // being answered by emitting `message_start` with the user message it picked up, immediately after
+            // the `queue_update` above that shows the entry gone. The host uses it to split the turn so the
+            // answer lands under the message it answers.
+            //
+            // A NON-user `message_start` is not a delivery: it gets the same once-per-type report every other
+            // unrouted event gets, which is the same policy the RPC drain loop applies.
+            const delivered = describeDeliveredUserMessage(record);
+            if (delivered === undefined) {
+                report(`type ${JSON.stringify(record.type)}`);
+                return true;
+            }
+            try {
+                handlers.onSteerDelivered?.(delivered);
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: the steer delivery handler threw: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+            return true;
+        }
+        case "agent_settled": {
+            queue.push({ kind: "end" });
+            return true;
+        }
+        default:
+            // AN EVENT NOBODY UNDERSTANDS IS REPORTED, HERE. The reporting lives inside this function rather
+            // than in its caller so that a caller cannot forget it: a new event type that nobody handles
+            // would then be silently dropped, and the "it looks wired up but nothing happens" failure is
+            // exactly the one that is hardest to diagnose from the outside.
+            report(`type ${JSON.stringify(record.type)}`);
+            return true;
+    }
+}
+/**
+ * The name of a tool call, read the way the RPC side reads it.
+ *
+ * `toolcall_start` may carry the name directly, or only inside a partial content block - the RPC side
+ * reads the direct field first and falls back to the block, and the same order applies here, because
+ * the same Pi produces both shapes depending on how much of the call has been written.
+ */
+function toolNameOf(event) {
+    const direct = event.toolName;
+    if (typeof direct === "string" && direct)
+        return direct;
+    const content = event.partial?.content;
+    const block = Array.isArray(content) ? content.find((item) => item?.type === "toolCall") : undefined;
+    return typeof block?.name === "string" ? block.name : "";
+}

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

@@ -0,0 +1,166 @@
+/**
+ * THE SESSION POOL: one live Pi session per conversation, kept across turns.
+ *
+ * WHAT IT OWNS. A conversation's Pi session, its fingerprint, and the rule that decides when the live
+ * session has gone stale and must be thrown away. Everything that can make a session stale is a
+ * FINGERPRINT (see `pi-session.ts`): the agent's prompt, the tool allowlist, the mounted extensions,
+ * the workspace, the model. Pi decides all of those when a session is created and cannot change any of
+ * them afterwards, so a session whose fingerprint no longer matches the conversation's current
+ * requirements is not "slightly wrong" - it is the wrong session, and the only honest response is to
+ * replace it.
+ *
+ * WHY THE POOL IS EXPLICIT ABOUT EVICTING. A session holds a model client, a session file handle and a
+ * conversation context. Left alone, a server that has seen fifty conversations would hold fifty of
+ * them, and the ones nobody is using would be the ones costing the most memory. So an idle session is
+ * evicted after a while, and the conversation's context is not lost with it: Pi writes the transcript
+ * to disk, and the next session for that conversation is rebuilt from that file.
+ *
+ * THE REVERT CASE. `revert` truncates the transcript on disk. A live session's in-memory context does
+ * NOT change, and nothing in Pi would notice: the model would keep answering from history the user
+ * has withdrawn. So a revert must EVICT the session, and the next turn rebuilds from the truncated
+ * file. This is the one case where eviction is not an optimization but a correctness requirement.
+ */
+import { type PiSessionFactory, type PiSessionLike } from "./pi-session.js";
+/** What the pool needs to build a session for a conversation. */
+export interface SessionRequest {
+    conversationId: string;
+    cwd: string;
+    /** The agent's id, or null. */
+    agentId: string | null;
+    /** The environment Super Pi's extensions read when they are loaded. */
+    extensionEnv: Record<string, string>;
+    /** The tool allowlist, or undefined for Pi's own defaults. */
+    tools?: string[];
+    /** The tool denylist. */
+    excludeTools?: string[];
+    /** The model, when the conversation pins one. */
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    /** The thinking level, when the conversation pins one. */
+    thinkingLevel?: string;
+    /** The agent's system prompt file, when the conversation runs as an agent. */
+    systemPromptFile?: string;
+    /** Whether the agent prompt replaces Pi's own. */
+    systemPromptMode?: "replace" | "append";
+}
+/**
+ * The pool.
+ *
+ * One instance per server. It is deliberately not a general-purpose pool: the sessions it holds differ
+ * from each other in their agent, their tools and their workspace, so there is nothing to share between
+ * them and no reason to try.
+ */
+export declare class PiSessionPool {
+    /** Where Pi keeps its session files. */
+    private readonly sessionDir;
+    /** The repository root, for locating Super Pi's own extensions. */
+    private readonly repositoryRoot;
+    /** Pi's global configuration directory, when it is not Pi's own default. */
+    private readonly agentDir?;
+    /**
+     * Called when a session is destroyed, so the caller can release whatever the session was holding.
+     *
+     * A session holds a capability: the token its extension read out of the environment when it was
+     * loaded. When the session goes, that token must go with it - a credential whose holder no longer
+     * exists is exactly the shape the capability model exists to prevent. The pool does not know what a
+     * capability is, so it says WHEN and the caller says WHAT.
+     */
+    private readonly onSessionDestroyed?;
+    /**
+     * How a session is built. Injectable so a test can drive a session without a real Pi behind it.
+     */
+    private readonly factory;
+    /**
+     * Mints the credential the session's extension will hold. Injected rather than imported so the pool
+     * does not have to know what a capability is - it needs to know WHEN one is needed, and the caller
+     * knows what one looks like.
+     */
+    private readonly mintCapability;
+    private readonly sessions;
+    constructor(
+    /** Where Pi keeps its session files. */
+    sessionDir: string, 
+    /** The repository root, for locating Super Pi's own extensions. */
+    repositoryRoot: string, 
+    /** Pi's global configuration directory, when it is not Pi's own default. */
+    agentDir?: string | undefined, 
+    /**
+     * Called when a session is destroyed, so the caller can release whatever the session was holding.
+     *
+     * A session holds a capability: the token its extension read out of the environment when it was
+     * loaded. When the session goes, that token must go with it - a credential whose holder no longer
+     * exists is exactly the shape the capability model exists to prevent. The pool does not know what a
+     * capability is, so it says WHEN and the caller says WHAT.
+     */
+    onSessionDestroyed?: ((conversationId: string) => void) | undefined, 
+    /**
+     * How a session is built. Injectable so a test can drive a session without a real Pi behind it.
+     */
+    factory?: PiSessionFactory, 
+    /**
+     * Mints the credential the session's extension will hold. Injected rather than imported so the pool
+     * does not have to know what a capability is - it needs to know WHEN one is needed, and the caller
+     * knows what one looks like.
+     */
+    mintCapability?: (conversationId: string) => string);
+    /**
+     * The session for a conversation, built if there is none and REPLACED if the live one is stale.
+     *
+     * The fingerprint comparison is what makes a stale session impossible to use: it happens BEFORE the
+     * session is handed out, not after, so a caller can never accidentally run a turn on a session whose
+     * tool allowlist has changed.
+     */
+    acquire(request: SessionRequest): Promise<PiSessionLike>;
+    private build;
+    private fingerprintOf;
+    /**
+     * The live session for a conversation, without building one.
+     *
+     * Absent when there is none - including when the session is still being built, because a session
+     * that is not ready cannot be steered into.
+     */
+    get(conversationId: string): PiSessionLike | undefined;
+    /**
+     * Whether a conversation has a live session, without building one.
+     *
+     * Used by the paths that need to know whether a session EXISTS - `revert` has to know whether there is
+     * an in-memory context to invalidate - and by the tests.
+     */
+    has(conversationId: string): boolean;
+    /**
+     * Throws away a conversation's session.
+     *
+     * The reason this is a PUBLIC operation and not an internal detail is that the callers are the ones
+     * that know WHY the session is stale. `revert` calls it because the disk changed under the session;
+     * a configuration change calls it because the requirements changed. The pool does not second-guess
+     * either - it disposes what it is told to dispose.
+     */
+    evict(conversationId: string): Promise<void>;
+    /**
+     * Throws away every session that has not been used for a while.
+     *
+     * The conversation is not lost: Pi wrote the transcript to disk, and the next turn rebuilds the
+     * session from that file. What is lost is the in-memory context, which is exactly what an idle
+     * conversation does not need.
+     */
+    evictIdle(now?: number): Promise<void>;
+    /** Throws away every session. Used at shutdown. */
+    disposeAll(): Promise<void>;
+    /** The conversations with a live session. */
+    get conversationIds(): string[];
+}
+/**
+ * Where Super Pi's repository root is, found from the compiled server's own location.
+ *
+ * The extensions are mounted by PATH, and Pi resolves a relative path against the CONVERSATION's
+ * workspace rather than the server's directory - so the path has to be absolute, and it has to be
+ * derived from something that is the same in every way the server runs (built to `dist/server/`, or run
+ * from `src/server/` under tsx). `import.meta.dirname` is that thing.
+ */
+export declare function repositoryRootFrom(from?: string): string;
+/** Whether Super Pi's own extensions are present on disk. */
+export declare function extensionsAvailable(repositoryRoot: string): boolean;
+/** Whether the extension directory exists at all, for a clearer failure message. */
+export declare function extensionDirectoryExists(repositoryRoot: string): boolean;