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

package/README.md

@@ -155,14 +155,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.2.3",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-coordinator.ts

@@ -110,6 +110,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>();
@@ -994,6 +1012,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") {
@@ -1026,11 +1045,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(
@@ -1765,6 +1801,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 +1823,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 +1890,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;

package/src/minimal-subagents-extension.ts

@@ -99,6 +99,7 @@ function createRootConversationEndpoint(
         },
       );
     },
+    isIdle: () => context.isIdle(),
     hasDeliveryEvidence: (sourceAgentId, sourceTurnId, deliveryId) =>
       findDeliveryEvidence(
         context.sessionManager.getBranch(),

package/src/minimal-subagents-sessions.ts

@@ -520,6 +520,8 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     private readonly modelById: ReadonlyMap<string, Model<any>>,
     onSessionActivity?: () => void,
   ) {
+    // Keep this child-only; AgentSession.setSteeringMode would overwrite the user's global setting.
+    session.agent.steeringMode = "all";
     this.unsubscribe = session.subscribe((event) => {
       if (event.type !== "entry_appended") return;
       if (

package/src/minimal-subagents-types.ts

@@ -188,6 +188,7 @@ export interface CoordinatorMessage {
     status?: TurnStatus;
     elapsed_ms?: number;
     usage?: Usage;
+    messages?: Array<{ delivery_id?: string; message_id?: string }>;
   };
 }
 
@@ -248,6 +249,8 @@ export interface AgentSessionFactory {
 export interface RootConversationEndpoint {
   /** Queue one typed coordinator message into the root conversation. */
   queueCoordinatorMessage(message: CoordinatorMessage): Promise<void>;
+  /** Whether a coordinator message can start immediately instead of joining Pi's steer queue. */
+  isIdle(): boolean;
   hasDeliveryEvidence(sourceAgentId: string, sourceTurnId: string, deliveryId?: string): boolean;
 }