@hheei/pi-subagents 0.1.2 → 0.2.3

package/dist/child-process.js

@@ -0,0 +1,93 @@
+/**
+ * The child Pi process a parent Pi spawns directly.
+ *
+ * A background child has no terminal and no supervisor, so the parent that started it is also what
+ * ends it: the process is held open through stdin (never written to) and its output is drained
+ * rather than parsed, because the bridge is the control plane and stdio is plumbing.
+ */
+import { spawn } from "node:child_process";
+import { errorMessage } from "@hheei/pi-ext-core";
+export const DEFAULT_TERMINATE_GRACE_MS = 2_000;
+const DEFAULT_KILL_GRACE_MS = 1_000;
+function hasExited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}
+/**
+ * Live handles are held for the lifetime of this process. A background child is held open by the
+ * write end of its stdin, so dropping the handle early (an extension reload, a garbage collection)
+ * would send it an EOF and end a child that only its parent's exit is supposed to end.
+ */
+const retained = new Set();
+/**
+ * Starts a detached-from-the-terminal child Pi. The caller keeps the handle: this package has no
+ * supervisor process, so nothing else can end a background child after its parent is gone.
+ */
+export function spawnChildRuntime(options) {
+    const diagnose = options.diagnose ?? (() => { });
+    const child = spawn(options.command, [...options.args], {
+        cwd: options.cwd,
+        env: options.env,
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    // Node reports a failed spawn asynchronously, so the listener is attached before anything else:
+    // a command that never started must not surface as an unhandled 'error' event.
+    const exited = new Promise((resolve) => {
+        child.once("error", (error) => {
+            diagnose(`child process error: ${errorMessage(error)}`);
+            resolve(null);
+        });
+        child.once("exit", (code, signal) => {
+            retained.delete(child);
+            if (signal !== null)
+                diagnose(`child process exited on ${signal}`);
+            resolve(code);
+        });
+    });
+    if (child.pid === undefined) {
+        child.kill("SIGKILL");
+        throw new Error(`Child process ${options.command} did not start`);
+    }
+    retained.add(child);
+    // stdout is the child's Pi protocol stream and stderr its diagnostics; neither is a control
+    // channel, so they are drained to keep the pipes from filling and reported only as diagnostics.
+    child.stdout.on("data", () => { });
+    child.stderr.on("data", (chunk) => {
+        const text = chunk.toString("utf8").trim();
+        if (text !== "")
+            diagnose(text);
+    });
+    child.stdin.on("error", () => { });
+    return {
+        pid: child.pid,
+        get alive() {
+            return !hasExited(child);
+        },
+        exited,
+        async terminate(graceMs = DEFAULT_TERMINATE_GRACE_MS) {
+            if (hasExited(child))
+                return;
+            child.kill("SIGTERM");
+            if (await settled(exited, graceMs))
+                return;
+            diagnose(`child process ${child.pid} ignored SIGTERM; sending SIGKILL`);
+            child.kill("SIGKILL");
+            if (!(await settled(exited, DEFAULT_KILL_GRACE_MS))) {
+                diagnose(`child process ${child.pid} did not exit after SIGKILL`);
+            }
+        },
+    };
+}
+/** True when `work` settled within the window; the child process outlives this wait either way. */
+function settled(work, timeoutMs) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(false), timeoutMs);
+        timer.unref?.();
+        void work.then(() => {
+            clearTimeout(timer);
+            resolve(true);
+        }, () => {
+            clearTimeout(timer);
+            resolve(true);
+        });
+    });
+}

package/dist/commands.d.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { PublicSubagent } from "./domain.js";
+import { type PublicSubagent } from "./domain.js";
 import type { SubagentManager } from "./manager.js";
 export declare function formatStatusLine(children: readonly PublicSubagent[]): string | undefined;
 export declare function registerParentCommands(pi: ExtensionAPI, manager: SubagentManager): void;
-export declare function bindParentStatus(_pi: ExtensionAPI, context: ExtensionContext, manager: SubagentManager): () => void;
+export declare function bindParentStatus(_pi: ExtensionAPI, context: ExtensionContext, manager: SubagentManager, signal?: AbortSignal): () => void;

package/dist/commands.js

@@ -1,14 +1,20 @@
+import { splitSubcommand, subcommandCompletions } from "@hheei/pi-ext-core";
+import { toVisualSubagentState, VISUAL_SUBAGENT_GLYPH } from "./domain.js";
 const STATUS_KEY = "pi-subagents";
+/** Verbs of the dispatcher below; the completer and the no-argument picker share them. */
+const SUBAGENT_SUBCOMMANDS = ["list", "inspect", "send", "stop"];
+const SUBAGENT_COMMAND_USAGE = "Usage: /subagents list|inspect|send|stop [id]";
 export function formatStatusLine(children) {
-    const visible = children.filter((child) => child.state !== "done" && child.state !== "stopped");
+    const visible = children.filter((child) => child.state !== "done" && child.state !== "error");
     if (visible.length === 0)
         return undefined;
     return visible
         .map((child) => {
+        const visual = toVisualSubagentState(child.state, child.interrupted);
+        const glyph = VISUAL_SUBAGENT_GLYPH[visual];
         const name = child.displayName ?? child.agent;
-        const mode = child.mode === "tui" ? "tui" : child.state;
-        const flag = child.interrupted !== undefined ? " interrupted" : "";
-        return `${name} ${mode}${flag}`;
+        const mode = child.presentation === "panel" ? `${visual} panel` : visual;
+        return `${glyph} ${name} ${mode}`;
     })
         .join(" · ");
 }
@@ -20,8 +26,10 @@ function notifyResult(ctx, result, ok) {
     ctx.ui.notify(ok);
 }
 function childLabel(child) {
+    const visual = toVisualSubagentState(child.state, child.interrupted);
+    const glyph = VISUAL_SUBAGENT_GLYPH[visual];
     const name = child.displayName ?? child.agent;
-    return `${name} ${child.id} ${child.state}/${child.mode}`;
+    return `${glyph} ${name} #${child.id} ${visual}/${child.presentation}`;
 }
 async function pickChild(ctx, children, title) {
     if (children.length === 0) {
@@ -36,23 +44,12 @@ async function pickChild(ctx, children, title) {
         return undefined;
     return children[labels.indexOf(selected)];
 }
-async function attachSelected(ctx, manager, id) {
-    if (id !== undefined && id !== "") {
-        notifyResult(ctx, await manager.attach(id), `Attached ${id}`);
-        return;
-    }
-    const idle = (await manager.list()).filter((child) => child.mode === "rpc" && child.state === "idle");
-    const child = await pickChild(ctx, idle, "Attach idle subagent");
-    if (child === undefined)
-        return;
-    notifyResult(ctx, await manager.attach(child.id), `Attached ${child.id}`);
-}
 async function stopSelected(ctx, manager, id) {
     if (id !== undefined && id !== "") {
         notifyResult(ctx, await manager.stop(id), `Stopped ${id}`);
         return;
     }
-    const live = (await manager.list()).filter((child) => child.state !== "done" && child.state !== "stopped");
+    const live = (await manager.list()).filter((child) => child.state !== "done" && child.state !== "error");
     const child = await pickChild(ctx, live, "Stop subagent");
     if (child === undefined)
         return;
@@ -60,14 +57,16 @@ async function stopSelected(ctx, manager, id) {
 }
 export function registerParentCommands(pi, manager) {
     pi.registerCommand("subagents", {
-        description: "List, inspect, attach, send to, or stop an owned subagent",
+        description: "Manage subagents: /subagents [list | inspect | send | stop [id]]",
+        getArgumentCompletions: subcommandCompletions(SUBAGENT_SUBCOMMANDS),
         handler: async (args, ctx) => {
             if (ctx.mode !== "tui") {
-                ctx.ui.notify("Use spawn_subagent / send_subagent / get_subagent / stop_subagent in this mode");
+                ctx.ui.notify("Use spawn_agent / send_agent / get_agent / stop_agent in this mode");
                 return;
             }
-            const action = args.trim() ||
-                (await ctx.ui.select("Subagents", ["list", "inspect", "attach", "send", "stop"]));
+            const { verb, rest: target } = splitSubcommand(args);
+            // Only `attach` and `stop` take a subagent id; the picker verbs ignore the rest.
+            const action = verb === "" ? await ctx.ui.select("Subagents", [...SUBAGENT_SUBCOMMANDS]) : verb;
             if (action === undefined)
                 return;
             const children = await manager.list();
@@ -91,16 +90,12 @@ export function registerParentCommands(pi, manager) {
                 ctx.ui.notify(`${childLabel(inspected)}\n${inspected.summary ?? "no summary"}\nmodel ${inspected.model.provider}/${inspected.model.id}`);
                 return;
             }
-            if (action === "attach") {
-                await attachSelected(ctx, manager);
-                return;
-            }
             if (action === "stop") {
-                await stopSelected(ctx, manager);
+                await stopSelected(ctx, manager, target);
                 return;
             }
             if (action === "send") {
-                const live = children.filter((child) => child.mode === "rpc" && (child.state === "idle" || child.state === "running"));
+                const live = children.filter((child) => child.state === "running");
                 const child = await pickChild(ctx, live, "Send to subagent");
                 if (child === undefined)
                     return;
@@ -108,48 +103,45 @@ export function registerParentCommands(pi, manager) {
                 if (message === undefined || message.trim() === "")
                     return;
                 notifyResult(ctx, await manager.send(child.id, message.trim()), `Sent to ${child.id}`);
-            }
-        },
-    });
-    pi.registerCommand("attach-subagent", {
-        description: "Open an RPC child as a native Pi TUI. Idle children switch immediately; busy children wait for the current turn to finish. The session must already be flushed.",
-        handler: async (args, ctx) => {
-            await attachSelected(ctx, manager, args.trim());
-        },
-    });
-    pi.registerCommand("stop-subagent", {
-        description: "Stop an owned subagent",
-        handler: async (args, ctx) => {
-            await stopSelected(ctx, manager, args.trim());
-        },
-    });
-    pi.registerShortcut("ctrl+shift+a", {
-        description: "Attach idle subagent",
-        handler: (ctx) => {
-            if (ctx.mode !== "tui")
-                return;
-            return attachSelected(ctx, manager);
-        },
-    });
-    pi.registerShortcut("ctrl+shift+s", {
-        description: "Stop subagent",
-        handler: (ctx) => {
-            if (ctx.mode !== "tui")
                 return;
-            return stopSelected(ctx, manager);
+            }
+            ctx.ui.notify(`Unknown subcommand "${action}". ${SUBAGENT_COMMAND_USAGE}`, "warning");
         },
     });
 }
-export function bindParentStatus(_pi, context, manager) {
+export function bindParentStatus(_pi, context, manager, signal) {
+    let disposed = false;
     const refresh = () => {
-        void manager.list().then((children) => {
-            context.ui.setStatus(STATUS_KEY, formatStatusLine(children));
-        });
+        if (disposed || signal?.aborted)
+            return;
+        void manager
+            .list()
+            .then((children) => {
+            if (disposed || signal?.aborted)
+                return;
+            try {
+                context.ui.setStatus(STATUS_KEY, formatStatusLine(children));
+            }
+            catch {
+                // Context may be stale after session replacement or reload.
+            }
+        })
+            .catch(() => { });
     };
     const unsubscribe = manager.onChange(refresh);
     refresh();
     return () => {
+        if (disposed)
+            return;
+        disposed = true;
         unsubscribe();
-        context.ui.setStatus(STATUS_KEY, undefined);
+        if (signal?.aborted)
+            return;
+        try {
+            context.ui.setStatus(STATUS_KEY, undefined);
+        }
+        catch {
+            // Context may be stale after session replacement or reload.
+        }
     };
 }

package/dist/diagnostics.d.ts

@@ -6,5 +6,3 @@
  */
 export declare function writeDiagnostic(scope: string, message: string): void;
 export declare function toError(value: unknown): Error;
-export declare function errorMessage(value: unknown): string;
-export declare function abortError(): Error;

package/dist/diagnostics.js

@@ -10,11 +10,3 @@ export function writeDiagnostic(scope, message) {
 export function toError(value) {
     return value instanceof Error ? value : new Error(String(value));
 }
-export function errorMessage(value) {
-    return value instanceof Error ? value.message : String(value);
-}
-export function abortError() {
-    const error = new Error("Operation aborted");
-    error.name = "AbortError";
-    return error;
-}

package/dist/domain.d.ts

@@ -1,8 +1,20 @@
 export declare const PROTOCOL_VERSION: 1;
 export declare const REGISTRY_VERSION: 1;
-export type SubagentState = "starting" | "running" | "idle" | "done" | "stopped" | "failed";
-export type ExecutionMode = "rpc" | "tui";
+export type SubagentState = "running" | "done" | "blocked" | "error";
+export declare function normalizeSubagentState(value: unknown): SubagentState | undefined;
+/**
+ * Where a child is presented: `panel` is the native Pi TUI in a host panel (herdr tab / cmux
+ * surface), `background` is a headless Pi the parent owns over stdio. It is frozen when the child
+ * is created, because it decides who holds the process for the rest of the child's life.
+ */
+export type Presentation = "panel" | "background";
 export type SendMode = "steer" | "follow_up" | "auto";
+export type VisualSubagentState = SubagentState;
+export declare function toVisualSubagentState(state: SubagentState, interrupted?: string): VisualSubagentState;
+export declare const VISUAL_SUBAGENT_GLYPH: Record<VisualSubagentState, string>;
+export declare const VISUAL_SUBAGENT_TONE: Record<VisualSubagentState, "accent" | "success" | "warning" | "error">;
+export declare const SUBAGENT_GLYPH: Record<SubagentState, string>;
+export declare const SUBAGENT_TONE: Record<SubagentState, "accent" | "success" | "warning" | "error">;
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type LaunchValueSource = "agent" | "parent";
 export type SubagentIntent = "active" | "stopped";
@@ -48,14 +60,13 @@ export interface ResolvedThinking {
     readonly level: ThinkingLevel;
     readonly source: LaunchValueSource;
 }
-export interface ExtensionSelection {
-    readonly discovery: boolean;
-    readonly paths: readonly string[];
-}
-export interface SkillSelection {
+export interface Selection {
     readonly discovery: boolean;
     readonly paths: readonly string[];
 }
+/** Extensions and skills are selected the same way; the aliases keep the two roles named. */
+export type ExtensionSelection = Selection;
+export type SkillSelection = Selection;
 export interface EffectiveLaunchConfig {
     /** Logical child id; the same value the child bridge reports back. */
     readonly subagentId: string;
@@ -66,6 +77,8 @@ export interface EffectiveLaunchConfig {
     readonly sessionDir: string;
     /** Known only once the session has been flushed to disk. */
     readonly sessionPath?: string;
+    /** Optional path to a prior session JSONL file referenced for on-demand context inspection. */
+    readonly referencedSessionPath?: string;
     readonly agent: ResolvedAgentIdentity;
     readonly model: ResolvedModel;
     readonly thinking: ResolvedThinking;
@@ -77,6 +90,13 @@ export interface EffectiveLaunchConfig {
     readonly bridgeExtensionPath: string;
     /** Frozen at spawn. Interactive children do not auto-wake the parent except via contact_parent. */
     readonly interactive: boolean;
+    /** Whether the subagent operates in codemode-only mode. */
+    readonly codemodeOnly?: boolean;
+    /**
+     * Session title asked for at spawn, frozen so a relaunched child re-applies the same name.
+     * Presentation only: it never changes the child's identity or its host attachment label.
+     */
+    readonly title?: string;
 }
 export interface ResolvedAgentPolicy {
     readonly agent: ResolvedAgentIdentity;
@@ -87,24 +107,16 @@ export interface ResolvedAgentPolicy {
     readonly extensions: ExtensionSelection;
     readonly skills: SkillSelection;
     readonly interactive: boolean;
+    readonly codemodeOnly?: boolean;
+    readonly enabled?: boolean;
 }
+/**
+ * The runtime attachment a child was last launched with. It is evidence, never a liveness proof:
+ * whether that process is still serving this child is answered by the bridge connection.
+ */
 export interface RuntimeMetadata {
     readonly runtimeIdentity: string;
     readonly endpoint: string;
-    readonly pid?: number;
-}
-export type RuntimeClaimKind = "reconnect" | "replacement";
-/** Non-secret, durable ownership claim used to serialize reconnect and replacement. */
-export interface RuntimeClaim {
-    readonly claimId: string;
-    readonly kind: RuntimeClaimKind;
-    readonly holderPid: number;
-    readonly runtimeIdentity: string;
-    readonly endpoint: string;
-    /** SHA-256 of the one-time controller token; the token itself is never persisted. */
-    readonly controllerTokenHash: string;
-    /** Set by the runner before it starts the Pi writer. */
-    readonly runnerPid?: number;
 }
 export interface UsageSummary {
     readonly inputTokens: number;
@@ -126,12 +138,12 @@ export interface SubagentRecord {
     readonly initialTask: string;
     readonly intent: SubagentIntent;
     readonly state: SubagentState;
-    readonly mode: ExecutionMode;
+    readonly presentation: Presentation;
     readonly persistence: PersistenceState;
     readonly launchConfig: EffectiveLaunchConfig;
     readonly runtime?: RuntimeMetadata;
-    readonly claim?: RuntimeClaim;
     readonly latestSummary?: string;
+    readonly activeTool?: string;
     readonly usage?: UsageSummary;
     readonly interrupted?: string;
     readonly unacknowledgedInput?: string;
@@ -141,10 +153,11 @@ export interface PublicSubagent {
     readonly agent: string;
     readonly displayName?: string;
     readonly state: SubagentState;
-    readonly mode: ExecutionMode;
+    readonly presentation: Presentation;
     readonly cwd: string;
     readonly sessionId: string;
     readonly summary?: string;
+    readonly activeTool?: string;
     readonly usage?: UsageSummary;
     readonly interrupted?: string;
     readonly freshness: "live" | "last_known";
@@ -166,7 +179,23 @@ export interface SpawnSubagentInput {
     readonly task: string;
     readonly agent: string;
     readonly cwd?: string;
-}
+    /**
+     * Where to run this child. `auto` (the default) means a panel whenever this parent has a
+     * presentation host, and the background otherwise; the Task tool pins `background` because a
+     * Task is settled by its parent and never handed to a human. This is not a model-facing
+     * parameter: `spawn_agent` always spawns with `auto`.
+     */
+    readonly presentation?: Presentation | "auto";
+    /** Optional child session title; the child branch prefixes it with the subagent marker. */
+    readonly title?: string;
+    /**
+     * Optional session or agent to fork context from (e.g. 'parent', or a subagent id like 'agent-1').
+     * Thinking blocks are stripped and context is compacted if pi-ext-memory is active.
+     */
+    readonly forkFrom?: string;
+}
+/** True when a manager call returned a structured failure instead of a value. */
+export declare function isOperationError(value: unknown): value is OperationError;
 /** Child bridge tool name; agent tool policy must never remove it. */
 export declare const CONTACT_PARENT_TOOL_NAME: "contact_parent";
 /** Environment contract between a parent launch and the child branch of this extension. */
@@ -179,14 +208,15 @@ export declare const BRIDGE_ENVIRONMENT_KEYS: {
 };
 /** Non-secret agent label for the child TUI identity line. Not part of handshake. */
 export declare const CHILD_AGENT_ENV_KEY: "PI_SUBAGENTS_AGENT";
+/** Session title requested at spawn; empty means the child derives one. Not part of handshake. */
+export declare const CHILD_TITLE_ENV_KEY: "PI_SUBAGENTS_TITLE";
 /** Bound Pi session id for the child branch. Not part of the runner handshake. */
 export declare const CHILD_SESSION_ENV_KEY: "PI_SUBAGENTS_SESSION_ID";
 /** Pi session ids reach argv and file names, so they must stay in Pi's accepted alphabet. */
 export declare function isSessionId(value: unknown): value is string;
 export declare function isThinkingLevel(value: unknown): value is ThinkingLevel;
 export declare function isSubagentState(value: unknown): value is SubagentState;
-export declare function isExecutionMode(value: unknown): value is ExecutionMode;
+export declare function isPresentation(value: unknown): value is Presentation;
 export declare function isSubagentIntent(value: unknown): value is SubagentIntent;
 export declare function isPersistenceState(value: unknown): value is PersistenceState;
 export declare function isLaunchValueSource(value: unknown): value is LaunchValueSource;
-export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/domain.js

@@ -1,5 +1,56 @@
+import { isRecord } from "@hheei/pi-ext-core";
 export const PROTOCOL_VERSION = 1;
 export const REGISTRY_VERSION = 1;
+export function normalizeSubagentState(value) {
+    if (typeof value !== "string")
+        return undefined;
+    switch (value) {
+        case "running":
+        case "starting":
+        case "idle":
+            return "running";
+        case "done":
+            return "done";
+        case "blocked":
+            return "blocked";
+        case "error":
+        case "failed":
+        case "stopped":
+            return "error";
+        default:
+            return undefined;
+    }
+}
+export function toVisualSubagentState(state, interrupted) {
+    if (state === "error")
+        return "error";
+    if (state === "blocked")
+        return "blocked";
+    if (interrupted !== undefined && state !== "done")
+        return "blocked";
+    return state;
+}
+export const VISUAL_SUBAGENT_GLYPH = {
+    running: "󰪠",
+    done: "󰄴",
+    blocked: "󰀪",
+    error: "󰅚",
+};
+export const VISUAL_SUBAGENT_TONE = {
+    running: "accent",
+    done: "success",
+    blocked: "warning",
+    error: "error",
+};
+export const SUBAGENT_GLYPH = VISUAL_SUBAGENT_GLYPH;
+export const SUBAGENT_TONE = VISUAL_SUBAGENT_TONE;
+/** True when a manager call returned a structured failure instead of a value. */
+export function isOperationError(value) {
+    return (isRecord(value) &&
+        typeof value.operation === "string" &&
+        typeof value.reason === "string" &&
+        Array.isArray(value.sideEffects));
+}
 /** Child bridge tool name; agent tool policy must never remove it. */
 export const CONTACT_PARENT_TOOL_NAME = "contact_parent";
 /** Environment contract between a parent launch and the child branch of this extension. */
@@ -12,6 +63,8 @@ export const BRIDGE_ENVIRONMENT_KEYS = {
 };
 /** Non-secret agent label for the child TUI identity line. Not part of handshake. */
 export const CHILD_AGENT_ENV_KEY = "PI_SUBAGENTS_AGENT";
+/** Session title requested at spawn; empty means the child derives one. Not part of handshake. */
+export const CHILD_TITLE_ENV_KEY = "PI_SUBAGENTS_TITLE";
 /** Bound Pi session id for the child branch. Not part of the runner handshake. */
 export const CHILD_SESSION_ENV_KEY = "PI_SUBAGENTS_SESSION_ID";
 const SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/;
@@ -32,19 +85,18 @@ export function isThinkingLevel(value) {
     return typeof value === "string" && THINKING_LEVELS[value] === true;
 }
 const SUBAGENT_STATES = {
-    starting: true,
     running: true,
-    idle: true,
     done: true,
-    stopped: true,
-    failed: true,
+    blocked: true,
+    error: true,
 };
 export function isSubagentState(value) {
-    return typeof value === "string" && SUBAGENT_STATES[value] === true;
+    return (typeof value === "string" &&
+        (SUBAGENT_STATES[value] === true || normalizeSubagentState(value) !== undefined));
 }
-const EXECUTION_MODES = { rpc: true, tui: true };
-export function isExecutionMode(value) {
-    return typeof value === "string" && EXECUTION_MODES[value] === true;
+const PRESENTATIONS = { panel: true, background: true };
+export function isPresentation(value) {
+    return typeof value === "string" && PRESENTATIONS[value] === true;
 }
 const SUBAGENT_INTENTS = { active: true, stopped: true };
 export function isSubagentIntent(value) {
@@ -58,6 +110,3 @@ const LAUNCH_VALUE_SOURCES = { agent: true, parent: true };
 export function isLaunchValueSource(value) {
     return typeof value === "string" && LAUNCH_VALUE_SOURCES[value] === true;
 }
-export function isRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

package/dist/extension.d.ts

@@ -1,2 +1,27 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
+import { type BackgroundDelivery } from "@hheei/pi-ext-core";
+import type { SkillCatalogEntry } from "./agent-resolver.js";
+import { type ParentChannel } from "./manager.js";
+/** Parent channel plus the teardown its owner must call. */
+export interface ParentChannelHandle extends ParentChannel {
+    /** Unregisters delivery and appends anything still held without waking the parent. */
+    dispose(): void;
+}
+/**
+ * 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 declare function createParentChannel(pi: Pick<ExtensionAPI, "sendMessage" | "on">, deps: {
+    readonly isIdle: () => boolean;
+    readonly delivery: BackgroundDelivery;
+    readonly signal?: AbortSignal;
+}): ParentChannelHandle;
+/**
+ * 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 declare function skillCatalogFromLoaded(skills: readonly Skill[]): readonly SkillCatalogEntry[];
 export default function piSubagentsExtension(pi: ExtensionAPI): void;