@gotgenes/pi-subagents 6.11.0 → 6.12.1

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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)
+
+
+### Features
+
+* narrow runtime widget field to WidgetLike interface ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([afa70ab](https://github.com/gotgenes/pi-packages/commit/afa70ab430109248a8f61ccd182b0f3acd1fa7e1))
+* use SDK types in CreateSessionOptions ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([c2452af](https://github.com/gotgenes/pi-packages/commit/c2452af0ee3d47d778878443a634ca787f8d0bfb))
+
+
+### Bug Fixes
+
+* replace message-shape as-any casts with type guards ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([d7ad65a](https://github.com/gotgenes/pi-packages/commit/d7ad65a61267790ae1ae8414b0c2aa9ebc8ad59c))
+
+
+### Documentation
+
+* plan as-any cast reduction in test suite ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([f7cb1aa](https://github.com/gotgenes/pi-packages/commit/f7cb1aac0963021ae0545b73c88f950a7adb5fd2))
+* **retro:** add retro notes for issue [#133](https://github.com/gotgenes/pi-packages/issues/133) ([be32640](https://github.com/gotgenes/pi-packages/commit/be32640048943059a98fc79797a35dfefd70fc34))
+* update architecture doc for Step I completion ([#134](https://github.com/gotgenes/pi-packages/issues/134)) ([fd4aca7](https://github.com/gotgenes/pi-packages/commit/fd4aca79c74da2b8c4e3c58e2376e0612941d7d9))
+
 ## [6.11.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.10.0...pi-subagents-v6.11.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
@@ -517,7 +518,7 @@ They are included here because the display extraction unblocks menu decompositio
 | ----------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------- |
 | ~~7 `vi.mock()` calls~~       | ~~`agent-runner.test.ts`~~                              | ~~Resolved by Step H (#133)~~                                     |
 | ~~7 `vi.mock()` calls~~       | ~~`agent-runner-extension-tools.test.ts`~~              | ~~Resolved by Step H (#133)~~                                     |
-| 52 `as any` casts             | Across test suite                                       | SDK session/context interfaces too wide to construct in tests     |
+| ~~52 `as any` casts~~         | ~~Across test suite~~                                   | ~~Reduced to 15 by Step I (#134)~~                                |
 | 3× duplicated `mockSession()` | agent-manager, record-observer, ui-observer tests       | No shared test fixture                                            |
 | 3× duplicated `makeDeps()`    | agent-tool, background-spawner, foreground-runner tests | No shared tool-deps fixture                                       |
 | Weak assertions               | lifecycle, renderer, session-config tests               | `toHaveBeenCalled()` without args, `toContain()` on large strings |
@@ -549,27 +550,27 @@ Impact: reduces test boilerplate; single source of truth for mock shapes; change
 
 Impact: all 7 `vi.mock()` calls eliminated from both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts`; tests verify behavior (turn limits, tool filtering, response collection) through injected stubs; SDK imports moved to the extension entry point.
 
-### Step I: Reduce `as any` casts in tests (#134)
+### Step I: Reduce `as any` casts in tests (#134) ✓ done
 
-With Steps G and H, many `as any` casts disappear because tests construct narrow injectable interfaces instead of wide SDK types.
-Remaining casts are addressed by:
+Reduced `as any` count from 93 to 15 (plus 13 explicit `as unknown as T` bridge casts).
 
-1. Defining a `TestSession` type in `test/helpers/` that satisfies `SubscribableSession` + the fields tests actually read.
-2. Replacing `const mockCtx = { cwd: "/tmp" } as any` with properly typed `AssemblerContext` or `ParentSnapshot` objects.
-3. Using `satisfies` assertions where possible instead of `as any`.
+Production changes:
 
-Target: reduce `as any` count from 52 to under 10.
+- `ResourceLoaderOptions.appendSystemPromptOverride` typed to match `DefaultResourceLoaderOptions`; `createResourceLoader` factory cast removed from `index.ts`.
+- `CreateSessionOptions.settingsManager` / `RunnerIO.createSettingsManager` typed as `SettingsManager`.
+- `WidgetLike` interface in `runtime.ts` narrows the widget field.
+- Local `ToolCallContent` / `BashExecutionMessage` type guards replace `as any` duck-typing in `conversation-viewer.ts` and `agent-runner.ts`.
+- `textResult()` return no longer casts `details as any`.
+- `toAgentSession()` helper and `STUB_CTX` constant centralise unavoidable bridge casts.
 
-### Step J: Extract display helpers (#135)
+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.
 
-`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`:
+### Step J: Extract display helpers (#135) ✓ done
 
-- 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/0134-reduce-as-any-casts.md

@@ -0,0 +1,366 @@
+---
+issue: 134
+issue_title: "Reduce `as any` casts in test suite"
+---
+
+# Reduce as-any casts in test suite
+
+## Problem Statement
+
+The test suite contains 93 `as any` casts (plus 2 `as any[]`).
+These casts silence the type checker, hiding real errors — if a production interface adds a required field, tests silently pass with incomplete mocks instead of failing at compile time.
+The heaviest offenders are `renderer.test.ts` (29), `runtime.test.ts` (10), `agent-menu.test.ts` (8), and `helpers.test.ts` (7).
+The production source has 8 `as any` casts — 2 SDK bridge casts in `index.ts` and 6 message-shape casts in `conversation-viewer.ts` and `agent-runner.ts`.
+
+## Goals
+
+- Target near-zero `as any` casts across both source and test code.
+- Widen `CreateSessionOptions` and `ResourceLoaderOptions` to use SDK types, eliminating the SDK bridge casts in `index.ts`.
+- Define local message-content types and type guards in `conversation-viewer.ts` and `agent-runner.ts`, eliminating polymorphic duck-typing casts.
+- Define narrow production interfaces (`MenuCtx`, `WidgetLike`) where SDK types are too wide for test construction.
+- Define typed test factories where partial mocks currently require casting.
+- Preserve existing test coverage — no behavior changes.
+
+## Non-Goals
+
+- Changing production behavior or public API shapes.
+- Reaching literally zero — 1–3 casts may remain for private-field test access (`(manager as any).cleanupInterval`) where the alternative (exposing internals) is worse than the cast.
+
+## Background
+
+### Prerequisites
+
+Issues #132 and #133 (IO injection) are both closed.
+These eliminated the `vi.mock()`-heavy test patterns and introduced narrow injectable interfaces (`AssemblerIO`, `RunnerIO`), which already removed some `as any` casts from `agent-runner.test.ts` and `session-config.test.ts`.
+
+### Current as-any inventory by pattern
+
+| Pattern                                          | Count | Primary files                                                                                                       |
+| ------------------------------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------- |
+| Renderer — theme, message, result access         | 29    | `renderer.test.ts`                                                                                                  |
+| Context — `ctx as any` for handler/menu          | 14    | `agent-menu.test.ts`, `agent-manager.test.ts`, `print-mode.test.ts`, `parent-snapshot.test.ts`, `make-deps.test.ts` |
+| Session — `{ session: {} as any }`               | 10    | tool tests, `service-adapter.test.ts`, `print-mode.test.ts`, `agent-manager.test.ts`                                |
+| Runtime/widget — `fakeWidget as any`             | 9     | `runtime.test.ts`                                                                                                   |
+| Conversation viewer — message shapes             | 8     | `conversation-viewer.test.ts`, `src/conversation-viewer.ts`                                                         |
+| Helpers — registry, activity, details            | 7     | `helpers.test.ts`                                                                                                   |
+| RunOptions — `} as any, io)`                     | 3     | `agent-runner.test.ts`                                                                                              |
+| Tool execute — `{} as any` for ctx               | 5     | `steer-tool.test.ts`, `get-result-tool.test.ts`, `make-deps.test.ts`                                                |
+| SDK bridge — `opts as any` in index.ts           | 2     | `src/index.ts`                                                                                                      |
+| Other — `messages: [] as any[]`, internal access | 6     | `agent-runner*.test.ts`, `usage.test.ts`, `agent-manager.test.ts`                                                   |
+
+### Constraints from AGENTS.md
+
+- Avoid `any` unless absolutely necessary.
+- Prefer explicit configuration over hidden behavior.
+- Keep scope tight; prefer small, reversible changes.
+
+## Design Overview
+
+### Production changes that make the test changes easy
+
+Three targeted source-code changes remove the structural blockers that force casts elsewhere.
+
+#### 1. SDK-typed option interfaces (eliminates 2 source casts)
+
+`CreateSessionOptions` and `ResourceLoaderOptions` currently use `unknown` for opaque fields (`settingsManager`, `modelRegistry`, `model`).
+Tests never construct these option objects — they mock `io.createSession` and `io.createResourceLoader` at the function level.
+The `unknown` fields don't buy testability; the function-level mock does.
+
+The SDK exports `CreateAgentSessionOptions` with all fields optional, using `ModelRegistry`, `Model<any>`, `ResourceLoader`, `SessionManager`, `SettingsManager`.
+Widening `CreateSessionOptions` to use these SDK types makes the `as any` cast in `index.ts` unnecessary while preserving full test mockability.
+
+```typescript
+// Before (agent-runner.ts)
+export interface CreateSessionOptions {
+  settingsManager: unknown;
+  modelRegistry: unknown;
+  model?: unknown;
+  // ...
+}
+
+// After — use SDK types (type-only imports)
+import type { Model } from "@earendil-works/pi-ai";
+import type {
+  ModelRegistry,
+  ResourceLoader,
+  SessionManager,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+export interface CreateSessionOptions {
+  settingsManager: SettingsManager;
+  modelRegistry: ModelRegistry;
+  model?: Model<any>;
+  resourceLoader: ResourceLoader;
+  sessionManager: SessionManager;
+  // ...
+}
+```
+
+The `RunnerIO.createSettingsManager` return type also changes from `unknown` to `SettingsManager`.
+
+For `ResourceLoaderOptions`, the options are all primitives and callbacks — the SDK's `DefaultResourceLoader` constructor accepts them structurally.
+The fix is to ensure the option interface matches the constructor's parameter type so `new DefaultResourceLoader(opts)` works without `as any`.
+
+#### 2. Local message-content types + type guards (eliminates 6 source casts)
+
+`conversation-viewer.ts` and `agent-runner.ts` both do:
+
+```typescript
+(c as any).name ?? (c as any).toolName ?? "unknown"
+(msg as any).role === "bashExecution"
+const bash = msg as any;
+```
+
+Fix: define local discriminated-union types for the content items and message roles the code actually handles, plus type guards:
+
+```typescript
+/** Tool-call content item — SDK doesn't export a narrow type for this variant. */
+interface ToolCallContent {
+  type: "toolCall";
+  name?: string;
+  toolName?: string;
+}
+
+function getToolCallName(c: { type: string }): string | undefined {
+  if (c.type !== "toolCall") return undefined;
+  const tc = c as ToolCallContent;
+  return tc.name ?? tc.toolName;
+}
+
+/** Bash execution message — not in the standard role union. */
+interface BashExecutionMessage {
+  role: "bashExecution";
+  command: string;
+  output?: string;
+}
+
+function isBashExecution(msg: { role: string }): msg is BashExecutionMessage {
+  return msg.role === "bashExecution";
+}
+```
+
+These are small, file-local types that document the shapes the code already handles at runtime.
+They make the duck-typing explicit and compile-time checked.
+
+#### 3. Narrow production interfaces (`MenuCtx`, `WidgetLike`)
+
+Already described in the test-side patterns below.
+These are production-code changes that make the test-side casts disappear.
+
+### Test-side patterns
+
+#### Pattern A: renderer.test.ts (29 casts → 0)
+
+The renderer already defines narrow interfaces (`RendererMessage`, `RendererTheme`, `RenderOptions`).
+The test casts because it doesn't use them — `stubTheme()` and `{ details: makeDetails() }` already satisfy the interfaces structurally.
+The return type `Text` has a `.text` property — `(result as any).text` can become `result!.text` (non-null assertion after `expect(result).toBeDefined()`).
+
+Fix: remove the casts; structural typing handles it.
+For result access, define a minimal `{ text: string }` type or use non-null assertion.
+
+#### Pattern B: context casts (14 casts → 0)
+
+- `agent-menu.test.ts` (8): define `MenuCtx` in production; type `makeCtx()` return.
+- `agent-manager.test.ts` (1): `mockCtx` is consumed by a mocked `buildParentSnapshot` — type as `unknown`.
+- `parent-snapshot.test.ts` (1): define a test-local interface matching the fields `buildParentSnapshot` reads.
+- `print-mode.test.ts` (2): type `makeHeadlessCtx()` return.
+- `runtime.test.ts` (1): pass a structurally valid `UICtx` (fixed by `WidgetLike` step).
+- `make-deps.test.ts` (3): type ctx args or use `unknown`.
+
+#### Pattern C: session casts (10 casts → ~1)
+
+Most are `{ session: {} as any, outputFile: ... }` for `record.execution`.
+Fix: expand `createMockSession()` to include the fields these tests need (`dispose`, `steer`, `getSessionStats`), then use it.
+One cast may remain for truly minimal session stubs.
+
+#### Pattern D: runtime/widget casts (9 casts → 0)
+
+Define `WidgetLike` in `runtime.ts`; change the `widget` field type.
+Use real `AgentActivityTracker` instances (constructor takes only `maxTurns?`).
+
+#### Pattern E: tool-execute ctx casts (5 casts → 0)
+
+Define a `STUB_CTX` constant in `test/helpers/` satisfying the tool execute's context parameter.
+
+#### Pattern F: RunOptions casts (3 casts → 0)
+
+Check whether `defaultMaxTurns` and `graceTurns` are on `RunOptions` — they are.
+The `as any` casts are vestigial; remove them.
+
+#### Pattern G: helpers.test.ts (7 casts → 0)
+
+Construct typed `TypeListRegistry` mocks.
+Fix `textResult` return type to avoid `details as any`.
+Use real `AgentActivityTracker` instances.
+
+#### Pattern H: conversation-viewer test casts (4 test casts → ~1)
+
+Type message mock objects using the local types from production change #2.
+Keep `(viewer as any).buildContentLines()` (private method access — the alternative of exposing the method is worse).
+
+#### Pattern I: other (6 casts → ~2)
+
+- `messages: [] as any[]` → type as `unknown[]`.
+- `(manager as any).cleanupInterval` → keep (private field assertion is intentional).
+- `usage.test.ts` (2) → type mock objects.
+
+## Module-Level Changes
+
+### Modified source files
+
+1. `src/agent-runner.ts`
+   - Import SDK types (`Model`, `ModelRegistry`, `SettingsManager`, `SessionManager`, `ResourceLoader`) as type-only imports.
+   - Widen `CreateSessionOptions` fields from `unknown` to SDK types.
+   - Change `RunnerIO.createSettingsManager` return type from `unknown` to `SettingsManager`.
+   - Define `getToolCallName()` helper and local `ToolCallContent` interface.
+   - Replace `(c as any).name ?? (c as any).toolName` with `getToolCallName(c)` in `getAgentConversation`.
+
+2. `src/ui/conversation-viewer.ts`
+   - Define local `ToolCallContent`, `BashExecutionMessage` interfaces and type guards.
+   - Replace `(c as any).name ?? (c as any).toolName` with typed helper.
+   - Replace `(msg as any).role === "bashExecution"` / `const bash = msg as any` with type guard.
+
+3. `src/ui/agent-menu.ts`
+   - Define and export `MenuCtx` interface.
+   - Change handler parameter type from `ExtensionContext` to `MenuCtx`.
+
+4. `src/runtime.ts`
+   - Define and export `WidgetLike` interface.
+   - Change `widget` field type from `AgentWidget | null` to `WidgetLike | null`.
+
+5. `src/tools/helpers.ts`
+   - Change `textResult` to avoid `details as any` — type the return properly.
+
+6. `src/index.ts`
+   - Remove `opts as any` casts in `createResourceLoader` and `createSession` factories (enabled by SDK-typed option interfaces).
+
+### Modified test files
+
+1. `test/renderer.test.ts` — remove all 29 casts.
+2. `test/runtime.test.ts` — use `WidgetLike` stubs and real `AgentActivityTracker`.
+3. `test/ui/agent-menu.test.ts` — type `makeCtx()` as `MenuCtx`.
+4. `test/tools/helpers.test.ts` — typed registry mocks, real `AgentActivityTracker`.
+5. `test/conversation-viewer.test.ts` — typed message mocks.
+6. `test/agent-runner.test.ts` — remove `as any` on RunOptions; type messages.
+7. `test/agent-runner-extension-tools.test.ts` — type messages.
+8. `test/agent-manager.test.ts` — type `mockCtx`.
+9. `test/print-mode.test.ts` — type `makeHeadlessCtx()`.
+10. `test/parent-snapshot.test.ts` — type mock context.
+11. `test/service-adapter.test.ts` — use `createMockSession()`.
+12. `test/tools/steer-tool.test.ts` — stub ctx, use `createMockSession()`.
+13. `test/tools/get-result-tool.test.ts` — stub ctx, use `createMockSession()`.
+14. `test/tools/foreground-runner.test.ts` — use `createMockSession()`.
+15. `test/tools/background-spawner.test.ts` — use `createMockSession()`.
+16. `test/tools/agent-tool.test.ts` — use `createMockSession()`.
+17. `test/helpers/make-deps.test.ts` — type ctx args.
+18. `test/usage.test.ts` — type mock objects.
+
+## Test Impact Analysis
+
+1. No new test coverage — this is a type-safety improvement on existing tests.
+2. No tests become redundant.
+3. All existing tests stay as-is in terms of assertions; only type annotations and mock construction change.
+4. `pnpm run check` is the primary validation — every step must pass type checking since the goal is eliminating type holes.
+5. Expanding `createMockSession()` affects multiple consumers — diff existing defaults before changing (per testing skill).
+
+## TDD Order
+
+Steps are ordered by independence and impact (production changes first, then largest cast-count test reductions).
+
+1. **Widen option interfaces to SDK types; remove index.ts casts (2 source casts → 0).**
+   Import SDK types as type-only in `agent-runner.ts`.
+   Widen `CreateSessionOptions` fields (`settingsManager`, `modelRegistry`, `model`, `resourceLoader`, `sessionManager`) to SDK types.
+   Change `RunnerIO.createSettingsManager` return type to `SettingsManager`.
+   Remove `as any` casts from `index.ts` factories.
+   Run `pnpm run check` + full suite.
+   Commit: `feat: use SDK types in CreateSessionOptions (#134)`
+
+2. **Add message-content type guards; remove viewer and runner source casts (6 source casts → 0).**
+   Define `ToolCallContent` interface and `getToolCallName()` helper in `conversation-viewer.ts`.
+   Define `BashExecutionMessage` interface and `isBashExecution()` guard in `conversation-viewer.ts`.
+   Replace all source `as any` casts in `conversation-viewer.ts`.
+   Define the same `getToolCallName()` helper (or extract a shared one) in `agent-runner.ts` and replace its cast.
+   Run `pnpm run check` + affected tests.
+   Commit: `fix: replace message-shape as-any casts with type guards (#134)`
+
+3. **Remove renderer test casts (29 → 0).**
+   Remove all `as any` casts on `stubTheme()`, message objects, and result access.
+   Use `result!.text` (non-null assertion after `toBeDefined()` guard) for result access.
+   Run `pnpm run check` + `pnpm vitest run test/renderer.test.ts`.
+   Commit: `test: remove as-any casts in renderer tests (#134)`
+
+4. **Add `MenuCtx` interface; remove menu-test casts (8 → 0).**
+   Define `MenuCtx` in `agent-menu.ts`.
+   Change handler parameter from `ExtensionContext` to `MenuCtx`.
+   Type `makeCtx()` return in test.
+   Run `pnpm run check` + `pnpm vitest run test/ui/agent-menu.test.ts`.
+   Commit: `feat: narrow menu handler to MenuCtx interface (#134)`
+
+5. **Add `WidgetLike`; remove runtime casts (9 → 0).**
+   Define `WidgetLike` in `runtime.ts`.
+   Change `widget` field type.
+   Update `runtime.test.ts`: typed stubs, real `AgentActivityTracker` instances.
+   Run `pnpm run check` + `pnpm vitest run test/runtime.test.ts`.
+   Commit: `feat: narrow runtime widget field to WidgetLike interface (#134)`
+
+6. **Expand `createMockSession`; remove session casts (10 → ~1).**
+   Add fields to `createMockSession()` that tool/service tests need.
+   Use it in tool tests, service-adapter, agent-manager for `record.execution.session`.
+   Run `pnpm run check` + full suite.
+   Commit: `test: use createMockSession for session execution casts (#134)`
+
+7. **Remove helpers.test.ts casts (7 → 0).**
+   Typed `TypeListRegistry` mocks.
+   Fix `textResult` return type in `src/tools/helpers.ts`.
+   Real `AgentActivityTracker` instances.
+   Run `pnpm run check` + `pnpm vitest run test/tools/helpers.test.ts`.
+   Commit: `test: remove as-any casts in helpers tests (#134)`
+
+8. **Remove context casts across remaining test files (6 → 0).**
+   Type `mockCtx` in `agent-manager.test.ts`.
+   Type `makeHeadlessCtx()` in `print-mode.test.ts`.
+   Type mock context in `parent-snapshot.test.ts`.
+   Type `{} as any` in `make-deps.test.ts`.
+   Run `pnpm run check` + full suite.
+   Commit: `test: remove remaining context as-any casts (#134)`
+
+9. **Remove RunOptions and message-array casts (5 → 0).**
+   Remove vestigial `as any` on RunOptions objects.
+   Type `messages` arrays as `unknown[]`.
+   Run `pnpm run check` + affected tests.
+   Commit: `test: remove RunOptions and message-array casts (#134)`
+
+10. **Remove tool-execute ctx casts (5 → 0).**
+    Define `STUB_CTX` in `test/helpers/`.
+    Use it in `steer-tool.test.ts`, `get-result-tool.test.ts`, `make-deps.test.ts`.
+    Run `pnpm run check` + affected tests.
+    Commit: `test: remove tool-execute context casts (#134)`
+
+11. **Clean up conversation-viewer test and usage casts (6 → ~2).**
+    Type message mocks in `conversation-viewer.test.ts`.
+    Type usage mock objects in `usage.test.ts`.
+    Keep `(viewer as any).buildContentLines()` and `(manager as any).cleanupInterval` (private access, intentional).
+    Run `pnpm run check` + full suite.
+    Commit: `test: remove conversation-viewer and usage as-any casts (#134)`
+
+## Risks and Mitigations
+
+| Risk                                                                                            | Mitigation                                                                                                                                                                       |
+| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Widening `CreateSessionOptions` to SDK types re-couples `agent-runner.ts` to SDK                | These are type-only imports — no runtime coupling. Tests still mock at the `RunnerIO` function level. The `RunnerIO` interface is the decoupling boundary, not the option types. |
+| Narrowing `widget` to `WidgetLike` could break callers accessing `AgentWidget`-specific methods | Grep all `runtime.widget` access sites first; verify they only use `update()`, `markFinished()`, `setUICtx()`.                                                                   |
+| Narrowing menu handler to `MenuCtx` could break callers passing `ExtensionContext`              | `ExtensionContext` is structurally a superset of `MenuCtx` — callers pass it unchanged.                                                                                          |
+| Expanding `createMockSession()` could break consumers with different default expectations       | Diff existing consumers' default expectations before adding fields (per testing skill).                                                                                          |
+| Message type guards add code to conversation-viewer and agent-runner                            | Each guard is 2–4 lines; they replace unsafe `as any` access with documented, compile-checked types. Net code stays similar.                                                     |
+| 11-step plan is large                                                                           | Each step is independently committable. No step depends on a subsequent one. Steps can be reordered or skipped.                                                                  |
+
+## Open Questions
+
+- Should `getToolCallName()` be shared between `conversation-viewer.ts` and `agent-runner.ts`, or duplicated?
+  Both files handle the same SDK message shape.
+  A shared helper in a common module (e.g., `context.ts` which already has `extractText`) avoids duplication.
+  Alternatively, the duplication is cheap (3 lines) and the two files have different concerns.
+- Should `STUB_CTX` live in `test/helpers/stub-ctx.ts` or inline?
+  Centralize — 3+ tool tests share the pattern.
+- Estimated final count: 2–3 remaining casts (`(viewer as any).buildContentLines()`, `(manager as any).cleanupInterval`, possibly 1 more for an unexported SDK type).

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.