@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0195-convert-tool-factories-to-classes.md

@@ -1,264 +0,0 @@
----
-issue: 195
-issue_title: "Convert tool factories to classes"
----
-
-# Convert tool factories to classes
-
-## Problem Statement
-
-`createAgentTool`, `createGetResultTool`, and `createSteerTool` are closure factories that capture dependencies and return tool definitions.
-This pattern hides dependencies in closures, forces `index.ts` to build narrow adapter objects at each call site, and prevents direct structural typing between real objects and tool interfaces.
-With #193 (runtime owns queries) and #194 (interfaces aligned) both complete, the conversions are mechanical.
-
-## Goals
-
-- Convert all three tool factories to classes with constructor-injected dependencies.
-- Each class exposes a `toToolDefinition()` method that wraps the tool with `defineTool()`.
-- `index.ts` passes real objects directly — no adapter closures for tool wiring.
-- Eliminate 16+ adapter closures from `index.ts`.
-
-## Non-Goals
-
-- Converting `createAgentRunner` or `createAgentsMenuHandler` — those belong to #196.
-- Simplifying `index.ts` beyond tool wiring — that's #196 Layer 4.
-- Changing tool behavior or parameters — this is a purely structural refactoring.
-
-## Background
-
-### Dependencies (both closed)
-
-- Issue #193 moved context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) onto `SubagentRuntime`.
-- Issue #194 aligned tool interfaces so `AgentManager` and `SubagentRuntime` structurally satisfy the narrow tool interfaces without adapters.
-
-### Existing module layout
-
-The three factory functions live in:
-
-- `src/tools/agent-tool.ts` — `createAgentTool(deps: AgentToolDeps)`
-- `src/tools/get-result-tool.ts` — `createGetResultTool(getRecord, cancelNudge, getConversation, registry)`
-- `src/tools/steer-tool.ts` — `createSteerTool(getRecord, emitEvent, steerAgent, queueSteer)`
-
-Each returns a plain object with `name`, `label`, `description`, `parameters`, `execute`, and optional render methods.
-`index.ts` wraps each in `defineTool()` at registration time.
-
-### Architecture doc reference
-
-Phase 11, Layer 3 in `docs/architecture/architecture.md` (lines 689–709).
-
-## Design Overview
-
-### Class structure
-
-Each class stores constructor-injected dependencies as instance fields and exposes:
-
-1. A `toToolDefinition()` method that calls `defineTool(this.buildToolSpec())` (or similar) — returning the Pi SDK tool registration object.
-2. Private methods that correspond to the existing function body sections.
-
-### Constructor signatures
-
-| Class           | Constructor params                                                                                                                         |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| `AgentTool`     | `manager: AgentToolManager`, `runtime: AgentToolRuntime`, `settings: AgentToolSettings`, `registry: AgentTypeRegistry`, `agentDir: string` |
-| `GetResultTool` | `manager: GetResultToolManager`, `notifications: GetResultToolNotifications`, `registry: AgentConfigLookup`                                |
-| `SteerTool`     | `manager: SteerToolManager`, `events: SteerToolEvents`                                                                                     |
-
-### Narrow interfaces
-
-Each class defines its own narrow interface for the collaborators it uses.
-These already exist (e.g., `AgentToolManager`, `BackgroundManagerDeps`) — they stay as-is; the class uses them directly.
-
-#### `AgentTool`
-
-The existing `AgentToolDeps` interface (8 fields) collapses into 5 constructor params.
-The `widget`, `agentActivity`, `buildSnapshot`, `getModelInfo`, and `getSessionInfo` fields merge into a single `runtime` param because `SubagentRuntime` structurally satisfies all of them after #193/#194.
-
-New narrow interface for the runtime slice:
-
-```typescript
-export interface AgentToolRuntime {
-  readonly agentActivity: AgentActivityAccess;
-  setUICtx(ctx: UICtx): void;
-  ensureTimer(): void;
-  update(): void;
-  markFinished(id: string): void;
-  buildSnapshot(inheritContext: boolean): ParentSnapshot;
-  getModelInfo(): ModelInfo;
-  getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
-}
-```
-
-`SubagentRuntime` satisfies this structurally — no adapter needed in `index.ts`.
-
-#### `GetResultTool`
-
-New narrow interfaces:
-
-```typescript
-export interface GetResultToolManager {
-  getRecord(id: string): AgentRecord | undefined;
-}
-
-export interface GetResultToolNotifications {
-  cancelNudge(key: string): void;
-}
-```
-
-`getAgentConversation` is a pure function — imported directly by the class, not injected.
-
-#### `SteerTool`
-
-New narrow interfaces:
-
-```typescript
-export interface SteerToolManager {
-  getRecord(id: string): AgentRecord | undefined;
-  queueSteer(id: string, message: string): boolean;
-}
-
-export interface SteerToolEvents {
-  emit(name: string, data: unknown): void;
-}
-```
-
-`steerAgent` is a pure function — imported directly by the class, not injected.
-
-### Call site after conversion
-
-```typescript
-const agentTool = new AgentTool(manager, runtime, settings, registry, getAgentDir());
-const getResultTool = new GetResultTool(manager, notifications, registry);
-const steerTool = new SteerTool(manager, pi.events);
-pi.registerTool(agentTool.toToolDefinition());
-pi.registerTool(getResultTool.toToolDefinition());
-pi.registerTool(steerTool.toToolDefinition());
-```
-
-### Design decisions
-
-1. **`toToolDefinition()` on each class** — encapsulates the `defineTool()` call so `index.ts` doesn't import `defineTool` for each tool.
-2. **Pure functions imported directly** — `steerAgent` and `getAgentConversation` are pure utilities with no state; injecting them adds indirection without testability benefit.
-3. **`agentDir` stays a constructor param** — it's a static string computed once at startup; putting it on the registry would add scope responsibility the registry doesn't need.
-4. **Keep existing `AgentToolDeps` temporarily** — remove it in the same PR once the class replaces all usage.
-
-## Module-Level Changes
-
-### `src/tools/agent-tool.ts`
-
-- Add `AgentToolRuntime` interface (narrow runtime slice).
-- Add `AgentToolSettings` type alias (existing inline type, extracted for clarity).
-- Add `AgentTool` class with constructor storing `manager`, `runtime`, `settings`, `registry`, `agentDir`.
-- Move the existing factory body into class methods: `toToolDefinition()`, private `execute()`.
-- Remove `createAgentTool` function and `AgentToolDeps` interface.
-- Keep `AgentToolManager`, `AgentToolWidget`, `AgentActivityAccess` interfaces (still used by `background-spawner` and `foreground-runner` — though `AgentToolWidget` may be replaceable by `AgentToolRuntime`).
-
-### `src/tools/get-result-tool.ts`
-
-- Add `GetResultToolManager` and `GetResultToolNotifications` interfaces.
-- Add `GetResultTool` class with constructor.
-- Import `getAgentConversation` directly.
-- Move factory body into class method.
-- Remove `createGetResultTool` function.
-
-### `src/tools/steer-tool.ts`
-
-- Add `SteerToolManager` and `SteerToolEvents` interfaces.
-- Add `SteerTool` class with constructor.
-- Import `steerAgent` directly.
-- Move factory body into class method.
-- Remove `createSteerTool` function.
-
-### `src/tools/background-spawner.ts`
-
-- Update `BackgroundWidgetDeps` to reference `AgentToolRuntime` instead (or keep as-is since `AgentToolRuntime` is a superset).
-  Actually no change needed — `spawnBackground` already accepts narrow interfaces; the `AgentTool` class passes `this.runtime` which satisfies `BackgroundWidgetDeps` structurally.
-
-### `src/tools/foreground-runner.ts`
-
-- Same as above — no change needed.
-  The `AgentTool` class passes `this.runtime` which satisfies `ForegroundWidgetDeps` structurally.
-
-### `src/index.ts`
-
-- Remove adapter closures for all three tool registrations.
-- Replace with class construction + `toToolDefinition()` calls.
-- Remove `defineTool` import (moves into tool classes).
-- Remove unused imports that were only needed for adapter closures.
-
-### `test/tools/agent-tool.test.ts`
-
-- Replace `createToolDeps()` with class construction in test helpers.
-- Update `execute()` helper to instantiate `AgentTool` and call its execute.
-- Keep all existing test cases — behavior is unchanged.
-
-### `test/tools/get-result-tool.test.ts`
-
-- Replace positional args with class construction.
-- Update `makeDeps` and `execute` helpers.
-- Keep all existing test cases.
-
-### `test/tools/steer-tool.test.ts`
-
-- Replace positional args with class construction.
-- Update `makeDeps` and `execute` helpers.
-- Keep all existing test cases.
-
-### `test/helpers/make-deps.ts`
-
-- Update `createToolDeps` to construct `AgentTool`-compatible deps (or remove if no longer needed).
-  Likely transforms into a factory that builds mock `AgentToolRuntime`, `AgentToolManager`, etc.
-
-### `docs/architecture/architecture.md`
-
-- Update the Layer 3 table to mark #195 as done.
-- Update the file listing for `src/tools/` to reflect class names (if the listing is that detailed).
-
-## Test Impact Analysis
-
-1. **No new test surfaces** — this is a structural refactoring with identical behavior.
-   Existing tests already cover all tool paths.
-2. **Test helper changes** — `createToolDeps()` and per-tool `makeDeps()` functions need updating to use class construction instead of function calls, but the mock shapes remain the same.
-3. **All existing tests stay** — they exercise the tool execution logic which doesn't change.
-
-## TDD Order
-
-1. **Convert `SteerTool` to class** — smallest tool (fewest deps, no render methods).
-   - Update `steer-tool.ts`: add interfaces, add class, remove factory.
-   - Update `test/tools/steer-tool.test.ts`: use class construction.
-   - Verify: `pnpm vitest run test/tools/steer-tool.test.ts`
-   - Commit: `refactor: convert createSteerTool to SteerTool class (#195)`
-
-2. **Convert `GetResultTool` to class** — medium complexity (3 deps, no render methods).
-   - Update `get-result-tool.ts`: add interfaces, add class, import `getAgentConversation`, remove factory.
-   - Update `test/tools/get-result-tool.test.ts`: use class construction.
-   - Verify: `pnpm vitest run test/tools/get-result-tool.test.ts`
-   - Commit: `refactor: convert createGetResultTool to GetResultTool class (#195)`
-
-3. **Convert `AgentTool` to class** — largest (5 deps, render methods, delegates to spawner/runner).
-   - Add `AgentToolRuntime` and `AgentToolSettings` interfaces.
-   - Add `AgentTool` class.
-   - Remove `createAgentTool` and `AgentToolDeps`.
-   - Update `test/tools/agent-tool.test.ts` and `test/helpers/make-deps.ts`.
-   - Verify: `pnpm vitest run test/tools/agent-tool.test.ts`
-   - Commit: `refactor: convert createAgentTool to AgentTool class (#195)`
-
-4. **Update `index.ts`** — wire class constructors, remove adapter closures and `defineTool` import.
-   - Verify: `pnpm vitest run` (full suite) + `pnpm run check` (type-check).
-   - Commit: `refactor: wire tool classes in index.ts, remove adapter closures (#195)`
-
-5. **Update architecture doc** — mark Layer 3 (partial) as complete.
-   - Commit: `docs: mark #195 complete in architecture roadmap`
-
-## Risks and Mitigations
-
-| Risk                                                                                                      | Mitigation                                                                                    |
-| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `background-spawner` and `foreground-runner` accept narrow interfaces that differ from `AgentToolRuntime` | `AgentToolRuntime` is a superset — pass `this.runtime` and structural typing handles it.      |
-| Test factories import `AgentToolDeps` which will be removed                                               | Step 3 updates all test imports in the same commit.                                           |
-| `defineTool` import removed from `index.ts` — must live somewhere                                         | Each class's `toToolDefinition()` imports it internally.                                      |
-| Spreading class instances in tests breaks method access                                                   | Tests will construct the class, not spread it. Step 3 uses lift-and-shift for `make-deps.ts`. |
-
-## Open Questions
-
-- Should `AgentToolWidget` interface be removed entirely (replaced by `AgentToolRuntime`)?
-  Defer to implementation — if `background-spawner` and `foreground-runner` can accept `AgentToolRuntime` directly, remove it; otherwise keep the narrow subset interfaces.

package/docs/plans/0196-convert-runner-menu-to-classes.md

@@ -1,268 +0,0 @@
----
-issue: 196
-issue_title: "Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts"
----
-
-# Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts
-
-## Problem Statement
-
-Two remaining closure factories in pi-subagents mask class-shaped code:
-
-1. `createAgentRunner(runnerIO)` captures `RunnerIO` and returns `{ run, resume }` — the `AgentRunner` interface already exists but lacks a concrete class implementation.
-2. `createAgentsMenuHandler({...})` captures an 8-field deps object and returns a handler function.
-
-With #195 (tool factory → class conversions) complete, these are the last two closure factories.
-After converting them, `index.ts` can be simplified: adapter closures drop, fan-out decreases, and the composition root becomes pure object construction.
-
-## Goals
-
-- Convert `createAgentRunner` factory to a concrete `ConcreteAgentRunner` class implementing `AgentRunner`.
-- Convert `createAgentsMenuHandler` factory to an `AgentsMenuHandler` class.
-- Internalize the `getModelLabel` closure from `index.ts` into `AgentsMenuHandler` (it uses `resolveModel` and `getModelLabelFromConfig`, both pure functions the class can import directly).
-- Pass `AgentManager` directly as the `manager` param (it structurally satisfies `AgentMenuManager`), eliminating 3 adapter closures.
-- Simplify `index.ts` by removing eliminated adapter closures and unused imports.
-- Update architecture doc to mark Layer 3 and Layer 4 as done.
-
-## Non-Goals
-
-- Changing `runAgent()` or `resumeAgent()` function signatures — they remain as free functions called by the class.
-- Removing the `AgentRunner` interface — it stays as the contract for `AgentManager`.
-- Removing `RunnerIO` type — it stays as the IO boundary for `runAgent()`.
-- Changing the `AgentMenuManager` interface — it stays as the narrow contract; `AgentManager` satisfies it structurally.
-- Removing `AgentMenuDeps` — it is replaced by the class constructor; the type itself is removed.
-- Refactoring `NotificationManager`, `SettingsManager`, or `SessionLifecycleHandler` — those are already class-shaped.
-- Phase 12 work (decompose `renderWidgetLines`, consolidate test duplication).
-
-## Background
-
-### Phase 11 layer structure
-
-Phase 11 in `docs/architecture/architecture.md` converts closure factories to classes in four layers:
-
-- Layer 0: `SessionContext` interface (#192) ✓
-- Layer 1: Runtime owns context queries (#193) ✓
-- Layer 2: Align interfaces for structural typing (#194) ✓
-- Layer 3: Convert closure factories to classes (#195 tools ✓, #196 runner + menu)
-- Layer 4: Simplify `index.ts` (#196)
-
-Issue #196 completes Layer 3 (runner + menu) and Layer 4 (index.ts simplification).
-
-### Current state
-
-`createAgentRunner` (3 lines) wraps `runAgent`/`resumeAgent` in an object literal:
-
-```typescript
-export function createAgentRunner(io: RunnerIO): AgentRunner {
-  return {
-    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
-    resume: resumeAgent,
-  };
-}
-```
-
-`createAgentsMenuHandler` (200+ lines) captures 8 deps and returns a handler function.
-The deps bag includes `getModelLabel` (a closure built in `index.ts`) and `agentActivity` (a `Map` from runtime).
-
-`index.ts` currently has ~23 arrow closures and 27 imports at 229 lines.
-
-### Structural typing confirmation
-
-`AgentManager` already has `listAgents()`, `getRecord()`, and `spawnAndWait()` methods that structurally satisfy `AgentMenuManager`.
-The `spawnAndWait` parameter type (`Omit<AgentSpawnConfig, "isBackground">`) is a superset of the menu's `{ description, maxTurns }`, so structural typing matches.
-
-## Design Overview
-
-### ConcreteAgentRunner
-
-A minimal class that implements `AgentRunner` by delegating to the free functions:
-
-```typescript
-export class ConcreteAgentRunner implements AgentRunner {
-  constructor(private readonly io: RunnerIO) {}
-
-  async run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
-    return runAgent(snapshot, type, prompt, options, this.io);
-  }
-
-  async resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
-    return resumeAgent(session, prompt, options);
-  }
-}
-```
-
-The factory function `createAgentRunner` is removed.
-The free functions `runAgent`, `resumeAgent`, `getAgentConversation`, and `normalizeMaxTurns` remain exported — they are used directly by tests and other modules.
-
-### AgentsMenuHandler
-
-The class replaces `createAgentsMenuHandler` and `AgentMenuDeps`.
-Constructor params are the subset of deps that are true collaborators:
-
-```typescript
-export class AgentsMenuHandler {
-  constructor(
-    private readonly manager: AgentMenuManager,
-    private readonly registry: AgentTypeRegistry,
-    private readonly agentActivity: AgentActivityReader,
-    private readonly settings: AgentMenuSettings,
-    private readonly fileOps: AgentFileOps,
-    private readonly personalAgentsDir: string,
-    private readonly projectAgentsDir: string,
-  ) {}
-
-  async handle(ctx: { ui: MenuUI; modelRegistry: ModelRegistry; parentSnapshot: ParentSnapshot }): Promise<void> { ... }
-}
-```
-
-Key design decisions:
-
-1. **`agentActivity` stays as a constructor param** — it is a collaborator used in `viewAgentConversation`.
-   The issue's proposed signature omits it, but the class needs it at runtime.
-2. **`getModelLabel` is internalized** — the class imports `resolveModel` and `getModelLabelFromConfig` directly and computes the label in a private method.
-   This eliminates the closure from `index.ts` and removes the `getModelLabel` field from the deps interface.
-3. **`AgentMenuDeps` is removed** — the class constructor replaces it.
-4. **The `handle` method** replaces the returned function.
-   The inner helpers (`showAgentsMenu`, `showAllAgentsList`, etc.) become private methods.
-
-### index.ts simplification
-
-After both conversions:
-
-```typescript
-// Before (adapter closures):
-const agentsMenuHandler = createAgentsMenuHandler({
-  manager: {
-    listAgents: () => manager.listAgents(),
-    getRecord: (id) => manager.getRecord(id),
-    spawnAndWait: (...) => manager.spawnAndWait(...),
-  },
-  registry,
-  agentActivity: runtime.agentActivity,
-  getModelLabel: (type, modelRegistry) => { ... },  // 7-line closure
-  settings,
-  fileOps: new FsAgentFileOps(),
-  personalAgentsDir: join(getAgentDir(), 'agents'),
-  projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
-});
-
-// After:
-const agentsMenu = new AgentsMenuHandler(
-  manager, registry, runtime.agentActivity,
-  settings, new FsAgentFileOps(),
-  join(getAgentDir(), 'agents'),
-  join(process.cwd(), '.pi', 'agents'),
-);
-```
-
-Eliminated closures: 4 (3 manager method adapters + 1 getModelLabel closure).
-Eliminated imports: `getModelLabelFromConfig`, `resolveModel` (from index.ts), `createAgentRunner`, `type RunnerIO`, `createAgentsMenuHandler`.
-
-Remaining adapter closures in `index.ts` (~15) are necessary: event handler registrations, SDK factory callbacks, `pi.sendMessage`/`pi.exec` adapters.
-These are structural — they bridge the Pi SDK's callback-based API to the extension's object-oriented internals.
-
-## Module-Level Changes
-
-### `src/lifecycle/agent-runner.ts`
-
-- Add `ConcreteAgentRunner` class implementing `AgentRunner`.
-- Remove `createAgentRunner` factory function.
-- Keep all free functions (`runAgent`, `resumeAgent`, `getAgentConversation`, `normalizeMaxTurns`) and all types exported.
-
-### `src/ui/agent-menu.ts`
-
-- Replace `createAgentsMenuHandler` factory with `AgentsMenuHandler` class.
-- Remove `AgentMenuDeps` interface.
-- Add private `getModelLabel` method (internalizes the closure from `index.ts`).
-- Convert inner functions (`showAgentsMenu`, `showAllAgentsList`, `showRunningAgents`, `viewAgentConversation`, `showSettings`) to private methods.
-- Add imports: `resolveModel` from `#src/session/model-resolver`, `getModelLabelFromConfig` from `#src/tools/helpers`.
-- Keep exported interfaces: `AgentMenuManager`, `AgentMenuSettings`, `AgentActivityReader`, `MenuUI`.
-
-### `src/index.ts`
-
-- Replace `createAgentRunner(runnerIO)` with `new ConcreteAgentRunner(runnerIO)`.
-- Replace `createAgentsMenuHandler({...})` with `new AgentsMenuHandler(...)`.
-- Replace `agentsMenuHandler({...})` with `agentsMenu.handle({...})`.
-- Remove adapter closures for `manager.listAgents`, `manager.getRecord`, `manager.spawnAndWait`, and `getModelLabel`.
-- Remove unused imports: `createAgentRunner`, `type RunnerIO` → `ConcreteAgentRunner`; `createAgentsMenuHandler` → `AgentsMenuHandler`; `getModelLabelFromConfig`, `resolveModel`.
-- Net effect: ~15 lines removed, 5 imports removed.
-
-### `docs/architecture/architecture.md`
-
-- Mark Layer 3 remaining items (runner, menu) as done.
-- Mark Layer 4 as done.
-- Update the factory→class table entries for `createAgentRunner` and `createAgentsMenuHandler` with ✓.
-
-## Test Impact Analysis
-
-### `test/lifecycle/agent-runner.test.ts` (and siblings)
-
-No changes needed.
-Tests call `runAgent()` and `resumeAgent()` directly — they never use `createAgentRunner`.
-The `ConcreteAgentRunner` class is a trivial two-method delegation wrapper tested implicitly through `index.ts` integration and explicitly through one new unit test.
-
-### `test/ui/agent-menu.test.ts`
-
-Tests need updating:
-
-1. Replace `createAgentsMenuHandler(makeDeps())` with `new AgentsMenuHandler(...)`.
-2. Replace `handler(params)` with `handler.handle(params)`.
-3. Remove `getModelLabel` from `makeDeps()` — it is now an internal method.
-4. Remove `AgentMenuDeps` import; update `makeDeps` to construct positional args or a helper that returns a handler directly.
-
-No test logic changes — only call-site updates for the new API shape.
-
-### New tests
-
-One new unit test for `ConcreteAgentRunner`: verify it delegates `run` and `resume` to the underlying functions.
-
-## TDD Order
-
-1. **Add `ConcreteAgentRunner` class alongside factory.**
-   Add the class to `agent-runner.ts`, keep `createAgentRunner` temporarily.
-   Add a unit test verifying delegation.
-   `test: add ConcreteAgentRunner delegation test`
-
-2. **Switch `index.ts` to `ConcreteAgentRunner`, remove factory.**
-   Replace `createAgentRunner(runnerIO)` with `new ConcreteAgentRunner(runnerIO)`.
-   Remove the `createAgentRunner` factory function.
-   Update imports.
-   `refactor: replace createAgentRunner with ConcreteAgentRunner class`
-
-3. **Convert `createAgentsMenuHandler` to `AgentsMenuHandler` class.**
-   Replace factory function with class.
-   Move inner functions to private methods.
-   Internalize `getModelLabel` as a private method.
-   Remove `AgentMenuDeps` interface.
-   `refactor: convert createAgentsMenuHandler to AgentsMenuHandler class`
-
-4. **Update `agent-menu.test.ts` for class API.**
-   Replace `createAgentsMenuHandler(makeDeps())` with class construction.
-   Replace `handler(params)` with `handler.handle(params)`.
-   Remove `getModelLabel` from test deps.
-   All existing tests pass with updated call sites.
-   `test: update agent-menu tests for AgentsMenuHandler class`
-
-5. **Simplify `index.ts` wiring.**
-   Replace `createAgentsMenuHandler({...})` with `new AgentsMenuHandler(...)`.
-   Pass `manager` directly (structural typing).
-   Remove adapter closures and unused imports.
-   `refactor: simplify index.ts wiring for AgentsMenuHandler`
-
-6. **Update architecture doc.**
-   Mark Layer 3 remaining items and Layer 4 as done in `docs/architecture/architecture.md`.
-   `docs: mark Phase 11 Layer 3 and Layer 4 complete`
-
-## Risks and Mitigations
-
-| Risk                                                             | Mitigation                                                                                                                     |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| `AgentManager` might not structurally satisfy `AgentMenuManager` | Confirmed: `listAgents()`, `getRecord()`, `spawnAndWait()` signatures are compatible. `pnpm run check` in step 5 verifies.     |
-| Internalized `getModelLabel` might diverge from the closure      | The private method uses the same `resolveModel` and `getModelLabelFromConfig` imports — identical logic, just moved.           |
-| Tests that use `AgentMenuDeps` type break when removed           | Step 4 updates all test call sites before step 5 changes production code. The test file is 215 lines — manageable in one step. |
-| `agentActivity` missing from constructor                         | Included in the class constructor (diverging from the issue's proposed signature which omits it).                              |
-
-## Open Questions
-
-None — the issue's proposed design is clear and the implementation is mechanical.
-The one deviation (keeping `agentActivity` as a constructor param) is necessary and minimal.

package/docs/plans/0205-decompose-render-widget-lines.md

@@ -1,140 +0,0 @@
----
-issue: 205
-issue_title: "Decompose renderWidgetLines (cognitive 44)"
----
-
-# Decompose `renderWidgetLines`
-
-## Problem Statement
-
-`renderWidgetLines` in `ui/widget-renderer.ts` has cognitive complexity 44 (CRITICAL per fallow health).
-It handles agent categorization, per-status line building with tree connectors, non-overflow assembly with last-connector fixup, and overflow-budget assembly — all in a single 106-line function.
-This is the highest-complexity function remaining in the codebase (Phase 12, Step 1).
-
-## Goals
-
-- Extract distinct concerns into separate pure functions, each with cognitive complexity < 10.
-- Preserve all existing behavior — no visual or behavioral changes.
-- Keep all extracted functions in `widget-renderer.ts` (they are private helpers, not a separate module).
-
-## Non-Goals
-
-- Decomposing `showAgentDetail` (#206), `update` (#207), or shared test fixtures (#208) — those are sibling Phase 12 steps.
-- Changing the widget's visual output or tree-connector style.
-- Modifying `renderFinishedLine` or `renderRunningLines` — those are already single-concern functions.
-
-## Background
-
-`widget-renderer.ts` was extracted from `AgentWidget` in #148.
-The per-agent renderers (`renderFinishedLine`, `renderRunningLines`) are already clean single-concern functions.
-The remaining complexity lives entirely in `renderWidgetLines`, which orchestrates categorization, section building, and assembly.
-
-The function has five interwoven concerns:
-
-1. **Agent categorization** — filtering into running/queued/finished buckets.
-2. **Section building** — rendering each bucket into pre-formatted line arrays with `├─` tree connectors.
-3. **Heading construction** — choosing icon/color based on active vs. finished-only.
-4. **Non-overflow assembly** — concatenating sections when under `MAX_WIDGET_LINES`, then fixing the last connector (`├─` → `└─`).
-5. **Overflow assembly** — budget-based prioritized assembly (running > queued > finished) with an overflow indicator line.
-
-## Design Overview
-
-Extract four helper functions from the body of `renderWidgetLines`:
-
-### `categorizeAgents`
-
-Accepts the agents array and `shouldShowFinished` callback.
-Returns `{ running, queued, finished }` arrays.
-Pure filter — no rendering.
-
-### `buildSections`
-
-Accepts categorized agents, `activityMap`, `registry`, `spinnerFrame`, `theme`, and a `truncate` function.
-Returns `{ finishedLines, runningLines, queuedLine }` — the pre-formatted line arrays with `├─` connectors.
-Calls `renderFinishedLine` and `renderRunningLines` internally.
-
-### `assembleWithinBudget`
-
-Accepts `finishedLines`, `runningLines`, `queuedLine`, and the heading line.
-Handles the non-overflow path: concatenates sections and fixes the last tree connector (`├─` → `└─`, `│` → space).
-Returns the assembled `string[]`.
-
-### `assembleOverflow`
-
-Accepts `finishedLines`, `runningLines`, `queuedLine`, heading line, `maxBody` budget, `truncate`, and `theme`.
-Handles the overflow path: budget-based prioritized assembly with an overflow indicator.
-Returns the assembled `string[]`.
-
-After extraction, `renderWidgetLines` becomes a thin orchestrator:
-
-```typescript
-export function renderWidgetLines(params: { ... }): string[] {
-  const { running, queued, finished } = categorizeAgents(agents, shouldShowFinished);
-  if (running.length === 0 && queued.length === 0 && finished.length === 0) return [];
-
-  const truncate = (line: string) => truncateToWidth(line, terminalWidth);
-  const heading = buildHeadingLine(running, queued, truncate, theme);
-  const sections = buildSections(running, queued, finished, activityMap, registry, spinnerFrame, theme, truncate);
-  const totalBody = sections.finishedLines.length + sections.runningLines.length * 2 + (sections.queuedLine ? 1 : 0);
-
-  if (totalBody <= MAX_WIDGET_LINES - 1) {
-    return assembleWithinBudget(heading, sections);
-  }
-  return assembleOverflow(heading, sections, MAX_WIDGET_LINES - 1, truncate, theme);
-}
-```
-
-Each helper is a pure function with a single concern and low branching.
-
-## Module-Level Changes
-
-### Changed: `src/ui/widget-renderer.ts`
-
-- Add `categorizeAgents` (private) — extracts the three `agents.filter(...)` calls.
-- Add `buildSections` (private) — extracts the three section-building loops.
-- Add `assembleWithinBudget` (private) — extracts the non-overflow assembly + connector fixup.
-- Add `assembleOverflow` (private) — extracts the overflow-budget assembly + indicator line.
-- Simplify `renderWidgetLines` to a thin orchestrator calling the four helpers.
-
-No exports are added, removed, or renamed.
-No other files change.
-
-## Test Impact Analysis
-
-1. No new unit tests for the extracted helpers are needed — they are private functions tested through `renderWidgetLines`.
-   The existing `renderWidgetLines` tests in `test/widget-renderer.test.ts` (8 tests) cover all branches: single running, mixed agents, filtered finished, overflow priority, empty arrays, dim heading.
-2. No existing tests become redundant — they all exercise `renderWidgetLines` end-to-end, which is the correct level for assembly logic.
-3. All existing tests must stay as-is — the extraction is purely internal.
-
-## TDD Order
-
-1. **Red → Green:** Extract `categorizeAgents` and call it from `renderWidgetLines`.
-   All existing tests pass (no behavior change).
-   Commit: `refactor: extract categorizeAgents from renderWidgetLines`
-
-2. **Red → Green:** Extract `buildSections` and call it from `renderWidgetLines`.
-   All existing tests pass.
-   Commit: `refactor: extract buildSections from renderWidgetLines`
-
-3. **Red → Green:** Extract `assembleWithinBudget` and call it from `renderWidgetLines`.
-   All existing tests pass.
-   Commit: `refactor: extract assembleWithinBudget from renderWidgetLines`
-
-4. **Red → Green:** Extract `assembleOverflow` and call it from `renderWidgetLines`.
-   All existing tests pass.
-   Commit: `refactor: extract assembleOverflow from renderWidgetLines`
-
-5. **Verify:** Run `pnpm run check` and `pnpm vitest run test/widget-renderer.test.ts` to confirm no regressions.
-   Commit: n/a (verification only).
-
-## Risks and Mitigations
-
-| Risk                                                                        | Mitigation                                                                                                                             |
-| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
-| Tree-connector fixup logic is fragile (string replacement on Unicode chars) | Keep the fixup in `assembleWithinBudget` as-is — same logic, just relocated. Existing tests verify exact connector output.             |
-| Extracted helpers have many parameters                                      | Accept a `sections` object from `buildSections` to bundle `finishedLines`, `runningLines`, `queuedLine` — avoids long parameter lists. |
-| Intermediate commits break tests                                            | Each extraction step is self-contained — the function body moves into a helper and the call site replaces it in the same commit.       |
-
-## Open Questions
-
-None — the decomposition is purely mechanical extraction of existing code into named helpers.