@gotgenes/pi-subagents 7.2.4 → 7.2.6

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

@@ -0,0 +1,140 @@
+---
+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.

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

@@ -0,0 +1,73 @@
+---
+issue: 196
+issue_title: "Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts"
+---
+
+# Retro: #196 — Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts
+
+## Stage: Planning (2026-05-25T14:35:46Z)
+
+### Session summary
+
+Produced a 6-step TDD plan covering the final two closure-factory-to-class conversions (`createAgentRunner` → `ConcreteAgentRunner`, `createAgentsMenuHandler` → `AgentsMenuHandler`) and the subsequent `index.ts` simplification.
+Confirmed that `AgentManager` structurally satisfies `AgentMenuManager`, enabling direct pass-through without adapter closures.
+
+### Observations
+
+- The issue's proposed `AgentsMenuHandler` constructor omits `agentActivity`, but the class needs it for `viewAgentConversation`.
+  Plan includes it as a constructor param — minimal deviation from the issue.
+- `getModelLabel` can be internalized into `AgentsMenuHandler` since it only uses two pure imported functions (`resolveModel`, `getModelLabelFromConfig`) plus the registry (already a constructor param).
+  This eliminates a 7-line closure from `index.ts`.
+- Tests for `agent-runner` call `runAgent`/`resumeAgent` directly — no test uses `createAgentRunner`, so the runner conversion has zero test impact.
+- The `agent-menu.test.ts` file is 215 lines and needs call-site updates (factory → class constructor + `.handle()`), but no logic changes.
+- After both conversions, `index.ts` loses ~5 imports and ~4 adapter closures.
+  The remaining ~15 closures are structural (event registrations, SDK factory callbacks) and cannot be eliminated.
+
+## Stage: Implementation — TDD (2026-05-25T14:56:11Z)
+
+### Session summary
+
+Completed all 6 plan steps (collapsed into 5 commits: steps 3 and 5 merged).
+Baseline was 854 tests across 53 files; final suite is 856 tests across 54 files (+2 tests, +1 file for `concrete-agent-runner.test.ts`).
+All type-check, lint, and dead-code gates pass clean.
+
+### Observations
+
+- Plan steps 3 and 5 had to be merged into a single commit: removing `createAgentsMenuHandler` immediately broke `index.ts` imports, so the `index.ts` update could not wait for a separate commit.
+  This is a known coupling when a factory's only call site is in `index.ts`.
+- The `AgentsMenuHandler` class constructor includes `agentActivity` as planned (the issue's proposed signature omitted it; the plan's deviation was correct).
+- `getModelLabel` internalization was clean: `resolveModel` and `getModelLabelFromConfig` are pure functions the class imports directly.
+- `AgentManager` structurally satisfies `AgentMenuManager` with no adapter closures — confirmed by `pnpm run check` passing immediately.
+- The `agent-menu.test.ts` refactor replaced `Partial<AgentMenuDeps>` overrides with a `makeHandler(opts)` helper that returns both the handler and collaborator stubs, which is cleaner for assertion.
+- `rumdl` emitted 3 warnings in `pnpm run lint` — these are pre-existing and unrelated to this change (lint passes for markdown linting, the warnings are from biome/eslint steps that auto-fixed nothing).
+
+## Stage: Final Retrospective (2026-05-25T15:04:47Z)
+
+### Session summary
+
+Completed all three stages (planning, TDD, shipping) in one sitting.
+Issue #196 shipped as `pi-subagents-v7.2.5`.
+All closure factories in pi-subagents are now classes; Phase 11 (Layers 3 + 4) is complete.
+
+### Observations
+
+#### What went well
+
+- The three-session lifecycle (plan → TDD → ship) completed cleanly in a single sitting with no user corrections.
+- Structural typing confirmation during planning paid off — `AgentManager` satisfied `AgentMenuManager` without adapter closures, and `pnpm run check` passed immediately after the wiring change.
+- The `makeHandler(opts)` test helper pattern (returning handler + collaborator stubs) was cleaner than the `Partial<AgentMenuDeps>` spread approach it replaced.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — The plan separated factory removal (step 3) from call-site update (step 5), even though the testing skill already has a rule: "When a TDD step changes an interface that has a single call site, the step must include updating that call site."
+  The planner treated this as a testing concern and didn't apply it during plan authoring.
+  Impact: steps 3 and 5 had to be merged at implementation time, producing a commit message explaining the deviation.
+  Added a cross-reference to `plan-issue.md`.
+
+#### What caused friction (user side)
+
+Nothing notable — the user's issue was well-specified and the three `/` commands ran without intervention.
+
+### Changes made
+
+1. Added single-call-site rule to `.pi/prompts/plan-issue.md` TDD Order section: when a step removes a factory/export with one call site, include the call-site update in the same step.

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

@@ -0,0 +1,36 @@
+---
+issue: 205
+issue_title: "Decompose renderWidgetLines (cognitive 44)"
+---
+
+# Retro: #205 — Decompose renderWidgetLines
+
+## Stage: Planning (2026-05-25T15:27:45Z)
+
+### Session summary
+
+Planned the decomposition of `renderWidgetLines` (cognitive complexity 44) into four private helper functions: `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow`.
+Also updated `architecture.md` Phase 12 steps with issue links (#205–#208) and added a Phase 12 row to the structural refactoring issues table.
+
+### Observations
+
+- The function's complexity comes from five interwoven concerns (categorization, section building, heading, non-overflow assembly with connector fixup, overflow-budget assembly) — but the extraction is mechanical since all logic is already pure and stateless.
+- No new tests are needed — the existing 8 tests in `widget-renderer.test.ts` cover all branches end-to-end and remain the correct test level for assembly logic.
+- The tree-connector fixup (swapping `├─` → `└─` via string replacement on Unicode chars) is the most fragile part; it stays as-is inside `assembleWithinBudget` rather than being further decomposed.
+- A `sections` return object from `buildSections` bundles `finishedLines`, `runningLines`, and `queuedLine` to avoid long parameter lists on the assembly helpers.
+
+## Stage: Implementation — TDD (2026-05-25T15:35:10Z)
+
+### Session summary
+
+Completed all four TDD steps: extracted `categorizeAgents`, `buildSections`, `assembleWithinBudget`, and `assembleOverflow` from `renderWidgetLines`.
+All 23 `widget-renderer.test.ts` tests pass throughout; no new tests were added.
+Full suite (856 tests, 54 files) is green; type check and lint are clean.
+
+### Observations
+
+- **Stray backtick during `assembleOverflow` extraction:** The Edit tool introduced a double-backtick (`\`\``) at the end of the nested template literal on the overflow indicator line — the inner template literal's closing backtick concatenated with the outer template's closing backtick, creating a parse error.
+  Required Python-based line-level surgery to fix since the Edit tool cannot reliably match nested template literals through JSON escaping.
+- The `renderWidgetLines` `else` block removal also required Python because the Edit tool's `oldText` matching is unreliable when the target contains nested template literals with backticks.
+- Aside from the template-literal matching friction, all extractions were purely mechanical; no logic changes were needed.
+- The final `renderWidgetLines` is a clean 12-line orchestrator; each helper is well under complexity 10.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.2.4",
+  "version": "7.2.6",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/index.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/* eslint-disable @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
  *
@@ -24,7 +24,7 @@ import { AgentTypeRegistry } from "#src/config/agent-types";
 import { loadCustomAgents } from "#src/config/custom-agents";
 import { SessionLifecycleHandler, ToolStartHandler } from "#src/handlers/index";
 import { AgentManager, type AgentManagerObserver } from "#src/lifecycle/agent-manager";
-import { createAgentRunner, type RunnerIO } from "#src/lifecycle/agent-runner";
+import { ConcreteAgentRunner, type RunnerIO } from "#src/lifecycle/agent-runner";
 import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { GitWorktreeManager } from "#src/lifecycle/worktree";
 import { buildEventData, type NotificationDetails, NotificationManager } from "#src/observation/notification";
@@ -41,10 +41,9 @@ import { preloadSkills } from "#src/session/skill-loader";
 import { SettingsManager } from "#src/settings";
 import { AgentTool } from "#src/tools/agent-tool";
 import { GetResultTool } from "#src/tools/get-result-tool";
-import { getModelLabelFromConfig } from "#src/tools/helpers";
 import { SteerTool } from "#src/tools/steer-tool";
 import { FsAgentFileOps } from "#src/ui/agent-file-ops";
-import { createAgentsMenuHandler } from "#src/ui/agent-menu";
+import { AgentsMenuHandler } from "#src/ui/agent-menu";
 import { AgentWidget } from "#src/ui/agent-widget";
 
 export default function (pi: ExtensionAPI) {
@@ -147,7 +146,7 @@ export default function (pi: ExtensionAPI) {
   };
 
   const manager = new AgentManager({
-    runner: createAgentRunner(runnerIO),
+    runner: new ConcreteAgentRunner(runnerIO),
     worktrees: new GitWorktreeManager(process.cwd()),
     exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
     registry,
@@ -193,33 +192,20 @@ export default function (pi: ExtensionAPI) {
 
   // ---- /agents interactive menu ----
 
-  const agentsMenuHandler = createAgentsMenuHandler({
-    manager: {
-      listAgents: () => manager.listAgents(),
-      getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
-    },
+  const agentsMenu = new AgentsMenuHandler(
+    manager,
     registry,
-    agentActivity: runtime.agentActivity,
-    getModelLabel: (type, modelRegistry) => {
-      const cfg = registry.resolveAgentConfig(type);
-      if (!cfg.model) return 'inherit';
-      if (modelRegistry) {
-        const resolved = resolveModel(cfg.model, modelRegistry);
-        if (typeof resolved === 'string') return 'inherit';
-      }
-      return getModelLabelFromConfig(cfg.model);
-    },
+    runtime.agentActivity,
     settings,
-    fileOps: new FsAgentFileOps(),
-    personalAgentsDir: join(getAgentDir(), 'agents'),
-    projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
-  });
+    new FsAgentFileOps(),
+    join(getAgentDir(), "agents"),
+    join(process.cwd(), ".pi", "agents"),
+  );
 
-  pi.registerCommand('agents', {
-    description: 'Manage agents',
+  pi.registerCommand("agents", {
+    description: "Manage agents",
     handler: async (_args, ctx) => {
-      await agentsMenuHandler({
+      await agentsMenu.handle({
         ui: ctx.ui,
         modelRegistry: ctx.modelRegistry,
         parentSnapshot: buildParentSnapshot(ctx),

package/src/lifecycle/agent-runner.ts

@@ -202,17 +202,23 @@ export interface AgentRunner {
 }
 
 /**
- * Create an AgentRunner backed by the given IO boundary.
+ * Concrete AgentRunner backed by a RunnerIO boundary.
  *
  * Captures io at construction time so AgentManager remains IO-unaware.
  */
-export function createAgentRunner(io: RunnerIO): AgentRunner {
-  return {
-    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
-    resume: resumeAgent,
-  };
+export class ConcreteAgentRunner implements AgentRunner {
+  constructor(private readonly io: RunnerIO) {}
+
+  run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
+    return runAgent(snapshot, type, prompt, options, this.io);
+  }
+
+  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
+    return resumeAgent(session, prompt, options);
+  }
 }
 
+
 // ── Private helpers ───────────────────────────────────────────────────────────
 
 /**