@gotgenes/pi-subagents 6.12.0 → 6.12.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.12.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.12.0...pi-subagents-v6.12.1) (2026-05-22)
+
+
+### Documentation
+
+* mark Step J done, add ui/display.ts to module listing ([#135](https://github.com/gotgenes/pi-packages/issues/135)) ([37ced45](https://github.com/gotgenes/pi-packages/commit/37ced45e1a0287aa78e588cb8bc7905c0f969637))
+* plan display helper extraction from agent-widget ([#135](https://github.com/gotgenes/pi-packages/issues/135)) ([9e65e7d](https://github.com/gotgenes/pi-packages/commit/9e65e7d93bf47d4c4582d367d2f31a2386a5cc8c))
+* **retro:** add retro notes for issue [#134](https://github.com/gotgenes/pi-packages/issues/134) ([775ce99](https://github.com/gotgenes/pi-packages/commit/775ce99710153d4ebcf40f773eae21553c7f8a82))
+
 ## [6.12.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.11.0...pi-subagents-v6.12.0) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -68,6 +68,7 @@ notification.ts           — completion nudges, custom message renderer
 renderer.ts               — notification TUI component
 record-observer.ts        — session-event observer for record statistics
 
+ui/display.ts             — pure formatters, display helpers, and shared types (Theme, AgentDetails)
 ui/agent-widget.ts        — above-editor live status widget
 ui/agent-menu.ts          — /agents slash command menu
 ui/conversation-viewer.ts — scrollable session overlay
@@ -564,16 +565,12 @@ Production changes:
 
 Remaining 15 `as any` casts are: 8 menu-handler `ctx as any` (deferred — requires `AgentManager.spawn` to accept `ParentSnapshot` directly), 2 `print-mode.test.ts` (same ExtensionContext/API pattern), 2 private-field test access, 1 `createSession` SDK bridge in `index.ts`, 1 `foreground-runner.ts` `AgentToolResult<any>` detail, 1 `stub-ctx.ts` comment.
 
-### Step J: Extract display helpers (#135)
+### Step J: Extract display helpers (#135) ✓ done
 
-`agent-widget.ts` (600 lines) exports 11 helper functions and constants that are used by both the widget and the menu.
-Extract these into `ui/display.ts`:
-
-- Pure formatters: `formatTokens`, `formatSessionTokens`, `formatTurns`, `formatMs`, `formatDuration`.
-- Display helpers: `getDisplayName`, `getPromptModeLabel`, `buildInvocationTags`, `describeActivity`.
-- Constants: `SPINNER`, `ERROR_STATUSES`, `TOOL_DISPLAY`.
-
-Impact: `agent-widget.ts` drops from 600 → ~420 lines; shared display logic has a single import point; menu and tool modules stop importing from the widget.
+`ui/display.ts` now contains all pure formatters, display helpers, constants, and shared types (`Theme`, `AgentDetails`).
+`agent-widget.ts` dropped from 522 → ~340 lines.
+All consumer modules (menu, tools, renderer, conversation viewer) import from `ui/display.ts` directly.
+`test/agent-widget.test.ts` renamed to `test/display.test.ts`.
 
 ### Step K: Decompose agent-menu.ts (#136)
 

package/docs/plans/0135-extract-display-helpers.md

@@ -0,0 +1,182 @@
+---
+issue: 135
+issue_title: "Extract display helpers from `agent-widget.ts`"
+---
+
+# Extract display helpers from agent-widget.ts
+
+## Problem Statement
+
+`agent-widget.ts` (522 lines) exports 11 helper functions and constants that are general-purpose display utilities with no dependency on the widget's lifecycle or state.
+Six other source modules (`agent-menu.ts`, `conversation-viewer.ts`, `renderer.ts`, `agent-tool.ts`, `foreground-runner.ts`, `get-result-tool.ts`) and two tool support modules (`helpers.ts`, `background-spawner.ts`) import formatting functions or display types from the widget — creating a false dependency on a lifecycle-heavy UI module.
+
+This is Phase 8, Step J of the architecture plan.
+
+## Goals
+
+- Extract pure formatters, display helpers, constants, and associated types into `ui/display.ts`.
+- Update all import sites to import from `ui/display.ts` instead of `ui/agent-widget.ts`.
+- Reduce `agent-widget.ts` to only the `AgentWidget` class and its immediate dependencies (`UICtx`, private helpers).
+- Unblock Step K (menu decomposition, #136) — extracted menu sub-modules will import display helpers without pulling in the widget.
+
+## Non-Goals
+
+- Decomposing `agent-menu.ts` — deferred to #136 (Step K).
+- Changing any runtime behavior or public API.
+- Extracting `UICtx` — it is a widget-lifecycle type used only by `AgentWidget`, `runtime.ts`, and `index.ts`.
+
+## Background
+
+The architecture doc (Phase 8 roadmap, Step J) prescribes exactly which symbols to extract.
+The `code-design` skill's "Helpers stay in the file" rule applies: these helpers have accumulated to the point where they warrant their own module and tests.
+AGENTS.md's "one concern per file" constraint also supports the extraction.
+
+### Symbols to extract
+
+#### Pure formatters (zero runtime dependencies)
+
+1. `formatTokens(count)` — compact token count ("33.8k token").
+2. `formatSessionTokens(tokens, percent, theme, compactions)` — annotated token string with threshold colors.
+3. `formatTurns(turnCount, maxTurns)` — turn counter with optional limit.
+4. `formatMs(ms)` — milliseconds → "1.2s".
+5. `formatDuration(startedAt, completedAt)` — timestamp pair → human duration.
+
+#### Display helpers (registry lookup only)
+
+6. `getDisplayName(type, registry)` — resolved display name for an agent type.
+7. `getPromptModeLabel(type, registry)` — "twin" for append mode, undefined otherwise.
+8. `buildInvocationTags(invocation)` — config tags array from invocation options.
+9. `describeActivity(activeTools, responseText)` — human-readable activity string.
+
+#### Constants
+
+10. `SPINNER` — braille spinner frames.
+11. `ERROR_STATUSES` — set of error/non-success status strings.
+12. `TOOL_DISPLAY` — tool name → action verb mapping (private, moves with `describeActivity`).
+
+#### Types
+
+13. `Theme` — used in `formatSessionTokens` signature; must co-locate.
+14. `AgentDetails` — display metadata interface used by tools; no widget dependency.
+
+`UICtx` stays in `agent-widget.ts` — it defines the widget's host contract and is only consumed by the widget class, `runtime.ts`, and `index.ts`.
+
+### Current import graph (agent-widget.ts consumers)
+
+| Consumer                           | Symbols imported                                                                                                                    |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `ui/conversation-viewer.ts`        | `buildInvocationTags`, `describeActivity`, `formatDuration`, `formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`, `Theme` |
+| `ui/agent-menu.ts`                 | `formatDuration`, `getDisplayName`                                                                                                  |
+| `tools/agent-tool.ts`              | `AgentDetails`, `buildInvocationTags`, `formatMs`, `formatTurns`, `getDisplayName`, `getPromptModeLabel`, `SPINNER`, `UICtx`        |
+| `tools/foreground-runner.ts`       | `AgentDetails`, `describeActivity`, `formatMs`, `SPINNER`                                                                           |
+| `tools/get-result-tool.ts`         | `formatDuration`, `getDisplayName`                                                                                                  |
+| `tools/helpers.ts`                 | `AgentDetails`, `formatTokens`                                                                                                      |
+| `tools/background-spawner.ts`      | `AgentDetails`                                                                                                                      |
+| `renderer.ts`                      | `formatMs`, `formatTokens`, `formatTurns`                                                                                           |
+| `runtime.ts`                       | `UICtx`                                                                                                                             |
+| `index.ts`                         | `AgentWidget`, `UICtx`                                                                                                              |
+| `test/agent-widget.test.ts`        | `formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`                                                                       |
+| `test/conversation-viewer.test.ts` | `Theme`                                                                                                                             |
+
+### Post-extraction import graph
+
+After extraction, `ui/agent-widget.ts` imports `display.ts` for the symbols it still uses internally (e.g., `getDisplayName`, `formatMs`, `formatTurns`, `formatSessionTokens`, `ERROR_STATUSES`, `SPINNER`, `describeActivity`).
+All other consumers switch their imports from `./agent-widget.js` to `./display.js` (or `../ui/display.js` for `tools/` and `renderer.ts`).
+
+Only `index.ts` and `runtime.ts` continue to import from `agent-widget.ts` (for `AgentWidget` class and `UICtx` type).
+`tools/agent-tool.ts` splits its import: `UICtx` from `agent-widget.ts`, everything else from `display.ts`.
+
+## Design Overview
+
+This is a pure code-motion refactoring — no behavior changes.
+
+### New module: `ui/display.ts`
+
+Contains all 12 exported symbols (5 formatters, 4 display helpers, 3 constants) plus 2 types (`Theme`, `AgentDetails`) and 1 private helper (`truncateLine`, used by `describeActivity`).
+
+The module's only imports are:
+
+- `AgentConfigLookup` from `../agent-types.js` (type-only, for `getDisplayName`/`getPromptModeLabel`).
+- `SubagentType`, `AgentInvocation` from `../types.js` (type-only).
+
+No SDK imports, no runtime dependencies — exactly the kind of pure utility module the code-design skill prescribes.
+
+### Residual `agent-widget.ts`
+
+After extraction, `agent-widget.ts` contains:
+
+- `UICtx` type (widget host contract).
+- `AgentWidget` class (~340 lines) with its private helpers.
+- Imports from `./display.js` for the format/display functions used in rendering.
+
+## Module-Level Changes
+
+### New files
+
+| File                | Contents                                                                                                                                                                                                                                                                                    |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/display.ts` | All extracted symbols: `Theme`, `AgentDetails`, `SPINNER`, `ERROR_STATUSES`, `TOOL_DISPLAY`, `formatTokens`, `formatSessionTokens`, `formatTurns`, `formatMs`, `formatDuration`, `getDisplayName`, `getPromptModeLabel`, `buildInvocationTags`, `describeActivity`, private `truncateLine`. |
+
+### Modified files
+
+| File                               | Change                                                                                                                                                                     |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/agent-widget.ts`           | Remove all extracted symbols. Add `import` from `./display.js` for symbols `AgentWidget` still uses internally. Keep `UICtx`, `AgentWidget` class, private widget helpers. |
+| `src/ui/conversation-viewer.ts`    | Change import path from `./agent-widget.js` to `./display.js`.                                                                                                             |
+| `src/ui/agent-menu.ts`             | Change import path from `./agent-widget.js` to `./display.js`.                                                                                                             |
+| `src/tools/agent-tool.ts`          | Split import: `UICtx` from `../ui/agent-widget.js`; all others from `../ui/display.js`.                                                                                    |
+| `src/tools/foreground-runner.ts`   | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/get-result-tool.ts`     | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/helpers.ts`             | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/tools/background-spawner.ts`  | Change import path from `../ui/agent-widget.js` to `../ui/display.js`.                                                                                                     |
+| `src/renderer.ts`                  | Change import path from `./ui/agent-widget.js` to `./ui/display.js`.                                                                                                       |
+| `test/agent-widget.test.ts`        | Change import path to `../src/ui/display.js`. Rename file to `test/display.test.ts` since it tests extracted functions.                                                    |
+| `test/conversation-viewer.test.ts` | Change `Theme` import from `../src/ui/agent-widget.js` to `../src/ui/display.js`.                                                                                          |
+
+### Unchanged files
+
+| File             | Reason                                                              |
+| ---------------- | ------------------------------------------------------------------- |
+| `src/runtime.ts` | Imports only `UICtx` — stays in `agent-widget.ts`.                  |
+| `src/index.ts`   | Imports `AgentWidget` and `UICtx` — both stay in `agent-widget.ts`. |
+
+## Test Impact Analysis
+
+1. The extraction enables dedicated `display.test.ts` that tests formatting functions in isolation without any widget class ceremony.
+   The existing `agent-widget.test.ts` already tests only extracted functions (`formatSessionTokens`, `getDisplayName`, `getPromptModeLabel`) — it becomes `display.test.ts` with no assertion changes, just a file rename and import path update.
+2. No existing tests become redundant — the current test file already exercises the extracted layer exclusively.
+3. No existing tests need assertion changes — this is a pure code-motion refactoring with no behavior change.
+
+## TDD Order
+
+1. **Create `ui/display.ts` with all extracted symbols; update `agent-widget.ts` to import from it.**
+   Move the 12 exported symbols, 2 types, and 1 private helper to `ui/display.ts`.
+   Remove them from `agent-widget.ts` and add imports from `./display.js` for symbols the `AgentWidget` class still references.
+   Commit: `refactor: extract display helpers into ui/display.ts (#135)`
+
+2. **Update all consumer imports to point at `ui/display.ts`.**
+   Update the 8 source files (`conversation-viewer.ts`, `agent-menu.ts`, `agent-tool.ts`, `foreground-runner.ts`, `get-result-tool.ts`, `helpers.ts`, `background-spawner.ts`, `renderer.ts`) to import from the new module.
+   Commit: `refactor: update imports to use ui/display.ts (#135)`
+
+3. **Rename test file and update test imports.**
+   Rename `test/agent-widget.test.ts` → `test/display.test.ts`.
+   Update import path to `../src/ui/display.js`.
+   Update `Theme` import in `test/conversation-viewer.test.ts`.
+   Commit: `test: rename agent-widget test to display test (#135)`
+
+4. **Verify: run `pnpm run check` and `pnpm vitest run`.**
+   Confirm type-checking and all tests pass.
+   No commit needed — validation step.
+
+## Risks and Mitigations
+
+| Risk                                                 | Mitigation                                                                                                             |
+| ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Missed import site causes runtime `undefined` import | Grep confirmed all 10 source consumers and 2 test consumers above. Step 4 validates with type-check + full test suite. |
+| `TOOL_DISPLAY` made public unintentionally           | Keep it non-exported in `display.ts` (only `describeActivity` uses it).                                                |
+| Circular dependency `display.ts` ↔ `agent-widget.ts` | `display.ts` has no imports from `agent-widget.ts`. `agent-widget.ts` imports from `display.ts` — one-directional.     |
+| Re-export churn for downstream consumers             | No downstream consumers — these are all internal module imports, not public API.                                       |
+
+## Open Questions
+
+None — the architecture doc and issue specify the exact extraction set and target module.

package/docs/retro/0134-reduce-as-any-casts.md

@@ -0,0 +1,56 @@
+---
+issue: 134
+issue_title: "Reduce `as any` casts in test suite"
+---
+
+# Retro: #134 — Reduce as-any casts in test suite
+
+## Final Retrospective (2026-05-22T17:00:00Z)
+
+### Session summary
+
+Reduced `as any` casts from 93 to 15 across the pi-subagents package.
+Production changes added type guards (`getToolCallName`, `isBashExecution`), narrowed `SubagentRuntime.widget` to `WidgetLike`, typed `CreateSessionOptions.settingsManager` as `SettingsManager`, and fixed `ResourceLoaderOptions.appendSystemPromptOverride` to match the SDK.
+Test improvements introduced `toAgentSession()`, `STUB_CTX`, and `makeRegistry()` helpers to centralise unavoidable bridge casts.
+Also fixed 3 pre-existing lint issues.
+
+This session also included #133 (plan + implement + ship) which preceded the #134 work.
+
+### Observations
+
+#### What went well
+
+- The user's Kent Beck prompt ("make the change that makes the change easy") redirected the plan from test-only fixes to targeted production changes, yielding cleaner results — `WidgetLike`, type guards, and SDK-typed options eliminated casts that would have been impossible to remove from tests alone.
+- The user's TDA observation on the `MenuCtx` step caught a deep architectural issue (context threaded 4 layers just to relay to `buildParentSnapshot`).
+  Skipping step 4 was the right call — attempting it would have added a production cast or cascaded changes through 6+ files.
+
+#### What caused friction (agent side)
+
+1. `rabbit-hole` — Step 1 planning involved extensive analysis of whether `CreateSessionOptions` could use full SDK types.
+   Spent significant reasoning tracing `ModelRegistry` / `SessionManager` private fields, structural compatibility, `ParentSnapshot` constructibility, and `ResourceLoader` interface width before concluding that only `settingsManager` and the callback signature could be fixed.
+   The plan's claim "widen to SDK types" was optimistic about class-with-private-fields constraints.
+   Impact: added friction but no rework — the conclusion was correct, just slow to reach.
+
+2. `wrong-abstraction` — Step 4 (`MenuCtx`) attempted to mechanically narrow the handler parameter without questioning why `ctx` was threaded 4 layers deep.
+   Partially implemented the `MenuCtx` interface before the user's "What am I misunderstanding?"
+   prompt exposed the real issue: a TDA violation where intermediate functions carry `ExtensionContext` only to relay it.
+   Impact: partial implementation reverted via `git checkout src/ui/agent-menu.ts`; ~10 minutes of wasted edits.
+
+3. `instruction-violation` (user-caught) — Used `pnpm exec biome check --write --unsafe` instead of `pnpm run lint:fix` to fix pre-existing lint issues.
+   The `/tdd-plan` prompt explicitly says "run `pnpm run lint:fix`."
+   Impact: no functional difference (same result), but violated the established convention and used an unnecessary `--unsafe` flag.
+
+4. `instruction-violation` (user-caught) — Dismissed pre-existing lint issues as "not from our changes" without fixing them.
+   The user asked "Why do we have pre-existing lint issues?"
+   — the correct action was to fix them immediately rather than noting and ignoring them.
+   Impact: required an extra commit (`style: fix pre-existing lint issues`) that should have been folded into an earlier step.
+
+#### What caused friction (user side)
+
+- The user's interventions on the `MenuCtx` step and lint issues were both valuable redirections that improved the outcome.
+  No mechanical overhead identified — each intervention was strategic judgment that the agent couldn't have reached alone.
+
+### Changes made
+
+1. `.pi/prompts/tdd-plan.md` — added "Verify green baseline" section (check + lint + test before starting TDD); added "Fix all failures — including pre-existing ones" to the end-of-cycle lint step.
+2. `.pi/prompts/build-plan.md` — same baseline check and fix-all rule for non-TDD plans.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.12.0",
+  "version": "6.12.1",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/renderer.ts

@@ -1,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import type { NotificationDetails } from "./notification.js";
-import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
+import { formatMs, formatTokens, formatTurns } from "./ui/display.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */
 interface RendererTheme {

package/src/tools/agent-tool.ts

@@ -9,6 +9,7 @@ import { resolveInvocationModel } from "../model-resolver.js";
 
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import { type UICtx } from "../ui/agent-widget.js";
 import {
   type AgentDetails,
   buildInvocationTags,
@@ -17,8 +18,7 @@ import {
   getDisplayName,
   getPromptModeLabel,
   SPINNER,
-  type UICtx,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
 import { buildDetails, buildTypeListText, textResult } from "./helpers.js";

package/src/tools/background-spawner.ts

@@ -2,7 +2,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSpawnConfig } from "../agent-manager.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import type { AgentDetails } from "../ui/agent-widget.js";
+import type { AgentDetails } from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import { textResult } from "./helpers.js";

package/src/tools/foreground-runner.ts

@@ -8,7 +8,7 @@ import {
   describeActivity,
   formatMs,
   SPINNER,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import {

package/src/tools/get-result-tool.ts

@@ -2,7 +2,7 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "../agent-types.js";
 import type { AgentRecord } from "../types.js";
-import { formatDuration, getDisplayName } from "../ui/agent-widget.js";
+import { formatDuration, getDisplayName } from "../ui/display.js";
 import { getSessionContextPercent } from "../usage.js";
 import { formatLifetimeTokens, textResult } from "./helpers.js";
 

package/src/tools/helpers.ts

@@ -1,6 +1,6 @@
 import type { AgentConfigLookup } from "../agent-types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import { type AgentDetails, formatTokens } from "../ui/agent-widget.js";
+import { type AgentDetails, formatTokens } from "../ui/display.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
 /** Parenthetical status note for completed agent result text. */

package/src/ui/agent-menu.ts

@@ -10,7 +10,7 @@ import {
 import type { ModelRegistry } from "../model-resolver.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
-import { formatDuration, getDisplayName } from "./agent-widget.js";
+import { formatDuration, getDisplayName } from "./display.js";
 
 // ---- Deps interface ----
 

package/src/ui/agent-widget.ts

@@ -7,40 +7,29 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
-import { type AgentConfigLookup, AgentTypeRegistry } from "../agent-types.js";
-import type { AgentInvocation, SubagentType } from "../types.js";
+import { AgentTypeRegistry } from "../agent-types.js";
+import type { SubagentType } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
+import {
+  describeActivity,
+  ERROR_STATUSES,
+  formatMs,
+  formatSessionTokens,
+  formatTurns,
+  getDisplayName,
+  getPromptModeLabel,
+  SPINNER,
+  type Theme,
+} from "./display.js";
 
 // ---- Constants ----
 
 /** Maximum number of rendered lines before overflow collapse kicks in. */
 const MAX_WIDGET_LINES = 12;
 
-/** Braille spinner frames for animated running indicator. */
-export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
-
-/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
-export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
-
-/** Tool name → human-readable action for activity descriptions. */
-const TOOL_DISPLAY: Record<string, string> = {
-  read: "reading",
-  bash: "running command",
-  edit: "editing",
-  write: "writing",
-  grep: "searching",
-  find: "finding files",
-  ls: "listing",
-};
-
 // ---- Types ----
 
-export type Theme = {
-  fg(color: string, text: string): string;
-  bold(text: string): string;
-};
-
 export type UICtx = {
   setStatus(key: string, text: string | undefined): void;
   setWidget(
@@ -50,147 +39,6 @@ export type UICtx = {
   ): void;
 };
 
-/** Metadata attached to Agent tool results for custom rendering. */
-export interface AgentDetails {
-  displayName: string;
-  description: string;
-  subagentType: string;
-  toolUses: number;
-  tokens: string;
-  durationMs: number;
-  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
-  /** Human-readable description of what the agent is currently doing. */
-  activity?: string;
-  /** Current spinner frame index (for animated running indicator). */
-  spinnerFrame?: number;
-  /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
-  modelName?: string;
-  /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
-  tags?: string[];
-  /** Current turn count. */
-  turnCount?: number;
-  /** Effective max turns (undefined = unlimited). */
-  maxTurns?: number;
-  agentId?: string;
-  error?: string;
-}
-
-// ---- Formatting helpers ----
-
-/** Format a token count compactly: "33.8k token", "1.2M token". */
-export function formatTokens(count: number): string {
-  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
-  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
-  return `${count} token`;
-}
-
-/**
- * Token count with optional context-fill % and compaction-count annotations.
- * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
- *
- *   "12.3k token"               — no annotations
- *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
- */
-export function formatSessionTokens(
-  tokens: number,
-  percent: number | null,
-  theme: Theme,
-  compactions = 0,
-): string {
-  const tokenStr = formatTokens(tokens);
-  const annot: string[] = [];
-  if (percent !== null) {
-    const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
-    annot.push(theme.fg(color, `${Math.round(percent)}%`));
-  }
-  if (compactions > 0) {
-    annot.push(theme.fg("dim", `↻${compactions}`));
-  }
-  if (annot.length === 0) return tokenStr;
-  return `${tokenStr} (${annot.join(" · ")})`;
-}
-
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
-export function formatTurns(turnCount: number, maxTurns?: number | null): string {
-  return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
-}
-
-/** Format milliseconds as human-readable duration. */
-export function formatMs(ms: number): string {
-  return `${(ms / 1000).toFixed(1)}s`;
-}
-
-/** Format duration from start/completed timestamps. */
-export function formatDuration(startedAt: number, completedAt?: number): string {
-  if (completedAt) return formatMs(completedAt - startedAt);
-  return `${formatMs(Date.now() - startedAt)} (running)`;
-}
-
-/** Get display name for any agent type (built-in or custom). */
-export function getDisplayName(type: SubagentType, registry: AgentConfigLookup): string {
-  const config = registry.resolveAgentConfig(type);
-  return config.displayName ?? config.name;
-}
-
-/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
-export function getPromptModeLabel(type: SubagentType, registry: AgentConfigLookup): string | undefined {
-  const config = registry.resolveAgentConfig(type);
-  return config.promptMode === "append" ? "twin" : undefined;
-}
-
-/** Mode label is not included — callers add it where they want it. */
-export function buildInvocationTags(
-  invocation: AgentInvocation | undefined,
-): { modelName?: string; tags: string[] } {
-  const tags: string[] = [];
-  if (!invocation) return { tags };
-  if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
-  if (invocation.isolated) tags.push("isolated");
-  if (invocation.isolation === "worktree") tags.push("worktree");
-  if (invocation.inheritContext) tags.push("inherit context");
-  if (invocation.runInBackground) tags.push("background");
-  if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);
-  return { modelName: invocation.modelName, tags };
-}
-
-/** Truncate text to a single line, max `len` chars. */
-function truncateLine(text: string, len = 60): string {
-  const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
-  if (line.length <= len) return line;
-  return line.slice(0, len) + "…";
-}
-
-/** Build a human-readable activity string from currently-running tools or response text. */
-export function describeActivity(activeTools: ReadonlyMap<string, string>, responseText?: string): string {
-  if (activeTools.size > 0) {
-    const groups = new Map<string, number>();
-    for (const toolName of activeTools.values()) {
-      const action = TOOL_DISPLAY[toolName] ?? toolName;
-      groups.set(action, (groups.get(action) ?? 0) + 1);
-    }
-
-    const parts: string[] = [];
-    for (const [action, count] of groups) {
-      if (count > 1) {
-        parts.push(`${action} ${count} ${action === "searching" ? "patterns" : "files"}`);
-      } else {
-        parts.push(action);
-      }
-    }
-    return parts.join(", ") + "…";
-  }
-
-  // No tools active — show truncated response text if available
-  if (responseText && responseText.trim().length > 0) {
-    return truncateLine(responseText);
-  }
-
-  return "thinking…";
-}
-
 // ---- Widget manager ----
 
 export class AgentWidget {

package/src/ui/conversation-viewer.ts

@@ -12,7 +12,7 @@ import { extractText } from "../context.js";
 import type { AgentRecord } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent } from "../usage.js";
 import type { AgentActivityTracker } from "./agent-activity-tracker.js";
-import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./agent-widget.js";
+import { buildInvocationTags, describeActivity, formatDuration, formatSessionTokens, getDisplayName, getPromptModeLabel, type Theme } from "./display.js";
 
 // ── Local message-shape types ───────────────────────────────────────────────
 // The Pi SDK does not export narrow types for all message content variants.

package/src/ui/display.ts

@@ -0,0 +1,178 @@
+/**
+ * display.ts — Pure formatting helpers and display utilities for agent UI.
+ *
+ * All functions are stateless and dependency-free (no SDK, no widget lifecycle).
+ * Consumed by the widget, the menu, tool modules, and the notification renderer.
+ */
+
+import type { AgentConfigLookup } from "../agent-types.js";
+import type { AgentInvocation, SubagentType } from "../types.js";
+
+// ---- Types ----
+
+export type Theme = {
+  fg(color: string, text: string): string;
+  bold(text: string): string;
+};
+
+/** Metadata attached to Agent tool results for custom rendering. */
+export interface AgentDetails {
+  displayName: string;
+  description: string;
+  subagentType: string;
+  toolUses: number;
+  tokens: string;
+  durationMs: number;
+  status: "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error" | "background";
+  /** Human-readable description of what the agent is currently doing. */
+  activity?: string;
+  /** Current spinner frame index (for animated running indicator). */
+  spinnerFrame?: number;
+  /** Short model name if different from parent (e.g. "haiku", "sonnet"). */
+  modelName?: string;
+  /** Notable config tags (e.g. ["thinking: high", "isolated"]). */
+  tags?: string[];
+  /** Current turn count. */
+  turnCount?: number;
+  /** Effective max turns (undefined = unlimited). */
+  maxTurns?: number;
+  agentId?: string;
+  error?: string;
+}
+
+// ---- Constants ----
+
+/** Braille spinner frames for animated running indicator. */
+export const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Statuses that indicate an error/non-success outcome (used for linger behavior and icon rendering). */
+export const ERROR_STATUSES = new Set(["error", "aborted", "steered", "stopped"]);
+
+/** Tool name → human-readable action for activity descriptions. */
+const TOOL_DISPLAY: Record<string, string> = {
+  read: "reading",
+  bash: "running command",
+  edit: "editing",
+  write: "writing",
+  grep: "searching",
+  find: "finding files",
+  ls: "listing",
+};
+
+// ---- Pure formatters ----
+
+/** Format a token count compactly: "33.8k token", "1.2M token". */
+export function formatTokens(count: number): string {
+  if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M token`;
+  if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k token`;
+  return `${count} token`;
+}
+
+/**
+ * Token count with optional context-fill % and compaction-count annotations.
+ * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
+ * Compaction count rendered as `↻N` in dim.
+ *
+ *   "12.3k token"               — no annotations
+ *   "12.3k token (45%)"         — percent only
+ *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ↻2)"    — both
+ */
+export function formatSessionTokens(
+  tokens: number,
+  percent: number | null,
+  theme: Theme,
+  compactions = 0,
+): string {
+  const tokenStr = formatTokens(tokens);
+  const annot: string[] = [];
+  if (percent !== null) {
+    const color = percent >= 85 ? "error" : percent >= 70 ? "warning" : "dim";
+    annot.push(theme.fg(color, `${Math.round(percent)}%`));
+  }
+  if (compactions > 0) {
+    annot.push(theme.fg("dim", `↻${compactions}`));
+  }
+  if (annot.length === 0) return tokenStr;
+  return `${tokenStr} (${annot.join(" · ")})`;
+}
+
+/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+export function formatTurns(turnCount: number, maxTurns?: number | null): string {
+  return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+}
+
+/** Format milliseconds as human-readable duration. */
+export function formatMs(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+/** Format duration from start/completed timestamps. */
+export function formatDuration(startedAt: number, completedAt?: number): string {
+  if (completedAt) return formatMs(completedAt - startedAt);
+  return `${formatMs(Date.now() - startedAt)} (running)`;
+}
+
+// ---- Display helpers ----
+
+/** Get display name for any agent type (built-in or custom). */
+export function getDisplayName(type: SubagentType, registry: AgentConfigLookup): string {
+  const config = registry.resolveAgentConfig(type);
+  return config.displayName ?? config.name;
+}
+
+/** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
+export function getPromptModeLabel(type: SubagentType, registry: AgentConfigLookup): string | undefined {
+  const config = registry.resolveAgentConfig(type);
+  return config.promptMode === "append" ? "twin" : undefined;
+}
+
+/** Mode label is not included — callers add it where they want it. */
+export function buildInvocationTags(
+  invocation: AgentInvocation | undefined,
+): { modelName?: string; tags: string[] } {
+  const tags: string[] = [];
+  if (!invocation) return { tags };
+  if (invocation.thinking) tags.push(`thinking: ${invocation.thinking}`);
+  if (invocation.isolated) tags.push("isolated");
+  if (invocation.isolation === "worktree") tags.push("worktree");
+  if (invocation.inheritContext) tags.push("inherit context");
+  if (invocation.runInBackground) tags.push("background");
+  if (invocation.maxTurns != null) tags.push(`max turns: ${invocation.maxTurns}`);
+  return { modelName: invocation.modelName, tags };
+}
+
+/** Truncate text to a single line, max `len` chars. */
+function truncateLine(text: string, len = 60): string {
+  const line = text.split("\n").find(l => l.trim())?.trim() ?? "";
+  if (line.length <= len) return line;
+  return line.slice(0, len) + "…";
+}
+
+/** Build a human-readable activity string from currently-running tools or response text. */
+export function describeActivity(activeTools: ReadonlyMap<string, string>, responseText?: string): string {
+  if (activeTools.size > 0) {
+    const groups = new Map<string, number>();
+    for (const toolName of activeTools.values()) {
+      const action = TOOL_DISPLAY[toolName] ?? toolName;
+      groups.set(action, (groups.get(action) ?? 0) + 1);
+    }
+
+    const parts: string[] = [];
+    for (const [action, count] of groups) {
+      if (count > 1) {
+        parts.push(`${action} ${count} ${action === "searching" ? "patterns" : "files"}`);
+      } else {
+        parts.push(action);
+      }
+    }
+    return parts.join(", ") + "…";
+  }
+
+  // No tools active — show truncated response text if available
+  if (responseText && responseText.trim().length > 0) {
+    return truncateLine(responseText);
+  }
+
+  return "thinking…";
+}