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

package/src/minimal-subagents-status-panel.ts

@@ -1,21 +1,10 @@
 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 ExtensionContext,
   type KeybindingsManager,
   type Theme,
-  type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import {
-  Container,
   Text,
   matchesKey,
   truncateToWidth,
@@ -28,11 +17,14 @@ import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinato
 import {
   formatSubagentDuration,
   orderActiveAgentSubtrees,
-  renderMinimalSubagentsMessage,
-  renderMinimalSubagentsResult,
   subagentStatusLadder,
 } from "./minimal-subagents-rendering.js";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
+import {
+  createTranscriptRenderCache,
+  renderTranscriptSnapshot,
+  type TranscriptLayout,
+} from "./minimal-subagents-transcript.js";
 import type { SubagentAccessSnapshot } from "./minimal-subagents-access.js";
 import type {
   AgentSummary,
@@ -66,7 +58,7 @@ function flattenStatusAgents(status: HierarchyStatusResult): FlattenedStatusAgen
   const flattened: FlattenedStatusAgent[] = [];
   const visit = (agent: AgentSummary, depth: number): void => {
     flattened.push({ agent, depth });
-    for (const child of agent.children) visit(child, depth + 1);
+    for (const child of agent.children ?? []) visit(child, depth + 1);
   };
   const roots = "agents" in status ? status.agents : [status.agent];
   for (const agent of orderActiveAgentSubtrees(roots)) visit(agent, 0);
@@ -90,16 +82,20 @@ function statusAccessSourceLabel(source: SubagentAccessSnapshot["source"]): stri
   }
 }
 
-interface CachedTranscriptMessage {
-  container: Container;
-  tools: Map<string, ToolExecutionComponent>;
-  expanded: boolean;
-  streaming: boolean;
-}
-
-interface TranscriptLayout {
-  lines: string[];
-  messageStarts: number[];
+const BACKGROUND_CLEARING_SEQUENCES = ["\u001b[0m", "\u001b[m", "\u001b[49m"] as const;
+
+/**
+ * Re-open the panel background after each sequence that clears it. Truncation ends its cut text
+ * and ellipsis with full resets, and embedded native components may reset or close their own
+ * backgrounds; without this the rest of the row (ellipsis, padding, border) loses the panel fill.
+ */
+function keepBackgroundThroughResets(text: string, backgroundOpen: string): string {
+  if (!backgroundOpen) return text;
+  let result = text;
+  for (const sequence of BACKGROUND_CLEARING_SEQUENCES) {
+    result = result.replaceAll(sequence, `${sequence}${backgroundOpen}`);
+  }
+  return result;
 }
 
 function transcriptText(line: string): string {
@@ -137,180 +133,6 @@ function anchoredTranscriptOffset(
   return nextStart + Math.max(0, newLines.length - 1);
 }
 
-interface TranscriptRenderCache {
-  messages: WeakMap<AgentMessage, CachedTranscriptMessage>;
-  results: WeakMap<ToolExecutionComponent, AgentMessage>;
-}
-
-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],
-    };
-  }
-  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 lines = blocks.flatMap((block) => {
-    messageStarts.push(length);
-    // Native user-message prompt zones belong to the main terminal, not an embedded overlay.
-    const rendered = block
-      .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 };
-}
-
 /** Interactive, read-only Child Agent hierarchy and transcript status component. */
 export class MinimalSubagentsStatusPanelComponent implements Component {
   private status!: HierarchyStatusResult;
@@ -324,10 +146,7 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
   private following = true;
   private transcriptLineCount = 0;
   private transcriptLayout?: TranscriptLayout;
-  private readonly transcriptCache: TranscriptRenderCache = {
-    messages: new WeakMap(),
-    results: new WeakMap(),
-  };
+  private readonly transcriptCache = createTranscriptRenderCache();
   private bodyHeight = 1;
   private ensureSelectionVisible = true;
   private toolOutputExpanded = false;
@@ -461,8 +280,12 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + this.bodyHeight);
     while (visibleBody.length < this.bodyHeight) visibleBody.push("");
     const border = (text: string) => this.theme.fg("border", text);
+    const backgroundOpen = this.theme.getBgAnsi("customMessageBg");
     const rows = [...visibleHeader, ...visibleBody, ...help].map((line) => {
-      const content = truncateToWidth(line, innerWidth, "…");
+      const content = keepBackgroundThroughResets(
+        truncateToWidth(line, innerWidth, "…"),
+        backgroundOpen,
+      );
       return this.theme.bg(
         "customMessageBg",
         `${border("│")} ${content}${" ".repeat(innerWidth - visibleWidth(content))} ${border("│")}`,

package/src/minimal-subagents-tool-schemas.ts

@@ -2,7 +2,10 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { THINKING_LEVELS } from "./minimal-subagents-capabilities.js";
 
-const SessionContextSchema = StringEnum(["inherit", "compact", "omit"] as const);
+const SessionContextSchema = StringEnum(["inherit", "compact", "omit"] as const, {
+  description:
+    "Default omit: the child starts blank, so write a self-contained task. inherit copies your whole conversation (costly; no prompt-cache reuse); compact summarizes it first (adds a summarization call). Opt in only when the child needs the discussion itself.",
+});
 const ProjectContextSchema = StringEnum(["inherit", "omit"] as const, {
   description:
     "Whether to include project-scoped AGENTS.md instructions and skills. Settings, extensions, providers, and tools remain available.",
@@ -38,7 +41,11 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
     firstModelId === undefined ? Type.Never() : StringEnum([firstModelId, ...remainingModelIds]);
   return {
     subagent: Type.Object({
-      task: Type.String({ minLength: 1, description: "Task for the persistent child agent" }),
+      task: Type.String({
+        minLength: 1,
+        description:
+          "Self-contained brief for the persistent child agent: the goal and relevant background, target files and non-goals, the change or question, and observable acceptance criteria. Reference large inputs by file path instead of pasting them.",
+      }),
       agent_id: Type.Optional(
         Type.String({
           pattern: FRIENDLY_AGENT_ID_PATTERN,
@@ -69,7 +76,9 @@ export function createCoordinatorToolSchemas(modelIds: readonly string[]) {
       timeout_ms: Type.Optional(Type.Integer({ minimum: 0 })),
     }),
     subagent_status: Type.Object({
-      agent_id: Type.Optional(canonicalAgentIdSchema("Direct child canonical agent ID")),
+      agent_id: Type.Optional(
+        canonicalAgentIdSchema("Direct child canonical agent ID; the root may name any descendant"),
+      ),
     }),
     subagent_cancel: Type.Object({
       agent_id: canonicalAgentIdSchema("Direct child canonical agent ID"),

package/src/minimal-subagents-tools.ts

@@ -9,6 +9,7 @@ import {
   type ToolDefinition,
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
+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";
@@ -16,13 +17,21 @@ import {
   renderCoordinatorToolCall,
   renderCoordinatorToolResult,
   type CoordinatorToolName,
+  type LiveTurnRenderer,
 } from "./minimal-subagents-rendering.js";
+import {
+  createTranscriptRenderCache,
+  TranscriptRail,
+  type TranscriptRenderCache,
+} from "./minimal-subagents-transcript.js";
 import {
   CoordinatorToolOutputSchemas,
   type CoordinatorToolCallInput,
 } from "./minimal-subagents-render-contract.js";
 import type { createCoordinatorToolSchemas } from "./minimal-subagents-tool-schemas.js";
 import type {
+  ActiveTurnProgress,
+  AgentDetail,
   AgentMessageResult,
   CallerSnapshot,
   CancelResult,
@@ -41,7 +50,15 @@ const ORDINARY_CHILD_COORDINATOR_TOOL_NAMES = new Set([
 /** Coordinator operations consumed by the six public coordinator tool definitions. */
 export type CoordinatorToolOperations = Pick<
   MinimalSubagentsCoordinator,
-  "spawn" | "inspectStatus" | "sendAgentMessage" | "wait" | "status" | "cancel" | "delete"
+  | "spawn"
+  | "inspectStatus"
+  | "previewActiveTurn"
+  | "inspectActiveTurnTranscript"
+  | "sendAgentMessage"
+  | "wait"
+  | "status"
+  | "cancel"
+  | "delete"
 >;
 
 /** Dependencies and caller policy used to create caller-bound coordinator tools. */
@@ -81,37 +98,84 @@ async function runCoordinatorToolActivity<T>(
   }
 }
 
+/** The compact launch result, plus the full agent detail its transcript renderer displays. */
+type SpawnResultDetails = SpawnResult & { agent?: AgentDetail };
+
 type CoordinatorToolResultDetails =
-  | SpawnResult
+  | SpawnResultDetails
   | AgentMessageResult
   | WaitResult
   | StatusResult
   | CancelResult
   | DeleteResult
-  | { agent_id: string; status: "waiting"; elapsed_ms: number };
+  | WaitProgressDetails;
+
+/** Partial `subagent_wait` details: elapsed wait time plus the child's running-turn progress. */
+type WaitProgressDetails = {
+  agent_id: string;
+  status: "waiting";
+  elapsed_ms: number;
+} & Partial<ActiveTurnProgress>;
 
 type CoordinatorToolDefinition = ToolDefinition & {
   readonly outputSchema: (typeof CoordinatorToolOutputSchemas)[keyof typeof CoordinatorToolOutputSchemas];
 };
 
-function createCoordinatorToolRendering(toolName: CoordinatorToolName) {
+/** Native transcript components are re-rendered on each wait update, so their render requests are not needed. */
+const NON_RENDERING_TUI: Pick<TUI, "requestRender"> = { requestRender: () => undefined };
+
+/** Pi's per-call render context; the installed Pi does not export its named type. */
+type CoordinatorToolRenderContext = Parameters<NonNullable<ToolDefinition["renderResult"]>>[3];
+
+/** Renderer state Pi keeps for one tool row across its partial and final renders. */
+interface CoordinatorToolRowState {
+  liveTurnCache?: TranscriptRenderCache;
+}
+
+function createCoordinatorToolRendering(
+  options: CoordinatorToolDefinitionOptions,
+  toolName: CoordinatorToolName,
+) {
   return {
-    renderCall: (args: CoordinatorToolCallInput, theme: Theme) =>
-      renderCoordinatorToolCall(toolName, args, theme),
+    renderCall: (
+      args: CoordinatorToolCallInput,
+      theme: Theme,
+      context: { expanded: boolean } | undefined,
+    ) => renderCoordinatorToolCall(toolName, args, theme, context?.expanded ?? false),
     renderResult: (
       result: AgentToolResult<CoordinatorToolResultDetails>,
       renderOptions: ToolRenderResultOptions,
       theme: Theme,
-      context: { args: CoordinatorToolCallInput; isError: boolean },
-    ) =>
-      renderCoordinatorToolResult(
+      context: CoordinatorToolRenderContext,
+    ) => {
+      const rowState: CoordinatorToolRowState = context.state;
+      const renderLiveTurn: LiveTurnRenderer = (agentId, turnId, expanded) => {
+        const snapshot = options.coordinator.inspectActiveTurnTranscript(
+          options.callerId,
+          agentId,
+          turnId,
+        );
+        if (!snapshot || snapshot.messages.length === 0) return undefined;
+        return new TranscriptRail(
+          snapshot,
+          // SAFETY: Native transcript components only call requestRender on the TUI they receive.
+          NON_RENDERING_TUI as TUI,
+          context.cwd,
+          expanded,
+          (rowState.liveTurnCache ??= createTranscriptRenderCache()),
+          theme,
+        );
+      };
+      return renderCoordinatorToolResult(
         toolName,
         result,
         renderOptions,
         theme,
         context.args,
         context.isError,
-      ),
+        toolName === "subagent_wait" ? renderLiveTurn : undefined,
+      );
+    },
   };
 }
 
@@ -178,10 +242,12 @@ export function createCoordinatorToolDefinitions(
     name: "subagent",
     label: "Subagent",
     description:
-      "Create a persistent nested agent asynchronously. Returns its canonical agent ID and active turn ID immediately. Root-child IDs omit the root prefix; nested IDs retain the parent path.",
+      "Create a persistent nested agent asynchronously. Returns its canonical agent ID, active turn ID, and resolved model and tools immediately. Root-child IDs omit the root prefix; nested IDs retain the parent path. Children start without your conversation unless session_context opts in, so the task must be self-contained. Its final response is delivered automatically unless you claim it with subagent_wait. To continue an idle child later, send it agent_message; that starts a new turn you can wait on.",
     promptSnippet: "Spawn a persistent child with a prefix-free root-child ID",
     promptGuidelines: modelRolePromptGuidelines,
     parameters: options.schemas.subagent,
+    // A spawn must finish registering before a wait or message in the same batch can target it.
+    executionMode: "sequential",
     annotations: {
       readOnlyHint: false,
       destructiveHint: true,
@@ -195,24 +261,22 @@ export function createCoordinatorToolDefinitions(
           parameters,
           options.captureCaller(context),
         );
+        // The model and codemode receive the compact launch result; the transcript renderer
+        // additionally receives the full detail it displays.
         const status = options.coordinator.inspectStatus(result.agent_id);
-        const details: SpawnResult & {
-          agent?: import("./minimal-subagents-types.js").AgentDetail;
-        } = {
-          ...result,
-        };
-        if (status && "agent" in status) details.agent = status.agent;
-        return structuredToolResult(details);
+        const details: SpawnResultDetails = { ...result };
+        if ("agent" in status) details.agent = status.agent;
+        return { ...structuredToolResult(result), details };
       });
     },
-    ...createCoordinatorToolRendering("subagent"),
+    ...createCoordinatorToolRendering(options, "subagent"),
   });
 
   const messageTool = defineTool({
     name: "agent_message",
     label: "Agent Message",
     description:
-      "Send one mid-turn coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued for the recipient, or failed.",
+      "Send one coordination message to a direct parent, direct sibling, or direct child. The result says whether it was delivered through an active wait, queued into the recipient's active turn, started a new turn on an idle child (with its turn_id), or failed.",
     promptSnippet: "Coordinate required mid-turn action with one adjacent agent",
     parameters: options.schemas.agent_message,
     annotations: {
@@ -239,14 +303,14 @@ export function createCoordinatorToolDefinitions(
           : structuredToolResult(result);
       });
     },
-    ...createCoordinatorToolRendering("agent_message"),
+    ...createCoordinatorToolRendering(options, "agent_message"),
   });
 
   const waitTool = defineTool({
     name: "subagent_wait",
     label: "Subagent Wait",
     description:
-      "Wait for one direct child's oldest observable turn, or select an exact retained turn_id. An active child may first return event=message; later unconsumed items still fall back automatically. An already settled turn returns event=turn once with queued messages in messages. Timeout returns event=timeout with detailed child status and never cancels the child.",
+      "Wait for one direct child's oldest observable turn, 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 the same result. Timeout returns event=timeout with detailed child status and never cancels the child.",
     promptSnippet: "Wait for one direct child's exact turn",
     parameters: options.schemas.subagent_wait,
     annotations: {
@@ -257,15 +321,22 @@ export function createCoordinatorToolDefinitions(
     },
     async execute(_toolCallId, parameters, signal, onUpdate) {
       const startedAt = Date.now();
-      const updateWaitingResult = () =>
+      const updateWaitingResult = () => {
+        const details: WaitProgressDetails = {
+          agent_id: parameters.agent_id,
+          status: "waiting",
+          elapsed_ms: Date.now() - startedAt,
+          ...options.coordinator.previewActiveTurn(
+            options.callerId,
+            parameters.agent_id,
+            parameters.turn_id,
+          ),
+        };
         onUpdate?.({
           content: [{ type: "text", text: `Waiting for ${parameters.agent_id}` }],
-          details: {
-            agent_id: parameters.agent_id,
-            status: "waiting",
-            elapsed_ms: Date.now() - startedAt,
-          },
+          details,
         });
+      };
       updateWaitingResult();
       const waitingInterval = setInterval(updateWaitingResult, 1_000);
       waitingInterval.unref?.();
@@ -293,14 +364,14 @@ export function createCoordinatorToolDefinitions(
         clearInterval(waitingInterval);
       }
     },
-    ...createCoordinatorToolRendering("subagent_wait"),
+    ...createCoordinatorToolRendering(options, "subagent_wait"),
   });
 
   const statusTool = defineTool({
     name: "subagent_status",
     label: "Subagent Status",
     description:
-      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning.",
+      "List direct children when agent_id is omitted, or inspect one direct child's launch contract, result, usage, dependencies, and bounded recent activity including message text and reasoning. The root may inspect any descendant.",
     promptSnippet: "Inspect direct child state",
     parameters: options.schemas.subagent_status,
     annotations: {
@@ -314,7 +385,7 @@ export function createCoordinatorToolDefinitions(
         structuredToolResult(options.coordinator.status(options.callerId, parameters.agent_id)),
       );
     },
-    ...createCoordinatorToolRendering("subagent_status"),
+    ...createCoordinatorToolRendering(options, "subagent_status"),
   });
 
   const cancelTool = defineTool({
@@ -341,7 +412,7 @@ export function createCoordinatorToolDefinitions(
         ),
       );
     },
-    ...createCoordinatorToolRendering("subagent_cancel"),
+    ...createCoordinatorToolRendering(options, "subagent_cancel"),
   });
 
   const deleteTool = defineTool({
@@ -375,7 +446,7 @@ export function createCoordinatorToolDefinitions(
         return structuredToolResult(result);
       });
     },
-    ...createCoordinatorToolRendering("subagent_delete"),
+    ...createCoordinatorToolRendering(options, "subagent_delete"),
   });
 
   const coordinatorTools: CoordinatorToolDefinition[] = [