@gotgenes/pi-subagents 7.2.0 → 7.2.1

package/CHANGELOG.md

@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.0...pi-subagents-v7.2.1) (2026-05-25)
+
+
+### Documentation
+
+* mark Layer 2 done and update health metrics in architecture doc ([ad00426](https://github.com/gotgenes/pi-packages/commit/ad00426f0f29ceff0915033419fdc2f1b53755b0))
+* plan align tool interfaces for structural typing ([#194](https://github.com/gotgenes/pi-packages/issues/194)) ([36e56b0](https://github.com/gotgenes/pi-packages/commit/36e56b08351893e3c2d63569e7cfa140c172e20b))
+* **retro:** add planning stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([63a5763](https://github.com/gotgenes/pi-packages/commit/63a5763ed2bf4c2a6e2e9a19fdcdce71a2a9905a))
+* **retro:** add retro notes for issue [#193](https://github.com/gotgenes/pi-packages/issues/193) ([8987f90](https://github.com/gotgenes/pi-packages/commit/8987f907e00bb70429782c947a2afbdb1db5faa9))
+* **retro:** add TDD stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([f692323](https://github.com/gotgenes/pi-packages/commit/f69232395882c07d6d95273e08021b94800f0e43))
+
 ## [7.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.1.0...pi-subagents-v7.2.0) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -608,16 +608,16 @@ The approach is layered: each step makes the next step trivial.
 
 ### Findings
 
-| Metric                    | Value                                   |
-| ------------------------- | --------------------------------------- |
-| Health score              | 75/100 (B)                              |
-| #1 hotspot                | `index.ts` (128 commits, accelerating)  |
-| Dead exports              | 1 (`getToolCallName` re-export)         |
-| Production duplication    | 0                                       |
-| Test duplication          | 1,396 lines (69 clone groups, 22 files) |
-| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)     |
-| Adapter closures in index | 41 (down from 44; Layer 1 resolved 3)   |
-| Index fan-out             | 25 imports                              |
+| Metric                    | Value                                      |
+| ------------------------- | ------------------------------------------ |
+| Health score              | 75/100 (B)                                 |
+| #1 hotspot                | `index.ts` (128 commits, accelerating)     |
+| Dead exports              | 0 (down from 1; Layer 2 removed re-export) |
+| Production duplication    | 0                                          |
+| Test duplication          | 1,396 lines (69 clone groups, 22 files)    |
+| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)        |
+| Adapter closures in index | 40 (down from 44; Layers 1–2 resolved 4)   |
+| Index fan-out             | 25 imports                                 |
 
 ### Root cause
 
@@ -628,8 +628,10 @@ The real objects can't satisfy the interfaces because:
    Resolved by Layer 0 (#192) + Layer 1 (#193).
 2. ~~Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.~~
    Resolved by Layer 1 (#193).
-3. `AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).
-4. `AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).
+3. ~~`AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).~~
+   Resolved by Layer 2 (#194).
+4. ~~`AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).~~
+   Resolved by Layer 2 (#194).
 
 Fix these structural misalignments and the class conversions become mechanical.
 
@@ -668,7 +670,7 @@ Add typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessio
 - Outcome: 3 closure queries in index.ts → 0; `SubagentRuntime` is self-sufficient for tool deps
 - Enables: Layer 3 (tools accept `SubagentRuntime` directly)
 
-### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194])
+### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194]) ✓ done
 
 Three alignment changes:
 
@@ -681,7 +683,7 @@ After this step, `AgentManager` structurally satisfies `AgentToolManager` and `S
 
 - Target: `src/tools/agent-tool.ts` (interface), `src/runtime.ts` (method names), `src/ui/message-formatters.ts`
 - Smell: Category C (source mismatch, name mismatch) + Category A (dead export)
-- Outcome: structural typing connects real objects to tool interfaces without adapters
+- Outcome: structural typing connects real objects to tool interfaces without adapters; 0 dead exports (fallow clean)
 - Enables: Layer 3 (class constructors accept real objects directly)
 
 ### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])

package/docs/plans/0194-align-tool-interfaces-for-structural-typing.md

@@ -0,0 +1,139 @@
+---
+issue: 194
+issue_title: "Align tool interfaces for structural typing"
+---
+
+# Align tool interfaces for structural typing
+
+## Problem Statement
+
+The narrow interfaces that tool factories accept don't structurally match the real objects (`AgentManager`, `SubagentRuntime`, `SettingsManager`).
+This forces `index.ts` to build adapter closures bridging the gap — each a one-liner that exists only because names or ownership don't align.
+Three specific mismatches prevent structural typing from connecting real objects to tool interfaces directly.
+
+## Goals
+
+- Remove `getMaxConcurrent()` from `AgentToolManager` — it belongs on the settings accessor.
+- Rename `SubagentRuntime.updateWidget()` → `update()` so `SubagentRuntime` structurally satisfies `AgentToolWidget`.
+- Remove the dead `getToolCallName` re-export from `ui/message-formatters.ts`.
+- After these changes, `AgentManager` structurally satisfies `AgentToolManager` and `SubagentRuntime` structurally satisfies `AgentToolWidget` — no adapter closures needed in `index.ts`.
+
+## Non-Goals
+
+- Converting tool factories to classes (that's #195).
+- Simplifying `index.ts` wiring (that's #195/#196, after this layer).
+- Changing `NotificationManager`'s constructor parameter name (`updateWidget` callback) — it's a positional callback, not a structural interface member.
+
+## Background
+
+This is Phase 11, Layer 2 in `docs/architecture/architecture.md`.
+Layer 0 (#192, done) and Layer 1 (#193, done) established the typed `SessionContext` and moved context queries onto `SubagentRuntime`.
+Layer 2 (this issue) aligns the remaining structural mismatches.
+Layer 3 (#195) depends on this layer.
+
+Relevant modules:
+
+- `src/tools/agent-tool.ts` — defines `AgentToolManager` and `AgentToolWidget` interfaces.
+- `src/tools/background-spawner.ts` — defines `BackgroundManagerDeps` with `getMaxConcurrent()`.
+- `src/runtime.ts` — defines `SubagentRuntime` class with `updateWidget()` delegation method.
+- `src/ui/message-formatters.ts` — has the dead `getToolCallName` re-export.
+- `src/index.ts` — composition root that builds adapter closures.
+- `src/settings.ts` — `SettingsManager` owns `maxConcurrent`.
+
+## Design Overview
+
+### 1. Move `getMaxConcurrent` off manager interfaces → settings
+
+The `BackgroundManagerDeps` and `AgentToolManager` interfaces both declare `getMaxConcurrent(): number`.
+In reality, the value comes from `SettingsManager.maxConcurrent`.
+The fix:
+
+- Remove `getMaxConcurrent` from `AgentToolManager`.
+- Remove `getMaxConcurrent` from `BackgroundManagerDeps`.
+- Widen `AgentToolDeps.settings` from `{ readonly defaultMaxTurns: number | undefined }` to also include `readonly maxConcurrent: number`.
+- Pass `settings` (or a narrow settings interface) to `spawnBackground` so it can read `maxConcurrent` directly.
+- `SettingsManager` already exposes a `get maxConcurrent(): number` property, so it structurally satisfies the widened interface.
+
+After this, `AgentManager` (which has `spawn`, `spawnAndWait`, `resume`, `getRecord` but NOT `getMaxConcurrent`) structurally satisfies `AgentToolManager`.
+
+### 2. Rename `SubagentRuntime.updateWidget()` → `update()`
+
+The `AgentToolWidget` interface declares `update(): void`.
+`SubagentRuntime` has `updateWidget(): void` which delegates to `this.widget?.update()`.
+Renaming the delegation method to `update()` makes `SubagentRuntime` structurally satisfy `AgentToolWidget` (it already has `setUICtx`, `ensureTimer`, and `markFinished`).
+
+Callers of `runtime.updateWidget()`:
+
+- `src/index.ts` line 70: `() => runtime.updateWidget()` → `() => runtime.update()`
+- `src/index.ts` line 199: `update: () => runtime.updateWidget()` → can now pass `runtime` directly (but that's a #195 concern — for now just rename the call).
+
+The `WidgetLike` interface in `runtime.ts` already uses `update()` — no conflict.
+
+### 3. Remove dead re-export
+
+`src/ui/message-formatters.ts` line 24 exports `getToolCallName` from `#src/session/content-items`.
+No consumer imports `getToolCallName` from `message-formatters` — all uses go directly to `content-items.ts`.
+Delete the re-export line.
+
+### After all three changes
+
+```typescript
+// AgentToolManager (after removing getMaxConcurrent):
+interface AgentToolManager {
+  spawn(...): string;
+  spawnAndWait(...): Promise<AgentRecord>;
+  resume(...): Promise<AgentRecord | undefined>;
+  getRecord(id: string): AgentRecord | undefined;
+}
+// AgentManager has all four methods → structural match ✓
+
+// AgentToolWidget (unchanged):
+interface AgentToolWidget {
+  setUICtx(ctx: unknown): void;
+  ensureTimer(): void;
+  update(): void;
+  markFinished(id: string): void;
+}
+// SubagentRuntime has all four methods (after rename) → structural match ✓
+```
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                                                                                                            |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/agent-tool.ts`               | Remove `getMaxConcurrent` from `AgentToolManager`. Widen `settings` type in `AgentToolDeps` to include `readonly maxConcurrent: number`.                                                                                          |
+| `src/tools/background-spawner.ts`       | Remove `getMaxConcurrent` from `BackgroundManagerDeps`. Add a `settings: { readonly maxConcurrent: number }` parameter (or add to `BackgroundParams`). Read `settings.maxConcurrent` instead of `manager.getMaxConcurrent()`.     |
+| `src/runtime.ts`                        | Rename `updateWidget()` → `update()`.                                                                                                                                                                                             |
+| `src/ui/message-formatters.ts`          | Remove the `export { getToolCallName } from ...` line.                                                                                                                                                                            |
+| `src/index.ts`                          | Update `runtime.updateWidget()` → `runtime.update()` at both call sites. Remove `getMaxConcurrent` from the `manager` adapter object passed to `createAgentTool`. Pass `settings` through to `spawnBackground` via the tool deps. |
+| `test/tools/background-spawner.test.ts` | Remove `getMaxConcurrent` from mock manager objects. Add `settings` mock with `maxConcurrent`.                                                                                                                                    |
+| `test/runtime.test.ts`                  | Rename `updateWidget` → `update` in test descriptions and call sites.                                                                                                                                                             |
+| `docs/architecture/architecture.md`     | Update Layer 2 status and health metrics (adapter closures count, dead exports count).                                                                                                                                            |
+
+## Test Impact Analysis
+
+1. No new unit tests are strictly needed — this is interface alignment, not new behavior.
+2. `test/tools/background-spawner.test.ts` needs mock shape updates (remove `getMaxConcurrent` from manager mock, add settings mock).
+3. `test/runtime.test.ts` needs the method name updated from `updateWidget` to `update`.
+4. Existing tests for `agent-tool`, `notification`, and `message-formatters` remain as-is (no behavior change).
+
+## TDD Order
+
+1. `refactor:` Rename `SubagentRuntime.updateWidget()` → `update()` — update `runtime.ts`, `test/runtime.test.ts`, and both call sites in `index.ts`.
+   Run `pnpm run check` to verify no type errors remain.
+2. `refactor:` Move `getMaxConcurrent` off manager interfaces — remove from `AgentToolManager` and `BackgroundManagerDeps`, widen `AgentToolDeps.settings`, add settings parameter to `spawnBackground`, update `index.ts` call site and `test/tools/background-spawner.test.ts`.
+   Run `pnpm run check`.
+3. `refactor:` Remove dead `getToolCallName` re-export from `ui/message-formatters.ts`.
+4. `docs:` Update architecture doc — mark Layer 2 as done, update health metrics (dead exports: 0, adapter closures reduced).
+
+## Risks and Mitigations
+
+| Risk                                                                                                 | Mitigation                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update()` is a generic name on `SubagentRuntime` — could confuse readers about what's being updated | The method is a documented widget delegation like its siblings (`markFinished`, `ensureTimer`); the JSDoc comment clarifies it delegates to `widget.update()`. |
+| `background-spawner` signature change could break other callers                                      | Grep confirms only `agent-tool.ts` calls `spawnBackground` — no other consumers.                                                                               |
+| Renaming method in runtime could miss a call site                                                    | Grep and `pnpm run check` after each step catch all references.                                                                                                |
+
+## Open Questions
+
+None — the issue's proposed direction is unambiguous and the architecture doc confirms the design.

package/docs/retro/0193-runtime-owns-context-queries.md

@@ -41,3 +41,35 @@ This is cleaner than the plan's `getModelInfo(): { modelRegistry: unknown }` app
 - Biome's `noUnusedPrivateClassMembers` warning caught the leftover `private readonly pi: unknown` in `SessionLifecycleHandler`.
 Removed `pi` from the constructor entirely (rather than adding `_` prefix), which also cleaned up `index.ts`.
 - The `eslint-disable` directive at the top of `index.ts` had two now-unused entries (`no-unsafe-member-access`, `no-unsafe-call`) removed by `eslint --fix`.
+
+## Stage: Final Retrospective (2026-05-24T20:45:00Z)
+
+### Session summary
+
+All three stages (plan, TDD, ship) completed in a single session.
+Released as `pi-subagents-v7.2.0`.
+One plan contradiction required a judgment call during implementation; otherwise clean mechanical execution.
+
+### Observations
+
+#### What went well
+
+- The architecture doc's Phase 11 Layer 1 spec was precise enough that no `ask_user` was needed at any stage — the issue body, architecture doc, and #192 retro were fully aligned.
+- `ServiceRuntimeLike` ended up simpler than planned (only `currentCtx` + `buildSnapshot` instead of also requiring `getModelInfo()`) — the implementation found a cleaner design than the plan specified.
+- Test count increase (+6) validates the design: methods that were previously untestable as anonymous closures now have dedicated unit tests.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's Non-Goals section claimed `buildParentContext` would not change, contradicting Module-Level Changes item #4 which explicitly listed the file.
+  The planning stage didn't cross-check these sections before committing.
+  Impact: brief confusion during step 3 about which section to trust (resolved by following Module-Level Changes); no rework, added ~30s of deliberation.
+- `missing-context` — TypeScript's discriminated union narrowing limitation with a `{ type: string }` catch-all arm was not anticipated.
+  Impact: required adding a local `BranchEntry` union type and explicit casts in `context.ts`; no rework but ~2 min of debugging the type error.
+
+#### What caused friction (user side)
+
+- None — no user intervention was needed at any point across all three stages.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added a Non-Goals vs Module-Level Changes cross-check instruction under the Module-Level Changes bullet.

package/docs/retro/0194-align-tool-interfaces-for-structural-typing.md

@@ -0,0 +1,36 @@
+---
+issue: 194
+issue_title: "Align tool interfaces for structural typing"
+---
+
+# Retro: #194 — Align tool interfaces for structural typing
+
+## Stage: Planning (2026-05-24T12:00:00Z)
+
+### Session summary
+
+Produced an implementation plan for three targeted alignment changes: moving `getMaxConcurrent` off manager interfaces to the settings accessor, renaming `SubagentRuntime.updateWidget()` → `update()`, and removing the dead `getToolCallName` re-export.
+The plan includes a 4-step TDD order with type-check gates after each refactoring step.
+
+### Observations
+
+- Issue #193 (Layer 1) is already closed/implemented, confirming this layer can proceed immediately.
+
+## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps: renamed `SubagentRuntime.updateWidget()` → `update()`, moved `getMaxConcurrent` from manager interfaces to the `settings` narrow type, removed the dead `getToolCallName` re-export, and updated the architecture doc.
+Test count stayed flat at 854 (53 files) — all green.
+The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-deps.test.ts` that also validated `getMaxConcurrent` and the old `settings` shape; this file was updated as part of step 2.
+
+### Observations
+
+- An unexpected file `test/helpers/make-deps.test.ts` had three type errors after removing `getMaxConcurrent` (one test asserting `manager.getMaxConcurrent()`, one structural compatibility check referencing it, and one settings override that only passed `defaultMaxTurns`).
+  All three were fixed in the same commit as step 2 — no deviation from the plan.
+- Adding `settings` to `BackgroundParams` (instead of as a 5th function parameter) was the right call: it keeps `spawnBackground` at 4 arguments and groups all spawn-context values together.
+- The health metric update: dead exports 1 → 0, adapter closures 41 → 40 (only `getMaxConcurrent` was removed in this layer; the remaining 8 widget/manager adapter closures need #195 class conversion to collapse).
+- The `background-spawner.ts` module is the only consumer of `getMaxConcurrent` — grep confirms no other call sites beyond `agent-tool.ts`'s interface definition.
+- The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
+- The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
+- All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.

package/package.json

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

package/src/index.ts

@@ -67,7 +67,7 @@ export default function (pi: ExtensionAPI) {
     (msg, opts) => pi.sendMessage(msg, opts),
     runtime.agentActivity,
     (id) => runtime.markFinished(id),
-    () => runtime.updateWidget(),
+    () => runtime.update(),
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -191,12 +191,11 @@ export default function (pi: ExtensionAPI) {
       spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
-      getMaxConcurrent: () => settings.maxConcurrent,
     },
     widget: {
       setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
       ensureTimer: () => runtime.ensureTimer(),
-      update: () => runtime.updateWidget(),
+      update: () => runtime.update(),
       markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,

package/src/runtime.ts

@@ -109,7 +109,7 @@ export class SubagentRuntime {
   }
 
   /** Delegate to widget.update — no-op when widget is null. */
-  updateWidget(): void {
+  update(): void {
     this.widget?.update();
   }
 

package/src/tools/agent-tool.ts

@@ -23,7 +23,6 @@ export interface AgentToolManager {
   spawnAndWait: (snapshot: ParentSnapshot, 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;
 }
 
 /** Narrow widget interface — only the methods the Agent tool calls. */
@@ -50,8 +49,8 @@ export interface AgentToolDeps {
   agentActivity: AgentActivityAccess;
   registry: AgentTypeRegistry;
   agentDir: string;
-  /** Narrow settings accessor — only the default max turns is needed here. */
-  settings: { readonly defaultMaxTurns: number | undefined };
+  /** Narrow settings accessor — only the fields the Agent tool reads. */
+  settings: { readonly defaultMaxTurns: number | undefined; readonly maxConcurrent: number };
   /** Build a ParentSnapshot from the current session context. */
   buildSnapshot: (inheritContext: boolean) => ParentSnapshot;
   /** Model info from the current session context. */
@@ -252,7 +251,7 @@ Guidelines:
           manager,
           widget,
           agentActivity,
-          { config, snapshot, parentSession },
+          { config, snapshot, parentSession, settings },
         );
       }
 

package/src/tools/background-spawner.ts

@@ -11,7 +11,6 @@ import { subscribeUIObserver } from "#src/ui/ui-observer";
 export interface BackgroundManagerDeps {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
   getRecord(id: string): AgentRecord | undefined;
-  getMaxConcurrent(): number;
 }
 
 /** Narrow widget interface for the background spawner. */
@@ -25,6 +24,7 @@ export interface BackgroundParams {
   config: ResolvedSpawnConfig;
   snapshot: ParentSnapshot;
   parentSession: ParentSessionInfo;
+  settings: { readonly maxConcurrent: number };
 }
 
 /**
@@ -77,7 +77,7 @@ export function spawnBackground(
       `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
-        ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
+        ? `Position: queued (max ${params.settings.maxConcurrent} concurrent)\n`
         : "") +
       `\nYou will be notified when this agent completes.\n` +
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +

package/src/ui/message-formatters.ts

@@ -21,8 +21,6 @@ export interface FormatterContext {
 
 // ── File-local types and guards ─────────────────────────────────────────────
 
-export { getToolCallName } from "#src/session/content-items";
-
 /** Bash execution message — 'bashExecution' role is not in the SDK's AgentSession message role union. */
 export interface BashExecutionMessage {
   role: "bashExecution";