@ian-pascoe/pi-minimal-subagents 0.14.1 → 0.16.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
 
@@ -274,18 +276,21 @@ creation; reloading does not silently broaden them. The default maximum depth
 is two levels beneath the interactive Root Agent.
 
 The extension registers six coordinator tools for the Root Agent and fanout
-children: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
-`subagent_cancel`, and `subagent_delete`. Ordinary non-fanout children receive
-only the three adjacent-coordination tools: `agent_message`, `subagent_wait`,
-and `subagent_status`.
+children below the depth cap: `subagent`, `agent_message`, `subagent_wait`, `subagent_status`,
+`subagent_cancel`, and `subagent_delete`. Children that cannot spawn (delegation
+`none`, or fanout at the depth cap) have no children to wait on or inspect, so they
+receive only `agent_message`.
 
-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`
+and `reasoning`, as `0` when the provider reports none. Tool-result text and
+`structuredContent` round every `usage.cost` field to six decimal places of USD;
+exact values stay in session data. `subagent_cancel`
 lists in `affected_agent_ids` only agents whose active turns it cancelled.
 
 `session_context` defaults to `omit`: the child starts with only its system
@@ -351,8 +356,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.16.0",
   "private": false,
   "description": "Persistent nested subagents with bounded delegation for Pi",
   "keywords": [

package/src/minimal-subagents-context.ts

@@ -353,7 +353,7 @@ export function buildSubagentSystemPrompt(
 ): string {
   const coordinatorBoundary = options.canSpawn
     ? "Coordinator tools support subagent, agent_message, subagent_wait, subagent_status, subagent_cancel, and subagent_delete. Wait, status, cancel, and delete target direct children only; recursive cancel and delete may affect a child's subtree."
-    : "Coordinator tools support agent_message, subagent_wait, and subagent_status; wait and status target direct children only.";
+    : "Coordinator tools support only agent_message; you have no children to wait on or inspect.";
   const delegationBoundary = options.canSpawn
     ? [
         "You have explicit fanout responsibility for this assigned task.",

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({
@@ -266,7 +272,10 @@ const CoordinatorWaitSourceOutputSchema = {
   source_turn_id: Type.String(),
 };
 
-/** Final details schemas exposed to CodeMode for the six coordinator tools. */
+/**
+ * Final details schemas exposed to CodeMode for the six coordinator tools. `structuredContent`
+ * matches them with every `usage.cost` field rounded for presentation.
+ */
 export const CoordinatorToolOutputSchemas = {
   subagent: Type.Object({
     agent_id: Type.String(),
@@ -313,7 +322,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

@@ -13,6 +13,7 @@ import type { TUI } from "@earendil-works/pi-tui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import { withTroubleshootingHint } from "./troubleshooting-skill.js";
 import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
+import { roundMinimalSubagentsUsageCosts } from "./minimal-subagents-usage.js";
 import {
   renderCoordinatorToolCall,
   renderCoordinatorToolResult,
@@ -42,11 +43,8 @@ import type {
   WaitResult,
 } from "./minimal-subagents-types.js";
 
-const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
-  "agent_message",
-  "subagent_wait",
-  "subagent_status",
-]);
+/** A child that cannot spawn can never have children, so only adjacent messaging is useful. */
+const NON_SPAWNING_CHILD_COORDINATOR_TOOL_NAMES = new Set(["agent_message"]);
 
 /** Coordinator operations consumed by the six public coordinator tool definitions. */
 export type CoordinatorToolOperations = Pick<
@@ -183,10 +181,28 @@ function createCoordinatorToolRendering(
   };
 }
 
+/**
+ * Serialize a tool result with every nested `usage` cost rounded for presentation. Exact values
+ * stay in `details`, the Registry, and session data, which never pass through here.
+ */
+function stringifyWithRoundedUsageCosts(
+  result: CoordinatorToolResultDetails,
+  space?: number,
+): string {
+  // `JSON.stringify` types replacer values as `any`; a usage is recognized by key and `cost` object.
+  return JSON.stringify(
+    result,
+    (key, value) =>
+      key === "usage" && value?.cost ? roundMinimalSubagentsUsageCosts(value) : value,
+    space,
+  );
+}
+
 function structuredToolResult<TDetails extends CoordinatorToolResultDetails>(
   result: TDetails,
 ): AgentToolResult<TDetails> {
-  const json = JSON.stringify(result, null, 2);
+  // Presentation only: `details` keeps the exact values the session persists.
+  const json = stringifyWithRoundedUsageCosts(result, 2);
   const truncated = truncateHead(json, {
     maxBytes: DEFAULT_MAX_BYTES,
     maxLines: DEFAULT_MAX_LINES,
@@ -330,7 +346,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: {
@@ -380,7 +396,7 @@ export function createCoordinatorToolDefinitions(
                 ? alreadyDeliveredContent(result)
                 : structuredToolResult(result).content,
             details,
-            structuredContent: JSON.parse(JSON.stringify(details)),
+            structuredContent: JSON.parse(stringifyWithRoundedUsageCosts(details)),
           };
         });
       } finally {
@@ -483,5 +499,5 @@ export function createCoordinatorToolDefinitions(
   const allowFanoutTools = options.allowFanoutTools ?? options.callerId === "root";
   return allowFanoutTools
     ? coordinatorTools
-    : coordinatorTools.filter((tool) => ORDINARY_CHILD_COORDINATOR_TOOL_NAMES.has(tool.name));
+    : coordinatorTools.filter((tool) => NON_SPAWNING_CHILD_COORDINATOR_TOOL_NAMES.has(tool.name));
 }

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. */

package/src/minimal-subagents-usage.ts

@@ -33,3 +33,33 @@ export function addMinimalSubagentsUsage(
     },
   };
 }
+
+/**
+ * USD decimal places kept in model-visible and structured usage costs. Six places is one
+ * millionth of a dollar: finer than any single turn's cost is worth reading, yet coarse enough to
+ * drop the binary-float tails that summing many per-message costs produces.
+ */
+export const MINIMAL_SUBAGENTS_COST_DECIMALS = 6;
+
+const COST_SCALE = 10 ** MINIMAL_SUBAGENTS_COST_DECIMALS;
+
+function roundCost(value: number): number {
+  return Number.isFinite(value) ? Math.round(value * COST_SCALE) / COST_SCALE : value;
+}
+
+/**
+ * Return a clone whose cost fields are rounded for presentation. Each field rounds independently
+ * from its exact value, so `total` stays within half a unit per summed field of the rounded sum.
+ */
+export function roundMinimalSubagentsUsageCosts(usage: Usage): Usage {
+  return {
+    ...usage,
+    cost: {
+      input: roundCost(usage.cost.input),
+      output: roundCost(usage.cost.output),
+      cacheRead: roundCost(usage.cost.cacheRead),
+      cacheWrite: roundCost(usage.cost.cacheWrite),
+      total: roundCost(usage.cost.total),
+    },
+  };
+}