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

package/README.md

@@ -49,7 +49,9 @@ From this package checkout, load the source directly with
    pass `turn_id` to re-read a turn whose result is still retained, claimed or
    not.
 4. `subagent_status` inspects children; `subagent_cancel` stops work but keeps
-   the session; `subagent_delete` removes it. Deleted IDs cannot be reused.
+   the session; `subagent_delete` removes it. Deleted IDs cannot be reused, and
+   spawning with an existing `agent_id` fails with that child's state and the
+   next step (`agent_message`, `subagent_delete`, or another `agent_id`).
 
 ## Configuration
 
@@ -279,10 +281,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
+A running child's `latest_activity_at` advances with the timestamps of its latest
+messages and tool results. 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. Children target only direct children; the Root Agent
+assistant message but omits image data. Timeout Wait Events carry only a compact
+progress snapshot. Children target only direct children; the Root Agent
 may inspect any descendant. Model-facing status reports a `child_count` but no
 nested `children` summaries. Reported `usage` always includes `cacheWrite1h`
 and `reasoning`, as `0` when the provider reports none. `subagent_cancel`
@@ -351,8 +354,11 @@ 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"`
-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
+with the requested turn identity and a compact, bounded progress snapshot
+(`state`, `elapsed_ms`, `latest_activity_at`, `total_tokens`, and the labels of
+the last three Recent Activity items as `recent_activity_labels`), under about 1 KB. It omits the task and
+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.
 
 The persisted Delivery Ledger records Coordination Messages, terminal results,

package/package.json

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

package/src/minimal-subagents-coordinator.ts

@@ -69,12 +69,17 @@ import type {
   StatusResult,
   TurnResult,
   WaitMessageResult,
+  WaitTimeoutResult,
   WaitDeliveredTurnResult,
   WaitResult,
 } from "./minimal-subagents-types.js";
 
 const FRIENDLY_AGENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const RESERVED_AGENT_IDS = new Set(["root", "parent"]);
+/** Recent Activity labels a timed-out wait reports. */
+const WAIT_TIMEOUT_ACTIVITY_LIMIT = 3;
+/** Characters kept of each label so a timed-out wait stays bounded whatever a tool is named. */
+const WAIT_TIMEOUT_LABEL_MAX_LENGTH = 80;
 const RECENT_MESSAGE_LIMIT = 20;
 const DEFAULT_AUTOMATIC_DELIVERY_GRACE_MS = 1_000;
 
@@ -260,7 +265,7 @@ export class MinimalSubagentsCoordinator {
       );
     }
     if (this.agents.has(agentId) || this.pendingAgentIds.has(agentId)) {
-      throw new Error(`Minimal subagents duplicate agent ID: ${agentId}`);
+      throw new Error(this.duplicateAgentIdMessage(agentId));
     }
 
     const sessionContext = parameters.session_context ?? "omit";
@@ -481,7 +486,7 @@ export class MinimalSubagentsCoordinator {
     }
   }
 
-  /** Wait for one exact turn, returning detailed child status if the waiter times out. */
+  /** Wait for one exact turn, returning compact child progress if the waiter times out. */
   wait(
     callerId: string,
     agentId: string,
@@ -546,7 +551,7 @@ export class MinimalSubagentsCoordinator {
             agent_id: agentId,
             turn_id: turnId,
             timeout_ms: timeoutMs,
-            agent: this.buildAgentDetail(agent, false),
+            ...this.buildWaitTimeoutProgress(agent),
           });
         }, timeoutMs);
       }
@@ -1838,6 +1843,20 @@ export class MinimalSubagentsCoordinator {
     this.removeSettledEmptyTurnClaim(delivery.source_agent_id, delivery.source_turn_id);
   }
 
+  /** Name an existing agent ID's state and the next steps that are valid for that state. */
+  private duplicateAgentIdMessage(agentId: string): string {
+    const prefix = `Minimal subagents duplicate agent ID: ${agentId}`;
+    const existing = this.agents.get(agentId);
+    if (!existing) {
+      return `${prefix} is still being created; retry shortly or choose another agent_id`;
+    }
+    if (existing.availability === "unavailable") {
+      return `${prefix} already exists (unavailable). Use subagent_delete to remove it (a deleted ID cannot be reused), or choose another agent_id.`;
+    }
+    const state = existing.active_turn_id ? "running" : "idle";
+    return `${prefix} already exists (${state}). Use agent_message to continue it, subagent_delete to remove it (a deleted ID cannot be reused), or choose another agent_id.`;
+  }
+
   private buildAgentSummary(agent: PersistedAgent, includeDescendants = true): AgentSummary {
     const directChildren = this.childrenOf(agent.agent_id);
     const elapsed = agent.active_turn_started_at
@@ -1860,7 +1879,7 @@ export class MinimalSubagentsCoordinator {
       ...runtimeProfile,
       tools: runtime?.getActiveToolNames?.() ?? [...agent.launch_contract.ordinary_tools],
       elapsed_ms: elapsed ?? agent.latest_result?.elapsed_ms,
-      latest_activity_at: agent.latest_activity_at ?? agent.created_at,
+      latest_activity_at: this.latestActivityAt(agent, runtime),
       task: agent.task,
       child_count: directChildren.length,
     };
@@ -1870,6 +1889,41 @@ export class MinimalSubagentsCoordinator {
     return summary;
   }
 
+  /**
+   * The persisted activity time, advanced by the timestamps of the messages and tool results a
+   * running child has produced since. Only running children can have newer unpersisted activity.
+   */
+  private latestActivityAt(agent: PersistedAgent, runtime: ChildAgentRuntime | undefined): string {
+    const persisted = agent.latest_activity_at ?? agent.created_at;
+    if (!agent.active_turn_id || !runtime) return persisted;
+    const persistedMs = Date.parse(persisted);
+    let latestMs = persistedMs;
+    for (const { timestamp } of runtime.snapshotActivityMessages()) {
+      if (Number.isFinite(timestamp) && timestamp > latestMs) latestMs = timestamp;
+    }
+    return latestMs > persistedMs ? new Date(latestMs).toISOString() : persisted;
+  }
+
+  /** 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"> {
+    const summary = this.buildAgentSummary(agent, false);
+    const runtime = this.runtimes.get(agent.agent_id);
+    const messages =
+      runtime?.snapshotActivityMessages() ?? this.inspectTranscript(agent.agent_id).messages;
+    const usage = runtime?.getUsage() ?? agent.latest_result?.usage;
+    return {
+      state: summary.state,
+      elapsed_ms: summary.elapsed_ms,
+      latest_activity_at: summary.latest_activity_at,
+      total_tokens: usage?.totalTokens,
+      recent_activity_labels: buildRecentAgentActivity(messages)
+        .slice(-WAIT_TIMEOUT_ACTIVITY_LIMIT)
+        .map((activity) => activity.label.slice(0, WAIT_TIMEOUT_LABEL_MAX_LENGTH)),
+    };
+  }
+
   private buildAgentDetail(agent: PersistedAgent, includeDescendants = true): AgentDetail {
     const summary = this.buildAgentSummary(agent, includeDescendants);
     const runtime = this.runtimes.get(agent.agent_id);

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

@@ -154,7 +154,13 @@ const WaitTimeoutDetailsSchema = Type.Object({
   agent_id: Type.String(),
   turn_id: Type.String(),
   timeout_ms: Type.Number(),
-  agent: RenderStatusAgentSchema,
+  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())),
+  /** Pre-compact timeout results carried the full child status. */
+  agent: Type.Optional(RenderStatusAgentSchema),
 });
 const StatusDetailsSchema = Type.Union([
   Type.Object({
@@ -313,7 +319,11 @@ export const CoordinatorToolOutputSchemas = {
       agent_id: Type.String(),
       turn_id: Type.String(),
       timeout_ms: Type.Number(),
-      agent: CoordinatorAgentDetailOutputSchema,
+      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,
     }),
   ]),

package/src/minimal-subagents-rendering.ts

@@ -585,6 +585,16 @@ function renderWaitProgress(
 /** 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 activity labels of a timeout result, including pre-compact results that carried the full status. */
+function timeoutActivityLabels(
+  details: Extract<WaitRenderDetails, { event: "timeout" }>,
+): readonly string[] {
+  return (
+    details.recent_activity_labels ??
+    latestProgressActivity(details.agent?.recent_activity ?? []).map((entry) => entry.label)
+  );
+}
+
 /** The collapsed body of a settled wait: what the child said, or why it stopped. */
 function collapsedWaitBody(
   details: WaitRenderDetails,
@@ -593,8 +603,10 @@ function collapsedWaitBody(
 ): Component | undefined {
   if (details.event === "message") return collapsedTextPreview(details.message, theme);
   if (details.event === "timeout") {
-    const activity = latestProgressActivity(details.agent.recent_activity ?? []);
-    return activity.length > 0 ? new ActivityLines(activity, theme) : undefined;
+    const labels = timeoutActivityLabels(details);
+    return labels.length > 0
+      ? collapsedTextPreview(theme.fg("dim", labels.join(" \u00b7 ")), theme)
+      : undefined;
   }
   if (details.already_delivered) {
     return collapsedTextPreview(theme.fg("muted", ALREADY_DELIVERED_TEXT), theme);
@@ -627,7 +639,9 @@ function renderWaitResult(
     details.event === "timeout" ? details.timeout_ms : details.elapsed_ms,
   );
   const usage = details.event === "timeout" ? undefined : details.usage;
-  const tokens = formatSubagentTokenCount(usage?.totalTokens);
+  const tokens = formatSubagentTokenCount(
+    details.event === "timeout" ? details.total_tokens : usage?.totalTokens,
+  );
   const drainedMessageCount =
     details.event === "message" || details.event === "timeout"
       ? 0
@@ -658,12 +672,15 @@ function renderWaitResult(
     return container;
   }
   if (details.event === "timeout") {
-    appendComponentSection(
-      container,
-      theme,
-      "Child status",
-      renderDetailedStatusAgent(details.agent, options, theme),
+    container.addChild(
+      renderLabelValue(theme, "State", details.state ?? details.agent?.state ?? "unknown"),
     );
+    if (details.latest_activity_at) {
+      container.addChild(renderLabelValue(theme, "Latest activity", details.latest_activity_at));
+    }
+    const labels = timeoutActivityLabels(details);
+    if (labels.length > 0)
+      appendTextSection(container, theme, "Recent activity", labels.join("\n"));
     return container;
   }
   if (details.messages && details.messages.length > 0) {

package/src/minimal-subagents-tools.ts

@@ -330,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 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.",
+      "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 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.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {

package/src/minimal-subagents-types.ts

@@ -111,15 +111,20 @@ export interface WaitDeliveredTurnResult extends Pick<
   messages?: WaitMessageResult[];
 }
 
-/** Reports an observational wait timeout with the current detailed child status. */
+/** 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;
-  /** Detailed child status captured when the timeout callback won. */
-  agent: AgentDetail;
+  state: AgentState;
+  elapsed_ms?: number;
+  latest_activity_at?: string;
+  /** Total tokens the child has used, when usage is known. */
+  total_tokens?: number;
+  /** Labels of the child's last few Recent Activity items, oldest first. */
+  recent_activity_labels: string[];
 }
 
 /** Reports one message, terminal turn, or timeout returned by subagent_wait. */