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

package/src/minimal-subagents-extension.ts

@@ -17,6 +17,7 @@ import {
   type SessionShutdownEvent,
   type SessionStartEvent,
   type SessionTreeEvent,
+  type TurnEndEvent,
 } from "@earendil-works/pi-coding-agent";
 import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
 import {
@@ -182,9 +183,12 @@ function rootCallerSnapshot(pi: ExtensionAPI, context: ExtensionContext): Caller
 function createRootConversationEndpoint(
   pi: ExtensionAPI,
   context: ExtensionContext,
+  onSteer: () => void,
 ): RootConversationEndpoint {
   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();
       pi.sendMessage(
         {
           customType: message.customType,
@@ -505,6 +509,9 @@ export class MinimalSubagentsLifecycleController {
   private readonly coordinatorOperations: CoordinatorToolOperations = {
     spawn: (...args) => this.requireCoordinator().spawn(...args),
     inspectStatus: (...args) => this.requireCoordinator().inspectStatus(...args),
+    previewActiveTurn: (...args) => this.requireCoordinator().previewActiveTurn(...args),
+    inspectActiveTurnTranscript: (...args) =>
+      this.requireCoordinator().inspectActiveTurnTranscript(...args),
     sendAgentMessage: (...args) => this.requireCoordinator().sendAgentMessage(...args),
     wait: (...args) => this.requireCoordinator().wait(...args),
     status: (...args) => this.requireCoordinator().status(...args),
@@ -514,6 +521,7 @@ export class MinimalSubagentsLifecycleController {
   private uiController: MinimalSubagentsUiController | undefined;
   private statusPanelController: MinimalSubagentsStatusPanelController | undefined;
   private viewerShortcut: ReturnType<typeof installViewerShortcut> | undefined;
+  private unwatchRootTurnEnds: (() => void) | undefined;
   private accessSession: ActiveSubagentAccessSession | undefined;
   private preparedFork:
     | { sourceSessionFile: string; selectedBranchSnapshot: RegistrySnapshot }
@@ -525,7 +533,10 @@ export class MinimalSubagentsLifecycleController {
     private readonly effects: MinimalSubagentsLifecycleEffects,
   ) {}
 
-  /** Register stable tools, renderers, and the six Pi lifecycle event handlers. */
+  /**
+   * Register stable tools, renderers, and the six static Pi lifecycle event handlers. `turn_end` is
+   * registered only while a result waits in the root's steer queue (`watchRootTurnEnds`).
+   */
   register(): void {
     const rootTools = createCoordinatorToolDefinitions({
       coordinator: this.coordinatorOperations,
@@ -549,6 +560,7 @@ export class MinimalSubagentsLifecycleController {
     this.pi.on("session_before_fork", (event, context) => this.prepareSessionFork(event, context));
     this.pi.on("session_tree", (event, context) => this.restoreSessionTree(event, context));
     this.pi.on("message_end", (event, context) => this.reconcileMessageDelivery(event, context));
+    this.pi.on("agent_start", () => this.deliverDiscardedRootResults());
     this.pi.on("session_shutdown", (event, context) => this.shutdownSession(event, context));
   }
 
@@ -642,9 +654,10 @@ export class MinimalSubagentsLifecycleController {
     });
     activeCoordinator = new MinimalSubagentsCoordinator({
       sessions: sessionFactory,
-      root: createRootConversationEndpoint(this.pi, context),
+      root: createRootConversationEndpoint(this.pi, context, () => this.watchRootTurnEnds()),
       maxSubagentDepth: minimalSubagentsConfig.maxSubagentDepth,
       toolsets: minimalSubagentsConfig.toolsets,
+      modelRoles: minimalSubagentsConfig.modelRoles,
       registry: {
         rootSessionId,
         append: (registryEvent) => this.pi.appendEntry(REGISTRY_ENTRY_TYPE, registryEvent),
@@ -922,16 +935,63 @@ export class MinimalSubagentsLifecycleController {
     _context: ExtensionContext,
   ): Promise<void> {
     if (!this.coordinator) return;
+    this.coordinator.recordRootMessageEnd();
     if (event.message.role === "toolResult" || event.message.role === "custom") {
       await this.coordinator.reconcileDeliveries();
       this.uiController?.refresh();
     }
   }
 
+  /**
+   * Watch root turn boundaries while a result waits in the root's steer queue. Pi builds a boundary
+   * preview for every `turn_end` while any handler listens, so the handler is removed again once no
+   * queued result remains.
+   */
+  private watchRootTurnEnds(): void {
+    this.unwatchRootTurnEnds ??= this.pi.on("turn_end", (event, context) =>
+      this.requeueDiscardedRootResults(event, context),
+    );
+  }
+
+  private stopWatchingRootTurnEnds(): void {
+    this.unwatchRootTurnEnds?.();
+    this.unwatchRootTurnEnds = undefined;
+  }
+
+  /**
+   * Pi gives extensions no queue-cleared event, so Esc's discarded steers are found here: the turn
+   * boundary's pending-message preview is empty. Returns nothing, so the transcript, system prompt,
+   * and tools are unchanged.
+   *
+   * A queue clear without an abort (dequeue, RPC `clear_queue`) leaves the run going, so released
+   * results are steered back at once and Pi's poll after this boundary takes them in the same run.
+   * Esc aborts the run, so its released results wait for the root's next run.
+   */
+  private requeueDiscardedRootResults(event: TurnEndEvent, context: ExtensionContext): void {
+    if (!this.coordinator) {
+      this.stopWatchingRootTurnEnds();
+      return;
+    }
+    if (event.context.pendingMessages.length === 0) {
+      this.coordinator.requeueDiscardedRootResults();
+      if (context.signal && !context.signal.aborted) {
+        this.coordinator.deliverDiscardedRootResults();
+      }
+      this.uiController?.refresh();
+    }
+    if (!this.coordinator.hasQueuedRootHandOffs()) this.stopWatchingRootTurnEnds();
+  }
+
+  /** Re-send discarded results into a root run that just started; recovery never starts one. */
+  private deliverDiscardedRootResults(): void {
+    this.coordinator?.deliverDiscardedRootResults();
+  }
+
   private async shutdownSession(
     event: SessionShutdownEvent,
     context: ExtensionContext,
   ): Promise<void> {
+    this.stopWatchingRootTurnEnds();
     this.viewerShortcut?.dispose();
     this.viewerShortcut = undefined;
     this.statusPanelController?.dispose();

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

@@ -56,6 +56,7 @@ const ToolSelectionWireSchema = Type.Union([
 
 /** Parses persisted immutable Launch Contracts without coercion. */
 export const RegistryLaunchContractWireSchema = Type.Object({
+  role: Type.Optional(NonEmptyStringSchema),
   session_context: Type.Union([
     Type.Literal("inherit"),
     Type.Literal("compact"),

package/src/minimal-subagents-registry.ts

@@ -1,6 +1,8 @@
 import type { JsonValue } from "@earendil-works/pi-ai";
 import { Value } from "typebox/value";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
+import { isModelRoleName } from "./minimal-subagents-config.js";
+import { normalizeMinimalSubagentsUsage } from "./minimal-subagents-usage.js";
 import {
   createDeliveryLedger,
   deliveryLedgerSnapshot,
@@ -280,7 +282,8 @@ function cloneRegistryTurnResult(value: RegistryTurnResultWire): TurnResult {
     output: value.output,
   };
   if (value.error !== undefined) result.error = value.error;
-  if (value.usage !== undefined) result.usage = structuredClone(value.usage);
+  // Records from older versions may lack optional usage counters.
+  if (value.usage !== undefined) result.usage = normalizeMinimalSubagentsUsage(value.usage);
   if (value.elapsed_ms !== undefined) result.elapsed_ms = value.elapsed_ms;
   return result;
 }
@@ -302,6 +305,7 @@ function parseRegistryLaunchContract(
 ): LaunchContract | undefined {
   if (
     !isCanonicalModelId(value.model) ||
+    (value.role !== undefined && !isModelRoleName(value.role)) ||
     !isUniqueNonEmptyStringArray(value.ordinary_tools) ||
     !excludesCoordinatorToolNames(value.ordinary_tools) ||
     (Array.isArray(value.tools) &&
@@ -318,6 +322,7 @@ function parseRegistryLaunchContract(
     ordinary_tools: [...value.ordinary_tools],
   };
   if (value.delegation !== undefined) launchContract.delegation = value.delegation;
+  if (value.role !== undefined) launchContract.role = value.role;
   return launchContract;
 }
 

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

@@ -23,6 +23,7 @@ const RenderUsageSchema = Type.Object({
 });
 
 const RenderLaunchContractSchema = Type.Object({
+  role: Type.Optional(Type.String()),
   session_context: Type.Optional(Type.String()),
   project_context: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
@@ -87,9 +88,11 @@ const SpawnCallArgumentsSchema = Type.Object({
   agent_id: Type.Optional(Type.String()),
   session_context: Type.Optional(Type.String()),
   project_context: Type.Optional(Type.String()),
+  role: Type.Optional(Type.String()),
   model: Type.Optional(Type.String()),
   thinking_level: Type.Optional(Type.String()),
   delegation: Type.Optional(Type.String()),
+  tools: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())])),
 });
 const MessageCallArgumentsSchema = Type.Object({
   agent_id: Type.Optional(Type.String()),
@@ -113,6 +116,7 @@ const CurrentMessageDetailsSchema = Type.Object({
   agent_id: Type.String(),
   message_id: Type.Optional(Type.String()),
   disposition: Type.String(),
+  turn_id: Type.Optional(Type.String()),
   behavior: Type.Optional(Type.String()),
   error: Type.Optional(Type.String()),
 });
@@ -209,7 +213,7 @@ const CoordinatorAgentSummaryOutputSchema = Type.Object({
   latest_activity_at: Type.Optional(Type.String()),
   task: Type.Optional(Type.String()),
   child_count: Type.Number(),
-  children: Type.Array(Type.Unknown()),
+  children: Type.Optional(Type.Array(Type.Unknown())),
   model: Type.String(),
   thinking_level: Type.String(),
 });
@@ -217,6 +221,7 @@ const CoordinatorAgentDetailOutputSchema = Type.Object({
   ...CoordinatorAgentSummaryOutputSchema.properties,
   session_file: Type.Optional(Type.String()),
   launch_contract: Type.Object({
+    role: Type.Optional(Type.String()),
     session_context: Type.String(),
     project_context: Type.String(),
     model: Type.String(),
@@ -266,7 +271,11 @@ export const CoordinatorToolOutputSchemas = {
     agent_id: Type.String(),
     turn_id: Type.String(),
     status: Type.Literal("running"),
-    agent: Type.Optional(CoordinatorAgentDetailOutputSchema),
+    model: Type.String(),
+    thinking_level: Type.String(),
+    tools: Type.Array(Type.String()),
+    delegation: Type.Union([Type.Literal("none"), Type.Literal("fanout")]),
+    warnings: Type.Optional(Type.Array(Type.String())),
   }),
   agent_message: Type.Object({
     agent_id: Type.String(),
@@ -274,8 +283,10 @@ export const CoordinatorToolOutputSchemas = {
     disposition: Type.Union([
       Type.Literal("delivered-via-wait"),
       Type.Literal("queued"),
+      Type.Literal("started-turn"),
       Type.Literal("failed"),
     ]),
+    turn_id: Type.Optional(Type.String()),
     error: Type.Optional(Type.String()),
   }),
   subagent_wait: Type.Union([
@@ -319,6 +330,25 @@ const WaitRenderDetailsSchema = Type.Union([
   WaitTimeoutDetailsSchema,
 ]);
 
+/** Partial `subagent_wait` updates: elapsed wait time and, while the child runs, its progress. */
+const WaitProgressRenderDetailsSchema = Type.Object({
+  agent_id: Type.String(),
+  status: Type.Literal("waiting"),
+  elapsed_ms: Type.Number(),
+  turn_id: Type.Optional(Type.String()),
+  tool_calls: Type.Optional(Type.Number()),
+});
+
+export type WaitProgressRenderDetails = Static<typeof WaitProgressRenderDetailsSchema>;
+
+/** Parse one partial `subagent_wait` progress update. */
+export function parseWaitProgressDetails(
+  // oxlint-disable-next-line anti-slop/no-unknown-parameters -- Partial tool details are unparsed until the progress schema checks them below.
+  details: unknown,
+): WaitProgressRenderDetails | undefined {
+  return Value.Check(WaitProgressRenderDetailsSchema, details) ? details : undefined;
+}
+
 export type SpawnCallArguments = Static<typeof SpawnCallArgumentsSchema>;
 export type MessageCallArguments = Static<typeof MessageCallArgumentsSchema>;
 export type WaitCallArguments = Static<typeof WaitCallArgumentsSchema>;
@@ -331,6 +361,7 @@ export type StatusRenderDetails = Static<typeof StatusDetailsSchema>;
 export type CancelRenderDetails = Static<typeof CancelDetailsSchema>;
 export type DeleteRenderDetails = Static<typeof DeleteDetailsSchema>;
 export type RenderStatusAgent = Static<typeof RenderStatusAgentSchema>;
+export type RenderRecentActivity = Static<typeof RenderRecentActivitySchema>;
 
 /** Raw tool arguments supplied by Pi's tool-rendering interface. */
 export type CoordinatorToolCallInput = Parameters<NonNullable<ToolDefinition["renderCall"]>>[0];