@hheei/pi-subagents 0.2.4 → 0.4.0

package/dist/state.js

@@ -101,6 +101,118 @@ export function aggregateUsage(entries) {
     }
     return total;
 }
+function userText(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    if (!Array.isArray(message.content))
+        return undefined;
+    return message.content
+        .map((part) => {
+        const content = record(part);
+        return content?.type === "text" && typeof content.text === "string" ? content.text : "";
+    })
+        .join("");
+}
+function lastCompletedAssistant(entries) {
+    let last;
+    for (const entry of entries) {
+        const item = assistant(entry);
+        if (item === undefined || !completed(item.message))
+            continue;
+        last = item.message;
+    }
+    return last;
+}
+/** What the parent projects from a session. The transcript itself never crosses the bridge. */
+export function transcriptFacts(entries, expectedInput) {
+    const last = lastCompletedAssistant(entries);
+    const summary = summarizeCurrentBranch(entries);
+    const stopReason = typeof last?.stopReason === "string" ? last.stopReason : undefined;
+    const interrupted = last === undefined ? undefined : diagnostic(last);
+    const containsInput = expectedInput !== undefined &&
+        entries.some((entry) => {
+            const value = record(entry);
+            const message = record(value?.message);
+            return message?.role === "user" && userText(message) === expectedInput;
+        });
+    return {
+        usage: aggregateUsage(entries),
+        ...(summary === undefined ? {} : { summary }),
+        ...(stopReason === undefined ? {} : { stopReason }),
+        ...(interrupted === undefined ? {} : { interrupted }),
+        containsInput,
+    };
+}
+function usageNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** A mailbox answer is untrusted. Anything that is not these fields is not facts. */
+export function parseTranscriptFacts(value) {
+    if (!isRecord(value) || typeof value.containsInput !== "boolean" || !isRecord(value.usage)) {
+        return undefined;
+    }
+    const usage = value.usage;
+    const inputTokens = usageNumber(usage.inputTokens);
+    const outputTokens = usageNumber(usage.outputTokens);
+    const cacheReadTokens = usageNumber(usage.cacheReadTokens);
+    const cacheWriteTokens = usageNumber(usage.cacheWriteTokens);
+    const turns = usageNumber(usage.turns);
+    const costUsd = usage.costUsd === null ? null : usageNumber(usage.costUsd);
+    if (inputTokens === undefined ||
+        outputTokens === undefined ||
+        cacheReadTokens === undefined ||
+        cacheWriteTokens === undefined ||
+        turns === undefined ||
+        costUsd === undefined) {
+        return undefined;
+    }
+    const summary = typeof value.summary === "string" ? value.summary : undefined;
+    const stopReason = typeof value.stopReason === "string" ? value.stopReason : undefined;
+    const interrupted = typeof value.interrupted === "string" ? value.interrupted : undefined;
+    return {
+        usage: {
+            inputTokens,
+            outputTokens,
+            cacheReadTokens,
+            cacheWriteTokens,
+            costUsd,
+            turns,
+        },
+        ...(summary === undefined ? {} : { summary }),
+        ...(stopReason === undefined ? {} : { stopReason }),
+        ...(interrupted === undefined ? {} : { interrupted }),
+        containsInput: value.containsInput,
+    };
+}
+/**
+ * Categorizes a streaming assistant update into the phase the parent projects. The child throttles
+ * duplicate deltas with the same answer, so both ends of the bridge agree on what "still thinking"
+ * means instead of each re-deriving it from a different subset of the event.
+ */
+export function assistantUpdatePhase(assistantMessageEvent, message) {
+    const update = record(assistantMessageEvent);
+    const type = typeof update?.type === "string" ? update.type : undefined;
+    const current = record(message);
+    const currentText = current === undefined ? undefined : text(current);
+    if (type === undefined) {
+        return currentText === undefined ? undefined : { kind: "generating" };
+    }
+    if (type.startsWith("thinking_"))
+        return { kind: "thinking" };
+    if (type.startsWith("toolcall_")) {
+        const index = typeof update?.contentIndex === "number" ? update.contentIndex : undefined;
+        const part = current !== undefined && Array.isArray(current.content) && index !== undefined
+            ? record(current.content[index])
+            : undefined;
+        return {
+            kind: "toolcall",
+            ...(typeof part?.name === "string" ? { toolName: part.name } : {}),
+        };
+    }
+    if (type.startsWith("text_") || currentText !== undefined)
+        return { kind: "generating" };
+    return undefined;
+}
 export function createStateProjector(initialState = "running") {
     let state = initialState;
     let summary;
@@ -114,55 +226,89 @@ export function createStateProjector(initialState = "running") {
         ...(activeTool === undefined ? {} : { activeTool }),
         usage,
     });
+    const applyFacts = (facts) => {
+        activeTool = undefined;
+        summary = facts.summary;
+        usage = facts.usage;
+        interrupted = facts.interrupted;
+        if (facts.stopReason === "error")
+            state = "error";
+        else if (facts.stopReason !== undefined && state === "error")
+            state = "done";
+        return snapshot();
+    };
     return {
         applyEvent(event) {
             const value = record(event);
             if (value === undefined)
                 return snapshot();
             if (value.type === "agent_start" ||
+                value.type === "turn_start" ||
                 value.type === "auto_retry_start" ||
                 value.type === "auto_retry") {
                 state = "running";
+                summary = "thinking...";
                 interrupted = undefined;
                 activeTool = undefined;
             }
-            else if (value.type === "tool_execution_start") {
+            else if (value.type === "tool_execution_start" || value.type === "tool_execution_update") {
                 activeTool = typeof value.toolName === "string" ? value.toolName : undefined;
             }
             else if (value.type === "tool_execution_end") {
                 activeTool = undefined;
+                summary = "thinking...";
             }
             else if (value.type === "message_update") {
                 const message = record(value.message);
                 if (message?.role === "assistant") {
-                    const currentText = text(message);
-                    if (currentText !== undefined) {
-                        summary = currentText;
+                    const phase = assistantUpdatePhase(value.assistantMessageEvent, message);
+                    if (phase?.kind === "thinking") {
+                        summary = "thinking...";
+                        activeTool = undefined;
+                    }
+                    else if (phase?.kind === "toolcall") {
+                        activeTool = phase.toolName;
+                    }
+                    else if (phase?.kind === "generating") {
+                        summary = "generating...";
                         activeTool = undefined;
                     }
                 }
             }
             else if (value.type === "agent_end" || value.type === "agent_settled") {
                 activeTool = undefined;
-                // agent_end precedes retries, compaction and queued continuation work.
-                if (value.type === "agent_settled") {
-                    if (state !== "error" && state !== "blocked") {
-                        state = "done";
-                        interrupted = undefined;
-                    }
-                }
                 const messages = Array.isArray(value.messages) ? value.messages : [];
                 const message = record(messages.length > 0 ? messages[messages.length - 1] : value.message);
                 if (message?.role === "assistant") {
                     summary = text(message) ?? summary;
-                    if (value.type === "agent_settled") {
+                    if (value.type === "agent_end" && message.stopReason === "error") {
+                        state = "error";
                         interrupted = diagnostic(message);
-                        if (message.stopReason === "error")
-                            state = "error";
-                        else
-                            interrupted = undefined;
                     }
                 }
+                if (value.type === "agent_settled") {
+                    if (value.aborted === true) {
+                        state = "blocked";
+                        interrupted = "Assistant turn was interrupted";
+                    }
+                    else if (message?.stopReason === "error") {
+                        state = "error";
+                        interrupted = diagnostic(message);
+                    }
+                    else {
+                        state = "done";
+                        interrupted = undefined;
+                    }
+                }
+            }
+            else if (value.type === "compaction_start") {
+                summary = "compacting...";
+                activeTool = undefined;
+            }
+            else if (value.type === "compaction_end") {
+                if (summary === "compacting...") {
+                    summary = undefined;
+                }
             }
             else if (value.type === "error") {
                 state = "error";
@@ -172,27 +318,10 @@ export function createStateProjector(initialState = "running") {
             return snapshot();
         },
         rebuild(entries) {
-            activeTool = undefined;
-            summary = summarizeCurrentBranch(entries);
-            usage = aggregateUsage(entries);
-            let lastAssistant;
-            for (const entry of entries) {
-                const item = assistant(entry);
-                if (item === undefined || !completed(item.message))
-                    continue;
-                lastAssistant = item.message;
-            }
-            if (lastAssistant !== undefined) {
-                interrupted = diagnostic(lastAssistant);
-                if (lastAssistant.stopReason === "error")
-                    state = "error";
-                else if (state === "error")
-                    state = "done";
-            }
-            else {
-                interrupted = undefined;
-            }
-            return snapshot();
+            return applyFacts(transcriptFacts(entries));
+        },
+        applyTranscriptFacts(facts) {
+            return applyFacts(facts);
         },
         syncState(next) {
             state = next;

package/dist/status.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import type { ThemeLike } from "@hheei/pi-ext-core";
+import { type PublicSubagent } from "./domain.js";
+export declare const SUBAGENT_STATUS_KEY = "pi-subagents";
+/** Display shorthand only; commands and tools still use the full child id. */
+export declare function formatSubagentId(id: string): string;
+export declare function formatSubagentStatus(children: readonly PublicSubagent[], theme: ThemeLike): string | undefined;
+/** Native status transport; no widget, timers or dependency on pi-status. */
+export declare function createSubagentStatus(ui: Pick<ExtensionUIContext, "setStatus"> & {
+    readonly theme: ThemeLike;
+}, signal: AbortSignal): {
+    refresh(children: readonly PublicSubagent[]): void;
+    dispose(): void;
+};

package/dist/status.js

@@ -0,0 +1,36 @@
+import { toVisualSubagentState, VISUAL_SUBAGENT_GLYPH } from "./domain.js";
+export const SUBAGENT_STATUS_KEY = "pi-subagents";
+/** Display shorthand only; commands and tools still use the full child id. */
+export function formatSubagentId(id) {
+    return `#${id.replace(/^agent-/u, "")}`;
+}
+export function formatSubagentStatus(children, theme) {
+    const running = children.filter((child) => toVisualSubagentState(child.state, child.interrupted) === "running");
+    if (running.length === 0)
+        return undefined;
+    return ("🤖 " +
+        theme.fg("accent", VISUAL_SUBAGENT_GLYPH.running) +
+        running.map((child) => theme.fg("dim", formatSubagentId(child.id))).join(" "));
+}
+/** Native status transport; no widget, timers or dependency on pi-status. */
+export function createSubagentStatus(ui, signal) {
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        signal.removeEventListener("abort", dispose);
+        ui.setStatus(SUBAGENT_STATUS_KEY, undefined);
+    };
+    if (signal.aborted)
+        dispose();
+    else
+        signal.addEventListener("abort", dispose, { once: true });
+    return {
+        refresh(children) {
+            if (!disposed)
+                ui.setStatus(SUBAGENT_STATUS_KEY, formatSubagentStatus(children, ui.theme));
+        },
+        dispose,
+    };
+}

package/dist/tool-activation.d.ts

@@ -1,11 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SubagentManager } from "./manager.js";
 /** Interactive agent tools managed by dynamic activation. */
-export declare const INTERACTIVE_TOOL_NAMES: readonly ["spawn_agent", "send_agent", "get_agent", "stop_agent"];
+export declare const INTERACTIVE_TOOL_NAMES: readonly ["agent_spawn", "agent_send", "agent_get", "agent_stop"];
 export type InteractiveToolName = (typeof INTERACTIVE_TOOL_NAMES)[number];
-export declare const SUBAGENT_LOADER_NAME = "subagent_enable";
-export declare const SUBAGENTS_LOADER_NAME = "subagent_enable";
-export declare function supportsDynamicTools(pi: ExtensionAPI): boolean;
+export declare const SUBAGENT_OPTIONAL_TOOL_KEY = "subagents";
+export declare const SUBAGENT_OPTIONAL_TOOL_BULLET = "subagents (query: \"agent\"): Subagent orchestration and delegation (agent_spawn, agent_send, agent_get, agent_stop).";
 export interface RegisterInteractiveToolActivationOptions {
     readonly pi: ExtensionAPI;
     readonly manager: SubagentManager;

package/dist/tool-activation.js

@@ -1,227 +1,25 @@
-import { buildSessionContext } from "@earendil-works/pi-coding-agent";
-import { getToolTui, isRecord, textToolResult } from "@hheei/pi-ext-core";
-import { Type } from "typebox";
-import { discoverAgents } from "./agent-resolver.js";
-import { builtinAgents } from "./builtin-agents.js";
+import { setOptionalToolBullet } from "@hheei/pi-ext-core";
 /** Interactive agent tools managed by dynamic activation. */
 export const INTERACTIVE_TOOL_NAMES = [
-    "spawn_agent",
-    "send_agent",
-    "get_agent",
-    "stop_agent",
+    "agent_spawn",
+    "agent_send",
+    "agent_get",
+    "agent_stop",
 ];
-export const SUBAGENT_LOADER_NAME = "subagent_enable";
-export const SUBAGENTS_LOADER_NAME = SUBAGENT_LOADER_NAME;
-const DESCRIPTION = "Enable interactive agent tools (spawn_agent, send_agent, get_agent, stop_agent) for running interactive subagents. Enabled tools are available on the next model request.";
-const SNIPPET = "Interactive subagents (spawn_agent, send_agent, get_agent, stop_agent) require activation. Call subagent_enable to activate them.";
-const emptySchema = Type.Object({}, { additionalProperties: false });
-export function supportsDynamicTools(pi) {
-    return (typeof pi.getAllTools === "function" &&
-        typeof pi.getActiveTools === "function" &&
-        typeof pi.setActiveTools === "function");
-}
-function hasToolDeclarations(messages) {
-    return messages.some((message) => isRecord(message) && ("toolsAdded" in message || "toolsRemoved" in message));
-}
-function currentTranscriptToolNames(messages) {
-    const tools = new Set();
-    for (const message of messages) {
-        if (!isRecord(message))
-            continue;
-        const declaration = message;
-        for (const tool of declaration.toolsRemoved ?? [])
-            tools.delete(tool.name);
-        for (const tool of declaration.toolsAdded ?? [])
-            tools.add(tool.name);
-    }
-    return [...tools];
-}
-const LEGACY_TOOL_NAMES = new Set([
-    "spawn_subagent",
-    "send_subagent",
-    "get_subagent",
-    "stop_subagent",
-    "list_subagents",
-    "subagents_enable",
-]);
-function branchHasSubagentCalls(messages, toolNames) {
-    const names = new Set([...toolNames, ...LEGACY_TOOL_NAMES]);
-    for (const msg of messages) {
-        if (!isRecord(msg))
-            continue;
-        if (msg.role === "assistant" && Array.isArray(msg.content)) {
-            for (const part of msg.content) {
-                if (isRecord(part) &&
-                    (part.type === "tool_use" || part.type === "toolCall") &&
-                    typeof part.name === "string") {
-                    if (part.name === SUBAGENT_LOADER_NAME || names.has(part.name))
-                        return true;
-                }
-            }
-        }
-        if (msg.role === "tool" &&
-            typeof msg.toolName === "string" &&
-            (msg.toolName === SUBAGENT_LOADER_NAME || names.has(msg.toolName))) {
-            return true;
-        }
-    }
-    return false;
-}
+export const SUBAGENT_OPTIONAL_TOOL_KEY = "subagents";
+export const SUBAGENT_OPTIONAL_TOOL_BULLET = 'subagents (query: "agent"): Subagent orchestration and delegation (agent_spawn, agent_send, agent_get, agent_stop).';
 export function registerInteractiveToolActivation(options) {
-    const { pi, manager, context } = options;
-    if (!supportsDynamicTools(pi)) {
-        return {
-            dispose() { },
-            selectFromSession: async () => { },
-        };
-    }
-    const names = INTERACTIVE_TOOL_NAMES;
-    const tui = getToolTui(pi);
-    const loaderTool = {
-        name: SUBAGENT_LOADER_NAME,
-        label: "Enable Interactive Subagents",
-        description: DESCRIPTION,
-        promptSnippet: SNIPPET,
-        parameters: emptySchema,
-        async execute(_id, _params, _signal, _onUpdate, execCtx) {
-            const registered = new Set(pi.getAllTools().map((tool) => tool.name));
-            const unavailable = names.filter((name) => !registered.has(name));
-            if (unavailable.length > 0) {
-                throw new Error(`Cannot enable unavailable tools: ${unavailable.join(", ")}.`);
-            }
-            const cwd = execCtx !== undefined &&
-                typeof execCtx === "object" &&
-                "cwd" in execCtx &&
-                typeof execCtx.cwd === "string"
-                ? execCtx.cwd
-                : (context.cwd ?? process.cwd());
-            let allAgents;
-            try {
-                allAgents = await discoverAgents(cwd);
-            }
-            catch {
-                allAgents = builtinAgents();
-            }
-            const interactiveAgents = allAgents
-                .filter((agent) => agent.frontmatter.interactive === true && agent.frontmatter.hidden !== true)
-                .map((agent) => ({
-                name: agent.name,
-                description: typeof agent.frontmatter.description === "string" &&
-                    agent.frontmatter.description.trim() !== ""
-                    ? agent.frontmatter.description.trim()
-                    : "No description provided.",
-            }))
-                .sort((a, b) => a.name.localeCompare(b.name));
-            const currentlyActive = new Set(pi.getActiveTools());
-            const alreadyActive = names.every((name) => currentlyActive.has(name));
-            if (!alreadyActive) {
-                try {
-                    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...names])]);
-                }
-                catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
-                    throw new Error(`Activation failed: ${message}.`);
-                }
-            }
-            const lines = [
-                alreadyActive
-                    ? `Interactive agent tools are already enabled: ${names.join(", ")}.`
-                    : `Enabled interactive agent tools: ${names.join(", ")}. They will be available on the next model request.`,
-            ];
-            if (interactiveAgents.length > 0) {
-                lines.push("");
-                lines.push("<interactive_agents>");
-                for (const agent of interactiveAgents) {
-                    lines.push(`- ${agent.name}: ${agent.description}`);
-                }
-                lines.push("</interactive_agents>");
-            }
-            return textToolResult(lines.join("\n"), {
-                enabled: [...names],
-                ...(interactiveAgents.length > 0 ? { interactiveAgents } : {}),
-            });
-        },
-    };
-    pi.registerTool(tui.frame(loaderTool, {
-        summary: () => "enable interactive subagents",
-        headerLine: "truncate",
-        footer: (result) => {
-            const details = result.details;
-            const count = details?.enabled?.length;
-            return count !== undefined
-                ? count === 1
-                    ? "1 tool enabled"
-                    : `${count} tools enabled`
-                : undefined;
-        },
-    }));
-    function loaderAvailable() {
-        return pi.getAllTools().some((tool) => tool.name === SUBAGENT_LOADER_NAME);
-    }
-    async function selectFromSession(ctx) {
-        if (!loaderAvailable())
-            return;
-        try {
-            let messages = [];
-            try {
-                const branch = ctx.sessionManager?.getBranch?.();
-                if (Array.isArray(branch) && branch.length > 0) {
-                    messages = buildSessionContext(branch).messages;
-                }
-            }
-            catch {
-                // branch or sessionManager may not be available in mock contexts
-            }
-            let hasLiveChildren = false;
-            try {
-                const children = await manager.list();
-                hasLiveChildren = children.some((child) => child.freshness === "live" || child.state === "running");
-            }
-            catch {
-                // manager may be recovering or unavailable
-            }
-            const recorded = hasToolDeclarations(messages)
-                ? new Set(currentTranscriptToolNames(messages))
-                : messages.length > 0 && branchHasSubagentCalls(messages, names)
-                    ? new Set(names)
-                    : new Set();
-            const shouldBeActive = hasLiveChildren || names.some((name) => recorded.has(name));
-            const heavy = new Set(names);
-            const active = pi.getActiveTools().filter((name) => !heavy.has(name));
-            if (shouldBeActive) {
-                for (const name of names)
-                    active.push(name);
-            }
-            pi.setActiveTools([...new Set([...active, SUBAGENT_LOADER_NAME])]);
+    const { pi } = options;
+    const unbindBeforeAgent = pi.on("before_agent_start", (event) => {
+        const sections = event.systemPromptOptions?.sections;
+        if (sections !== undefined) {
+            setOptionalToolBullet(sections, SUBAGENT_OPTIONAL_TOOL_KEY, SUBAGENT_OPTIONAL_TOOL_BULLET);
         }
-        catch (error) {
-            console.warn(`[pi-subagents] Subagent tool activation setup fallback: ${error instanceof Error ? error.message : String(error)}`);
-        }
-    }
-    const unbindSessionStart = pi.on("session_start", (_event, ctx) => {
-        void selectFromSession(ctx);
-    });
-    const unbindSessionTree = pi.on("session_tree", (_event, ctx) => {
-        void selectFromSession(ctx);
     });
-    const unbindBeforeAgentStart = () => {
-        if (!loaderAvailable() || pi.getActiveTools().includes(SUBAGENT_LOADER_NAME))
-            return;
-        try {
-            pi.setActiveTools([...pi.getActiveTools(), SUBAGENT_LOADER_NAME]);
-        }
-        catch {
-            // Best effort
-        }
-    };
-    const unbindBeforeAgent = pi.on("before_agent_start", unbindBeforeAgentStart);
-    void selectFromSession(context);
     return {
         dispose() {
-            unbindSessionStart();
-            unbindSessionTree();
             unbindBeforeAgent();
         },
-        selectFromSession,
+        selectFromSession: async () => { },
     };
 }

package/dist/tool-presentation.d.ts

@@ -0,0 +1,14 @@
+import type { ExtensionAPI, ToolRenderers } from "@earendil-works/pi-coding-agent";
+export interface AgentSpawnDetails {
+    readonly id: string;
+    readonly path: string;
+}
+/** One renderer set per tool, named exactly after its tool so nested calls resolve too. */
+export declare function parentToolRenderers(pi: ExtensionAPI): {
+    readonly spawn: ToolRenderers;
+    readonly send: ToolRenderers;
+    readonly get: ToolRenderers;
+    readonly stop: ToolRenderers;
+};
+/** The child's blocker report names the reason in the header and keeps the full message readable. */
+export declare function contactParentRenderers(pi: ExtensionAPI): ToolRenderers;