@ian-pascoe/pi-minimal-subagents 0.19.2 → 0.20.0

package/README.md

@@ -387,6 +387,18 @@ Launch Contract; targeted `subagent_status` returns the full detail.
 It removes only the waiter, leaving the child
 running and all pending delivery unclaimed. Abort signals remain errors.
 
+A wait that would block also ends early when a Queued Steer is pending for the
+caller's session, because Pi hands a steer to an agent only after every tool call in
+the current batch returns. It returns an `event: "steered"` Wait Event with the
+requested turn identity and the same compact progress snapshot as a timeout, and,
+like a timeout, removes only its waiter: nothing is claimed, the child is not
+cancelled, and later messages and the terminal result keep automatic fallback.
+A wait that starts while a steer is pending returns `steered` at once, but a
+retained result or pending Coordination Message is still returned first. Only steers
+count (a user's mid-run message, a parent's Coordination Message into a busy child, or
+another child's result steered into the caller); follow-ups never do. A child
+session's steer clears when its next turn starts or its run ends.
+
 The persisted Delivery Ledger records Coordination Messages, terminal results,
 globally increasing sequence, and wait ownership before delivery. Existing items
 retain their sequence; gaps from skipped malformed records are valid. Claims can

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ian-pascoe/pi-minimal-subagents",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [
@@ -31,7 +31,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@ian-pascoe/pi-utils": "^0.7.1",
+    "@ian-pascoe/pi-utils": "^0.9.0",
     "minimatch": "^10.2.6"
   },
   "peerDependencies": {

package/src/minimal-subagents-coordinator.ts

@@ -69,7 +69,8 @@ import type {
   StatusResult,
   TurnResult,
   WaitMessageResult,
-  WaitTimeoutResult,
+  WaitProgressSnapshot,
+  WaitSteeredResult,
   AutomaticDelivery,
   WaitDeliveredTurnResult,
   WaitResult,
@@ -106,6 +107,8 @@ interface TurnWaiter {
   timeout?: ReturnType<typeof setTimeout>;
   abortSignal?: AbortSignal;
   abortListener?: () => void;
+  steerSignal?: AbortSignal;
+  steerListener?: () => void;
 }
 
 interface PendingParentMessage {
@@ -489,13 +492,19 @@ export class MinimalSubagentsCoordinator {
     }
   }
 
-  /** Wait for one exact turn, returning compact child progress if the waiter times out. */
+  /**
+   * Wait for one exact turn, returning compact child progress if the waiter times out. Once
+   * `steerSignal` aborts, a Queued Steer is pending for the caller, so a wait that would block
+   * ends with a `steered` Steer Yield instead, claiming nothing and leaving the child running;
+   * `signal` still rejects as a cancellation.
+   */
   wait(
     callerId: string,
     agentId: string,
     timeoutMs?: number,
     signal?: AbortSignal,
     requestedTurnId?: string,
+    steerSignal?: AbortSignal,
   ): Promise<WaitResult> {
     this.assertAccepting();
     this.assertCallerExists(callerId);
@@ -538,8 +547,18 @@ export class MinimalSubagentsCoordinator {
       );
     }
 
+    if (steerSignal?.aborted && !signal?.aborted) {
+      return Promise.resolve(this.steeredWaitResult(agent, turnId));
+    }
+
     return new Promise<WaitResult>((resolve, reject) => {
-      const waiter: TurnWaiter = { callerId, resolve, reject, abortSignal: signal };
+      const waiter: TurnWaiter = {
+        callerId,
+        resolve,
+        reject,
+        abortSignal: signal,
+        steerSignal,
+      };
       let turnWaiters = this.waiters.get(key);
       if (!turnWaiters) {
         turnWaiters = new Set();
@@ -562,6 +581,13 @@ export class MinimalSubagentsCoordinator {
           });
         }, timeoutMs);
       }
+      if (steerSignal) {
+        waiter.steerListener = () => {
+          this.removeWaiter(key, waiter);
+          resolve(this.steeredWaitResult(agent, turnId));
+        };
+        steerSignal.addEventListener("abort", waiter.steerListener, { once: true });
+      }
       if (signal) {
         waiter.abortListener = () =>
           stopWaiting(new Error(`Minimal subagents wait cancelled for ${agentId}`));
@@ -571,6 +597,16 @@ export class MinimalSubagentsCoordinator {
     });
   }
 
+  /** The Steer Yield: the timeout's progress snapshot, with nothing claimed or cancelled. */
+  private steeredWaitResult(agent: PersistedAgent, turnId: string): WaitSteeredResult {
+    return {
+      event: "steered",
+      agent_id: agent.agent_id,
+      turn_id: turnId,
+      ...this.buildWaitTimeoutProgress(agent),
+    };
+  }
+
   /** Return direct-child status for a child caller; the root may inspect any descendant. */
   status(callerId: string, agentId?: string): StatusResult {
     this.assertCallerExists(callerId);
@@ -1918,9 +1954,7 @@ export class MinimalSubagentsCoordinator {
   }
 
   /** The compact progress a timed-out wait reports; `subagent_status` has the full detail. */
-  private buildWaitTimeoutProgress(
-    agent: PersistedAgent,
-  ): Omit<WaitTimeoutResult, "event" | "agent_id" | "turn_id" | "timeout_ms"> {
+  private buildWaitTimeoutProgress(agent: PersistedAgent): WaitProgressSnapshot {
     const summary = this.buildAgentSummary(agent, false);
     const runtime = this.runtimes.get(agent.agent_id);
     const messages =
@@ -2099,6 +2133,9 @@ export class MinimalSubagentsCoordinator {
     if (waiter.abortSignal && waiter.abortListener) {
       waiter.abortSignal.removeEventListener("abort", waiter.abortListener);
     }
+    if (waiter.steerSignal && waiter.steerListener) {
+      waiter.steerSignal.removeEventListener("abort", waiter.steerListener);
+    }
   }
 
   private resolveWaiterWithMessage(

package/src/minimal-subagents-extension.ts

@@ -20,6 +20,7 @@ import {
   type TurnEndEvent,
 } from "@earendil-works/pi-coding-agent";
 import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
+import { raiseQueuedSteer, trackQueuedSteers } from "@ian-pascoe/pi-utils/queued-steer";
 import { expandMessageOnClick, noticeText } from "@ian-pascoe/pi-utils/ui";
 import {
   createSubagentAccessBranchRecord,
@@ -189,7 +190,11 @@ function createRootConversationEndpoint(
   return {
     async queueCoordinatorMessage(message) {
       // A running root takes the message as a clearable steer; an idle root starts a turn with it.
-      if (!context.isIdle()) onSteer();
+      if (!context.isIdle()) {
+        onSteer();
+        // Pi hands the steer over only after the running tool batch ends, so waits there yield.
+        raiseQueuedSteer(context.sessionManager.getSessionId());
+      }
       pi.sendMessage(
         {
           customType: message.customType,
@@ -548,6 +553,7 @@ export class MinimalSubagentsLifecycleController {
    * registered only while a result waits in the root's steer queue (`watchRootTurnEnds`).
    */
   register(): void {
+    trackQueuedSteers(this.pi);
     const rootTools = createCoordinatorToolDefinitions({
       coordinator: this.coordinatorOperations,
       callerId: "root",

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

@@ -163,6 +163,16 @@ const WaitTimeoutDetailsSchema = Type.Object({
   /** Pre-compact timeout results carried the full child status. */
   agent: Type.Optional(RenderStatusAgentSchema),
 });
+const WaitSteeredDetailsSchema = Type.Object({
+  event: Type.Literal("steered"),
+  agent_id: Type.String(),
+  turn_id: Type.String(),
+  state: Type.Optional(Type.String()),
+  elapsed_ms: Type.Optional(Type.Number()),
+  latest_activity_at: Type.Optional(Type.String()),
+  total_tokens: Type.Optional(Type.Number()),
+  recent_activity_labels: Type.Optional(Type.Array(Type.String())),
+});
 const StatusDetailsSchema = Type.Union([
   Type.Object({
     parent_id: Type.Optional(Type.String()),
@@ -331,6 +341,17 @@ export const CoordinatorToolOutputSchemas = {
       recent_activity_labels: Type.Array(Type.String()),
       ...CoordinatorWaitSourceOutputSchema,
     }),
+    Type.Object({
+      event: Type.Literal("steered"),
+      agent_id: Type.String(),
+      turn_id: Type.String(),
+      state: Type.Union([Type.Literal("running"), Type.Literal("idle")]),
+      elapsed_ms: Type.Optional(Type.Number()),
+      latest_activity_at: Type.Optional(Type.String()),
+      total_tokens: Type.Optional(Type.Number()),
+      recent_activity_labels: Type.Array(Type.String()),
+      ...CoordinatorWaitSourceOutputSchema,
+    }),
   ]),
   subagent_status: Type.Union([
     Type.Object({
@@ -351,6 +372,7 @@ const WaitRenderDetailsSchema = Type.Union([
   WaitMessageDetailsSchema,
   WaitTurnDetailsSchema,
   WaitTimeoutDetailsSchema,
+  WaitSteeredDetailsSchema,
 ]);
 
 /** Partial `subagent_wait` updates: elapsed wait time and, while the child runs, its progress. */

package/src/minimal-subagents-rendering.ts

@@ -597,13 +597,20 @@ function alreadyDeliveredText(details: { delivery_pending?: boolean }): string {
   return details.delivery_pending ? DELIVERY_PENDING_TEXT : ALREADY_DELIVERED_TEXT;
 }
 
-/** The activity labels of a timeout result, including pre-compact results that carried the full status. */
-function timeoutActivityLabels(
-  details: Extract<WaitRenderDetails, { event: "timeout" }>,
-): readonly string[] {
+/** A wait that ended early with a progress snapshot: a timeout or a Steer Yield. */
+type WaitEarlyEndRenderDetails = Extract<WaitRenderDetails, { event: "timeout" | "steered" }>;
+
+function isWaitProgress(details: WaitRenderDetails): details is WaitEarlyEndRenderDetails {
+  return details.event === "timeout" || details.event === "steered";
+}
+
+/** The activity labels of a timeout or steered result, including pre-compact results that carried the full status. */
+function timeoutActivityLabels(details: WaitEarlyEndRenderDetails): readonly string[] {
   return (
     details.recent_activity_labels ??
-    latestProgressActivity(details.agent?.recent_activity ?? []).map((entry) => entry.label)
+    latestProgressActivity(
+      ("agent" in details ? details.agent?.recent_activity : undefined) ?? [],
+    ).map((entry) => entry.label)
   );
 }
 
@@ -614,7 +621,7 @@ function collapsedWaitBody(
   theme: MinimalSubagentsRenderTheme,
 ): Component | undefined {
   if (details.event === "message") return collapsedText(theme, details.message);
-  if (details.event === "timeout") {
+  if (isWaitProgress(details)) {
     const labels = timeoutActivityLabels(details);
     return labels.length > 0
       ? collapsedText(theme, theme.fg("dim", labels.join(" \u00b7 ")))
@@ -643,18 +650,18 @@ function renderWaitResult(
       ? "message"
       : details.event === "timeout"
         ? "timed out"
-        : details.status;
+        : details.event === "steered"
+          ? "steered"
+          : details.status;
   const duration = formatSubagentDuration(
     details.event === "timeout" ? details.timeout_ms : details.elapsed_ms,
   );
-  const usage = details.event === "timeout" ? undefined : details.usage;
+  const usage = isWaitProgress(details) ? undefined : details.usage;
   const tokens = formatSubagentTokenCount(
-    details.event === "timeout" ? details.total_tokens : usage?.totalTokens,
+    isWaitProgress(details) ? details.total_tokens : usage?.totalTokens,
   );
   const drainedMessageCount =
-    details.event === "message" || details.event === "timeout"
-      ? 0
-      : (details.messages?.length ?? 0);
+    details.event === "message" || isWaitProgress(details) ? 0 : (details.messages?.length ?? 0);
   const metrics = [
     duration,
     tokens ? `${tokens} tokens` : undefined,
@@ -674,10 +681,9 @@ function renderWaitResult(
     container.addChild(renderLabelValue(theme, "Message ID", details.message_id));
     return container;
   }
-  if (details.event === "timeout") {
-    container.addChild(
-      renderLabelValue(theme, "State", details.state ?? details.agent?.state ?? "unknown"),
-    );
+  if (isWaitProgress(details)) {
+    const legacyState = "agent" in details ? details.agent?.state : undefined;
+    container.addChild(renderLabelValue(theme, "State", details.state ?? legacyState ?? "unknown"));
     if (details.latest_activity_at) {
       container.addChild(renderLabelValue(theme, "Latest activity", details.latest_activity_at));
     }

package/src/minimal-subagents-result-text.ts

@@ -17,7 +17,9 @@ import type {
   ToolSelection,
   WaitDeliveredTurnResult,
   WaitMessageResult,
+  WaitProgressSnapshot,
   WaitResult,
+  WaitSteeredResult,
   WaitTimeoutResult,
   WaitTurnResult,
 } from "./minimal-subagents-types.js";
@@ -157,12 +159,8 @@ function formatWaitTurnText(result: WaitTurnResult): string {
   return `${lines.join("\n")}\n\n${result.output || "(no output)"}`;
 }
 
-/** The observational timeout snapshot; the wait never cancels the child. */
-function formatWaitTimeoutText(result: WaitTimeoutResult): string {
-  const lines = [
-    `Wait timed out after ${formatSubagentDuration(result.timeout_ms) ?? `${result.timeout_ms}ms`}; ${result.agent_id} is ${result.state} on turn ${result.turn_id} and was not cancelled.`,
-  ];
-  const progress = joinParts([
+function waitProgressText(result: WaitProgressSnapshot): string {
+  return joinParts([
     result.elapsed_ms === undefined
       ? undefined
       : `elapsed ${formatSubagentDuration(result.elapsed_ms)}`,
@@ -171,6 +169,27 @@ function formatWaitTimeoutText(result: WaitTimeoutResult): string {
       ? undefined
       : `${formatSubagentTokenCount(result.total_tokens)} tokens`,
   ]);
+}
+
+/** The observational timeout snapshot; the wait never cancels the child. */
+function formatWaitTimeoutText(result: WaitTimeoutResult): string {
+  const lines = [
+    `Wait timed out after ${formatSubagentDuration(result.timeout_ms) ?? `${result.timeout_ms}ms`}; ${result.agent_id} is ${result.state} on turn ${result.turn_id} and was not cancelled.`,
+  ];
+  const progress = waitProgressText(result);
+  if (progress) lines.push(progress);
+  if (result.recent_activity_labels.length > 0) {
+    lines.push(`recent activity: ${result.recent_activity_labels.join(", ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** The Steer Yield snapshot: a Queued Steer ended the wait, and the child was not cancelled. */
+function formatWaitSteeredText(result: WaitSteeredResult): string {
+  const lines = [
+    `Wait ended early: a queued steer is waiting for you. ${result.agent_id} is ${result.state} on turn ${result.turn_id} and was not cancelled; wait again to resume.`,
+  ];
+  const progress = waitProgressText(result);
   if (progress) lines.push(progress);
   if (result.recent_activity_labels.length > 0) {
     lines.push(`recent activity: ${result.recent_activity_labels.join(", ")}`);
@@ -178,7 +197,7 @@ function formatWaitTimeoutText(result: WaitTimeoutResult): string {
   return lines.join("\n");
 }
 
-/** Any Wait Event: a message, a settled or already-delivered turn, or a timeout. */
+/** Any Wait Event: a message, a settled or already-delivered turn, a timeout, or a steer yield. */
 export function formatWaitResultText(result: WaitResult): string {
   if ("already_delivered" in result) return formatWaitDeliveredText(result);
   switch (result.event) {
@@ -188,6 +207,8 @@ export function formatWaitResultText(result: WaitResult): string {
       return formatWaitTurnText(result);
     case "timeout":
       return formatWaitTimeoutText(result);
+    case "steered":
+      return formatWaitSteeredText(result);
   }
 }
 

package/src/minimal-subagents-sessions.ts

@@ -27,6 +27,7 @@ import {
   readAgentLineage,
   type AgentLineage,
 } from "@ian-pascoe/pi-utils/agent-lineage";
+import { raiseQueuedSteer, settleQueuedSteers } from "@ian-pascoe/pi-utils/queued-steer";
 import type { Static, TSchema } from "typebox";
 import { Value } from "typebox/value";
 import {
@@ -525,11 +526,12 @@ export function findDeliveryEvidence(
           ))
       );
     }
-    // A message, timeout, or already-delivered wait result never carried the turn's terminal result.
+    // A message, timeout, steer yield, or already-delivered wait result never carried the turn's terminal result.
     if (
       waitToolResult &&
       (details.event === "message" ||
         details.event === "timeout" ||
+        details.event === "steered" ||
         details.already_delivered === true)
     )
       return false;
@@ -631,6 +633,11 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     // Keep this child-only; AgentSession.setSteeringMode would overwrite the user's global setting.
     session.agent.steeringMode = "all";
     this.unsubscribe = session.subscribe((event) => {
+      // Child sessions get no Pi `input` events, so this runtime settles its own Queued Steers.
+      if (event.type === "turn_start" || event.type === "agent_end") {
+        settleQueuedSteers(this.sessionId);
+        return;
+      }
       if (event.type !== "entry_appended") return;
       if (
         event.entry.type === "custom_message" ||
@@ -641,6 +648,10 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
     });
   }
 
+  private get sessionId(): string {
+    return this.session.sessionManager.getSessionId();
+  }
+
   get sessionLeafId(): string | undefined {
     return this.session.sessionManager.getLeafId() ?? undefined;
   }
@@ -660,6 +671,8 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
   }
 
   runMessage(message: CoordinatorMessage): Promise<RuntimeTurnOutcome> {
+    // An idle child starts a turn with the message; a streaming child queues it as a steer.
+    if (this.session.isStreaming) raiseQueuedSteer(this.sessionId);
     return this.captureTurn(() =>
       this.session.sendCustomMessage(
         {
@@ -682,6 +695,7 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
       details: message.details,
       timestamp: Date.now(),
     });
+    raiseQueuedSteer(this.sessionId);
   }
 
   async abort(): Promise<void> {
@@ -691,6 +705,7 @@ class PiChildAgentRuntime implements ChildAgentRuntime {
 
   async dispose(): Promise<void> {
     this.unsubscribe();
+    settleQueuedSteers(this.sessionId);
     try {
       await this.observer?.dispose();
       // Let child extensions release services such as MCP server connections.

package/src/minimal-subagents-tools.ts

@@ -11,6 +11,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Container, type Component, type TUI } from "@earendil-works/pi-tui";
 import { acceptNullForOptionalArguments } from "@ian-pascoe/pi-utils/null-optional-arguments";
+import { watchQueuedSteer } from "@ian-pascoe/pi-utils/queued-steer";
 import { appendDurationFooter, callDurationFooter } from "@ian-pascoe/pi-utils/ui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import { withTroubleshootingHint } from "./troubleshooting-skill.js";
@@ -359,7 +360,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 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. If it was handed to you but is not yet in your conversation, delivery_pending=true and it arrives as a separate message; do not reread. Timeout returns a compact event=timeout (state, elapsed_ms, latest_activity_at, total_tokens, last few activity labels; use subagent_status for detail) 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. If it was handed to you but is not yet in your conversation, delivery_pending=true and it arrives as a separate message; do not reread. Timeout returns a compact event=timeout (state, elapsed_ms, latest_activity_at, total_tokens, last few activity labels; use subagent_status for detail) and never cancels the child. A queued steer for you returns event=steered with the same snapshot, immediately if one is already pending; it claims nothing and never cancels the child, so wait again to resume.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {
@@ -368,7 +369,7 @@ export function createCoordinatorToolDefinitions(
       idempotentHint: false,
       openWorldHint: false,
     },
-    async execute(_toolCallId, parameters, signal, onUpdate) {
+    async execute(_toolCallId, parameters, signal, onUpdate, context) {
       const startedAt = Date.now();
       const updateWaitingResult = () => {
         const details: WaitProgressDetails = {
@@ -389,6 +390,8 @@ export function createCoordinatorToolDefinitions(
       updateWaitingResult();
       const waitingInterval = setInterval(updateWaitingResult, 1_000);
       waitingInterval.unref?.();
+      // Pi hands a Queued Steer over only after this tool call returns, so end the wait for it.
+      const steerWatch = watchQueuedSteer(context.sessionManager.getSessionId());
       try {
         return await runCoordinatorToolActivity(options, async () => {
           const result = await options.coordinator.wait(
@@ -397,6 +400,7 @@ export function createCoordinatorToolDefinitions(
             parameters.timeout_ms,
             signal,
             parameters.turn_id,
+            steerWatch.signal,
           );
           const details = {
             ...result,
@@ -410,6 +414,7 @@ export function createCoordinatorToolDefinitions(
           };
         });
       } finally {
+        steerWatch.dispose();
         clearInterval(waitingInterval);
       }
     },

package/src/minimal-subagents-types.ts

@@ -119,13 +119,8 @@ export interface WaitDeliveredTurnResult extends Pick<
   messages?: WaitMessageResult[];
 }
 
-/** Reports an observational wait timeout with a compact, bounded child progress snapshot. */
-export interface WaitTimeoutResult {
-  event: "timeout";
-  agent_id: string;
-  turn_id: string;
-  /** Requested timeout duration that expired. */
-  timeout_ms: number;
+/** The compact, bounded child progress snapshot an observational wait ending early reports. */
+export interface WaitProgressSnapshot {
   state: AgentState;
   elapsed_ms?: number;
   latest_activity_at?: string;
@@ -135,12 +130,32 @@ export interface WaitTimeoutResult {
   recent_activity_labels: string[];
 }
 
-/** Reports one message, terminal turn, or timeout returned by subagent_wait. */
+/** Reports an observational wait timeout with a compact, bounded child progress snapshot. */
+export interface WaitTimeoutResult extends WaitProgressSnapshot {
+  event: "timeout";
+  agent_id: string;
+  turn_id: string;
+  /** Requested timeout duration that expired. */
+  timeout_ms: number;
+}
+
+/**
+ * Reports a Steer Yield: the wait ended early because a Queued Steer is pending for the caller,
+ * with the same progress snapshot as a timeout. The child keeps running and nothing is claimed.
+ */
+export interface WaitSteeredResult extends WaitProgressSnapshot {
+  event: "steered";
+  agent_id: string;
+  turn_id: string;
+}
+
+/** Reports one message, terminal turn, timeout, or steer yield returned by subagent_wait. */
 export type WaitResult =
   | WaitMessageResult
   | WaitTurnResult
   | WaitDeliveredTurnResult
-  | WaitTimeoutResult;
+  | WaitTimeoutResult
+  | WaitSteeredResult;
 
 /** Provides bounded hierarchy, usage, and best-known Runtime Profile data for one persistent agent. */
 export interface AgentSummary extends RuntimeProfile {