@gotgenes/pi-subagents 6.8.1 → 6.8.3

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.8.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.2...pi-subagents-v6.8.3) (2026-05-22)
+
+
+### Documentation
+
+* mark Step D1 complete in architecture.md ([#113](https://github.com/gotgenes/pi-packages/issues/113)) ([b42de23](https://github.com/gotgenes/pi-packages/commit/b42de238710931348336d6e7fd81bb000a0ab584))
+* plan disambiguate SpawnOptions (public vs internal) ([#113](https://github.com/gotgenes/pi-packages/issues/113)) ([2f3cebc](https://github.com/gotgenes/pi-packages/commit/2f3cebc6623e0ba20c73145d8e7c6b9ffae6f875))
+* **retro:** add retro notes for issue [#112](https://github.com/gotgenes/pi-packages/issues/112) ([2a59ed4](https://github.com/gotgenes/pi-packages/commit/2a59ed4e4f5462cdbf8df96e4b675a9c5ec6eb9d))
+
+## [6.8.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.1...pi-subagents-v6.8.2) (2026-05-22)
+
+
+### Documentation
+
+* mark Step C complete in architecture.md ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([9f6e783](https://github.com/gotgenes/pi-packages/commit/9f6e783ab4ddcabdc24224e02aa631b93b0fb6d4))
+* plan replace AgentManager callbacks with observer interface ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([b32dde1](https://github.com/gotgenes/pi-packages/commit/b32dde1e473611b2734a287e88c8d155642405a7))
+* **retro:** add retro notes for issue [#123](https://github.com/gotgenes/pi-packages/issues/123) ([e9333ee](https://github.com/gotgenes/pi-packages/commit/e9333ee2af70e821ba1bace63bdbd7befa72ce84))
+
 ## [6.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.0...pi-subagents-v6.8.1) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -384,8 +384,8 @@ Each step is sequenced so it makes the next step easier.
 | ~~Mutable state bag~~          | ~~`AgentActivity` (7 fields)~~           | **Fixed #110**: `AgentActivityTracker` class; `ui-observer.ts` calls transition methods; widget, notification, agent-tool use read-only accessors                         |
 | ~~Settings relay~~             | ~~`AgentMenuDeps` (13 fields)~~          | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                         |
 | ~~Post-construction mutation~~ | ~~`AgentRecord` non-transition state~~   | **Fixed #111**: `ExecutionState`, `WorktreeState`, `NotificationState` collaborators; `pendingSteers` moved to `AgentManager`; stats encapsulated behind mutation methods |
-| Fire-and-forget callbacks      | `AgentManagerOptions`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
-| Duplicate `SpawnOptions`       | `service.ts` + `agent-manager.ts`        | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
+| ~~Fire-and-forget callbacks~~  | ~~`AgentManagerOptions`~~                | **Fixed #112**: `AgentManagerObserver` interface; `observer` replaces 3 callbacks; `index.ts` constructs one observer object instead of 3 closure lambdas                 |
+| ~~Duplicate `SpawnOptions`~~   | ~~`service.ts` + `agent-manager.ts`~~    | **Fixed #113**: internal type renamed to `AgentSpawnConfig`; public `SpawnOptions` in `service.ts` unchanged                                                              |
 | Type dumping ground            | `types.ts`                               | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each |
 | Wide dependency bags           | `AgentToolDeps` (7), `AgentMenuDeps` (8) | Settings narrowed (#109); registry narrowed (#108); more narrowing planned in D steps                                                                                     |
 
@@ -445,21 +445,22 @@ Split post-construction mutation into phase-specific collaborators, each born co
 Each piece is born complete at the moment its information is available.
 The record doesn't accumulate half-baked state — it receives fully constructed collaborators.
 
-### Step C: Replace `AgentManager` callbacks with observer (#112)
+### Step C: Replace `AgentManager` callbacks with observer (#112) ✅
 
-Replace the `onStart`/`onComplete`/`onCompact` callback parameters with an `AgentManagerObserver` interface (or typed event emitter).
-The observer methods receive the same data the callbacks receive today.
-`index.ts` constructs the observer once instead of building 3 closure callbacks that capture `runtime`, `pi`, `notifications`, etc.
-`AgentManagerOptions` drops from 8 → 5 fields.
+**Done.**
+`AgentManagerObserver` interface replaces `onStart`/`onComplete`/`onCompact`.
+`index.ts` constructs one observer object instead of 3 closure lambdas.
+`AgentManagerOptions` drops from 9 → 7 fields.
 
 ### Step D: Disambiguate `SpawnOptions` and narrow dependency bags
 
 With the registry class, settings manager, and observer in place, the dependency bags shrink naturally.
 
-#### D1. Disambiguate `SpawnOptions` (#113)
+#### D1. Disambiguate `SpawnOptions` (#113) ✅
 
-Rename the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig` (or similar) to distinguish it from the JSON-friendly public `SpawnOptions` in `service.ts`.
-The two types serve different consumers and should not share a name.
+**Done.**
+Internal `SpawnOptions` in `agent-manager.ts` renamed to `AgentSpawnConfig`.
+Public `SpawnOptions` in `service.ts` is unchanged.
 
 #### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114)
 

package/docs/plans/0112-replace-agent-manager-callbacks.md

@@ -0,0 +1,241 @@
+---
+issue: 112
+issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
+---
+
+# Replace AgentManager callbacks with observer interface
+
+## Problem Statement
+
+`AgentManagerOptions` accepts three fire-and-forget callbacks — `onStart`, `onComplete`, `onCompact` — that `index.ts` wires as closure lambdas capturing `runtime`, `pi`, `notifications`, and other extension state.
+This is the same callback-threading pattern that was replaced with direct session subscriptions in #100, but one level up.
+The callbacks are notification-style (fire-and-forget, no return value) and match the observer pattern exactly.
+
+## Goals
+
+- Replace the three callback parameters on `AgentManagerOptions` with a single `observer?: AgentManagerObserver` interface.
+- `index.ts` constructs one observer object instead of three independent closure lambdas.
+- `AgentManagerOptions` shrinks by two net fields (remove 3 callbacks, add 1 observer).
+- Preserve all existing behavior: lifecycle events, record persistence, notification dispatch, compaction events.
+- Non-breaking refactor — no public API changes (the callbacks are internal to the package).
+
+## Non-Goals
+
+- Extracting the observer implementation from `index.ts` into its own module — that can follow if the object grows.
+- Changing `RecordObserverOptions` (session-level observer) — it remains a separate concern at a different layer.
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` — tracked in #114.
+- Disambiguating `SpawnOptions` — tracked in #113.
+
+## Background
+
+### Current callback wiring
+
+`agent-manager.ts` defines three callback type aliases and stores them as private fields:
+
+```typescript
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+```
+
+`AgentManager` invokes them at three points:
+
+1. `onStart` — called in `startAgent()` after `record.markRunning()`.
+2. `onComplete` — called in `startAgent()`'s `.then()` and `.catch()` handlers for background agents, and in `drainQueue()` on late failure.
+3. `onCompact` — relayed through `subscribeRecordObserver()` → `RecordObserverOptions.onCompact`.
+
+`index.ts` builds ~30 lines of closure lambdas (lines 73–116) that capture `pi`, `notifications`, and `buildEventData`.
+
+### Observer pattern already established
+
+`record-observer.ts` and `ui/ui-observer.ts` are session-level observers that subscribe directly to session events.
+This refactoring applies the same principle at the manager level — grouping related notification callbacks into a single interface.
+
+### Dependency: issue #111 (AgentRecord lifecycle split)
+
+Issue #111 is closed.
+The observer interface is designed against the current record shape, which reflects the post-#111 lifecycle split.
+
+### Architecture reference
+
+Phase 7, Step C in `docs/architecture/architecture.md`.
+
+## Design Overview
+
+### Observer interface
+
+```typescript
+export interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+}
+```
+
+All three methods are fire-and-forget (void return, no async).
+The interface uses past-tense naming (`Started`, `Completed`, `Compacted`) to signal that these are after-the-fact notifications, not hooks that influence the operation.
+
+### `AgentManagerOptions` change
+
+```typescript
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  exec: ShellExec;
+  registry: AgentTypeRegistry;
+  getMaxConcurrent?: () => number;
+  getRunConfig?: () => RunConfig;
+  observer?: AgentManagerObserver;  // replaces onStart, onComplete, onCompact
+}
+```
+
+Fields go from 9 → 7 (remove 3 callbacks, add 1 observer).
+
+### AgentManager internal changes
+
+The three private fields (`onStart`, `onComplete`, `onCompact`) become one: `private observer?: AgentManagerObserver`.
+Call sites change from `this.onStart?.(record)` to `this.observer?.onAgentStarted(record)`.
+
+The `onCompact` relay into `subscribeRecordObserver` changes from:
+
+```typescript
+onCompact: (r, info) => this.onCompact?.(r, info),
+```
+
+to:
+
+```typescript
+onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+```
+
+### `CompactionInfo` stays in `agent-manager.ts`
+
+`CompactionInfo` is a data shape consumed by the observer interface and already defined in `agent-manager.ts`.
+It stays co-located since both `AgentManagerObserver` and `CompactionInfo` are exported from the same module.
+`record-observer.ts` continues to import `CompactionInfo` from `agent-manager.ts`.
+
+### Observer construction in `index.ts`
+
+The three closure lambdas collapse into one object literal:
+
+```typescript
+const observer: AgentManagerObserver = {
+  onAgentStarted(record) {
+    pi.events.emit("subagents:started", {
+      id: record.id, type: record.type, description: record.description,
+    });
+  },
+  onAgentCompleted(record) {
+    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+    const eventData = buildEventData(record);
+    if (isError) pi.events.emit("subagents:failed", eventData);
+    else pi.events.emit("subagents:completed", eventData);
+
+    pi.appendEntry("subagents:record", { /* same fields as today */ });
+
+    if (record.notification?.resultConsumed) {
+      notifications.cleanupCompleted(record.id);
+      return;
+    }
+    notifications.sendCompletion(record);
+  },
+  onAgentCompacted(record, info) {
+    pi.events.emit("subagents:compacted", {
+      id: record.id, type: record.type, description: record.description,
+      reason: info.reason, tokensBefore: info.tokensBefore,
+      compactionCount: record.compactionCount,
+    });
+  },
+};
+```
+
+Passed as `observer` to `new AgentManager({ ..., observer })`.
+
+### Removed exports
+
+The three callback type aliases are removed:
+
+- `OnAgentStart`
+- `OnAgentComplete`
+- `OnAgentCompact`
+
+These are only imported in `agent-manager.test.ts` — no production consumers outside `agent-manager.ts`.
+
+## Module-Level Changes
+
+### `src/agent-manager.ts`
+
+- Add `AgentManagerObserver` interface (3 methods).
+- Remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact` type aliases.
+- Replace `onStart`, `onComplete`, `onCompact` fields in `AgentManagerOptions` with `observer?: AgentManagerObserver`.
+- Replace three private fields with `private observer?: AgentManagerObserver`.
+- Update constructor to assign `this.observer = options.observer`.
+- Update all call sites: `this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.
+- The `onCompact` relay to `subscribeRecordObserver` uses `this.observer?.onAgentCompacted`.
+
+### `src/index.ts`
+
+- Replace the three closure-lambda properties (`onComplete:`, `onStart:`, `onCompact:`) with a single `observer` object literal.
+- Import `AgentManagerObserver` from `agent-manager.ts`.
+- Remove any now-unused callback type imports.
+
+### `src/record-observer.ts`
+
+- No changes.
+  `RecordObserverOptions.onCompact` stays as-is — it is the session-level relay, not the manager-level observer.
+  `CompactionInfo` import from `agent-manager.ts` stays unchanged.
+
+### `test/agent-manager.test.ts`
+
+- Update imports: remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`; add `AgentManagerObserver`.
+- Update `createManager` helper: replace the three callback overrides with `observer?: Partial<AgentManagerObserver>`.
+  The factory spreads a no-op default observer with test-provided overrides.
+- Update each test that wires a callback to construct an observer object instead.
+
+## Test Impact Analysis
+
+1. No new unit tests are enabled by this refactoring — it's a 1:1 shape change.
+2. No existing tests become redundant — each test exercises a specific lifecycle scenario (race condition, foreground vs background, error handling, queue drain).
+3. All existing `agent-manager.test.ts` tests stay, with mechanical updates to the observer wiring.
+   The assertions remain the same (e.g., "observer.onAgentCompleted fires with `resultConsumed=false` when `markConsumed` called after await").
+
+## TDD Order
+
+### Step 1: Introduce `AgentManagerObserver` interface alongside existing callbacks
+
+Add the interface to `agent-manager.ts`.
+No production behavior changes — the interface is unused at this point.
+
+- Commit: `refactor: add AgentManagerObserver interface`
+
+### Step 2: Switch `AgentManager` internals to observer
+
+1. Replace the three `onStart`/`onComplete`/`onCompact` fields on `AgentManagerOptions` with `observer?: AgentManagerObserver`.
+2. Replace the three private fields with one `private observer?: AgentManagerObserver`.
+3. Update all internal call sites (`this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.).
+4. Remove the three callback type aliases (`OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`).
+5. Update `test/agent-manager.test.ts`: change imports, update `createManager` helper and all test call sites to construct observer objects instead of individual callbacks.
+6. Run `pnpm run check` to verify types.
+
+- Commit: `refactor: replace AgentManager callbacks with observer interface (#112)`
+
+### Step 3: Update `index.ts` to construct observer
+
+1. Replace the three closure-lambda properties in the `new AgentManager({...})` call with a single `observer` object.
+2. Import `AgentManagerObserver` type.
+3. Remove unused callback type imports.
+4. Run full test suite.
+
+- Commit: `refactor: construct AgentManagerObserver in index.ts (#112)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                | Mitigation                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Tests break silently because esbuild ignores excess properties — old `onComplete` fields pass through without error | Step 2 removes the type aliases, so TypeScript catches any test still using the old shape via `pnpm run check`                                                              |
+| `onComplete` error-swallowing behavior changes                                                                      | The `try/catch` around `this.onComplete?.(record)` in the `.then()` path moves exactly to `this.observer?.onAgentCompleted(record)` — same guard, same catch, same debugLog |
+| `Partial<AgentManagerObserver>` in test factory silently drops required methods                                     | Tests that need a specific method construct it explicitly; the factory only provides a convenient default for tests that don't care about any observer method               |
+
+## Open Questions
+
+- None — the issue's proposed design is unambiguous and aligns with the established session-observer pattern.

package/docs/plans/0113-disambiguate-spawn-options.md

@@ -0,0 +1,155 @@
+---
+issue: 113
+issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
+---
+
+# Disambiguate SpawnOptions (public vs internal)
+
+## Problem Statement
+
+`SpawnOptions` is defined in two places with the same name but incompatible shapes:
+
+- `service.ts` (public API): 8 fields, JSON-friendly (`model` is `string`, `thinkingLevel` is `string`, uses `foreground` not `isBackground`).
+- `agent-manager.ts` (internal): 13 fields, runtime types (`model` is `Model<any>`, `thinkingLevel` is `ThinkingLevel`, includes `signal`, `onSessionCreated`, `invocation`).
+
+The name collision makes it ambiguous which type a reader is working with when they see `SpawnOptions` in a signature.
+`service-adapter.ts` manually converts between the two shapes.
+
+## Goals
+
+- Rename the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig`.
+- Keep the public `SpawnOptions` in `service.ts` unchanged — it's the published API.
+- Update all internal consumers (`agent-tool.ts`, `agent-menu.ts`, `agent-manager.ts`) to use the new name.
+- Update the `SpawnArgs` internal interface in `agent-manager.ts` to reference `AgentSpawnConfig`.
+- Non-breaking refactor — the public API surface is unchanged.
+
+## Non-Goals
+
+- Splitting `AgentSpawnConfig` into agent-configuration fields vs execution/lifecycle fields — the issue mentions this as a "consider" item; defer to a follow-up if the type grows further.
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` — tracked in #114.
+- Removing `onSessionCreated` — it's a legitimate per-spawn callback used by `agent-tool.ts` for UI streaming, structurally different from the lifecycle observer (#112).
+
+## Background
+
+### Current consumers of internal `SpawnOptions`
+
+| File                  | How it references `SpawnOptions`                                                            |
+| --------------------- | ------------------------------------------------------------------------------------------- |
+| `agent-manager.ts`    | Defines the type; uses it in `spawn()`, `spawnAndWait()`, and `SpawnArgs`                   |
+| `tools/agent-tool.ts` | Imports and uses in `AgentToolManager.spawn` and `AgentToolManager.spawnAndWait` signatures |
+| `ui/agent-menu.ts`    | Imports and uses in `AgentMenuManager.spawnAndWait` signature                               |
+
+### Public `SpawnOptions` in `service.ts`
+
+Defined alongside `SubagentsService`.
+Used by `service-adapter.ts` at the conversion boundary.
+Published via `package.json` exports — **not touched by this change**.
+
+### Dependency: issue #112 (observer refactor)
+
+Issue #112 is closed.
+The observer eliminated `onStart`/`onComplete`/`onCompact` from `AgentManagerOptions`.
+`onSessionCreated` remains on the internal `SpawnOptions` (now `AgentSpawnConfig`) — it's per-spawn, not per-manager.
+
+### Architecture reference
+
+Phase 7, Step D1 in `docs/architecture/architecture.md`.
+
+## Design Overview
+
+This is a pure rename — no structural or behavioral changes.
+The internal `SpawnOptions` becomes `AgentSpawnConfig`.
+Every `import type { SpawnOptions }` from `"../agent-manager.js"` or `"./agent-manager.js"` becomes `import type { AgentSpawnConfig }`.
+
+The name `AgentSpawnConfig` was chosen because:
+
+1. It disambiguates from the public `SpawnOptions`.
+2. It follows the established naming convention in this package (`AgentRecord`, `AgentInvocation`, `AgentTypeRegistry`).
+3. "Config" conveys that this is a configuration bag assembled by the caller and consumed by the manager — not a service-level options type.
+
+### Type shape (unchanged)
+
+```typescript
+export interface AgentSpawnConfig {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  bypassQueue?: boolean;
+  isolation?: IsolationMode;
+  invocation?: AgentInvocation;
+  signal?: AbortSignal;
+  onSessionCreated?: (session: AgentSession) => void;
+  parentSessionFile?: string;
+  parentSessionId?: string;
+}
+```
+
+## Module-Level Changes
+
+### `src/agent-manager.ts`
+
+- Rename `export interface SpawnOptions` → `export interface AgentSpawnConfig`.
+- Update `SpawnArgs.options` type from `SpawnOptions` to `AgentSpawnConfig`.
+- Update `spawn()` parameter type from `SpawnOptions` to `AgentSpawnConfig`.
+- Update `spawnAndWait()` parameter type from `Omit<SpawnOptions, "isBackground">` to `Omit<AgentSpawnConfig, "isBackground">`.
+
+### `src/tools/agent-tool.ts`
+
+- Change import from `SpawnOptions` to `AgentSpawnConfig`.
+- Update `AgentToolManager.spawn` and `AgentToolManager.spawnAndWait` signatures.
+
+### `src/ui/agent-menu.ts`
+
+- Change import from `SpawnOptions` to `AgentSpawnConfig`.
+- Update `AgentMenuManager.spawnAndWait` signature.
+
+### `src/service.ts`
+
+- No changes — the public `SpawnOptions` stays as-is.
+
+### `src/service-adapter.ts`
+
+- No changes — it already uses `unknown` for the spawn options parameter in `AgentManagerLike`.
+
+### `test/agent-manager.test.ts`
+
+- No import changes needed — the test file does not import `SpawnOptions`.
+- One test description string mentions "SpawnOptions" → update to "AgentSpawnConfig" for accuracy.
+
+## Test Impact Analysis
+
+1. No new tests are enabled by this rename — it's a 1:1 name substitution.
+2. No existing tests become redundant.
+3. All existing tests stay as-is — they construct raw object literals that structurally satisfy the type regardless of its name.
+
+## TDD Order
+
+### Step 1: Rename `SpawnOptions` to `AgentSpawnConfig` and update all consumers
+
+1. Rename the interface in `agent-manager.ts`.
+2. Update `SpawnArgs`, `spawn()`, and `spawnAndWait()` in `agent-manager.ts`.
+3. Update the import and signatures in `tools/agent-tool.ts`.
+4. Update the import and signature in `ui/agent-menu.ts`.
+5. Update the test description string in `test/agent-manager.test.ts`.
+6. Run `pnpm run check` to verify types.
+7. Run `pnpm vitest run` to verify all tests pass.
+
+- Commit: `refactor: rename internal SpawnOptions to AgentSpawnConfig (#113)`
+
+This is a single-step refactor because the rename is mechanical and all consumers must be updated atomically for the type checker to stay green.
+
+## Risks and Mitigations
+
+| Risk                                                     | Mitigation                                                                                                                 |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| Missed consumer still references old name                | `pnpm run check` will catch any unresolved `SpawnOptions` import from `agent-manager.ts` since the export no longer exists |
+| Test descriptions become misleading                      | Grep for "SpawnOptions" in test files and update any description strings that reference the old name                       |
+| Confusion with `service.ts` `SpawnOptions` during review | The plan is scoped to internal-only changes; `service.ts` is explicitly listed as "no changes"                             |
+
+## Open Questions
+
+- None — the rename is unambiguous and aligns with both the issue proposal and the architecture doc.

package/docs/retro/0112-replace-agent-manager-callbacks.md

@@ -0,0 +1,35 @@
+---
+issue: 112
+issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
+---
+
+# Retro: #112 — replace AgentManager callbacks with observer interface
+
+## Final Retrospective (2026-05-21T21:00:00-04:00)
+
+### Session summary
+
+Replaced three fire-and-forget callback fields (`onStart`, `onComplete`, `onCompact`) on `AgentManagerOptions` with a single `AgentManagerObserver` interface.
+The refactoring touched `agent-manager.ts`, `index.ts`, and `agent-manager.test.ts` with zero test-count delta (652/652).
+Released as `pi-subagents-v6.8.2`.
+
+### Observations
+
+#### What went well
+
+- The issue description was thorough and unambiguous — no `ask_user` needed during planning, and the design mapped directly to implementation.
+- Self-identified the testing skill's single-call-site rule during execution: the plan split Steps 2 and 3 into separate commits, but `AgentManagerOptions` has one call site in `index.ts`, so both had to land together.
+  Merged them without rework.
+- Pre-existing lint issue (unused `ExecutionState` import in `agent-manager.ts`) caught and fixed proactively during the lint step.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` (self-identified) — The plan wrote TDD Steps 2 and 3 as separate commits, but the testing skill says "when a TDD step changes an interface that has a single call site, the step must include updating that call site."
+  The planning phase loaded the testing skill but didn't apply this specific rule when structuring the TDD order.
+  Impact: added friction but no rework — caught during execution when `pnpm run check` surfaced the expected type error in `index.ts` after Step 2.
+- `other` (tool interaction) — One `Edit` tool `oldText` match failure in `agent-manager.ts` because the selected block included a blank line that didn't exist between `subscribeRecordObserver` and `options.onSessionCreated`.
+  Impact: one extra read + edit cycle (~30 seconds).
+
+#### What caused friction (user side)
+
+- Nothing — the session ran without user corrections or redirections.

package/docs/retro/0123-remove-vi-fn-cast-smell.md

@@ -0,0 +1,49 @@
+---
+issue: 123
+issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
+---
+
+# Retro: #123 — remove vi.fn() cast smell from test helpers
+
+## Final Retrospective (2026-05-22T00:00:00Z)
+
+### Session summary
+
+Planned and implemented removal of all 9 `as ReturnType<typeof vi.fn>` casts and 5 `vi.mocked()` calls across 3 test files, replacing them with named typed mock variables.
+Released as `pi-subagents-v6.8.1`.
+Pure test hygiene — no production code changes, no behavioral changes, 652 tests unchanged.
+
+### Observations
+
+#### What went well
+
+- **Three-file scope executed cleanly once the plan was right.**
+  Each file was an independent commit with no cross-file dependencies.
+  The named-variable pattern (`const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>()`) worked identically across all three test files despite different mock construction styles (factory function vs `beforeEach` assignment).
+
+#### What caused friction (agent side)
+
+- `scope-drift` — The initial plan scoped the fix to `service-adapter.test.ts` only, listing `lifecycle.test.ts` and `tool-start.test.ts` as explicit Non-Goals — despite the planning-phase grep showing all 9 cast sites across 3 files.
+  The user redirected with "let's eliminate this pattern of behavior."
+  Updated the GitHub issue body, rewrote the plan, and amended the commit.
+  Impact: plan rewrite (~2 minutes), no implementation rework.
+  User-caught.
+- `missing-context` — Imported `MockInstance` from `vitest` during step 1 (`service-adapter.test.ts`) but actually used `ReturnType<typeof vi.fn<...>>` — matching the pattern used in the other two files.
+  The unused import was caught by `pnpm run lint` at the post-implementation check, not proactively.
+  Impact: one extra edit + amend cycle.
+  Self-identified (via lint).
+- `other` — Ran `git commit --amend` to fix the unused import but HEAD was step 3's commit (`tool-start`), not step 1's (`service-adapter`).
+  The amend landed the `service-adapter.test.ts` change into the wrong commit with the wrong message.
+  Required `git reset --soft` back to the plan commit and recommitting all 3 files.
+  Impact: ~1 minute of git surgery, clean result.
+  Self-identified.
+
+#### What caused friction (user side)
+
+- The issue body scoped the fix to `service-adapter.test.ts` only, which the agent followed literally.
+  The broader intent ("eliminate this pattern") was implicit.
+  Flagging the desired scope as "all files with this pattern" in the issue body would have avoided the plan rewrite.
+
+### Changes made
+
+1. Wrote retro file at `packages/pi-subagents/docs/retro/0123-remove-vi-fn-cast-smell.md`.

package/package.json

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

package/src/agent-manager.ts

@@ -13,7 +13,6 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
-import type { ExecutionState } from "./execution-state.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
@@ -21,11 +20,15 @@ import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, Subagen
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 
-export type OnAgentComplete = (record: AgentRecord) => void;
-export type OnAgentStart = (record: AgentRecord) => void;
-export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
+/** Observer interface for agent lifecycle notifications. */
+export interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+}
+
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
@@ -37,19 +40,17 @@ export interface AgentManagerOptions {
   /** Injected getter for the concurrency limit — owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
-  onStart?: OnAgentStart;
-  onComplete?: OnAgentComplete;
-  onCompact?: OnAgentCompact;
+  observer?: AgentManagerObserver;
 }
 
 interface SpawnArgs {
   snapshot: ParentSnapshot;
   type: SubagentType;
   prompt: string;
-  options: SpawnOptions;
+  options: AgentSpawnConfig;
 }
 
-export interface SpawnOptions {
+export interface AgentSpawnConfig {
   description: string;
   model?: Model<any>;
   maxTurns?: number;
@@ -80,9 +81,7 @@ export interface SpawnOptions {
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
-  private onComplete?: OnAgentComplete;
-  private onStart?: OnAgentStart;
-  private onCompact?: OnAgentCompact;
+  private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
   private readonly exec: ShellExec;
@@ -102,9 +101,7 @@ export class AgentManager {
     this.worktrees = options.worktrees;
     this.exec = options.exec;
     this.registry = options.registry;
-    this.onComplete = options.onComplete;
-    this.onStart = options.onStart;
-    this.onCompact = options.onCompact;
+    this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
@@ -141,7 +138,7 @@ export class AgentManager {
     ctx: ExtensionContext,
     type: SubagentType,
     prompt: string,
-    options: SpawnOptions,
+    options: AgentSpawnConfig,
   ): string {
     const id = randomUUID().slice(0, 17);
     const abortController = new AbortController();
@@ -196,7 +193,7 @@ export class AgentManager {
 
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
-    this.onStart?.(record);
+    this.observer?.onAgentStarted(record);
 
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined;
@@ -239,7 +236,7 @@ export class AgentManager {
         }
         // Subscribe record observer for stats accumulation
         unsubRecordObserver = subscribeRecordObserver(session, record, {
-          onCompact: (r, info) => this.onCompact?.(r, info),
+          onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
         });
         options.onSessionCreated?.(session);
       },
@@ -268,7 +265,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
+          try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
           this.drainQueue();
         }
         return responseText;
@@ -290,7 +287,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          this.onComplete?.(record);
+          this.observer?.onAgentCompleted(record);
           this.drainQueue();
         }
         return "";
@@ -311,7 +308,7 @@ export class AgentManager {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
         record.markError(err);
-        this.onComplete?.(record);
+        this.observer?.onAgentCompleted(record);
       }
     }
   }
@@ -324,7 +321,7 @@ export class AgentManager {
     ctx: ExtensionContext,
     type: SubagentType,
     prompt: string,
-    options: Omit<SpawnOptions, "isBackground">,
+    options: Omit<AgentSpawnConfig, "isBackground">,
   ): Promise<AgentRecord> {
     const id = this.spawn(ctx, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
@@ -347,7 +344,7 @@ export class AgentManager {
     record.resetForResume(Date.now());
 
     const unsubResume = subscribeRecordObserver(session, record, {
-      onCompact: (r, info) => this.onCompact?.(r, info),
+      onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
     });
 
     try {

package/src/index.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { AgentManager } from "./agent-manager.js";
+import { AgentManager, type AgentManagerObserver } from "./agent-manager.js";
 import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -64,14 +64,18 @@ export default function (pi: ExtensionAPI) {
   });
   settings.load();
 
-  // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager({
-    runner: { run: runAgent, resume: resumeAgent },
-    worktrees: new GitWorktreeManager(process.cwd()),
-    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
-    registry,
-    onComplete: (record) => {
-      // Emit lifecycle event based on terminal status
+  // Observer: receives agent lifecycle notifications and dispatches events/notifications.
+  const observer: AgentManagerObserver = {
+    onAgentStarted(record) {
+      // Emit started event when agent transitions to running (including from queue).
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onAgentCompleted(record) {
+      // Emit lifecycle event based on terminal status.
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
       const eventData = buildEventData(record);
       if (isError) {
@@ -80,14 +84,14 @@ export default function (pi: ExtensionAPI) {
         pi.events.emit("subagents:completed", eventData);
       }
 
-      // Persist final record for cross-extension history reconstruction
+      // Persist final record for cross-extension history reconstruction.
       pi.appendEntry("subagents:record", {
         id: record.id, type: record.type, description: record.description,
         status: record.status, result: record.result, error: record.error,
         startedAt: record.startedAt, completedAt: record.completedAt,
       });
 
-      // Skip notification if result was already consumed via get_subagent_result
+      // Skip notification if result was already consumed via get_subagent_result.
       if (record.notification?.resultConsumed) {
         notifications.cleanupCompleted(record.id);
         return;
@@ -95,15 +99,7 @@ export default function (pi: ExtensionAPI) {
 
       notifications.sendCompletion(record);
     },
-    onStart: (record) => {
-      // Emit started event when agent transitions to running (including from queue)
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    onCompact: (record, info) => {
+    onAgentCompacted(record, info) {
       // Emit compacted event when agent's session compacts (preserves count on record).
       pi.events.emit("subagents:compacted", {
         id: record.id,
@@ -114,6 +110,14 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
+  };
+
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    registry,
+    observer,
     getMaxConcurrent: () => settings.maxConcurrent,
     getRunConfig: () => settings,
   });

package/src/tools/agent-tool.ts

@@ -1,7 +1,7 @@
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
-import type { SpawnOptions } from "../agent-manager.js";
+import type { AgentSpawnConfig } from "../agent-manager.js";
 import { normalizeMaxTurns } from "../agent-runner.js";
 import { AgentTypeRegistry } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
@@ -75,8 +75,8 @@ export function buildDetails(
 
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
-  spawn: (ctx: ExtensionContext, type: string, prompt: string, opts: SpawnOptions) => string;
-  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
+  spawn: (ctx: ExtensionContext, type: string, prompt: string, opts: AgentSpawnConfig) => string;
+  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;

package/src/ui/agent-menu.ts

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { SpawnOptions } from "../agent-manager.js";
+import type { AgentSpawnConfig } from "../agent-manager.js";
 import {
   AgentTypeRegistry,
   BUILTIN_TOOL_NAMES,
@@ -19,7 +19,7 @@ export interface AgentMenuManager {
   listAgents: () => AgentRecord[];
   getRecord: (id: string) => AgentRecord | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
-  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
+  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
 }
 
 /** Narrow settings interface required by the agent menu. */