@gotgenes/pi-subagents 6.8.2 → 6.8.3

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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)
 
 

package/docs/architecture/architecture.md

@@ -385,7 +385,7 @@ Each step is sequenced so it makes the next step easier.
 | ~~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                                                                                               |
+| ~~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                                                                                     |
 
@@ -456,10 +456,11 @@ 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)
 

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/package.json

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

package/src/agent-manager.ts

@@ -47,10 +47,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 +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();
@@ -321,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)!;

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. */