@evandu/super-pi 0.1.149 → 0.1.151

package/dist/client/index.html

@@ -8,7 +8,7 @@
     <link rel="alternate icon" href="/favicon.ico" />
     <link rel="apple-touch-icon" href="/favicon.svg" />
     <title>Super Pi</title>
-    <script type="module" crossorigin src="/assets/index-Dzyp_7sf.js"></script>
+    <script type="module" crossorigin src="/assets/index-Csr3-JTY.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-BMpqviwU.css">
   </head>
   <body>

package/dist/server/agents.d.ts

@@ -38,7 +38,7 @@ type Frontmatter = Record<string, unknown>;
  */
 export declare const PI_TOOL_NAMES: readonly ["read", "bash", "powershell", "edit", "write", "grep", "find", "ls", "codemode", "tool_search", "list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"];
 /** Tools shipped by this package. Authors must be able to explicitly deny host extras. */
-export declare const SUPER_PI_TOOL_NAMES: readonly ["task", "todowrite", "workflow", "run_async", "scheduled_task", "question", "tool_register", "memory", "skill_manage", "session_search", "session_spawn", "session_status", "session_dispatch", "session_stop", "session_report", "knowledge_search", "knowledge_import", "document_read", "document_write", "web_search", "web_fetch", "feishu_doc_read", "feishu_doc_write"];
+export declare const SUPER_PI_TOOL_NAMES: readonly ["task", "todowrite", "workflow", "run_async", "scheduled_task", "question", "tool_register", "memory", "skill_manage", "session_search", "session_spawn", "session_status", "session_dispatch", "session_stop", "session_report", "session_stop_subtree", "knowledge_search", "knowledge_import", "document_read", "document_write", "web_search", "web_fetch", "feishu_doc_read", "feishu_doc_write"];
 /**
  * Whether a name can be a real Pi tool. A name is real if it is one of `PI_TOOL_NAMES`, an MCP
  * server tool, or a PATTERN.

package/dist/server/agents.js

@@ -40,7 +40,7 @@ export const PI_TOOL_NAMES = [
 export const SUPER_PI_TOOL_NAMES = [
     "task", "todowrite", "workflow", "run_async", "scheduled_task", "question", "tool_register",
     "memory", "skill_manage", "session_search",
-    "session_spawn", "session_status", "session_dispatch", "session_stop", "session_report",
+    "session_spawn", "session_status", "session_dispatch", "session_stop", "session_report", "session_stop_subtree",
     "knowledge_search", "knowledge_import",
     "document_read", "document_write", "web_search", "web_fetch", "feishu_doc_read", "feishu_doc_write",
 ];

package/dist/server/application/session-orchestrator-service.d.ts

@@ -230,6 +230,42 @@ export declare class SessionOrchestratorService {
         stopped: boolean;
         mode: string;
     }>;
+    /**
+     * THE SESSIONS UNDER ONE SESSION, DEEPEST LAST.
+     *
+     * The tree edge lives on the conversation itself (`parentConversationId`), so "who is under this
+     * one?" is a walk over the workspace's conversations rather than a separate structure that could
+     * disagree with it. The order is breadth-first, which is depth order - and the caller stops them
+     * in reverse, so the deepest work dies before the session that owns it.
+     */
+    private descendantsOf;
+    /**
+     * STOPS A SESSION AND EVERYTHING UNDER IT.
+     *
+     * THIS IS NOT THE SAME THING AS STOPPING A SESSION, and it is deliberately a separate operation
+     * rather than a flag on the other one. Stopping a session stops THAT session: its turn, its queued
+     * messages, its watchdog. Nothing else. That behaviour is right for the ordinary case - a child
+     * that went down the wrong path should not take its own children down with it, because those
+     * children may be doing work the parent still wants.
+     *
+     * But there is a case where the ordinary case leaves a mess. A supervisor whose own supervisor has
+     * stopped is an ORPHAN, and the sessions it started are orphans too: they keep burning tokens,
+     * keep writing files, and report their results to a session that is no longer running - nobody is
+     * left to read them. The parent sees a child that has gone wrong, stops it, and the grandchildren
+     * keep running with no parent to stop them.
+     *
+     * So this operation takes the whole tree: the root, its children, its grandchildren, deepest
+     * first. The descendants are stopped AS A CONSEQUENCE of the root being stopped - the caller is
+     * still only managing its OWN direct child, and the cross-level reach the scope rules forbid is
+     * not what happens here: a grandchild cannot be stopped on its own, and it cannot be spared
+     * either, because it cannot outlive the session that owns it.
+     */
+    stopSubtree(conversationId: string, options?: StopSessionOptions): Promise<{
+        stopped: boolean;
+        mode: string;
+        stoppedIds: string[];
+        descendantCount: number;
+    }>;
     /**
      * Resumes execution in a conversation.
      * If prompt is provided, sends it as a new turn.

package/dist/server/application/session-orchestrator-service.js

@@ -695,6 +695,95 @@ export class SessionOrchestratorService {
         await this.watchdog.cancel(conversationId);
         return { stopped: true, mode };
     }
+    /**
+     * THE SESSIONS UNDER ONE SESSION, DEEPEST LAST.
+     *
+     * The tree edge lives on the conversation itself (`parentConversationId`), so "who is under this
+     * one?" is a walk over the workspace's conversations rather than a separate structure that could
+     * disagree with it. The order is breadth-first, which is depth order - and the caller stops them
+     * in reverse, so the deepest work dies before the session that owns it.
+     */
+    descendantsOf(rootConversationId) {
+        const root = this.store.conversation(rootConversationId);
+        if (!root)
+            return [];
+        const childrenByParent = new Map();
+        for (const conversation of this.store.conversationsForWorkspace(root.workspaceId)) {
+            const parentId = conversation.parentConversationId;
+            if (!parentId)
+                continue;
+            const siblings = childrenByParent.get(parentId);
+            if (siblings)
+                siblings.push(conversation.id);
+            else
+                childrenByParent.set(parentId, [conversation.id]);
+        }
+        const ordered = [];
+        const seen = new Set([rootConversationId]);
+        const queue = [rootConversationId];
+        while (queue.length) {
+            const current = queue.shift();
+            for (const child of childrenByParent.get(current) ?? []) {
+                // A cycle in the stored edges must not turn this into an endless walk.
+                if (seen.has(child))
+                    continue;
+                seen.add(child);
+                ordered.push(child);
+                queue.push(child);
+            }
+        }
+        return ordered;
+    }
+    /**
+     * STOPS A SESSION AND EVERYTHING UNDER IT.
+     *
+     * THIS IS NOT THE SAME THING AS STOPPING A SESSION, and it is deliberately a separate operation
+     * rather than a flag on the other one. Stopping a session stops THAT session: its turn, its queued
+     * messages, its watchdog. Nothing else. That behaviour is right for the ordinary case - a child
+     * that went down the wrong path should not take its own children down with it, because those
+     * children may be doing work the parent still wants.
+     *
+     * But there is a case where the ordinary case leaves a mess. A supervisor whose own supervisor has
+     * stopped is an ORPHAN, and the sessions it started are orphans too: they keep burning tokens,
+     * keep writing files, and report their results to a session that is no longer running - nobody is
+     * left to read them. The parent sees a child that has gone wrong, stops it, and the grandchildren
+     * keep running with no parent to stop them.
+     *
+     * So this operation takes the whole tree: the root, its children, its grandchildren, deepest
+     * first. The descendants are stopped AS A CONSEQUENCE of the root being stopped - the caller is
+     * still only managing its OWN direct child, and the cross-level reach the scope rules forbid is
+     * not what happens here: a grandchild cannot be stopped on its own, and it cannot be spared
+     * either, because it cannot outlive the session that owns it.
+     */
+    async stopSubtree(conversationId, options) {
+        const root = this.store.conversation(conversationId);
+        if (!root) {
+            throw new Error(`找不到会话：${conversationId}`);
+        }
+        const descendants = this.descendantsOf(conversationId);
+        const stoppedIds = [];
+        // DEEPEST FIRST. A session that is stopped while its children still run is exactly the zombie
+        // this operation exists to prevent, so the leaves go before their parents.
+        for (const descendantId of [...descendants].reverse()) {
+            try {
+                await this.stop(descendantId, options);
+                stoppedIds.push(descendantId);
+            }
+            catch (error) {
+                // ONE SESSION THAT WILL NOT STOP MUST NOT LEAVE THE REST RUNNING. The point of the cascade
+                // is that nothing survives, so a failure on one session is recorded and the sweep goes on.
+                console.warn(`Super Pi: stopping descendant ${descendantId} failed:`, error instanceof Error ? error.message : String(error));
+            }
+        }
+        const result = await this.stop(conversationId, options);
+        stoppedIds.push(conversationId);
+        return {
+            stopped: result.stopped,
+            mode: result.mode,
+            stoppedIds,
+            descendantCount: descendants.length,
+        };
+    }
     /**
      * Resumes execution in a conversation.
      * If prompt is provided, sends it as a new turn.

package/dist/server/http-server.js

@@ -1614,6 +1614,21 @@ export function createHttpServer(options) {
                         json(200, { ok: true, ...result });
                         return;
                     }
+                    if (action === "stop_subtree") {
+                        if (!body.conversationId)
+                            throw new Error("stop_subtree requires conversationId");
+                        // THE ROOT OF THE TREE IS STILL THE CALLER'S DIRECT CHILD. The scope rule does not move:
+                        // the descendants go down with their owner, they are not reachable on their own, and a
+                        // caller still cannot stop somebody else's branch.
+                        const scope = verifyTargetScope(body.conversationId, "停止");
+                        if (!scope.ok) {
+                            json(scope.status, { error: scope.error });
+                            return;
+                        }
+                        const result = await service.stopSubtree(body.conversationId, { mode: body.mode, messageId: body.messageId });
+                        json(200, { ok: true, ...result });
+                        return;
+                    }
                     if (action === "resume") {
                         if (!body.conversationId)
                             throw new Error("resume requires conversationId");
@@ -1691,6 +1706,56 @@ export function createHttpServer(options) {
                 }
                 return;
             }
+            // THE PERSON'S OWN STOP.
+            //
+            // The endpoint above is the AGENT's path, and it authenticates with the session's capability,
+            // because a dispatch spends model quota on somebody's behalf and the capability is what says
+            // "this really is that session". A person clicking "stop" in their own browser is not that:
+            // stopping REDUCES work, it grants nothing, and a browser has no capability to present - so
+            // this path is refused by the address guard instead, the same guard every other user-facing
+            // write in this server carries.
+            //
+            // WHY IT IS A SEPARATE PATH AND NOT A FLAG ON THE AGENT'S ENDPOINT. The two have different
+            // authorities: one proves a session is speaking, the other proves a person is. Mixing them
+            // would mean either the browser gets a dispatch credential it must not have, or the agent
+            // loses the proof that it is the agent.
+            if (url.pathname === "/api/orchestrator/stop") {
+                if (request.method !== "POST" || !isLocalOrPrivateAddress(remote)) {
+                    response.writeHead(403, { "content-type": "text/plain; charset=utf-8" }).end("Stopping a session requires a loopback or private network POST");
+                    return;
+                }
+                const asked = await readRequestText(request, 64 * 1024);
+                if (asked.tooLarge) {
+                    response.writeHead(413, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify({ error: "请求体过大", code: "too_large" }));
+                    return;
+                }
+                const json = (status, body) => {
+                    response.writeHead(status, { "content-type": "application/json; charset=utf-8" }).end(JSON.stringify(body));
+                };
+                try {
+                    const service = context.sessionOrchestratorService;
+                    if (!service) {
+                        json(503, { error: "编排服务未就绪" });
+                        return;
+                    }
+                    const body = JSON.parse(asked.text);
+                    const conversationId = body.conversationId?.trim();
+                    if (!conversationId) {
+                        json(400, { error: "缺少 conversationId" });
+                        return;
+                    }
+                    // THE TREE GOES WITH THE ROOT WHEN THE PERSON ASKS FOR THE TREE. Stopping one session and
+                    // stopping its whole branch are two different intentions, and the person says which.
+                    const result = body.subtree
+                        ? await service.stopSubtree(conversationId, { mode: body.mode, messageId: body.messageId })
+                        : await service.stop(conversationId, { mode: body.mode, messageId: body.messageId });
+                    json(200, { ok: true, ...result });
+                }
+                catch (error) {
+                    json(400, { error: error instanceof Error ? error.message : "stop failed" });
+                }
+                return;
+            }
             if (url.pathname === "/api/conversation/usage") {
                 const json = (status, payload) => {
                     response.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" }).end(JSON.stringify(payload));

package/dist/server/runtime.js

@@ -24,7 +24,7 @@ import { LengthExceededError } from "./turn-failure.js";
 // 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, ORCHESTRATOR_WORKSPACE_ENV, SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_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, SESSION_REPORT_TOOL_NAME, SESSION_STOP_SUBTREE_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";
@@ -1260,7 +1260,7 @@ export class PiRpcRuntime {
         if (process.env.SUPER_PI_FEISHU_ENDPOINT)
             names.push(FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME);
         if (this.options.orchestratorEndpoint)
-            names.push(SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME);
+            names.push(SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME, SESSION_STOP_SUBTREE_TOOL_NAME);
         return names;
     }
     /**
@@ -1479,7 +1479,7 @@ export class PiRpcRuntime {
         // allowlist and naming a tool Pi has not registered would change the spawn line for every other
         // mode. The prompt asks for a bare JSON array and nothing else; if the model spends a turn on a
         // tool call anyway the reranker times out and falls back to the lexical order.
-        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register", ...(this.options.orchestratorEndpoint ? [SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME] : [])] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : []), ...(feishuEnabled ? [FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME] : [])] });
+        const agentArgs = memoryReview ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates", "--tools", "memory,skill_manage,session_search"] : knowledgeRerank ? ["--no-extensions", "--no-skills", "--no-mcp", "--no-context-files", "--no-prompt-templates"] : await agentSpawnArgs(this.agents.promptDir, agent, { extraAllowedTools: [...(extensionArgs.length ? [TASK_TOOL_NAME, TODO_TOOL_NAME, WORKFLOW_TOOL_NAME, RUN_ASYNC_TOOL_NAME, SCHEDULED_TASK_TOOL_NAME, "question", "tool_register", ...(this.options.orchestratorEndpoint ? [SESSION_SPAWN_TOOL_NAME, SESSION_STATUS_TOOL_NAME, SESSION_DISPATCH_TOOL_NAME, SESSION_STOP_TOOL_NAME, SESSION_REPORT_TOOL_NAME, SESSION_STOP_SUBTREE_TOOL_NAME] : [])] : []), ...(memoryEnabled ? ["memory", "skill_manage", "session_search"] : []), ...(knowledgeEnabled ? [KNOWLEDGE_TOOL_NAME, KNOWLEDGE_IMPORT_TOOL_NAME] : []), ...(documentsEnabled ? [DOCUMENT_READ_TOOL_NAME, DOCUMENT_WRITE_TOOL_NAME] : []), ...(webEnabled ? [WEB_SEARCH_TOOL_NAME, WEB_FETCH_TOOL_NAME] : []), ...(feishuEnabled ? [FEISHU_READ_TOOL_NAME, FEISHU_WRITE_TOOL_NAME] : [])] });
         // Refused here, with the reason, rather than handed to the spawn: an ENOENT from `spawn` reads as
         // "the app is broken" and hides the one fact that matters, which is where it looked for Pi.
         if (!this.pi.found)

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

@@ -258,6 +258,7 @@ 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";
 export declare const SESSION_REPORT_TOOL_NAME = "session_report";
+export declare const SESSION_STOP_SUBTREE_TOOL_NAME = "session_stop_subtree";
 /** 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.\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.\n6. Optionally pass 'model' to choose which model the NEW session runs on: {\"provider\":\"...\",\"modelId\":\"...\"} - the same \"provider/modelId\" pair the model picker shows, and BOTH halves are required. Leave 'model' out and the new session starts on the workspace default model.\n7. Optionally pass 'watchdogTimeoutSeconds' to declare how long YOU are willing to wait for a report before you want to be reminded: a positive number of seconds. If the new session stays silent that long, you receive a '[Watchdog \u63D0\u9192]' message naming it. A report from the child (session_report) restarts the clock; the watchdog never stops the child. Leave it out to run without a watchdog.";
 /** Model-facing description for session_status. */
@@ -268,3 +269,5 @@ export declare const SESSION_DISPATCH_DESCRIPTION = "Send a message, follow-up i
 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.";
 /** Model-facing description for session_report. */
 export declare const SESSION_REPORT_DESCRIPTION = "Report progress from THIS session to the parent session that spawned it.\n\nWHEN TO USE THIS:\n- You are a spawned sibling session, and the parent is waiting to hear from you: a milestone is done, a roadblock appeared, or the task is finished.\n- The parent set a watchdog (session_spawn's 'watchdogTimeoutSeconds'): a report is what restarts that clock, and silence is what triggers the reminder.\n- The task is over and the parent needs the outcome NOW rather than after the automatic end-of-turn result.\n\nWHEN NOT TO USE THIS:\n- This session has no parent (the user opened it directly): there is nobody to report to, and the server refuses the call.\n- You want to ASK the parent something or send it new instructions: that is session_dispatch, and only the parent can send it. A report is one-way - the parent receives it as a message.\n\nUsage notes:\n1. 'content' is required: it is the text the parent receives. Write it for the parent - what is done, what is left, what you need.\n2. 'status' says what the report MEANS:\n   - 'in_progress' (default): an interim update. The task continues, and the parent's watchdog clock restarts.\n   - 'completed': the task is finished and this is your final word.\n   - 'failed': the task could not be finished, and this says why.\n3. A 'completed' or 'failed' report tells the server the work is over, so the parent is NOT also sent the automatic end-of-turn result. Send it once, at the end, with the final answer in 'content'.\n4. Reporting does NOT end your turn. If the task is not done, keep working afterwards - the parent is waiting on the work, not on the report.\n5. The report reaches your DIRECT parent only. A sibling, a cousin, and the user's own session are all out of reach, and the server refuses those.";
+/** Model-facing description for session_stop_subtree. */
+export declare const SESSION_STOP_SUBTREE_DESCRIPTION = "Stop a sibling session AND every session underneath it.\n\nWHEN TO USE THIS:\n- The session has children of its own and you are stopping it: those children would otherwise keep running with a dead parent - zombies that burn tokens, keep writing files, and report results nobody is left to read.\n- The whole branch should go: stopping only the top leaves the work underneath it alive.\n- A child went wrong and everything it started has to go down with it.\n\nWHEN NOT TO USE THIS:\n- The session has no children: session_stop does the same thing to one session and says less.\n- The session is only misbehaving at the top and its children are doing work you still want: stop it alone with session_stop.\n- You want to cancel one queued message: session_stop's 'messageId'.\n\nUsage notes:\n1. 'conversationId' must be your own DIRECT child, exactly as for session_stop. You are not reaching across levels to manage anybody.\n2. Everything under that session goes down with it - children, grandchildren, the whole tree - deepest first, so nothing is left running under a session that is already gone.\n3. The descendants are stopped AS A CONSEQUENCE of stopping the root. They cannot be spared, because a session cannot outlive the one that owns it.\n4. The answer says how many sessions were stopped in total, including the one you named.";

package/dist/server/task-tool.js

@@ -363,6 +363,7 @@ export const SESSION_STATUS_TOOL_NAME = "session_status";
 export const SESSION_DISPATCH_TOOL_NAME = "session_dispatch";
 export const SESSION_STOP_TOOL_NAME = "session_stop";
 export const SESSION_REPORT_TOOL_NAME = "session_report";
+export const SESSION_STOP_SUBTREE_TOOL_NAME = "session_stop_subtree";
 /** 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.
 
@@ -447,3 +448,21 @@ Usage notes:
 3. A 'completed' or 'failed' report tells the server the work is over, so the parent is NOT also sent the automatic end-of-turn result. Send it once, at the end, with the final answer in 'content'.
 4. Reporting does NOT end your turn. If the task is not done, keep working afterwards - the parent is waiting on the work, not on the report.
 5. The report reaches your DIRECT parent only. A sibling, a cousin, and the user's own session are all out of reach, and the server refuses those.`;
+/** Model-facing description for session_stop_subtree. */
+export const SESSION_STOP_SUBTREE_DESCRIPTION = `Stop a sibling session AND every session underneath it.
+
+WHEN TO USE THIS:
+- The session has children of its own and you are stopping it: those children would otherwise keep running with a dead parent - zombies that burn tokens, keep writing files, and report results nobody is left to read.
+- The whole branch should go: stopping only the top leaves the work underneath it alive.
+- A child went wrong and everything it started has to go down with it.
+
+WHEN NOT TO USE THIS:
+- The session has no children: session_stop does the same thing to one session and says less.
+- The session is only misbehaving at the top and its children are doing work you still want: stop it alone with session_stop.
+- You want to cancel one queued message: session_stop's 'messageId'.
+
+Usage notes:
+1. 'conversationId' must be your own DIRECT child, exactly as for session_stop. You are not reaching across levels to manage anybody.
+2. Everything under that session goes down with it - children, grandchildren, the whole tree - deepest first, so nothing is left running under a session that is already gone.
+3. The descendants are stopped AS A CONSEQUENCE of stopping the root. They cannot be spared, because a session cannot outlive the one that owns it.
+4. The answer says how many sessions were stopped in total, including the one you named.`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@evandu/super-pi",
-  "version": "0.1.149",
+  "version": "0.1.151",
   "description": "Web control plane and companion for Pi",
   "license": "MIT",
   "type": "module",
@@ -217,6 +217,7 @@
     "scripts/background-result-steer.test.mjs",
     "scripts/session-report-watchdog.test.mjs",
     "scripts/session-report-tool.test.mjs",
+    "scripts/session-stop-subtree.test.mjs",
     "scripts/awaiting-background-status.test.mjs"
   ],
   "check:browser": [