@hheei/pi-subagents 0.2.4 → 0.3.0

package/dist/session-bootstrap.js

@@ -1,13 +1,27 @@
 import { randomUUID } from "node:crypto";
-import { open, readdir, stat } from "node:fs/promises";
+import { open, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { getAgentDir, SessionManager } from "@earendil-works/pi-coding-agent";
 import { isRecord } from "@hheei/pi-ext-core";
 import { resolveAgent } from "./agent-resolver.js";
 import { builtinAgentToolProblem } from "./builtin-agents.js";
 import { isSessionId } from "./domain.js";
 import { assembleChildPrompt, resolveBridgeExtensionPath, resolvePiInvocation, } from "./launch-spec.js";
-import { formatSessionReferencePrompt } from "./session-fork.js";
+/** Reads all JSON entries from a session file on disk. */
+export async function readSessionJsonlEntries(sessionPath) {
+    const raw = await readFile(sessionPath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.trim() !== "");
+    const entries = [];
+    for (const line of lines) {
+        try {
+            entries.push(JSON.parse(line));
+        }
+        catch {
+            // ignore trailing malformed line
+        }
+    }
+    return entries;
+}
 /** Bounded read for a session header; the first line holds the whole identity of the file. */
 const HEADER_READ_BYTES = 64 * 1024;
 /**
@@ -151,10 +165,10 @@ export function createSubagentId(existingIds) {
 export async function resolveSubagentLaunch(options) {
     const task = options.input.task.trim();
     if (task === "")
-        throw new Error("spawn_agent requires a non-empty task");
+        throw new Error("agent_spawn requires a non-empty task");
     const name = options.input.agent?.trim();
     if (name === undefined || name === "") {
-        throw new Error("spawn_agent requires an explicit agent name; V1 has no built-in default agent");
+        throw new Error("agent_spawn requires an explicit agent name; V1 has no built-in default agent");
     }
     const cwd = resolve(options.input.cwd?.trim() || options.cwd);
     const requestedTitle = options.input.title?.trim();
@@ -174,12 +188,9 @@ export async function resolveSubagentLaunch(options) {
         ...(options.onWarning === undefined ? {} : { onWarning: options.onWarning }),
     });
     if (options.enforceEnabled === true && policy.enabled === false) {
-        throw new Error(`Agent "${policy.agent.name}" is disabled: no model is specified in user configuration (~/.pi/agent/agents/ or .pi/agents/)`);
-    }
-    let instructions = policy.agent.instructions;
-    if (options.referencedSessionPath !== undefined && options.referencedSessionPath.trim() !== "") {
-        instructions = `${instructions.trim()}\n\n${formatSessionReferencePrompt(options.referencedSessionPath)}`;
+        throw new Error(`Agent "${policy.agent.name}" is disabled: no model is specified in user configuration (${join(getAgentDir(), "agents")}/ or .pi/agents/)`);
     }
+    const instructions = policy.agent.instructions;
     return Object.freeze({
         subagentId,
         invocation: options.invocation ?? resolvePiInvocation(),
@@ -187,9 +198,6 @@ export async function resolveSubagentLaunch(options) {
         sessionId,
         sessionDir: resolveSubagentSessionDir(cwd),
         ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
-        ...(options.referencedSessionPath === undefined
-            ? {}
-            : { referencedSessionPath: options.referencedSessionPath }),
         agent: policy.agent,
         model: policy.model,
         thinking: policy.thinking,
@@ -197,9 +205,9 @@ export async function resolveSubagentLaunch(options) {
         excludeTools: policy.excludeTools,
         extensions: policy.extensions,
         skills: policy.skills,
+        mcp: policy.mcp,
         prompt: assembleChildPrompt(instructions),
         bridgeExtensionPath,
-        interactive: policy.interactive,
         ...(policy.codemodeOnly ? { codemodeOnly: true } : {}),
         ...(title === undefined ? {} : { title }),
     });

package/dist/state.d.ts

@@ -19,4 +19,17 @@ export interface StateProjector {
 }
 export declare function summarizeCurrentBranch(entries: readonly unknown[]): string | undefined;
 export declare function aggregateUsage(entries: readonly unknown[]): UsageSummary;
+/** The phase a streaming assistant update is in: what the parent shows as the child's activity. */
+export type AssistantPhaseKind = "thinking" | "generating" | "toolcall";
+export interface AssistantPhase {
+    readonly kind: AssistantPhaseKind;
+    /** The tool being streamed, when the phase is a tool call. */
+    readonly toolName?: string;
+}
+/**
+ * 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 declare function assistantUpdatePhase(assistantMessageEvent: unknown, message: unknown): AssistantPhase | undefined;
 export declare function createStateProjector(initialState?: SubagentState): StateProjector;

package/dist/state.js

@@ -101,6 +101,35 @@ export function aggregateUsage(entries) {
     }
     return total;
 }
+/**
+ * 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;
@@ -120,47 +149,61 @@ export function createStateProjector(initialState = "running") {
             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 (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);
-                        if (message.stopReason === "error")
-                            state = "error";
-                        else
-                            interrupted = undefined;
+                    }
+                    else {
+                        state = "done";
+                        interrupted = undefined;
                     }
                 }
             }

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,17 @@
+import type { ExtensionAPI, ToolRenderers } from "@earendil-works/pi-coding-agent";
+/**
+ * Owned presentations for the four parent-facing subagent tools. The native renderers keep the
+ * model-visible text and raw errors when pi-ext-ui is absent; a loaded pi-ext-ui wraps the same
+ * presentation through the ext-core provider registry, so both paths share one semantic source.
+ */
+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;
+};