@evandu/super-pi 0.1.144 → 0.1.146

package/dist/server/pi-session.js

@@ -27,6 +27,7 @@ import { existsSync, statSync } from "node:fs";
 import { open, readdir } from "node:fs/promises";
 import { StringDecoder } from "node:string_decoder";
 import { dirname, join, resolve } from "node:path";
+import { effectiveContextWindow, readDeclaredWindows } from "./model-context-window.js";
 import { fileURLToPath, pathToFileURL } from "node:url";
 const traceSession = (conversationId, phase, startedAt, extra = "") => {
     if (process.env.SUPER_PI_TRACE_LATENCY !== "1")
@@ -326,11 +327,24 @@ export async function createPiSession(creation) {
         // It is attached to the session rather than kept beside it because the session is what outlives a
         // turn: a model change applies to a LIVE session, and the live session is the thing that has to be
         // able to answer "give me this model whole".
+        // THE WINDOW THE MODEL REALLY HAS. Pi's remote catalogue can overwrite the `contextWindow` the
+        // PERSON configured in `models.json` (Pi's own merge lets the catalogue win), and a provider
+        // that reports a million tokens makes Pi's auto-compaction wait for 983,616 tokens - while the
+        // model refuses at its real 128,000. The overflow recovery then asks the same too-long
+        // conversation of the same too-small model, and the session stops working entirely.
+        //
+        // So the person's file wins: a number somebody typed is a decision, and a number a catalogue
+        // fetched is a claim. See `model-context-window.ts` for the whole reasoning.
+        const declared = readDeclaredWindows(agentDir);
         live.resolveModel = (provider, modelId) => {
             const found = modelRuntime.getModel?.(provider, modelId);
             if (!found || typeof found !== "object")
                 return undefined;
-            return found;
+            const model = found;
+            const window = effectiveContextWindow(declared, provider, modelId, model.contextWindow);
+            // The model is handed to Pi WHOLE - it is what the agent runs on - so this is where the
+            // corrected window has to be. A model Super Pi has no opinion about is handed over untouched.
+            return window === undefined ? model : { ...model, contextWindow: window };
         };
         return live;
     })();

package/dist/server/runtime.d.ts

@@ -2,6 +2,7 @@ import { type RpcRecord } from "./rpc-channel.js";
 export { RpcChannel, type RpcRecord } from "./rpc-channel.js";
 import type { ActiveMemory } from "./active-memory.js";
 import { type KnowledgeBase } from "./knowledge.js";
+import { type TurnUsageReadout } from "./conversation-usage.js";
 export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
 import { type PiSessionFactory } from "./pi-session.js";
@@ -171,6 +172,8 @@ export interface AnswerInput {
     onThinking?(delta: string): void | Promise<void>;
     /** Called when the reasoning phase ends - the only signal that it has. */
     onThinkingEnd?(): void;
+    /** One turn's completed-message usage and final context snapshot, also reported on abort/failure. */
+    onUsage?(readout: TurnUsageReadout): void | Promise<void>;
 }
 /**
  * What Pi answered when a `steer` was written to it, from the `disposition` of that command's response

package/dist/server/runtime.js

@@ -7,6 +7,8 @@ import { DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME } from "./documents.j
 import { FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME } from "./feishu-cli.js";
 import { WEB_FETCH_TOOL_NAME, WEB_SEARCH_TOOL_NAME } from "./web.js";
 import { existsSync } from "node:fs";
+import { ConversationUsageCollector } from "./conversation-usage.js";
+import { defaultAgentDir } from "./pi-session.js";
 import { mkdir, stat } from "node:fs/promises";
 import { forkSessionFile, truncateSessionFile } from "./session-repository.js";
 export { forkSessionFile, truncateSessionFile } from "./session-repository.js";
@@ -21,7 +23,7 @@ import { describeDeliveredUserMessage, describePiQueue, handleSessionEvent, Turn
 // paths recognise a delivery identically. Re-exported because they were part of this module's surface.
 export { describeDeliveredUserMessage, describePiQueue } from "./pi-session-events.js";
 import { createPiSession, createSdkCatalog, piSdkAvailable, resolveTranscriptFile, superPiExtensionPaths } from "./pi-session.js";
-import { TASK_CONVERSATION_ENV, PARENT_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, SCHEDULED_TASK_ENDPOINT_ENV, SCHEDULED_TASK_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, ORCHESTRATOR_ENDPOINT_ENV, SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, rosterPayload, } from "./task-tool.js";
+import { TASK_CONVERSATION_ENV, PARENT_CONVERSATION_ENV, TASK_DEPTH_ENV, TASK_ENDPOINT_ENV, TASK_EXEC_ENDPOINT_ENV, TASK_ROSTER_ENV, TASK_TOOL_NAME, TODO_ENDPOINT_ENV, TODO_TOOL_NAME, SCHEDULED_TASK_ENDPOINT_ENV, SCHEDULED_TASK_TOOL_NAME, WORKFLOW_ENDPOINT_ENV, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, ORCHESTRATOR_ENDPOINT_ENV, ORCHESTRATOR_WORKSPACE_ENV, SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, rosterPayload, } from "./task-tool.js";
 import { BLOCKING_UI_METHODS, EXTENSION_UI_METHODS, } from "./types.js";
 import { loadConversationImages } from "./upload.js";
 import { describeToolCall, describeToolCallArgs, describeToolCallInProgress, extractPartialResultText, extractToolResultText, readQuestionCall } from "./tool-calls.js";
@@ -696,7 +698,7 @@ export class PiRpcRuntime {
      * its environment once, when it is loaded) and a token minted per turn would be replaced before the
      * second turn of the conversation, leaving the extension holding a value the server had forgotten.
      */
-    async taskExtensionEnv(conversationId, parentConversationId) {
+    async taskExtensionEnv(conversationId, workspaceId, parentConversationId) {
         const { agents, problems } = await readAgents(this.agents.dir, { mode: "subagent" });
         for (const problem of problems)
             console.warn(`PiRpcRuntime: ${problem.file} is not a usable sub-agent - ${problem.message}`);
@@ -711,6 +713,7 @@ export class PiRpcRuntime {
             [SCHEDULED_TASK_ENDPOINT_ENV]: this.options.scheduledTaskEndpoint ?? "",
             [WORKFLOW_ENDPOINT_ENV]: this.options.workflowEndpoint ?? "",
             [ORCHESTRATOR_ENDPOINT_ENV]: this.options.orchestratorEndpoint ?? "",
+            [ORCHESTRATOR_WORKSPACE_ENV]: workspaceId,
             SUPER_PI_ORCHESTRATOR_CONVERSATION: conversationId,
             SUPER_PI_QUESTION_ENDPOINT: this.options.questionEndpoint ?? "",
             SUPER_PI_TOOLS_ENDPOINT: this.options.toolsEndpoint ?? "",
@@ -738,9 +741,9 @@ export class PiRpcRuntime {
      * here. A session lives for many turns, so its credential is minted when the session is created (see
      * `PiSessionPool.acquire`) and the server separately requires a running turn for it to be usable.
      */
-    async oneShotExtensionEnv(conversationId, capability, parentConversationId) {
+    async oneShotExtensionEnv(conversationId, workspaceId, capability, parentConversationId) {
         return {
-            ...(await this.taskExtensionEnv(conversationId, parentConversationId)),
+            ...(await this.taskExtensionEnv(conversationId, workspaceId, parentConversationId)),
             [TASK_CAPABILITY_ENV]: capability,
             SUPER_PI_TOOLS_CAPABILITY: capability,
         };
@@ -801,7 +804,7 @@ export class PiRpcRuntime {
             ...(systemPromptFile ? { systemPromptFile } : {}),
             ...(agent?.promptMode ? { systemPromptMode: agent.promptMode } : {}),
             extensionPaths: superPiExtensionPaths(repositoryRootFrom()),
-            extensionEnv: await this.taskExtensionEnv(conversation.id, conversation.parentConversationId),
+            extensionEnv: await this.taskExtensionEnv(conversation.id, conversation.workspaceId, conversation.parentConversationId),
             ...(conversation.model ? { model: { provider: conversation.model.provider, modelId: conversation.model.modelId } } : {}),
             ...(conversation.thinkingLevel ? { thinkingLevel: conversation.thinkingLevel } : {}),
         };
@@ -902,8 +905,12 @@ export class PiRpcRuntime {
         // turn failed. The bridge clears it when a new assistant message starts, and raises it when Pi
         // settles.
         const failure = { current: undefined };
+        const usage = new ConversationUsageCollector();
         const unsubscribe = session.subscribe((event) => {
             try {
+                const record = event;
+                if (record?.type === "message_end" && record.message?.role === "assistant")
+                    usage.add(record.message.usage);
                 handleSessionEvent(event, queue, handlers, report, failure);
             }
             catch (error) {
@@ -1086,6 +1093,14 @@ export class PiRpcRuntime {
             if (input.host)
                 this.sessionHosts.delete(conversation.id);
             await finished.catch(() => undefined);
+            if (input.onUsage) {
+                let context;
+                try {
+                    context = session.getContextUsage?.();
+                }
+                catch { /* Unavailable context must not discard usage or keep a stale occupancy. */ }
+                await input.onUsage(usage.readout(context, session.model, defaultAgentDir()));
+            }
         }
     }
     /**
@@ -1477,7 +1492,7 @@ export class PiRpcRuntime {
             // every turn would silently replace the child's environment with whatever THIS process has at
             // spawn time. Inheriting is what an omitted `env` already does, so the two paths differ in nothing
             // but the four documented additions.
-            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled || documentsEnabled || webEnabled || feishuEnabled) ? { env: { ...process.env, ...(oneShotCapability ? await this.oneShotExtensionEnv(conversation.id, oneShotCapability, conversation.parentConversationId) : {}), ...(memoryEnabled ? {
+            ...((extensionArgs.length || memoryEnabled || knowledgeEnabled || documentsEnabled || webEnabled || feishuEnabled) ? { env: { ...process.env, ...(oneShotCapability ? await this.oneShotExtensionEnv(conversation.id, conversation.workspaceId, oneShotCapability, conversation.parentConversationId) : {}), ...(memoryEnabled ? {
                         SUPER_PI_MEMORY_ENDPOINT: process.env.SUPER_PI_MEMORY_ENDPOINT,
                         SUPER_PI_MEMORY_TOKEN: memoryToken,
                         SUPER_PI_MEMORY_REVIEW: memoryReview ? "1" : "0",

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

@@ -0,0 +1,17 @@
+/**
+ * Resolves a conversation's optional relative cwd without ever letting it leave the workspace.
+ * An absent value preserves the workspace root; an invalid or escaping value is rejected back to
+ * that same root rather than thrown or allowed to select another directory.
+ */
+export declare function resolveSessionCwd(workspaceRoot: string, cwd?: string | null): Promise<string>;
+/**
+ * Validates an explicitly requested session cwd at creation time. Unlike the request-time fallback
+ * above, an invalid value is an error: the caller must not receive a session rooted somewhere else.
+ */
+export declare function assertSessionCwdInsideWorkspace(workspaceRoot: string, cwd?: string | null): Promise<void>;
+/** The canonical, workspace-relative spelling persisted on a conversation. */
+export declare function normalizeSessionCwd(workspaceRoot: string, cwd?: string | null): Promise<string | undefined>;
+/** Converts a path relative to the effective session root into a workspace-relative Git path. */
+export declare function workspacePathFromSession(workspaceRoot: string, sessionRoot: string, path: string): Promise<string>;
+/** One map identity per workspace/cwd pair. The root-session key remains the bare workspace id. */
+export declare function sessionScopeKey(workspaceId: string, cwd?: string): string;

package/dist/server/session-cwd.js

@@ -0,0 +1,43 @@
+import { relative, resolve, sep } from "node:path";
+import { resolveInsideRoot } from "./files.js";
+/**
+ * Resolves a conversation's optional relative cwd without ever letting it leave the workspace.
+ * An absent value preserves the workspace root; an invalid or escaping value is rejected back to
+ * that same root rather than thrown or allowed to select another directory.
+ */
+export async function resolveSessionCwd(workspaceRoot, cwd) {
+    if (!cwd?.trim())
+        return resolveInsideRoot(workspaceRoot, "");
+    try {
+        return await resolveInsideRoot(workspaceRoot, cwd);
+    }
+    catch {
+        return resolveInsideRoot(workspaceRoot, "");
+    }
+}
+/**
+ * Validates an explicitly requested session cwd at creation time. Unlike the request-time fallback
+ * above, an invalid value is an error: the caller must not receive a session rooted somewhere else.
+ */
+export async function assertSessionCwdInsideWorkspace(workspaceRoot, cwd) {
+    if (!cwd?.trim())
+        return;
+    await resolveInsideRoot(workspaceRoot, cwd);
+}
+/** The canonical, workspace-relative spelling persisted on a conversation. */
+export async function normalizeSessionCwd(workspaceRoot, cwd) {
+    if (!cwd?.trim())
+        return undefined;
+    const effective = await resolveSessionCwd(workspaceRoot, cwd);
+    const normalized = relative(resolve(workspaceRoot), effective).split(sep).join("/");
+    return normalized ? normalized : undefined;
+}
+/** Converts a path relative to the effective session root into a workspace-relative Git path. */
+export async function workspacePathFromSession(workspaceRoot, sessionRoot, path) {
+    const absolute = await resolveInsideRoot(sessionRoot, path);
+    return relative(resolve(workspaceRoot), absolute).split(sep).join("/");
+}
+/** One map identity per workspace/cwd pair. The root-session key remains the bare workspace id. */
+export function sessionScopeKey(workspaceId, cwd) {
+    return cwd ? `${workspaceId}\0${cwd}` : workspaceId;
+}

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

@@ -19,6 +19,13 @@ export interface SessionLedgerEntry {
     updatedAt: number;
     /** High-level progress snippet or latest outcome */
     lastProgress?: string;
+    /** Currently executing tool, if any */
+    activeTool?: {
+        label: string;
+        detail?: string;
+    };
+    /** Error message if execution failed */
+    error?: string;
 }
 /**
  * In-memory relationship ledger for sibling and child sessions.

package/dist/server/store.d.ts

@@ -3,6 +3,7 @@ import { defaultJsonStatePath } from "./persistence/json-state-repository.js";
 import type { ScheduledTask } from "./scheduled-tasks.js";
 import type { WorkflowRun } from "./workflow.js";
 import type { AppState, Conversation, Message, MessageDelivery, MessageImage, ModelSelection, SubagentRun, SubagentRunUpdate, TodoItem, ToolCallQuestion, ToolCallArg, ToolCallBlock, ToolResultSummary, Workspace } from "./types.js";
+import type { TurnUsageReadout } from "./conversation-usage.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
@@ -271,6 +272,7 @@ export declare class Store {
         thinkingLevel?: string | null;
         modelNotice?: string;
         agentNotice?: string;
+        cwd?: string;
         parentConversationId?: string;
         origin?: "user" | "orchestrator";
     }): Promise<Conversation>;
@@ -388,6 +390,24 @@ export declare class Store {
      * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
      * moment a turn genuinely begins.
      */
+    /**
+     * Writes ONE INSTRUCTION INTO THE TRANSCRIPT AS SOMETHING THE SYSTEM SAID.
+     *
+     * `addUserMessage` above is the only way a person's words come into being, and everything written
+     * through it wears the reader's own name and the reader's bubble. That is right for a person and
+     * wrong for the orchestrator: when a primary agent dispatches a task to a child session, the
+     * child receives an ORDER, not something the reader typed - and the child transcript showed it
+     * under the reader's avatar, so the reader saw their own name on an instruction they never wrote.
+     *
+     * The role is `tool` for a reason that is not cosmetic: `tool` is already the product's word for
+     * "the system delivered this", it renders as the 系统 side of the transcript rather than as a
+     * person, and Pi's queue already knows how to hand a `tool` message to a model (see
+     * `composePrompt` in the run service). So the instruction reaches the model the same way, and the
+     * reader sees who spoke.
+     */
+    addAgentMessage(conversationId: string, content: string, options?: {
+        delivery?: Message["delivery"];
+    }): Promise<Message>;
     addUserMessage(conversationId: string, content: string, images?: MessageImage[], attachments?: import("./types.js").MessageAttachments, options?: {
         clientId?: string;
         delivery?: Message["delivery"];
@@ -578,6 +598,8 @@ export declare class Store {
      */
     clearPreparingToolCalls(conversationId: string, messageId: string, rows: readonly number[]): Promise<ToolCallBlock[]>;
     setStatus(conversationId: string, status: Conversation["status"]): Promise<void>;
+    /** Commit once at turn end; metadata transactions work for both JSON and SQLite repositories. */
+    recordConversationUsage(conversationId: string, readout: TurnUsageReadout): Promise<void>;
     /**
      * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
      * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives

package/dist/server/store.js

@@ -1103,6 +1103,8 @@ export class Store {
             // 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.cwd)
+                conversation.cwd = configuration.cwd;
             if (configuration.parentConversationId)
                 conversation.parentConversationId = configuration.parentConversationId;
             if (configuration.origin)
@@ -1212,6 +1214,8 @@ export class Store {
             conversation.thinkingLevel = source.thinkingLevel;
         if (source.agentId)
             conversation.agentId = source.agentId;
+        if (source.cwd)
+            conversation.cwd = source.cwd;
         this.state.conversations.unshift(conversation);
         await this.persist();
         return structuredClone(conversation);
@@ -1350,6 +1354,33 @@ export class Store {
      * whatever was typed into a box that was not listening yet. `openTurnOnMessage` applies them at the
      * moment a turn genuinely begins.
      */
+    /**
+     * Writes ONE INSTRUCTION INTO THE TRANSCRIPT AS SOMETHING THE SYSTEM SAID.
+     *
+     * `addUserMessage` above is the only way a person's words come into being, and everything written
+     * through it wears the reader's own name and the reader's bubble. That is right for a person and
+     * wrong for the orchestrator: when a primary agent dispatches a task to a child session, the
+     * child receives an ORDER, not something the reader typed - and the child transcript showed it
+     * under the reader's avatar, so the reader saw their own name on an instruction they never wrote.
+     *
+     * The role is `tool` for a reason that is not cosmetic: `tool` is already the product's word for
+     * "the system delivered this", it renders as the 系统 side of the transcript rather than as a
+     * person, and Pi's queue already knows how to hand a `tool` message to a model (see
+     * `composePrompt` in the run service). So the instruction reaches the model the same way, and the
+     * reader sees who spoke.
+     */
+    async addAgentMessage(conversationId, content, options) {
+        console.error("STORE addAgentMessage conv=" + conversationId + " content=" + content.slice(0, 60));
+        const conversation = this.requireConversation(conversationId);
+        if (conversation.archivedAt)
+            throw new Error("无法向已归档的会话下发指令，请先恢复该会话");
+        const message = { id: id("message"), role: "tool", content, createdAt: now() };
+        if (options?.delivery)
+            message.delivery = options.delivery;
+        conversation.messages.push(message);
+        await this.persistMessages(conversation);
+        return structuredClone(message);
+    }
     async addUserMessage(conversationId, content, images, attachments, options) {
         const conversation = this.requireConversation(conversationId);
         // The browser cannot reach an archived conversation, so this guard exists for any other caller -
@@ -1429,6 +1460,7 @@ export class Store {
      * state it also enters `waitingMessages` and `runConversationTurns` will pick it up next.
      */
     async addToolMessage(conversationId, content, options) {
+        console.error("STORE addToolMessage conv=" + conversationId + " content=" + content.slice(0, 60));
         const conversation = this.requireConversation(conversationId);
         if (conversation.archivedAt)
             throw new Error("无法向已归档的会话追加后台回传，请先恢复该会话");
@@ -1836,6 +1868,26 @@ export class Store {
         return structuredClone(calls);
     }
     async setStatus(conversationId, status) { const conversation = this.requireConversation(conversationId); conversation.status = status; conversation.updatedAt = now(); await this.persistMetadata(conversationId); }
+    /** Commit once at turn end; metadata transactions work for both JSON and SQLite repositories. */
+    async recordConversationUsage(conversationId, readout) {
+        const conversation = this.requireConversation(conversationId);
+        if (readout.usage) {
+            const previous = conversation.usage;
+            const total = { ...readout.usage };
+            if (previous)
+                for (const key of ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"])
+                    total[key] += previous[key];
+            conversation.usage = total;
+            conversation.usageCostKnown = (conversation.usageCostKnown ?? true) && readout.costKnown;
+        }
+        if (readout.contextUsage)
+            conversation.contextUsage = { ...readout.contextUsage };
+        else
+            delete conversation.contextUsage;
+        if (readout.usage || readout.contextUsage)
+            conversation.usageUpdatedAt = now();
+        await this.persistMetadata(conversationId);
+    }
     /**
      * Records WHY a turn failed in a way the reader can see. `Conversation.error` is rendered as a red
      * banner above the transcript (`App.tsx:conversation-error`), and it is the only field that survives

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

@@ -251,13 +251,14 @@ export declare function todoSummary(todos: readonly TodoItem[]): string;
  * `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";
+export declare const ORCHESTRATOR_WORKSPACE_ENV = "SUPER_PI_ORCHESTRATOR_WORKSPACE";
 /** 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.\n4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.";
+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.\n4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.\n5. The new session always belongs to the calling session's workspace. Pass 'cwd' as a workspace-relative subdirectory (for example, 'packages/a') when it should work below the workspace root; absolute paths and traversal are rejected.";
 /** 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 sibling conversations whose direct parent is 'parentConversationId' (the calling session by default).\n3. By default it never returns full transcripts; concise summaries keep your context window lean. Set 'includeOutput' with a conversationId to read the final output from its result file, capped to the last 64Ki characters with an explicit truncation notice.";
 /** Model-facing description for session_dispatch. */

package/dist/server/task-tool.js

@@ -356,6 +356,7 @@ export function todoSummary(todos) {
  * `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";
+export const ORCHESTRATOR_WORKSPACE_ENV = "SUPER_PI_ORCHESTRATOR_WORKSPACE";
 /** Tool names registered with Pi. */
 export const SESSION_SPAWN_TOOL_NAME = "session_spawn";
 export const SESSION_STATUS_TOOL_NAME = "session_status";
@@ -382,7 +383,8 @@ 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.
-4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.`;
+4. The new session reports completion to its DIRECT parent automatically. 'parentConversationId' optionally selects that parent; by default it is the calling session.
+5. The new session always belongs to the calling session's workspace. Pass 'cwd' as a workspace-relative subdirectory (for example, 'packages/a') when it should work below the workspace root; absolute paths and traversal are rejected.`;
 /** 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.
 

package/dist/server/terminal.d.ts

@@ -104,6 +104,7 @@ export type TerminalCommand = {
     type: "terminal.open";
     sessionId: string;
     workspaceId: string;
+    cwd?: string;
     cols?: number;
     rows?: number;
 } | {

package/dist/server/terminal.js

@@ -52,6 +52,7 @@ import { createRequire } from "node:module";
 import { existsSync, accessSync, constants } from "node:fs";
 import { delimiter, join } from "node:path";
 import { isLocalOrPrivateAddress } from "./http-server.js";
+import { resolveSessionCwd } from "./session-cwd.js";
 let ptyModule;
 let ptyLoadFailure;
 /**
@@ -305,10 +306,11 @@ export class TerminalService {
                 send({ type: "terminal.error", sessionId: command.sessionId, message: "工作区不存在，无法打开终端。" });
                 return;
             }
+            const cwd = await resolveSessionCwd(workspace.path, command.cwd);
             // A workspace whose directory was deleted or renamed must not spawn a shell in `process.cwd()`,
             // which would silently run the terminal in the SERVER's directory instead of an error.
-            if (!existsSync(workspace.path)) {
-                send({ type: "terminal.error", sessionId: command.sessionId, message: `工作区目录不存在：${workspace.path}` });
+            if (!existsSync(cwd)) {
+                send({ type: "terminal.error", sessionId: command.sessionId, message: `会话工作目录不存在：${cwd}` });
                 return;
             }
             const pty = loadPty();
@@ -319,7 +321,7 @@ export class TerminalService {
                 name: "xterm-256color",
                 cols: clamp(command.cols, MIN_COLS, MAX_COLS, 80),
                 rows: clamp(command.rows, MIN_ROWS, MAX_ROWS, 24),
-                cwd: workspace.path,
+                cwd,
                 env: { ...process.env, TERM: "xterm-256color" },
             });
             const session = { pty: child, closed: false, killed: false, pending: "" };

package/dist/server/turn-failure.js

@@ -43,7 +43,9 @@ export function formatTurnFailure(error) {
     // WORKSPACE PATH - turn refused on directory the contract forbids. Refusal happens before
     // anything is on screen, so the banner is also the only place the reason lives.
     if (lower.includes("workspace directory") || lower.includes("does not exist or is not a directory")) {
-        return `工作区目录无效：${raw}`;
+        const match = raw.match(/does not exist or is not a directory:\s*(.+?)(?:\.\s*Refusing|$)/);
+        const path = match?.[1]?.trim();
+        return `工作区目录不存在：${path || "未知路径"}`;
     }
     // PROVIDER UNREACHABLE - the request never reached the model. This is the branch a custom
     // provider with a wrong Base URL lands in, and the person editing that URL needs to be told that
@@ -63,6 +65,19 @@ export function formatTurnFailure(error) {
     if (code >= 500 && code <= 599 || /internal server error|bad gateway|service unavailable|gateway timeout/.test(lower)) {
         return `模型供应商服务端出错了${code ? `（HTTP ${code}）` : ""}，通常稍后重试即可。`;
     }
+    // CONTEXT OVERFLOW - the conversation outgrew the model's window.
+    //
+    // This is the branch a reader hits when the session stops working entirely, so it has to name the
+    // cause AND the way out. The upstream wording varies by provider, and the shapes that show up are
+    // "context length exceeded", "maximum context length", "too many tokens", "prompt is too long",
+    // "reduce the length of the messages", and the 400s some providers use for it.
+    //
+    // The action is the same in every case: the conversation is too long for one request, and the
+    // reader's choices are to start a new conversation or use a model with a bigger window. Saying
+    // "the model refused" would hide both.
+    if (/context[\s_]*(?:length|window|size)[\s_]*(?:exceeded|exceeds|too large|limit)|maximum context|context limit|too many tokens|prompt is too long|reduce the length of the messages|exceeds the maximum|上下文(?:超|过)限|上下文长度/.test(lower)) {
+        return "这一轮的内容超过了模型的上下文上限，模型没能读下整段对话。可以新开一个会话继续，或换一个上下文窗口更大的模型（Pi 会在超限前自动压缩，这轮没能完成压缩）。";
+    }
     // IMAGE MISMATCH - explicit by the caller, no need to translate.
     if (lower.includes("不支持图片输入")) {
         return raw;

package/dist/server/types.d.ts

@@ -464,6 +464,12 @@ export type Conversation = {
     status: RunStatus;
     messages: Message[];
     archivedAt?: string;
+    /** Cumulative primary-assistant usage observed since readout collection began; excludes subagents. */
+    usage?: SubagentUsage;
+    /** False means cost is only a sum of reported costs, not a complete price (zero is not "free"). */
+    usageCostKnown?: boolean;
+    contextUsage?: ConversationContextUsage;
+    usageUpdatedAt?: string;
     /** Transport projection only: false means messages were omitted, rather than an empty transcript. */
     messagesLoaded?: boolean;
     /** Pending question summary, retained when a focused snapshot omits this conversation's messages. */
@@ -519,6 +525,8 @@ export type Conversation = {
      * deleted agent degrades to "no role" instead of leaving a stale snapshot in state.json.
      */
     agentId?: string;
+    /** Relative to the workspace root. Absent or empty preserves the original workspace-root cwd. */
+    cwd?: 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
@@ -655,6 +663,12 @@ export type SubagentUsage = {
     cost: number;
     turns: number;
 };
+/** Current context occupancy, distinct from cumulative billed tokens; null means unknown after compaction. */
+export type ConversationContextUsage = {
+    tokens: number | null;
+    contextWindow: number;
+    percent: number | null;
+};
 /**
  * ONE TOOL CALL, as the card shows it, and the boundary that keeps a child's turn out of `state.json`.
  *
@@ -1022,6 +1036,7 @@ export type ClientCommandBody =
     type: "terminal.open";
     sessionId: string;
     workspaceId: string;
+    cwd?: string;
     cols?: number;
     rows?: number;
 }
@@ -1182,6 +1197,7 @@ export type ClientCommandBody =
 } | {
     type: "conversation.create";
     workspaceId: string;
+    cwd?: string;
 } | {
     type: "conversation.select";
     conversationId: string;
@@ -1284,6 +1300,7 @@ export type ClientCommandBody =
  | {
     type: "files.index.subscribe";
     workspaceId?: string;
+    cwd?: string;
 } | {
     type: "state.subscribe";
     conversationId?: string;
@@ -1601,6 +1618,7 @@ export type ServerEvent = {
 } | {
     type: "files.index";
     workspaceId: string;
+    cwd?: string;
     version: number;
     changed: {
         path: string;

package/dist/server/version.d.ts

@@ -1,10 +1,33 @@
 import type { ServerVersionInfo } from "./types.js";
+export declare const UNKNOWN_VERSION = "0.0.0-unknown";
+/**
+ * Reads and validates the version string from a package.json located in the given directory.
+ */
+export declare function readPackageVersion(dir?: string): string | undefined;
+/**
+ * Resolves the version of Super Pi itself by searching relative to this module's location.
+ * In both development (`src/server/`) and production build (`dist/server/`), two levels up
+ * is the repository / package root containing package.json.
+ */
+export declare function resolveSelfVersion(fromDir?: string): string | undefined;
 /**
  * Initializes the version captured when this server process booted up.
+ * If the provided rootDir fails to yield a valid package.json version,
+ * attempts to self-heal using the module's own location before falling back to UNKNOWN_VERSION.
+ */
+export declare function initRunningVersion(rootDir: string, selfFromDir?: string): string;
+/**
+ * Returns the currently running version captured in memory.
+ */
+export declare function getRunningVersion(): string;
+/**
+ * Resets the in-memory running version, primarily for testing purposes.
  */
-export declare function initRunningVersion(rootDir: string): string;
+export declare function resetRunningVersion(toVersion?: string): string;
 /**
  * Checks whether the package.json version on disk has been updated beyond
  * the version currently executing in this process.
+ * If rootDir fails to yield a valid package.json version, attempts to self-heal
+ * using the module's own location.
  */
-export declare function checkDiskVersion(rootDir: string): ServerVersionInfo;
+export declare function checkDiskVersion(rootDir: string, selfFromDir?: string): ServerVersionInfo;