@gotgenes/pi-subagents 7.2.4 → 7.2.5

package/CHANGELOG.md

@@ -5,6 +5,16 @@ 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).
 
+## [7.2.5](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.4...pi-subagents-v7.2.5) (2026-05-25)
+
+
+### Documentation
+
+* mark Phase 11 Layer 3 and Layer 4 complete ([bf71795](https://github.com/gotgenes/pi-packages/commit/bf71795649a5b3c14a2b3ff16b2109d131a0ed32))
+* plan convert AgentRunner and AgentsMenuHandler to classes ([#196](https://github.com/gotgenes/pi-packages/issues/196)) ([cd0bd1f](https://github.com/gotgenes/pi-packages/commit/cd0bd1fdec0c87655bdb38f8243084df807b676a))
+* **retro:** add planning stage notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([677d4bf](https://github.com/gotgenes/pi-packages/commit/677d4bf6619f13eba8d17181efab04cc67e47bbd))
+* **retro:** add TDD stage notes for issue [#196](https://github.com/gotgenes/pi-packages/issues/196) ([72d24ba](https://github.com/gotgenes/pi-packages/commit/72d24ba56b8dc7668ff350ad3f0ba027b996d26e))
+
 ## [7.2.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.3...pi-subagents-v7.2.4) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -686,45 +686,46 @@ After this step, `AgentManager` structurally satisfies `AgentToolManager` and `S
 - Outcome: structural typing connects real objects to tool interfaces without adapters; 0 dead exports (fallow clean)
 - Enables: Layer 3 (class constructors accept real objects directly)
 
-### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])
+### Layer 3: Convert closure factories to classes ([#195][195], [#196][196]) ✓ done
 
-With Layers 0–2 complete, each factory is a mechanical conversion. ✓ Tool factories converted in [#195][195]:
+All closure factories converted to classes. ✓ Tool factories in [#195][195]; runner and menu in [#196][196]:
 
-| Factory                          | Class                          | Constructor params                                  |
-| -------------------------------- | ------------------------------ | --------------------------------------------------- |
-| `createAgentTool({...})`         | `AgentTool` ✓                  | `manager`, `runtime`, `settings`, `registry`        |
-| `createGetResultTool(...)`       | `GetResultTool` ✓              | `manager`, `notifications`, `registry`              |
-| `createSteerTool(...)`           | `SteerTool` ✓                  | `manager`, `events`                                 |
-| `createAgentRunner(runnerIO)`    | `AgentRunner` (concrete class) | `io: RunnerIO`                                      |
-| `createAgentsMenuHandler({...})` | `AgentsMenuHandler`            | `manager`, `registry`, `settings`, `fileOps`, paths |
+| Factory                          | Class                   | Constructor params                                                   |
+| -------------------------------- | ----------------------- | -------------------------------------------------------------------- |
+| `createAgentTool({...})`         | `AgentTool` ✓           | `manager`, `runtime`, `settings`, `registry`                         |
+| `createGetResultTool(...)`       | `GetResultTool` ✓       | `manager`, `notifications`, `registry`                               |
+| `createSteerTool(...)`           | `SteerTool` ✓           | `manager`, `events`                                                  |
+| `createAgentRunner(runnerIO)`    | `ConcreteAgentRunner` ✓ | `io: RunnerIO`                                                       |
+| `createAgentsMenuHandler({...})` | `AgentsMenuHandler` ✓   | `manager`, `registry`, `agentActivity`, `settings`, `fileOps`, paths |
 
 Each class satisfies the existing interface via structural typing.
 The `defineTool()` wrapper moves into a `toToolDefinition()` method on each tool class.
+`getModelLabel` internalized into `AgentsMenuHandler` (was a 7-line closure in `index.ts`).
 
 - Target: `src/tools/*.ts`, `src/lifecycle/agent-runner.ts`, `src/ui/agent-menu.ts`
 - Smell: Category C (closure factories masquerading as classes)
 - Outcome: deps are constructor params (inspectable, testable); no captured closures
 - Enables: Layer 4 (index.ts simplification)
 
-### Layer 4: Simplify index.ts (included in [#196][196])
+### Layer 4: Simplify index.ts (included in [#196][196]) ✓ done
 
-With real objects satisfying tool interfaces and queries living on `SubagentRuntime`, the composition root becomes pure construction:
+With all factories converted to classes and `AgentManager` satisfying `AgentMenuManager` structurally:
 
 ```typescript
-const runtime = new SubagentRuntime();
-const settings = new SettingsManager(...);
-const manager = new AgentManager(...);
-const agentTool = new AgentTool(manager, runtime, settings, registry);
-pi.registerTool(agentTool.toToolDefinition());
+const agentsMenu = new AgentsMenuHandler(
+  manager, registry, runtime.agentActivity,
+  settings, new FsAgentFileOps(),
+  join(getAgentDir(), "agents"),
+  join(process.cwd(), ".pi", "agents"),
+);
 ```
 
-No adapter closures.
-No `as any`.
-Fan-out drops from 25 to ~15 (internal factories eliminated).
+Eliminated: 4 adapter closures (3 manager method adapters + `getModelLabel`), 4 unused imports.
+Remaining ~15 closures are structural (event registrations, SDK factory callbacks).
 
 - Target: `src/index.ts`
 - Smell: Category B (god file) + Category C (adapter closure density)
-- Outcome: index.ts shrinks from 280 to ~150 lines; churn hotspot stabilizes
+- Outcome: adapter closure count reduced; `AgentManager` passed directly without wrappers; churn hotspot stabilized
 
 ### Step dependencies
 

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

@@ -0,0 +1,268 @@
+---
+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/retro/0196-convert-runner-menu-to-classes.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.2.4",
+  "version": "7.2.5",
   "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 ───────────────────────────────────────────────────────────
 
 /**

package/src/ui/agent-menu.ts

@@ -2,7 +2,8 @@
 import { wrapTextWithAnsi } from "@earendil-works/pi-tui";
 import { AgentTypeRegistry } from "#src/config/agent-types";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { ModelRegistry } from "#src/session/model-resolver";
+import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
+import { getModelLabelFromConfig } from "#src/tools/helpers";
 import type { AgentConfig, AgentRecord } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { createAgentConfigEditor } from "#src/ui/agent-config-editor";
@@ -10,7 +11,7 @@ import { createAgentCreationWizard } from "#src/ui/agent-creation-wizard";
 import type { AgentFileOps } from "#src/ui/agent-file-ops";
 import { formatDuration, getDisplayName } from "#src/ui/display";
 
-// ---- Deps interface ----
+// ---- Narrow interfaces ----
 
 /** Narrow manager interface for menu operations. */
 export interface AgentMenuManager {
@@ -43,19 +44,6 @@ export interface AgentActivityReader {
   get(id: string): AgentActivityTracker | undefined;
 }
 
-export interface AgentMenuDeps {
-  manager: AgentMenuManager;
-  registry: AgentTypeRegistry;
-  agentActivity: AgentActivityReader;
-  /** Resolve model label for a given agent type + registry. */
-  getModelLabel: (type: string, registry?: ModelRegistry) => string;
-  /** Settings manager — owns in-memory values and persistence. */
-  settings: AgentMenuSettings;
-  fileOps: AgentFileOps;
-  personalAgentsDir: string;
-  projectAgentsDir: string;
-}
-
 // ---- Narrow UI context types ----
 
 /** Narrow UI interface — only the ctx.ui methods menu handlers actually call. */
@@ -68,48 +56,74 @@ export interface MenuUI {
   custom<R>(component: any, options?: any): Promise<R>;
 }
 
-// ---- Factory ----
+// ---- Class ----
 
 /**
- * Create the `/agents` command handler.
- * Returns a function suitable for `pi.registerCommand("agents", { handler })`.
+ * Handler for the `/agents` slash command.
+ *
+ * Call `handle(ctx)` from the Pi command registration to open the interactive menu.
  */
-export function createAgentsMenuHandler({
-  manager,
-  registry,
-  agentActivity,
-  getModelLabel,
-  settings,
-  fileOps,
-  personalAgentsDir,
-  projectAgentsDir,
-}: AgentMenuDeps) {
-  const editor = createAgentConfigEditor(
-    fileOps,
-    registry,
-    personalAgentsDir,
-    projectAgentsDir,
-  );
-
-  const wizard = createAgentCreationWizard({
-    fileOps,
-    manager,
-    registry,
-    personalAgentsDir,
-    projectAgentsDir,
-  });
-
-  async function showAgentsMenu(
+export class AgentsMenuHandler {
+  private readonly editor: ReturnType<typeof createAgentConfigEditor>;
+  private readonly wizard: ReturnType<typeof createAgentCreationWizard>;
+
+  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,
+  ) {
+    this.editor = createAgentConfigEditor(
+      fileOps,
+      registry,
+      personalAgentsDir,
+      projectAgentsDir,
+    );
+    this.wizard = createAgentCreationWizard({
+      fileOps,
+      manager,
+      registry,
+      personalAgentsDir,
+      projectAgentsDir,
+    });
+  }
+
+  async handle({
+    ui,
+    modelRegistry,
+    parentSnapshot,
+  }: {
+    ui: MenuUI;
+    modelRegistry: ModelRegistry;
+    parentSnapshot: ParentSnapshot;
+  }): Promise<void> {
+    await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
+  }
+
+  private getModelLabel(type: string, modelRegistry?: ModelRegistry): string {
+    const cfg = this.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);
+  }
+
+  private async showAgentsMenu(
     ui: MenuUI,
     modelRegistry: ModelRegistry,
     parentSnapshot: ParentSnapshot,
-  ) {
-    registry.reload();
-    const allNames = registry.getAllTypes();
+  ): Promise<void> {
+    this.registry.reload();
+    const allNames = this.registry.getAllTypes();
 
     const options: string[] = [];
 
-    const agents = manager.listAgents();
+    const agents = this.manager.listAgents();
     if (agents.length > 0) {
       const running = agents.filter(
         (a) => a.status === "running" || a.status === "queued",
@@ -144,21 +158,21 @@ export function createAgentsMenuHandler({
     if (!choice) return;
 
     if (choice.startsWith("Running agents (")) {
-      await showRunningAgents(ui);
-      await showAgentsMenu(ui, modelRegistry, parentSnapshot);
+      await this.showRunningAgents(ui);
+      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
     } else if (choice.startsWith("Agent types (")) {
-      await showAllAgentsList(ui, modelRegistry);
-      await showAgentsMenu(ui, modelRegistry, parentSnapshot);
+      await this.showAllAgentsList(ui, modelRegistry);
+      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
     } else if (choice === "Create new agent") {
-      await wizard.showCreateWizard(ui, parentSnapshot);
+      await this.wizard.showCreateWizard(ui, parentSnapshot);
     } else if (choice === "Settings") {
-      await showSettings(ui);
-      await showAgentsMenu(ui, modelRegistry, parentSnapshot);
+      await this.showSettings(ui);
+      await this.showAgentsMenu(ui, modelRegistry, parentSnapshot);
     }
   }
 
-  async function showAllAgentsList(ui: MenuUI, modelRegistry: ModelRegistry) {
-    const allNames = registry.getAllTypes();
+  private async showAllAgentsList(ui: MenuUI, modelRegistry: ModelRegistry): Promise<void> {
+    const allNames = this.registry.getAllTypes();
     if (allNames.length === 0) {
       ui.notify("No agents.", "info");
       return;
@@ -173,9 +187,9 @@ export function createAgentsMenuHandler({
     };
 
     const entries = allNames.map((name) => {
-      const cfg = registry.resolveAgentConfig(name);
+      const cfg = this.registry.resolveAgentConfig(name);
       const disabled = cfg.enabled === false;
-      const model = getModelLabel(name, modelRegistry);
+      const model = this.getModelLabel(name, modelRegistry);
       const indicator = sourceIndicator(cfg);
       const prefix = `${indicator}${name} · ${model}`;
       const desc = disabled ? "(disabled)" : cfg.description;
@@ -184,11 +198,11 @@ export function createAgentsMenuHandler({
     const maxPrefix = Math.max(...entries.map((e) => e.prefix.length));
 
     const hasCustom = allNames.some((n) => {
-      const c = registry.resolveAgentConfig(n);
+      const c = this.registry.resolveAgentConfig(n);
       return !c.isDefault && c.enabled !== false;
     });
     const hasDisabled = allNames.some(
-      (n) => registry.resolveAgentConfig(n).enabled === false,
+      (n) => this.registry.resolveAgentConfig(n).enabled === false,
     );
     const legendParts: string[] = [];
     if (hasCustom) legendParts.push("• = project  ◦ = global");
@@ -207,21 +221,21 @@ export function createAgentsMenuHandler({
       .split(" · ")[0]
       .replace(/^[•◦✕\s]+/, "")
       .trim();
-    if (registry.resolveType(agentName) != null) {
-      await editor.showAgentDetail(ui, agentName);
-      await showAllAgentsList(ui, modelRegistry);
+    if (this.registry.resolveType(agentName) != null) {
+      await this.editor.showAgentDetail(ui, agentName);
+      await this.showAllAgentsList(ui, modelRegistry);
     }
   }
 
-  async function showRunningAgents(ui: MenuUI) {
-    const agents = manager.listAgents();
+  private async showRunningAgents(ui: MenuUI): Promise<void> {
+    const agents = this.manager.listAgents();
     if (agents.length === 0) {
       ui.notify("No agents.", "info");
       return;
     }
 
     const options = agents.map((a) => {
-      const dn = getDisplayName(a.type, registry);
+      const dn = getDisplayName(a.type, this.registry);
       const dur = formatDuration(a.startedAt, a.completedAt);
       return `${dn} (${a.description}) · ${a.toolUses} tools · ${a.status} · ${dur}`;
     });
@@ -233,11 +247,11 @@ export function createAgentsMenuHandler({
     if (idx < 0) return;
     const record = agents[idx];
 
-    await viewAgentConversation(ui, record);
-    await showRunningAgents(ui);
+    await this.viewAgentConversation(ui, record);
+    await this.showRunningAgents(ui);
   }
 
-  async function viewAgentConversation(ui: MenuUI, record: AgentRecord) {
+  private async viewAgentConversation(ui: MenuUI, record: AgentRecord): Promise<void> {
     const session = record.session;
     if (!session) {
       ui.notify(
@@ -250,7 +264,7 @@ export function createAgentsMenuHandler({
     const { ConversationViewer, VIEWPORT_HEIGHT_PCT } = await import(
       "./conversation-viewer"
     );
-    const activity = agentActivity.get(record.id);
+    const activity = this.agentActivity.get(record.id);
 
     await ui.custom<undefined>(
       (tui: any, theme: any, _keybindings: any, done: any) => {
@@ -261,7 +275,7 @@ export function createAgentsMenuHandler({
           activity,
           theme,
           done,
-          registry,
+          registry: this.registry,
           wrapText: wrapTextWithAnsi,
         });
       },
@@ -276,23 +290,23 @@ export function createAgentsMenuHandler({
     );
   }
 
-  async function showSettings(ui: MenuUI) {
+  private async showSettings(ui: MenuUI): Promise<void> {
     const choice = await ui.select("Settings", [
-      `Max concurrency (current: ${settings.maxConcurrent})`,
-      `Default max turns (current: ${settings.defaultMaxTurns ?? "unlimited"})`,
-      `Grace turns (current: ${settings.graceTurns})`,
+      `Max concurrency (current: ${this.settings.maxConcurrent})`,
+      `Default max turns (current: ${this.settings.defaultMaxTurns ?? "unlimited"})`,
+      `Grace turns (current: ${this.settings.graceTurns})`,
     ]);
     if (!choice) return;
 
     if (choice.startsWith("Max concurrency")) {
       const val = await ui.input(
         "Max concurrent background agents",
-        String(settings.maxConcurrent),
+        String(this.settings.maxConcurrent),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          const toast = settings.applyMaxConcurrent(n);
+          const toast = this.settings.applyMaxConcurrent(n);
           ui.notify(toast.message, toast.level);
         } else {
           ui.notify("Must be a positive integer.", "warning");
@@ -301,12 +315,12 @@ export function createAgentsMenuHandler({
     } else if (choice.startsWith("Default max turns")) {
       const val = await ui.input(
         "Default max turns before wrap-up (0 = unlimited)",
-        String(settings.defaultMaxTurns ?? 0),
+        String(this.settings.defaultMaxTurns ?? 0),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 0) {
-          const toast = settings.applyDefaultMaxTurns(n);
+          const toast = this.settings.applyDefaultMaxTurns(n);
           ui.notify(toast.message, toast.level);
         } else {
           ui.notify("Must be 0 (unlimited) or a positive integer.", "warning");
@@ -315,12 +329,12 @@ export function createAgentsMenuHandler({
     } else if (choice.startsWith("Grace turns")) {
       const val = await ui.input(
         "Grace turns after wrap-up steer",
-        String(settings.graceTurns),
+        String(this.settings.graceTurns),
       );
       if (val) {
         const n = parseInt(val, 10);
         if (n >= 1) {
-          const toast = settings.applyGraceTurns(n);
+          const toast = this.settings.applyGraceTurns(n);
           ui.notify(toast.message, toast.level);
         } else {
           ui.notify("Must be a positive integer.", "warning");
@@ -328,16 +342,4 @@ export function createAgentsMenuHandler({
       }
     }
   }
-
-  return async ({
-    ui,
-    modelRegistry,
-    parentSnapshot,
-  }: {
-    ui: MenuUI;
-    modelRegistry: ModelRegistry;
-    parentSnapshot: ParentSnapshot;
-  }) => {
-    await showAgentsMenu(ui, modelRegistry, parentSnapshot);
-  };
 }