@evandu/super-pi 0.1.138 → 0.1.140

package/dist/server/store.d.ts

@@ -119,6 +119,29 @@ export declare class Store {
      */
     workspaceForConversation(conversationId: string): Workspace | undefined;
     workspace(workspaceId: string): Workspace | undefined;
+    /** Read the app-wide default without cloning conversations or transcripts. */
+    defaultModel(): ModelSelection | undefined;
+    /** Read one detached conversation for lifecycle operations. */
+    conversation(conversationId: string): Conversation | undefined;
+    /** Return every pending question in one conversation without cloning unrelated history. */
+    pendingQuestions(conversationId: string): Array<{
+        messageId: string;
+        index: number;
+        question: ToolCallQuestion;
+    }>;
+    /**
+     * THE SCHEDULED TASKS, WITHOUT CLONING THE STATE TO FIND THEM.
+     *
+     * The same argument as the readers above, with a sharper edge: the scheduled-task clock sweeps
+     * every fifteen seconds and used to read its three-to-zero tasks through `snapshot()` - a deep
+     * clone of the whole application, every fifteen seconds, whether the user has any scheduled task or
+     * not. On a server holding a long transcript that is a full copy of the app four times a minute,
+     * produced for a list that is usually empty.
+     *
+     * The tasks are returned as a shallow copy of the array: the sweep reads `enabled` and
+     * `nextRunAt` and then hands the whole task back to the store, which owns the real one.
+     */
+    scheduledTasks(): ScheduledTask[];
     /** Small detached rows used when refreshing each conversation's scoped model catalog. */
     catalogConversationTargets(): Array<Pick<Conversation, "id" | "archivedAt" | "model">>;
     /** Clone only one workspace's transcripts, never unrelated workspaces or app state. */
@@ -239,11 +262,14 @@ export declare class Store {
      * Filtering HERE, in one place, rather than in every reader, is what keeps the client dumb: the
      * sidebar renders `state.workspaces` and never has to know that a closed workspace exists.
      */
-    clientState(): AppState;
+    clientState(scope?: {
+        conversationId?: string;
+    }): AppState;
     createConversation(workspaceId: string, configuration?: {
         agentId?: string;
         model?: ModelSelection | null;
         thinkingLevel?: string | null;
+        modelNotice?: string;
     }): Promise<Conversation>;
     /**
      * Copies a conversation into a NEW one, under an id the caller has already minted.
@@ -480,6 +506,20 @@ export declare class Store {
      * Every field is `undefined`-tested for the same reason `settleToolCall` does it: `""` and `[]` are
      * values a tool can genuinely produce, and treating them as "not reported" would erase a real answer.
      */
+    /**
+     * THE TOOL-CALL WRITES, PERSISTED AS ONE MESSAGE INSTEAD OF THE WHOLE APPLICATION.
+     *
+     * A tool call's lifecycle touches exactly ONE thing: the `toolCalls` array of ONE message. The
+     * write used to be `this.persist()`, which hands the ENTIRE state to the repository - every
+     * workspace, every conversation, every message of every conversation - to be serialized and
+     * written. A turn that calls five tools therefore wrote the whole application ten to fifteen
+     * times, and every one of those writes was proportional to the whole history rather than to the
+     * one row that changed (LAT-020).
+     *
+     * `message.replace` is the transaction that means 「this one message now reads like this」, and it
+     * is exactly the write this is: the row's content did not change, only its tool calls did.
+     */
+    private persistToolCallMessage;
     updateToolCall(conversationId: string, messageId: string, index: number, patch: {
         label?: string;
         detail?: string;
@@ -487,6 +527,9 @@ export declare class Store {
         live?: string;
         preparing?: boolean;
         question?: ToolCallQuestion;
+        at?: number;
+        thinkingAt?: number;
+        thinkingBlock?: number | null;
         backgroundTask?: ToolCallBlock["backgroundTask"];
     }): Promise<ToolCallBlock[]>;
     /**

package/dist/server/store.js

@@ -721,6 +721,47 @@ export class Store {
         const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
         return workspace ? { ...workspace } : undefined;
     }
+    /** Read the app-wide default without cloning conversations or transcripts. */
+    defaultModel() {
+        const model = this.state.defaultModel;
+        return model ? { ...model } : undefined;
+    }
+    /** Read one detached conversation for lifecycle operations. */
+    conversation(conversationId) {
+        const conversation = this.state.conversations.find((item) => item.id === conversationId);
+        return conversation ? structuredClone(conversation) : undefined;
+    }
+    /** Return every pending question in one conversation without cloning unrelated history. */
+    pendingQuestions(conversationId) {
+        const conversation = this.state.conversations.find((item) => item.id === conversationId);
+        if (!conversation)
+            return [];
+        const pending = [];
+        for (const message of conversation.messages) {
+            for (let index = 0; index < (message.toolCalls?.length ?? 0); index += 1) {
+                const question = message.toolCalls?.[index]?.question;
+                if (message.toolCalls?.[index]?.label === "question" && question?.status === "pending") {
+                    pending.push({ messageId: message.id, index, question: structuredClone(question) });
+                }
+            }
+        }
+        return pending;
+    }
+    /**
+     * THE SCHEDULED TASKS, WITHOUT CLONING THE STATE TO FIND THEM.
+     *
+     * The same argument as the readers above, with a sharper edge: the scheduled-task clock sweeps
+     * every fifteen seconds and used to read its three-to-zero tasks through `snapshot()` - a deep
+     * clone of the whole application, every fifteen seconds, whether the user has any scheduled task or
+     * not. On a server holding a long transcript that is a full copy of the app four times a minute,
+     * produced for a list that is usually empty.
+     *
+     * The tasks are returned as a shallow copy of the array: the sweep reads `enabled` and
+     * `nextRunAt` and then hands the whole task back to the store, which owns the real one.
+     */
+    scheduledTasks() {
+        return this.state.scheduledTasks ? [...this.state.scheduledTasks] : [];
+    }
     /** Small detached rows used when refreshing each conversation's scoped model catalog. */
     catalogConversationTargets() {
         return this.state.conversations.map(({ id, archivedAt, model }) => ({
@@ -788,8 +829,10 @@ export class Store {
     snapshot() {
         const startedAt = process.env.SUPER_PI_TRACE_LATENCY === "1" ? performance.now() : 0;
         const value = structuredClone(this.state);
+        // Do not stringify here just to count bytes: that makes tracing add a second full serialization
+        // and mislabels that extra work as clone time. The broadcaster measures the actual JSON payload.
         if (startedAt)
-            console.warn(`[super-pi latency] phase=state.snapshot bytes=${JSON.stringify(value).length} cloneMs=${Math.round(performance.now() - startedAt)}`);
+            console.warn(`[super-pi latency] phase=state.snapshot cloneMs=${Math.round(performance.now() - startedAt)}`);
         return value;
     }
     /** Cheap scalar/entity reads for hot paths. Never expose the live mutable state object. */
@@ -981,14 +1024,32 @@ export class Store {
      * Filtering HERE, in one place, rather than in every reader, is what keeps the client dumb: the
      * sidebar renders `state.workspaces` and never has to know that a closed workspace exists.
      */
-    clientState() {
-        const state = this.snapshot();
-        const closed = new Set(state.workspaces.filter((item) => item.closedAt).map((item) => item.id));
-        if (!closed.size)
-            return state;
-        state.workspaces = state.workspaces.filter((item) => !closed.has(item.id));
-        state.conversations = state.conversations.filter((item) => !closed.has(item.workspaceId));
-        return state;
+    clientState(scope) {
+        const closed = new Set(this.state.workspaces.filter((item) => item.closedAt).map((item) => item.id));
+        const workspaces = this.state.workspaces.filter((item) => !closed.has(item.id));
+        const visible = this.state.conversations.filter((item) => !closed.has(item.workspaceId));
+        // Legacy sockets still receive complete visible transcripts. Project before cloning so a closed
+        // workspace's retained history is never copied just to discard it afterwards.
+        if (scope === undefined)
+            return structuredClone({ ...this.state, workspaces, conversations: visible });
+        // A focused socket keeps every sidebar row, but owns only the selected transcript. An empty scope
+        // deliberately loads none; a missing/closed selection must not expose retained workspace history.
+        const selectedId = visible.find((item) => item.id === scope.conversationId)?.id;
+        const conversations = visible.map(({ messages, ...metadata }) => ({
+            ...metadata,
+            messages: metadata.id === selectedId ? messages : [],
+            messagesLoaded: metadata.id === selectedId,
+            hasPendingQuestion: messages.some((message) => message.toolCalls?.some((call) => call.question?.status === "pending")),
+        }));
+        return structuredClone({
+            ...this.state,
+            workspaces,
+            conversations,
+            subagentRuns: this.state.subagentRuns.filter((run) => run.conversationId === selectedId),
+            ...(this.state.workflows ? { workflows: this.state.workflows.filter((run) => run.conversationId === selectedId) } : {}),
+            ...(this.state.todosByConversation ? { todosByConversation: selectedId && this.state.todosByConversation[selectedId]
+                    ? { [selectedId]: this.state.todosByConversation[selectedId] } : {} } : {}),
+        });
     }
     async createConversation(workspaceId, configuration) {
         const workspace = this.state.workspaces.find((item) => item.id === workspaceId);
@@ -1007,6 +1068,10 @@ export class Store {
         if (workspace.defaultAgentId)
             conversation.agentId = workspace.defaultAgentId;
         if (configuration) {
+            // WHY THIS CONVERSATION IS NOT ON THE MODEL THE USER SET. Set once, at birth, and never
+            // rewritten: it describes how this conversation came to be, not what is true right now.
+            if (configuration.modelNotice !== undefined)
+                conversation.modelNotice = configuration.modelNotice;
             if (configuration.model !== undefined) {
                 if (configuration.model)
                     conversation.model = { ...configuration.model };
@@ -1477,7 +1542,7 @@ export class Store {
         };
         calls.push(structuredClone(placed));
         conversation.updatedAt = now();
-        await this.persist();
+        await this.persistToolCallMessage(conversationId, messageId);
         return structuredClone(calls);
     }
     /**
@@ -1521,7 +1586,7 @@ export class Store {
         // finished tool block that vanishes the moment the call ends is a block that taught the reader
         // nothing. The client prefers `live` when both are present, falling back to `result`.
         conversation.updatedAt = now();
-        await this.persist();
+        await this.persistToolCallMessage(conversationId, messageId);
         return structuredClone(calls);
     }
     /**
@@ -1533,6 +1598,26 @@ export class Store {
      * Every field is `undefined`-tested for the same reason `settleToolCall` does it: `""` and `[]` are
      * values a tool can genuinely produce, and treating them as "not reported" would erase a real answer.
      */
+    /**
+     * THE TOOL-CALL WRITES, PERSISTED AS ONE MESSAGE INSTEAD OF THE WHOLE APPLICATION.
+     *
+     * A tool call's lifecycle touches exactly ONE thing: the `toolCalls` array of ONE message. The
+     * write used to be `this.persist()`, which hands the ENTIRE state to the repository - every
+     * workspace, every conversation, every message of every conversation - to be serialized and
+     * written. A turn that calls five tools therefore wrote the whole application ten to fifteen
+     * times, and every one of those writes was proportional to the whole history rather than to the
+     * one row that changed (LAT-020).
+     *
+     * `message.replace` is the transaction that means 「this one message now reads like this」, and it
+     * is exactly the write this is: the row's content did not change, only its tool calls did.
+     */
+    async persistToolCallMessage(conversationId, messageId) {
+        const conversation = this.requireConversation(conversationId);
+        const message = conversation.messages.find((item) => item.id === messageId);
+        if (!message)
+            return;
+        await this.persistTransaction({ kind: "message.replace", conversationId, message: structuredClone(message), updatedAt: conversation.updatedAt });
+    }
     async updateToolCall(conversationId, messageId, index, patch) {
         const conversation = this.requireConversation(conversationId);
         const message = conversation.messages.find((item) => item.id === messageId);
@@ -1569,11 +1654,28 @@ export class Store {
         // the call was being written are gone by the time it runs.
         if (patch.live !== undefined)
             call.live = patch.live;
+        // WHERE THE CALL HAPPENED, corrected when the call is announced. The placeholder stamped the
+        // offsets of the moment it was made, and that moment is not the moment the call belongs to
+        // (UX-008).
+        if (patch.at !== undefined)
+            call.at = patch.at;
+        if (patch.thinkingAt !== undefined)
+            call.thinkingAt = patch.thinkingAt;
+        // WHICH REASONING BLOCK THIS CALL BELONGS TO. It is written when the call is ANNOUNCED, not
+        // when its placeholder was made, and it is written HERE because the placeholder row already
+        // exists by then - a placeholder created while the model was still writing the arguments
+        // cannot know whether the reasoning was over by the time the call was made (UX-008).
+        //
+        // `null` IS A VALUE, NOT AN ABSENCE: it says the call is outside every reasoning block, and
+        // the browser needs to hear that difference from "not decided yet". So the check is
+        // `!== undefined`, never a truthiness test.
+        if (patch.thinkingBlock !== undefined)
+            call.thinkingBlock = patch.thinkingBlock;
         // The question rides on the call rather than beside it, so this is the only write it needs.
         if (patch.question !== undefined)
             call.question = patch.question;
         conversation.updatedAt = now();
-        await this.persist();
+        await this.persistToolCallMessage(conversationId, messageId);
         return structuredClone(calls);
     }
     /**

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;
@@ -125,7 +141,22 @@ export class SubagentRunRecorder {
         // Generated HERE, not by `run()`, because the record has to exist first - see this file's header.
         const id = input.id ?? newSubagentRunId();
         const started = { id, conversationId, agentId, task, dispatchedBy, parentRunId: input.parentRunId, depth: input.depth ?? 0, loopId: input.loopId, role: input.role, originMessageId: input.originMessageId, originCallRow: input.originCallRow, status: "running", startedAt: new Date().toISOString(), sessionId: id };
-        await this.hooks.store.beginSubagentRun(started);
+        // Own cancellation before the first persistence await. A conversation stop must also reach a
+        // human dispatch whose initial row is still being written, before a supervisor/child exists.
+        const controller = new AbortController();
+        this.controllers.set(id, { controller, conversationId });
+        const onCallerAbort = () => controller.abort();
+        input.signal?.addEventListener("abort", onCallerAbort, { once: true });
+        if (input.signal?.aborted)
+            controller.abort();
+        try {
+            await this.hooks.store.beginSubagentRun(started);
+        }
+        catch (error) {
+            input.signal?.removeEventListener("abort", onCallerAbort);
+            this.controllers.delete(id);
+            throw error;
+        }
         // The recorder's own copy, held separately from the store's. Mutating the object `beginSubagentRun`
         // was handed would reach into the store's state behind its back, and every snapshot it hands out
         // would then move under its reader.
@@ -159,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,
@@ -207,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;
         };
         /**
@@ -219,13 +251,9 @@ export class SubagentRunRecorder {
          * run happened.
          */
         const elapsedMs = () => Math.max(0, Date.now() - new Date(started.startedAt).getTime());
-        // One controller for both abort sources: the caller's signal and `abortAll` are the same button from
-        // the child's point of view, and `run()` takes exactly one.
-        const controller = new AbortController();
-        this.controllers.set(id, { controller, conversationId });
-        const onCallerAbort = () => controller.abort();
-        input.signal?.addEventListener("abort", onCallerAbort, { once: true });
         try {
+            if (controller.signal.aborted)
+                throw new SubagentCancelled(id);
             const result = await this.supervisor.run({
                 id,
                 conversationId,

package/dist/server/subagents.js

@@ -265,6 +265,13 @@ export class SubagentSupervisor {
             args.push("--provider", chosen.provider, "--model", chosen.modelId);
         if (agent.thinkingLevel)
             args.push("--thinking", agent.thinkingLevel);
+        // Cancellation may arrive during filesystem/config/model preparation, before the child or its
+        // abort listener exists. Refuse the spawn instead of starting work after the user pressed stop.
+        if (signal?.aborted) {
+            if (memoryToken)
+                this.memory?.release(memoryToken);
+            throw new SubagentCancelled(id);
+        }
         // npm exposes global CLIs as .cmd shims on Windows; Node requires a shell to launch those shims.
         const child = spawn(shellQuote(this.pi.command), args, { cwd: childCwd, stdio: ["pipe", "pipe", "pipe"], shell: process.platform === "win32", ...(memoryToken ? { env: { ...process.env, SUPER_PI_MEMORY_ENDPOINT: process.env.SUPER_PI_MEMORY_ENDPOINT, SUPER_PI_MEMORY_TOKEN: memoryToken, SUPER_PI_MEMORY_READ_ONLY: "1" } } : {}) });
         if (memoryToken)

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/tool-runner.js

@@ -156,8 +156,15 @@ export class ToolRunner {
         // -I ignores user Python configuration and user site packages. No shell means params never become code.
         const child = spawn(python.path, ["-I", "-u", input.script], { cwd: input.cwd, shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"], env: { PATH: process.env.PATH, SystemRoot: process.env.SystemRoot, TEMP: process.env.TEMP, TMP: process.env.TMP, PYTHONIOENCODING: "utf-8", PYTHONNOUSERSITE: "1", SUPER_PI_TOOL_ID: input.toolId } });
         active.child = child;
-        child.stdout.on("data", (data) => { active.stdout = clipped(`${active.stdout}${data.toString("utf8")}`); });
-        child.stderr.on("data", (data) => logLine(active, data.toString("utf8")));
+        // A PIPE CARRIES BYTES, AND A READ BOUNDARY CAN LAND INSIDE A CHARACTER. A Chinese character is
+        // three bytes, so decoding one chunk at a time turns every character that straddles a boundary
+        // into U+FFFD - the same output comes out damaged on one machine and whole on another. The
+        // stream decodes instead, and Node keeps an incomplete character until the rest of its bytes
+        // arrive.
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (text) => { active.stdout = clipped(`${active.stdout}${text}`); });
+        child.stderr.on("data", (text) => logLine(active, text));
         child.once("error", (error) => this.finish(id, "failed", error.message));
         child.once("close", (code) => {
             if (active.run.status !== "running")
@@ -210,8 +217,10 @@ function runCapture(python, args, timeoutMs, onOutput) {
         }
         catch { } resolve({ ok: false, code: null, stdout, error: `timed out after ${timeoutMs}ms` }); }, timeoutMs);
         timer.unref();
-        child.stdout.on("data", (data) => { const text = data.toString("utf8"); stdout += text; onOutput?.(text); });
-        child.stderr.on("data", (data) => { const text = data.toString("utf8"); stderr += text; onOutput?.(text); });
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (text) => { stdout += text; onOutput?.(text); });
+        child.stderr.on("data", (text) => { stderr += text; onOutput?.(text); });
         child.once("error", (error) => { if (settled)
             return; settled = true; clearTimeout(timer); resolve({ ok: false, code: null, stdout, error: error.message }); });
         child.once("close", (code) => { if (settled)