@gotgenes/pi-subagents 6.8.2 → 6.9.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.9.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.3...pi-subagents-v6.9.0) (2026-05-22)
+
+
+### Features
+
+* add onAgentCreated to AgentManagerObserver ([e2f1c12](https://github.com/gotgenes/pi-packages/commit/e2f1c1273ce560231cc98ef3c7e214efd2c20f47))
+
+
+### Documentation
+
+* mark D2 done, update field counts in architecture.md ([#114](https://github.com/gotgenes/pi-packages/issues/114)) ([702caf4](https://github.com/gotgenes/pi-packages/commit/702caf4187bfa015b0d80361b06b6360fddc31b1))
+* plan narrow AgentToolDeps and AgentMenuDeps ([#114](https://github.com/gotgenes/pi-packages/issues/114)) ([0f7e953](https://github.com/gotgenes/pi-packages/commit/0f7e95362043109c4113cfe3f7b848e296f118c9))
+* **retro:** add retro notes for issue [#113](https://github.com/gotgenes/pi-packages/issues/113) ([6b3c280](https://github.com/gotgenes/pi-packages/commit/6b3c2800e6d7728b8b620172e4acb1068b65e6c4))
+
+## [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)
 
 

package/docs/architecture/architecture.md

@@ -377,17 +377,17 @@ Each step is sequenced so it makes the next step easier.
 
 ### Current smells
 
-| Smell                          | Location                                 | Evidence                                                                                                                                                                  |
-| ------------------------------ | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ~~Global mutable state~~       | ~~`agent-types.ts`~~                     | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                 |
-| Closure bag as class           | `createNotificationSystem()`             | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                       |
-| ~~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`~~                | **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`        | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
-| 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                                                                                     |
+| Smell                          | Location                                     | Evidence                                                                                                                                                                          |
+| ------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ~~Global mutable state~~       | ~~`agent-types.ts`~~                         | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                         |
+| Closure bag as class           | `createNotificationSystem()`                 | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                               |
+| ~~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`~~                    | **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` (9), `AgentMenuDeps` (8)~~ | **Fixed #114**: `AgentToolDeps` 9 → 6; `AgentMenuDeps` 8 → 7; `emitEvent` removed from both; description text derived from registry; `agentActivity` narrowed to typed interfaces |
 
 ### Step A: Extract state into classes (foundation, parallel)
 
@@ -456,17 +456,23 @@ The record doesn't accumulate half-baked state — it receives fully constructed
 
 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) ✅
 
-#### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114)
+**Done.**
+`AgentToolDeps` 9 → 6: removed `emitEvent` (moved to `AgentManagerObserver.onAgentCreated`), `typeListText`, `availableTypesText` (derived inside `createAgentTool`); `agentActivity` narrowed to `AgentActivityAccess`.
+`AgentMenuDeps` 8 → 7: removed dead `emitEvent` field; `agentActivity` narrowed to `AgentActivityReader`.
+`buildTypeListText` extracted to `tools/helpers.ts`.
 
-| Bag             | Before    | After | How                                                                                                                    |
-| --------------- | --------- | ----- | ---------------------------------------------------------------------------------------------------------------------- |
-| `AgentToolDeps` | 9 fields  | ~5    | Registry owns reload; activity tracker is a collaborator; `emitEvent` moves to observer                                |
-| `AgentMenuDeps` | 13 fields | ~6    | Settings manager absorbs 6 fields (#109); apply methods remove `notifyConcurrencyChanged` (#118); registry owns reload |
+| Bag             | Before   | After | How                                                                                                           |
+| --------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------- |
+| `AgentToolDeps` | 9 fields | 6     | `emitEvent` → observer; `typeListText`/`availableTypesText` derived from registry; `agentActivity` narrowed   |
+| `AgentMenuDeps` | 8 fields | 7     | Dead `emitEvent` removed; `agentActivity` narrowed to read-only `AgentActivityReader`                         |
 
 ### Step E: Decompose large files and relocate types (parallel)
 
@@ -493,8 +499,8 @@ The 654-line file splits along a natural seam.
 | Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**)     | 0       |
 | Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**) | 0 ✓     |
 | `AgentManagerOptions` fields               | 8                                                                                | 5       |
-| `AgentToolDeps` fields                     | ~~9~~ **7** (−6 registry #108, −1 settings #109 → +1 settings obj)               | ~5      |
-| `AgentMenuDeps` fields                     | ~~13~~ **8** (−6 settings #109 collapsed to 1; −1 registry #108)                 | ~6 ✓    |
+| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed) | 6 ✓     |
+| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)        | 7 ✓     |
 | `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                           | 0       |
 | Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain     | 0       |
 | Types in `types.ts` without a natural home | 4                                                                                | 0       |

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/plans/0114-narrow-agent-tool-menu-deps.md

@@ -0,0 +1,279 @@
+---
+issue: 114
+issue_title: "refactor(pi-subagents): narrow AgentToolDeps and AgentMenuDeps"
+---
+
+# Narrow AgentToolDeps and AgentMenuDeps
+
+## Problem Statement
+
+With the foundational extractions complete — `AgentTypeRegistry` (#108), `SettingsManager` (#109), `AgentActivityTracker` (#110), and `AgentManagerObserver` (#112) — the two widest dependency bags in the extension still carry fields that belong on their collaborators.
+
+`AgentToolDeps` has 9 fields: 3 are description-text strings derivable from the registry, 1 is a raw `emitEvent` callback that the observer should own, and the `agentActivity` Map is passed as raw mutable state.
+`AgentMenuDeps` has 8 fields: `emitEvent` is defined but never referenced in the module (dead field).
+
+Each excess field inflates test mock construction and obscures the real dependency surface.
+
+## Goals
+
+- Remove `emitEvent` from both `AgentToolDeps` and `AgentMenuDeps`.
+- Remove `typeListText` and `availableTypesText` from `AgentToolDeps` — derive them from `registry` inside `createAgentTool`.
+- Add `onAgentCreated` to `AgentManagerObserver` so the `subagents:created` event is emitted by the observer, not the tool.
+- Narrow `agentActivity` in both interfaces to a typed read/write interface instead of raw `Map`.
+- Final counts: `AgentToolDeps` 9 → 6, `AgentMenuDeps` 8 → 7.
+
+## Non-Goals
+
+- Removing `agentDir` from `AgentToolDeps` — it is not derivable from the registry (it comes from the Pi SDK's `getAgentDir()`).
+- Adding presentation methods to `AgentTypeRegistry` — that would mix SRP concerns.
+- Splitting `agent-tool.ts` foreground/background (tracked in #115).
+- Removing `personalAgentsDir` / `projectAgentsDir` from `AgentMenuDeps` — they are genuine menu-level concerns (file management UI).
+
+## Background
+
+### Prerequisite status
+
+All prerequisites are implemented and merged:
+
+| Issue | Title                                          | Status  |
+| ----- | ---------------------------------------------- | ------- |
+| #108  | Extract `AgentTypeRegistry`                    | ✅ Done |
+| #109  | Extract `SettingsManager`                      | ✅ Done |
+| #110  | `AgentActivityTracker`                         | ✅ Done |
+| #112  | Replace `AgentManager` callbacks with observer | ✅ Done |
+| #113  | Disambiguate `SpawnOptions`                    | ✅ Done |
+| #118  | `SettingsManager` apply methods                | ✅ Done |
+
+### Current interfaces
+
+```typescript
+// tools/agent-tool.ts — 9 fields
+interface AgentToolDeps {
+  manager: AgentToolManager;
+  widget: AgentToolWidget;
+  agentActivity: Map<string, AgentActivityTracker>;
+  emitEvent: (name: string, data: unknown) => void;
+  registry: AgentTypeRegistry;
+  typeListText: string;
+  availableTypesText: string;
+  agentDir: string;
+  settings: { readonly defaultMaxTurns: number | undefined };
+}
+
+// ui/agent-menu.ts — 8 fields
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: Map<string, AgentActivityTracker>;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  emitEvent: (name: string, data: unknown) => void;   // ← dead field
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+### Relevant design principles
+
+- **Dependency width** (code-design skill): do not pass a shared bag to functions that only use a subset.
+- **Output arguments**: `agentActivity` is a raw `Map` mutated via `.set()` and `.delete()` — encapsulate behind methods.
+- **ISP**: consumers should depend on the narrowest interface they need.
+
+## Design Overview
+
+### 1. Move `subagents:created` to observer
+
+The `AgentManagerObserver` interface gains an `onAgentCreated` method.
+`AgentManager.spawn()` calls `observer.onAgentCreated(record)` after creating the record.
+The observer implementation in `index.ts` emits `pi.events.emit("subagents:created", ...)`.
+The tool no longer calls `deps.emitEvent(...)`.
+
+The event payload includes `id`, `type`, `description`, and `isBackground`.
+Since `isBackground` is known at spawn-time (it's part of the spawn config), the observer has all needed data.
+
+```typescript
+interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+  onAgentCreated(record: AgentRecord): void;  // ← new
+}
+```
+
+### 2. Derive description text from registry
+
+Move `buildTypeListText()` from `index.ts` to `tools/helpers.ts` as a pure function that accepts the registry and `agentDir`:
+
+```typescript
+function buildTypeListText(
+  registry: AgentConfigLookup & { getDefaultAgentNames(): string[]; getUserAgentNames(): string[] },
+  agentDir: string,
+): string;
+```
+
+Inside `createAgentTool`, compute both strings from `deps.registry` and `deps.agentDir`:
+
+```typescript
+const typeListText = buildTypeListText(deps.registry, deps.agentDir);
+const availableTypesText = deps.registry.getAvailableTypes().join(", ");
+```
+
+This removes `typeListText` and `availableTypesText` from the interface.
+The helper requires `getModelLabelFromConfig`, which already lives in `tools/helpers.ts`.
+
+### 3. Narrow agentActivity to a typed interface
+
+Instead of `Map<string, AgentActivityTracker>`, both interfaces accept a narrow typed interface matching their actual usage:
+
+```typescript
+/** Read/write interface for agent-tool's activity tracking needs. */
+interface AgentActivityAccess {
+  get(id: string): AgentActivityTracker | undefined;
+  set(id: string, tracker: AgentActivityTracker): void;
+  delete(id: string): void;
+}
+```
+
+The `AgentMenuDeps` only reads (`.get()`), so it gets a narrower read-only type:
+
+```typescript
+/** Read-only interface for menu's conversation viewer. */
+interface AgentActivityReader {
+  get(id: string): AgentActivityTracker | undefined;
+}
+```
+
+The runtime's `Map<string, AgentActivityTracker>` satisfies both interfaces structurally.
+No wrapper class is needed — `Map` already implements `get/set/delete`.
+The benefit is that the type signature communicates the actual usage pattern.
+
+### 4. Remove dead `emitEvent` from `AgentMenuDeps`
+
+This field is defined in the interface but never referenced inside `agent-menu.ts`.
+Remove it from the interface and from the construction site in `index.ts`.
+
+### Final interfaces
+
+```typescript
+// tools/agent-tool.ts — 6 fields (was 9)
+interface AgentToolDeps {
+  manager: AgentToolManager;
+  widget: AgentToolWidget;
+  agentActivity: AgentActivityAccess;
+  registry: AgentTypeRegistry;
+  agentDir: string;
+  settings: { readonly defaultMaxTurns: number | undefined };
+}
+
+// ui/agent-menu.ts — 7 fields (was 8)
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: AgentActivityReader;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/agent-manager.ts`** — Call `observer.onAgentCreated(record)` in `spawn()` after creating the record.
+   Update `AgentManagerObserver` interface to include `onAgentCreated`.
+
+2. **`src/tools/agent-tool.ts`** — Remove `emitEvent`, `typeListText`, `availableTypesText` from `AgentToolDeps`.
+   Add `AgentActivityAccess` interface.
+   Derive description text from `registry` + `agentDir` inside `createAgentTool`.
+   Remove `deps.emitEvent(...)` call.
+   Replace `Map<string, AgentActivityTracker>` with `AgentActivityAccess`.
+
+3. **`src/tools/helpers.ts`** — Add `buildTypeListText(registry, agentDir)` extracted from `index.ts`.
+
+4. **`src/ui/agent-menu.ts`** — Remove `emitEvent` from `AgentMenuDeps`.
+   Add `AgentActivityReader` interface.
+   Replace `Map<string, AgentActivityTracker>` with `AgentActivityReader`.
+
+5. **`src/index.ts`** — Remove `buildTypeListText` closure.
+   Remove `typeListText`, `availableTypesText`, `emitEvent` from the `AgentToolDeps` construction.
+   Remove `emitEvent` from the `AgentMenuDeps` construction.
+   Add `onAgentCreated` to the observer object.
+
+6. **`test/tools/agent-tool.test.ts`** — Update `makeDeps` factory: remove `emitEvent`, `typeListText`, `availableTypesText`.
+   Update assertions that check `emitEvent` was called.
+
+7. **`test/ui/agent-menu.test.ts`** — Update `makeDeps` factory: remove `emitEvent`.
+
+8. **`test/agent-manager.test.ts`** — Add test for `observer.onAgentCreated` being called during spawn.
+
+## Test Impact Analysis
+
+1. **New tests enabled**: `observer.onAgentCreated` can be tested in `agent-manager.test.ts` — verify it fires during `spawn()` with the correct record.
+
+2. **Tests that simplify**: `agent-tool.test.ts` mock factory drops 3 fields (`emitEvent`, `typeListText`, `availableTypesText`).
+   Tests asserting `deps.emitEvent` was called become assertions that the observer was invoked (tested at the manager level instead).
+   `agent-menu.test.ts` mock factory drops 1 field (`emitEvent`).
+
+3. **Tests that stay**: all tool-behavior tests (spawn paths, resume, error handling) remain — they test the tool's own logic, not the narrowed plumbing.
+
+## TDD Order
+
+1. **Add `onAgentCreated` to observer interface and manager.**
+   Add the method to `AgentManagerObserver`.
+   Call it in `AgentManager.spawn()`.
+   Test: verify `observer.onAgentCreated` fires with the created record.
+   Commit: `feat: add onAgentCreated to AgentManagerObserver`
+
+2. **Extract `buildTypeListText` to helpers.**
+   Move the function from `index.ts` to `tools/helpers.ts` as a pure function.
+   Test: unit test `buildTypeListText` with a mock registry.
+   Update `index.ts` to import and call the extracted helper.
+   Commit: `refactor: extract buildTypeListText to tools/helpers`
+
+3. **Derive description text inside `createAgentTool`.**
+   Remove `typeListText` and `availableTypesText` from `AgentToolDeps`.
+   Compute them from `deps.registry` + `deps.agentDir` inside `createAgentTool`.
+   Update `index.ts` construction site.
+   Update `agent-tool.test.ts` mock factory.
+   Test: verify tool description still contains expected text.
+   Commit: `refactor: derive description text from registry in createAgentTool`
+
+4. **Remove `emitEvent` from `AgentToolDeps`.**
+   Remove the field from the interface.
+   Remove the `deps.emitEvent(...)` call in the background spawn path.
+   Wire `onAgentCreated` in the `index.ts` observer to emit `subagents:created`.
+   Update `agent-tool.test.ts` (remove `emitEvent` from factory, remove/update related assertions).
+   Commit: `refactor: remove emitEvent from AgentToolDeps`
+
+5. **Remove dead `emitEvent` from `AgentMenuDeps`.**
+   Remove the field from the interface.
+   Remove from `index.ts` construction site.
+   Update `agent-menu.test.ts` mock factory.
+   Commit: `refactor: remove dead emitEvent from AgentMenuDeps`
+
+6. **Narrow `agentActivity` to typed interfaces.**
+   Add `AgentActivityAccess` interface to `agent-tool.ts`.
+   Add `AgentActivityReader` interface to `agent-menu.ts`.
+   Replace `Map<string, AgentActivityTracker>` with the narrow type in both interfaces.
+   Update test factories (no functional change — `Map` satisfies both interfaces).
+   Commit: `refactor: narrow agentActivity to typed interfaces`
+
+## Risks and Mitigations
+
+| Risk                                                                                    | Mitigation                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagents:created` event data changes shape when moved to observer                     | Observer receives the full `AgentRecord` which contains `id`, `type`, `description`. `isBackground` must be derivable from the record or spawn config — verify the record carries this at spawn time. |
+| `buildTypeListText` depends on `getModelLabelFromConfig` which is in `tools/helpers.ts` | This is already the target file — no circular dependency risk.                                                                                                                                        |
+| Third-party consumers rely on `emitEvent` presence in `AgentToolDeps`                   | `AgentToolDeps` is not in the public `exports` — it's internal. No external API breakage.                                                                                                             |
+| `AgentActivityAccess` interface is structurally identical to a subset of `Map`          | This is intentional — the `Map` satisfies it without a wrapper. If a non-Map implementation is needed later, the interface is already in place.                                                       |
+
+## Open Questions
+
+1. Should `onAgentCreated` receive the full `AgentRecord` or a narrow payload?
+   The other observer methods receive `AgentRecord` — consistency suggests the same.
+   The `isBackground` flag is needed for the event payload; verify it's available on the record at creation time (it should be, since background is set at spawn).
+2. Should `steer-tool.ts`'s `emitEvent` (emits `subagents:steered`) also move to the observer?
+   It's a separate concern (tool-level steering) and a different event.
+   Defer to a follow-up if desired.

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/0113-disambiguate-spawn-options.md

@@ -0,0 +1,29 @@
+---
+issue: 113
+issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
+---
+
+# Retro: #113 — disambiguate SpawnOptions (public vs internal)
+
+## Final Retrospective (2026-05-21T21:10:00-04:00)
+
+### Session summary
+
+Renamed the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig` to disambiguate it from the public `SpawnOptions` in `service.ts`.
+Pure mechanical rename across 4 files with zero test-count delta (652/652).
+Released as `pi-subagents-v6.8.3`.
+
+### Observations
+
+#### What went well
+
+- Completely frictionless execution — single-step plan executed exactly as written with no corrections, rework, or failed edits.
+- The session benefited from context already loaded during the preceding #112 cycle (same package, same skills, same source files), which made planning and execution faster.
+
+#### What caused friction (agent side)
+
+- Nothing — the rename was purely mechanical and the plan matched reality exactly.
+
+#### What caused friction (user side)
+
+- Nothing — no user intervention needed.

package/package.json

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

package/src/agent-manager.ts

@@ -27,6 +27,8 @@ export interface AgentManagerObserver {
   onAgentStarted(record: AgentRecord): void;
   onAgentCompleted(record: AgentRecord): void;
   onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+  /** Fires synchronously after a background agent record is created (before startAgent). */
+  onAgentCreated(record: AgentRecord): void;
 }
 
 /** Default max concurrent background agents. */
@@ -47,10 +49,10 @@ 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;
@@ -138,7 +140,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();
@@ -153,6 +155,10 @@ export class AgentManager {
     });
     this.agents.set(id, record);
 
+    if (options.isBackground) {
+      this.observer?.onAgentCreated(record);
+    }
+
     const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
@@ -321,7 +327,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)!;

package/src/index.ts

@@ -110,6 +110,15 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
+    onAgentCreated(record) {
+      // Emit created event for background agents (before startAgent / queue drain).
+      pi.events.emit("subagents:created", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        isBackground: true,
+      });
+    },
   };
 
   const manager = new AgentManager({
@@ -151,33 +160,6 @@ export default function (pi: ExtensionAPI) {
   const toolStart = new ToolStartHandler(runtime);
   pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
-  /** Build the full type list text dynamically from the unified registry. */
-  const buildTypeListText = () => {
-    const defaultNames = registry.getDefaultAgentNames();
-    const userNames = registry.getUserAgentNames();
-
-    const defaultDescs = defaultNames.map((name) => {
-      const cfg = registry.resolveAgentConfig(name);
-      const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-      return `- ${name}: ${cfg.description}${modelSuffix}`;
-    });
-
-    const customDescs = userNames.map((name) => {
-      const cfg = registry.resolveAgentConfig(name);
-      return `- ${name}: ${cfg.description}`;
-    });
-
-    return [
-      "Default agents:",
-      ...defaultDescs,
-      ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
-      "",
-      `Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
-    ].join("\n");
-  };
-
-  const typeListText = buildTypeListText();
-
   // ---- Agent tool ----
 
   pi.registerTool(defineTool(createAgentTool({
@@ -196,10 +178,7 @@ export default function (pi: ExtensionAPI) {
       markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,
-    emitEvent: (name, data) => pi.events.emit(name, data),
     registry,
-    typeListText,
-    availableTypesText: registry.getAvailableTypes().join(", "),
     agentDir: getAgentDir(),
     settings,
   })));
@@ -242,7 +221,6 @@ export default function (pi: ExtensionAPI) {
       return getModelLabelFromConfig(cfg.model);
     },
     settings,
-    emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });

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";
@@ -23,7 +23,7 @@ import {
 } from "../ui/agent-widget.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { LifetimeUsage } from "../usage.js";
-import { formatLifetimeTokens, textResult } from "./helpers.js";
+import { buildTypeListText, formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
@@ -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;
@@ -91,14 +91,21 @@ export interface AgentToolWidget {
   markFinished: (id: string) => void;
 }
 
+/**
+ * Narrow read/write interface for the agent-tool's agentActivity access.
+ * The full Map satisfies this structurally — no wrapper needed.
+ */
+export interface AgentActivityAccess {
+  get(id: string): AgentActivityTracker | undefined;
+  set(id: string, tracker: AgentActivityTracker): void;
+  delete(id: string): void;
+}
+
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivityTracker>;
-  emitEvent: (name: string, data: unknown) => void;
+  agentActivity: AgentActivityAccess;
   registry: AgentTypeRegistry;
-  typeListText: string;
-  availableTypesText: string;
   agentDir: string;
   /** Narrow settings accessor — only the default max turns is needed here. */
   settings: { readonly defaultMaxTurns: number | undefined };
@@ -108,6 +115,8 @@ export interface AgentToolDeps {
 
 /** Create the Agent tool definition (without Pi SDK wrapper). */
 export function createAgentTool(deps: AgentToolDeps) {
+  const typeListText = buildTypeListText(deps.registry, deps.agentDir);
+  const availableTypesText = deps.registry.getAvailableTypes().join(", ");
   return {
     name: "Agent" as const,
     label: "Agent",
@@ -116,7 +125,7 @@ export function createAgentTool(deps: AgentToolDeps) {
 The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
 Available agent types:
-${deps.typeListText}
+${typeListText}
 
 Guidelines:
 - For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
@@ -140,7 +149,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${deps.availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
+        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -439,14 +448,6 @@ Guidelines:
         deps.widget.ensureTimer();
         deps.widget.update();
 
-        // Emit created event
-        deps.emitEvent("subagents:created", {
-          id,
-          type: subagentType,
-          description: params.description,
-          isBackground: true,
-        });
-
         const isQueued = record?.status === "queued";
         return textResult(
           `Agent ${isQueued ? "queued" : "started"} in background.\n` +

package/src/tools/helpers.ts

@@ -1,3 +1,4 @@
+import type { AgentConfigLookup } from "../agent-types.js";
 import { formatTokens } from "../ui/agent-widget.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
@@ -12,6 +13,43 @@ export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): strin
   return t > 0 ? formatTokens(t) : "";
 }
 
+/**
+ * Narrow registry interface needed by buildTypeListText.
+ * Extends AgentConfigLookup with the two name-listing methods.
+ */
+export interface TypeListRegistry extends AgentConfigLookup {
+  getDefaultAgentNames(): string[];
+  getUserAgentNames(): string[];
+}
+
+/**
+ * Build the full agent-type list text for the Agent tool description.
+ * Extracted from index.ts so it can be called inside createAgentTool.
+ */
+export function buildTypeListText(registry: TypeListRegistry, agentDir: string): string {
+  const defaultNames = registry.getDefaultAgentNames();
+  const userNames = registry.getUserAgentNames();
+
+  const defaultDescs = defaultNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+    return `- ${name}: ${cfg.description}${modelSuffix}`;
+  });
+
+  const customDescs = userNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    return `- ${name}: ${cfg.description}`;
+  });
+
+  return [
+    "Default agents:",
+    ...defaultDescs,
+    ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+    "",
+    `Custom agents can be defined in .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
+  ].join("\n");
+}
+
 /** Derive a short model label from a model string. */
 export function getModelLabelFromConfig(model: string): string {
   // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")

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. */
@@ -32,15 +32,22 @@ export interface AgentMenuSettings {
   applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
 }
 
+/**
+ * Read-only interface for the agent-menu's agentActivity access.
+ * Only the conversation viewer needs to read a tracker by agent ID.
+ */
+export interface AgentActivityReader {
+  get(id: string): AgentActivityTracker | undefined;
+}
+
 export interface AgentMenuDeps {
   manager: AgentMenuManager;
   registry: AgentTypeRegistry;
-  agentActivity: Map<string, AgentActivityTracker>;
+  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;
-  emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
   projectAgentsDir: string;
 }