@evandu/super-pi 0.1.145 → 0.1.147

package/dist/server/model-context-window.d.ts

@@ -0,0 +1,46 @@
+/** One model's declared window, as the person's file states it. */
+export type DeclaredWindow = {
+    provider: string;
+    modelId: string;
+    contextWindow: number;
+};
+/**
+ * The windows the person's `models.json` declares, keyed by `provider/modelId`.
+ *
+ * Pi's file shape is `{ providers: { <providerId>: { models: [{ id, contextWindow, ... }] } } }`,
+ * and a model without a `contextWindow` is simply not declared - it does not become a zero, because
+ * a zero would be a claim ("this model has no window") rather than an absence.
+ */
+export declare function declaredWindows(modelsJson: unknown): Map<string, number>;
+/**
+ * The window to USE for a model, given what the person's file says.
+ *
+ * `undefined` means "say nothing" - the caller keeps whatever Pi believes. That is the honest
+ * answer for a model the person's file does not mention: Super Pi has no opinion about a model
+ * somebody else configured, and inventing one would be the same mistake in the other direction.
+ *
+ * TWO LOOKUPS, AND THE SECOND ONE IS THE ONE THAT MATTERS:
+ *
+ *   1. `provider/modelId` - the exact pair. This is the common case.
+ *   2. `modelId` ALONE, across every provider the person's file declares.
+ *
+ * The second lookup exists because a CONTEXT WINDOW IS A PROPERTY OF THE MODEL, NOT OF THE
+ * ENDPOINT. Measured on this machine: the person's `models.json` declares the model `MiniMax-M3`
+ * under the provider id `minimax` (the OpenAI-compatible endpoint) with `contextWindow: 128000`,
+ * while Pi's remote catalogue declares the SAME model under a DIFFERENT provider id,
+ * `minimax-cn` (the Anthropic-compatible endpoint), with `contextWindow: 1000000`. The session runs
+ * on `minimax-cn`, so the exact-pair lookup finds nothing and the bogus number survives.
+ *
+ * When several providers declare the same model with DIFFERENT windows, the SMALLEST wins: a model
+ * can never really have more context than its own limit, and a window that is too large is exactly
+ * the failure this exists to prevent - it pushes compaction past the point where the model refuses.
+ */
+export declare function effectiveContextWindow(declared: Map<string, number>, provider: string, modelId: string, reported?: number): number | undefined;
+/**
+ * Reads the person's `models.json` and returns its declared windows.
+ *
+ * A missing or unreadable file is an empty map, not a throw: Super Pi must not refuse to start
+ * because a person has not configured a custom provider, and the consequence of an empty map is
+ * simply "Super Pi has no opinion about this model's window" - which is where it started.
+ */
+export declare function readDeclaredWindows(agentDir: string): Map<string, number>;

package/dist/server/model-context-window.js

@@ -0,0 +1,121 @@
+/**
+ * THE CONTEXT WINDOW A MODEL REALLY HAS.
+ *
+ * Pi reads its model list from two places and one of them wins:
+ *
+ *   - `~/.pi/agent/models.json` - the file a PERSON writes, or that Super Pi writes from its own
+ *     registry. Its `contextWindow` is a deliberate statement about the model.
+ *   - `~/.pi/agent/models-store.json` - the REMOTE CATALOGUE Pi fetches from the provider, with
+ *     an etag and a timestamp. Its `contextWindow` is the PROVIDER'S SELF-REPORT.
+ *
+ * Pi's own merge lets the remote catalogue overwrite the person's file (`merged[index] = model`),
+ * so a provider that reports a generous window wins over the one the person configured.
+ *
+ * WHY THAT MATTERS, AND HOW IT BREAKS A SESSION:
+ *
+ *   Pi's auto-compaction is `shouldCompact(contextTokens, contextWindow, settings)`, i.e.
+ *   `contextTokens > contextWindow - reserveTokens`. With `reserveTokens = 16384` and a reported
+ *   window of 1,000,000, compaction waits for 983,616 tokens. The real window of that model is
+ *   128,000. So the model refuses the request at 128K, and the OVERFLOW RECOVERY - which asks the
+ *   SAME model to summarise the same too-long conversation - fails the same way. The session is
+ *   then a session that cannot answer anything, and the reader sees a dead conversation.
+ *
+ *   Measured on this machine: `models.json` says `MiniMax-M3` has `contextWindow: 128000`; the
+ *   remote catalogue says `1000000`; Pi ends up believing 1,000,000.
+ *
+ * SO: THE PERSON'S FILE WINS. A number somebody typed is a decision; a number a catalogue fetched
+ * is a claim, and a claim that is too generous does not fail loudly - it fails by never compacting.
+ *
+ * This module is deliberately narrow: it reads the person's file, and it says what the model
+ * window SHOULD be. It does not touch Pi, does not decide anything else, and is a pure function of
+ * two plain objects so it can be tested without a server, a socket, a browser or a model.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The windows the person's `models.json` declares, keyed by `provider/modelId`.
+ *
+ * Pi's file shape is `{ providers: { <providerId>: { models: [{ id, contextWindow, ... }] } } }`,
+ * and a model without a `contextWindow` is simply not declared - it does not become a zero, because
+ * a zero would be a claim ("this model has no window") rather than an absence.
+ */
+export function declaredWindows(modelsJson) {
+    const out = new Map();
+    if (!modelsJson || typeof modelsJson !== "object")
+        return out;
+    const providers = modelsJson.providers;
+    if (!providers || typeof providers !== "object")
+        return out;
+    for (const [providerId, provider] of Object.entries(providers)) {
+        if (!provider || typeof provider !== "object")
+            continue;
+        const models = provider.models;
+        if (!Array.isArray(models))
+            continue;
+        for (const model of models) {
+            if (!model || typeof model !== "object")
+                continue;
+            const id = model.id;
+            const window = model.contextWindow;
+            if (typeof id !== "string" || !id.trim())
+                continue;
+            if (typeof window !== "number" || !Number.isSafeInteger(window) || window <= 0)
+                continue;
+            out.set(`${providerId}/${id}`, window);
+        }
+    }
+    return out;
+}
+/**
+ * The window to USE for a model, given what the person's file says.
+ *
+ * `undefined` means "say nothing" - the caller keeps whatever Pi believes. That is the honest
+ * answer for a model the person's file does not mention: Super Pi has no opinion about a model
+ * somebody else configured, and inventing one would be the same mistake in the other direction.
+ *
+ * TWO LOOKUPS, AND THE SECOND ONE IS THE ONE THAT MATTERS:
+ *
+ *   1. `provider/modelId` - the exact pair. This is the common case.
+ *   2. `modelId` ALONE, across every provider the person's file declares.
+ *
+ * The second lookup exists because a CONTEXT WINDOW IS A PROPERTY OF THE MODEL, NOT OF THE
+ * ENDPOINT. Measured on this machine: the person's `models.json` declares the model `MiniMax-M3`
+ * under the provider id `minimax` (the OpenAI-compatible endpoint) with `contextWindow: 128000`,
+ * while Pi's remote catalogue declares the SAME model under a DIFFERENT provider id,
+ * `minimax-cn` (the Anthropic-compatible endpoint), with `contextWindow: 1000000`. The session runs
+ * on `minimax-cn`, so the exact-pair lookup finds nothing and the bogus number survives.
+ *
+ * When several providers declare the same model with DIFFERENT windows, the SMALLEST wins: a model
+ * can never really have more context than its own limit, and a window that is too large is exactly
+ * the failure this exists to prevent - it pushes compaction past the point where the model refuses.
+ */
+export function effectiveContextWindow(declared, provider, modelId, reported) {
+    const exact = declared.get(`${provider}/${modelId}`);
+    if (exact !== undefined)
+        return exact;
+    let smallest;
+    for (const [key, window] of declared) {
+        const slash = key.indexOf("/");
+        if (slash < 0 || key.slice(slash + 1) !== modelId)
+            continue;
+        if (smallest === undefined || window < smallest)
+            smallest = window;
+    }
+    return smallest;
+}
+/**
+ * Reads the person's `models.json` and returns its declared windows.
+ *
+ * A missing or unreadable file is an empty map, not a throw: Super Pi must not refuse to start
+ * because a person has not configured a custom provider, and the consequence of an empty map is
+ * simply "Super Pi has no opinion about this model's window" - which is where it started.
+ */
+export function readDeclaredWindows(agentDir) {
+    try {
+        const raw = readFileSync(join(agentDir, "models.json"), "utf8");
+        return declaredWindows(JSON.parse(raw));
+    }
+    catch {
+        return new Map();
+    }
+}

package/dist/server/pi-session-events.js

@@ -18,6 +18,7 @@
  */
 import { describeToolCall, describeToolCallArgs, extractPartialResultText, readQuestionCall } from "./tool-calls.js";
 import { toolTargetPath } from "./file-changes.js";
+import { LengthExceededError } from "./turn-failure.js";
 /** Keeps only real strings, so a malformed queue snapshot cannot put objects into a broadcast. */
 const textList = (value) => Array.isArray(value) ? value.filter((item) => typeof item === "string") : undefined;
 /**
@@ -337,7 +338,10 @@ export function handleSessionEvent(event, queue, handlers, report, failure) {
             const held = failure?.current;
             if (held) {
                 failure.current = undefined;
-                queue.push({ kind: "error", error: new Error(held.message) });
+                const err = held.stopReason === "length"
+                    ? new LengthExceededError(held.message)
+                    : new Error(held.message);
+                queue.push({ kind: "error", error: err });
                 return true;
             }
             queue.push({ kind: "end" });

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

@@ -165,6 +165,8 @@ export declare class PiSessionPool {
      * tool allowlist has changed.
      */
     acquire(request: SessionRequest): Promise<PiSessionLike>;
+    /** Keep an accidental session fan-out from retaining one full transcript context per conversation. */
+    private evictOverflow;
     private build;
     /**
      * Puts a live session on the model and level the conversation is asking for.

package/dist/server/pi-session-pool.js

@@ -25,6 +25,7 @@ import { join } from "node:path";
 import { createPiSession, sameFingerprint, superPiExtensionPaths, superPiSkillPaths, } from "./pi-session.js";
 /** How long an idle session survives before it is evicted. */
 const IDLE_EVICTION_MS = 10 * 60_000;
+const MAX_LIVE_SESSIONS = Math.max(4, Number.parseInt(process.env.SUPER_PI_MAX_LIVE_SESSIONS ?? "32", 10) || 32);
 /**
  * The environment variable the session's credential travels in.
  *
@@ -119,6 +120,7 @@ export class PiSessionPool {
      * tool allowlist has changed.
      */
     async acquire(request) {
+        await this.evictOverflow(request.conversationId);
         const fingerprint = this.fingerprintOf(request);
         const existing = this.sessions.get(request.conversationId);
         if (existing) {
@@ -182,6 +184,20 @@ export class PiSessionPool {
             throw error;
         }
     }
+    /** Keep an accidental session fan-out from retaining one full transcript context per conversation. */
+    async evictOverflow(exceptConversationId) {
+        if (this.sessions.size < MAX_LIVE_SESSIONS)
+            return;
+        const candidates = [...this.sessions.entries()]
+            .filter(([id, entry]) => id !== exceptConversationId && !entry.building)
+            .sort((a, b) => a[1].lastUsedAt - b[1].lastUsedAt);
+        while (this.sessions.size >= MAX_LIVE_SESSIONS && candidates.length) {
+            const [conversationId] = candidates.shift();
+            if (process.env.SUPER_PI_TRACE_LATENCY === "1")
+                console.warn(`[super-pi latency] conversation=${conversationId} phase=session.max-live-evict`);
+            await this.evict(conversationId);
+        }
+    }
     async build(request, fingerprint) {
         const creation = {
             cwd: request.cwd,

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

@@ -349,6 +349,12 @@ export interface PiSessionLike {
         provider?: string;
         id?: string;
     } | undefined;
+    /** Pi's estimate for the current context, including its post-compaction unknown state. */
+    getContextUsage?(): {
+        tokens: number | null;
+        contextWindow: number;
+        percent: number | null;
+    } | undefined;
     /**
      * Switches the model on a LIVE session.
      *

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";
@@ -16,12 +18,13 @@ import { TASK_CAPABILITY_ENV, mintCapability, releaseCapability } from "./capabi
 import { resolvePiCommand, shellQuote } from "./pi-command.js";
 import { PiSessionPool, repositoryRootFrom } from "./pi-session-pool.js";
 import { describeDeliveredUserMessage, describePiQueue, handleSessionEvent, TurnQueue } from "./pi-session-events.js";
+import { LengthExceededError } from "./turn-failure.js";
 // The queue/steer recognisers live in pi-session-events.ts, where the SESSION path's bridge can use
 // them; the one-shot drain loop below reads the same records through the same two functions, so both
 // 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 +699,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 +714,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 +742,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 +805,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 +906,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 +1094,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 +1493,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",
@@ -1589,7 +1605,7 @@ export class PiRpcRuntime {
                 if (reason === "aborted")
                     throw new Error(outcome.errorMessage || "Pi 意外中止了本轮回答。");
                 if (reason === "length")
-                    throw new Error(outcome.errorMessage || "模型输出达到本轮长度上限，回答未完成。");
+                    throw new LengthExceededError(outcome.errorMessage || "模型输出达到本轮长度上限，回答未完成。");
             };
             let firstPiRecord = true;
             // Nothing may be dropped without a trace. Pi emits a wide, open-ended family of agent

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/session-tree-scope.d.ts

@@ -0,0 +1,125 @@
+import type { Store } from "./store.js";
+/**
+ * THE SESSION TREE'S SCOPE RULE.
+ *
+ * A session may only manage its DIRECT children: the sessions whose `parentConversationId` is
+ * exactly its own id. Nothing else. A grandchild is a level away, a peer sits in somebody else's
+ * branch, an ancestor is above - none of them is this session's subordinate, so none of them may be
+ * dispatched to, read, stopped or resumed by it. A workspace is NOT an organisation chart: two
+ * supervisors can sit in the same workspace without being each other's subordinates.
+ *
+ * WHY THE RULE IS ONE LINE. The tree edge is written on the conversation itself at birth
+ * (`parentConversationId`), so "is this session my child?" is a comparison, not a walk. The walk up
+ * the chain exists for ONE purpose only: writing a refusal that says WHY, so the reader knows
+ * whether it asked for a peer, a grandchild or somebody else's department. The walk NEVER decides
+ * anything - a refusal is a refusal because the parent is not the caller, never because the walk
+ * came back empty.
+ *
+ * WHY THIS MATTERS AT ALL. The result callback of a dispatched session goes back to the session that
+ * OWNS it - the one whose id is the target's `parentConversationId`. If a session could dispatch to
+ * a session it does not own, that session's result would report to somebody else, and the tree the
+ * user sees in the sidebar would stop being the tree the work actually flows through. Making the
+ * target's parent be the caller is what keeps "who gave the order is who gets the report" true by
+ * construction.
+ */
+/** How the caller and the target relate in the session tree. Computed for the MESSAGE only. */
+export type SessionRelation = "self" | "direct-child" | "descendant" | "ancestor" | "peer" | "other-root" | "unrelated";
+/** The outcome of a scope check: allowed, or a refusal with the status code and the reason. */
+export type ScopeVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** The verb a refusal is about, so the message reads like the action that was refused. */
+export type ScopeVerb = "调度" | "读取" | "停止" | "恢复" | "列出" | "看护";
+/** What the caller was trying to reach: a session to manage, a session's children, or a parent to claim. */
+export type ScopeSubject = "manage" | "list-children" | "declare-parent";
+/** The narrow slice of the store this file needs. */
+type ConversationReader = Pick<Store, "conversation">;
+/**
+ * The relation between two sessions, in the tree.
+ *
+ * READ ONLY. This classifies a pair for the sake of the refusal message; it never grants access.
+ */
+export declare const classifySessionRelation: (store: ConversationReader, callerConversationId: string, targetConversationId: string) => SessionRelation;
+/**
+ * Writes the refusal for a pair that is not allowed to be reached.
+ *
+ * The three shapes, because the three failures are different failures:
+ *   - managing a session      -> 「不能调度/读取/停止/恢复会话 X」
+ *   - listing a session's kids -> 「不能列出会话 X 的下属」
+ *   - claiming a parent        -> 「不能把会话 X 声明为自己的下属」
+ */
+export declare const describeScopeRefusal: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+    verb: ScopeVerb;
+    subject: ScopeSubject;
+}) => string;
+/**
+ * Checks that the caller may manage the target: the target must be the caller's DIRECT child.
+ *
+ * The workspace check is NOT part of this rule and is NOT removed by it - a conversation has to be
+ * in the caller's workspace AND in the caller's own subtree. The workspace refusal comes first
+ * because it is the older, coarser boundary, and its message names the two workspaces.
+ */
+export declare const verifyDirectChildScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+    verb?: ScopeVerb;
+}) => ScopeVerdict;
+/**
+ * Checks that the caller may list a parent's children.
+ *
+ * The rule is EQUALITY, not parenthood: the parent whose children are listed must be the caller
+ * itself, so the only sessions on the list are the caller's own direct children. Listing the
+ * children of the caller's own child would be listing grandchildren, which is the cross-level reach
+ * this whole rule exists to refuse.
+ */
+export declare const verifyListParentScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    requestedParentId?: string;
+}) => ScopeVerdict;
+/**
+ * Checks that the caller may REPORT to the target: the target must be the caller's DIRECT PARENT.
+ *
+ * THE REPORTING LINE IS THE TREE EDGE, READ BACKWARDS. Every other rule in this file asks "may this
+ * session manage that one?" - and the answer is always about a session's subordinates. A report is the
+ * one message that travels UP, so the rule is inverted: a child reports to the session that owns it,
+ * the one whose id is the child's `parentConversationId`, and to nobody else.
+ *
+ * WHY THE INVERSION IS NOT A LOOPHOLE. A peer is somebody else's child, an ancestor is above the
+ * caller's own parent, a grandchild is below the caller, and a session in another workspace is another
+ * department. Every one of them would put one branch's news into another branch's inbox, and the inbox
+ * is where a parent's NEXT ACTION is decided - so a report that crossed a branch would be a stranger's
+ * news steering the wrong supervisor.
+ *
+ * THE RECIPIENT IS DERIVED, NOT CHOSEN. This check exists for the case where a caller NAMES a
+ * recipient at all: the server derives the parent from the tree and this refuses anything else, so a
+ * model cannot redirect its own report up or sideways.
+ */
+export declare const verifyReportTargetScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    targetConversationId: string;
+}) => ScopeVerdict;
+/**
+ * Checks the parent a new session is created under.
+ *
+ * The parent edge is written onto the new conversation at birth, and the result callback follows
+ * that edge home. A caller that names somebody ELSE as the parent would therefore rewrite that
+ * session's reporting line - putting the victim's result into the caller's inbox - so the parent
+ * must be the caller. An empty parent means a top-level session, which is what the user's own "+"
+ * creates and what a session with no owner legitimately is.
+ */
+export declare const verifySpawnParentScope: (options: {
+    store: ConversationReader;
+    callerConversationId: string;
+    requestedParentId?: string;
+}) => ScopeVerdict;
+export {};