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

package/src/minimal-subagents-settings-writer.ts

@@ -1,5 +1,5 @@
-import type { JsonValue } from "@earendil-works/pi-ai";
 import { CONFIG_DIR_NAME } from "@earendil-works/pi-coding-agent";
+import { rewriteNamespaceDocument } from "@ian-pascoe/pi-utils/layered-settings";
 import { updateFileLocked } from "@ian-pascoe/pi-utils/locked-file-update";
 import { resolve } from "node:path";
 
@@ -12,31 +12,6 @@ export interface MinimalSubagentsSettingsWriteContext {
   isProjectTrusted(): boolean;
 }
 
-type SettingsJsonObject = Record<string, JsonValue>;
-
-function isSettingsJsonObject(value: JsonValue | undefined): value is SettingsJsonObject {
-  // oxlint-disable-next-line anti-slop/no-runtime-typeof -- JSON.parse already established JSON data; distinguish object roots and settings blocks from primitives and arrays.
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}
-
-function parseSettings(content: string | undefined, path: string): SettingsJsonObject {
-  if (content === undefined) return {};
-  // JSON.parse is the provenance for this JSON type; the object shape is checked below.
-  let parsed: JsonValue;
-  try {
-    parsed = JSON.parse(content.charCodeAt(0) === 0xfeff ? content.slice(1) : content);
-  } catch (cause) {
-    throw new Error(`Minimal subagents settings JSON is malformed at ${path}`, { cause });
-  }
-  if (!isSettingsJsonObject(parsed)) {
-    throw new Error(`Minimal subagents settings at ${path} must have an object root`);
-  }
-  if (parsed.minimalSubagents !== undefined && !isSettingsJsonObject(parsed.minimalSubagents)) {
-    throw new Error(`Minimal subagents settings at ${path} must have an object minimalSubagents`);
-  }
-  return parsed;
-}
-
 /**
  * Set or remove `minimalSubagents.enabled` in global or trusted-project Pi settings,
  * preserving every unrelated setting. Writes re-read the file under Pi's settings lock.
@@ -58,15 +33,26 @@ export async function writeMinimalSubagentsEnabled(
     );
   }
 
-  await updateFileLocked(path, (content) => {
-    const settings = parseSettings(content, path);
-    const current = settings.minimalSubagents;
-    const minimalSubagents = isSettingsJsonObject(current) ? { ...current } : {};
-    if (enabled === undefined) delete minimalSubagents.enabled;
-    else minimalSubagents.enabled = enabled;
-    if (Object.keys(minimalSubagents).length === 0) delete settings.minimalSubagents;
-    else settings.minimalSubagents = minimalSubagents;
-    return `${JSON.stringify(settings, undefined, 2)}\n`;
-  });
+  await updateFileLocked(path, (current) =>
+    rewriteNamespaceDocument({
+      current,
+      namespace: "minimalSubagents",
+      invalid: (reason, cause) => {
+        if (reason === "malformed")
+          return new Error(`Minimal subagents settings JSON is malformed at ${path}`, { cause });
+        return new Error(
+          reason === "root"
+            ? `Minimal subagents settings at ${path} must have an object root`
+            : `Minimal subagents settings at ${path} must have an object minimalSubagents`,
+        );
+      },
+      update: (stored) => {
+        const minimalSubagents = { ...stored };
+        if (enabled === undefined) delete minimalSubagents.enabled;
+        else minimalSubagents.enabled = enabled;
+        return minimalSubagents;
+      },
+    }),
+  );
   return path;
 }

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

@@ -1,5 +1,6 @@
 import { stripVTControlCharacters } from "node:util";
 import {
+  DynamicBorder,
   type ExtensionContext,
   type KeybindingsManager,
   type Theme,
@@ -8,16 +9,20 @@ import {
   Text,
   matchesKey,
   truncateToWidth,
-  visibleWidth,
+  wrapTextWithAnsi,
   type Component,
   type OverlayHandle,
   type TUI,
 } from "@earendil-works/pi-tui";
+import { hintLine, joinInline, noticeText } from "@ian-pascoe/pi-utils/ui";
 import type { MinimalSubagentsCoordinator } from "./minimal-subagents-coordinator.js";
 import {
   formatSubagentDuration,
   orderActiveAgentSubtrees,
+  renderSubagentStatusLabel,
+  renderSubagentStatusMark,
   subagentStatusLadder,
+  treeRowPrefixes,
 } from "./minimal-subagents-rendering.js";
 import { COORDINATOR_TOOL_NAMES } from "./minimal-subagents-capabilities.js";
 import {
@@ -82,21 +87,11 @@ function statusAccessSourceLabel(source: SubagentAccessSnapshot["source"]): stri
   }
 }
 
-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;
-}
+/** The panel's ellipsis, in Pi's three-dot form. */
+const ELLIPSIS = "...";
+
+/** The theme operations the panel draws with; Pi's `Theme` satisfies it. */
+type StatusPanelTheme = Pick<Theme, "fg" | "bold">;
 
 function transcriptText(line: string): string {
   return stripVTControlCharacters(line).replace(/\s/g, "");
@@ -152,14 +147,15 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
   private toolOutputExpanded = false;
   private disposed = false;
   private readonly stopRefresh: () => void;
+  private readonly border = new DynamicBorder((text) => this.theme.fg("border", text));
 
   /** Bind one live status component to its coordinator, terminal, and explicit refresh owner. */
   constructor(
     private readonly coordinator: MinimalSubagentsCoordinator,
     private readonly getAccess: () => MinimalSubagentsStatusAccess,
     private readonly tui: TUI,
-    private readonly theme: Theme,
-    private readonly keybindings: KeybindingsManager,
+    private readonly theme: StatusPanelTheme,
+    private readonly keybindings: Pick<KeybindingsManager, "matches" | "getKeys">,
     private readonly cwd: string,
     private readonly onClose: () => void,
     startRefresh: StartStatusPanelRefresh = startStatusPanelRefresh,
@@ -208,7 +204,7 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     this.tui.requestRender();
   }
 
-  /** Render one framed, terminal-bounded tree or Child Session Transcript. */
+  /** Render the tree or Child Session Transcript in Pi's selector frame, within the terminal. */
   render(width: number): string[] {
     if (width <= 0) return [];
     const height = Math.max(
@@ -219,24 +215,24 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
       ),
     );
     if (width < 6 || height < 5) {
-      return new Text("Esc back · Enlarge terminal", 0, 0).render(width).slice(0, height);
+      const cancelKey = this.keybindings.getKeys("tui.select.cancel").join("/");
+      return new Text(this.theme.fg("muted", `${cancelKey} back · Enlarge terminal`), 0, 0)
+        .render(width)
+        .slice(0, height);
     }
-    const innerWidth = width - 4;
+    const innerWidth = width - 2;
     const selected = this.flattened.find(({ agent }) => agent.agent_id === this.selectedAgentId);
     const transcriptView = this.view === "transcript" && this.transcript;
     const header = transcriptView
       ? [
-          this.theme.bold(`Transcript · ${this.selectedAgentId}`),
-          selected ? this.renderAgentRow(selected.agent, 0, innerWidth) : "",
+          this.theme.fg("accent", this.theme.bold(`Transcript · ${this.selectedAgentId}`)),
+          selected ? this.renderAgentRow(selected.agent, "", false) : "",
         ]
-      : this.renderHeader(innerWidth);
-    const toolKey = this.keybindings.getKeys("app.tools.expand").join("/");
-    const helpText = transcriptView
-      ? `Esc tree · End live · ${toolKey} tools · ↑↓/PgUp/PgDn scroll · ${this.following ? "Following" : "Paused"}`
-      : "Esc close · Enter transcript · ↑↓ select · PgUp/PgDn page";
-    const help = new Text(this.theme.fg("text", helpText), 0, 0)
-      .render(innerWidth)
-      .slice(0, Math.min(2, height - 4));
+      : this.renderHeader();
+    const help = [
+      "",
+      ...wrapTextWithAnsi(this.renderHints(Boolean(transcriptView)), innerWidth),
+    ].slice(0, Math.min(3, height - 4));
     const visibleHeader = header.slice(0, Math.max(1, height - help.length - 3));
     this.bodyHeight = Math.max(1, height - 2 - visibleHeader.length - help.length);
     let body: string[];
@@ -262,10 +258,11 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
       const maximum = Math.max(0, body.length - this.bodyHeight);
       this.scrollOffset = this.following ? maximum : Math.min(this.scrollOffset, maximum);
     } else {
-      body = this.flattened.map(({ agent, depth }) =>
-        this.renderAgentRow(agent, depth, innerWidth),
+      const prefixes = treeRowPrefixes(this.flattened.map(({ depth }) => depth));
+      body = this.flattened.map(({ agent }, index) =>
+        this.renderAgentRow(agent, prefixes[index] ?? "", agent.agent_id === this.selectedAgentId),
       );
-      if (body.length === 0) body.push("No Child Agents yet.");
+      if (body.length === 0) body.push(this.theme.fg("muted", "No Child Agents yet."));
       const selectedLine = this.flattened.findIndex(
         ({ agent }) => agent.agent_id === this.selectedAgentId,
       );
@@ -279,19 +276,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 = keepBackgroundThroughResets(
-        truncateToWidth(line, innerWidth, "…"),
-        backgroundOpen,
-      );
-      return this.theme.bg(
-        "customMessageBg",
-        `${border("│")} ${content}${" ".repeat(innerWidth - visibleWidth(content))} ${border("│")}`,
-      );
-    });
-    return [border(`╭${"─".repeat(width - 2)}╮`), ...rows, border(`╰${"─".repeat(width - 2)}╯`)];
+    // Each row keeps Pi's one-column margin and fills the pane so the overlay covers what is under it.
+    const rows = [...visibleHeader, ...visibleBody, ...help].map((line) =>
+      truncateToWidth(` ${line}`, width, ELLIPSIS, true),
+    );
+    const [border = ""] = this.border.render(width);
+    return [border, ...rows, border];
   }
 
   /** Rebuild native transcript components when their theme changes. */
@@ -326,7 +316,34 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     }
   }
 
-  private renderHeader(width: number): string[] {
+  private keyLabel(binding: Parameters<KeybindingsManager["getKeys"]>[0]): string {
+    return this.keybindings.getKeys(binding).join("/");
+  }
+
+  private renderHints(transcript: boolean): string {
+    const page = `${this.keyLabel("tui.select.pageUp")}/${this.keyLabel("tui.select.pageDown")}`;
+    const hints = transcript
+      ? hintLine(this.theme, [
+          { key: this.keyLabel("tui.select.cancel"), description: "tree" },
+          { key: "end", description: "live" },
+          { key: this.keyLabel("app.tools.expand"), description: "tools" },
+          { key: "\u2191\u2193", description: "scroll" },
+          { key: page, description: "page" },
+        ])
+      : hintLine(this.theme, [
+          { key: "\u2191\u2193", description: "select" },
+          { key: this.keyLabel("tui.select.confirm"), description: "transcript" },
+          { key: page, description: "page" },
+          { key: this.keyLabel("tui.select.cancel"), description: "close" },
+        ]);
+    if (!transcript) return hints;
+    const following = this.following
+      ? this.theme.fg("muted", "following")
+      : this.theme.fg("warning", "paused");
+    return `${hints}  ${following}`;
+  }
+
+  private renderHeader(): string[] {
     const direct = "agents" in this.status ? this.status.agents : [this.status.agent];
     const running = direct.filter((agent) => agent.state === "running").length;
     const idle = direct.length - running;
@@ -340,34 +357,41 @@ export class MinimalSubagentsStatusPanelComponent implements Component {
     const projectValue = this.access.projectTrusted
       ? authoredAccessValue(this.access.projectEnabled)
       : "unavailable (untrusted)";
+    const field = (label: string, ...values: string[]) =>
+      `${this.theme.fg("muted", `${label}:`)} ${joinInline(this.theme, values)}`;
     return [
-      truncateToWidth(this.theme.bold("Subagents status"), width, "…"),
-      truncateToWidth(
-        `Access: ${accessState} · ${statusAccessSourceLabel(this.access.source)}`,
-        width,
-        "…",
-      ),
-      truncateToWidth(
-        `Defaults: branch ${this.access.branchOverride} · project ${projectValue} · global ${authoredAccessValue(this.access.globalEnabled)}`,
-        width,
-        "…",
+      this.theme.fg("accent", this.theme.bold("Subagents status")),
+      field("Access", accessState, statusAccessSourceLabel(this.access.source)),
+      field(
+        "Defaults",
+        `branch ${this.access.branchOverride}`,
+        `project ${projectValue}`,
+        `global ${authoredAccessValue(this.access.globalEnabled)}`,
       ),
-      truncateToWidth(`Coordinator Tools: ${toolState}`, width, "…"),
-      truncateToWidth(`Direct Children: ${running} running · ${idle} idle`, width, "…"),
-      this.theme.fg("warning", this.notice),
+      field("Coordinator Tools", toolState),
+      field("Direct Children", `${running} running`, `${idle} idle`),
+      ...(this.notice ? [this.theme.fg("warning", this.notice)] : []),
     ];
   }
 
-  private renderAgentRow(agent: AgentSummary, depth: number, width: number): string {
-    const selected = agent.agent_id === this.selectedAgentId;
-    const disclosure = "▸";
+  /** One row of the hierarchy: selection marker, tree prefix, Status Mark, id, status, profile, task. */
+  private renderAgentRow(agent: AgentSummary, prefix: string, selected: boolean): string {
     const status = subagentStatusLadder(agent);
     const elapsed = formatSubagentDuration(agent.elapsed_ms);
     const task = agent.task?.replace(/\s+/g, " ").trim();
-    const line = `${selected ? ">" : " "} ${"  ".repeat(depth)}${disclosure} ${agent.agent_id} · ${status}${
-      elapsed ? ` ${elapsed}` : ""
-    } · ${agent.model}:${agent.thinking_level}${task ? ` · ${task}` : ""}`;
-    return truncateToWidth(selected ? this.theme.fg("accent", line) : line, width, "…");
+    const identity = `${renderSubagentStatusMark(this.theme, status)} ${
+      selected ? this.theme.fg("accent", agent.agent_id) : agent.agent_id
+    }`;
+    const details = joinInline(this.theme, [
+      identity,
+      `${renderSubagentStatusLabel(this.theme, status)}${
+        elapsed ? ` ${this.theme.fg("muted", elapsed)}` : ""
+      }`,
+      this.theme.fg("muted", `${agent.model}:${agent.thinking_level}`),
+      task ? this.theme.fg("muted", task) : undefined,
+    ]);
+    const marker = selected ? this.theme.fg("accent", "→ ") : "  ";
+    return `${marker}${prefix ? this.theme.fg("dim", prefix) : ""}${details}`;
   }
 
   private scroll(delta: number): void {
@@ -491,7 +515,7 @@ export class MinimalSubagentsStatusPanelController {
         },
       )
       .catch(() => {
-        this.context.ui.notify("Subagents status view failed.", "error");
+        this.context.ui.notify(noticeText("Subagents", "Status view failed."), "error");
       })
       .finally(() => {
         this.activePanel?.dispose();

package/src/minimal-subagents-tools.ts

@@ -9,10 +9,12 @@ import {
   type ToolDefinition,
   type ToolRenderResultOptions,
 } from "@earendil-works/pi-coding-agent";
-import type { TUI } from "@earendil-works/pi-tui";
+import { Container, type Component, type TUI } from "@earendil-works/pi-tui";
+import { appendDurationFooter, callDurationFooter } from "@ian-pascoe/pi-utils/ui";
 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 +44,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<
@@ -136,6 +135,13 @@ interface CoordinatorToolRowState {
   liveTurnCache?: TranscriptRenderCache;
 }
 
+function withFooter(body: Component, footer: Component): Component {
+  const container = new Container();
+  container.addChild(body);
+  container.addChild(footer);
+  return container;
+}
+
 function createCoordinatorToolRendering(
   options: CoordinatorToolDefinitionOptions,
   toolName: CoordinatorToolName,
@@ -144,8 +150,13 @@ function createCoordinatorToolRendering(
     renderCall: (
       args: CoordinatorToolCallInput,
       theme: Theme,
-      context: { expanded: boolean } | undefined,
-    ) => renderCoordinatorToolCall(toolName, args, theme, context?.expanded ?? false),
+      context: CoordinatorToolRenderContext | undefined,
+    ) => {
+      const call = renderCoordinatorToolCall(toolName, args, theme, context?.expanded ?? false);
+      // A wait streams partial results, whose footer already shows its running time.
+      if (!context || toolName === "subagent_wait") return call;
+      return withFooter(call, callDurationFooter(theme, context));
+    },
     renderResult: (
       result: AgentToolResult<CoordinatorToolResultDetails>,
       renderOptions: ToolRenderResultOptions,
@@ -170,7 +181,7 @@ function createCoordinatorToolRendering(
           theme,
         );
       };
-      return renderCoordinatorToolResult(
+      const rendered = renderCoordinatorToolResult(
         toolName,
         result,
         renderOptions,
@@ -179,14 +190,36 @@ function createCoordinatorToolRendering(
         context.isError,
         toolName === "subagent_wait" ? renderLiveTurn : undefined,
       );
+      const container = new Container();
+      container.addChild(rendered);
+      appendDurationFooter(container, theme, context, { isPartial: renderOptions.isPartial });
+      return container;
     },
   };
 }
 
+/**
+ * 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,
@@ -380,7 +413,7 @@ export function createCoordinatorToolDefinitions(
                 ? alreadyDeliveredContent(result)
                 : structuredToolResult(result).content,
             details,
-            structuredContent: JSON.parse(JSON.stringify(details)),
+            structuredContent: JSON.parse(stringifyWithRoundedUsageCosts(details)),
           };
         });
       } finally {
@@ -459,9 +492,7 @@ export function createCoordinatorToolDefinitions(
           parameters.recursive ?? true,
         );
         if (result.failures.length > 0) {
-          options.onAttention?.(
-            `Minimal subagents deletion partially failed for ${parameters.agent_id}`,
-          );
+          options.onAttention?.(`Deletion partially failed for ${parameters.agent_id}`);
           return failedStructuredToolResult("Minimal subagents deletion partially failed", result, {
             troubleshootingHint: true,
           });
@@ -483,5 +514,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-transcript.ts

@@ -11,7 +11,14 @@ import {
   UserMessageComponent,
   type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
-import { Container, Text, type Component, type TUI } from "@earendil-works/pi-tui";
+import {
+  Container,
+  Text,
+  wrapTextWithAnsi,
+  type Component,
+  type TUI,
+} from "@earendil-works/pi-tui";
+import { COLLAPSED_LINES, expandHint } from "@ian-pascoe/pi-utils/ui";
 import {
   ACTIVITY_RAIL_WIDTH,
   drawActivityRail,
@@ -224,7 +231,7 @@ export function createTranscriptRenderCache(): TranscriptRenderCache {
 }
 
 /** Collapsed live views keep at most this many lines of the child's recent work. */
-const COLLAPSED_TRANSCRIPT_RAIL_LINES = 20;
+const COLLAPSED_TRANSCRIPT_RAIL_LINES = COLLAPSED_LINES.fallback;
 
 function isSpacerLine(line: string): boolean {
   // Includes a tool box's coloured padding rows, so each rail connector meets visible content.
@@ -277,16 +284,14 @@ export class TranscriptRail implements Component {
     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,
+    const hidden =
+      items.reduce((total, lines) => total + lines.length, 0) -
+      kept.reduce((total, lines) => total + lines.length, 0);
+    const hint = wrapTextWithAnsi(
+      expandHint(this.theme, hidden, "earlier"),
+      Math.max(1, width - ACTIVITY_RAIL_WIDTH),
     );
+    return drawActivityRail(hidden > 0 ? [hint, ...kept] : kept, this.theme);
   }
 
   invalidate(): void {