@hheei/pi-subagents 0.1.2 → 0.2.2

package/dist/manager.d.ts

@@ -1,7 +1,19 @@
-import type { EffectiveLaunchConfig, OperationError, PublicSubagent, SendMode, SpawnSubagentInput, SubagentRecord, SubagentState } from "./domain.js";
-import type { HostKind, HostSelection } from "./host-adapter.js";
+import { type TaskRegistry } from "@hheei/pi-ext-core";
+import type { ChildRuntime } from "./child-process.js";
+import type { EffectiveLaunchConfig, OperationError, Presentation, PublicSubagent, SendMode, SpawnSubagentInput, SubagentRecord, SubagentState } from "./domain.js";
+import type { HostAttachment } from "./host-adapter.js";
+import { type BridgeOperation } from "./protocol.js";
 import type { SubagentRegistry } from "./registry.js";
-import type { RuntimeTokenStore } from "./runtime.js";
+import type { LaunchOutcome, RuntimeTokenStore } from "./runtime.js";
+/**
+ * How long an idle child keeps its runtime. A background child holds a whole Pi process and its
+ * session lock, so an idle one is reclaimed after this window and a later `send_agent` starts it
+ * again from the same session.
+ */
+export declare const SUBAGENT_IDLE_TIMEOUT_MS = 15000;
+export declare const SUBAGENT_SETTLED_CLOSE_TIMEOUT_MS = 15000;
+/** How long stop waits for an adopted child's bridge to go away before calling the exit unconfirmed. */
+export declare const SUBAGENT_EXIT_WAIT_MS = 2000;
 export interface ParentChannelReport {
     readonly parentSessionId: string;
     readonly childId: string;
@@ -14,34 +26,21 @@ export interface ParentChannelReport {
 export interface ParentChannel {
     deliver(report: ParentChannelReport): Promise<void>;
 }
-export interface RunnerLike {
-    readonly connected: boolean;
-    request(operation: "prompt" | "steer" | "follow_up" | "get_state" | "get_entries" | "shutdown" | "pause" | "cancel_pause" | "close_writer" | "start_rpc", payload?: unknown, options?: {
+/**
+ * The parent side of the bridge, as the manager needs it: one connection per child, requests the
+ * parent may send, and the events and connection transitions the child reports. Liveness is a
+ * connection: no other channel can say whether this child is still running.
+ */
+export interface ChildBridgeTransport {
+    isConnected(childId: string): boolean;
+    /** Ends a child's connection from this side, for a process that stopped being this child. */
+    disconnect(childId: string): void;
+    request(childId: string, operation: BridgeOperation, payload?: unknown, options?: {
         readonly timeoutMs?: number;
         readonly signal?: AbortSignal;
     }): Promise<unknown>;
-    close(): void;
-    onEvent(listener: (event: unknown) => void): () => void;
-}
-export interface AttachHost {
-    select(preferredHost?: HostKind): Promise<HostSelection>;
-}
-export interface AttachOptions {
-    readonly preferredHost?: HostKind;
-    readonly signal?: AbortSignal;
-}
-export interface AttachResult {
-    readonly child: PublicSubagent;
-    readonly host: HostKind;
-    readonly attachmentId: string;
-}
-export type DetachOrigin = "tui_exit" | "tui_crash" | "session_switch" | "manual";
-export interface DetachOptions {
-    readonly origin: DetachOrigin;
-    /** Close the host pane. False when session B still owns that TUI process. */
-    readonly closeHost?: boolean;
-    /** Operation label reported in failures; defaults to "detach". */
-    readonly operation?: string;
+    onEvent(listener: (childId: string, event: unknown) => void): () => void;
+    onConnectionChange(listener: (childId: string, connected: boolean) => void): () => void;
 }
 export interface ManagerDependencies {
     readonly parentSessionId: string;
@@ -51,17 +50,40 @@ export interface ManagerDependencies {
         readonly parentSessionId: string;
         readonly task: string;
         readonly launchConfig: EffectiveLaunchConfig;
+        readonly presentation: Presentation;
     }) => Promise<SubagentRecord>;
-    readonly launch: (record: SubagentRecord) => Promise<RunnerLike>;
-    readonly connect?: (record: SubagentRecord) => Promise<RunnerLike>;
+    readonly bridge: ChildBridgeTransport;
+    /** Starts a background runtime for this record and resolves once the child has connected. */
+    readonly launch: (record: SubagentRecord) => Promise<LaunchOutcome<ChildRuntime>>;
+    /**
+     * Presentation hosts of this parent. Absent when no panel host is available, in which case every
+     * child runs in the background; `hostReason` is what the spawn result tells the caller, so a
+     * fallback is visible instead of silent.
+     */
+    readonly presentation?: PresentationDeps;
+    /** Waits for an already-running runtime to reconnect; false when it does not. */
+    readonly connect: (record: SubagentRecord) => Promise<boolean>;
     readonly deadlineMs?: number;
-    readonly watchIntervalMs?: number;
+    readonly settledCloseTimeoutMs?: number;
+    readonly idleTimeoutMs?: number;
+    readonly failedPanelCloseTimeoutMs?: number;
     readonly channel?: ParentChannel;
-    readonly attachHost?: AttachHost;
     readonly tokens?: RuntimeTokenStore;
 }
+/**
+ * How this parent presents children, as the manager needs it: something that opens a panel for a
+ * record and resolves once the child has connected, plus the reason for that state of affairs,
+ * which is said out loud when a child falls back to the background.
+ */
+export interface PresentationDeps {
+    readonly reason: string;
+    /** Absent when this parent has no presentation host, which makes every child a background one. */
+    readonly openPanel?: (record: SubagentRecord) => Promise<LaunchOutcome<HostAttachment>>;
+}
 export interface SpawnResult {
     readonly child: PublicSubagent;
+    /** Set when the child did not run where it would have by default. */
+    readonly note?: string;
 }
 export interface RecoveryResult {
     readonly recovered: readonly string[];
@@ -70,32 +92,54 @@ export interface RecoveryResult {
         readonly reason: string;
     }[];
 }
+/**
+ * Extracts the trailing text of the most recent assistant message in session entries.
+ * Used to automatically capture a subagent's final output without requiring a tool call.
+ */
+export declare function extractLastAssistantText(entries: readonly unknown[]): string | undefined;
 export declare class SubagentManager {
     #private;
+    bindTaskRegistry(registry: TaskRegistry): () => void;
     constructor(deps: ManagerDependencies);
+    /**
+     * Observes the raw bridge events of every child. A Task producer needs the child's
+     * `task_result` and settle events without also owning the bridge connection.
+     */
+    onChildEvent(listener: (childId: string, event: unknown) => void): () => void;
     /** Presentation-only: widget and similar projections re-read list() after this. */
     onChange(listener: () => void): () => void;
-    /** Reattaches active persisted children without replaying any historical input. */
+    dispose(): void;
+    /**
+     * Releases this process's local view of its children. Child processes are deliberately left
+     * alone: a background child is held by its stdin pipe, so it ends when this Pi process ends and
+     * not when extensions are reloaded.
+     */
+    closeLocalConnections(): void;
+    /** Reads a child's session entries; exposed for Task completion inspection. */
+    getEntries(id: string): Promise<readonly unknown[] | undefined>;
+    /**
+     * Adopts the children that are still running. Nothing is launched here: a child that survived a
+     * parent restart reconnects its bridge by itself, and a child that did not is simply not live
+     * until a later send starts it from its recorded session.
+     */
     recover(): Promise<RecoveryResult>;
     spawn(input: SpawnSubagentInput): Promise<SpawnResult | OperationError>;
-    send(id: string, message: string, mode?: SendMode, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
+    send(id: string, rawMessage: string, mode?: SendMode, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
     get(id: string): Promise<PublicSubagent | OperationError>;
     list(): Promise<readonly PublicSubagent[]>;
-    stop(id: string, signal?: AbortSignal): Promise<OperationError | PublicSubagent>;
-    ownsHostAttachment(identity: {
-        readonly host: HostKind;
-        readonly attachmentId: string;
-    }): boolean;
-    attach(id: string, options?: AttachOptions): Promise<AttachResult | OperationError>;
-    restoreRpc(id: string): Promise<OperationError | PublicSubagent>;
-    detach(id: string, options: DetachOptions): Promise<OperationError | PublicSubagent>;
-    inspectHost(id: string): Promise<OperationError | PublicSubagent | {
-        readonly alive: boolean;
-        readonly known: boolean;
-        readonly detail: string;
-    }>;
-    contactParent(id: string, reason: string, message: string): Promise<OperationError | {
+    /** Child startup and runs count until Pi settles, including post-agent_end continuation. */
+    get activeCount(): number;
+    stop(id: string): Promise<OperationError | PublicSubagent>;
+    contactParent(id: string, reason: string, message: string, knownRecord?: SubagentRecord): Promise<OperationError | {
         readonly delivered: true;
     }>;
-    closeLocalConnections(): void;
+    /**
+     * Handles a request a child sent to its parent. The two child-initiated operations are the
+     * child's report channel and its Task result, and both are answered here so the child learns
+     * whether the parent accepted them.
+     */
+    handleChildRequest(childId: string, operation: string, payload: unknown): Promise<unknown>;
+    /** Applies a bridge event to this child's record and notifies the raw child-event listeners. */
+    handleEvent(childId: string, event: unknown): void;
+    handleConnectionChange(childId: string, connected: boolean): void;
 }