@gotgenes/pi-subagents 10.2.0 → 11.0.0

package/src/lifecycle/agent-manager.ts

@@ -8,27 +8,22 @@
 
 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 { Agent, type AgentLifecycleObserver } from "#src/lifecycle/agent";
 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";
-
-export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
+import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Observer interface for agent lifecycle notifications. */
 export interface AgentManagerObserver {
   onAgentStarted(record: Agent): void;
   onAgentCompleted(record: Agent): void;
   onAgentCompacted(record: Agent, info: CompactionInfo): void;
-  /** Fires synchronously after a background agent record is created (before startAgent). */
+  /** Fires synchronously after a background agent record is created (before run). */
   onAgentCreated(record: Agent): void;
 }
 
@@ -38,30 +33,12 @@ 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;
   observer?: AgentManagerObserver;
 }
 
-interface SpawnArgs {
-  snapshot: ParentSnapshot;
-  type: SubagentType;
-  prompt: string;
-  options: AgentSpawnConfig;
-}
-
-export interface ParentSessionInfo {
-  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
-  parentSessionFile?: string;
-  /** Session ID of the parent agent (stored in the child session's parentSession header). */
-  parentSessionId?: string;
-  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
-  toolCallId?: string;
-}
-
 export interface AgentSpawnConfig {
   description: string;
   model?: Model<any>;
@@ -82,8 +59,8 @@ export interface AgentSpawnConfig {
   invocation?: AgentInvocation;
   /** Parent abort signal - when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Called when the agent session is created - receives the session and the agent's record. */
-  onSessionCreated?: (session: AgentSession, record: Agent) => void;
+  /** Per-agent lifecycle observer — replaces onSessionCreated callback. */
+  observer?: AgentLifecycleObserver;
   /** Parent session identity - grouped fields that travel together from the tool boundary. */
   parentSession?: ParentSessionInfo;
 }
@@ -94,20 +71,16 @@ 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;
 
-  /** Queue of background agents waiting to start. */
-  private queue: { id: string; args: SpawnArgs }[] = [];
+  /** Queue of background agent IDs waiting to start. */
+  private queue: string[] = [];
   /** Number of currently running background agents. */
   private runningBackground = 0;
   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);
@@ -124,6 +97,25 @@ export class AgentManager {
     this.drainQueue();
   }
 
+  /** Compose a per-agent lifecycle observer from manager and spawn-config concerns. */
+  private buildObserver(options: AgentSpawnConfig): AgentLifecycleObserver {
+    return {
+      onStarted: (agent) => {
+        if (options.isBackground) this.runningBackground++;
+        this.observer?.onAgentStarted(agent);
+      },
+      onSessionCreated: options.observer?.onSessionCreated
+        ? (agent, session) => options.observer!.onSessionCreated!(agent, session)
+        : undefined,
+      onRunFinished: (agent) => {
+        if (options.isBackground) this.finalizeBackgroundRun(agent);
+      },
+      onCompacted: (agent, info) => {
+        this.observer?.onAgentCompacted(agent, info);
+      },
+    };
+  }
+
   /**
    * Spawn an agent and return its ID immediately (for background use).
    * If the concurrency limit is reached, the agent is queued.
@@ -135,92 +127,45 @@ export class AgentManager {
     options: AgentSpawnConfig,
   ): string {
     const id = randomUUID().slice(0, 17);
-    const abortController = new AbortController();
     const record = new Agent({
       id,
       type,
       description: options.description,
       status: options.isBackground ? "queued" : "running",
       startedAt: Date.now(),
-      abortController,
       invocation: options.invocation,
+      // Run config
+      snapshot,
+      prompt,
+      model: options.model,
+      maxTurns: options.maxTurns,
+      isolated: options.isolated,
+      thinkingLevel: options.thinkingLevel,
+      isolation: options.isolation,
+      parentSession: options.parentSession,
+      signal: options.signal,
+      // Shared deps
+      runner: this.runner,
+      worktrees: this.worktrees,
+      observer: this.buildObserver(options),
+      getRunConfig: this.getRunConfig,
     });
     this.agents.set(id, record);
 
-    if (options.parentSession?.toolCallId) {
-      record.notification = new NotificationState(options.parentSession.toolCallId);
-    }
-
     if (options.isBackground) {
       this.observer?.onAgentCreated(record);
     }
 
-    const args: SpawnArgs = { snapshot, type, prompt, options };
-
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
       // Queue it - will be started when a running agent completes
-      this.queue.push({ id, args });
+      this.queue.push(id);
       return id;
     }
 
-    // setupWorktree can throw (e.g. strict worktree-isolation failure) - clean
-    // up the record so callers don't see an orphan in `listAgents()`.
-    try {
-      record.setupWorktree(this.worktrees, options.isolation);
-      record.promise = this.startAgent(id, record, args);
-    } catch (err) {
-      this.agents.delete(id);
-      throw err;
-    }
+    record.promise = record.run();
     return id;
   }
 
-  /** Actually start an agent (called immediately or from queue drain). */
-  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);
-
-    record.setOnRunFinished(
-      options.isBackground ? () => this.finalizeBackgroundRun(record) : undefined,
-    );
-    record.wireSignal(options.signal, () => this.abort(id));
-
-    const runConfig = this.getRunConfig?.();
-    try {
-      const result = await this.runner.run(snapshot, type, prompt, {
-        context: {
-          exec: this.exec,
-          registry: this.registry,
-          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. */
   private finalizeBackgroundRun(record: Agent): void {
     this.runningBackground--;
@@ -231,18 +176,10 @@ export class AgentManager {
   /** Start queued agents up to the concurrency limit. */
   private drainQueue() {
     while (this.queue.length > 0 && this.runningBackground < this._getMaxConcurrent()) {
-      const next = this.queue.shift()!;
-      const record = this.agents.get(next.id);
+      const id = this.queue.shift()!;
+      const record = this.agents.get(id);
       if (record?.status !== "queued") continue;
-      try {
-        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.
-        record.markError(err);
-        this.observer?.onAgentCompleted(record);
-      }
+      record.promise = record.run();
     }
   }
 
@@ -310,7 +247,7 @@ export class AgentManager {
 
     // Remove from queue if queued
     if (record.status === "queued") {
-      this.queue = this.queue.filter(q => q.id !== id);
+      this.queue = this.queue.filter(qid => qid !== id);
       record.markStopped();
       return true;
     }
@@ -358,8 +295,8 @@ export class AgentManager {
   abortAll(): number {
     let count = 0;
     // Clear queued agents first
-    for (const queued of this.queue) {
-      const record = this.agents.get(queued.id);
+    for (const id of this.queue) {
+      const record = this.agents.get(id);
       if (record) {
         record.markStopped();
         count++;

package/src/lifecycle/agent-runner.ts

@@ -9,14 +9,13 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
-import type { ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { registerChildSession, unregisterChildSession } from "#src/lifecycle/permission-bridge";
 import { extractAssistantContent } from "#src/session/content-items";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
 import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
-import type { ShellExec, SubagentType, ThinkingLevel } from "#src/types";
+import type { ParentSessionInfo, ShellExec, SubagentType, ThinkingLevel } from "#src/types";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
@@ -114,19 +113,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 +189,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 +261,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 +283,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 +295,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 +311,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,