@ian-pascoe/pi-minimal-subagents 0.2.2 → 0.3.0

package/README.md

@@ -130,6 +130,11 @@ children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
 only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
 and `subagent_status`.
 
+Targeted `subagent_status` includes `recent_activity`, a bounded tail of message
+text, reasoning, tool calls, and tool results. It includes the current streaming
+assistant message but omits image data. Timeout Wait Events include the same
+detailed status snapshot.
+
 The `subagent` `tools` argument distinguishes capability presets from exact
 lists: `"read"` grants `read`, `grep`, `find`, and `ls`; `"modify"` adds
 `bash`, `edit`, and `write`; an array such as `["read"]` grants exactly the
@@ -148,6 +153,10 @@ optional `turn_id` to address an older retained turn exactly. Without it, waits
 select the oldest observable claimed or pending turn before the active/latest
 turn. A caller may have only one outstanding wait for the same source turn; a
 concurrent duplicate is rejected instead of competing for one Wait Event.
+When `timeout_ms` expires, the wait returns an observational `event: "timeout"`
+with the requested turn identity and the same detailed Child Agent status used
+by targeted `subagent_status`. It removes only the waiter, leaving the child
+running and all pending delivery unclaimed. Abort signals remain errors.
 
 The persisted Delivery Ledger records Coordination Messages, terminal results,
 globally increasing sequence, and wait ownership before delivery. Existing
@@ -155,14 +164,15 @@ items retain their sequence; gaps from skipped malformed records are valid.
 Claims can name only active, latest, or retained turns. Wait-returned messages
 retain individual delivery evidence; terminal wait ownership remains durable
 across reloads, forks, and newer turns. Automatic fallback retains its ordered
-queue reservation and sends every unclaimed Coordination Message and terminal
-result as a Pi steer, including while the recipient is active. Destination-session
-Delivery Evidence settles and compacts ledger items, preventing duplicate delivery
-and unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
-most 20 pending wait-only terminal results per source agent; Coordination
-Messages are not removed by that terminal-retention limit. Delivered messages
-include stable delivery, source-agent, and source-turn identities in persisted
-details.
+queue reservation while batching queued messages from one source turn into one
+Pi steer. Root-bound messages remain batchable while the root turn is active; a
+pending terminal result absorbs them. Child sessions drain all available steers
+before the next model call. Destination-session Delivery Evidence still settles
+each batched ledger item independently, preventing duplicate delivery and
+unbounded checkpoint growth. The pure Delivery Ledger state machine retains at
+most 20 pending wait-only terminal results per source agent; Coordination Messages
+are not removed by that terminal-retention limit. Delivered messages include
+stable delivery, source-agent, and source-turn identities in persisted details.
 
 Deleting a child first verifies its session header and persistent identity,
 then uses the optional `trash` command when available and falls back to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-capabilities.ts

@@ -39,11 +39,10 @@ export function buildEligibleModelIds(input: {
   return [...new Set(source.map(({ provider, id }) => `${provider}/${id}`))];
 }
 
-/** Supplies inherited tools, the ancestor ceiling, and runtime availability for exact tool resolution. */
+/** Supplies inherited tools and the ancestor ceiling for exact tool resolution. */
 export interface ToolResolutionContext {
   ordinaryTools: readonly string[];
   capabilityCeiling: readonly string[];
-  availableTools: readonly string[];
 }
 
 /** Resolve an exact ordinary-tool contract and reject missing or over-ceiling capabilities. */
@@ -69,13 +68,9 @@ export function resolveOrdinaryToolSelection(
       `Minimal subagents ordinary tool selection: coordinator tools are injected separately and must not appear in tools: ${requestedCoordinatorTools.join(", ")}`,
     );
   }
-  const available = new Set(context.availableTools);
+  // ponytail: availableTools and capabilityCeiling are identical at every production site,
+  // so availability and the ancestor ceiling are enforced by a single membership check.
   const ceiling = new Set(context.capabilityCeiling);
-  const missing = uniqueRequested.filter((name) => !available.has(name));
-  if (missing.length > 0) {
-    throw new Error(`Minimal subagents tool resolution: unavailable tool: ${missing.join(", ")}`);
-  }
-
   const exceeded = uniqueRequested.filter((name) => !ceiling.has(name));
   if (exceeded.length > 0) {
     throw new Error(`Minimal subagents capability ceiling exceeded: ${exceeded.join(", ")}`);

package/src/minimal-subagents-context.ts

@@ -1,5 +1,11 @@
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
-import type { SessionContextMode } from "./minimal-subagents-types.js";
+import { contentText, type ImageContent, type TextContent } from "@earendil-works/pi-ai";
+import { truncateTail } from "@earendil-works/pi-coding-agent";
+import type { RecentAgentActivity, SessionContextMode } from "./minimal-subagents-types.js";
+
+const RECENT_AGENT_ACTIVITY_LIMIT = 12;
+const RECENT_AGENT_ACTIVITY_MAX_LINES = 20;
+const RECENT_AGENT_ACTIVITY_MAX_BYTES = 2 * 1024;
 
 /** Clone committed caller messages and exclude only the currently streaming assistant message. */
 export function snapshotCommittedContext(
@@ -11,6 +17,71 @@ export function snapshotCommittedContext(
   return structuredClone(committed);
 }
 
+function boundedRecentActivityContent(label: string, content: string): RecentAgentActivity {
+  const bounded = truncateTail(content, {
+    maxLines: RECENT_AGENT_ACTIVITY_MAX_LINES,
+    maxBytes: RECENT_AGENT_ACTIVITY_MAX_BYTES,
+  });
+  return { label, content: bounded.content, truncated: bounded.truncated };
+}
+
+function visibleMessageContent(content: string | readonly (TextContent | ImageContent)[]): string {
+  return contentText(content, "\n\n") || "(no text content)";
+}
+
+/** Build a bounded recent activity tail from message text, reasoning, and tool work. */
+export function buildRecentAgentActivity(messages: readonly AgentMessage[]): RecentAgentActivity[] {
+  const activity: RecentAgentActivity[] = [];
+  for (const message of messages) {
+    if (message.role === "assistant") {
+      for (const content of message.content) {
+        if (content.type === "text" && content.text) {
+          activity.push(boundedRecentActivityContent("assistant message", content.text));
+        } else if (content.type === "thinking") {
+          activity.push(
+            boundedRecentActivityContent(
+              "reasoning",
+              content.thinking ||
+                (content.redacted ? "[redacted reasoning]" : "(no reasoning text)"),
+            ),
+          );
+        } else if (content.type === "toolCall") {
+          activity.push(
+            boundedRecentActivityContent(
+              `tool call ${content.name}`,
+              JSON.stringify(content.arguments, null, 2),
+            ),
+          );
+        }
+      }
+    } else if (message.role === "toolResult") {
+      activity.push(
+        boundedRecentActivityContent(
+          `tool result ${message.toolName}${message.isError ? " (error)" : ""}`,
+          visibleMessageContent(message.content),
+        ),
+      );
+    } else if (message.role === "user" || message.role === "custom") {
+      activity.push(
+        boundedRecentActivityContent(
+          `${message.role} message`,
+          visibleMessageContent(message.content),
+        ),
+      );
+    } else if (message.role === "branchSummary" || message.role === "compactionSummary") {
+      activity.push(boundedRecentActivityContent(`${message.role} message`, message.summary));
+    } else if (message.role === "bashExecution") {
+      activity.push(
+        boundedRecentActivityContent(
+          `${message.role} message`,
+          `$ ${message.command}\n${message.output || "(no output)"}`,
+        ),
+      );
+    }
+  }
+  return activity.slice(-RECENT_AGENT_ACTIVITY_LIMIT);
+}
+
 /** Carries the selected caller messages and whether child preparation should compact them. */
 export interface ImportedSubagentContext {
   messages: AgentMessage[];

package/src/minimal-subagents-coordinator.ts

@@ -1,5 +1,9 @@
 import { randomUUID } from "node:crypto";
-import { assembleImportedContext, contextContainsImages } from "./minimal-subagents-context.js";
+import {
+  assembleImportedContext,
+  buildRecentAgentActivity,
+  contextContainsImages,
+} from "./minimal-subagents-context.js";
 import {
   canAgentContractSpawn,
   DEFAULT_MAX_SUBAGENT_DEPTH,
@@ -29,6 +33,7 @@ import {
   type DeliveryLedgerTransition,
 } from "./minimal-subagents-delivery-ledger.js";
 import { addCoordinatorMessageEnvelope } from "./minimal-subagents-message-envelope.js";
+import { unavailableAgent } from "./minimal-subagents-sessions.js";
 import { createRegistryEvent } from "./minimal-subagents-registry.js";
 import type {
   AgentDetail,
@@ -51,7 +56,6 @@ import type {
   SpawnParameters,
   SpawnResult,
   StatusResult,
-  TurnId,
   TurnResult,
   WaitMessageResult,
   WaitResult,
@@ -110,6 +114,24 @@ function terminalWaitResult(result: TurnResult, messages: WaitMessageResult[] =
   return messages.length === 0 ? terminal : { ...terminal, messages: structuredClone(messages) };
 }
 
+function combineCoordinatorMessages(messages: readonly CoordinatorMessage[]): CoordinatorMessage {
+  const latest = messages.at(-1);
+  if (!latest) throw new Error("Minimal subagents message batch must not be empty");
+  if (messages.length === 1) return latest;
+  const references = messages.flatMap(
+    (message) =>
+      message.details.messages ??
+      (message.details.delivery_id
+        ? [{ delivery_id: message.details.delivery_id, message_id: message.details.message_id }]
+        : []),
+  );
+  return {
+    ...latest,
+    content: messages.map((message) => message.content).join("\n\n"),
+    details: references.length > 0 ? { ...latest.details, messages: references } : latest.details,
+  };
+}
+
 /** One root-owned coordinator for persistent nested Pi child sessions. */
 export class MinimalSubagentsCoordinator {
   private readonly agents = new Map<string, PersistedAgent>();
@@ -185,7 +207,6 @@ export class MinimalSubagentsCoordinator {
     const ordinaryTools = resolveOrdinaryToolSelection(parameters.tools, {
       ordinaryTools: excludeCoordinatorTools(caller.ordinaryTools),
       capabilityCeiling: excludeCoordinatorTools(caller.capabilityCeiling),
-      availableTools: excludeCoordinatorTools(caller.availableTools),
     });
     const committedMessages = structuredClone(caller.messages);
     const imported = assembleImportedContext(sessionContext, committedMessages);
@@ -278,7 +299,6 @@ export class MinimalSubagentsCoordinator {
       thinkingLevel: agent.launch_contract.thinking_level,
       ordinaryTools: [...agent.launch_contract.ordinary_tools],
       capabilityCeiling: [...agent.capability_ceiling],
-      availableTools: [...agent.capability_ceiling],
       spawnEntryId,
     };
   }
@@ -336,7 +356,7 @@ export class MinimalSubagentsCoordinator {
     }
   }
 
-  /** Wait for one exact turn and claim its message/result delivery from automatic fallback. */
+  /** Wait for one exact turn, returning detailed child status if the waiter times out. */
   wait(
     callerId: string,
     agentId: string,
@@ -387,13 +407,16 @@ export class MinimalSubagentsCoordinator {
         reject(error);
       };
       if (timeoutMs !== undefined) {
-        waiter.timeout = setTimeout(
-          () =>
-            stopWaiting(
-              new Error(`Minimal subagents wait timed out for ${agentId} after ${timeoutMs}ms`),
-            ),
-          timeoutMs,
-        );
+        waiter.timeout = setTimeout(() => {
+          this.removeWaiter(key, waiter);
+          resolve({
+            event: "timeout",
+            agent_id: agentId,
+            turn_id: turnId,
+            timeout_ms: timeoutMs,
+            agent: this.buildAgentDetail(agent, false),
+          });
+        }, timeoutMs);
       }
       if (signal) {
         waiter.abortListener = () =>
@@ -474,7 +497,6 @@ export class MinimalSubagentsCoordinator {
       agent_id: agentId,
       recursive,
       deleted_agent_ids: [],
-      tombstoned_agent_ids: [],
       trashed_session_files: [],
       failures: [],
     };
@@ -502,7 +524,6 @@ export class MinimalSubagentsCoordinator {
         this.pruneRecentMessageProjectionsForDeletedAgent(agent.agent_id);
         this.tombstones.add(agent.agent_id);
         result.deleted_agent_ids.push(agent.agent_id);
-        result.tombstoned_agent_ids.push(agent.agent_id);
         this.dependencies.registry.append(
           createRegistryEvent(this.dependencies.registry.rootSessionId, "agent-deleted", {
             agent_ids: [agent.agent_id],
@@ -549,12 +570,8 @@ export class MinimalSubagentsCoordinator {
     this.runtimeInitializations.clear();
     this.pendingAgentIds.clear();
     this.tombstones.clear();
-    this.deliveryLedger = createDeliveryLedger();
     this.waiters.clear();
-    this.pendingParentMessages.clear();
     this.waitHandedDeliveryIds.clear();
-    this.recipientQueues.clear();
-    this.backgroundOperations.clear();
     this.automaticDeliveryKeys.clear();
     this.automaticCoordinationDeliveryIds.clear();
     this.deliveryLedger = createDeliveryLedger({
@@ -898,9 +915,8 @@ export class MinimalSubagentsCoordinator {
     return initialization;
   }
 
-  private beginTurn(agent: PersistedAgent): TurnId {
-    // SAFETY: The generated value embeds the canonical agent ID and a fresh turn UUID before branding.
-    const turnId = `${agent.agent_id}:turn-${randomUUID()}` as TurnId;
+  private beginTurn(agent: PersistedAgent): string {
+    const turnId = `${agent.agent_id}:turn-${randomUUID()}`;
     const startedAt = this.now().toISOString();
     agent.active_turn_id = turnId;
     agent.active_turn_started_at = startedAt;
@@ -994,6 +1010,7 @@ export class MinimalSubagentsCoordinator {
     if (this.automaticDeliveryKeys.has(deliveryKey)) return;
     this.automaticDeliveryKeys.add(deliveryKey);
     const graceMs = this.deliveryGraceMs();
+    let batchedCoordinationDeliveries: PersistedCoordinationDelivery[] = [];
     try {
       await this.enqueueRecipientDelivery(delivery.destination_agent_id, async () => {
         if (delivery.destination_agent_id !== "root") {
@@ -1008,11 +1025,6 @@ export class MinimalSubagentsCoordinator {
           this.settleDelivery(delivery);
           return;
         }
-        if (!this.acceptingOperations || this.shouldStopAutomaticTerminalDelivery(delivery)) return;
-        if (this.hasDeliveryEvidence(delivery)) {
-          this.settleDelivery(delivery);
-          return;
-        }
         const message: CoordinatorMessage = {
           customType: "minimal-subagents.result",
           content: result.output,
@@ -1026,11 +1038,28 @@ export class MinimalSubagentsCoordinator {
             usage: result.usage,
           },
         };
-        await this.deliverToRecipient(delivery.destination_agent_id, message, () =>
-          this.isTerminalDeliveryCurrent(delivery),
+        batchedCoordinationDeliveries = this.takePendingParentDeliveryBatch(
+          deliveryKey,
+          delivery.destination_agent_id,
+        );
+        for (const batchedDelivery of batchedCoordinationDeliveries) {
+          this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
+        }
+        await this.deliverToRecipient(
+          delivery.destination_agent_id,
+          combineCoordinatorMessages([
+            ...batchedCoordinationDeliveries.map((item) => item.message),
+            message,
+          ]),
+          () =>
+            this.isTerminalDeliveryCurrent(delivery) &&
+            batchedCoordinationDeliveries.every((item) => this.isCoordinationDeliveryCurrent(item)),
         );
       });
     } catch (error) {
+      for (const batchedDelivery of batchedCoordinationDeliveries) {
+        this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
+      }
       if (!this.isTerminalDeliveryCurrent(delivery)) return;
       const deliveryError = error instanceof Error ? error.message : String(error);
       this.deliveryLedger = setTerminalDeliveryError(
@@ -1442,11 +1471,6 @@ export class MinimalSubagentsCoordinator {
       elapsed_ms: elapsed ?? agent.latest_result?.elapsed_ms,
       latest_activity_at: agent.latest_activity_at ?? agent.created_at,
       task: agent.task,
-      latest_activity: agent.active_turn_id
-        ? "turn running"
-        : agent.latest_result
-          ? `turn ${agent.latest_result.status}`
-          : "created",
       child_count: directChildren.length,
       children,
     };
@@ -1454,7 +1478,8 @@ export class MinimalSubagentsCoordinator {
 
   private buildAgentDetail(agent: PersistedAgent, includeDescendants = true): AgentDetail {
     const summary = this.buildAgentSummary(agent, includeDescendants);
-    const runtimeUsage = this.runtimes.get(agent.agent_id)?.getUsage();
+    const runtime = this.runtimes.get(agent.agent_id);
+    const runtimeUsage = runtime?.getUsage();
     return {
       ...summary,
       session_file: agent.session_file,
@@ -1462,6 +1487,7 @@ export class MinimalSubagentsCoordinator {
       capability_ceiling: [...agent.capability_ceiling],
       spawn_entry_id: agent.spawn_entry_id,
       recent_messages: structuredClone(agent.recent_messages),
+      recent_activity: buildRecentAgentActivity(runtime?.snapshotActivityMessages() ?? []),
       latest_result: agent.latest_result ? structuredClone(agent.latest_result) : undefined,
       missing_dependencies: [...agent.missing_dependencies],
       unavailable_reason: agent.unavailable_reason,
@@ -1585,19 +1611,7 @@ export class MinimalSubagentsCoordinator {
   }
 
   private createForkPlaceholder(agent: PersistedAgent, cloneError: string): PersistedAgent {
-    return {
-      ...structuredClone(agent),
-      session_file: undefined,
-      session_id: undefined,
-      session_leaf_id: undefined,
-      clone_error: cloneError,
-      active_turn_id: undefined,
-      active_turn_started_at: undefined,
-      latest_activity_at: this.now().toISOString(),
-      availability: "unavailable",
-      missing_dependencies: [cloneError],
-      unavailable_reason: cloneError,
-    };
+    return unavailableAgent(agent, cloneError, this.now().toISOString());
   }
 
   private rejectAllWaiters(error: Error): void {
@@ -1765,6 +1779,7 @@ export class MinimalSubagentsCoordinator {
     )
       return;
 
+    let automaticBatch = [delivery];
     const operation = this.enqueueRecipientDelivery(targetId, async () => {
       if (targetId !== "root") {
         await this.ensureRuntime(this.requireUsableAgent(targetId, "message"));
@@ -1786,25 +1801,63 @@ export class MinimalSubagentsCoordinator {
       pending.cancelGrace?.();
       pending.cancelGrace = undefined;
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
+      while (
+        targetId === "root" &&
+        !this.dependencies.root.isIdle() &&
+        !findTerminalDelivery(
+          this.deliveryLedger,
+          message.details.source_agent_id,
+          message.details.source_turn_id,
+        ) &&
+        this.acceptingOperations &&
+        !pending.claimed &&
+        !turnClaimed()
+      ) {
+        await Promise.race([
+          pending.claimPromise,
+          new Promise((resolve) => setTimeout(resolve, 25)),
+        ]);
+      }
       if (!this.acceptingOperations || pending.claimed || turnClaimed()) return;
-      this.removePendingParentMessage(key, pending);
-      this.waitHandedDeliveryIds.add(delivery.delivery_id);
-      await this.deliverToRecipient(targetId, message, () =>
-        this.isCoordinationDeliveryCurrent(delivery),
+      const terminalDelivery = findTerminalDelivery(
+        this.deliveryLedger,
+        message.details.source_agent_id,
+        message.details.source_turn_id,
+      );
+      if (
+        terminalDelivery?.destination_agent_id === targetId &&
+        terminalDelivery.path === "message"
+      ) {
+        for (const queued of this.pendingParentMessages.get(key) ?? []) {
+          queued.cancelGrace?.();
+          queued.releaseClaim();
+        }
+        return;
+      }
+      automaticBatch = this.takePendingParentDeliveryBatch(key, targetId);
+      for (const batchedDelivery of automaticBatch) {
+        this.waitHandedDeliveryIds.add(batchedDelivery.delivery_id);
+      }
+      if (automaticBatch.length === 0) return;
+      await this.deliverToRecipient(
+        targetId,
+        combineCoordinatorMessages(automaticBatch.map((item) => item.message)),
+        () => automaticBatch.every((item) => this.isCoordinationDeliveryCurrent(item)),
       );
     });
     void operation.catch((cause) => {
-      this.removePendingParentMessage(key, pending);
-      this.waitHandedDeliveryIds.delete(delivery.delivery_id);
-      if (!this.isCoordinationDeliveryCurrent(delivery)) return;
       const deliveryError = cause instanceof Error ? cause.message : String(cause);
-      this.deliveryLedger = setCoordinationDeliveryError(
-        this.deliveryLedger,
-        delivery.delivery_id,
-        deliveryError,
-      );
-      const current = findCoordinationDelivery(this.deliveryLedger, delivery.delivery_id);
-      if (current) this.persistCoordinationDeliveryState(current);
+      for (const batchedDelivery of automaticBatch) {
+        this.waitHandedDeliveryIds.delete(batchedDelivery.delivery_id);
+        if (!this.isCoordinationDeliveryCurrent(batchedDelivery)) continue;
+        this.deliveryLedger = setCoordinationDeliveryError(
+          this.deliveryLedger,
+          batchedDelivery.delivery_id,
+          deliveryError,
+        );
+        const current = findCoordinationDelivery(this.deliveryLedger, batchedDelivery.delivery_id);
+        if (current) this.persistCoordinationDeliveryState(current);
+      }
       this.dependencies.notify?.({
         type: "failure",
         agentId: message.details.source_agent_id,
@@ -1815,6 +1868,25 @@ export class MinimalSubagentsCoordinator {
     });
   }
 
+  private takePendingParentDeliveryBatch(
+    key: string,
+    targetId: string,
+  ): PersistedCoordinationDelivery[] {
+    const batch = (this.pendingParentMessages.get(key) ?? []).filter(
+      (pending) => pending.destinationAgentId === targetId && !pending.claimed,
+    );
+    for (const pending of batch) {
+      pending.claimed = true;
+      pending.cancelGrace?.();
+      pending.releaseClaim();
+      this.removePendingParentMessage(key, pending);
+    }
+    return batch.flatMap((pending) => {
+      const delivery = findCoordinationDelivery(this.deliveryLedger, pending.deliveryId);
+      return delivery ? [delivery] : [];
+    });
+  }
+
   private removePendingParentMessage(key: string, pending: PendingParentMessage): void {
     const pendingMessages = this.pendingParentMessages.get(key);
     if (!pendingMessages) return;