@ian-pascoe/pi-minimal-subagents 0.1.0

package/src/minimal-subagents-shutdown.ts

@@ -0,0 +1,29 @@
+interface MinimalSubagentsShutdownCoordinator {
+  waitForSettledOperations(): Promise<void>;
+  shutdownAfterSettling(): Promise<void>;
+  shutdown(): Promise<void>;
+}
+
+interface MinimalSubagentsRootIdleGate {
+  isRootIdle(): boolean;
+  waitForRootIdle(): Promise<void>;
+}
+
+/** Drain active child and root work before reload while preserving canceling shutdown elsewhere. */
+export async function shutdownMinimalSubagentsSession(
+  reason: string,
+  coordinator: MinimalSubagentsShutdownCoordinator,
+  rootIdleGate: MinimalSubagentsRootIdleGate,
+): Promise<void> {
+  if (reason !== "reload") {
+    await coordinator.shutdown();
+    return;
+  }
+
+  while (true) {
+    await coordinator.waitForSettledOperations();
+    if (rootIdleGate.isRootIdle()) break;
+    await rootIdleGate.waitForRootIdle();
+  }
+  await coordinator.shutdownAfterSettling();
+}

package/src/minimal-subagents-tool-schemas.ts

@@ -0,0 +1,66 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type TSchema } from "typebox";
+import { THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
+
+const SessionContextSchema = StringEnum(["inherit", "compact", "omit"] as const);
+const ProjectContextSchema = StringEnum(["inherit", "omit"] as const);
+const DelegationSchema = StringEnum(["none", "fanout"] as const);
+const ThinkingLevelSchema = StringEnum(THINKING_LEVELS);
+const ToolSelectionSchema = Type.Union([
+  StringEnum(["none", "read", "modify"] as const),
+  Type.Array(Type.String({ minLength: 1 }), { uniqueItems: true }),
+]);
+const FRIENDLY_AGENT_ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$";
+const CANONICAL_AGENT_ID_PATTERN =
+  "^(?:root\\.)?[A-Za-z0-9][A-Za-z0-9_-]{0,63}(?:\\.[A-Za-z0-9][A-Za-z0-9_-]{0,63})*$";
+
+function canonicalAgentIdSchema(description?: string) {
+  return Type.String({ minLength: 1, pattern: CANONICAL_AGENT_ID_PATTERN, description });
+}
+
+/** Build all six strict TypeBox schemas, including the refreshed runtime model enum. */
+export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
+  const explicitModelSchema: TSchema =
+    modelIds.length > 0 ? StringEnum(modelIds as [string, ...string[]]) : Type.Never();
+  return {
+    subagent: Type.Object({
+      task: Type.String({ minLength: 1, description: "Task for the persistent child agent" }),
+      agent_id: Type.Optional(
+        Type.String({
+          pattern: FRIENDLY_AGENT_ID_PATTERN,
+          description:
+            "Friendly peer-unique ID segment; a root child uses this segment as its canonical ID",
+        }),
+      ),
+      session_context: Type.Optional(SessionContextSchema),
+      project_context: Type.Optional(ProjectContextSchema),
+      model: Type.Optional(explicitModelSchema),
+      thinking_level: Type.Optional(ThinkingLevelSchema),
+      tools: Type.Optional(ToolSelectionSchema),
+      delegation: Type.Optional(DelegationSchema),
+    }),
+    agent_message: Type.Object({
+      agent_id: Type.Optional(
+        canonicalAgentIdSchema(
+          "Direct parent, sibling, or child canonical agent ID, or parent alias",
+        ),
+      ),
+      message: Type.String({ minLength: 1 }),
+    }),
+    subagent_wait: Type.Object({
+      agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),
+      timeout_ms: Type.Optional(Type.Integer({ minimum: 0 })),
+    }),
+    subagent_status: Type.Object({
+      agent_id: Type.Optional(canonicalAgentIdSchema("Direct child canonical agent ID")),
+    }),
+    subagent_cancel: Type.Object({
+      agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),
+      recursive: Type.Optional(Type.Boolean()),
+    }),
+    subagent_delete: Type.Object({
+      agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),
+      recursive: Type.Optional(Type.Boolean()),
+    }),
+  };
+}

package/src/minimal-subagents-tools.ts

@@ -0,0 +1,285 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  defineTool,
+  truncateHead,
+  type AgentToolResult,
+  type ExtensionContext,
+  type Theme,
+  type ToolDefinition,
+  type ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
+import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
+import {
+  renderCoordinatorToolCall,
+  renderCoordinatorToolResult,
+  type CoordinatorToolName,
+} from "./minimal-subagents-rendering.js";
+import type { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
+import type { CallerSnapshot, SpawnParameters } from "./minimal-subagents-types.js";
+
+const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
+  "agent_message",
+  "subagent_wait",
+  "subagent_status",
+]);
+
+interface CoordinatorToolDefinitionOptions {
+  coordinator: MinimalSubagentsCoordinator;
+  callerId: string;
+  allowFanoutTools?: boolean;
+  modelRoles?: readonly MinimalSubagentsModelRole[];
+  schemas: ReturnType<typeof createCoordinatorToolSchemas>;
+  captureCaller: (context: ExtensionContext) => CallerSnapshot;
+  onActivity?: () => void;
+  onAttention?: (message: string) => void;
+}
+
+function buildModelRolePromptGuidelines(
+  modelRoles: readonly MinimalSubagentsModelRole[],
+): string[] | undefined {
+  if (modelRoles.length === 0) return undefined;
+  const roleLines = modelRoles.map(
+    (role) => `  - ${role.name} → ${role.model}${role.hint ? ` — ${role.hint}` : ""}`,
+  );
+  return [
+    ["Configured model roles are guidance, not constraints:", ...roleLines].join("\n"),
+    "Choose a model based on the task. Choose thinking_level independently.",
+  ];
+}
+
+async function runCoordinatorToolActivity<T>(
+  options: CoordinatorToolDefinitionOptions,
+  operation: () => Promise<T> | T,
+): Promise<T> {
+  try {
+    return await operation();
+  } finally {
+    options.onActivity?.();
+  }
+}
+
+function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
+  return {
+    renderCall: (args: Record<string, unknown>, theme: Theme) =>
+      renderCoordinatorToolCall(toolName, args, theme),
+    renderResult: (
+      result: AgentToolResult<unknown>,
+      renderOptions: ToolRenderResultOptions,
+      theme: Theme,
+      context: { args: Record<string, unknown>; isError: boolean },
+    ) =>
+      renderCoordinatorToolResult(
+        toolName,
+        result,
+        renderOptions,
+        theme,
+        context.args,
+        context.isError,
+      ),
+  };
+}
+
+function structuredToolResult(result: unknown) {
+  const json = JSON.stringify(result, null, 2);
+  const truncated = truncateHead(json, {
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxLines: DEFAULT_MAX_LINES,
+  });
+  return {
+    content: [{ type: "text" as const, text: truncated.content }],
+    details: result,
+  };
+}
+
+function failedStructuredOperation(prefix: string, result: unknown): never {
+  const json = JSON.stringify(result);
+  const truncated = truncateHead(json, {
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxLines: DEFAULT_MAX_LINES,
+  });
+  throw new Error(`${prefix}: ${truncated.content}`);
+}
+
+function callerSourceTurnId(
+  coordinator: MinimalSubagentsCoordinator,
+  callerId: string,
+  toolCallId: string,
+): string {
+  if (callerId === "root") return `root:${toolCallId}`;
+  const status = coordinator.inspectStatus(callerId);
+  return "agent" in status && status.agent.active_turn_id
+    ? status.agent.active_turn_id
+    : `${callerId}:${toolCallId}`;
+}
+
+/** Create caller-bound definitions for the six coordinator tools shared by root and children. */
+export function createCoordinatorToolDefinitions(
+  options: CoordinatorToolDefinitionOptions,
+): ToolDefinition[] {
+  const modelRolePromptGuidelines = buildModelRolePromptGuidelines(options.modelRoles ?? []);
+  const spawnTool = defineTool({
+    name: "subagent",
+    label: "Subagent",
+    description:
+      "Create a persistent nested agent asynchronously. Returns its canonical agent ID and active turn ID immediately. Root-child IDs omit the root prefix; nested IDs retain the parent path.",
+    promptSnippet: "Spawn a persistent child with a prefix-free root-child ID",
+    promptGuidelines: modelRolePromptGuidelines,
+    parameters: options.schemas.subagent,
+    async execute(_toolCallId, parameters, _signal, _onUpdate, context) {
+      return runCoordinatorToolActivity(options, async () => {
+        const result = await options.coordinator.spawn(
+          options.callerId,
+          parameters as SpawnParameters,
+          options.captureCaller(context),
+        );
+        const status = options.coordinator.inspectStatus(result.agent_id);
+        return {
+          ...structuredToolResult(result),
+          details: {
+            ...result,
+            ...(status && "agent" in status ? { agent: status.agent } : {}),
+          },
+        };
+      });
+    },
+    ...createCoordinatorToolRendering("subagent"),
+  });
+
+  const messageTool = defineTool({
+    name: "agent_message",
+    label: "Agent Message",
+    description:
+      "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child when the recipient must act before the caller's turn finishes.",
+    promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
+    parameters: options.schemas.agent_message,
+    async execute(toolCallId, parameters) {
+      return runCoordinatorToolActivity(options, async () => {
+        const result = await options.coordinator.sendAgentMessage(
+          options.callerId,
+          {
+            agent_id: parameters.agent_id,
+            message: parameters.message,
+          },
+          callerSourceTurnId(options.coordinator, options.callerId, toolCallId),
+        );
+        return structuredToolResult(result);
+      });
+    },
+    ...createCoordinatorToolRendering("agent_message"),
+  });
+
+  const waitTool = defineTool({
+    name: "subagent_wait",
+    label: "Subagent Wait",
+    description:
+      "Wait for one direct child's exact active turn, or return its latest settled turn immediately. Timeout never cancels the child.",
+    promptSnippet: "Wait for one direct child's exact turn",
+    parameters: options.schemas.subagent_wait,
+    async execute(_toolCallId, parameters, signal, onUpdate) {
+      const startedAt = Date.now();
+      const updateWaitingResult = () =>
+        onUpdate?.({
+          content: [{ type: "text", text: `Waiting for ${parameters.agent_id}` }],
+          details: {
+            agent_id: parameters.agent_id,
+            status: "waiting",
+            elapsed_ms: Date.now() - startedAt,
+          },
+        });
+      updateWaitingResult();
+      const waitingInterval = setInterval(updateWaitingResult, 1_000);
+      waitingInterval.unref?.();
+      try {
+        return await runCoordinatorToolActivity(options, async () => {
+          const result = await options.coordinator.wait(
+            options.callerId,
+            parameters.agent_id,
+            parameters.timeout_ms,
+            signal,
+          );
+          return {
+            ...structuredToolResult(result),
+            details: {
+              ...result,
+              source_agent_id: result.agent_id,
+              source_turn_id: result.turn_id,
+            },
+          };
+        });
+      } finally {
+        clearInterval(waitingInterval);
+      }
+    },
+    ...createCoordinatorToolRendering("subagent_wait"),
+  });
+
+  const statusTool = defineTool({
+    name: "subagent_status",
+    label: "Subagent Status",
+    description:
+      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, and dependencies.",
+    promptSnippet: "Inspect direct child state",
+    parameters: options.schemas.subagent_status,
+    async execute(_toolCallId, parameters) {
+      return runCoordinatorToolActivity(options, () =>
+        structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
+      );
+    },
+    ...createCoordinatorToolRendering("subagent_status"),
+  });
+
+  const cancelTool = defineTool({
+    name: "subagent_cancel",
+    label: "Subagent Cancel",
+    description:
+      "Abort active work for one direct child while preserving sessions for later continuation. Recursive cancellation includes its subtree and defaults to true.",
+    promptSnippet: "Cancel active subagent turns without deleting sessions",
+    parameters: options.schemas.subagent_cancel,
+    async execute(_toolCallId, parameters) {
+      return runCoordinatorToolActivity(options, async () =>
+        structuredToolResult(
+          await options.coordinator.cancel(
+            options.callerId,
+            parameters.agent_id,
+            parameters.recursive ?? true,
+          ),
+        ),
+      );
+    },
+    ...createCoordinatorToolRendering("subagent_cancel"),
+  });
+
+  const deleteTool = defineTool({
+    name: "subagent_delete",
+    label: "Subagent Delete",
+    description:
+      "Delete one direct child's persistent session and retain durable ID tombstones. Recursive deletion includes its subtree and defaults to true.",
+    promptSnippet: "Delete subagent sessions and tombstone their IDs",
+    parameters: options.schemas.subagent_delete,
+    async execute(_toolCallId, parameters) {
+      return runCoordinatorToolActivity(options, async () => {
+        const result = await options.coordinator.delete(
+          options.callerId,
+          parameters.agent_id,
+          parameters.recursive ?? true,
+        );
+        if (result.failures.length > 0) {
+          options.onAttention?.(
+            `Minimal subagents deletion partially failed for ${parameters.agent_id}`,
+          );
+          failedStructuredOperation("Minimal subagents deletion partially failed", result);
+        }
+        return structuredToolResult(result);
+      });
+    },
+    ...createCoordinatorToolRendering("subagent_delete"),
+  });
+
+  const coordinatorTools = [spawnTool, messageTool, waitTool, statusTool, cancelTool, deleteTool];
+  const allowFanoutTools = options.allowFanoutTools ?? options.callerId === "root";
+  return allowFanoutTools
+    ? coordinatorTools
+    : coordinatorTools.filter((tool) => ORDINARY_CHILD_COORDINATOR_TOOL_NAMES.has(tool.name));
+}

package/src/minimal-subagents-types.ts

@@ -0,0 +1,305 @@
+import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Usage } from "@earendil-works/pi-ai";
+
+/** Canonical path-like identity for one persistent subagent. */
+export type AgentId = string & { readonly __agentId: unique symbol };
+
+/** Stable identity for one prompt and its complete assistant/tool loop. */
+export type TurnId = string & { readonly __turnId: unique symbol };
+
+/** Controls how much committed caller conversation enters a new child session. */
+export type SessionContextMode = "inherit" | "compact" | "omit";
+/** Controls whether child resource discovery includes project instructions, skills, and prompts. */
+export type ProjectContextMode = "inherit" | "omit";
+/** Selects inherited, bundled, absent, or explicitly named ordinary child tools. */
+export type ToolSelection = "none" | "read" | "modify" | string[];
+/** Controls whether a child must work directly or may explicitly fan out one bounded level. */
+export type DelegationMode = "none" | "fanout";
+/** Reports whether a persistent agent currently owns an active turn. */
+export type AgentState = "running" | "idle";
+/** Reports whether saved launch dependencies can recreate an agent runtime. */
+export type AgentAvailability = "available" | "unavailable";
+/** Classifies active and terminal persistent subagent turn outcomes. */
+export type TurnStatus = "running" | "completed" | "failed" | "cancelled" | "interrupted";
+
+/** Defines the validated launch contract accepted by the subagent tool. */
+export interface SpawnParameters {
+  task: string;
+  agent_id?: string;
+  session_context?: SessionContextMode;
+  project_context?: ProjectContextMode;
+  model?: string;
+  thinking_level?: ThinkingLevel;
+  tools?: ToolSelection;
+  delegation?: DelegationMode;
+}
+
+/** Returns persistent agent and turn identities immediately after launch scheduling. */
+export interface SpawnResult {
+  agent_id: string;
+  turn_id: string;
+  status: "running";
+}
+
+/** Retains one keyed terminal turn result for waits and durable delivery recovery. */
+export interface TurnResult {
+  agent_id: string;
+  turn_id: string;
+  status: Exclude<TurnStatus, "running">;
+  output: string;
+  error?: string;
+  usage?: Usage;
+  elapsed_ms?: number;
+}
+
+/** Reports delivery of one direct message to an authorized adjacent agent. */
+export interface AgentMessageResult {
+  agent_id: string;
+  delivered: boolean;
+  error?: string;
+}
+
+/** Provides bounded hierarchy and usage data for one persistent agent. */
+export interface AgentSummary {
+  agent_id: string;
+  parent_id: string;
+  state: AgentState;
+  availability: AgentAvailability;
+  active_turn_id?: string;
+  latest_turn?: Pick<TurnResult, "turn_id" | "status">;
+  model: string;
+  thinking_level: ThinkingLevel;
+  tools: string[];
+  elapsed_ms?: number;
+  latest_activity?: string;
+  latest_activity_at?: string;
+  task?: string;
+  child_count: number;
+  children: AgentSummary[];
+}
+
+/** Provides bounded recent child conversation text for detailed status. */
+export interface RecentAgentMessage {
+  source_agent_id: string;
+  turn_id: string;
+  content: string;
+}
+
+/** Extends summary status with launch, dependency, and recent-message diagnostics. */
+export interface AgentDetail extends AgentSummary {
+  session_file?: string;
+  launch_contract: Record<string, unknown>;
+  capability_ceiling: string[];
+  spawn_entry_id: string;
+  recent_messages: RecentAgentMessage[];
+  latest_result?: TurnResult;
+  missing_dependencies: string[];
+  unavailable_reason?: string;
+  usage?: Usage;
+}
+
+/** Returns either caller-owned direct children or one authorized direct-child detail. */
+export type StatusResult = { parent_id: string; agents: AgentSummary[] } | { agent: AgentDetail };
+
+/** Supplies the complete root hierarchy to trusted internal UI and activity projections. */
+export type HierarchyStatusResult =
+  | { root_id: "root"; agents: AgentSummary[] }
+  | { agent: AgentDetail };
+
+/** Reports active turns cancelled without deleting persistent sessions. */
+export interface CancelResult {
+  agent_id: string;
+  recursive: boolean;
+  affected_agent_ids: string[];
+  cancelled_turn_ids: string[];
+}
+
+/** Reports post-order deletion successes, tombstones, trash paths, and partial failures. */
+export interface DeleteResult {
+  agent_id: string;
+  recursive: boolean;
+  deleted_agent_ids: string[];
+  tombstoned_agent_ids: string[];
+  trashed_session_files: string[];
+  failures: Array<{ agent_id: string; error: string }>;
+}
+
+/** Persists immutable context, model, thinking, and ordinary-tool launch choices. */
+export interface LaunchContract {
+  session_context: SessionContextMode;
+  project_context: ProjectContextMode;
+  model: string;
+  thinking_level: ThinkingLevel;
+  tools: ToolSelection | undefined;
+  ordinary_tools: string[];
+  delegation?: DelegationMode;
+}
+
+/** Captures committed caller context and its capability ceiling at spawn time. */
+export interface CallerSnapshot {
+  messages: AgentMessage[];
+  model: string;
+  thinkingLevel: ThinkingLevel;
+  ordinaryTools: string[];
+  capabilityCeiling: string[];
+  availableTools: string[];
+  spawnEntryId: string;
+}
+
+/** Normalizes Pi child runtime completion before persistent turn settlement. */
+export interface RuntimeTurnOutcome {
+  status: "completed" | "failed" | "cancelled";
+  output: string;
+  error?: string;
+  usage?: Usage;
+}
+
+/** Carries keyed conversation-plane content between persistent agent sessions. */
+export interface CoordinatorMessage {
+  customType: "minimal-subagents.message" | "minimal-subagents.result";
+  content: string;
+  details: {
+    source_agent_id: string;
+    destination_agent_id?: string;
+    source_turn_id: string;
+    status?: TurnStatus;
+    elapsed_ms?: number;
+    usage?: Usage;
+  };
+}
+
+/** Process-local adapter around one SDK-created Pi child session. */
+export interface ChildAgentRuntime {
+  readonly sessionFile: string;
+  readonly sessionId: string;
+  readonly isRunning: boolean;
+  runPrompt(
+    task: string,
+    compact: boolean,
+    callerModel: string,
+    callerThinkingLevel: ThinkingLevel,
+  ): Promise<RuntimeTurnOutcome>;
+  runMessage(message: CoordinatorMessage): Promise<RuntimeTurnOutcome>;
+  /** Steer one typed coordinator message into the child session. */
+  steerCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
+  abort(): Promise<void>;
+  dispose(): void;
+  snapshotCommittedMessages(): AgentMessage[];
+  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string): boolean;
+  getUsage(): Usage | undefined;
+  cloneSession(): Promise<{ sessionFile: string; sessionId: string }>;
+}
+
+/** Identifies one writable child JSONL session owned by a coordinator root. */
+export interface PersistedSessionIdentity {
+  sessionFile: string;
+  sessionId: string;
+}
+
+/** Combines a persisted agent record with first-launch imported context. */
+export interface RuntimeCreationRequest {
+  agent: PersistedAgent;
+  importedMessages: AgentMessage[];
+}
+
+/** Pi-specific session operations injected into the pure coordinator. */
+export interface AgentSessionFactory {
+  createIdentity(agent: PersistedAgent, importedMessages: AgentMessage[]): PersistedSessionIdentity;
+  createRuntime(request: RuntimeCreationRequest): Promise<ChildAgentRuntime>;
+  restoreRuntime(agent: PersistedAgent): Promise<ChildAgentRuntime>;
+  resolveLaunchMissingDependencies(agent: PersistedAgent): Promise<string[]>;
+  resolveRestorationMissingDependencies(agent: PersistedAgent): Promise<string[]>;
+  resolveThinkingLevel(modelId: string, requested: ThinkingLevel): ThinkingLevel;
+  modelSupportsImages(modelId: string): boolean;
+  cloneSession(agent: PersistedAgent): Promise<PersistedSessionIdentity>;
+  trashSessionFile(sessionFile: string): Promise<void>;
+}
+
+/** Abstracts root message delivery and durable delivery-evidence lookup. */
+export interface RootConversationEndpoint {
+  /** Steer one typed coordinator message into the root conversation. */
+  steerCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
+  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string): boolean;
+}
+
+/** Stores root-owned agent identity, launch contract, availability, and latest activity. */
+export interface PersistedAgent {
+  agent_id: string;
+  friendly_id: string;
+  parent_id: string;
+  created_at: string;
+  task?: string;
+  latest_activity_at?: string;
+  spawn_entry_id: string;
+  session_file?: string;
+  session_id?: string;
+  clone_error?: string;
+  launch_contract: LaunchContract;
+  capability_ceiling: string[];
+  active_turn_id?: string;
+  active_turn_started_at?: string;
+  latest_result?: TurnResult;
+  availability: AgentAvailability;
+  missing_dependencies: string[];
+  unavailable_reason?: string;
+  recent_messages: RecentAgentMessage[];
+  deleted?: boolean;
+}
+
+/** Records whether successful output was observed through wait or automatic messaging. */
+export type DeliveryPath = "wait" | "message";
+
+/** Stores a keyed successful result until destination evidence settles delivery. */
+export interface PersistedDelivery {
+  source_agent_id: string;
+  source_turn_id: string;
+  destination_agent_id: string;
+  path: DeliveryPath;
+  settled: boolean;
+  result?: TurnResult;
+  error?: string;
+}
+
+/** Checkpoints all live agents, deletion tombstones, and delivery records for one root. */
+export interface RegistrySnapshot {
+  agents: PersistedAgent[];
+  tombstones: string[];
+  deliveries: PersistedDelivery[];
+}
+
+/** Clones a registry snapshot while recording the source root session file. */
+export interface ForkSnapshot extends RegistrySnapshot {
+  source_root_session_file: string;
+}
+
+/** Appends root-owned registry events to the active root conversation branch. */
+export interface RegistryWriter {
+  readonly rootSessionId: string;
+  append(event: import("./minimal-subagents-registry.js").RegistryEventV1): void;
+}
+
+/** Describes concise lifecycle notices surfaced through Pi UI notifications. */
+export interface CoordinatorNotification {
+  type:
+    | "spawn"
+    | "completion"
+    | "failure"
+    | "cancellation"
+    | "interruption"
+    | "restoration"
+    | "unavailable"
+    | "fork-clone-failure";
+  agentId: string;
+  message: string;
+}
+
+/** Injects sessions, root delivery, registry, delegation depth, delivery grace, and notifications. */
+export interface CoordinatorDependencies {
+  registry: RegistryWriter;
+  sessions: AgentSessionFactory;
+  root: RootConversationEndpoint;
+  maxSubagentDepth?: number;
+  now?: () => Date;
+  automaticDeliveryGraceMs?: number;
+  notify?: (notification: CoordinatorNotification) => void;
+}