@ian-pascoe/pi-minimal-subagents 0.14.0 → 0.14.1

package/README.md

@@ -40,7 +40,9 @@ From this package checkout, load the source directly with
    `agent_message` in the same tool batch can target the new child.
 2. `subagent_wait` claims the turn's result, or leave it unclaimed and the final
    response arrives automatically as a steer message. Without `turn_id`, a wait
-   skips turns whose result you already claimed or received automatically.
+   skips turns whose result you already claimed or received automatically, and
+   never repeats an automatically delivered result: it reports
+   `already_delivered: true` instead of the output.
 3. `agent_message` continues an idle child: the result reports
    `disposition: "started-turn"` with the new `turn_id`. A plain
    `subagent_wait({ agent_id })` targets that new turn, not the first result;
@@ -336,12 +338,16 @@ intermediate Wait Event containing a Coordination Message before the child turn
 settles. That event claims only its message, so later unconsumed messages and the
 terminal result retain automatic fallback. If the turn has already settled, a
 wait returns its terminal result with queued messages in `messages`; waiting
-again for the same settled turn returns the same result while it is retained. Pass
-optional `turn_id` to address a retained turn exactly, including one whose
-result you already claimed (a claimed result stays retained until Delivery
-Evidence settles it). Without it, waits skip claimed turns and turns whose
-result was already delivered to you automatically, and select the oldest
-remaining observable turn, falling back to the active, then latest, turn. A
+again for a settled turn you claimed returns the same result while it is
+retained. Pass optional `turn_id` to address a retained turn exactly, including
+one whose result you already claimed (a claimed result stays retained until
+Delivery Evidence settles it). Without it, waits skip claimed turns and turns
+whose result was already delivered to you automatically, and select the oldest
+remaining observable turn, falling back to the active, then latest, turn. When
+that fallback reaches a result already delivered to you automatically, whether
+still queued or settled, the wait returns `event: "turn"` with
+`already_delivered: true`, the turn identity, and status, but no output; it does
+not claim the turn, and `turn_id` rereads the full result. 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"`

package/package.json

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

package/src/minimal-subagents-coordinator.ts

@@ -69,6 +69,7 @@ import type {
   StatusResult,
   TurnResult,
   WaitMessageResult,
+  WaitDeliveredTurnResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
@@ -145,6 +146,27 @@ function terminalWaitResult(result: TurnResult, messages: WaitMessageResult[] =
   return messages.length === 0 ? terminal : { ...terminal, messages: structuredClone(messages) };
 }
 
+/** A terminal Wait Event naming an already delivered result without repeating its output. */
+function alreadyDeliveredWaitResult(
+  result: TurnResult,
+  messages: WaitMessageResult[],
+): WaitDeliveredTurnResult {
+  const delivered: WaitDeliveredTurnResult = {
+    event: "turn",
+    agent_id: result.agent_id,
+    turn_id: result.turn_id,
+    status: result.status,
+    already_delivered: true,
+  };
+  if (messages.length > 0) delivered.messages = structuredClone(messages);
+  return delivered;
+}
+
+/** The message ID of an automatic result message, which is also its Delivery Evidence key. */
+function automaticResultMessageId(sourceAgentId: string, sourceTurnId: string): string {
+  return `result:${sourceAgentId}:${sourceTurnId}`;
+}
+
 function combineCoordinatorMessages(messages: readonly CoordinatorMessage[]): CoordinatorMessage {
   const latest = messages.at(-1);
   if (!latest) throw new Error("Minimal subagents message batch must not be empty");
@@ -486,6 +508,11 @@ export class MinimalSubagentsCoordinator {
       (agent.latest_result?.turn_id === turnId ? agent.latest_result : undefined);
     if (retainedResult) {
       const messages = this.drainPendingParentMessages(callerId, agentId, turnId);
+      // A default wait falls back to the latest turn, whose result may already have been delivered
+      // automatically; repeating its output would deliver it twice. An explicit turn_id rereads it.
+      if (requestedTurnId === undefined && this.wasAlreadyDelivered(callerId, retainedResult)) {
+        return Promise.resolve(alreadyDeliveredWaitResult(retainedResult, messages));
+      }
       this.claimTerminalDelivery(callerId, retainedResult);
       return Promise.resolve(terminalWaitResult(retainedResult, messages));
     }
@@ -1335,7 +1362,7 @@ export class MinimalSubagentsCoordinator {
             source_agent_id: delivery.source_agent_id,
             destination_agent_id: delivery.destination_agent_id,
             source_turn_id: result.turn_id,
-            message_id: `result:${delivery.source_agent_id}:${result.turn_id}`,
+            message_id: automaticResultMessageId(delivery.source_agent_id, result.turn_id),
             status: result.status,
             elapsed_ms: result.elapsed_ms,
             usage: result.usage,
@@ -1737,6 +1764,22 @@ export class MinimalSubagentsCoordinator {
     );
   }
 
+  /**
+   * Whether this result was already delivered to the caller automatically: it is handed, or the
+   * caller's branch holds its automatic result message. A wait's own tool result does not count.
+   */
+  private wasAlreadyDelivered(callerId: string, result: TurnResult): boolean {
+    return (
+      this.handedTerminalKeys.has(deliveryTurnKey(result.agent_id, result.turn_id)) ||
+      this.hasRecipientDeliveryEvidence(
+        callerId,
+        result.agent_id,
+        result.turn_id,
+        automaticResultMessageId(result.agent_id, result.turn_id),
+      )
+    );
+  }
+
   private hasDeliveryEvidence(delivery: PersistedDelivery): boolean {
     return this.hasRecipientDeliveryEvidence(
       delivery.destination_agent_id,

package/src/minimal-subagents-render-contract.ts

@@ -146,6 +146,7 @@ const WaitTurnDetailsSchema = Type.Object({
   error: Type.Optional(Type.String()),
   elapsed_ms: Type.Optional(Type.Number()),
   usage: Type.Optional(RenderUsageSchema),
+  already_delivered: Type.Optional(Type.Boolean()),
   messages: Type.Optional(Type.Array(WaitMessageDetailsSchema)),
 });
 const WaitTimeoutDetailsSchema = Type.Object({
@@ -300,6 +301,13 @@ export const CoordinatorToolOutputSchemas = {
       messages: Type.Optional(Type.Array(CoordinatorWaitMessageOutputSchema)),
       ...CoordinatorWaitSourceOutputSchema,
     }),
+    Type.Object({
+      ...Type.Pick(CoordinatorTurnOutputSchema, ["agent_id", "turn_id", "status"]).properties,
+      event: Type.Literal("turn"),
+      already_delivered: Type.Literal(true),
+      messages: Type.Optional(Type.Array(CoordinatorWaitMessageOutputSchema)),
+      ...CoordinatorWaitSourceOutputSchema,
+    }),
     Type.Object({
       event: Type.Literal("timeout"),
       agent_id: Type.String(),

package/src/minimal-subagents-rendering.ts

@@ -582,6 +582,9 @@ function renderWaitProgress(
   return container;
 }
 
+/** Shown instead of the output of a result already delivered to the parent automatically. */
+const ALREADY_DELIVERED_TEXT = "Already delivered automatically; wait with turn_id to reread it.";
+
 /** The collapsed body of a settled wait: what the child said, or why it stopped. */
 function collapsedWaitBody(
   details: WaitRenderDetails,
@@ -593,6 +596,9 @@ function collapsedWaitBody(
     const activity = latestProgressActivity(details.agent.recent_activity ?? []);
     return activity.length > 0 ? new ActivityLines(activity, theme) : undefined;
   }
+  if (details.already_delivered) {
+    return collapsedTextPreview(theme.fg("muted", ALREADY_DELIVERED_TEXT), theme);
+  }
   const output = details.output ?? "";
   if (status === "completed") {
     return output ? collapsedMarkdownPreview(output, theme) : undefined;
@@ -669,7 +675,9 @@ function renderWaitResult(
     );
   }
   const output = details.output ?? "";
-  if (status === "completed") {
+  if (details.already_delivered) {
+    appendTextSection(container, theme, "Output", ALREADY_DELIVERED_TEXT);
+  } else if (status === "completed") {
     if (output.length > 0) {
       appendComponentSection(
         container,

package/src/minimal-subagents-session-wire.ts

@@ -36,6 +36,7 @@ const DeliveryEvidenceMessageSchema = Type.Object({
 /** Parses durable custom-message and wait-tool Delivery Evidence details. */
 export const DeliveryEvidenceDetailsSchema = Type.Object({
   event: Type.Optional(Type.String()),
+  already_delivered: Type.Optional(Type.Boolean()),
   source_agent_id: Type.String(),
   source_turn_id: Type.String(),
   delivery_id: Type.Optional(Type.String()),

package/src/minimal-subagents-sessions.ts

@@ -503,8 +503,13 @@ export function findDeliveryEvidence(
           ))
       );
     }
-    // A message or timeout wait result never carried the turn's terminal result.
-    if (waitToolResult && (details.event === "message" || details.event === "timeout"))
+    // A message, timeout, or already-delivered wait result never carried the turn's terminal result.
+    if (
+      waitToolResult &&
+      (details.event === "message" ||
+        details.event === "timeout" ||
+        details.already_delivered === true)
+    )
       return false;
     return details.source_agent_id === sourceAgentId && details.source_turn_id === sourceTurnId;
   });

package/src/minimal-subagents-tools.ts

@@ -38,6 +38,7 @@ import type {
   DeleteResult,
   SpawnResult,
   StatusResult,
+  WaitDeliveredTurnResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
@@ -197,6 +198,22 @@ function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   };
 }
 
+/**
+ * One line saying an already-delivered result is not repeated and how to reread it, followed by
+ * any Coordination Messages the wait drained, which the parent has not seen yet.
+ */
+function alreadyDeliveredContent(
+  result: WaitDeliveredTurnResult,
+): AgentToolResult<WaitResult>["content"] {
+  const notice = `Result of ${result.agent_id} turn ${result.turn_id} (${result.status}) was already delivered automatically; call subagent_wait with turn_id "${result.turn_id}" to reread it.`;
+  if (!result.messages) return [{ type: "text", text: notice }];
+  const messages = truncateHead(JSON.stringify({ messages: result.messages }, null, 2), {
+    maxBytes: DEFAULT_MAX_BYTES,
+    maxLines: DEFAULT_MAX_LINES,
+  });
+  return [{ type: "text", text: `${notice}\n${messages.content}` }];
+}
+
 /**
  * Report a failed operation that still carries declared output: the model sees an error and
  * codemode scripts receive `structuredContent` instead of a data-less rejection.
@@ -313,7 +330,7 @@ export function createCoordinatorToolDefinitions(
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn whose result you have neither claimed nor received, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. A settled turn returns event=turn, with any queued messages in messages; waiting again returns the same result. Timeout returns event=timeout with detailed child status and never cancels the child.",
+      "Wait for one direct child's oldest observable turn whose result you have neither claimed nor received, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. A settled turn returns event=turn, with any queued messages in messages; waiting again returns a result you claimed in full. Without turn_id, a result already delivered to you automatically returns event=turn with already_delivered=true and no output; pass its turn_id to reread it. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {
@@ -358,7 +375,10 @@ export function createCoordinatorToolDefinitions(
             source_turn_id: result.turn_id,
           };
           return {
-            ...structuredToolResult(result),
+            content:
+              "already_delivered" in result
+                ? alreadyDeliveredContent(result)
+                : structuredToolResult(result).content,
             details,
             structuredContent: JSON.parse(JSON.stringify(details)),
           };

package/src/minimal-subagents-types.ts

@@ -98,6 +98,19 @@ export interface WaitTurnResult extends TurnResult {
   messages?: WaitMessageResult[];
 }
 
+/**
+ * Reports that a default wait selected a terminal turn whose result was already delivered
+ * automatically, handed or settled, so the output is not repeated; an explicit `turn_id` rereads it.
+ */
+export interface WaitDeliveredTurnResult extends Pick<
+  TurnResult,
+  "agent_id" | "turn_id" | "status"
+> {
+  event: "turn";
+  already_delivered: true;
+  messages?: WaitMessageResult[];
+}
+
 /** Reports an observational wait timeout with the current detailed child status. */
 export interface WaitTimeoutResult {
   event: "timeout";
@@ -110,7 +123,11 @@ export interface WaitTimeoutResult {
 }
 
 /** Reports one message, terminal turn, or timeout returned by subagent_wait. */
-export type WaitResult = WaitMessageResult | WaitTurnResult | WaitTimeoutResult;
+export type WaitResult =
+  | WaitMessageResult
+  | WaitTurnResult
+  | WaitDeliveredTurnResult
+  | WaitTimeoutResult;
 
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {