@evandu/super-pi 0.1.139 → 0.1.141

package/dist/server/store.d.ts

@@ -270,7 +270,17 @@ export declare class Store {
         model?: ModelSelection | null;
         thinkingLevel?: string | null;
         modelNotice?: string;
+        parentConversationId?: string;
+        origin?: "user" | "orchestrator";
     }): Promise<Conversation>;
+    /**
+     * Records (or clears) one conversation as collapsed in the sidebar's session tree. The list is a
+     * SET in array clothing - order means nothing, duplicates must not accumulate - and it follows the
+     * assign -> persist -> rollback pattern `setTerminalShell` established: the in-memory value is the
+     * previous value again the moment persistence fails, so a rejected write can never leave the
+     * screen and the disk disagreeing.
+     */
+    setConversationCollapsed(conversationId: string, collapsed: boolean): Promise<void>;
     /**
      * Copies a conversation into a NEW one, under an id the caller has already minted.
      *

package/dist/server/store.js

@@ -1086,11 +1086,49 @@ export class Store {
             }
             if (configuration.agentId)
                 conversation.agentId = configuration.agentId;
+            // THE SESSION TREE'S EDGE, WRITTEN AT BIRTH. Both fields describe how this conversation CAME TO
+            // BE, exactly like modelNotice above, so they are set once here and never rewritten: the tree
+            // the sidebar draws after a restart is the tree that was true when each session was opened.
+            // Written only when present, so a conversation created without them (the user's own "+") reads
+            // as a top-level one on every code path, including every state.json from before this field.
+            if (configuration.parentConversationId)
+                conversation.parentConversationId = configuration.parentConversationId;
+            if (configuration.origin)
+                conversation.origin = configuration.origin;
         }
         this.state.conversations.unshift(conversation);
         await this.persist();
         return structuredClone(conversation);
     }
+    /**
+     * Records (or clears) one conversation as collapsed in the sidebar's session tree. The list is a
+     * SET in array clothing - order means nothing, duplicates must not accumulate - and it follows the
+     * assign -> persist -> rollback pattern `setTerminalShell` established: the in-memory value is the
+     * previous value again the moment persistence fails, so a rejected write can never leave the
+     * screen and the disk disagreeing.
+     */
+    async setConversationCollapsed(conversationId, collapsed) {
+        const previous = this.state.collapsedConversationIds;
+        const next = new Set(previous ?? []);
+        if (collapsed)
+            next.add(conversationId);
+        else
+            next.delete(conversationId);
+        if (next.size === 0)
+            delete this.state.collapsedConversationIds;
+        else
+            this.state.collapsedConversationIds = [...next];
+        try {
+            await this.persist();
+        }
+        catch (error) {
+            if (previous === undefined)
+                delete this.state.collapsedConversationIds;
+            else
+                this.state.collapsedConversationIds = previous;
+            throw error;
+        }
+    }
     /**
      * Copies a conversation into a NEW one, under an id the caller has already minted.
      *

package/dist/server/subagent-runs.d.ts

@@ -15,7 +15,8 @@ import type { ModelSelection, ServerEvent, SubagentRun } from "./types.js";
  *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
  * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
  *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
- *    extension (design §2, reason 1).
+ *    extension (design §2, reason 1). The snapshot's `output` is the TAIL of the accumulated text
+ *    ({@link LIVE_OUTPUT_TAIL_CAP}); the whole text is in the store and in the settle event.
  *
  * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
  */
@@ -29,6 +30,21 @@ import type { ModelSelection, ServerEvent, SubagentRun } from "./types.js";
  * what was said. The parent model is handed the capped copy, because that is the window it actually has.
  */
 export declare const PER_TASK_OUTPUT_CAP: number;
+/**
+ * How much of the ACCUMULATED output a delta-phase `subagent.event` may carry.
+ *
+ * A delta event is a SNAPSHOT the card replaces itself with, and it fires PER DELTA. Carrying the whole
+ * accumulated text makes the Nth event N characters long - the traffic is quadratic in the output length
+ * (the flood behind "连接中 / 断连 / 连接中", see docs/SUBAGENT-WS-FLOOD-FIX-2026-10-29.md). So a live
+ * event carries only the TAIL of what the child has said; the run's full output still reaches everyone -
+ * the STORE record is written unabridged on every delta (a mid-run reload rebuilds from `state`, not from
+ * events), and the settle event carries the final text in full. A watching human needs the last few
+ * hundred characters, not the first ones, so the tail is the useful end.
+ *
+ * THIS CHANGES WHAT AN OLD CLIENT SEES: a card whose child has said more than this shows the latest 8 KB
+ * (sliding) instead of the whole text, then the full text at settle. The field shape is unchanged.
+ */
+export declare const LIVE_OUTPUT_TAIL_CAP: number;
 /** What a caller supplies to dispatch one run. The workspace directory is required, like `AnswerInput.cwd`. */
 export type SubagentDispatch = {
     id?: string;
@@ -75,6 +91,20 @@ export type SubagentRunHooks = {
      * attached without changing the recorder.
      */
     broadcast: (event: ServerEvent) => void;
+    /**
+     * Fires ONCE per run, AFTER the terminal `subagent.event` has been broadcast from `settle()`. This -
+     * not the delta phase - is when a caller should broadcast a full `state` snapshot: the run's final
+     * record is on disk by then, so a browser that reloads after it sees the finished card. Broadcasting
+     * state on every DELTA is what flooded the socket (each delta demanded a full state frame; a burst of
+     * deltas demanded hundreds).
+     */
+    onSettled?: () => void;
+    /**
+     * Cap on `run.output` in delta-phase events, in characters; defaults to {@link LIVE_OUTPUT_TAIL_CAP}.
+     * A settle event always carries the full output regardless. `Number.POSITIVE_INFINITY` disables the
+     * cap - the diagnostic "legacy flood" mode uses that to reproduce the pre-fix wire shape.
+     */
+    liveTailCap?: number;
     /**
      * Builds the host that answers a CHILD's questions, keyed by the run as well as the conversation
      * (design §4). Optional because a headless caller has nobody to ask; a child that asks in that case is

package/dist/server/subagent-runs.js

@@ -12,7 +12,8 @@ import { SubagentCancelled, newSubagentRunId } from "./subagents.js";
  *    mid-run leaves an orphan - and `Store.open` fails that orphan with a reason on the next start.
  * 2. **A snapshot on every delta.** `subagent.event` carries the run as it stands, not just at the end,
  *    because streaming a sub-agent is the entire reason Super Pi spawns its own instead of shipping Pi's
- *    extension (design §2, reason 1).
+ *    extension (design §2, reason 1). The snapshot's `output` is the TAIL of the accumulated text
+ *    ({@link LIVE_OUTPUT_TAIL_CAP}); the whole text is in the store and in the settle event.
  *
  * What deliberately does NOT go into either is the child's transcript. See `SubagentRun`.
  */
@@ -26,6 +27,21 @@ import { SubagentCancelled, newSubagentRunId } from "./subagents.js";
  * what was said. The parent model is handed the capped copy, because that is the window it actually has.
  */
 export const PER_TASK_OUTPUT_CAP = 50 * 1024;
+/**
+ * How much of the ACCUMULATED output a delta-phase `subagent.event` may carry.
+ *
+ * A delta event is a SNAPSHOT the card replaces itself with, and it fires PER DELTA. Carrying the whole
+ * accumulated text makes the Nth event N characters long - the traffic is quadratic in the output length
+ * (the flood behind "连接中 / 断连 / 连接中", see docs/SUBAGENT-WS-FLOOD-FIX-2026-10-29.md). So a live
+ * event carries only the TAIL of what the child has said; the run's full output still reaches everyone -
+ * the STORE record is written unabridged on every delta (a mid-run reload rebuilds from `state`, not from
+ * events), and the settle event carries the final text in full. A watching human needs the last few
+ * hundred characters, not the first ones, so the tail is the useful end.
+ *
+ * THIS CHANGES WHAT AN OLD CLIENT SEES: a card whose child has said more than this shows the latest 8 KB
+ * (sliding) instead of the whole text, then the full text at settle. The field shape is unchanged.
+ */
+export const LIVE_OUTPUT_TAIL_CAP = 8 * 1024;
 export class SubagentRunRecorder {
     supervisor;
     hooks;
@@ -174,24 +190,22 @@ export class SubagentRunRecorder {
          * and is what a card should say about a run whose child never existed. See `SubagentFailure`.
          */
         let stage = "dispatch";
+        // Live events carry only the tail of the accumulated output (see LIVE_OUTPUT_TAIL_CAP) so a
+        // per-delta snapshot stays small no matter how much the child has said.
+        const liveTailCap = this.hooks.liveTailCap ?? LIVE_OUTPUT_TAIL_CAP;
         const publish = () => {
-            record.output = streamed;
+            record.output = streamed.length > liveTailCap ? streamed.slice(streamed.length - liveTailCap) : streamed;
             record.toolCalls = toolCalls;
             record.activity = activity;
             // WRITE BEFORE ANNOUNCE, and this is the whole defect. The order of the two statements below is
             // load-bearing; swapping them back reintroduces a card that loses text it already streamed.
             //
-            // The hook a caller installs announces the event and THEN broadcasts `state` (`index.ts`), so both
-            // frames leave here in that order whatever this function does internally. Announcing first made the
-            // `state` frame a snapshot of a store this delta had not reached yet - the write below had not even
-            // been CALLED. The browser REPLACES on `state` (`App.tsx`), so a card that had just been handed the
-            // right text had it taken back one frame later.
-            //
-            // Why some cards lived anyway and this one did not: a child that keeps talking recovers by accident,
-            // because its NEXT delta publishes a `state` once the write queue has drained. A child that says one
-            // thing and goes quiet never publishes again, so nothing restores it - and it is not only that child's
-            // card. Every later `state` broadcast from any command, including ones about an unrelated
-            // conversation, reads that same stale record.
+            // Announcing before the store write means any `state` snapshot taken after the announce - from
+            // whatever command, this run's or an unrelated conversation's - still reads the PRE-delta record.
+            // The browser REPLACES on `state` (`App.tsx`), so a card that had just been handed the right text
+            // would have it taken back one frame later. This run's own delta phase no longer triggers a
+            // `state` broadcast at all (the caller hooks that via `onSettled` at settle time only), but OTHER
+            // commands broadcast `state` while this child streams, and every one of them reads this record.
             //
             // The write is still not awaited, and still must not be: `onTextDelta` is synchronous, and a drain loop
             // that flushed to disk per token would throttle the child. Reordering buys the correctness anyway,
@@ -222,6 +236,9 @@ export class SubagentRunRecorder {
             // the correct trade: never announce state that a reload would contradict.
             const settled = await this.hooks.store.setSubagentRun(id, changes);
             this.hooks.broadcast({ type: "subagent.event", run: structuredClone(record) });
+            // The ONE moment a full `state` broadcast is needed: the final record is on disk NOW, so a browser
+            // that reloads after this point rebuilds the finished card from `state`. See the `onSettled` doc.
+            this.hooks.onSettled?.();
             return settled;
         };
         /**

package/dist/server/task-tool.d.ts

@@ -244,3 +244,21 @@ export declare function normalizeTodos(raw: unknown): {
  * header are computed from the same stored list and cannot disagree.
  */
 export declare function todoSummary(todos: readonly TodoItem[]): string;
+/**
+ * The orchestrator extension's half of the environment contract.
+ * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
+ */
+export declare const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+/** Tool names registered with Pi. */
+export declare const SESSION_SPAWN_TOOL_NAME = "session_spawn";
+export declare const SESSION_STATUS_TOOL_NAME = "session_status";
+export declare const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
+export declare const SESSION_STOP_TOOL_NAME = "session_stop";
+/** Model-facing description for session_spawn. */
+export declare const SESSION_SPAWN_DESCRIPTION = "Create a new sibling conversation in the current workspace and immediately dispatch its initial task.\n\nDIFFERENCE FROM THE 'task' TOOL:\n- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.\n- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.\n\nWHEN TO USE THIS:\n- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.\n- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.\n- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.\n\nWHEN NOT TO USE THIS:\n- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.\n- For running shell commands or build watchers: use 'run_async'.\n- For a linear multi-step subagent pipeline: use 'workflow'.\n\nUsage notes:\n1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.\n2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.\n3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.";
+/** Model-facing description for session_status. */
+export declare const SESSION_STATUS_DESCRIPTION = "Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.\n\nWHEN TO USE THIS:\n- To check whether a spawned sibling conversation is still running, has finished (idle), is stopped, or encountered an error.\n- To read the latest assistant progress snippet without bloating your context with the session's entire raw message transcript.\n- To list all sibling conversations under your coordination when conversationId is omitted.\n\nUsage notes:\n1. When 'conversationId' is provided: returns a compact summary for that specific session, including its run status ('idle', 'running', 'waiting', 'stopped', 'failed'), messageCount, turnCount, lastAssistantSnippet, lastUserSnippet, activeTool, and error (if any).\n2. When 'conversationId' is omitted: returns a summary list of ALL sibling conversations spawned by this orchestrator session.\n3. This tool never returns full transcripts; it returns concise summaries and snippets to keep your context window lean.";
+/** Model-facing description for session_dispatch. */
+export declare const SESSION_DISPATCH_DESCRIPTION = "Send a message, follow-up instructions, or steering guidance to an existing sibling conversation.\n\nWHEN TO USE THIS:\n- To follow up with a sibling session after reading its progress with session_status.\n- To give feedback, provide additional requirements, or answer a question from a sibling session.\n- To kick off a new turn on an idle or stopped sibling session.\n\nUsage notes:\n1. 'conversationId' is required and must identify an existing sibling conversation.\n2. 'content' is the text instruction sent to that session, just as if typed by a user in that session's chat.\n3. Dispatch is ASYNCHRONOUS by default: it enqueues the message into the session's queue and returns immediately.\n4. If the sibling session is currently busy running a turn, the dispatched message is placed in its waiting queue and processed when the active turn completes.";
+/** Model-facing description for session_stop. */
+export declare const SESSION_STOP_DESCRIPTION = "Stop execution in a sibling conversation.\n\nWHEN TO USE THIS:\n- When a sibling session has gone down the wrong path, is stuck in an unwanted loop, or when the overall goal has changed and remaining work should be aborted.\n- To clear pending queued messages before they start running.\n\nUsage notes:\n1. 'mode' controls what to stop:\n   - 'all' (default): stops the currently running turn and cancels all pending queued messages in the session.\n   - 'active': only interrupts the active running turn; leaves any pending queued messages untouched.\n   - 'queued': only cancels pending queued messages; lets the currently running turn complete naturally.\n2. Use 'messageId' if you want to cancel or interrupt one specific queued message instead of all queued messages.";

package/dist/server/task-tool.js

@@ -333,3 +333,88 @@ export function todoSummary(todos) {
         return `全部完成：${todos.length} 个待办任务`;
     return `${open} 个待办未完成，共 ${todos.length} 个`;
 }
+// ---------------------------------------------------------------------------------------------
+// The `session_*` orchestrator tools: manage sibling conversations in the current workspace.
+//
+// WHY THESE TOOLS EXIST. A primary agent can already delegate a single transient job to a subagent
+// via `task` (a one-shot Pi process), or pipeline 2-8 steps via `workflow`. What was missing was the
+// ability to spin up INDEPENDENT, PERSISTENT sibling conversations in Super Pi — sessions that appear
+// in the workspace sidebar, carry their own full message history, run concurrently in the background,
+// and can be conversed with over multiple turns via `session_dispatch`, monitored via `session_status`,
+// or cancelled via `session_stop`.
+//
+// WHY THEY DIFFER FROM `task`. `task` runs an ephemeral child process: it has no conversation history,
+// cannot be conversed with across turns, does not appear in the sidebar, and dies upon returning its
+// final text. Sibling conversations are first-class Super Pi conversations: they retain their own
+// transcripts, can be opened and viewed by the user in the UI, and can execute complex multi-phase
+// work in parallel with the orchestrator.
+// ---------------------------------------------------------------------------------------------
+/**
+ * The orchestrator extension's half of the environment contract.
+ * `agents/super-pi-task/core.ts` is the other end; `scripts/task-tool.test.mjs` asserts the two copies agree.
+ */
+export const ORCHESTRATOR_ENDPOINT_ENV = "SUPER_PI_ORCHESTRATOR_ENDPOINT";
+/** Tool names registered with Pi. */
+export const SESSION_SPAWN_TOOL_NAME = "session_spawn";
+export const SESSION_STATUS_TOOL_NAME = "session_status";
+export const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
+export const SESSION_STOP_TOOL_NAME = "session_stop";
+/** Model-facing description for session_spawn. */
+export const SESSION_SPAWN_DESCRIPTION = `Create a new sibling conversation in the current workspace and immediately dispatch its initial task.
+
+DIFFERENCE FROM THE 'task' TOOL:
+- The 'task' tool delegates to a transient, one-shot subagent process (scout, critic, patcher) that runs once, returns its final text, and terminates. It has no conversation history and does not appear in the workspace sidebar.
+- 'session_spawn' creates a real, persistent sibling CONVERSATION in Super Pi. It appears in the sidebar, retains multi-turn message history, can receive follow-up messages via session_dispatch, can be inspected via session_status, and can be stopped via session_stop. The user can also switch to it in the Web UI.
+
+WHEN TO USE THIS:
+- Long-running, multi-phase tracks of work that require ongoing context, multiple turns of dialogue, or independent user visibility.
+- Parallel work streams (e.g., Track A: backend refactor, Track B: frontend component update) where both need full conversational capabilities.
+- When the user asks you to act as an orchestrator/manager who delegates to multiple sessions.
+
+WHEN NOT TO USE THIS:
+- For one-off, focused delegation with a single answer: use 'task' (with scout/critic/patcher). It is faster, cheaper, and returns directly to your transcript.
+- For running shell commands or build watchers: use 'run_async'.
+- For a linear multi-step subagent pipeline: use 'workflow'.
+
+Usage notes:
+1. Spawning is ASYNCHRONOUS by default: it creates the conversation, enqueues the initial task, and returns the new conversationId immediately. The sibling session runs in the background.
+2. The initial task should provide clear context and goals since the new session starts with a fresh conversation history.
+3. Use session_status with the returned conversationId to check progress, or session_dispatch to send further messages.`;
+/** Model-facing description for session_status. */
+export const SESSION_STATUS_DESCRIPTION = `Inspect the progress, run state, and latest activity of sibling conversations created by the orchestrator.
+
+WHEN TO USE THIS:
+- To check whether a spawned sibling conversation is still running, has finished (idle), is stopped, or encountered an error.
+- To read the latest assistant progress snippet without bloating your context with the session's entire raw message transcript.
+- To list all sibling conversations under your coordination when conversationId is omitted.
+
+Usage notes:
+1. When 'conversationId' is provided: returns a compact summary for that specific session, including its run status ('idle', 'running', 'waiting', 'stopped', 'failed'), messageCount, turnCount, lastAssistantSnippet, lastUserSnippet, activeTool, and error (if any).
+2. When 'conversationId' is omitted: returns a summary list of ALL sibling conversations spawned by this orchestrator session.
+3. This tool never returns full transcripts; it returns concise summaries and snippets to keep your context window lean.`;
+/** Model-facing description for session_dispatch. */
+export const SESSION_DISPATCH_DESCRIPTION = `Send a message, follow-up instructions, or steering guidance to an existing sibling conversation.
+
+WHEN TO USE THIS:
+- To follow up with a sibling session after reading its progress with session_status.
+- To give feedback, provide additional requirements, or answer a question from a sibling session.
+- To kick off a new turn on an idle or stopped sibling session.
+
+Usage notes:
+1. 'conversationId' is required and must identify an existing sibling conversation.
+2. 'content' is the text instruction sent to that session, just as if typed by a user in that session's chat.
+3. Dispatch is ASYNCHRONOUS by default: it enqueues the message into the session's queue and returns immediately.
+4. If the sibling session is currently busy running a turn, the dispatched message is placed in its waiting queue and processed when the active turn completes.`;
+/** Model-facing description for session_stop. */
+export const SESSION_STOP_DESCRIPTION = `Stop execution in a sibling conversation.
+
+WHEN TO USE THIS:
+- When a sibling session has gone down the wrong path, is stuck in an unwanted loop, or when the overall goal has changed and remaining work should be aborted.
+- To clear pending queued messages before they start running.
+
+Usage notes:
+1. 'mode' controls what to stop:
+   - 'all' (default): stops the currently running turn and cancels all pending queued messages in the session.
+   - 'active': only interrupts the active running turn; leaves any pending queued messages untouched.
+   - 'queued': only cancels pending queued messages; lets the currently running turn complete naturally.
+2. Use 'messageId' if you want to cancel or interrupt one specific queued message instead of all queued messages.`;

package/dist/server/types.d.ts

@@ -516,6 +516,21 @@ export type Conversation = {
      * deleted agent degrades to "no role" instead of leaving a stale snapshot in state.json.
      */
     agentId?: string;
+    /**
+     * The conversation that opened this one, when an orchestrator agent created it. Absent for a
+     * conversation the user started. This is the session tree's edge, and it PERSISTS: the sidebar
+     * draws the hierarchy from it after a restart, which a server-side in-memory ledger cannot do.
+     * Absence also reads correctly on every state.json written before this field existed - no parent
+     * recorded simply means "top level", which is what those conversations genuinely are.
+     */
+    parentConversationId?: string;
+    /**
+     * Who opened this conversation. "user" for one the user started, "orchestrator" for one an agent
+     * created. Kept beside the parent id because a conversation can be an orchestrator's without
+     * having a parent (the top-level orchestrator), and because the context menu's "stop the session
+     * AND its queue" needs to know a queue exists without polling the orchestrator's ledger.
+     */
+    origin?: "user" | "orchestrator";
 };
 /**
  * One parsed agent definition, as read from an `agents/*.md` file. `prompt` is the file body and is the
@@ -863,7 +878,13 @@ export type AppState = {
     todosByConversation?: Record<string, TodoItem[]>;
     workflows?: WorkflowRun[];
     scheduledTasks?: ScheduledTask[];
-    customAgentDirs?: string[];
+    customAgentDirs?: string[]; /**
+     * Which conversations the reader has collapsed in the sidebar's session tree, by conversation id.
+     * Server-side so the tree looks the same after a restart and on another machine - the sidebar is a
+     * view of the PRODUCT's state, not of one browser's session. Absent (older state.json) means
+     * "nothing collapsed", which is the correct reading of a preference that did not exist yet.
+     */
+    collapsedConversationIds?: string[];
 };
 export type TodoItem = {
     id?: string;
@@ -871,6 +892,29 @@ export type TodoItem = {
     status: "pending" | "in_progress" | "completed";
     priority?: "high" | "medium" | "low";
 };
+/** Summary of an orchestrated sibling session, returned by orchestrator queries. */
+export type OrchestratorSessionSummary = {
+    conversationId: string;
+    workspaceId: string;
+    title: string;
+    status: RunStatus;
+    origin: "user" | "orchestrator";
+    parentConversationId?: string;
+    task?: string;
+    messageCount: number;
+    turnCount: number;
+    lastAssistantSnippet?: string;
+    lastUserSnippet?: string;
+    hasPendingQuestion: boolean;
+    activeTool?: {
+        label: string;
+        detail?: string;
+    };
+    error?: string;
+    updatedAt: string;
+    createdAt?: number;
+    lastProgress?: string;
+};
 /**
  * What Pi reports about ITS OWN queue, forwarded to the browser as it arrives.
  *
@@ -1135,6 +1179,17 @@ export type ClientCommandBody =
 } | {
     type: "conversation.unarchive";
     conversationId: string;
+}
+/**
+ * Collapses or expands one conversation's whole subtree in the sidebar's session tree. The state
+ * lives SERVER-SIDE (`AppState.collapsedConversationIds`), not in the browser: the tree must look
+ * the same after a restart and on another machine, and a bare WS client must not be able to leave
+ * the server's truth and the screen's truth disagreeing about a preference the product owns.
+ */
+ | {
+    type: "conversation.collapse";
+    conversationId: string;
+    collapsed: boolean;
 } | {
     type: "conversation.rename";
     conversationId: string;

package/dist/server/ws-server.d.ts

@@ -10,6 +10,21 @@ import type { CatalogService } from "./application/catalog-service.js";
  * a network peer that has disappeared can therefore make the buffer grow
  * without throwing.  Once this threshold is crossed we drop that connection
  * and let the normal close path clean up its resources.
+ *
+ * AND YET DROPPING IT IS THE WRONG ANSWER FOR A BUSY SERVER.  The threshold was
+ * written for a peer that has gone away - a frozen tab, a pulled cable.  A server
+ * that is merely DELIVERING TOO MUCH hits the same number: a sub-agent that
+ * streams text emits one `subagent.event` per delta, each of which asks for a
+ * full state broadcast, and a browser that cannot parse frames as fast as they
+ * arrive lets the buffer grow past the threshold while it is perfectly alive.
+ * The browser then reports code 1006 and reconnects, only to be dropped again -
+ * "连接中 / 断连 / 连接中" forever - and the user's work is interrupted rather
+ * than slowed.
+ *
+ * So a frame that does not fit is DROPPED, not the connection: the next frame
+ * carries the same state, and a browser that is behind will catch up on the next
+ * one instead of being disconnected and losing its place.  The connection is
+ * only terminated when the socket itself is gone (readyState is not OPEN).
  */
 export declare const MAX_WS_BUFFERED_BYTES: number;
 /** Maximum size of one inbound WebSocket message. Attachments are uploaded
@@ -34,7 +49,19 @@ export declare class WsBroadcaster implements EventBroadcaster {
     private readonly fileIndexScopes;
     private readonly coalescedSockets;
     private readonly pendingStreams;
-    private stateFlushScheduled;
+    /**
+     * DIAGNOSTIC ONLY - sends every requested state frame immediately instead of merging them.
+     *
+     * The legacy flood switch (`SUPER_PI_LEGACY_SUBAGENT_FLOOD=1`) restores the pre-fix WIRING: one
+     * full state broadcast per sub-agent event. But the 150ms merge window would still fold those
+     * broadcasts into one frame, so the "before" measurement would not actually be "before" - it
+     * would show a flood that the fixed server also survives, and the A/B comparison would prove
+     * nothing. This flag removes the window as well, so the probe can reproduce the real pre-fix
+     * wire shape: one frame per request, sent at once.
+     *
+     * Never set outside a probe or a regression test that is asserting the old behaviour.
+     */
+    private readonly sendStateImmediately;
     constructor(getState: (scope?: {
         conversationId?: string;
     }) => AppState);
@@ -51,7 +78,31 @@ export declare class WsBroadcaster implements EventBroadcaster {
     private enqueueStreaming;
     getSockets(): Set<WebSocket>;
     broadcast(event: ServerEvent): void;
+    /**
+     * BROADCAST STATES IN A TIME WINDOW, NOT IN A MICROTASK.
+     *
+     * The microtask flag this replaces merged only the calls that arrived within the
+     * SAME tick.  A sub-agent that streams text emits one `subagent.event` per delta,
+     * each asking for a full state broadcast, and those deltas arrive across many
+     * ticks - so a single sub-agent run could ask for HUNDREDS of full state
+     * broadcasts.  On a machine whose state is large, that is a flood the browser
+     * cannot drain: its parse queue falls behind, the socket buffer grows, and the
+     * connection is dropped (the browser reports 1006).
+     *
+     * A window turns a burst into a handful of frames.  The state a browser receives
+     * is the LATEST state - the intermediate ones carried nothing the last one did
+     * not - so nothing is lost by sending fewer of them.  The only thing that
+     * changes is how promptly the browser sees a change, and 150ms is below the
+     * threshold at which a person notices.
+     */
+    private stateFlushScheduled;
     broadcastState(): void;
+    private flushState;
+    /**
+     * Releases the pending state window, so a shutting-down server does not hold the event loop
+     * open on a timer whose flush would send to sockets that are already closed.
+     */
+    dispose(): void;
     getStateSnapshot(scope?: {
         conversationId?: string;
     }): AppState;