@ian-pascoe/pi-minimal-subagents 0.1.1 → 0.2.1

package/src/minimal-subagents-shutdown.ts

@@ -21,9 +21,9 @@ export async function shutdownMinimalSubagentsSession(
   }
 
   while (true) {
+    if (!rootIdleGate.isRootIdle()) await rootIdleGate.waitForRootIdle();
     await coordinator.waitForSettledOperations();
     if (rootIdleGate.isRootIdle()) break;
-    await rootIdleGate.waitForRootIdle();
   }
   await coordinator.shutdownAfterSettling();
 }

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

@@ -1,15 +1,25 @@
 import { StringEnum } from "@earendil-works/pi-ai";
-import { Type, type TSchema } from "typebox";
+import { Type } 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 ToolSelectionSchema = Type.Union(
+  [
+    StringEnum(["none", "read", "modify"] as const),
+    Type.Array(Type.String({ minLength: 1 }), {
+      uniqueItems: true,
+      description:
+        "Exact ordinary tool names. Coordinator tools are injected separately and must not appear here. Arrays are not bundle names; use the string preset `read` or `modify` for bundled capabilities.",
+    }),
+  ],
+  {
+    description:
+      'Use the string preset "read" for read, grep, find, and ls; use "modify" for the read bundle plus bash, edit, and write. An array grants exactly those named tools (ordinary tools only); coordinator tools are injected separately.',
+  },
+);
 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})*$";
@@ -20,8 +30,9 @@ function canonicalAgentIdSchema(description?: string) {
 
 /** 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();
+  const [firstModelId, ...remainingModelIds] = modelIds;
+  const explicitModelSchema =
+    firstModelId === undefined ? Type.Never() : StringEnum([firstModelId, ...remainingModelIds]);
   return {
     subagent: Type.Object({
       task: Type.String({ minLength: 1, description: "Task for the persistent child agent" }),
@@ -49,6 +60,9 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
     }),
     subagent_wait: Type.Object({
       agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),
+      turn_id: Type.Optional(
+        Type.String({ minLength: 1, description: "Exact retained child turn ID" }),
+      ),
       timeout_ms: Type.Optional(Type.Integer({ minimum: 0 })),
     }),
     subagent_status: Type.Object({

package/src/minimal-subagents-tools.ts

@@ -16,8 +16,17 @@ import {
   renderCoordinatorToolResult,
   type CoordinatorToolName,
 } from "./minimal-subagents-rendering.js";
+import type { CoordinatorToolCallInput } from "./minimal-subagents-render-contract.js";
 import type { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
-import type { CallerSnapshot, SpawnParameters } from "./minimal-subagents-types.js";
+import type {
+  AgentMessageResult,
+  CallerSnapshot,
+  CancelResult,
+  DeleteResult,
+  SpawnResult,
+  StatusResult,
+  WaitResult,
+} from "./minimal-subagents-types.js";
 
 const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
   "agent_message",
@@ -25,8 +34,15 @@ const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
   "subagent_status",
 ]);
 
-interface CoordinatorToolDefinitionOptions {
-  coordinator: MinimalSubagentsCoordinator;
+/** Coordinator operations consumed by the six public coordinator tool definitions. */
+export type CoordinatorToolOperations = Pick<
+  MinimalSubagentsCoordinator,
+  "spawn" | "inspectStatus" | "sendAgentMessage" | "wait" | "status" | "cancel" | "delete"
+>;
+
+/** Dependencies and caller policy used to create caller-bound coordinator tools. */
+export interface CoordinatorToolDefinitionOptions {
+  coordinator: CoordinatorToolOperations;
   callerId: string;
   allowFanoutTools?: boolean;
   modelRoles?: readonly MinimalSubagentsModelRole[];
@@ -61,15 +77,24 @@ async function runCoordinatorToolActivity<T>(
   }
 }
 
+type CoordinatorToolResultDetails =
+  | SpawnResult
+  | AgentMessageResult
+  | WaitResult
+  | StatusResult
+  | CancelResult
+  | DeleteResult
+  | { agent_id: string; status: "waiting"; elapsed_ms: number };
+
 function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
   return {
-    renderCall: (args: Record<string, unknown>, theme: Theme) =>
+    renderCall: (args: CoordinatorToolCallInput, theme: Theme) =>
       renderCoordinatorToolCall(toolName, args, theme),
     renderResult: (
-      result: AgentToolResult<unknown>,
+      result: AgentToolResult<CoordinatorToolResultDetails>,
       renderOptions: ToolRenderResultOptions,
       theme: Theme,
-      context: { args: Record<string, unknown>; isError: boolean },
+      context: { args: CoordinatorToolCallInput; isError: boolean },
     ) =>
       renderCoordinatorToolResult(
         toolName,
@@ -82,7 +107,9 @@ function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
   };
 }
 
-function structuredToolResult(result: unknown) {
+function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
+  result: TDetails,
+): AgentToolResult<TDetails> {
   const json = JSON.stringify(result, null, 2);
   const truncated = truncateHead(json, {
     maxBytes: DEFAULT_MAX_BYTES,
@@ -94,7 +121,7 @@ function structuredToolResult(result: unknown) {
   };
 }
 
-function failedStructuredOperation(prefix: string, result: unknown): never {
+function failedStructuredOperation(prefix: string, result: DeleteResult): never {
   const json = JSON.stringify(result);
   const truncated = truncateHead(json, {
     maxBytes: DEFAULT_MAX_BYTES,
@@ -104,7 +131,7 @@ function failedStructuredOperation(prefix: string, result: unknown): never {
 }
 
 function callerSourceTurnId(
-  coordinator: MinimalSubagentsCoordinator,
+  coordinator: CoordinatorToolOperations,
   callerId: string,
   toolCallId: string,
 ): string {
@@ -132,17 +159,17 @@ export function createCoordinatorToolDefinitions(
       return runCoordinatorToolActivity(options, async () => {
         const result = await options.coordinator.spawn(
           options.callerId,
-          parameters as SpawnParameters,
+          parameters,
           options.captureCaller(context),
         );
         const status = options.coordinator.inspectStatus(result.agent_id);
-        return {
-          ...structuredToolResult(result),
-          details: {
-            ...result,
-            ...(status && "agent" in status ? { agent: status.agent } : {}),
-          },
+        const details: SpawnResult & {
+          agent?: import("./minimal-subagents-types.js").AgentDetail;
+        } = {
+          ...result,
         };
+        if (status && "agent" in status) details.agent = status.agent;
+        return structuredToolResult(details);
       });
     },
     ...createCoordinatorToolRendering("subagent"),
@@ -152,7 +179,7 @@ export function createCoordinatorToolDefinitions(
     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.",
+      "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued for the recipient, or failed.",
     promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
     parameters: options.schemas.agent_message,
     async execute(toolCallId, parameters) {
@@ -175,7 +202,7 @@ export function createCoordinatorToolDefinitions(
     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.",
+      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. A Wait Event containing a Coordination Message may arrive first as event=message; call again for the terminal turn result. A successful wait durably claims that turn so later messages and its terminal result return through wait without duplicate automatic delivery. 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) {
@@ -199,6 +226,7 @@ export function createCoordinatorToolDefinitions(
             parameters.agent_id,
             parameters.timeout_ms,
             signal,
+            parameters.turn_id,
           );
           return {
             ...structuredToolResult(result),

package/src/minimal-subagents-types.ts

@@ -1,9 +1,6 @@
 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 };
 
@@ -58,13 +55,29 @@ export interface TurnResult {
   elapsed_ms?: number;
 }
 
-/** Reports delivery of one direct message to an authorized adjacent agent. */
+/** Reports whether one direct message was handed to a wait, queued, or failed. */
+export type AgentMessageDisposition = "delivered-via-wait" | "queued" | "failed";
+
 export interface AgentMessageResult {
   agent_id: string;
-  delivered: boolean;
+  message_id: string;
+  disposition: AgentMessageDisposition;
   error?: string;
 }
 
+/** Reports one coordination message returned before the source turn settles. */
+export interface WaitMessageResult {
+  event: "message";
+  agent_id: string;
+  turn_id: string;
+  message_id: string;
+  delivery_id?: string;
+  message: string;
+}
+
+/** Reports one terminal child turn returned by subagent_wait. */
+export type WaitResult = WaitMessageResult | ({ event: "turn" } & TurnResult);
+
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {
   agent_id: string;
@@ -92,7 +105,7 @@ export interface RecentAgentMessage {
 /** Extends summary status with launch, dependency, and recent-message diagnostics. */
 export interface AgentDetail extends AgentSummary {
   session_file?: string;
-  launch_contract: Record<string, unknown>;
+  launch_contract: LaunchContract;
   capability_ceiling: string[];
   spawn_entry_id: string;
   recent_messages: RecentAgentMessage[];
@@ -164,6 +177,8 @@ export interface CoordinatorMessage {
     source_agent_id: string;
     destination_agent_id?: string;
     source_turn_id: string;
+    message_id: string;
+    delivery_id?: string;
     status?: TurnStatus;
     elapsed_ms?: number;
     usage?: Usage;
@@ -172,8 +187,7 @@ export interface CoordinatorMessage {
 
 /** Process-local adapter around one SDK-created Pi child session. */
 export interface ChildAgentRuntime {
-  readonly sessionFile: string;
-  readonly sessionId: string;
+  readonly sessionLeafId: string | undefined;
   readonly isRunning: boolean;
   runPrompt(
     task: string,
@@ -182,48 +196,55 @@ export interface ChildAgentRuntime {
     callerThinkingLevel: ThinkingLevel,
   ): Promise<RuntimeTurnOutcome>;
   runMessage(message: CoordinatorMessage): Promise<RuntimeTurnOutcome>;
-  /** Steer one typed coordinator message into the child session. */
-  steerCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
+  /** Queue one typed coordinator message into the child session. */
+  queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
   abort(): Promise<void>;
   dispose(): void;
   /** Return the live Runtime Profile, or undefined when the SDK session has no model. */
   getRuntimeProfile(): RuntimeProfile | undefined;
   snapshotCommittedMessages(): AgentMessage[];
-  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string): boolean;
+  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: 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[];
+  sessionLeafId?: string;
 }
 
 /** 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>;
+  /** Open one verified persisted Child Agent runtime for launch or restoration. */
+  openRuntime(agent: PersistedAgent): Promise<ChildAgentRuntime>;
   resolveLaunchMissingDependencies(agent: PersistedAgent): Promise<string[]>;
   resolveRestorationMissingDependencies(agent: PersistedAgent): Promise<string[]>;
   resolveThinkingLevel(modelId: string, requested: ThinkingLevel): ThinkingLevel;
   modelSupportsImages(modelId: string): boolean;
+  /** Clone a child leaf owned by the active source root during confirmed shutdown. */
   cloneSession(agent: PersistedAgent): Promise<PersistedSessionIdentity>;
-  trashSessionFile(sessionFile: string): Promise<void>;
+  /** Clone a source-owned leaf recovered from a proven destination branch. */
+  cloneForkSourceSession(
+    agent: PersistedAgent,
+    sourceRootSessionId: string,
+  ): Promise<PersistedSessionIdentity>;
+  /** Append and verify destination-root ownership for one fork clone. */
+  adoptForkSessionOwnership(
+    agent: PersistedAgent,
+    sourceRootSessionId: string,
+  ): Promise<PersistedSessionIdentity>;
+  trashSession(agent: PersistedAgent): 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;
+  /** Queue one typed coordinator message into the root conversation. */
+  queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
+  hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
+  /** Report whether automatic delivery can start a new root turn without racing an active wait. */
+  isIdle(): boolean;
 }
 
 /** Stores root-owned agent identity, launch contract, availability, and latest activity. */
@@ -237,6 +258,7 @@ export interface PersistedAgent {
   spawn_entry_id: string;
   session_file?: string;
   session_id?: string;
+  session_leaf_id?: string;
   clone_error?: string;
   launch_contract: LaunchContract;
   capability_ceiling: string[];
@@ -250,7 +272,7 @@ export interface PersistedAgent {
   deleted?: boolean;
 }
 
-/** Records whether successful output was observed through wait or automatic messaging. */
+/** Records which conversation path owns one successful terminal result. */
 export type DeliveryPath = "wait" | "message";
 
 /** Stores a keyed successful result until destination evidence settles delivery. */
@@ -260,26 +282,44 @@ export interface PersistedDelivery {
   destination_agent_id: string;
   path: DeliveryPath;
   settled: boolean;
+  sequence?: number;
   result?: TurnResult;
   error?: string;
 }
 
-/** Checkpoints all live agents, deletion tombstones, and delivery records for one root. */
+/** Stores one durable Coordination Message until destination evidence settles it. */
+export interface PersistedCoordinationDelivery {
+  delivery_id: string;
+  sequence: number;
+  destination_agent_id: string;
+  path: DeliveryPath;
+  settled: boolean;
+  message: CoordinatorMessage;
+  error?: string;
+}
+
+/** Checkpoints live agents, tombstones, and only pending delivery-ledger items for one root. */
 export interface RegistrySnapshot {
   agents: PersistedAgent[];
   tombstones: string[];
   deliveries: PersistedDelivery[];
+  coordination_deliveries?: PersistedCoordinationDelivery[];
+  wait_claimed_turns?: string[];
+  next_delivery_sequence?: number;
 }
 
 /** Clones a registry snapshot while recording the source root session file. */
 export interface ForkSnapshot extends RegistrySnapshot {
+  /** Canonical Pi root session file from which the selected fork branch originated. */
   source_root_session_file: string;
+  /** Root identity that every cloned Child Session provenance record must match. */
+  source_root_session_id: 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;
+  append(event: import("./minimal-subagents-registry.js").RegistryEventV2): void;
 }
 
 /** Describes concise lifecycle notices surfaced through Pi UI notifications. */

package/src/minimal-subagents-ui.ts

@@ -1,4 +1,7 @@
 import type { Theme } from "@earendil-works/pi-coding-agent";
+
+/** Theme operations used by the Minimal Subagents widget renderer. */
+export type MinimalSubagentsWidgetTheme = Pick<Theme, "fg" | "bold">;
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   sliceByColumn,
@@ -195,7 +198,7 @@ function renderMinimalSubagentsWidgetRowParts(
   task: string | undefined,
   duration: string | undefined,
   profile: string,
-  theme: Theme,
+  theme: MinimalSubagentsWidgetTheme,
 ): MinimalSubagentsWidgetRowParts {
   const branch = row.depth > 0 ? `${"  ".repeat(row.depth)}╰─ ` : "  ";
   const styledBranch = theme.fg("borderMuted", branch);
@@ -225,7 +228,7 @@ function minimalSubagentsWidgetProfileBudget(
   task: string | undefined,
   duration: string | undefined,
   separator: string,
-  theme: Theme,
+  theme: MinimalSubagentsWidgetTheme,
   width: number,
 ): number {
   const fixedParts = renderMinimalSubagentsWidgetRowParts(row, task, duration, "", theme);
@@ -235,7 +238,7 @@ function minimalSubagentsWidgetProfileBudget(
 function renderMinimalSubagentsWidgetRow(
   row: MinimalSubagentsWidgetRow,
   width: number,
-  theme: Theme,
+  theme: MinimalSubagentsWidgetTheme,
 ): string {
   const separator = theme.fg("dim", MINIMAL_SUBAGENTS_WIDGET_SEPARATOR_TEXT);
   const task = row.task?.replace(/\s+/g, " ").trim() || undefined;
@@ -336,7 +339,7 @@ function renderMinimalSubagentsWidgetRow(
 export function renderMinimalSubagentsWidgetLines(
   view: MinimalSubagentsWidgetView,
   width: number,
-  theme: Theme,
+  theme: MinimalSubagentsWidgetTheme,
 ): string[] {
   if (width <= 0) return [];
   const separator = theme.fg("dim", MINIMAL_SUBAGENTS_WIDGET_SEPARATOR_TEXT);
@@ -376,7 +379,7 @@ class MinimalSubagentsWidgetComponent implements Component {
   constructor(
     private view: MinimalSubagentsWidgetView,
     private readonly tui: TUI,
-    private readonly theme: Theme,
+    private readonly theme: MinimalSubagentsWidgetTheme,
   ) {}
 
   update(view: MinimalSubagentsWidgetView): void {