@evandu/super-pi 0.1.101 → 0.1.103

package/dist/client/index.html

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

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

@@ -58,6 +58,27 @@ export declare class CatalogService {
      * Broadcasts subagents to connected clients.
      */
     broadcastSubagents(): Promise<void>;
+    /**
+     * Sets the app-wide default model, or clears it back to "Pi's own default".
+     *
+     * THE MODEL IS CHECKED AGAINST PI'S OWN CATALOG, for the same reason the workspace default is:
+     * a default Pi does not offer would be stamped onto every new conversation, and the first turn
+     * would fail on a model the user never chose. The check happens at SAVE time rather than at
+     * birth time so the user hears about it while they are still looking at the list.
+     *
+     * The label is taken from the catalog row rather than from the request, so the stored value
+     * always carries the display name Pi itself reported.
+     */
+    setDefaultModel(model: {
+        provider: string;
+        modelId: string;
+    } | null): Promise<void>;
+    /**
+     * The UNFILTERED catalog, for the settings window's model panel. Deliberately not the scoped one:
+     * the panel is where the app-wide default is chosen, and a workspace's model rules must not hide
+     * models from the place that decides what the app-wide default may be.
+     */
+    getAllCatalog(): Promise<ModelCatalog>;
     /**
      * Helper formatting an error when a requested model/thinking level is not offered by Pi.
      */

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

@@ -165,6 +165,43 @@ export class CatalogService {
     async broadcastSubagents() {
         this.broadcaster.broadcast({ type: "subagent.catalog", catalog: await this.subagentCatalog() });
     }
+    /**
+     * Sets the app-wide default model, or clears it back to "Pi's own default".
+     *
+     * THE MODEL IS CHECKED AGAINST PI'S OWN CATALOG, for the same reason the workspace default is:
+     * a default Pi does not offer would be stamped onto every new conversation, and the first turn
+     * would fail on a model the user never chose. The check happens at SAVE time rather than at
+     * birth time so the user hears about it while they are still looking at the list.
+     *
+     * The label is taken from the catalog row rather than from the request, so the stored value
+     * always carries the display name Pi itself reported.
+     */
+    async setDefaultModel(model) {
+        if (!this.store)
+            throw new Error("Store unavailable");
+        let selection;
+        if (model) {
+            const catalog = await this.runtime.catalog();
+            const option = catalog.source === "pi"
+                ? catalog.models.find(item => item.provider === model.provider && item.modelId === model.modelId)
+                : undefined;
+            if (catalog.source === "pi" && !option)
+                throw this.notOffered(`模型 ${model.provider}/${model.modelId}`, catalog);
+            selection = option
+                ? { provider: option.provider, modelId: option.modelId, label: option.label }
+                : { provider: model.provider, modelId: model.modelId, label: model.modelId };
+        }
+        await this.store.setDefaultModel(selection);
+        this.broadcaster.broadcastState();
+    }
+    /**
+     * The UNFILTERED catalog, for the settings window's model panel. Deliberately not the scoped one:
+     * the panel is where the app-wide default is chosen, and a workspace's model rules must not hide
+     * models from the place that decides what the app-wide default may be.
+     */
+    async getAllCatalog() {
+        return this.runtime.catalog();
+    }
     /**
      * Helper formatting an error when a requested model/thinking level is not offered by Pi.
      */

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

@@ -42,7 +42,13 @@ export class ConversationService {
         // stamp a dead selection onto every new conversation: the scoped catalog probe would
         // fail and leave the model/thinking controls unavailable. A missing or invalid default
         // means "follow Pi's current default" for this newly-created conversation.
-        let model = workspace.defaultModel;
+        // THE PRECEDENCE AT BIRTH IS WORKSPACE > APP > Pi. The app-wide default is a FALLBACK, not an
+        // override: a workspace that has a default of its own keeps it, and only a workspace with none
+        // inherits the app-wide one. Both are copied onto the conversation and never consulted again,
+        // so changing either default never rewrites an existing conversation.
+        const appDefault = this.store.snapshot().defaultModel;
+        const inheritsAppDefault = !workspace.defaultModel && Boolean(appDefault);
+        let model = workspace.defaultModel ?? appDefault;
         let thinkingLevel = workspace.defaultThinkingLevel;
         const catalog = model || thinkingLevel ? await this.runtime.catalog() : undefined;
         if (catalog?.source === "pi" && model) {
@@ -60,6 +66,19 @@ export class ConversationService {
                 }
             }
         }
+        if (inheritsAppDefault && model) {
+            // An app-wide default belongs to no workspace, so the workspace's model rules are checked HERE,
+            // at birth, where the workspace is finally known. A default the rules forbid is not stamped
+            // on: the conversation starts on Pi's own default instead, which is the same outcome as a
+            // workspace default that pointed at a model Pi no longer offers.
+            try {
+                assertModelAllowed(this.store.snapshot().modelFilterRules, workspace, model);
+            }
+            catch {
+                model = undefined;
+                thinkingLevel = undefined;
+            }
+        }
         const resolved = workspace.defaultAgentId
             ? await this.resolveAgentConfiguration({ id: workspaceId, model, thinkingLevel }, workspace.defaultAgentId, workspaceId)
             : { model, thinkingLevel };

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

@@ -219,6 +219,57 @@ export declare class RunService {
      * the moment Pi holds it.
      */
     onPiQueue(conversationId: string, snapshot: PiQueueSnapshot): void;
+    /**
+     * The message a delivery is about, resolved by the text Pi announced.
+     *
+     * WHY THE TEXT AND NOT THE POSITION. A message that was STEERED is `sending` here - claimed, so the
+     * user cannot withdraw it - and the oldest `sending` message is the one Pi picked up, because Pi's
+     * steering queue is FIFO. That is the old rule and it still holds. A message that was handed to Pi's
+     * FOLLOW-UP queue is NOT `sending`: Super Pi keeps it in its own list so the user can still withdraw
+     * it, and a conversation can hold a `waiting` message and a `sending` one at the same time. For that
+     * one, position is the wrong question and the text is the right one.
+     *
+     * THE TEXT IS THE SAME TEXT ON BOTH SIDES. Pi matches its own queue by `indexOf` on the message text
+     * (`agent-session.ts:1123`), so two messages with identical words are ONE entry to Pi and the first of
+     * them to Super Pi as well. Resolving by text is therefore not a guess that could pick a different
+     * message than Pi did - it is the same comparison Pi itself made.
+     *
+     * A `sending` message wins over a `waiting` one with the same text, because Pi drains its steering
+     * queue before its follow-up queue, so the steering message is the one that was delivered first.
+     */
+    private matchDeliveredMessage;
+    /**
+     * Hands a waiting message to Pi's follow-up queue, so the run that is already going answers it.
+     *
+     * WHY THIS EXISTS. A message typed while the agent was busy used to wait for the current turn to END
+     * and then be answered by a turn of its own - a fresh `prompt()`, which runs Pi's `_prepareRun`, which
+     * emits `before_agent_start`. Super Pi's memory extension answers that hook with an HTTP search and
+     * patches the system prompt with what came back, so every queued message paid for a round trip to the
+     * memory endpoint and for a prompt larger than the one before it. A follow-up is delivered by Pi's
+     * agent loop inside the running turn, so it pays for neither.
+     *
+     * IT IS AN OPTIMISATION, NOT A COMMITMENT. The message stays in Super Pi's own waiting list, so it is
+     * still the user's to withdraw and still the user's to interrupt, and if Pi does not deliver it - the
+     * run was aborted, the queues were cleared - the message falls back to being answered by a turn of its
+     * own. Nothing is lost either way, which is what makes it safe to try.
+     */
+    private submitToPiQueue;
+    /**
+     * Empties Pi's steering and follow-up queues for a conversation.
+     *
+     * WHY A HOST HAS TO DO THIS. Pi delivers whatever is left in those queues when the run ends, and it
+     * cannot take back a single message - `clear_queue` is the only queue command it has. So whenever
+     * Super Pi takes a message back, the queues have to be emptied, or Pi answers words the user believes
+     * they took back.
+     *
+     * NOTHING IS LOST. Every message Pi was holding is still in Super Pi's own waiting list, and the run's
+     * loop answers those as turns of their own.
+     *
+     * THE STEERS COME BACK. Emptying the queues also empties the steering queue, and a steer is a message
+     * the user asked to be answered NOW - so the ones Pi had not delivered go back in, and clearing the
+     * queues for one message does not silently un-steer another.
+     */
+    private clearPiQueues;
     /**
      * Opens a turn on a message that is ALREADY IN THE TRANSCRIPT.
      *

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

@@ -285,6 +285,11 @@ export class RunService {
                         console.warn(`Super Pi: auto-trigger for background exec result failed: ${error instanceof Error ? error.message : "unknown error"}`);
                     });
                 }
+                else {
+                    // THE CONVERSATION IS BUSY, so the run that is going answers this result itself - through
+                    // Pi's own follow-up queue, so the result does not have to wait for a turn of its own.
+                    await this.submitToPiQueue(task.conversationId, queued);
+                }
             }
             catch (error) {
                 console.warn(`Super Pi: exec result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -541,6 +546,118 @@ export class RunService {
     onPiQueue(conversationId, snapshot) {
         this.broadcaster.broadcast({ type: "pi.queue", conversationId, ...snapshot });
     }
+    /**
+     * The message a delivery is about, resolved by the text Pi announced.
+     *
+     * WHY THE TEXT AND NOT THE POSITION. A message that was STEERED is `sending` here - claimed, so the
+     * user cannot withdraw it - and the oldest `sending` message is the one Pi picked up, because Pi's
+     * steering queue is FIFO. That is the old rule and it still holds. A message that was handed to Pi's
+     * FOLLOW-UP queue is NOT `sending`: Super Pi keeps it in its own list so the user can still withdraw
+     * it, and a conversation can hold a `waiting` message and a `sending` one at the same time. For that
+     * one, position is the wrong question and the text is the right one.
+     *
+     * THE TEXT IS THE SAME TEXT ON BOTH SIDES. Pi matches its own queue by `indexOf` on the message text
+     * (`agent-session.ts:1123`), so two messages with identical words are ONE entry to Pi and the first of
+     * them to Super Pi as well. Resolving by text is therefore not a guess that could pick a different
+     * message than Pi did - it is the same comparison Pi itself made.
+     *
+     * A `sending` message wins over a `waiting` one with the same text, because Pi drains its steering
+     * queue before its follow-up queue, so the steering message is the one that was delivered first.
+     */
+    matchDeliveredMessage(conversationId, text) {
+        if (!text)
+            return undefined;
+        const waiting = this.store.listWaitingMessages(conversationId);
+        const match = waiting.find((item) => item.delivery === "sending" && composePrompt(item) === text)
+            ?? waiting.find((item) => item.delivery === "waiting" && composePrompt(item) === text);
+        return match?.id;
+    }
+    /**
+     * Hands a waiting message to Pi's follow-up queue, so the run that is already going answers it.
+     *
+     * WHY THIS EXISTS. A message typed while the agent was busy used to wait for the current turn to END
+     * and then be answered by a turn of its own - a fresh `prompt()`, which runs Pi's `_prepareRun`, which
+     * emits `before_agent_start`. Super Pi's memory extension answers that hook with an HTTP search and
+     * patches the system prompt with what came back, so every queued message paid for a round trip to the
+     * memory endpoint and for a prompt larger than the one before it. A follow-up is delivered by Pi's
+     * agent loop inside the running turn, so it pays for neither.
+     *
+     * IT IS AN OPTIMISATION, NOT A COMMITMENT. The message stays in Super Pi's own waiting list, so it is
+     * still the user's to withdraw and still the user's to interrupt, and if Pi does not deliver it - the
+     * run was aborted, the queues were cleared - the message falls back to being answered by a turn of its
+     * own. Nothing is lost either way, which is what makes it safe to try.
+     */
+    async submitToPiQueue(conversationId, message) {
+        if (!this.runtime.followUp)
+            return;
+        // NOTHING TO FOLLOW UP ON. With no turn running, Pi would hold the message until the NEXT one,
+        // which is a later answer than the one the message is waiting for.
+        if (!this.activeRuns.has(conversationId))
+            return;
+        // AN INTERRUPT IS ALREADY STARTING. It aborts the run and empties Pi's queues, so a message handed
+        // to Pi now would be taken back a moment later. It waits in the list for the next run, exactly as it
+        // did before.
+        if (this.interruptTargets.has(conversationId))
+            return;
+        // A MESSAGE THAT IS A COMMAND IS NOT QUEUED. Pi expands a skill command or a prompt template before
+        // it queues the text (`agent-session.ts:2221-2222`), and it REFUSES an extension command outright.
+        // An expanded text is not the text Super Pi has, so the delivery could not be resolved back to its
+        // message - the answer would land under the wrong question. Such a message waits for a turn of its
+        // own, where it is the prompt and the question and the answer are the same thing.
+        if (composePrompt(message).startsWith("/"))
+            return;
+        try {
+            await this.runtime.followUp(conversationId, composePrompt(message), message.images);
+        }
+        catch (error) {
+            // THE FALLBACK IS THE OLD BEHAVIOUR, so a refusal here is not a failure: the message stays in the
+            // waiting list and the run's loop answers it with a turn of its own.
+            console.warn(`Super Pi: handing a queued message to Pi's follow-up queue failed: ${error instanceof Error ? error.message : "unknown error"}`);
+        }
+    }
+    /**
+     * Empties Pi's steering and follow-up queues for a conversation.
+     *
+     * WHY A HOST HAS TO DO THIS. Pi delivers whatever is left in those queues when the run ends, and it
+     * cannot take back a single message - `clear_queue` is the only queue command it has. So whenever
+     * Super Pi takes a message back, the queues have to be emptied, or Pi answers words the user believes
+     * they took back.
+     *
+     * NOTHING IS LOST. Every message Pi was holding is still in Super Pi's own waiting list, and the run's
+     * loop answers those as turns of their own.
+     *
+     * THE STEERS COME BACK. Emptying the queues also empties the steering queue, and a steer is a message
+     * the user asked to be answered NOW - so the ones Pi had not delivered go back in, and clearing the
+     * queues for one message does not silently un-steer another.
+     */
+    async clearPiQueues(conversationId) {
+        if (!this.runtime.clearQueues)
+            return;
+        let cleared;
+        try {
+            cleared = await this.runtime.clearQueues(conversationId);
+        }
+        catch (error) {
+            console.warn(`Super Pi: clearing Pi's queues for ${conversationId} failed: ${error instanceof Error ? error.message : "unknown error"}`);
+            return;
+        }
+        for (const text of cleared.steering ?? []) {
+            // A STEER NEEDS A TURN TO GO INTO. With no turn running there is nothing to steer, and the message
+            // is released back to `waiting` when the run ends anyway - so it is answered as a turn of its own.
+            if (this.runtime.canSteer && !this.runtime.canSteer(conversationId))
+                continue;
+            const message = this.store.listWaitingMessages(conversationId)
+                .find((item) => item.delivery === "sending" && composePrompt(item) === text);
+            if (!message)
+                continue;
+            try {
+                await this.runtime.steer?.(conversationId, text, message.images);
+            }
+            catch (error) {
+                console.warn(`Super Pi: putting a steered message back failed: ${error instanceof Error ? error.message : "unknown error"}`);
+            }
+        }
+    }
     /**
      * Opens a turn on a message that is ALREADY IN THE TRANSCRIPT.
      *
@@ -825,18 +942,28 @@ export class RunService {
          * cleared rather than reassigned for the same reason. `thinkingBlock` continues numbering on purpose:
          * it is a global fold sequence, and restarting it would make the browser render two folds numbered 0.
          */
-        const onSteerDelivered = () => {
-            enqueueTools("a steer being delivered", async () => {
+        const onSteerDelivered = (text) => {
+            enqueueTools("a queued message being delivered", async () => {
                 const previous = assistant;
-                // Checkpoint first: the message being left behind is complete - Pi drains steering at a turn
+                // Checkpoint first: the message being left behind is complete - Pi drains its queues at a turn
                 // boundary - and this is the last chance to write it durably with the lane it belongs to.
                 await this.store.checkpointMessage(conversation.id, previous.id);
-                const delivered = await this.store.deliverWaitingMessage(conversation.id, agentIdentity);
+                // WHICH MESSAGE THIS DELIVERY IS ABOUT. Pi announces the text it picked up, and Pi itself matches
+                // its own queue by that text (`agent-session.ts:1123`), so the same text resolves to the same
+                // message on both sides - including when two messages carry identical words, where both sides
+                // pick the first. A message handed to Pi's FOLLOW-UP queue was never claimed here: it is still
+                // `waiting`, so the user can still withdraw it, and a conversation can hold a `waiting` and a
+                // `sending` message at the same time. Position cannot answer that one; the text can.
+                //
+                // WHEN THE TEXT MATCHES NOTHING the old position-based answer is used, which is the steer path's
+                // proven behaviour: the message Pi is holding is the one Pi picked up. A text that matches
+                // nothing AND has no `sending` message is a delivery of a message Super Pi no longer has - one
+                // the user withdrew - and there is then nothing to open an answer to.
+                const target = this.matchDeliveredMessage(conversation.id, text);
+                const delivered = await this.store.deliverWaitingMessage(conversation.id, agentIdentity, target);
                 // NOTHING TO DELIVER MEANS NOTHING TO SPLIT. Pi may announce a user `message_start` that this
                 // server never handed it - the prompt that opened the turn is the obvious case - and inventing an
-                // assistant message for one of those would open an empty bubble before every single turn. The
-                // question "was anything `sending`?" is the server's own state, not something the event decides,
-                // which is the same reason the delivery is matched by position rather than by text.
+                // assistant message for one of those would open an empty bubble before every single turn.
                 if (!delivered)
                     return [];
                 const next = delivered.assistant;
@@ -978,6 +1105,13 @@ export class RunService {
             for (;;) {
                 if (controller.signal.aborted)
                     break;
+                // PI'S QUEUES ARE EMPTIED BEFORE THE NEXT MESSAGE IS TAKEN. A message handed to Pi's follow-up
+                // queue is delivered by the agent loop inside the run that has just ended - Pi drains that queue
+                // before it settles - so whatever is STILL in the queue when the turn ended was not delivered.
+                // Emptying it gives those messages back: they are still in the waiting list, and the loop below
+                // answers them with a turn of their own, which is the behaviour there was before Pi's queue was
+                // used at all. Nothing is lost, and nothing is delivered twice.
+                await this.clearPiQueues(conversation.id);
                 // Taken AND opened, in that order, by two separate writes. The take is what bounds this loop -
                 // every pass strictly shrinks the waiting set - and it is what makes a crash honest, because a
                 // server that dies between the two has a message that is neither waiting nor answered, and the
@@ -1045,6 +1179,10 @@ export class RunService {
                 await this.store.markMessageWaiting(conversationId, message.id);
                 this.broadcaster.broadcastState();
             }
+            // The turn that is running answers this message itself, through Pi's own follow-up queue, rather
+            // than by a turn of its own once the running one is over. The message stays in the waiting list
+            // either way, so it is still the user's to withdraw - Pi is holding a copy, not the only copy.
+            await this.submitToPiQueue(conversationId, message);
             return;
         }
         const controller = new AbortController();
@@ -1199,6 +1337,12 @@ export class RunService {
         try {
             if (this.activeRuns.has(conversationId))
                 await this.stopRun(conversationId);
+            // PI'S QUEUES ARE EMPTIED BEFORE THE SELECTED MESSAGE IS ANSWERED ON ITS OWN. The message may be
+            // in Pi's follow-up queue - it was handed over when it was written - and Pi would deliver it when
+            // the aborted run ended. The message is about to be answered as a turn of its own, so the queue
+            // copy has to go: a message answered twice is worse than one answered once, and the transcript
+            // would show the same words under two answers.
+            await this.clearPiQueues(conversationId);
             await this.awaitRunSlotReleased(conversationId);
             await this.processWaitingMessage(conversationId, messageId);
         }
@@ -1300,6 +1444,12 @@ export class RunService {
     async cancelQueuedUnsafe(conversationId, messageId) {
         if (this.interruptTargets.get(conversationId) === messageId)
             throw new Error("这条消息正在打断并回答，无法撤回");
+        // PI'S QUEUES ARE EMPTIED BEFORE THE MESSAGE IS TAKEN BACK. A message that was handed to Pi's
+        // follow-up queue is in Pi's hands as well as in Super Pi's, and Pi would deliver it when the run
+        // ends - the model would answer words the user believes they withdrew. Pi cannot take back one
+        // message, so its queues are emptied; the other messages Pi was holding are still in Super Pi's
+        // waiting list and are answered as turns of their own.
+        await this.clearPiQueues(conversationId);
         await this.store.cancelWaitingMessage(conversationId, messageId);
         this.broadcaster.broadcastState();
     }

package/dist/server/command-handler.js

@@ -65,6 +65,10 @@ export class CommandHandler {
             await this.catalogService.setModelRules(command.rules);
             return;
         }
+        if (command.type === "settings.defaultModel") {
+            await this.catalogService.setDefaultModel(command.model);
+            return;
+        }
         if (command.type === "workspace.create") {
             return await this.workspaceService.createWorkspace(command.name, command.path);
         }
@@ -239,6 +243,14 @@ export class CommandHandler {
                 await this.catalogService.broadcastCatalog(undefined, command.conversationId);
             return;
         }
+        // The unfiltered catalog, for the settings window's model panel. Sent to the ASKING socket only:
+        // it is a panel's private list, and broadcasting it would overwrite every open conversation's
+        // filtered catalog with one that no workspace's rules apply to.
+        if (command.type === "catalog.fetchAll") {
+            if (sendToSocket)
+                sendToSocket({ type: "model.catalog.all", catalog: await this.catalogService.getAllCatalog() });
+            return;
+        }
         if (command.type === "agent.catalog.fetch") {
             await this.catalogService.broadcastAgents();
             return;

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

@@ -174,6 +174,31 @@ export interface PiSessionLike {
         images?: unknown[];
         streamingBehavior?: "steer" | "followUp";
     }): Promise<void>;
+    /**
+     * Queues a message to be answered AFTER the current run finishes its pending work.
+     *
+     * PI'S OWN FOLLOW-UP QUEUE, and the reason a queued message does not need a turn of its own. A
+     * `prompt()` runs `_prepareRun`, which emits `before_agent_start` - and Super Pi's memory extension
+     * answers that hook with an HTTP search whose result is patched into the system prompt. So a fresh
+     * prompt pays a round trip to the memory endpoint and a bigger prompt; a follow-up is delivered by
+     * the agent loop inside the run and pays neither.
+     *
+     * Optional because a test double has no queues; its absence means "this session cannot hold a
+     * message for later", and the caller falls back to answering it as a turn of its own.
+     */
+    followUp?(message: string, images?: unknown[]): Promise<"queued" | "handled">;
+    /**
+     * Removes every message Pi is holding in its steering and follow-up queues, and returns what was
+     * removed.
+     *
+     * PI CANNOT TAKE BACK ONE MESSAGE - `clear_queue` is the only queue command it has - so this is
+     * how a host says "none of these are wanted any more". The returned texts are the queue as it
+     * was, which is what lets a host put back the ones that should still be answered.
+     */
+    clearQueue?(): {
+        steering: string[];
+        followUp: string[];
+    };
     /** Aborts the current operation and waits for the session to become idle. */
     abort(): Promise<void>;
     /** Subscribes to session events. Returns the unsubscribe function. */
@@ -184,6 +209,15 @@ export interface PiSessionLike {
     readonly sessionFile?: string | undefined;
     /** The id of the session. */
     readonly sessionId?: string | undefined;
+    /**
+     * The system prompt Pi will send with every turn.
+     *
+     * READ FOR ITS SIZE, not for its content. The time to first token is a function of how many bytes
+     * the provider has to receive before it can answer, so this number is what turns "the model was
+     * slow" into a fact. Pi builds the prompt from the agent directory, the skills, the extensions and
+     * the context files - none of which Super Pi controls.
+     */
+    readonly systemPrompt?: string | undefined;
     /**
      * The model the session is running on.
      *

package/dist/server/runtime.d.ts

@@ -236,6 +236,32 @@ export interface AgentRuntime {
      */
     steer?(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
     canSteer?(conversationId: string): boolean;
+    /**
+     * Hands one message to the Pi that is running RIGHT NOW, to be answered after the current run
+     * finishes its pending work.
+     *
+     * PI'S OWN FOLLOW-UP QUEUE, and the difference from a steer is the difference in WHEN. A steer is
+     * injected at the next turn boundary of the running turn; a follow-up waits until the agent would
+     * otherwise stop. Both are delivered by the agent loop inside the same run, which is what makes
+     * them cheap: neither goes through `_prepareRun`, so neither re-emits `before_agent_start` and
+     * neither pays for the memory search and the system-prompt patch that hook does.
+     *
+     * A message handed over this way is still Super Pi's to cancel, because Super Pi keeps it in its
+     * own waiting list - Pi is holding a copy, not the only copy.
+     */
+    followUp?(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
+    /**
+     * Empties Pi's steering and follow-up queues, and returns what was in them.
+     *
+     * WHY A HOST NEEDS THIS. Pi cannot take back a single queued message, and it will deliver whatever
+     * is left in those queues when the run ends. So whenever Super Pi takes a message back - the user
+     * withdrew it, or the user asked for it to be answered on its own - the queues have to be emptied,
+     * or Pi answers words the user believes they took back.
+     */
+    clearQueues?(conversationId: string): Promise<{
+        steering: string[];
+        followUp: string[];
+    }>;
     /**
      * ONE-SHOT TITLE GENERATION. Spawns its own short-lived Pi child rather than borrowing a running one.
      *
@@ -966,6 +992,31 @@ export declare class PiRpcRuntime implements AgentRuntime {
      * silent success.
      */
     private sessionFor;
+    /**
+     * Hands a message to Pi's FOLLOW-UP queue, to be answered when the current run finishes its work.
+     *
+     * WHY THIS EXISTS ALONGSIDE A STEER. Both put a message into a queue Pi drains inside the running
+     * turn, and neither of them re-runs `_prepareRun` - so neither re-emits `before_agent_start`, and
+     * neither pays for the memory search and the system-prompt patch that hook does. A queued message
+     * that answered itself with a fresh `prompt()` paid for both, once per message, and the prompt it
+     * sent was larger than the one before it.
+     *
+     * The difference between the two is WHEN Pi delivers the message: a steer lands at the next turn
+     * boundary (in the middle of the answer, which is what 「插队」 means), and a follow-up lands when
+     * the agent would otherwise stop (after the answer, which is what a message typed while the agent
+     * was busy means).
+     */
+    followUp(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
+    /**
+     * Empties Pi's steering and follow-up queues and returns what was in them.
+     *
+     * The session path asks Pi directly (`session.clearQueue`). The one-shot path writes Pi's
+     * `clear_queue` command, which answers with the text it removed.
+     */
+    clearQueues(conversationId: string): Promise<{
+        steering: string[];
+        followUp: string[];
+    }>;
     steer(conversationId: string, message: string, images?: MessageImage[]): Promise<SteerDisposition>;
     /**
      * The model/thinking catalog, from Pi, cached.

package/dist/server/runtime.js

@@ -755,12 +755,29 @@ export class PiRpcRuntime {
             abortTurn();
         else
             signal.addEventListener("abort", onAbort, { once: true });
+        // HOW BIG IS THE PROMPT WE ARE ABOUT TO SEND. The time to first token is a function of
+        // this, not of anything Super Pi does, and it is the number that explains a slow first turn: the
+        // model's provider has to RECEIVE the whole thing before it can answer, so a big prompt on a slow
+        // link is seconds before the first word.
+        //
+        // It is traced rather than computed, because the system prompt is what Pi builds from the agent
+        // directory, the skills, the extensions and the context files - none of which Super Pi controls,
+        // and all of which the person who installed them controls.
+        const promptSize = () => {
+            try {
+                const system = typeof session.systemPrompt === "string" ? session.systemPrompt : "";
+                return `systemPrompt=${Buffer.byteLength(system, "utf8")}B`;
+            }
+            catch {
+                return "systemPrompt=?";
+            }
+        };
         let firstTextSeen = false;
         const finished = (async () => {
             try {
                 const promptOptions = images?.length
-                    ? { images: images, preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt) }
-                    : { preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt) };
+                    ? { images: images, preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt, promptSize()) }
+                    : { preflightResult: () => traceLatency(conversation.id, "session.prompt.accepted", latencyStartedAt, promptSize()) };
                 await session.prompt(prompt, promptOptions);
                 // `prompt()` RETURNING IS NOT THE TURN ENDING. Pi's `prompt` resolves when the message has
                 // been ACCEPTED and the run has been started; the agent is still streaming, still executing
@@ -2080,6 +2097,76 @@ export class PiRpcRuntime {
             throw new SteerUnavailableError(`会话 ${conversationId} 还没有可用的 Pi 会话`);
         return session;
     }
+    /**
+     * Hands a message to Pi's FOLLOW-UP queue, to be answered when the current run finishes its work.
+     *
+     * WHY THIS EXISTS ALONGSIDE A STEER. Both put a message into a queue Pi drains inside the running
+     * turn, and neither of them re-runs `_prepareRun` - so neither re-emits `before_agent_start`, and
+     * neither pays for the memory search and the system-prompt patch that hook does. A queued message
+     * that answered itself with a fresh `prompt()` paid for both, once per message, and the prompt it
+     * sent was larger than the one before it.
+     *
+     * The difference between the two is WHEN Pi delivers the message: a steer lands at the next turn
+     * boundary (in the middle of the answer, which is what 「插队」 means), and a follow-up lands when
+     * the agent would otherwise stop (after the answer, which is what a message typed while the agent
+     * was busy means).
+     */
+    async followUp(conversationId, message, images) {
+        // THE SESSION PATH. `session.followUp` is Pi's own follow-up queue, so the message joins the run
+        // that is already going and is delivered by the agent loop when that run has nothing left to do.
+        if (this.activeTurns.has(conversationId)) {
+            const session = await this.sessionFor(conversationId);
+            const imagePayloads = this.options.uploadsDir && images?.length
+                ? await loadConversationImages(this.options.uploadsDir, conversationId, images)
+                : undefined;
+            if (!session.followUp)
+                throw new SteerUnavailableError(`会话 ${conversationId} 的 Pi 不支持排队消息`);
+            const disposition = await session.followUp(message, imagePayloads);
+            return disposition === "handled" ? "handled" : "queued";
+        }
+        // NO TURN TO FOLLOW. A follow-up is only meaningful while something is running - with nothing
+        // running, Pi would hold the message until the NEXT run, which is the same answer arriving much
+        // later than a prompt would have given it.
+        //
+        // THE ONE-SHOT PATH IS THIS CASE TOO, and it is not an accident: that path runs each turn in a
+        // short-lived child that is killed when the turn ends, so a follow-up queue would die with it. The
+        // message falls back to being answered by a turn of its own, which is the only thing that path can
+        // do anyway.
+        throw new SteerUnavailableError(`会话 ${conversationId} 当前没有可以接手的 Pi 会话，无法排队`);
+    }
+    /**
+     * Empties Pi's steering and follow-up queues and returns what was in them.
+     *
+     * The session path asks Pi directly (`session.clearQueue`). The one-shot path writes Pi's
+     * `clear_queue` command, which answers with the text it removed.
+     */
+    async clearQueues(conversationId) {
+        const empty = { steering: [], followUp: [] };
+        if (this.activeTurns.has(conversationId)) {
+            const session = this.sessionPool.get(conversationId);
+            if (!session?.clearQueue)
+                return empty;
+            try {
+                const cleared = session.clearQueue();
+                return { steering: [...(cleared?.steering ?? [])], followUp: [...(cleared?.followUp ?? [])] };
+            }
+            catch (error) {
+                console.warn(`PiRpcRuntime: clearing the queues of ${conversationId} threw: ${error instanceof Error ? error.message : "unknown error"}`);
+                return empty;
+            }
+        }
+        const run = this.runs.get(conversationId);
+        if (!run || !this.canSteer(conversationId))
+            return empty;
+        // THE ONE-SHOT PATH NEEDS NO CLEAR, and the reason is structural rather than convenient: that path
+        // runs each turn in a short-lived child that is KILLED when the turn ends (`answerOneShot`'s
+        // finally), and the child's queues die with it. A message Pi was holding in that child is gone the
+        // moment the turn is over, so there is nothing to clear and nothing to wait for. Clearing it
+        // anyway would cost a round trip to a child that is about to be killed, on the path between a turn
+        // ending and the next one starting.
+        void run;
+        return empty;
+    }
     async steer(conversationId, message, images) {
         // THE SESSION PATH. A steer on a persistent session is a `prompt` with `streamingBehavior:
         // "steer"` - the same queueing semantics Pi's RPC `steer` command has, expressed the way the SDK