@evandu/super-pi 0.1.93 → 0.1.95

package/dist/server/capability.js

@@ -37,12 +37,12 @@ import { randomUUID, timingSafeEqual } from "node:crypto";
  */
 export const TASK_CAPABILITY_ENV = "SUPER_PI_TASK_CAPABILITY";
 /**
- * The live capability per conversation, while that conversation's primary turn is running.
+ * The live capability per conversation, while that conversation's primary session is alive.
  *
  * Keyed by CONVERSATION rather than being one global token, so two conversations being driven at once
- * cannot dispatch as each other and so releasing one turn's capability cannot revoke another's. The value
- * is replaced rather than accumulated: a conversation has one primary turn in flight, and a second spawn
- * for the same conversation supersedes the first.
+ * cannot dispatch as each other and so releasing one session's capability cannot revoke another's. The
+ * value is replaced rather than accumulated: a conversation has one primary session, and rebuilding it
+ * supersedes the first.
  */
 const live = new Map();
 /** A fixed capability, for tests. See `seededCapability` for why this does not weaken anything. */
@@ -50,21 +50,32 @@ const SEED = process.env.SUPER_PI_TASK_CAPABILITY_SEED;
 /** Announced once, because a capability that silently stopped rotating is a security change nobody agreed to. */
 let warnedSeed = false;
 /**
- * Mints the capability for one turn of one conversation, and returns it for the extension's environment.
+ * Mints the capability for one conversation's primary session, and returns it for the extension's
+ * environment.
  *
- * CALLED AT SPAWN, so the value is decided before the child exists and cannot be changed underneath it.
- * A turn that never reaches the spawn mints nothing, which is correct: there is no process to hand it to.
+ * CALLED WHEN THE SESSION IS CREATED, so the value is decided before the session exists and cannot be
+ * changed underneath it. A session that is never created mints nothing, which is correct: there is
+ * nothing to hand it to.
  *
- * ROTATED EVERY TURN, and that is the property the duration would not give on its own. A token valid for
- * the whole server lifetime would still be a token an unrelated process could not guess - but a token
- * valid only while its holder is alive is a token that stops being a credential the moment the turn ends,
- * so there is no window in which a leaked value is still live.
+ * ROTATED EVERY SESSION, and that is the property the duration would not give on its own. A token valid
+ * for the whole server lifetime would still be a token an unrelated process could not guess - but a token
+ * valid only while its holder is alive is a token that stops being a credential the moment the session
+ * ends, so there is no window in which a leaked value is still live.
+ *
+ * WHY IT IS THE SESSION AND NOT THE TURN. The capability travels in the extension's ENVIRONMENT, and an
+ * extension reads its environment when it is LOADED. A session that outlives its turns loads its
+ * extension once, so a per-turn token would have to be re-read from an environment that cannot change -
+ * and the second turn of a conversation would carry the FIRST turn's token, which the server would
+ * (correctly) refuse. The session is therefore the unit the credential belongs to, and the server
+ * enforces the turn separately. The application service owns the authoritative active-turn map, and
+ * passes that fact to `verifyCapability` at each protected endpoint. A stolen token is therefore worth
+ * nothing to a caller that cannot also start a turn.
  */
 export function mintCapability(conversationId) {
     if (SEED) {
         if (!warnedSeed) {
             warnedSeed = true;
-            console.warn(`Super Pi: SUPER_PI_TASK_CAPABILITY_SEED is set, so every dispatch capability is the same fixed value instead of being minted per turn. This is for tests - set it only on a server nothing else can reach.`);
+            console.warn(`Super Pi: SUPER_PI_TASK_CAPABILITY_SEED is set, so every dispatch capability is the same fixed value instead of being minted per session. This is for tests - set it only on a server nothing else can reach.`);
         }
         live.set(conversationId, SEED);
         return SEED;
@@ -74,11 +85,13 @@ export function mintCapability(conversationId) {
     return token;
 }
 /**
- * Forgets a conversation's capability, at the end of its turn.
+ * Forgets a conversation's capability, when its session ends.
  *
- * CALLED FROM `answer()`'s `finally`, so it runs on every exit - a turn that answered, a turn that threw,
- * and a turn whose child was killed. A capability that outlived its turn would keep working for a process
- * that no longer exists, which is precisely the shape of a credential with no owner.
+ * CALLED WHEN THE SESSION IS DESTROYED, so it runs on every exit - a session that was evicted as idle, a
+ * session that was thrown away by a revert, a session that was replaced because the conversation's
+ * configuration changed, and a session that was disposed at shutdown. A capability that outlived its
+ * session would keep working for a session that no longer exists, which is precisely the shape of a
+ * credential with no owner.
  */
 export function releaseCapability(conversationId) {
     live.delete(conversationId);
@@ -87,6 +100,7 @@ export function releaseCapability(conversationId) {
 export function releaseAllCapabilities() {
     live.clear();
 }
+/**
 /**
  * The capability currently valid for a conversation, or `undefined` when no primary turn is running.
  *
@@ -111,8 +125,8 @@ export function capabilityFor(conversationId) {
  * silently omitted the header would otherwise be indistinguishable from an attacker, and would keep
  * retrying forever.
  */
-export function verifyCapability(conversationId, presented) {
-    // A seeded server accepts its fixed value for EVERY conversation, including one with no turn running.
+export function verifyCapability(conversationId, presented, options = {}) {
+    // A seeded server accepts its fixed value for EVERY conversation, including one with no session.
     // That relaxation is exactly the test affordance and nothing else: `SEED` is documented as test-only,
     // and a process that can set it could set `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
     // The comparison below is still real - a wrong value is still refused - so a seeded server still catches
@@ -121,7 +135,7 @@ export function verifyCapability(conversationId, presented) {
     if (!expected) {
         return {
             ok: false,
-            message: `No primary turn is running for conversation ${conversationId}, so there is nothing that could have dispatched this. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
+            message: `No primary session is running for conversation ${conversationId}, so there is nothing that could have dispatched this. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
         };
     }
     if (typeof presented !== "string" || !presented) {
@@ -130,7 +144,27 @@ export function verifyCapability(conversationId, presented) {
     const left = Buffer.from(expected);
     const right = Buffer.from(presented);
     if (left.length !== right.length || !timingSafeEqual(left, right)) {
-        return { ok: false, message: `The ${TASK_CAPABILITY_ENV} presented does not match the one this turn was given. It is minted per turn, so a value from an earlier turn - or from another conversation - is not accepted. Do not retry the same call.` };
+        return { ok: false, message: `The ${TASK_CAPABILITY_ENV} presented does not match the one this session was given. It is minted per session, so a value from an earlier session - or from another conversation - is not accepted. Do not retry the same call.` };
+    }
+    // THE SECOND HALF. The token proves the caller holds this session's credential; this proves the
+    // session is actually doing something. A dispatch is accepted only while a turn is running, which is
+    // what a session-scoped token would otherwise have lost: the value is now good for the whole life of
+    // the session rather than for one turn, and a live turn is the difference between "the right
+    // credential" and "the right credential being used at the right time".
+    //
+    // A conversation that has a session but is idle has nothing to dispatch FOR: there is no turn, no
+    // model, no transcript being written. A caller presenting a valid token for an idle conversation is
+    // not the primary agent of a running turn - it is something replaying a value it read earlier.
+    //
+    // A SEEDED SERVER IS EXEMPT, and that is the same relaxation the seeded value itself gets: a seeded
+    // server already accepts its fixed token for a conversation with no session at all, and the seed is a
+    // documented test-only affordance. A process able to set the seed could set
+    // `SUPER_PI_ACCESS_TOKEN` instead and already have full control.
+    if (!SEED && options.running !== true) {
+        return {
+            ok: false,
+            message: `Conversation ${conversationId} is not running a turn, so there is no primary agent to dispatch for. Dispatch happens from inside a turn: send the tool call during a turn rather than posting to the server directly.`,
+        };
     }
     return { ok: true };
 }

package/dist/server/http-server.js

@@ -8,7 +8,6 @@ import { describe as describeFilesError, fileMeta, listDirectory, MAX_FILE_BYTES
 import { findUploadFile, MAX_UPLOAD_BODY_BYTES, saveUpload } from "./upload.js";
 import { checkDiskVersion } from "./version.js";
 import { gitDiff, gitLog, gitStatus } from "./git.js";
-import { verifyCapability } from "./capability.js";
 import { MAX_KNOWLEDGE_REQUEST_BYTES } from "./knowledge.js";
 import { MAX_TOOL_BODY_BYTES } from "./tool-registry.js";
 import { packageUpdateArgs } from "./update.js";
@@ -222,7 +221,7 @@ export function createHttpServer(options) {
         // the same reason: it is reached only by the Pi process of one turn, carrying that turn's
         // capability in a header. The MANAGEMENT half (`/api/knowledge`) is deliberately NOT exempted - it
         // imports and deletes documents, so it stays behind the ordinary token.
-        if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
+        if (requestPath !== "/api/memory/tool" && requestPath !== "/api/knowledge/tool" && requestPath !== "/api/todos" && requestPath !== "/api/question" && (requestPath !== "/api/tools" || request.method !== "POST") && !requestPath.startsWith("/tools/") && !isAuthorized(request, accessToken)) {
             response.writeHead(401, { "www-authenticate": "Bearer" }).end("Authentication required");
             return;
         }
@@ -300,7 +299,7 @@ export function createHttpServer(options) {
                         json(401, { error: "authentication or agent capability required" });
                         return;
                     }
-                    const verdict = verifyCapability(body.conversationId, body.capability ?? request.headers["x-super-pi-capability"]);
+                    const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability ?? request.headers["x-super-pi-capability"]);
                     if (!verdict.ok) {
                         json(403, { error: verdict.message });
                         return;
@@ -811,9 +810,8 @@ export function createHttpServer(options) {
                 json(400, { error: "cmd, cwd and conversationId are required" });
                 return;
             }
-            // Verify capability to prove this came from the primary agent
-            const { verifyCapability } = await import("./capability.js");
-            const result = verifyCapability(conversationId, capability);
+            // Verify both the credential and RunService's authoritative active-turn state.
+            const result = runService.verifyPrimaryCapability(conversationId, capability);
             if (!result.ok) {
                 json(403, { error: result.message });
                 return;
@@ -915,6 +913,11 @@ export function createHttpServer(options) {
                 const conversationId = body.conversationId?.trim();
                 if (!conversationId)
                     throw new Error("todowrite requires conversationId");
+                const verdict = runService.verifyPrimaryCapability(conversationId, body.capability);
+                if (!verdict.ok) {
+                    json(403, { error: verdict.message });
+                    return;
+                }
                 const { todos, dropped } = await store.setTodos(conversationId, body.todos);
                 broadcaster.broadcastState();
                 json(200, { todos, dropped, conversationId });
@@ -936,6 +939,11 @@ export function createHttpServer(options) {
                 const body = JSON.parse(raw);
                 if (!body.conversationId || !body.question || !Array.isArray(body.options))
                     throw new Error("invalid question");
+                const verdict = runService.verifyPrimaryCapability(body.conversationId, body.capability);
+                if (!verdict.ok) {
+                    response.writeHead(403, { "content-type": "application/json" }).end(JSON.stringify({ error: verdict.message }));
+                    return;
+                }
                 const result = await runService.askQuestion(body.conversationId);
                 response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify(result));
             }

package/dist/server/index.js

@@ -198,11 +198,20 @@ async function shutdown(reason) {
         execService.closeAll();
         runService.abortAll();
         workflows.abortAll();
-        releaseAllCapabilities();
         for (const c of store.snapshot().conversations) {
             extensionUiService.cancelPendingUi(c.id, "aborted");
         }
         await Promise.all([runService.waitForIdle(), workflows.waitForIdle()]);
+        // THE LIVE SESSIONS GO NEXT, AND THEY HAVE TO GO EXPLICITLY. `runService.abortAll()` stops the
+        // TURNS, and a stopped turn is not a stopped session: a session with nothing running on it is idle,
+        // it holds a model client and a session file, and nothing in the abort path would reach it. So
+        // without this the server would exit with a session per conversation still alive - and on Windows
+        // those sessions hold their working directory open, which is the lock that made a deleted workspace
+        // fail to go away.
+        await runtime.disposeSessions?.();
+        // The capabilities die AFTER the sessions that carry them: a session that is still alive could
+        // otherwise use a credential the server has already forgotten about.
+        releaseAllCapabilities();
         await store.flush();
         wsServer.close();
         httpServer.closeAllConnections();

package/dist/server/pi-command.d.ts

@@ -16,7 +16,8 @@
 export type PiCommandResolution = {
     found: true;
     command: string;
-    via: string;
+    via: string; /** Whether the command was named explicitly rather than found. */
+    explicit: boolean;
 } | {
     found: false;
     reason: string;
@@ -29,6 +30,17 @@ export interface PiCommandOptions {
     env?: Record<string, string | undefined>;
     platform?: NodeJS.Platform;
     exists?: (path: string) => boolean;
+    /**
+     * Where the "copy of Pi that came with Super Pi" is looked for, and how it is found.
+     *
+     * INJECTED, and the reason is the same reason `exists` is: the bundled lookup walks the REAL
+     * filesystem, so a test that asserts a resolution RULE ("PATH wins", "the global directory is
+     * searched") would otherwise be answered by whatever happens to be installed on the machine running
+     * the test. The rule being asserted has to be the only thing that decides the answer.
+     *
+     * The default walks up from this module's own location, which is the tree Super Pi was loaded from.
+     */
+    bundled?: (exists: (path: string) => boolean, platform: NodeJS.Platform) => string | undefined;
 }
 /**
  * Resolves the command that starts Pi: the explicit override, then PATH, then npm's global bin
@@ -38,6 +50,22 @@ export interface PiCommandOptions {
  * silent fallback would make a typo in `SUPER_PI_PI_COMMAND` look like a working Pi somewhere else.
  */
 export declare function resolvePiCommand(options?: PiCommandOptions): PiCommandResolution;
+/**
+ * The `pi` executable of the Pi package Super Pi depends on, if it is installed next to Super Pi.
+ *
+ * npm puts a dependency's binaries in `node_modules/.bin`, as a shell script on POSIX and as a `.cmd`
+ * shim on Windows. Two layouts have to be covered, because Super Pi runs in both:
+ *
+ * - INSTALLED: `<node_modules>/@evandu/super-pi/dist/server/pi-command.js`, and the shim is at
+ *   `<node_modules>/.bin/pi` - the `.bin` of the tree that HOLDS Super Pi, two levels up.
+ * - A CHECKOUT: `<repo>/dist/server/pi-command.js`, and the shim is at `<repo>/node_modules/.bin/pi`
+ *   - the `.bin` of Super Pi's OWN tree.
+ *
+ * So every level of the walk checks both `<dir>/.bin` and `<dir>/node_modules/.bin`, and the walk
+ * starts at this module's own location rather than at `process.cwd()`: the server is started from
+ * wherever the user happened to be, and the answer must not depend on that.
+ */
+export declare function bundledPiCommand(exists?: (path: string) => boolean, platform?: NodeJS.Platform): string | undefined;
 /**
  * Decodes a child process's output, falling back to the console code page when it is not UTF-8.
  *

package/dist/server/pi-command.js

@@ -100,6 +100,7 @@ const firstHit = (names, directories, exists, platform) => {
 export function resolvePiCommand(options = {}) {
     const { command, env = process.env, platform = process.platform } = options;
     const exists = options.exists ?? defaultExists(platform);
+    const findBundled = options.bundled ?? bundledPiCommand;
     const names = launcherNames(platform);
     const explicit = (command ?? env.SUPER_PI_PI_COMMAND ?? "").trim();
     const onPath = pathDirectories(env, platform);
@@ -109,7 +110,7 @@ export function resolvePiCommand(options = {}) {
         if (/[\\/]/.test(explicit)) {
             const full = nativeEntry(explicit, platform) ?? explicit;
             if (exists(full))
-                return { found: true, command: full, via: label };
+                return { found: true, command: full, via: label, explicit: true };
             return {
                 found: false,
                 reason: `${label} points at ${full}, and no such file exists. Fix ${command ? "that argument" : "SUPER_PI_PI_COMMAND"} or unset it to fall back to PATH and npm's global bin directory. This is an environment problem, not a defect in the agent mechanism.`,
@@ -118,26 +119,78 @@ export function resolvePiCommand(options = {}) {
         }
         const hit = firstHit([explicit], [...onPath, ...globalDirs], exists, platform);
         if (hit)
-            return { found: true, command: hit.command, via: `${label} (${hit.dir})` };
+            return { found: true, command: hit.command, via: `${label} (${hit.dir})`, explicit: true };
         return {
             found: false,
             reason: `${label} names ${explicit}, which is on no PATH entry and in none of npm's global bin directories. This is an environment problem, not a defect in the agent mechanism.`,
             searched: [...onPath, ...globalDirs],
         };
     }
+    // THE COPY OF PI THAT CAME WITH SUPER PI, and it comes FIRST among the automatic choices.
+    //
+    // Super Pi depends on Pi's package, so npm installs it and puts its `pi` executable in
+    // `node_modules/.bin` - which is not on the user's PATH, and which is therefore invisible to the
+    // lookups below. Two reasons it wins over a Pi the user installed separately:
+    //
+    // 1. ONE Pi version in the product. The primary agent runs on the SDK - the very same package - and
+    //    the sub-agents spawn an executable. If those two were different versions, one conversation could
+    //    load the same extension file into two different Pi versions, and the older one would quietly
+    //    lack a tool the newer one has. One package, one version, one set of extensions.
+    // 2. "Installing Super Pi installs Pi" is the product's promise, and it only holds if the copy that
+    //    came with Super Pi is the copy Super Pi runs.
+    //
+    // A user's own Pi is still reachable by NAMING it (`SUPER_PI_PI_COMMAND`), which is the explicit
+    // override and wins outright - that is how the test suite drives a fake peer, and it is a legitimate
+    // thing for a person to want.
+    const bundled = findBundled(exists, platform);
+    if (bundled)
+        return { found: true, command: bundled, via: "the copy of Pi that came with Super Pi", explicit: false };
     const namesFound = firstHit(names, onPath, exists, platform);
     if (namesFound)
-        return { found: true, command: namesFound.command, via: `PATH (${namesFound.dir})` };
+        return { found: true, command: namesFound.command, via: `PATH (${namesFound.dir})`, explicit: false };
     const globalFound = firstHit(names, globalDirs, exists, platform);
     if (globalFound)
-        return { found: true, command: globalFound.command, via: `npm's global bin directory (${globalFound.dir})` };
+        return { found: true, command: globalFound.command, via: `npm's global bin directory (${globalFound.dir})`, explicit: false };
     const searched = [...new Set([...onPath, ...globalDirs])];
     return {
         found: false,
-        reason: `Pi was not found: no ${names.map((name) => `"${name}"`).join(" or ")} in ${searched.length} directory(ies) on PATH or in npm's global bin location (${searched.join(", ") || "none known"}). Install it with "npm i -g pi" or set SUPER_PI_PI_COMMAND to its full path. This is an environment fact, NOT evidence that the agent mechanism is broken - only a Pi that IS present and disagrees can say that.`,
+        reason: `Pi was not found: no ${names.map((name) => `"${name}"`).join(" or ")} in ${searched.length} directory(ies) on PATH or in npm's global bin location (${searched.join(", ") || "none known"}), and Super Pi's own copy of Pi is not installed either. Reinstall Super Pi (npm i -g @evandu/super-pi) so that Pi comes with it, or set SUPER_PI_PI_COMMAND to a Pi's full path. This is an environment fact, NOT evidence that the agent mechanism is broken - only a Pi that IS present and disagrees can say that.`,
         searched,
     };
 }
+/**
+ * The `pi` executable of the Pi package Super Pi depends on, if it is installed next to Super Pi.
+ *
+ * npm puts a dependency's binaries in `node_modules/.bin`, as a shell script on POSIX and as a `.cmd`
+ * shim on Windows. Two layouts have to be covered, because Super Pi runs in both:
+ *
+ * - INSTALLED: `<node_modules>/@evandu/super-pi/dist/server/pi-command.js`, and the shim is at
+ *   `<node_modules>/.bin/pi` - the `.bin` of the tree that HOLDS Super Pi, two levels up.
+ * - A CHECKOUT: `<repo>/dist/server/pi-command.js`, and the shim is at `<repo>/node_modules/.bin/pi`
+ *   - the `.bin` of Super Pi's OWN tree.
+ *
+ * So every level of the walk checks both `<dir>/.bin` and `<dir>/node_modules/.bin`, and the walk
+ * starts at this module's own location rather than at `process.cwd()`: the server is started from
+ * wherever the user happened to be, and the answer must not depend on that.
+ */
+export function bundledPiCommand(exists = defaultExists(process.platform), platform = process.platform) {
+    const at = joinFor(platform);
+    let dir = import.meta.dirname;
+    for (let depth = 0; depth < 6; depth += 1) {
+        for (const binDir of [at(dir, ".bin"), at(dir, "node_modules", ".bin")]) {
+            for (const name of launcherNames(platform)) {
+                const candidate = at(binDir, name);
+                if (exists(candidate))
+                    return candidate;
+            }
+        }
+        const parent = at(dir, "..");
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
 /**
  * Decodes a child process's output, falling back to the console code page when it is not UTF-8.
  *

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

@@ -0,0 +1,111 @@
+/**
+ * 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 type { PiQueueSnapshot, ToolCallNotice, ToolCallPreparing } from "./types.js";
+/**
+ * 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 declare function describePiQueue(record: unknown): PiQueueSnapshot | undefined;
+/**
+ * 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 declare function describeDeliveredUserMessage(record: unknown): string | undefined;
+/** What the bridge hands to the turn, one item at a time. */
+export type TurnItem = 
+/** A chunk of assistant text. */
+{
+    kind: "text";
+    delta: string;
+}
+/** The turn is over. */
+ | {
+    kind: "end";
+}
+/** The turn failed. */
+ | {
+    kind: "error";
+    error: Error;
+};
+/** The callbacks a turn supplies. The names match the RPC runtime's, so the two paths behave alike. */
+export interface TurnEventHandlers {
+    onToolCall?(call: ToolCallNotice): void;
+    onToolUpdate?(call: ToolCallNotice): void;
+    onToolPreparing?(call: ToolCallPreparing): void;
+    onToolEnd?(call: ToolCallNotice): void;
+    onThinking?(delta: string): void;
+    onThinkingEnd?(): void;
+    /** A steer this turn delivered - the text Pi picked up from its own queue. */
+    onSteerDelivered?(text: string): void;
+    /** Pi's own queue, as a full snapshot. */
+    onPiQueue?(queue: {
+        steering: string[];
+        followUp: string[];
+    }): void;
+}
+/**
+ * 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 declare class TurnQueue {
+    private readonly items;
+    private readonly waiters;
+    private settled;
+    /**
+     * 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.
+     */
+    readonly settledSignal: Promise<void>;
+    private markSettled;
+    constructor();
+    push(item: TurnItem): void;
+    /** Settles the queue with an error, for a turn that failed before it produced anything. */
+    fail(error: Error): void;
+    next(): Promise<TurnItem>;
+    get isSettled(): boolean;
+}
+/**
+ * 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 declare function handleSessionEvent(event: unknown, queue: TurnQueue, handlers: TurnEventHandlers, report: (key: string) => void): boolean;