@ian-pascoe/pi-minimal-subagents 0.1.0 → 0.2.0

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

@@ -9,6 +9,7 @@ import {
   type ToolDefinition,
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 import {
@@ -16,8 +17,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 +35,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[];
@@ -36,16 +53,38 @@ interface CoordinatorToolDefinitionOptions {
   onAttention?: (message: string) => void;
 }
 
+/** Arguments consumed by the wait tool's narrow coordinator execution seam. */
+export type CoordinatorWaitToolParameters = Static<
+  ReturnType<typeof createCoordinatorToolSchemas>["subagent_wait"]
+>;
+
+/** Forward one typed wait-tool request without requiring an unrelated Pi execution context. */
+export function executeCoordinatorWaitTool(
+  coordinator: Pick<CoordinatorToolOperations, "wait">,
+  callerId: string,
+  parameters: CoordinatorWaitToolParameters,
+  signal: AbortSignal | undefined,
+): Promise<WaitResult> {
+  return coordinator.wait(
+    callerId,
+    parameters.agent_id,
+    parameters.timeout_ms,
+    signal,
+    parameters.turn_id,
+  );
+}
+
 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}` : ""}`,
-  );
+  const roleLines = modelRoles.map((role) => {
+    const thinkingGuidance = role.thinkingLevel ? `, thinking_level=${role.thinkingLevel}` : "";
+    return `  - ${role.name} → model=${role.model}${thinkingGuidance}${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.",
+    "Choose a model based on the task. A listed thinking_level is a preference, not a constraint. Callers choose thinking_level independently for roles without one.",
   ];
 }
 
@@ -60,15 +99,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,
@@ -81,7 +129,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,
@@ -93,7 +143,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,
@@ -103,7 +153,7 @@ function failedStructuredOperation(prefix: string, result: unknown): never {
 }
 
 function callerSourceTurnId(
-  coordinator: MinimalSubagentsCoordinator,
+  coordinator: CoordinatorToolOperations,
   callerId: string,
   toolCallId: string,
 ): string {
@@ -131,17 +181,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"),
@@ -151,7 +201,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) {
@@ -174,7 +224,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) {
@@ -193,10 +243,10 @@ export function createCoordinatorToolDefinitions(
       waitingInterval.unref?.();
       try {
         return await runCoordinatorToolActivity(options, async () => {
-          const result = await options.coordinator.wait(
+          const result = await executeCoordinatorWaitTool(
+            options.coordinator,
             options.callerId,
-            parameters.agent_id,
-            parameters.timeout_ms,
+            parameters,
             signal,
           );
           return {

package/src/minimal-subagents-types.ts

@@ -22,6 +22,12 @@ export type AgentAvailability = "available" | "unavailable";
 /** Classifies active and terminal persistent subagent turn outcomes. */
 export type TurnStatus = "running" | "completed" | "failed" | "cancelled" | "interrupted";
 
+/** Describes the canonical model and resolved thinking level currently used by a Child Agent. */
+export interface RuntimeProfile {
+  model: string;
+  thinking_level: ThinkingLevel;
+}
+
 /** Defines the validated launch contract accepted by the subagent tool. */
 export interface SpawnParameters {
   task: string;
@@ -52,23 +58,37 @@ 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;
 }
 
-/** Provides bounded hierarchy and usage data for one persistent agent. */
-export interface AgentSummary {
+/** 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;
   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;
@@ -88,7 +108,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[];
@@ -125,11 +145,9 @@ export interface DeleteResult {
 }
 
 /** Persists immutable context, model, thinking, and ordinary-tool launch choices. */
-export interface LaunchContract {
+export interface LaunchContract extends RuntimeProfile {
   session_context: SessionContextMode;
   project_context: ProjectContextMode;
-  model: string;
-  thinking_level: ThinkingLevel;
   tools: ToolSelection | undefined;
   ordinary_tools: string[];
   delegation?: DelegationMode;
@@ -162,6 +180,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,6 +192,7 @@ export interface CoordinatorMessage {
 export interface ChildAgentRuntime {
   readonly sessionFile: string;
   readonly sessionId: string;
+  readonly sessionLeafId: string | undefined;
   readonly isRunning: boolean;
   runPrompt(
     task: string,
@@ -180,20 +201,22 @@ 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;
+  sessionLeafId?: string;
 }
 
 /** Combines a persisted agent record with first-launch imported context. */
@@ -211,15 +234,28 @@ export interface AgentSessionFactory {
   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. */
@@ -233,6 +269,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[];
@@ -246,7 +283,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. */
@@ -256,26 +293,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. */