@tt-a1i/openpi 0.3.1 → 0.5.0

package/extensions/subagents/navigation.ts

@@ -2,21 +2,28 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 import type { TUI } from "@earendil-works/pi-tui";
 import {
   fitNavigationSides,
+  renderNavigationMetrics,
   type BelowEditorStripState,
 } from "../shared/below-editor-navigation.ts";
 import {
   unreadActivityCounts,
   type ActivityCounts,
 } from "../shared/activity-status.ts";
+import { spinnerFrame } from "../shared/spinner.ts";
 import { sanitizeTerminalText } from "../shared/terminal-text.ts";
 import { formatElapsed, type SubagentSnapshot } from "./src/domain.ts";
-import { formatContextUtilization } from "./src/format.ts";
+import { contextPercent } from "../shared/context-utilization.ts";
 
 export interface SubagentStripEntry {
   snapshot: SubagentSnapshot;
   counts: ActivityCounts;
 }
 
+/** Changes only when the strip needs an immediate lifecycle repaint. */
+export function subagentStripEntryKey(entry: SubagentStripEntry | undefined) {
+  return entry ? `${entry.snapshot.id}:${entry.snapshot.status}` : undefined;
+}
+
 function cleanLine(value: string) {
   return sanitizeTerminalText(value).replace(/\s+/g, " ").trim();
 }
@@ -58,13 +65,22 @@ function statusColor(status: SubagentSnapshot["status"]) {
   return "error" as const;
 }
 
-function statusSquare(snapshot: SubagentSnapshot, theme: Theme) {
-  return theme.fg(statusColor(snapshot.status), "■");
+/**
+ * One status indicator per run state; doubles as the focus marker when
+ * selected. Running spins, in step with the dashboard and takeover headers.
+ */
+function statusGlyph(snapshot: SubagentSnapshot, theme: Theme, now: number) {
+  if (snapshot.status === "running")
+    return theme.fg("warning", spinnerFrame(now));
+  if (snapshot.status === "done") return theme.fg("success", "✓");
+  return theme.fg("error", "✗");
 }
 
+const SUBAGENT_STRIP_INTERVAL_MS = 500;
+
 /** One-line subagent manager entry with the same affordance as Workflow. */
 export class SubagentStripWidget {
-  private readonly timer: ReturnType<typeof setInterval>;
+  private timer: ReturnType<typeof setInterval> | undefined;
   private readonly tui: TUI;
   private readonly theme: Theme;
   private readonly strip: BelowEditorStripState;
@@ -80,42 +96,84 @@ export class SubagentStripWidget {
     this.theme = theme;
     this.strip = strip;
     this.getEntry = getEntry;
-    this.timer = setInterval(() => this.tui.requestRender(), 500);
-    this.timer.unref?.();
+    this.syncSpinner();
   }
 
   dispose() {
-    clearInterval(this.timer);
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
   }
 
-  invalidate() {}
+  invalidate() {
+    this.syncSpinner();
+  }
+
+  private syncSpinner() {
+    if (this.getEntry()?.snapshot.status === "running") {
+      if (this.timer) return;
+      const timer = setInterval(() => {
+        if (this.timer !== timer) return;
+        if (this.getEntry()?.snapshot.status !== "running") {
+          clearInterval(timer);
+          this.timer = undefined;
+        }
+        this.tui.requestRender();
+      }, SUBAGENT_STRIP_INTERVAL_MS);
+      this.timer = timer;
+      timer.unref?.();
+      return;
+    }
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
 
   render(width: number) {
+    this.syncSpinner();
     const entry = this.getEntry();
     if (!entry || width <= 0) return [];
     const { snapshot, counts } = entry;
-    const marker = this.strip.focused
+    const glyph = this.strip.focused
       ? this.theme.fg("accent", "❯")
-      : this.theme.fg("dim", "○");
-    const titleText = normalizeSubagentTitle(snapshot.title, snapshot.id);
-    const title = this.strip.focused
-      ? this.theme.bold(this.theme.fg("accent", titleText))
-      : this.theme.fg("text", titleText);
-    const model = snapshot.meta.modelLabel
-      ? cleanLine(snapshot.meta.modelLabel)
-      : undefined;
-    const left = ` ${marker} ${statusSquare(snapshot, this.theme)} ${title}${model ? this.theme.fg("dim", ` · ${model}`) : ""}`;
-    const settled = counts.done + counts.failed;
-    const total = counts.running + settled;
-    const metrics = [
-      `${settled}/${total} agents`,
-      formatElapsed(snapshot),
-      formatContextUtilization(snapshot.usage),
+      : statusGlyph(snapshot, this.theme, Date.now());
+    // A name only means something when it names the only active subagent; with
+    // several, an aggregate label is honest and the counts carry the detail.
+    const total = counts.running + counts.done + counts.failed;
+    const single = total === 1;
+    const labelText = single
+      ? normalizeSubagentTitle(snapshot.title, snapshot.id)
+      : "subagents";
+    const label = this.strip.focused
+      ? this.theme.bold(this.theme.fg("accent", labelText))
+      : this.theme.fg("text", labelText);
+    // The footer already shows the session model; the takeover view keeps the
+    // per-subagent model, so the one-line strip stays title-only.
+    const left = ` ${glyph} ${label}`;
+    // Worded counts read at a glance; the selected run's own state comes
+    // first so the emphasis colour always lands on the matching count. A lone
+    // subagent needs no count — the glyph and label already say it.
+    const donePart = counts.done > 0 ? `${counts.done} done` : undefined;
+    const failedPart =
+      counts.failed > 0 ? `${counts.failed} failed` : undefined;
+    const activity = single
+      ? []
+      : counts.running > 0
+        ? [`${counts.running} running`]
+        : snapshot.status === "error"
+          ? [failedPart, donePart]
+          : [donePart, failedPart];
+    const percent = contextPercent(snapshot.usage);
+    const right = renderNavigationMetrics(
+      this.theme,
+      [
+        ...activity,
+        formatElapsed(snapshot),
+        percent === undefined ? undefined : `${percent}% ctx`,
+      ],
       this.strip.focused ? "enter open · ↑ back" : "↓ to manage",
-    ]
-      .filter((part): part is string => Boolean(part))
-      .join(" · ");
-    const right = this.theme.fg(statusColor(snapshot.status), metrics);
+      single || snapshot.status === "running"
+        ? undefined
+        : statusColor(snapshot.status),
+    );
     return [fitNavigationSides(left, right, width)];
   }
 }

package/extensions/subagents/src/agent-types.ts

@@ -24,18 +24,18 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import type { Model } from "@earendil-works/pi-ai";
 import {
-  parseFrontmatter,
   type ModelRegistry,
+  parseFrontmatter,
 } from "@earendil-works/pi-coding-agent";
 import {
   CHILD_EXCLUDED_TOOL_NAMES,
   CHILD_SAFE_PACKAGE_TOOL_NAMES,
 } from "../../shared/child-session.ts";
-import { sanitizeTerminalText } from "../../shared/terminal-text.ts";
 import {
   isSubagentRoleName,
   type SubagentRoleModel,
 } from "../../shared/subagent-roles.ts";
+import { sanitizeTerminalText } from "../../shared/terminal-text.ts";
 import { REASONING_EFFORTS, type ReasoningEffort } from "./domain.ts";
 
 /** Directory name scanned under both the agent dir and a project's `.pi`. */
@@ -101,7 +101,17 @@ export interface AgentType {
   readonly source: string;
 }
 
-const READ_ONLY_TOOLS = ["read", "grep", "find", "ls", "fd", "rg"];
+export const READ_ONLY_AGENT_TOOLS = [
+  "read",
+  "grep",
+  "find",
+  "ls",
+  "fd",
+  "rg",
+  "git_show",
+  "git_diff",
+  "git_log",
+];
 
 /**
  * Built-in role definitions are deliberately provider-free: model selection is
@@ -112,33 +122,45 @@ export const BUILT_IN_AGENT_TYPES: readonly AgentType[] = [
   {
     name: "explorer",
     description:
-      "Read-only codebase exploration. Use high for routine, local, direct tracing; xhigh for interacting state transitions, concurrency or trust boundaries, or subtle multi-path lifecycle/control-flow; max only for exceptionally difficult broad unfamiliar architecture with unresolved competing flows.",
-    tools: READ_ONLY_TOOLS,
-    reasoningEffort: "high",
+      "Read-only codebase exploration. Usually use moderate reasoning, increasing it for harder tasks.",
+    tools: READ_ONLY_AGENT_TOOLS,
     body: "Explore the codebase read-only. Trace the real flow, inspect related callers, and report concise evidence with file paths and line references.",
     source: "built-in:explorer",
   },
   {
     name: "implementer",
-    description: "Focused implementation with repository checks.",
-    tools: ["read", "bash", "edit", "write", "grep", "find", "ls", "fd", "rg"],
-    reasoningEffort: "high",
+    description:
+      "Focused implementation with repository checks. Usually use medium-high reasoning, adjusted for scope, risk, and task difficulty.",
+    tools: [
+      "read",
+      "bash",
+      "edit",
+      "write",
+      "grep",
+      "find",
+      "ls",
+      "fd",
+      "rg",
+      "git_show",
+      "git_diff",
+      "git_log",
+    ],
     body: "Implement the requested change carefully. Trace the affected flow first, make the smallest correct edit, and run relevant checks before reporting results.",
     source: "built-in:implementer",
   },
   {
     name: "reviewer",
-    description: "Read-only review for correctness, safety, and regressions.",
-    tools: READ_ONLY_TOOLS,
-    reasoningEffort: "medium",
+    description:
+      "Read-only review for correctness, safety, and regressions. Usually use high reasoning, adjusted for task difficulty.",
+    tools: READ_ONLY_AGENT_TOOLS,
     body: "Review the requested code or change read-only. Identify concrete correctness, security, and regression risks with evidence; do not modify files.",
     source: "built-in:reviewer",
   },
   {
     name: "advisor",
-    description: "Deep read-only analysis and technical advice.",
-    tools: READ_ONLY_TOOLS,
-    reasoningEffort: "xhigh",
+    description:
+      "Deep read-only analysis and technical advice. Usually use high reasoning, adjusted for task difficulty.",
+    tools: READ_ONLY_AGENT_TOOLS,
     body: "Analyze the problem deeply without modifying files. Explain the relevant tradeoffs, risks, and recommended next step using repository evidence.",
     source: "built-in:advisor",
   },

package/extensions/subagents/src/backend.ts

@@ -5,11 +5,11 @@
  * on it rather than on the pi session directly.
  *
  * - pi (./backends/pi.ts): in-process `createAgentSession()` via the pi SDK.
- * - stub (./backends/stub.ts): scripted sessions, test-only.
  */
 
 import type { Effect, Scope, Stream } from "effect";
 import { Context } from "effect";
+import type { AgentToolRenderer } from "../../shared/agent-tool-renderer.ts";
 import type {
   BackendName,
   SendError,
@@ -19,6 +19,13 @@ import type {
   SubagentMeta,
 } from "./domain.ts";
 
+export interface SubagentCleanupReceipt {
+  /** True when the session/worktree state could not be proven quiescent. */
+  readonly uncertain: boolean;
+  /** Bounded operator-facing explanation of the cleanup result. */
+  readonly message: string;
+}
+
 /**
  * A live subagent session. The manager is the single consumer of `events`;
  * it folds them into the `SubagentSnapshot` everything else reads.
@@ -42,6 +49,10 @@ export interface SubagentSession {
    * this with a timeout and fall back to closing the session scope.
    */
   readonly interrupt: Effect.Effect<void>;
+  /** Ephemeral Pi-native tool projection for the operator-facing child page. */
+  readonly toolRenderer?: AgentToolRenderer;
+  /** Cleanup receipt populated when scope teardown cannot prove safety. */
+  readonly cleanupReceipt?: () => SubagentCleanupReceipt | undefined;
 }
 
 export interface SubagentBackend {