@gotgenes/pi-subagents 5.5.0 → 5.6.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [5.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.5.0...pi-subagents-v5.6.0) (2026-05-20)
+
+
+### Features
+
+* convert AgentManager to options-bag constructor with DI ([1292cec](https://github.com/gotgenes/pi-packages/commit/1292cec60c24d8e657985c53b9b3413089c2a79d))
+* define AgentRunner interface in agent-runner.ts ([6a3c85a](https://github.com/gotgenes/pi-packages/commit/6a3c85a445daf0e4e8c01620eb6ae1a8237f1766))
+
+
+### Documentation
+
+* mark [#84](https://github.com/gotgenes/pi-packages/issues/84) as done in plan ([#72](https://github.com/gotgenes/pi-packages/issues/72)) ([5cfa1ec](https://github.com/gotgenes/pi-packages/commit/5cfa1ecf080f95fbd6b4aec05b27cc9672f60267))
+* **retro:** add retro notes for issue [#84](https://github.com/gotgenes/pi-packages/issues/84) ([99d9016](https://github.com/gotgenes/pi-packages/commit/99d90161df5fe9d302514e33c2d2d9fbfb248f25))
+
 ## [5.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.4.1...pi-subagents-v5.5.0) (2026-05-20)
 
 

package/docs/plans/0072-inject-agent-manager-collaborators.md

@@ -35,7 +35,7 @@ Any test of `AgentManager` must mock entire modules via `vi.mock()`, coupling th
 | #71   | Extract pure agent-session assembler                | ✓ Done  |
 | #76   | Inject `cwd` into `AgentManager`                    | ✓ Done  |
 | #80   | Consolidate `getConfig`/`getAgentConfig`            | ✓ Done  |
-| #84   | Extract `GitWorktreeManager` class from worktree.ts | Pending |
+| #84   | Extract `GitWorktreeManager` class from worktree.ts | ✓ Done  |
 
 ### Prior art
 
@@ -201,7 +201,7 @@ expect(runner.run).toHaveBeenCalled();
 
 ### `src/worktree.ts` (no changes in this issue)
 
-`WorktreeManager` interface and `GitWorktreeManager` class are added by prerequisite #84.
+`WorktreeManager` interface and `GitWorktreeManager` class were added by #84.
 
 ### `src/agent-runner.ts` (modified)
 

package/docs/retro/0084-extract-git-worktree-manager.md

@@ -0,0 +1,37 @@
+---
+issue: 84
+issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
+---
+
+# Retro: #84 — extract GitWorktreeManager class from worktree.ts free functions
+
+## Final Retrospective (2026-05-20T13:31:00Z)
+
+### Session summary
+
+Extracted a `WorktreeManager` interface and `GitWorktreeManager` class from the three free functions in `worktree.ts`.
+The two-step TDD cycle (add tests → add implementation) executed cleanly with no rework or deviations from the plan.
+Released as `pi-subagents-v5.5.0`.
+
+### Observations
+
+#### What went well
+
+- The issue body included an exact "Proposed Interface" section with TypeScript code, which made the plan nearly mechanical and eliminated all design ambiguity.
+  The `ask-user` step was correctly skipped.
+- The two-step TDD cycle was appropriately minimal for a thin delegation extraction — no over-engineering of the test or commit structure.
+- The full pipeline (plan → TDD → ship → release) completed in a single pass with zero corrections.
+
+#### What caused friction (agent side)
+
+No friction observed.
+The issue was well-scoped and the existing pipeline instructions handled every step.
+
+#### What caused friction (user side)
+
+No friction observed.
+The pipeline was driven cleanly with `/plan-issue` → `/tdd-plan` → `/ship-issue`.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0084-extract-git-worktree-manager.md`.

package/package.json

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

package/src/agent-manager.ts

@@ -9,12 +9,12 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { resumeAgent, runAgent, type ToolActivity } from "./agent-runner.js";
+import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
-import { cleanupWorktree, createWorktree, pruneWorktrees, } from "./worktree.js";
+import type { WorktreeManager } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -24,6 +24,16 @@ export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; toke
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  maxConcurrent?: number;
+  getRunConfig?: () => RunConfig;
+  onStart?: OnAgentStart;
+  onComplete?: OnAgentComplete;
+  onCompact?: OnAgentCompact;
+}
+
 interface SpawnArgs {
   pi: ExtensionAPI;
   ctx: ExtensionContext;
@@ -72,7 +82,8 @@ export class AgentManager {
   private onComplete?: OnAgentComplete;
   private onStart?: OnAgentStart;
   private onCompact?: OnAgentCompact;
-  private readonly cwd: string;
+  private readonly runner: AgentRunner;
+  private readonly worktrees: WorktreeManager;
   private maxConcurrent: number;
   private getRunConfig?: () => RunConfig;
 
@@ -81,20 +92,14 @@ export class AgentManager {
   /** Number of currently running background agents. */
   private runningBackground = 0;
 
-  constructor(
-    cwd: string,
-    onComplete?: OnAgentComplete,
-    maxConcurrent = DEFAULT_MAX_CONCURRENT,
-    onStart?: OnAgentStart,
-    onCompact?: OnAgentCompact,
-    getRunConfig?: () => RunConfig,
-  ) {
-    this.cwd = cwd;
-    this.onComplete = onComplete;
-    this.onStart = onStart;
-    this.onCompact = onCompact;
-    this.getRunConfig = getRunConfig;
-    this.maxConcurrent = maxConcurrent;
+  constructor(options: AgentManagerOptions) {
+    this.runner = options.runner;
+    this.worktrees = options.worktrees;
+    this.onComplete = options.onComplete;
+    this.onStart = options.onStart;
+    this.onCompact = options.onCompact;
+    this.getRunConfig = options.getRunConfig;
+    this.maxConcurrent = options.maxConcurrent ?? DEFAULT_MAX_CONCURRENT;
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
     this.cleanupInterval = setInterval(() => this.cleanup(), 60_000);
     this.cleanupInterval.unref();
@@ -164,7 +169,7 @@ export class AgentManager {
     // BEFORE state mutation so a throw doesn't leave the record half-running.
     let worktreeCwd: string | undefined;
     if (options.isolation === "worktree") {
-      const wt = createWorktree(ctx.cwd, id);
+      const wt = this.worktrees.create(id);
       if (!wt) {
         throw new Error(
           'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -190,7 +195,7 @@ export class AgentManager {
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
     const runConfig = this.getRunConfig?.();
-    const promise = runAgent(ctx, type, prompt, {
+    const promise = this.runner.run(ctx, type, prompt, {
       pi,
       model: options.model,
       maxTurns: options.maxTurns,
@@ -247,7 +252,7 @@ export class AgentManager {
 
         // Clean up worktree if used
         if (record.worktree) {
-          const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+          const wtResult = this.worktrees.cleanup(record.worktree, options.description);
           record.worktreeResult = wtResult;
           if (wtResult.hasChanges && wtResult.branch) {
             record.result = (record.result ?? "") +
@@ -281,7 +286,7 @@ export class AgentManager {
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {
-            const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
+            const wtResult = this.worktrees.cleanup(record.worktree, options.description);
             record.worktreeResult = wtResult;
           } catch (err) { debugLog("cleanupWorktree on agent error", err); }
         }
@@ -351,7 +356,7 @@ export class AgentManager {
     record.error = undefined;
 
     try {
-      const responseText = await resumeAgent(record.session, prompt, {
+      const responseText = await this.runner.resume(record.session, prompt, {
         onToolActivity: (activity) => {
           if (activity.type === "end") record.toolUses++;
         },
@@ -488,6 +493,6 @@ export class AgentManager {
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)
-    try { pruneWorktrees(this.cwd); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
+    try { this.worktrees.prune(); } catch (err) { debugLog("pruneWorktrees on dispose", err); }
   }
 }

package/src/agent-runner.ts

@@ -129,6 +129,23 @@ export interface RunResult {
   steered: boolean;
 }
 
+/** Options for resuming an existing agent session. */
+export interface ResumeOptions {
+  onToolActivity?: (activity: ToolActivity) => void;
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Execution boundary: decouples AgentManager (lifecycle management) from the
+ * SDK session orchestration in runAgent/resumeAgent.
+ */
+export interface AgentRunner {
+  run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+  resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
+}
+
 /**
  * Subscribe to a session and collect the last assistant message text.
  * Returns an object with a `getText()` getter and an `unsubscribe` function.
@@ -375,19 +392,7 @@ export async function runAgent(
 export async function resumeAgent(
   session: AgentSession,
   prompt: string,
-  options: {
-    onToolActivity?: (activity: ToolActivity) => void;
-    onAssistantUsage?: (usage: {
-      input: number;
-      output: number;
-      cacheWrite: number;
-    }) => void;
-    onCompaction?: (info: {
-      reason: "manual" | "threshold" | "overflow";
-      tokensBefore: number;
-    }) => void;
-    signal?: AbortSignal;
-  } = {},
+  options: ResumeOptions = {},
 ): Promise<string> {
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);

package/src/index.ts

@@ -13,7 +13,7 @@
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, normalizeMaxTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
@@ -33,6 +33,7 @@ import {
   AgentWidget,
   type UICtx,
 } from "./ui/agent-widget.js";
+import { GitWorktreeManager } from "./worktree.js";
 
 export default function (pi: ExtensionAPI) {
   // ---- Register custom notification renderer ----
@@ -61,49 +62,55 @@ export default function (pi: ExtensionAPI) {
   });
 
   // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager(process.cwd(), (record) => {
-    // Emit lifecycle event based on terminal status
-    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-    const eventData = buildEventData(record);
-    if (isError) {
-      pi.events.emit("subagents:failed", eventData);
-    } else {
-      pi.events.emit("subagents:completed", eventData);
-    }
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    onComplete: (record) => {
+      // Emit lifecycle event based on terminal status
+      const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+      const eventData = buildEventData(record);
+      if (isError) {
+        pi.events.emit("subagents:failed", eventData);
+      } else {
+        pi.events.emit("subagents:completed", eventData);
+      }
 
-    // Persist final record for cross-extension history reconstruction
-    pi.appendEntry("subagents:record", {
-      id: record.id, type: record.type, description: record.description,
-      status: record.status, result: record.result, error: record.error,
-      startedAt: record.startedAt, completedAt: record.completedAt,
-    });
+      // Persist final record for cross-extension history reconstruction
+      pi.appendEntry("subagents:record", {
+        id: record.id, type: record.type, description: record.description,
+        status: record.status, result: record.result, error: record.error,
+        startedAt: record.startedAt, completedAt: record.completedAt,
+      });
 
-    // Skip notification if result was already consumed via get_subagent_result
-    if (record.resultConsumed) {
-      notifications.cleanupCompleted(record.id);
-      return;
-    }
+      // Skip notification if result was already consumed via get_subagent_result
+      if (record.resultConsumed) {
+        notifications.cleanupCompleted(record.id);
+        return;
+      }
 
-    notifications.sendCompletion(record);
-  }, undefined, (record) => {
-    // Emit started event when agent transitions to running (including from queue)
-    pi.events.emit("subagents:started", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-    });
-  }, (record, info) => {
-    // Emit compacted event when agent's session compacts (preserves count on record).
-    pi.events.emit("subagents:compacted", {
-      id: record.id,
-      type: record.type,
-      description: record.description,
-      reason: info.reason,
-      tokensBefore: info.tokensBefore,
-      compactionCount: record.compactionCount,
-    });
-  },
-  () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }));
+      notifications.sendCompletion(record);
+    },
+    onStart: (record) => {
+      // Emit started event when agent transitions to running (including from queue)
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onCompact: (record, info) => {
+      // Emit compacted event when agent's session compacts (preserves count on record).
+      pi.events.emit("subagents:compacted", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        reason: info.reason,
+        tokensBefore: info.tokensBefore,
+        compactionCount: record.compactionCount,
+      });
+    },
+    getRunConfig: () => ({ defaultMaxTurns: runtime.defaultMaxTurns, graceTurns: runtime.graceTurns }),
+  });
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");