@gotgenes/pi-subagents 10.1.0 → 10.2.1

package/src/lifecycle/agent-manager.ts

@@ -9,106 +9,16 @@
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
-import { AgentTypeRegistry } from "#src/config/agent-types";
 import { debugLog } from "#src/debug";
 import { Agent } from "#src/lifecycle/agent";
-import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
+import type { AgentRunner } from "#src/lifecycle/agent-runner";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeAgentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
-import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
-
-/**
- * RunHandle - per-run lifecycle object that owns cleanup state.
- *
- * Owns the observer unsubscribe and parent-signal detach handles acquired during
- * a run. Exposes `complete()` and `fail()` as the only way to finish a run,
- * eliminating mutable closure variables from `startAgent`.
- * `fireOnFinished` is idempotent - safe to call from both success and error paths.
- */
-class RunHandle {
-  private unsub?: () => void;
-  private detachFn?: () => void;
-  private onFinished?: () => void;
-
-  constructor(
-    private readonly record: Agent,
-    private readonly worktrees: WorktreeManager,
-    onFinished?: () => void,
-  ) {
-    this.onFinished = onFinished;
-  }
-
-  /** Wire a parent AbortSignal so it stops this agent when fired. */
-  wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
-    if (!signal) return;
-    const listener = () => onAbort();
-    signal.addEventListener("abort", listener, { once: true });
-    this.detachFn = () => signal.removeEventListener("abort", listener);
-  }
-
-  /** Store the record-observer unsubscribe handle (called from onSessionCreated). */
-  attachObserver(unsub: () => void): void {
-    this.unsub = unsub;
-  }
-
-  /** Complete a run successfully - clean up, transition record, fire onFinished. */
-  complete(result: RunResult): string {
-    this.releaseListeners();
-
-    let finalResult = result.responseText;
-    if (this.record.worktreeState) {
-      const wtResult = this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
-      if (wtResult.hasChanges && wtResult.branch) {
-        finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
-      }
-    }
-
-    if (result.aborted) this.record.markAborted(finalResult);
-    else if (result.steered) this.record.markSteered(finalResult);
-    else this.record.markCompleted(finalResult);
-
-    // Update execution with the final session/outputFile from the runner
-    this.record.execution = {
-      session: result.session,
-      outputFile: result.sessionFile ?? this.record.execution?.outputFile,
-    };
-
-    this.fireOnFinished();
-    return result.responseText;
-  }
-
-  /** Fail a run - mark error, best-effort worktree cleanup, fire onFinished. */
-  fail(err: unknown): void {
-    this.record.markError(err);
-    this.releaseListeners();
-
-    if (this.record.worktreeState) {
-      try {
-        this.record.worktreeState.performCleanup(this.worktrees, this.record.description);
-      } catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
-    }
-
-    this.fireOnFinished();
-  }
-
-  private releaseListeners(): void {
-    this.unsub?.();
-    this.unsub = undefined;
-    this.detachFn?.();
-    this.detachFn = undefined;
-  }
-
-  /** Fire the onFinished callback at most once. */
-  private fireOnFinished(): void {
-    const fn = this.onFinished;
-    this.onFinished = undefined;
-    fn?.();
-  }
-}
+import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "#src/types";
 
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
@@ -127,8 +37,6 @@ const DEFAULT_MAX_CONCURRENT = 4;
 export interface AgentManagerOptions {
   runner: AgentRunner;
   worktrees: WorktreeManager;
-  exec: ShellExec;
-  registry: AgentTypeRegistry;
   /** Injected getter for the concurrency limit - owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
@@ -183,8 +91,6 @@ export class AgentManager {
   private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
-  private readonly exec: ShellExec;
-  private readonly registry: AgentTypeRegistry;
   private readonly _getMaxConcurrent: () => number;
   private getRunConfig?: () => RunConfig;
 
@@ -195,8 +101,6 @@ export class AgentManager {
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
-    this.exec = options.exec;
-    this.registry = options.registry;
     this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
@@ -252,10 +156,11 @@ export class AgentManager {
       return id;
     }
 
-    // startAgent can throw (e.g. strict worktree-isolation failure) - clean
+    // setupWorktree can throw (e.g. strict worktree-isolation failure) - clean
     // up the record so callers don't see an orphan in `listAgents()`.
     try {
-      this.startAgent(id, record, args);
+      record.setupWorktree(this.worktrees, options.isolation);
+      record.promise = this.startAgent(id, record, args);
     } catch (err) {
       this.agents.delete(id);
       throw err;
@@ -264,49 +169,47 @@ export class AgentManager {
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
-  private startAgent(id: string, record: Agent, { snapshot, type, prompt, options }: SpawnArgs) {
-    const worktreeCwd = record.setupWorktree(this.worktrees, options.isolation);
-
+  private async startAgent(id: string, record: Agent, { snapshot, type, prompt, options }: SpawnArgs): Promise<void> {
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
     this.observer?.onAgentStarted(record);
 
-    const handle = new RunHandle(
-      record, this.worktrees,
+    record.setOnRunFinished(
       options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
     );
-    handle.wireSignal(options.signal, () => this.abort(id));
+    record.wireSignal(options.signal, () => this.abort(id));
 
     const runConfig = this.getRunConfig?.();
-    record.promise = this.runner.run(snapshot, type, prompt, {
-      context: {
-        exec: this.exec,
-        registry: this.registry,
-        cwd: worktreeCwd,
-        parentSession: options.parentSession,
-      },
-      model: options.model,
-      maxTurns: options.maxTurns,
-      defaultMaxTurns: runConfig?.defaultMaxTurns,
-      graceTurns: runConfig?.graceTurns,
-      isolated: options.isolated,
-      thinkingLevel: options.thinkingLevel,
-      signal: record.abortController!.signal,
-      onSessionCreated: (session) => {
-        // Capture the session file path early so it's available for display
-        // before the run completes (e.g. in background agent status messages).
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
-        const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
-        record.execution = { session, outputFile };
-        record.flushPendingSteers(session);
-        handle.attachObserver(subscribeAgentObserver(session, record, {
-          onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-        }));
-        options.onSessionCreated?.(session, record);
-      },
-    })
-      .then((result) => handle.complete(result))
-      .catch((err: unknown) => { handle.fail(err); return ""; });
+    try {
+      const result = await this.runner.run(snapshot, type, prompt, {
+        context: {
+          cwd: record.worktreeState?.path,
+          parentSession: options.parentSession,
+        },
+        model: options.model,
+        maxTurns: options.maxTurns,
+        defaultMaxTurns: runConfig?.defaultMaxTurns,
+        graceTurns: runConfig?.graceTurns,
+        isolated: options.isolated,
+        thinkingLevel: options.thinkingLevel,
+        signal: record.abortController!.signal,
+        onSessionCreated: (session) => {
+          // Capture the session file path early so it's available for display
+          // before the run completes (e.g. in background agent status messages).
+          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- sessionManager is typed as always present but Pi SDK may not provide it
+          const outputFile = session.sessionManager?.getSessionFile?.() ?? undefined;
+          record.execution = { session, outputFile };
+          record.flushPendingSteers(session);
+          record.attachObserver(subscribeAgentObserver(session, record, {
+            onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
+          }));
+          options.onSessionCreated?.(session, record);
+        },
+      });
+      record.completeRun(result, this.worktrees);
+    } catch (err) {
+      record.failRun(err, this.worktrees);
+    }
   }
 
   /** Decrement background counter, notify observer (crash-safe), and drain the queue. */
@@ -323,7 +226,8 @@ export class AgentManager {
       const record = this.agents.get(next.id);
       if (record?.status !== "queued") continue;
       try {
-        this.startAgent(next.id, record, next.args);
+        record.setupWorktree(this.worktrees, next.args.options.isolation);
+        record.promise = this.startAgent(next.id, record, next.args);
       } catch (err) {
         // Late failure (e.g. strict worktree-isolation) - surface on the record
         // so the user/agent can see it via /agents, then keep draining.
@@ -471,7 +375,7 @@ export class AgentManager {
       const pending = [...this.agents.values()]
         .filter(r => r.status === "running" || r.status === "queued")
         .map(r => r.promise)
-        .filter((p): p is Promise<string> => p != null);
+        .filter((p): p is Promise<void> => p != null);
       if (pending.length === 0) break;
       await Promise.allSettled(pending);
     }

package/src/lifecycle/agent-runner.ts

@@ -114,19 +114,27 @@ export interface SessionFactoryIO {
  */
 export type RunnerIO = EnvironmentIO & SessionFactoryIO;
 
+/**
+ * Dependencies owned by the runner — injected at construction time.
+ *
+ * Groups the IO boundary with the two static domain deps (exec, registry)
+ * that every run() call needs but that do not vary per call.
+ */
+export interface RunnerDeps {
+  io: RunnerIO;
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+}
+
 // ── Public interfaces ─────────────────────────────────────────────────────────
 
 /**
- * Parent execution context - where/who is running.
+ * Per-call execution context — fields that vary per spawn.
  *
- * Groups the four fields that describe the parent environment and identity,
- * separating them from the per-call execution parameters in RunOptions.
+ * Static dependencies (exec, registry) live on RunnerDeps; this interface
+ * carries only the two per-call fields that AgentManager supplies at spawn time.
  */
 export interface RunContext {
-  /** Shell-exec callback for detectEnv - injected from pi.exec(). */
-  exec: ShellExec;
-  /** Agent config lookup - provides resolveAgentConfig and getToolNamesForType. */
-  registry: AgentConfigLookup;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
   /** Parent session identity (file path + session ID). */
@@ -182,15 +190,16 @@ export interface AgentRunner {
 }
 
 /**
- * Concrete AgentRunner backed by a RunnerIO boundary.
+ * Concrete AgentRunner backed by RunnerDeps.
  *
- * Captures io at construction time so AgentManager remains IO-unaware.
+ * Captures IO, exec, and registry at construction time so AgentManager
+ * remains unaware of runner-internal dependencies.
  */
 export class ConcreteAgentRunner implements AgentRunner {
-  constructor(private readonly io: RunnerIO) {}
+  constructor(private readonly deps: RunnerDeps) {}
 
   run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult> {
-    return runAgent(snapshot, type, prompt, options, this.io);
+    return runAgent(snapshot, type, prompt, options, this.deps);
   }
 
   resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string> {
@@ -253,11 +262,11 @@ export async function runAgent(
   type: SubagentType,
   prompt: string,
   options: RunOptions,
-  io: RunnerIO,
+  deps: RunnerDeps,
 ): Promise<RunResult> {
   // Resolve working directory upfront - needed for detectEnv before assembly.
   const effectiveCwd = options.context.cwd ?? snapshot.cwd;
-  const env = await io.detectEnv(options.context.exec, effectiveCwd);
+  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
   const cfg = assembleSessionConfig(
@@ -275,11 +284,11 @@ export async function runAgent(
       thinkingLevel: options.thinkingLevel,
     },
     env,
-    options.context.registry,
-    io.assemblerIO,
+    deps.registry,
+    deps.io.assemblerIO,
   );
 
-  const agentDir = io.getAgentDir();
+  const agentDir = deps.io.getAgentDir();
 
   // Load extensions/skills: true → load; false → don't.
   // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
@@ -287,7 +296,7 @@ export async function runAgent(
   // would defeat prompt_mode: replace and isolated: true. Parent context, if
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
-  const loader = io.createResourceLoader({
+  const loader = deps.io.createResourceLoader({
     cwd: cfg.effectiveCwd,
     agentDir,
     noExtensions: !cfg.extensions,
@@ -303,15 +312,15 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = io.deriveSessionDir(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
-  const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
+  const sessionDir = deps.io.deriveSessionDir(options.context.parentSession?.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = deps.io.createSessionManager(cfg.effectiveCwd, sessionDir);
   sessionManager.newSession({ parentSession: options.context.parentSession?.parentSessionId });
 
-  const { session } = await io.createSession({
+  const { session } = await deps.io.createSession({
     cwd: cfg.effectiveCwd,
     agentDir,
     sessionManager,
-    settingsManager: io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    settingsManager: deps.io.createSettingsManager(cfg.effectiveCwd, agentDir),
     modelRegistry: snapshot.modelRegistry,
     model: cfg.model,
     tools: cfg.toolNames,

package/src/lifecycle/agent.ts

@@ -16,6 +16,8 @@
  */
 
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
+import { debugLog } from "#src/debug";
+import type { RunResult } from "#src/lifecycle/agent-runner";
 import type { ExecutionState } from "#src/lifecycle/execution-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
@@ -44,7 +46,7 @@ export interface AgentInit {
 	error?: string;
 	abortController?: AbortController;
 	invocation?: AgentInvocation;
-	promise?: Promise<string>;
+	promise?: Promise<void>;
 }
 
 export class Agent {
@@ -83,7 +85,7 @@ export class Agent {
 	/** AbortController for cancelling this agent. Set at construction; used only by AgentManager. */
 	readonly abortController?: AbortController;
 	/** Promise for the full agent run (including post-processing). Set once by AgentManager. */
-	promise?: Promise<string>;
+	promise?: Promise<void>;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
@@ -248,12 +250,90 @@ export class Agent {
 		this._pendingSteers = [];
 	}
 
-	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
 	resetForResume(startedAt: number): void {
 		this._status = "running";
 		this._startedAt = startedAt;
 		this._completedAt = undefined;
 		this._result = undefined;
 		this._error = undefined;
+		this.releaseListeners();
+		this._onRunFinished = undefined;
+	}
+
+	// --- Per-run listener state (released on completion or resume reset) ---
+	private _unsub?: () => void;
+	private _detachFn?: () => void;
+	private _onRunFinished?: () => void;
+
+	/** Wire a parent AbortSignal so it stops this agent when fired. */
+	wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
+		if (!signal) return;
+		const listener = () => onAbort();
+		signal.addEventListener("abort", listener, { once: true });
+		this._detachFn = () => signal.removeEventListener("abort", listener);
+	}
+
+	/** Store the record-observer unsubscribe handle. */
+	attachObserver(unsub: () => void): void {
+		this._unsub = unsub;
+	}
+
+	/** Release observer + signal listener handles. */
+	releaseListeners(): void {
+		this._unsub?.();
+		this._unsub = undefined;
+		this._detachFn?.();
+		this._detachFn = undefined;
+	}
+
+	/** Set the callback fired once when the run finishes (for concurrency drain). */
+	setOnRunFinished(fn: (() => void) | undefined): void {
+		this._onRunFinished = fn;
+	}
+
+	/** Fire the onRunFinished callback at most once. */
+	private fireOnRunFinished(): void {
+		const fn = this._onRunFinished;
+		this._onRunFinished = undefined;
+		fn?.();
+	}
+
+	/** Complete a run: release listeners, worktree cleanup, status transition, execution update, fire onRunFinished. */
+	completeRun(result: RunResult, worktrees: WorktreeManager): void {
+		this.releaseListeners();
+
+		let finalResult = result.responseText;
+		if (this.worktreeState) {
+			const wtResult = this.worktreeState.performCleanup(worktrees, this.description);
+			if (wtResult.hasChanges && wtResult.branch) {
+				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
+			}
+		}
+
+		if (result.aborted) this.markAborted(finalResult);
+		else if (result.steered) this.markSteered(finalResult);
+		else this.markCompleted(finalResult);
+
+		this.execution = {
+			session: result.session,
+			outputFile: result.sessionFile ?? this.execution?.outputFile,
+		};
+
+		this.fireOnRunFinished();
+	}
+
+	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, fire onRunFinished. */
+	failRun(err: unknown, worktrees: WorktreeManager): void {
+		this.markError(err);
+		this.releaseListeners();
+
+		if (this.worktreeState) {
+			try {
+				this.worktreeState.performCleanup(worktrees, this.description);
+			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
+		}
+
+		this.fireOnRunFinished();
 	}
 }