@gotgenes/pi-subagents 7.3.1 → 7.4.0

package/docs/retro/0208-extract-shared-test-fixtures.md

@@ -5,6 +5,63 @@ issue_title: "Extract shared test fixtures to reduce test duplication"
 
 # Retro: #208 — Extract shared test fixtures to reduce test duplication
 
+## Stage: Final Retrospective (2026-05-25T22:00:00Z)
+
+### Session summary
+
+Reviewed the planning, TDD, and shipping sessions for issue #208.
+The work completed Phase 12 of the pi-subagents improvement roadmap.
+Identified Vitest v4 type compatibility as the dominant friction pattern, and the user surfaced a strategic insight: shared test factories are treating symptoms of ISP violations in production interfaces.
+
+### Observations
+
+#### What went well
+
+- The planning session's duplication diff (comparing default values across all copies before writing the shared factory) prevented cascading assertion failures during migration — the testing skill rule paid off.
+- Using a Python script for the `agent-manager.test.ts` spawn consolidation (step 9) handled 42 multi-line replacements with 7 distinct patterns cleanly in one pass.
+- `pnpm run check` caught 4 separate type errors that Vitest's esbuild would have silently ignored at runtime: wrong `findAgentFile` parameter type, dropped `AgentConfig` import, unused `@ts-expect-error` directives, and `Mock<Procedure>` incompatibility.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — Wrote `vi.fn().mockReturnValue([])` in the shared factory without checking whether `Mock<Procedure>` is structurally assignable to the production function signatures (`RunnerIO`, `AgentFileOps`).
+   The testing skill warns about `ReturnType<typeof vi.fn>` at the field level, but I didn't connect this to the structural-compatibility scenario where a factory's return value flows to a typed production parameter.
+   Impact: 37 type errors after step 2, requiring a fixup commit (2953adc) and removal of the `assemblerOverrides` parameter.
+2. `missing-context` — Assumed `findAgentFile` took `(dir: string, name: string)` based on test usage patterns rather than checking the `AgentFileOps` interface.
+   The actual signature is `(name: string, dirs: string[])` — the second parameter is `string[]`.
+   Impact: caught by `pnpm run check`, fixed in the same commit, no rework.
+3. `scope-drift` — Removed `import type { AgentConfig }` from `agent-config-editor.test.ts` because the symbols it was needed for (`testDefaultConfig`, `testCustomConfig`) were being removed.
+   Didn't check that `buildEjectContent` tests 400 lines later also used `AgentConfig`.
+   Impact: caught by `pnpm run check`, one-line fix, no rework.
+4. `premature-convergence` — Added `@ts-expect-error` directives for `.mock` property access in the factory tests, assuming TypeScript wouldn't know about Mock's `.mock` property.
+   Once the `vi.fn()` stubs were typed with implementations, TypeScript recognized the Mock type and `.mock` was accessible, making all 5 directives unused.
+   Impact: added friction but no rework — eslint caught them.
+
+#### What caused friction (user side)
+
+- No friction caused by the user.
+  The user's post-ship reflection ("we need to eliminate complex setup, right?") was a strategic insight that elevated the conversation from mechanical duplication reduction to ISP-driven interface narrowing.
+  This kind of mid-session reframing is valuable and came at exactly the right time — after the work was done, so it informs future phases rather than disrupting the current one.
+
+#### Phase 13 guidance: ISP narrowing targets
+
+The `test/helpers/` factory inventory is a concrete map of production interfaces worth narrowing:
+
+| Factory             | Production interface                                          | Methods                       | Consumer usage                   |
+| ------------------- | ------------------------------------------------------------- | ----------------------------- | -------------------------------- |
+| `createRunnerIO`    | `RunnerIO` (`EnvironmentIO & SessionFactoryIO`)               | 8 (7 functions + assemblerIO) | Most tests use 2–3               |
+| `makeFileOps`       | `AgentFileOps`                                                | 6                             | Most tests use `exists` + `read` |
+| `createToolDeps`    | `AgentToolManager` + `AgentToolRuntime` + `AgentToolSettings` | 12+ across 3 interfaces       | Spawners use 2–3 each            |
+| `createMockSession` | `AgentSession` (SDK class)                                    | 5 stubs                       | Observers use `subscribe` only   |
+| `createAgentLookup` | `AgentConfigLookup`                                           | 2                             | Already narrow ✓                 |
+
+When a factory needs its own unit tests, the interface it stubs is too wide for its consumers.
+The fix is ISP narrowing of the production interface, not more test infrastructure.
+
+### Changes made
+
+1. Added rule to `testing` skill: typed implementations in shared factories when return value satisfies a production interface.
+2. Added ISP signal to `improvement-discovery` skill Category D table: shared factory complexity → narrow the production interface.
+
 ## Stage: Implementation — TDD (2026-05-25T21:00:00Z)
 
 ### Session summary

package/docs/retro/0214-convert-remaining-closure-factories-to-classes.md

@@ -0,0 +1,66 @@
+---
+issue: 214
+issue_title: "Convert remaining closure factories to classes (Phase 13, Step 1)"
+---
+
+# Retro: #214 — Convert remaining closure factories to classes
+
+## Stage: Planning (2026-05-25T20:00:00Z)
+
+### Session summary
+
+Produced a 4-step TDD plan to convert the three remaining closure factories (`createAgentConfigEditor`, `createAgentCreationWizard`, `createSubagentsService`) to classes.
+Each conversion is one commit covering source, test, and consumer updates together.
+
+### Observations
+
+- The conversions are entirely mechanical — same pattern as Phase 11 (#195, #196).
+  No design ambiguity requiring user input.
+- `AgentCreationWizardDeps` is only used within its own file, so removing it is safe.
+  The class dissolves the deps bag into positional constructor params for consistency with `AgentConfigEditor`.
+- The `agent-creation-wizard.test.ts` has ~18 inline `createAgentCreationWizard(deps)` calls; the plan suggests adding a `makeWizard(deps)` helper to centralize construction and reduce the diff size.
+- `SubagentsServiceAdapter` uses `implements SubagentsService` for compile-time verification, unlike the factory which relied on structural typing of the returned object literal.
+- Pure helper functions (`buildMenuOptions`, `buildEjectContent`, `toSubagentRecord`) and narrow interfaces (`AgentManagerLike`, `ServiceRuntimeLike`, `WizardManager`, `WizardRegistry`) remain unchanged.
+
+## Stage: Implementation — TDD (2026-05-25T21:00:00Z)
+
+### Session summary
+
+All 4 TDD steps completed in 4 commits.
+Three closure factories converted to classes (`AgentConfigEditor`, `AgentCreationWizard`, `SubagentsServiceAdapter`) with tests and consumers updated in the same commit as each production change.
+Test count held at 913 (57 files) — no new tests needed, no tests removed.
+
+### Observations
+
+- All three conversions were mechanical find-and-replace with no behavioral surprises.
+- The `makeWizard(deps)` helper in `agent-creation-wizard.test.ts` centralized 14 inline `createAgentCreationWizard(deps)` calls, keeping the diff readable.
+- `SubagentsServiceAdapter` uses `implements SubagentsService` — the TypeScript compiler confirmed the contract at compile time with no gaps.
+- Adding the `SpawnOptions` import to `service-adapter.ts` was required for the `spawn` method signature; the plan anticipated this correctly.
+- The `sed -i` command required the macOS `-i ''` form (no in-place backup extension) rather than the GNU `sed -i` form.
+- Dead-code gate (`pnpm fallow dead-code`) passed cleanly from the repo root — no suppression needed.
+
+## Stage: Final Retrospective (2026-05-25T22:00:00Z)
+
+### Session summary
+
+Shipped `pi-subagents-v7.3.2` with 3 refactor commits converting all remaining closure factories to classes.
+All 4 lifecycle stages (plan → TDD → ship → retro) completed in a single day with zero rework and zero deviations from the plan.
+
+### Observations
+
+#### What went well
+
+- Strong precedent from Phase 11 (#195, #196) made this issue zero-friction — the plan, implementation, and test updates all followed an established template.
+- The plan's prediction of a `makeWizard(deps)` helper for `agent-creation-wizard.test.ts` kept the step-2 diff readable by centralizing 14 inline constructor calls.
+- `SubagentsServiceAdapter implements SubagentsService` gave compile-time contract verification, catching any interface drift immediately via `pnpm run check`.
+- The plan correctly anticipated the `SpawnOptions` import need in `service-adapter.ts`.
+
+#### What caused friction (agent side)
+
+- None.
+  This was a textbook mechanical refactoring with no behavioral changes, no edge cases, and no test rework.
+
+#### What caused friction (user side)
+
+- None.
+  The issue was well-scoped with explicit target files and a clear precedent to follow.

package/package.json

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

package/src/index.ts

@@ -31,7 +31,7 @@ import { buildEventData, type NotificationDetails, NotificationManager } from "#
 import { createNotificationRenderer } from "#src/observation/renderer";
 import { createSubagentRuntime } from "#src/runtime";
 import { publishSubagentsService, unpublishSubagentsService } from "#src/service/service";
-import { createSubagentsService } from "#src/service/service-adapter";
+import { SubagentsServiceAdapter } from "#src/service/service-adapter";
 import { detectEnv } from "#src/session/env";
 
 import { resolveModel } from "#src/session/model-resolver";
@@ -157,7 +157,7 @@ export default function (pi: ExtensionAPI) {
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
-  const service = createSubagentsService(manager, resolveModel, runtime);
+  const service = new SubagentsServiceAdapter(manager, resolveModel, runtime);
   publishSubagentsService(service);
 
   const lifecycle = new SessionLifecycleHandler(

package/src/lifecycle/agent-runner.ts

@@ -455,8 +455,9 @@ export function getAgentConversation(session: AgentSession): string {
       if (text.trim()) parts.push(`[User]: ${text.trim()}`);
     } else if (msg.role === "assistant") {
       const { textParts, toolNames } = extractAssistantContent(msg.content);
+      const attribution = formatAttribution(msg);
       if (textParts.length > 0)
-        parts.push(`[Assistant]: ${textParts.join("\n")}`);
+        parts.push(`[Assistant${attribution}]: ${textParts.join("\n")}`);
       if (toolNames.length > 0)
         parts.push(`[Tool Calls]:\n${toolNames.map((n) => `  Tool: ${n}`).join("\n")}`);
     } else if (msg.role === "toolResult") {
@@ -468,3 +469,11 @@ export function getAgentConversation(session: AgentSession): string {
 
   return parts.join("\n\n");
 }
+
+/** Build a `(provider/model)` attribution suffix for assistant messages. */
+function formatAttribution(msg: { provider?: string; model?: string }): string {
+  const { provider, model } = msg;
+  if (!provider && !model) return "";
+  if (provider && model) return ` (${provider}/${model})`;
+  return ` (${provider ?? model})`;
+}

package/src/service/service-adapter.ts

@@ -6,7 +6,7 @@
  */
 
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { SubagentRecord, SubagentsService } from "#src/service/service";
+import type { SpawnOptions, SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
 import type { AgentRecord, SessionContext } from "#src/types";
 
@@ -30,83 +30,83 @@ export interface ServiceRuntimeLike {
   buildSnapshot(inheritContext: boolean): ParentSnapshot;
 }
 
-/** Create a SubagentsService backed by the given dependencies. */
-export function createSubagentsService(
-  manager: AgentManagerLike,
-  resolveModel: (input: string, registry: ModelRegistry) => unknown,
-  runtime: ServiceRuntimeLike,
-): SubagentsService {
-  return {
-    spawn(type: string, prompt: string, options?) {
-      if (!runtime.currentCtx) {
-        throw new Error("No active session — cannot spawn agents outside a session.");
+/** Adapter that wraps AgentManager to satisfy SubagentsService. */
+export class SubagentsServiceAdapter implements SubagentsService {
+  constructor(
+    private readonly manager: AgentManagerLike,
+    private readonly resolveModel: (input: string, registry: ModelRegistry) => unknown,
+    private readonly runtime: ServiceRuntimeLike,
+  ) {}
+
+  spawn(type: string, prompt: string, options?: SpawnOptions): string {
+    if (!this.runtime.currentCtx) {
+      throw new Error("No active session — cannot spawn agents outside a session.");
+    }
+
+    let model: unknown;
+    if (options?.model) {
+      const registry = this.runtime.currentCtx.modelRegistry;
+      if (!registry) {
+        throw new Error("No model registry available.");
       }
-
-      let model: unknown;
-      if (options?.model) {
-        const registry = runtime.currentCtx.modelRegistry;
-        if (!registry) {
-          throw new Error("No model registry available.");
-        }
-        const resolved = resolveModel(options.model, registry);
-        if (typeof resolved === "string") {
-          throw new Error(resolved);
-        }
-        model = resolved;
-      }
-
-      const description = options?.description ?? prompt.slice(0, 80);
-      const isBackground = !(options?.foreground ?? false);
-
-      const snapshot = runtime.buildSnapshot(options?.inheritContext ?? false);
-      return manager.spawn(snapshot, type, prompt, {
-        description,
-        model,
-        maxTurns: options?.maxTurns,
-        thinkingLevel: options?.thinkingLevel,
-        isolated: options?.isolated,
-        inheritContext: options?.inheritContext,
-        bypassQueue: options?.bypassQueue,
-        isolation: options?.isolation,
-        isBackground,
-      });
-    },
-
-    getRecord(id: string): SubagentRecord | undefined {
-      const record = manager.getRecord(id);
-      return record ? toSubagentRecord(record) : undefined;
-    },
-
-    listAgents(): SubagentRecord[] {
-      return manager.listAgents().map(toSubagentRecord);
-    },
-
-    abort(id: string): boolean {
-      return manager.abort(id);
-    },
-
-    async steer(id: string, message: string): Promise<boolean> {
-      const record = manager.getRecord(id);
-      if (record?.status !== "running") {
-        return false;
-      }
-      const session = record.session;
-      if (!session) {
-        // Session not ready yet — queue via manager for delivery once initialized
-        return manager.queueSteer(id, message);
+      const resolved = this.resolveModel(options.model, registry);
+      if (typeof resolved === "string") {
+        throw new Error(resolved);
       }
-      await session.steer(message);
-      return true;
-    },
-
-    async waitForAll(): Promise<void> {
-      return manager.waitForAll();
-    },
-
-    hasRunning(): boolean {
-      return manager.hasRunning();
-    },
-  };
+      model = resolved;
+    }
+
+    const description = options?.description ?? prompt.slice(0, 80);
+    const isBackground = !(options?.foreground ?? false);
+
+    const snapshot = this.runtime.buildSnapshot(options?.inheritContext ?? false);
+    return this.manager.spawn(snapshot, type, prompt, {
+      description,
+      model,
+      maxTurns: options?.maxTurns,
+      thinkingLevel: options?.thinkingLevel,
+      isolated: options?.isolated,
+      inheritContext: options?.inheritContext,
+      bypassQueue: options?.bypassQueue,
+      isolation: options?.isolation,
+      isBackground,
+    });
+  }
+
+  getRecord(id: string): SubagentRecord | undefined {
+    const record = this.manager.getRecord(id);
+    return record ? toSubagentRecord(record) : undefined;
+  }
+
+  listAgents(): SubagentRecord[] {
+    return this.manager.listAgents().map(toSubagentRecord);
+  }
+
+  abort(id: string): boolean {
+    return this.manager.abort(id);
+  }
+
+  async steer(id: string, message: string): Promise<boolean> {
+    const record = this.manager.getRecord(id);
+    if (record?.status !== "running") {
+      return false;
+    }
+    const session = record.session;
+    if (!session) {
+      // Session not ready yet — queue via manager for delivery once initialized
+      return this.manager.queueSteer(id, message);
+    }
+    await session.steer(message);
+    return true;
+  }
+
+  async waitForAll(): Promise<void> {
+    return this.manager.waitForAll();
+  }
+
+  hasRunning(): boolean {
+    return this.manager.hasRunning();
+  }
 }
 
 /**

package/src/ui/agent-config-editor.ts

@@ -61,86 +61,88 @@ export function buildEjectContent(cfg: AgentConfig): string {
   return `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
 }
 
-// ---- Factory ----
-
-export function createAgentConfigEditor(
-  fileOps: AgentFileOps,
-  registry: AgentTypeRegistry,
-  personalAgentsDir: string,
-  projectAgentsDir: string,
-) {
-  function agentDirs(): string[] {
-    return [projectAgentsDir, personalAgentsDir];
+// ---- Class ----
+
+export class AgentConfigEditor {
+  constructor(
+    private readonly fileOps: AgentFileOps,
+    private readonly registry: AgentTypeRegistry,
+    private readonly personalAgentsDir: string,
+    private readonly projectAgentsDir: string,
+  ) {}
+
+  private agentDirs(): string[] {
+    return [this.projectAgentsDir, this.personalAgentsDir];
   }
 
-  async function showAgentDetail(ui: MenuUI, name: string) {
-    if (registry.resolveType(name) == null) {
+  async showAgentDetail(ui: MenuUI, name: string): Promise<void> {
+    if (this.registry.resolveType(name) == null) {
       ui.notify(`Agent config not found for "${name}".`, "warning");
       return;
     }
-    const cfg = registry.resolveAgentConfig(name);
-    const file = fileOps.findAgentFile(name, agentDirs());
+    const cfg = this.registry.resolveAgentConfig(name);
+    const file = this.fileOps.findAgentFile(name, this.agentDirs());
 
     const choice = await ui.select(name, buildMenuOptions(cfg, file));
     if (!choice || choice === "Back") return;
 
-    if (choice === "Edit" && file) await handleEdit(ui, name, file);
-    else if (choice === "Delete" && file) await handleDelete(ui, name, file);
+    if (choice === "Edit" && file) await this.handleEdit(ui, name, file);
+    else if (choice === "Delete" && file) await this.handleDelete(ui, name, file);
     else if (choice === "Reset to default" && file)
-      await handleReset(ui, name, file);
-    else if (choice.startsWith("Eject")) await ejectAgent(ui, name, cfg);
-    else if (choice === "Disable") await disableAgent(ui, name);
-    else if (choice === "Enable") await enableAgent(ui, name);
+      await this.handleReset(ui, name, file);
+    else if (choice.startsWith("Eject")) await this.ejectAgent(ui, name, cfg);
+    else if (choice === "Disable") await this.disableAgent(ui, name);
+    else if (choice === "Enable") await this.enableAgent(ui, name);
   }
 
-  async function handleEdit(ui: MenuUI, name: string, file: string) {
-    const content = fileOps.read(file);
+  private async handleEdit(ui: MenuUI, name: string, file: string): Promise<void> {
+    const content = this.fileOps.read(file);
     if (content === undefined) return;
     const edited = await ui.editor(`Edit ${name}`, content);
     if (edited !== undefined && edited !== content) {
-      fileOps.write(file, edited);
-      registry.reload();
+      this.fileOps.write(file, edited);
+      this.registry.reload();
       ui.notify(`Updated ${file}`, "info");
     }
   }
 
-  async function handleDelete(ui: MenuUI, name: string, file: string) {
+  private async handleDelete(ui: MenuUI, name: string, file: string): Promise<void> {
     const confirmed = await ui.confirm(
       "Delete agent",
       `Delete ${name} (${file})?`,
     );
     if (confirmed) {
-      fileOps.remove(file);
-      registry.reload();
+      this.fileOps.remove(file);
+      this.registry.reload();
       ui.notify(`Deleted ${file}`, "info");
     }
   }
 
-  async function handleReset(ui: MenuUI, name: string, file: string) {
+  private async handleReset(ui: MenuUI, name: string, file: string): Promise<void> {
     const confirmed = await ui.confirm(
       "Reset to default",
       `Delete override ${file} and restore embedded default?`,
     );
     if (confirmed) {
-      fileOps.remove(file);
-      registry.reload();
+      this.fileOps.remove(file);
+      this.registry.reload();
       ui.notify(`Restored default ${name}`, "info");
     }
   }
 
-  async function ejectAgent(ui: MenuUI, name: string, cfg: AgentConfig) {
+  private async ejectAgent(ui: MenuUI, name: string, cfg: AgentConfig): Promise<void> {
     const location = await ui.select("Choose location", [
       "Project (.pi/agents/)",
-      `Personal (${personalAgentsDir})`,
+      `Personal (${this.personalAgentsDir})`,
     ]);
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir
-      : personalAgentsDir;
+      ? this.projectAgentsDir
+      : this.personalAgentsDir;
 
     const targetPath = join(targetDir, `${name}.md`);
-    if (fileOps.exists(targetPath)) {
+    if (this.fileOps.exists(targetPath)) {
       const overwrite = await ui.confirm(
         "Overwrite",
         `${targetPath} already exists. Overwrite?`,
@@ -148,23 +150,23 @@ export function createAgentConfigEditor(
       if (!overwrite) return;
     }
 
-    fileOps.write(targetPath, buildEjectContent(cfg));
-    registry.reload();
+    this.fileOps.write(targetPath, buildEjectContent(cfg));
+    this.registry.reload();
     ui.notify(`Ejected ${name} to ${targetPath}`, "info");
   }
 
-  async function disableAgent(ui: MenuUI, name: string) {
-    const file = fileOps.findAgentFile(name, agentDirs());
+  private async disableAgent(ui: MenuUI, name: string): Promise<void> {
+    const file = this.fileOps.findAgentFile(name, this.agentDirs());
     if (file) {
-      const content = fileOps.read(file);
+      const content = this.fileOps.read(file);
       if (content?.includes("\nenabled: false\n")) {
         ui.notify(`${name} is already disabled.`, "info");
         return;
       }
       if (content) {
         const updated = content.replace(/^---\n/, "---\nenabled: false\n");
-        fileOps.write(file, updated);
-        registry.reload();
+        this.fileOps.write(file, updated);
+        this.registry.reload();
         ui.notify(`Disabled ${name} (${file})`, "info");
       }
       return;
@@ -172,40 +174,38 @@ export function createAgentConfigEditor(
 
     const location = await ui.select("Choose location", [
       "Project (.pi/agents/)",
-      `Personal (${personalAgentsDir})`,
+      `Personal (${this.personalAgentsDir})`,
     ]);
     if (!location) return;
 
     const targetDir = location.startsWith("Project")
-      ? projectAgentsDir
-      : personalAgentsDir;
+      ? this.projectAgentsDir
+      : this.personalAgentsDir;
 
     const targetPath = join(targetDir, `${name}.md`);
-    fileOps.write(targetPath, "---\nenabled: false\n---\n");
-    registry.reload();
+    this.fileOps.write(targetPath, "---\nenabled: false\n---\n");
+    this.registry.reload();
     ui.notify(`Disabled ${name} (${targetPath})`, "info");
   }
 
   // eslint-disable-next-line @typescript-eslint/require-await
-  async function enableAgent(ui: MenuUI, name: string) {
-    const file = fileOps.findAgentFile(name, agentDirs());
+  private async enableAgent(ui: MenuUI, name: string): Promise<void> {
+    const file = this.fileOps.findAgentFile(name, this.agentDirs());
     if (!file) return;
 
-    const content = fileOps.read(file);
+    const content = this.fileOps.read(file);
     if (!content) return;
 
     const updated = content.replace(/^(---\n)enabled: false\n/, "$1");
 
     if (updated.trim() === "---\n---" || updated.trim() === "---\n---\n") {
-      fileOps.remove(file);
-      registry.reload();
+      this.fileOps.remove(file);
+      this.registry.reload();
       ui.notify(`Enabled ${name} (removed ${file})`, "info");
     } else {
-      fileOps.write(file, updated);
-      registry.reload();
+      this.fileOps.write(file, updated);
+      this.registry.reload();
       ui.notify(`Enabled ${name} (${file})`, "info");
     }
   }
-
-  return { showAgentDetail };
 }