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

package/src/minimal-subagents-transcript.ts

@@ -0,0 +1,296 @@
+import { stripVTControlCharacters } from "node:util";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import { contentText } from "@earendil-works/pi-ai";
+import {
+  AssistantMessageComponent,
+  BashExecutionComponent,
+  BranchSummaryMessageComponent,
+  CompactionSummaryMessageComponent,
+  CustomMessageComponent,
+  ToolExecutionComponent,
+  UserMessageComponent,
+  type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { Container, Text, type Component, type TUI } from "@earendil-works/pi-tui";
+import {
+  ACTIVITY_RAIL_WIDTH,
+  drawActivityRail,
+  renderMinimalSubagentsMessage,
+  renderMinimalSubagentsResult,
+  type MinimalSubagentsRenderTheme,
+} from "./minimal-subagents-rendering.js";
+import type { ChildAgentTranscriptSnapshot } from "./minimal-subagents-types.js";
+
+interface CachedTranscriptMessage {
+  container: Container;
+  tools: Map<string, ToolExecutionComponent>;
+  expanded: boolean;
+  streaming: boolean;
+}
+
+/** Rendered transcript lines and the first line of each message. */
+export interface TranscriptLayout {
+  lines: string[];
+  messageStarts: number[];
+  /** First line of each native component, such as one assistant reply or one tool execution. */
+  itemStarts: number[];
+}
+
+/** Native components reused across renders while their source messages are unchanged. */
+export interface TranscriptRenderCache {
+  messages: WeakMap<AgentMessage, CachedTranscriptMessage>;
+  results: WeakMap<ToolExecutionComponent, AgentMessage>;
+}
+
+/** Render a Child Session Transcript with Pi's native message and tool components. */
+export function renderTranscriptSnapshot(
+  snapshot: ChildAgentTranscriptSnapshot,
+  tui: TUI,
+  cwd: string,
+  expanded: boolean,
+  width: number,
+  cache: TranscriptRenderCache,
+): TranscriptLayout {
+  if (snapshot.messages.length === 0) {
+    return {
+      lines: new Text(snapshot.fallback || "No conversation messages yet.", 3, 0).render(width),
+      messageStarts: [0],
+      itemStarts: [0],
+    };
+  }
+  const blocks: Container[] = [];
+  const tools = new Map(
+    snapshot.toolDefinitions.map((definition) => [definition.name, definition]),
+  );
+  const pendingTools = new Map<string, ToolExecutionComponent>();
+  const currentMessages = new Set(snapshot.messages);
+
+  for (const [messageIndex, message] of snapshot.messages.entries()) {
+    if (message.role === "toolResult") {
+      const paired = pendingTools.get(message.toolCallId);
+      if (paired) {
+        if (cache.results.get(paired) !== message) {
+          paired.updateResult(message);
+          cache.results.set(paired, message);
+        }
+        pendingTools.delete(message.toolCallId);
+        blocks.push(new Container());
+        continue;
+      }
+    }
+    const streaming = messageIndex === snapshot.streamingAssistantIndex;
+    const cached = cache.messages.get(message);
+    const staleResult =
+      cached &&
+      [...cached.tools.values()].some((tool) => {
+        const result = cache.results.get(tool);
+        return result !== undefined && !currentMessages.has(result);
+      });
+    if (cached && !staleResult && cached.expanded === expanded && cached.streaming === streaming) {
+      blocks.push(cached.container);
+      for (const [id, tool] of cached.tools) pendingTools.set(id, tool);
+      continue;
+    }
+    const container = new Container();
+    const messageTools = new Map<string, ToolExecutionComponent>();
+    switch (message.role) {
+      case "user": {
+        const text = contentText(message.content, "\n\n");
+        if (text) container.addChild(new UserMessageComponent(text));
+        break;
+      }
+      case "assistant": {
+        const assistant = new AssistantMessageComponent(message);
+        assistant.updateContent(message, messageIndex === snapshot.streamingAssistantIndex);
+        container.addChild(assistant);
+        for (const content of message.content) {
+          if (content.type !== "toolCall") continue;
+          const tool = new ToolExecutionComponent(
+            content.name,
+            content.id,
+            content.arguments,
+            { showImages: false },
+            tools.get(content.name) ?? {},
+            tui,
+            cwd,
+          );
+          tool.setExpanded(expanded);
+          container.addChild(tool);
+          if (message.stopReason === "aborted" || message.stopReason === "error") {
+            tool.updateResult({
+              content: [
+                {
+                  type: "text",
+                  text:
+                    message.stopReason === "aborted"
+                      ? "Operation aborted"
+                      : (message.errorMessage ?? "Error"),
+                },
+              ],
+              isError: true,
+            });
+          } else {
+            pendingTools.set(content.id, tool);
+            messageTools.set(content.id, tool);
+          }
+        }
+        break;
+      }
+      case "toolResult": {
+        const inherited = new ToolExecutionComponent(
+          message.toolName,
+          message.toolCallId,
+          {},
+          { showImages: false },
+          {},
+          tui,
+          cwd,
+        );
+        inherited.setExpanded(expanded);
+        inherited.updateResult(message);
+        container.addChild(inherited);
+        break;
+      }
+      case "custom": {
+        if (!message.display) break;
+        const renderer =
+          message.customType === "minimal-subagents.message"
+            ? renderMinimalSubagentsMessage
+            : message.customType === "minimal-subagents.result"
+              ? renderMinimalSubagentsResult
+              : undefined;
+        const custom = new CustomMessageComponent(message, renderer);
+        custom.setExpanded(expanded);
+        container.addChild(custom);
+        break;
+      }
+      case "bashExecution": {
+        const bash = new BashExecutionComponent(message.command, tui, message.excludeFromContext);
+        if (message.output) bash.appendOutput(message.output);
+        bash.setComplete(
+          message.exitCode,
+          message.cancelled,
+          // SAFETY: Persisted bash messages retain only the truncation flag; BashExecutionComponent reads that flag here.
+          message.truncated ? ({ truncated: true } as TruncationResult) : undefined,
+          message.fullOutputPath,
+        );
+        bash.setExpanded(expanded);
+        container.addChild(bash);
+        break;
+      }
+      case "branchSummary": {
+        const summary = new BranchSummaryMessageComponent(message);
+        summary.setExpanded(expanded);
+        container.addChild(summary);
+        break;
+      }
+      case "compactionSummary": {
+        const summary = new CompactionSummaryMessageComponent(message);
+        summary.setExpanded(expanded);
+        container.addChild(summary);
+        break;
+      }
+    }
+    cache.messages.set(message, { container, tools: messageTools, expanded, streaming });
+    blocks.push(container);
+  }
+  let length = 0;
+  const messageStarts: number[] = [];
+  const itemStarts: number[] = [];
+  // Containers concatenate their children, so rendering children one by one yields the same lines.
+  const lines = blocks.flatMap((block) => {
+    messageStarts.push(length);
+    return block.children.flatMap((child) => {
+      itemStarts.push(length);
+      // Native user-message prompt zones belong to the main terminal, not an embedded overlay.
+      const rendered = child
+        .render(width)
+        .map((line) =>
+          line
+            .replaceAll("\x1b]133;A\x07", "")
+            .replaceAll("\x1b]133;B\x07", "")
+            .replaceAll("\x1b]133;C\x07", ""),
+        );
+      length += rendered.length;
+      return rendered;
+    });
+  });
+  return { lines, messageStarts, itemStarts };
+}
+
+/** Create an empty cache for {@link renderTranscriptSnapshot}. */
+export function createTranscriptRenderCache(): TranscriptRenderCache {
+  return { messages: new WeakMap(), results: new WeakMap() };
+}
+
+/** Collapsed live views keep at most this many lines of the child's recent work. */
+const COLLAPSED_TRANSCRIPT_RAIL_LINES = 20;
+
+function isSpacerLine(line: string): boolean {
+  // Includes a tool box's coloured padding rows, so each rail connector meets visible content.
+  return stripVTControlCharacters(line).trim().length === 0;
+}
+
+function withoutSpacerEdges(lines: string[]): string[] {
+  const start = lines.findIndex((line) => !isSpacerLine(line));
+  if (start < 0) return [];
+  const end = lines.findLastIndex((line) => !isSpacerLine(line));
+  return lines.slice(start, end + 1);
+}
+
+/**
+ * A child's recent transcript drawn with Pi's native message and tool components, one rail item
+ * per component. Collapsed, it keeps the latest items that fit the line budget.
+ */
+export class TranscriptRail implements Component {
+  constructor(
+    private readonly snapshot: ChildAgentTranscriptSnapshot,
+    private readonly tui: TUI,
+    private readonly cwd: string,
+    private readonly expanded: boolean,
+    private readonly cache: TranscriptRenderCache,
+    private readonly theme: MinimalSubagentsRenderTheme,
+  ) {}
+
+  render(width: number): string[] {
+    const layout = renderTranscriptSnapshot(
+      this.snapshot,
+      this.tui,
+      this.cwd,
+      this.expanded,
+      Math.max(1, width - ACTIVITY_RAIL_WIDTH),
+      this.cache,
+    );
+    const items = layout.itemStarts
+      .map((start, index) =>
+        withoutSpacerEdges(layout.lines.slice(start, layout.itemStarts[index + 1])),
+      )
+      .filter((lines) => lines.length > 0);
+    if (this.expanded) return drawActivityRail(items, this.theme);
+    let shown = 0;
+    let lineCount = 0;
+    for (const item of items.toReversed()) {
+      if (shown > 0 && lineCount + item.length > COLLAPSED_TRANSCRIPT_RAIL_LINES) break;
+      shown++;
+      lineCount += item.length;
+    }
+    const kept = items
+      .slice(items.length - shown)
+      .map((lines) => lines.slice(0, COLLAPSED_TRANSCRIPT_RAIL_LINES));
+    const earlier = items.length - shown;
+    return drawActivityRail(
+      earlier > 0
+        ? [
+            [this.theme.fg("dim", `… ${earlier} earlier ${earlier === 1 ? "step" : "steps"}`)],
+            ...kept,
+          ]
+        : kept,
+      this.theme,
+    );
+  }
+
+  invalidate(): void {
+    this.cache.messages = new WeakMap();
+    this.cache.results = new WeakMap();
+  }
+}

package/src/minimal-subagents-types.ts

@@ -1,6 +1,7 @@
 import type { AgentMessage, ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { Usage } from "@earendil-works/pi-ai";
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { MinimalSubagentsModelRole } from "./minimal-subagents-config.js";
 
 /** Controls how much committed caller conversation enters a new child session. */
 export type SessionContextMode = "inherit" | "compact" | "omit";
@@ -35,17 +36,24 @@ export interface SpawnParameters {
   agent_id?: string;
   session_context?: SessionContextMode;
   project_context?: ProjectContextMode;
+  /** Configured model role whose model and thinking level apply unless overridden below. */
+  role?: string;
   model?: string;
   thinking_level?: ThinkingLevel;
   tools?: ToolSelection;
   delegation?: DelegationMode;
 }
 
-/** Returns persistent agent and turn identities immediately after launch scheduling. */
-export interface SpawnResult {
+/** Returns persistent agent and turn identities plus the resolved grant immediately after launch scheduling. */
+export interface SpawnResult extends RuntimeProfile {
   agent_id: string;
   turn_id: string;
   status: "running";
+  /** Concrete ordinary tools granted by the Launch Contract. */
+  tools: string[];
+  delegation: DelegationMode;
+  /** Non-fatal tool-resolution warnings, such as skipped configured tools. */
+  warnings?: string[];
 }
 
 /** Retains one keyed terminal turn result for waits and durable delivery recovery. */
@@ -59,13 +67,18 @@ export interface TurnResult {
   elapsed_ms?: number;
 }
 
-/** Reports whether one direct message was handed to a wait, queued, or failed. */
-export type AgentMessageDisposition = "delivered-via-wait" | "queued" | "failed";
+/**
+ * Reports whether one direct message was handed to a wait, queued into an active turn, started a
+ * new turn on an idle recipient, or failed.
+ */
+export type AgentMessageDisposition = "delivered-via-wait" | "queued" | "started-turn" | "failed";
 
 export interface AgentMessageResult {
   agent_id: string;
   message_id: string;
   disposition: AgentMessageDisposition;
+  /** Turn started on an idle recipient; present only for `started-turn`. */
+  turn_id?: string;
   error?: string;
 }
 
@@ -112,7 +125,8 @@ export interface AgentSummary extends RuntimeProfile {
   latest_activity_at?: string;
   task?: string;
   child_count: number;
-  children: AgentSummary[];
+  /** Nested summaries; omitted from caller-scoped status, which reports only `child_count`. */
+  children?: AgentSummary[];
 }
 
 /** Provides bounded recent child conversation text for detailed status. */
@@ -129,6 +143,12 @@ export interface RecentAgentActivity {
   truncated: boolean;
 }
 
+/** Live progress of a Child Agent's running turn, shown while its parent waits. */
+export interface ActiveTurnProgress {
+  turn_id: string;
+  tool_calls: number;
+}
+
 /** Holds the complete selected-branch Child Session Transcript for trusted status UI. */
 export interface ChildAgentTranscriptSnapshot {
   messages: AgentMessage[];
@@ -182,6 +202,8 @@ export interface DeleteResult {
 
 /** Persists immutable context, model, thinking, and ordinary-tool launch choices. */
 export interface LaunchContract extends RuntimeProfile {
+  /** Configured model role the caller named at launch; absent when none was used. */
+  role?: string;
   session_context: SessionContextMode;
   project_context: ProjectContextMode;
   tools: ToolSelection | undefined;
@@ -407,6 +429,7 @@ export interface CoordinatorDependencies {
   root: RootConversationEndpoint;
   maxSubagentDepth?: number;
   toolsets?: MinimalSubagentsToolsets;
+  modelRoles?: readonly MinimalSubagentsModelRole[];
   now?: () => Date;
   automaticDeliveryGraceMs?: number;
   notify?: (notification: CoordinatorNotification) => void;

package/src/minimal-subagents-ui.ts

@@ -59,7 +59,7 @@ function flattenAgentHierarchy(agents: readonly AgentSummary[]): FlattenedAgentS
   const flattened: FlattenedAgentSummary[] = [];
   const visit = (agent: AgentSummary, depth: number, parentId?: string) => {
     flattened.push({ agent, depth, parentId, order: flattened.length });
-    for (const child of agent.children) visit(child, depth + 1, agent.agent_id);
+    for (const child of agent.children ?? []) visit(child, depth + 1, agent.agent_id);
   };
   for (const agent of agents) visit(agent, 0);
   return flattened;

package/src/minimal-subagents-usage.ts

@@ -1,17 +1,28 @@
 import type { Usage } from "@earendil-works/pi-ai";
 
+/** Return a clone with optional counters present, so every reported usage has one shape. */
+export function normalizeMinimalSubagentsUsage(usage: Usage): Usage {
+  return {
+    ...structuredClone(usage),
+    cacheWrite1h: usage.cacheWrite1h ?? 0,
+    reasoning: usage.reasoning ?? 0,
+  };
+}
+
 /** Add two optional Pi usage totals without retaining mutable references to either input. */
 export function addMinimalSubagentsUsage(
   left: Usage | undefined,
   right: Usage | undefined,
 ): Usage | undefined {
-  if (!left) return right ? structuredClone(right) : undefined;
-  if (!right) return structuredClone(left);
+  if (!left) return right ? normalizeMinimalSubagentsUsage(right) : undefined;
+  if (!right) return normalizeMinimalSubagentsUsage(left);
   return {
     input: left.input + right.input,
     output: left.output + right.output,
     cacheRead: left.cacheRead + right.cacheRead,
     cacheWrite: left.cacheWrite + right.cacheWrite,
+    cacheWrite1h: (left.cacheWrite1h ?? 0) + (right.cacheWrite1h ?? 0),
+    reasoning: (left.reasoning ?? 0) + (right.reasoning ?? 0),
     totalTokens: left.totalTokens + right.totalTokens,
     cost: {
       input: left.cost.input + right.cost.input,