@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/extension.js

@@ -1,15 +1,26 @@
-import { registerExtensionLifecycle } from "@hheei/pi-ext-core";
+import { errorMessage, getBackgroundDelivery, registerExtensionLifecycle, TASK_REGISTRY_SERVICE_KEY, waitForService, } from "@hheei/pi-ext-core";
+import { ChildBridgeServer } from "./bridge-server.js";
 import { registerChildBridge } from "./child-bridge.js";
 import { bindParentStatus, registerParentCommands } from "./commands.js";
 import { BRIDGE_ENVIRONMENT_KEYS, isThinkingLevel } from "./domain.js";
 import { createCmuxHostAdapter, createHerdrHostAdapter, selectHostAdapter, } from "./host-adapter.js";
 import { SubagentManager } from "./manager.js";
+import { transformSubagentsMarkdown } from "./markdown.js";
 import { createSubagentRegistry } from "./registry.js";
-import { createRuntimeTokenStore, launchDetachedRunner, recoverDetachedRunner } from "./runtime.js";
+import { createRuntimeTokenStore, launchChild, openChildPanel, parentBridgeEndpoint, prepareRuntimeDirectory, } from "./runtime.js";
 import { persistSubagentIntent, resolveSubagentLaunch } from "./session-bootstrap.js";
+import { resolveForkSessionReference } from "./session-fork.js";
+import { registerInteractiveToolActivation } from "./tool-activation.js";
 import { registerParentTools } from "./tools.js";
 import { createSubagentWidget } from "./widget.js";
 const CHILD_ENV_KEYS = Object.values(BRIDGE_ENVIRONMENT_KEYS);
+/** How long startup waits for a child that survived a parent restart to reconnect its bridge. */
+const ADOPT_WINDOW_MS = 5_000;
+function diagnose(message) {
+    if (process.env.DEBUG || process.env.PI_SUBAGENTS_DEBUG) {
+        console.error(`pi-subagents: ${message}`);
+    }
+}
 function requiredBridgeValue(env, key) {
     const value = env[key];
     if (typeof value !== "string" || value === "") {
@@ -29,6 +40,72 @@ function childIdentityFromEnv(env) {
         token: requiredBridgeValue(env, BRIDGE_ENVIRONMENT_KEYS.token),
     };
 }
+/**
+ * How child reports reach the parent conversation.
+ *
+ * Busy parents receive a steer into the next model step. Idle parents wait until all registered
+ * background work finishes; decision requests and blockers bypass that wait. The shared gate
+ * coordinates this channel with Task/Bash results so only one message requests a new idle turn.
+ */
+export function createParentChannel(pi, deps) {
+    const held = [];
+    let disposed = false;
+    const flush = (triggerTurn, urgentOnly = false) => {
+        if (held.length === 0)
+            return;
+        const reports = urgentOnly ? held.filter((report) => report.reason === "blocked") : [...held];
+        if (reports.length === 0)
+            return;
+        for (const report of reports)
+            held.splice(held.indexOf(report), 1);
+        try {
+            pi.sendMessage({
+                customType: "subagent-report",
+                content: reports.map(reportText).join("\n\n"),
+                display: true,
+                details: { reports },
+            }, { triggerTurn, deliverAs: "steer" });
+        }
+        catch (error) {
+            held.unshift(...reports);
+            throw error;
+        }
+    };
+    const registration = deps.delivery.registerChannel({
+        isIdle: deps.isIdle,
+        hasPending: () => !deps.signal?.aborted && held.length > 0,
+        flush,
+    });
+    const stopWatching = pi.on("agent_start", () => registration.request());
+    const stopSettled = pi.on("agent_settled", () => registration.request());
+    return {
+        async deliver(report) {
+            if (disposed)
+                throw new Error("Parent report channel is disposed");
+            held.push(report);
+            registration.request(report.reason === "blocked");
+        },
+        dispose() {
+            disposed = true;
+            registration.dispose();
+            stopWatching();
+            stopSettled();
+            // The session is going away, so the held reports are appended for the record without
+            // starting a run in a parent that is being torn down.
+            flush(false);
+        },
+    };
+}
+/**
+ * Pi publishes the skills it loaded with every prompt; a definition names them the same way, so
+ * the launch path needs exactly the name and the file path from that list.
+ */
+export function skillCatalogFromLoaded(skills) {
+    return skills.map((skill) => ({ name: skill.name, path: skill.filePath }));
+}
+function reportText(report) {
+    return `[Subagent ${report.agent} ${report.childId}: ${report.reason}]\n${report.message}`;
+}
 export default function piSubagentsExtension(pi) {
     const child = childIdentityFromEnv(process.env);
     if (child !== undefined) {
@@ -41,19 +118,64 @@ export default function piSubagentsExtension(pi) {
             const context = runtime.extension;
             const parentSessionId = context.sessionManager.getSessionId();
             const registry = createSubagentRegistry({ parentSessionId });
-            const tokens = createRuntimeTokenStore();
-            const channel = {
-                async deliver(report) {
-                    pi.sendMessage({
-                        customType: "pi-subagent-report",
-                        content: `[Subagent ${report.agent} ${report.childId}: ${report.reason}]\n${report.message}`,
-                        display: true,
-                        details: report,
-                    }, { triggerTurn: true, deliverAs: "nextTurn" });
+            const tokens = createRuntimeTokenStore({ parentSessionId, diagnose });
+            // Presentation is chosen once per parent session: herdr first, then cmux, and a parent with
+            // neither runs every child in the background. Successful selection stays silent; only actual
+            // failures and fallback diagnostics are reported by the launch path.
+            const ownerId = parentSessionId;
+            const ownsAttachment = (identity) => identity.createdBy === ownerId;
+            const hostSelection = await selectHostAdapter({
+                adapters: {
+                    herdr: createHerdrHostAdapter({ ownerId, ownsAttachment }),
+                    cmux: createCmuxHostAdapter({ ownerId, ownsAttachment }),
                 },
-            };
+            });
+            const delivery = getBackgroundDelivery(pi);
+            const channel = createParentChannel(pi, {
+                isIdle: () => context.isIdle(),
+                delivery,
+                signal: runtime.signal,
+            });
+            runtime.resources.add("parent-channel", () => channel.dispose());
             let manager;
-            const ownsAttachment = (identity) => manager.ownsHostAttachment(identity);
+            // The parent listens; every child dials this socket, so the bridge connection is both the
+            // control plane and the only honest answer to "is this child still running?".
+            const server = new ChildBridgeServer({
+                endpoint: parentBridgeEndpoint(parentSessionId),
+                parentSessionId,
+                authorize: async (frame) => {
+                    const expected = tokens.get(frame.runtimeIdentity);
+                    if (expected === undefined) {
+                        return `no bridge token is recorded for runtime ${frame.runtimeIdentity}`;
+                    }
+                    if (expected !== frame.token)
+                        return "bridge token mismatch";
+                    // The token says which runtime is calling; the registry says which child that runtime
+                    // belongs to. Without this check a child could name another child's id and take over
+                    // its control channel, so a hello that does not match its record is refused.
+                    const record = await registry.get(frame.subagentId).catch(() => undefined);
+                    if (record === undefined)
+                        return `no recorded child ${frame.subagentId}`;
+                    if (record.runtime?.runtimeIdentity !== frame.runtimeIdentity) {
+                        return `runtime ${frame.runtimeIdentity} is not the recorded runtime of child ${frame.subagentId}`;
+                    }
+                    return undefined;
+                },
+                handleRequest: (request) => manager.handleChildRequest(request.childId, request.operation, request.payload),
+                diagnose,
+            });
+            await prepareRuntimeDirectory(diagnose);
+            await server.listen();
+            // Closing is awaited: the endpoint is unlinked after the server is closed, so a reload that
+            // started the next server first could have this close unlink the new socket path.
+            runtime.resources.add("subagent-bridge", () => server.close());
+            // A definition names skills the way Pi lists them, so the parent's loaded skill set is
+            // the only name → path catalog; Pi hands it over before every prompt of this session.
+            let skillCatalog = [];
+            const unsubscribeSkillCatalog = pi.on("before_agent_start", (event) => {
+                skillCatalog = skillCatalogFromLoaded(event.systemPromptOptions.skills);
+            });
+            runtime.resources.add("subagent-skill-catalog", unsubscribeSkillCatalog);
             manager = new SubagentManager({
                 parentSessionId,
                 registry,
@@ -67,10 +189,38 @@ export default function piSubagentsExtension(pi) {
                     if (!isThinkingLevel(thinking)) {
                         throw new Error(`Unsupported parent thinking level: ${thinking}`);
                     }
+                    const records = await registry.list().catch(() => []);
+                    const existingSubagentIds = records.map((record) => record.subagentId);
+                    let referencedSessionPath;
+                    const forkTarget = input.forkFrom?.trim();
+                    if (forkTarget !== undefined && forkTarget !== "") {
+                        try {
+                            if (forkTarget === "current") {
+                                throw new Error("forkFrom cannot be 'current'. Use 'parent' to reference the parent session or specify a subagent id like 'agent-1'.");
+                            }
+                            const parentSessionFile = context.sessionManager.getSessionFile();
+                            referencedSessionPath = await resolveForkSessionReference({
+                                forkFrom: forkTarget,
+                                ...(parentSessionFile === undefined
+                                    ? {}
+                                    : { parentSessionPath: parentSessionFile }),
+                                registry,
+                                onWarning: (message) => context.ui.notify(message, "warning"),
+                            });
+                        }
+                        catch (error) {
+                            context.ui.notify(`Referencing session failed: ${errorMessage(error)}; starting fresh session without reference`, "warning");
+                        }
+                    }
                     return resolveSubagentLaunch({
                         input,
                         cwd: context.cwd,
                         modelRegistry: context.modelRegistry,
+                        skillCatalog,
+                        existingSubagentIds,
+                        enforceEnabled: true,
+                        onWarning: (message) => context.ui.notify(message, "warning"),
+                        ...(referencedSessionPath === undefined ? {} : { referencedSessionPath }),
                         parent: {
                             model: { provider: model.provider, id: model.id },
                             thinking,
@@ -80,59 +230,106 @@ export default function piSubagentsExtension(pi) {
                 bootstrap(input) {
                     return persistSubagentIntent({ registry, ...input });
                 },
+                bridge: server,
                 launch(record) {
-                    return launchDetachedRunner({
+                    return launchChild({
                         registry,
                         record,
                         tokens,
+                        waitForBridge: (childId, signal) => server.waitForConnection(childId, {
+                            timeoutMs: ADOPT_WINDOW_MS,
+                            ...(signal === undefined ? {} : { signal }),
+                        }),
                         signal: runtime.signal,
+                        diagnose,
                     });
                 },
+                presentation: {
+                    reason: hostSelection.reason,
+                    ...(hostSelection.available
+                        ? {
+                            openPanel: (record) => openChildPanel({
+                                registry,
+                                record,
+                                tokens,
+                                host: hostSelection.adapter,
+                                waitForBridge: (childId, signal) => server.waitForConnection(childId, {
+                                    timeoutMs: ADOPT_WINDOW_MS,
+                                    ...(signal === undefined ? {} : { signal }),
+                                }),
+                                signal: runtime.signal,
+                                diagnose,
+                            }),
+                        }
+                        : {}),
+                },
+                // Adoption is a wait, never a spawn: a child that survived this parent reconnects on
+                // its own, and one that did not stays recorded until a send starts it again.
                 connect(record) {
-                    return recoverDetachedRunner({
-                        registry,
-                        record,
-                        tokens,
+                    return server.waitForConnection(record.subagentId, {
+                        timeoutMs: ADOPT_WINDOW_MS,
                         signal: runtime.signal,
                     });
                 },
-                attachHost: {
-                    select(preferredHost) {
-                        return selectHostAdapter({
-                            adapters: {
-                                herdr: createHerdrHostAdapter({
-                                    ownerId: parentSessionId,
-                                    ownsAttachment,
-                                }),
-                                cmux: createCmuxHostAdapter({
-                                    ownerId: parentSessionId,
-                                    ownsAttachment,
-                                }),
-                            },
-                            ...(preferredHost === undefined ? {} : { preferredHost }),
-                        });
-                    },
-                },
             });
-            const recovery = await manager.recover();
+            const unregisterWork = delivery.registerSource({
+                activeCount: () => manager.activeCount,
+                onChange: (listener) => manager.onChange(listener),
+            });
+            runtime.resources.add("subagent-background-work", unregisterWork);
+            // Recovery must never take the extension down with it: a registry this version cannot
+            // read (for example records written by an older release) is reported in the session and
+            // the user is told how to reset it.
+            const recovery = await manager.recover().catch((error) => ({
+                recovered: [],
+                failures: [
+                    {
+                        childId: "registry",
+                        reason: `${errorMessage(error)}. Delete the stale records (or the whole registry file) to reset this parent session's subagent state.`,
+                    },
+                ],
+            }));
             if (recovery.failures.length > 0) {
-                pi.sendMessage({
-                    customType: "pi-subagent-recovery-failure",
-                    content: `Subagent recovery failed:\n${recovery.failures
-                        .map((failure) => `- ${failure.childId}: ${failure.reason}`)
-                        .join("\n")}`,
-                    display: true,
-                    details: recovery.failures,
-                }, { triggerTurn: false });
+                context.ui.notify(`Subagent recovery failed:\n${recovery.failures
+                    .map((failure) => `- ${failure.childId}: ${failure.reason}`)
+                    .join("\n")}`, "error");
             }
             registerParentTools(pi, manager);
+            if (typeof pi.registerMarkdownTransformer === "function") {
+                pi.registerMarkdownTransformer(transformSubagentsMarkdown);
+            }
+            const activation = registerInteractiveToolActivation({
+                pi,
+                manager,
+                context,
+            });
+            runtime.resources.add("interactive-tool-activation", () => activation.dispose());
             registerParentCommands(pi, manager);
+            void waitForService(pi, TASK_REGISTRY_SERVICE_KEY, { signal: runtime.signal })
+                .then((taskRegistry) => {
+                if (runtime.signal.aborted)
+                    return;
+                const unbind = manager.bindTaskRegistry(taskRegistry);
+                runtime.resources.add("subagent-task-registry", unbind);
+            })
+                .catch((error) => {
+                diagnose(`Task registry service unavailable for subagents: ${errorMessage(error)}`);
+            });
             const widget = createSubagentWidget(pi, context, runtime.signal);
             const refreshWidget = () => {
-                void manager.list().then((children) => widget?.refresh(children));
+                if (runtime.signal.aborted)
+                    return;
+                void manager
+                    .list()
+                    .then((children) => {
+                    if (runtime.signal.aborted)
+                        return;
+                    widget?.refresh(children);
+                })
+                    .catch(() => { });
             };
             const unsubscribe = manager.onChange(refreshWidget);
-            const unbindStatus = bindParentStatus(pi, context, manager);
+            const unbindStatus = bindParentStatus(pi, context, manager, runtime.signal);
             refreshWidget();
             runtime.resources.add("subagent-widget", () => {
                 unsubscribe();

package/dist/host-adapter.d.ts

@@ -1,7 +1,5 @@
 import type { LaunchSpec } from "./launch-spec.js";
 export type HostKind = "herdr" | "cmux";
-/** Where a host command failed: session/env, layout, or the launch command itself. */
-export type HostFailureClass = "environment" | "pane" | "command";
 export interface HostCommandResult {
     readonly stdout: string;
     readonly stderr: string;
@@ -22,15 +20,11 @@ export type HostSelection = {
     readonly available: true;
     readonly selectedHost: HostKind;
     readonly adapter: HostAdapter;
-    readonly explicit: boolean;
     readonly reason: string;
-    readonly attempts: readonly HostCapability[];
 } | {
     readonly available: false;
     readonly selectedHost: null;
-    readonly explicit: boolean;
     readonly reason: string;
-    readonly attempts: readonly HostCapability[];
 };
 export interface HostAttachmentIdentity {
     readonly host: HostKind;
@@ -41,18 +35,27 @@ export interface HostObservation {
     readonly identity: HostAttachmentIdentity;
     readonly alive: boolean;
     readonly known: boolean;
+    /**
+     * Whether a human is looking at this panel. Absent when the host cannot say, which includes
+     * both hosts without the capability and a lookup that failed just now; the caller must treat
+     * an absent answer as "do not touch", because an unfocused answer lets it close the panel.
+     */
+    readonly focused?: boolean;
     readonly detail: string;
 }
 export interface HostAttachment {
     readonly identity: HostAttachmentIdentity;
     readonly launch: HostCommandResult;
+    /** True when `observe()` can report focus; idle reclaim needs it and fails open without it. */
+    readonly reportsFocus: boolean;
     observe(): Promise<HostObservation>;
     cleanup(): Promise<HostCommandResult>;
 }
 export interface HostAdapter {
     readonly kind: HostKind;
     probe(): Promise<HostCapability>;
-    attach(spec: LaunchSpec): Promise<HostAttachment>;
+    /** Opens the child's panel and runs the LaunchSpec in it. */
+    open(spec: LaunchSpec): Promise<HostAttachment>;
 }
 export interface SelectHostAdapterOptions {
     readonly adapters: Readonly<Record<HostKind, HostAdapter>>;
@@ -60,17 +63,39 @@ export interface SelectHostAdapterOptions {
 }
 /** Selects a presentation host visibly; an explicit unavailable host never falls back. */
 export declare function selectHostAdapter(options: SelectHostAdapterOptions): Promise<HostSelection>;
-export declare class HostCommandError extends Error {
-    readonly kind: HostFailureClass;
-    readonly result: HostCommandResult;
-    constructor(kind: HostFailureClass, message: string, result: HostCommandResult);
-}
 export declare const systemHostCommandRunner: HostCommandRunner;
 export interface HostAdapterOptions {
     readonly runner?: HostCommandRunner;
     readonly ownerId: string;
     readonly ownsAttachment: (identity: HostAttachmentIdentity) => boolean;
     readonly timeoutMs?: number;
+    readonly env?: NodeJS.ProcessEnv;
 }
 export declare function createHerdrHostAdapter(options: HostAdapterOptions): HostAdapter;
 export declare function createCmuxHostAdapter(options: HostAdapterOptions): HostAdapter;
+/**
+ * Herdr tab creation carries cwd, env, label, and explicit workspace id matching the parent
+ * process, ensuring the child tab spawns in the process's own workspace rather than whatever
+ * workspace happens to have user focus.
+ */
+export declare function herdrTabCreateArgs(spec: LaunchSpec, workspaceId?: string): string[];
+export declare function parseHerdrWorkspaceId(output: string): string | undefined;
+/**
+ * Resolves the workspace id of the current process so new tabs open in the same workspace.
+ * Reads environment variables first, falling back to herdr pane queries.
+ */
+export declare function resolveHerdrProcessWorkspaceId(runner: HostCommandRunner, timeoutMs: number, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/**
+ * Focus is answered from two listings: `tab list` says whether the child's tab is focused and
+ * which workspace owns it, `workspace list` says whether that workspace is the rendered one. A
+ * child is being watched only when both are focused. Anything missing — a failed listing, an absent
+ * field, a tab that is not there — is unknown, never "unfocused", because the caller closes a panel
+ * on an unfocused answer.
+ */
+export declare function herdrPanelFocused(tabList: string, workspaceList: string, tabId: string): boolean | undefined;
+/**
+ * Reads the pane's process state. A pane that no longer exists is a definite "not alive" — that is
+ * how a closed panel looks — while a query that never ran or failed for any other reason is
+ * unknown, because the caller closes the panel on "not alive".
+ */
+export declare function herdrPaneAlive(result: HostCommandResult): boolean | undefined;