@evandu/super-pi 0.1.89 → 0.1.91

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-Bpy8UeU1.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-CC-Q5gNQ.css">
+    <script type="module" crossorigin src="/assets/index-DYjBTgl4.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BcHIMxNF.css">
   </head>
   <body>
     <div id="root"></div>

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

@@ -37,9 +37,35 @@ export class ConversationService {
         const workspace = this.store.snapshot().workspaces.find(item => item.id === workspaceId);
         if (!workspace)
             throw new Error("Workspace not found");
-        const defaults = workspace.defaultAgentId
-            ? await this.resolveAgentConfiguration({ id: workspaceId, model: workspace.defaultModel, thinkingLevel: workspace.defaultThinkingLevel }, workspace.defaultAgentId, workspaceId)
-            : undefined;
+        // Workspace defaults are copied at birth, but Pi's model list can change after the
+        // setting was saved (for example when a model is removed from Pi's config). Do not
+        // 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;
+        let thinkingLevel = workspace.defaultThinkingLevel;
+        const catalog = model || thinkingLevel ? await this.runtime.catalog() : undefined;
+        if (catalog?.source === "pi" && model) {
+            const option = catalog.models.find(item => item.provider === model?.provider && item.modelId === model?.modelId);
+            if (!option) {
+                model = undefined;
+                thinkingLevel = undefined;
+            }
+            else {
+                model = { provider: option.provider, modelId: option.modelId, label: option.label };
+                if (thinkingLevel) {
+                    const scoped = await this.runtime.catalog(model);
+                    if (scoped.source === "pi" && !scoped.levels.includes(thinkingLevel))
+                        thinkingLevel = undefined;
+                }
+            }
+        }
+        const resolved = workspace.defaultAgentId
+            ? await this.resolveAgentConfiguration({ id: workspaceId, model, thinkingLevel }, workspace.defaultAgentId, workspaceId)
+            : { model, thinkingLevel };
+        // `null` is intentional here: Store uses it to remove a workspace value that it
+        // would otherwise have copied before applying the resolved configuration.
+        const defaults = { ...resolved, model: resolved.model ?? null, thinkingLevel: resolved.thinkingLevel ?? null };
         const created = await this.store.createConversation(workspaceId, defaults);
         this.broadcaster.broadcastState();
         return created.id;

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

@@ -99,6 +99,12 @@ export declare class RunService {
     /**
      * Called by the exec completion handler in index.ts when a background exec session ends.
      * Injects the result into the conversation and cleans up the background task record.
+     *
+     * The result is now a REAL queue item, not a one-way notice the model never gets to read: it lands
+     * with `delivery: "waiting"` (so the dock shows it), at the front of the waiting set (so any pending
+     * user sends wait behind it), and the conversation auto-starts a turn for the agent to handle it
+     * when nothing else is busy. The render stays as a 后台回传 block throughout - in dock and in
+     * transcript - so a `role: "user"` is never impersonated.
      */
     enqueueExecResult(sessionId: string, exitCode: number, stdout: string, stderr: string): void;
     /** Per-conversation command lane.  All queue mutations and run claims use the same lane, so
@@ -233,6 +239,27 @@ export declare class RunService {
     steer(conversationId: string, messageId: string): Promise<void>;
     /** Starts a chosen waiting message as the next turn, only when the conversation is idle. */
     sendQueued(conversationId: string, messageId: string): Promise<void>;
+    /**
+     * Stops the current turn and immediately gives one waiting message its own fresh turn.
+     *
+     * `steer` cannot provide this meaning: Pi only reads its steering queue after the current tool batch
+     * finishes. Stopping first is what makes a long-running tool give way now. `sendQueued` already owns
+     * the hand-off window after a stop, so it waits until the old run has released its slot before opening
+     * the selected message. That preserves the one-Pi-per-conversation invariant.
+     */
+    interruptQueued(conversationId: string, messageId: string): Promise<void>;
+    /**
+     * The lower-level "wait for run slot, open the turn on a specific waiting message, run it" sequence.
+     *
+     * Called from two places: the user-facing `sendQueued` (which adds a stop-clearing grace window
+     * before this) and the auto-trigger paths in `enqueueExecResult` and `dispatchTask`'s background
+     * branch (which only call it when `!this.activeRuns.has(conversationId)`). The two callers differ
+     * only in who arrived first; the open-turn-and-run contract is the same.
+     *
+     * `composePrompt` is what makes the `role: "tool"` path real - the `<task>` envelope stays in the
+     * transcript, but the prose form of the same fact is what reaches Pi.
+     */
+    private processWaitingMessage;
     private steerUnsafe;
     /**
      * Withdraws a waiting message.

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

@@ -98,6 +98,35 @@ async function expandAtReferences(store, workspace, content) {
     }
     return blocks.length ? `${content}\n${blocks.join("\n")}` : content;
 }
+/**
+ * The text the model is handed when a waiting message becomes its turn.
+ *
+ * `role: "user"` is the user's own words - pass through verbatim. `role: "tool"` is a 后台回传 block
+ * whose `message.content` is the `<task>` envelope the transcript and dock render from; handing the raw
+ * XML to Pi asks it to parse the format itself, which is the "未定义行为" path that 0.1.66 worked around
+ * by simply not triggering a turn. We DO trigger a turn now (queue semantics), so we synthesise prose
+ * the model can read like any other user message.
+ *
+ * The envelope and the prose are NOT redundant: the envelope is what the reader sees in the transcript
+ * column, what they cancel or reorder; the prose is what leaves the server for Pi.
+ */
+function composePrompt(message) {
+    if (message.role !== "tool")
+        return message.content;
+    const content = message.content;
+    const summaryMatch = /<summary>([\s\S]*?)<\/summary>/.exec(content);
+    const summary = summaryMatch ? summaryMatch[1].trim() : "后台任务";
+    const stateMatch = /<task id="[^"]+" state="([^"]+)"/.exec(content);
+    const state = stateMatch ? stateMatch[1] : "completed";
+    const bodyMatch = /<task_(?:result|error)>\n?([\s\S]*?)\n?<\/(?:task_result|task_error)>/.exec(content);
+    const body = bodyMatch ? bodyMatch[1] : content;
+    const stateLabel = state === "completed" ? "已完成" : state === "error" ? "失败" : state;
+    // The marker `@bgdelivery:` is at the end so the visible prose is what the model sees (it can ignore
+    // a trailing `@`-token, which is what its other tools do too). The fake-pi fixture recognises the
+    // marker and settles immediately so test paths through this turn do not hang on the BLOCKING
+    // extension-UI default. A real model treats the marker as part of the user's prose.
+    return `[后台任务「${summary}」${stateLabel}]\n\n${body}\n\n@bgdelivery:${state}`;
+}
 /**
  * Service managing execution of conversation turns, message queueing,
  * follow-ups, and sub-agent dispatching.
@@ -187,6 +216,12 @@ export class RunService {
     /**
      * Called by the exec completion handler in index.ts when a background exec session ends.
      * Injects the result into the conversation and cleans up the background task record.
+     *
+     * The result is now a REAL queue item, not a one-way notice the model never gets to read: it lands
+     * with `delivery: "waiting"` (so the dock shows it), at the front of the waiting set (so any pending
+     * user sends wait behind it), and the conversation auto-starts a turn for the agent to handle it
+     * when nothing else is busy. The render stays as a 后台回传 block throughout - in dock and in
+     * transcript - so a `role: "user"` is never impersonated.
      */
     enqueueExecResult(sessionId, exitCode, stdout, stderr) {
         const tasks = this.store.snapshot().backgroundTasks;
@@ -195,10 +230,6 @@ export class RunService {
             return;
         const tag = exitCode === 0 ? "task_result" : "task_error";
         const body = exitCode === 0 ? stdout : (stderr || `Command exited with code ${exitCode}`);
-        // The result becomes a `role: "tool"` message in the conversation, not a user prompt for a fresh
-        // turn. The transcript now has a 「后台回传」 column the client renders, and the model sees the
-        // result only when something else starts a turn that includes it. Asking the model to consume a
-        // `<task>` envelope as user prose is the "undefined behaviour" path the user reported.
         const message = `<task id="${sessionId}" state="${exitCode === 0 ? "completed" : "error"}" kind="exec">\n<summary>${task.title}</summary>\n<${tag}>\n${body}</${tag}>\n</task>`;
         void this.trackDetached((async () => {
             try {
@@ -211,8 +242,31 @@ export class RunService {
                     this.broadcaster.broadcast({ type: "message.tools", conversationId: task.conversationId, messageId: task.originMessageId, toolCalls });
                 }
                 this.broadcaster.broadcast({ type: "exec.exit", sessionId, exitCode, stdout, stderr });
-                await this.store.addToolMessage(task.conversationId, message);
+                // QUEUE ITEM, NOT A NOTICE. `delivery: "waiting"` is what makes the row show in the dock; without
+                // it the message is a transcript entry only and `takeNextWaitingMessage` (which `runConversationTurns`
+                // calls after every turn) never picks it up.
+                const queued = await this.store.addToolMessage(task.conversationId, message, { delivery: "waiting" });
                 this.broadcaster.broadcastState();
+                // STEER PRIORITY. If anything else is already waiting, jump this one to the front of the queue
+                // so a 后台回传 cuts ahead of user sends - matching "按插队逻辑来处理".
+                const waiting = this.store.listWaitingMessages(task.conversationId);
+                if (waiting.length > 1) {
+                    await this.store.reorderWaitingMessage(task.conversationId, queued.id, 0);
+                    this.broadcaster.broadcastState();
+                }
+                // AUTO-TRIGGER WHEN IDLE. The conversation may already be busy (running turn, taking the next
+                // waiting message in its own follow-up loop); if so, the existing loop picks this one up and
+                // this branch is a no-op. If idle, kick off a fresh turn so the model processes the result
+                // without the user having to send anything - the failure case is intentionally included: the
+                // model seeing "[后台任务 X 失败]" is part of the same "after current AI finishes, automatically
+                // processes the result" contract, and the auto-triggered turn goes through the same
+                // `composePrompt` path the success case does (so a helper failure surfaces as `state="error"`
+                // prose the agent can react to).
+                if (!this.activeRuns.has(task.conversationId)) {
+                    void this.processWaitingMessage(task.conversationId, queued.id).catch((error) => {
+                        console.warn(`Super Pi: auto-trigger for background exec result failed: ${error instanceof Error ? error.message : "unknown error"}`);
+                    });
+                }
             }
             catch (error) {
                 console.warn(`Super Pi: exec result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -488,6 +542,22 @@ export class RunService {
         let assistant = assistantMessage;
         let toolCalls = [];
         let pendingTools = Promise.resolve();
+        // A TURN MOVES FROM `waiting` TO `running` ONCE THE MODEL HAS PRODUCED ANY SIGNAL: a text delta
+        // OR a tool-call notice. The `running` state means "we have data flowing", and that is true the
+        // moment Pi yields anything back, regardless of shape. Without this, a pure tool-call turn would
+        // stay in `waiting` until the very end and the reader would see a stuck turn for the whole of a
+        // long tool execution. The flag is the only way to make the flip one-shot: calling `setStatus` on
+        // every delta would be a per-token status write.
+        let firstSignal = true;
+        const promoteToRunning = async () => {
+            if (!firstSignal)
+                return;
+            firstSignal = false;
+            if (this.store.snapshot().conversations.find((item) => item.id === conversation.id)?.status === "waiting") {
+                await this.store.setStatus(conversation.id, "running");
+                this.broadcaster.broadcastState();
+            }
+        };
         // Live events are independent from durable checkpoints. Persisting every token made the stdout
         // reader wait for one disk transaction per token; over a remote browser connection that backlog
         // looked exactly like a slow model. Keep the in-memory transcript current, publish immediately, and
@@ -516,6 +586,12 @@ export class RunService {
         };
         const enqueueTools = (what, work) => {
             pendingTools = pendingTools.then(async () => {
+                // A TOOL CALL IS A SIGNAL THE MODEL IS ALIVE. Promote `waiting` → `running` on the same
+                // path as text deltas: a tool row appearing on screen is the same "we have data" event
+                // the status needs to reflect. Doing it BEFORE the tool write keeps the order
+                // honest - a client that saw the new tool row in the same frame also saw the running
+                // status, instead of flashing back to a still-spinning waiting mark for the next paint.
+                await promoteToRunning();
                 toolCalls = await work();
                 this.broadcaster.broadcast({ type: "message.tools", conversationId: conversation.id, messageId: assistant.id, toolCalls });
             }).catch((error) => {
@@ -799,6 +875,12 @@ export class RunService {
                 // publish a new message underneath it. One `await` at the top covers both, and costs nothing:
                 // the lane is empty most of the time.
                 await pendingTools;
+                // `waiting` → `running` ON THE FIRST DELTA, before the live write. The conversation was
+                // opened in `waiting` (see `openTurn` / `openTurnOnSpecificMessage` / `openTurnOnMessage`),
+                // and the first response token is the observable fact that says the LLM is actually
+                // answering rather than hanging on auth / quota / network. `promoteToRunning` is a no-op
+                // after the first signal so this stays a one-shot status write, not a per-token one.
+                await promoteToRunning();
                 this.store.appendAssistantDeltaLive(conversation.id, assistant.id, delta);
                 spoken += delta.length;
                 // Tool events are structural transcript boundaries. Publish any boundary Pi announced before
@@ -870,7 +952,9 @@ export class RunService {
                 const followUp = await this.store.openTurnOnMessage(conversation.id, next.id, identity);
                 this.broadcaster.broadcastState();
                 const current = this.turnContext(conversation.id).conversation;
-                await this.streamTurn(current, workspace, next.content, followUp.assistant, controller, followUp.user.id, next.images, identity);
+                // `composePrompt` synthesises the prose for a 后台回传 (the `<task>` envelope is what the transcript
+                // column reads from; the prose is what leaves the server for Pi). For user messages it is a no-op.
+                await this.streamTurn(current, workspace, composePrompt(next), followUp.assistant, controller, followUp.user.id, next.images, identity);
             }
         }
         finally {
@@ -1024,22 +1108,42 @@ export class RunService {
     }
     /** Starts a chosen waiting message as the next turn, only when the conversation is idle. */
     async sendQueued(conversationId, messageId) {
-        const waitForStop = async () => {
-            // A stop broadcasts `stopped` before the previous run has finished its finally block. Allow that
-            // short cleanup window; a click on the newly visible button must not race the old run slot.
-            const deadline = Date.now() + 15_000;
-            while (this.activeRuns.has(conversationId) && this.store.snapshot().conversations.find((item) => item.id === conversationId)?.status === "stopped" && Date.now() < deadline) {
-                await new Promise((resolve) => setTimeout(resolve, 10));
-            }
-        };
-        await waitForStop();
+        // A stop broadcasts `stopped` before the previous run has finished its finally block. Allow that
+        // short cleanup window; a click on the newly visible button must not race the old run slot.
+        const deadline = Date.now() + 15_000;
+        while (this.activeRuns.has(conversationId) && this.store.snapshot().conversations.find((item) => item.id === conversationId)?.status === "stopped" && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 10));
+        }
+        await this.processWaitingMessage(conversationId, messageId);
+    }
+    /**
+     * Stops the current turn and immediately gives one waiting message its own fresh turn.
+     *
+     * `steer` cannot provide this meaning: Pi only reads its steering queue after the current tool batch
+     * finishes. Stopping first is what makes a long-running tool give way now. `sendQueued` already owns
+     * the hand-off window after a stop, so it waits until the old run has released its slot before opening
+     * the selected message. That preserves the one-Pi-per-conversation invariant.
+     */
+    async interruptQueued(conversationId, messageId) {
+        if (this.activeRuns.has(conversationId))
+            await this.stopRun(conversationId);
+        await this.sendQueued(conversationId, messageId);
+    }
+    /**
+     * The lower-level "wait for run slot, open the turn on a specific waiting message, run it" sequence.
+     *
+     * Called from two places: the user-facing `sendQueued` (which adds a stop-clearing grace window
+     * before this) and the auto-trigger paths in `enqueueExecResult` and `dispatchTask`'s background
+     * branch (which only call it when `!this.activeRuns.has(conversationId)`). The two callers differ
+     * only in who arrived first; the open-turn-and-run contract is the same.
+     *
+     * `composePrompt` is what makes the `role: "tool"` path real - the `<task>` envelope stays in the
+     * transcript, but the prose form of the same fact is what reaches Pi.
+     */
+    async processWaitingMessage(conversationId, messageId) {
         return this.serializeConversation(conversationId, async () => {
             if (this.activeRuns.has(conversationId))
                 throw new Error("当前轮仍在运行；停止或等待它结束后再发送这条消息");
-            // Claim the run slot BEFORE releasing the command lane, then start the turn from the message that
-            // is already in the transcript. It is not re-sent through `enqueueAndRun`, which would write a
-            // SECOND copy of these words: the whole point of this action is that the user is sending a message
-            // they can already see sitting in their conversation.
             const controller = new AbortController();
             this.activeRuns.set(conversationId, controller);
             try {
@@ -1048,14 +1152,14 @@ export class RunService {
                 const identity = agent ? { id: agent.id, name: agent.name } : { name: "Pi" };
                 const opened = await this.store.openTurnOnSpecificMessage(conversationId, messageId, identity);
                 this.broadcaster.broadcastState();
-                await this.runConversationTurns(conversation, workspace, opened.user.content, controller, opened.user.id, opened.user.images);
+                await this.runConversationTurns(conversation, workspace, composePrompt(opened.user), controller, opened.user.id, opened.user.images);
                 await this.store.setStatus(conversationId, controller.signal.aborted ? "stopped" : "completed");
             }
             catch (error) {
                 await this.store.setStatus(conversationId, "failed");
-                // A preflight failure must put the words BACK where the user can see them. Re-adding them would
-                // duplicate the message that is still in the transcript, so this only re-marks the one that is
-                // there - which is what makes "the send failed, your message is still waiting" a true statement.
+                // A preflight failure must put the message BACK where the reader can see it. Re-adding it would
+                // duplicate the row that is still in the transcript, so this only re-marks the one that is
+                // there - which is what makes "the send failed, this row is still in the queue" a true statement.
                 await this.store.releaseWaitingMessage(conversationId, messageId).catch(() => undefined);
                 throw error;
             }
@@ -1097,7 +1201,10 @@ export class RunService {
         const claimed = await this.store.claimWaitingMessage(conversationId, messageId);
         this.broadcaster.broadcastState();
         try {
-            await this.runtime.steer(conversationId, claimed.content, claimed.images);
+            // `composePrompt` turns a 后台回传 into the prose the model can read as a user message; for a
+            // user waiting message it is the no-op identity. `claimed.images` is always undefined for a
+            // `role: "tool"` row, and that is correct - 后台回传 carries no images today.
+            await this.runtime.steer(conversationId, composePrompt(claimed), claimed.images);
         }
         catch (error) {
             // Back to waiting in every failure case, including the "Pi is gone" one. It is still at the front of
@@ -1223,11 +1330,24 @@ export class RunService {
                     this.memory?.review(this.turnContext(conversationId).conversation, { task: body.prompt, result: run.output });
                 const result = run.status === "completed" ? run.output ?? "" : `Background task failed: ${run.error ?? run.status}`;
                 const tag = run.status === "completed" ? "task_result" : "task_error";
-                // Result is appended as a `role: "tool"` message, not a user-prompted turn. The transcript
-                // shows the result in its own column; the model only sees it on a later turn.
+                // A 后台回传 that the agent will actually get to read: same `<task>` envelope the transcript and
+                // dock render from, but with `delivery: "waiting"` so it lives in the queue, jumps to the
+                // front, and auto-triggers a turn when the conversation is idle. The render side is unchanged -
+                // still the 后台回传 column.
                 const message = `<task id="${run.id}" state="${run.status === "completed" ? "completed" : "error"}" kind="subagent">\n<summary>Background task ${run.status === "completed" ? "completed" : "failed"}: ${body.description?.trim() || subagentType}</summary>\n<${tag}>\n${result}</${tag}>\n</task>`;
                 try {
-                    await this.store.addToolMessage(conversation.id, message);
+                    const queued = await this.store.addToolMessage(conversation.id, message, { delivery: "waiting" });
+                    this.broadcaster.broadcastState();
+                    const waiting = this.store.listWaitingMessages(conversation.id);
+                    if (waiting.length > 1) {
+                        await this.store.reorderWaitingMessage(conversation.id, queued.id, 0);
+                        this.broadcaster.broadcastState();
+                    }
+                    if (!this.activeRuns.has(conversation.id)) {
+                        void this.processWaitingMessage(conversation.id, queued.id).catch((error) => {
+                            console.warn(`Super Pi: auto-trigger for background sub-agent result failed: ${error instanceof Error ? error.message : "unknown error"}`);
+                        });
+                    }
                 }
                 catch (error) {
                     console.warn(`Super Pi: sub-agent result could not be appended as a tool message: ${error instanceof Error ? error.message : "unknown error"}`);
@@ -1237,7 +1357,16 @@ export class RunService {
             }).catch(async (error) => {
                 const message = `<task id="${backgroundId}" state="error" kind="subagent">\n<summary>Background task failed: ${body.description?.trim() || subagentType}</summary>\n<task_error>Background task failed before completion: ${error instanceof Error ? error.message : "unknown error"}</task_error>\n</task>`;
                 try {
-                    await this.store.addToolMessage(conversationId, message);
+                    const queued = await this.store.addToolMessage(conversationId, message, { delivery: "waiting" });
+                    this.broadcaster.broadcastState();
+                    const waiting = this.store.listWaitingMessages(conversationId);
+                    if (waiting.length > 1) {
+                        await this.store.reorderWaitingMessage(conversationId, queued.id, 0);
+                        this.broadcaster.broadcastState();
+                    }
+                    // No auto-trigger on this failure branch (the result envelope says `state="error"` and the
+                    // conversation is by construction not in a turn that asked for it). The row is visible in the
+                    // dock for the reader to send-now or cancel.
                 }
                 catch (innerError) {
                     console.warn(`Super Pi: sub-agent failure could not be appended as a tool message: ${innerError instanceof Error ? innerError.message : "unknown error"}`);

package/dist/server/command-handler.js

@@ -169,6 +169,10 @@ export class CommandHandler {
             await this.runService.steer(command.conversationId, command.messageId);
             return;
         }
+        if (command.type === "message.interrupt") {
+            await this.runService.interruptQueued(command.conversationId, command.messageId);
+            return;
+        }
         if (command.type === "message.sendQueued") {
             await this.runService.sendQueued(command.conversationId, command.messageId);
             return;

package/dist/server/store.d.ts

@@ -1,7 +1,7 @@
 import type { AppStateRepository } from "./persistence/app-state-repository.js";
 import { defaultJsonStatePath } from "./persistence/json-state-repository.js";
 import type { WorkflowRun } from "./workflow.js";
-import type { AppState, Conversation, Message, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
+import type { AppState, Conversation, Message, MessageDelivery, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
 /** Mints the id a forked conversation will have, BEFORE its Pi transcript exists.
  *
  *  Exported because the ordering demands it and no other arrangement provides it. Pi's copied file's header
@@ -107,8 +107,8 @@ export declare class Store {
     deleteWorkspace(workspaceId: string): Promise<string[]>;
     createConversation(workspaceId: string, configuration?: {
         agentId?: string;
-        model?: ModelSelection;
-        thinkingLevel?: string;
+        model?: ModelSelection | null;
+        thinkingLevel?: string | null;
     }): Promise<Conversation>;
     /**
      * Copies a conversation into a NEW one, under an id the caller has already minted.
@@ -220,18 +220,18 @@ export declare class Store {
      */
     private claimClientMessageId;
     /**
-     * Appends one background-result message to a conversation, without starting a turn.
-     *
-     * Used by sub-agent dispatch completions and the exec service when they finish out of band - the
-     * result is the prompt for a follow-up turn in the old design, which made a "后台回传" render under
-     * the "你" bubble and asked the model to consume a tool envelope as user prose. This appends a
-     * `role: "tool"` message that the client renders with its own column and its own block UI, so the
-     * transcript shows the result AND nothing pretends the user said it.
+     * Appends one background-result message to a conversation. The render column is the same as before
+     * (a `role: "tool"` row, never impersonating a user bubble) - what this method now ALSO supports is
+     * putting the message straight into the dock by passing `delivery: "waiting"`, which is what exec and
+     * sub-agent background completions do once a 后台回传 is treated as a queue item with steer priority
+     * rather than a one-way notice the model never gets to read.
      *
-     * NO `turnContext` claim, NO `status: "running"`. The message sits in the transcript and a subsequent
-     * caller can start a turn normally if it wants the model to react to the result.
+     * NO `turnContext` claim, NO `status: "running"`. The message sits in the transcript; with a delivery
+     * state it also enters `waitingMessages` and `runConversationTurns` will pick it up next.
      */
-    addToolMessage(conversationId: string, content: string): Promise<Message>;
+    addToolMessage(conversationId: string, content: string, options?: {
+        delivery?: MessageDelivery;
+    }): Promise<Message>;
     /**
      * Records the model a conversation runs on. `updatedAt` is deliberately NOT touched, for the same
      * reason rename does not touch it: it is the sidebar's recency key, and switching model is not
@@ -421,7 +421,11 @@ export declare class Store {
      * browsers and the array is mutated in place by the very next send.
      */
     listWaitingMessages(conversationId: string): Message[];
-    /** The same list by reference, for callers that only read a field and must not pay for a clone. */
+    /** The same list by reference, for callers that only read a field and must not pay for a clone.
+     *
+     * Includes `role: "tool"` messages now that a 后台回传 is a real queue item: same dock, same ordering,
+     * same delivery state machine, same steer/claim semantics - the only thing different is the render
+     * (kept as a 后台回传 block) and what the agent is told when its turn comes (see `composePrompt`). */
     private waitingMessages;
     private requireWaitingMessage;
     private persistMessages;
@@ -491,12 +495,9 @@ export declare class Store {
      */
     cancelWaitingMessage(conversationId: string, messageId: string): Promise<Message | undefined>;
     /**
-     * Rewrites the words of one waiting message.
-     *
-     * Only legal while nothing has read it. `waiting` means the text is still only in this transcript, so
-     * changing it is changing the whole truth of the message - there is no second copy anywhere that could
-     * fall out of step. `sending` means Pi already holds it, and a message the model is about to answer is
-     * not one the user gets to rewrite after the fact.
+     * Rewrites the words of one waiting message. User sends only - a 后台回传 carries a `<task>` envelope
+     * the model parses for state, summary and body, and editing it would change a fact the agent has
+     * already started reasoning from. The client dock shows no 「改字」 button for `role: "tool"` rows.
      */
     editWaitingMessage(conversationId: string, messageId: string, content: string): Promise<Message>;
     /**
@@ -548,9 +549,10 @@ export declare class Store {
      * question that is still waiting - a transcript lying about its own order. Splicing at
      * `indexOf(user) + 1` keeps every waiting message below the reply that belongs to the one above it.
      *
-     * The side effects - title, `updatedAt`, `status: "running"`, clearing a stale failure - all describe a
+     * The side effects - title, `updatedAt`, `status: "waiting"`, clearing a stale failure - all describe a
      * TURN rather than a message, which is why `addUserMessage` skips them for a message that is only
-     * waiting. They belong here, at the moment the turn genuinely begins.
+     * waiting. They belong here, at the moment the turn genuinely begins - the model still has not
+     * returned a token, and that is the shape the row carries until `streamTurn` sees the first delta.
      */
     openTurnOnMessage(conversationId: string, messageId: string, agentIdentity?: Message["agentIdentity"]): Promise<{
         user: Message;