@gotgenes/pi-subagents 10.2.0 → 11.0.0

package/src/lifecycle/agent.ts

@@ -15,16 +15,32 @@
  * after construction as lifecycle information becomes available.
  */
 
+import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import type { RunResult } from "#src/lifecycle/agent-runner";
+import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
 import type { ExecutionState } from "#src/lifecycle/execution-state";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { WorktreeManager } from "#src/lifecycle/worktree";
 import { WorktreeState } from "#src/lifecycle/worktree-state";
-import type { NotificationState } from "#src/observation/notification-state";
-import type { AgentInvocation, IsolationMode, SubagentType } from "#src/types";
+import { NotificationState } from "#src/observation/notification-state";
+import { subscribeAgentObserver } from "#src/observation/record-observer";
+import type { RunConfig } from "#src/runtime";
+import type { AgentInvocation, CompactionInfo, IsolationMode, ParentSessionInfo, SubagentType, ThinkingLevel } from "#src/types";
+
+/** Per-agent lifecycle observer — created by AgentManager for each spawn. */
+export interface AgentLifecycleObserver {
+	/** Fires when the agent transitions to running (inside run(), after markRunning). */
+	onStarted?(agent: Agent): void;
+	/** Fires when the runner creates the session — delivers the session to external consumers. */
+	onSessionCreated?(agent: Agent, session: AgentSession): void;
+	/** Fires once when the run completes or fails (for concurrency drain). */
+	onRunFinished?(agent: Agent): void;
+	/** Fires on compaction events during the run. */
+	onCompacted?(agent: Agent, info: CompactionInfo): void;
+}
 
 export type AgentStatus =
 	| "queued"
@@ -36,17 +52,36 @@ export type AgentStatus =
 	| "error";
 
 export interface AgentInit {
+	// Identity
 	id: string;
 	type: SubagentType;
 	description: string;
+	invocation?: AgentInvocation;
+
+	// Status (for tests and restore scenarios)
 	status?: AgentStatus;
 	startedAt?: number;
 	completedAt?: number;
 	result?: string;
 	error?: string;
-	abortController?: AbortController;
-	invocation?: AgentInvocation;
-	promise?: Promise<void>;
+
+	// Shared deps (required for run(), optional for tests)
+	runner?: AgentRunner;
+	worktrees?: WorktreeManager;
+	observer?: AgentLifecycleObserver;
+	getRunConfig?: () => RunConfig;
+
+	// Run config (required for run(), optional for tests)
+	snapshot?: ParentSnapshot;
+	prompt?: string;
+	model?: Model<any>;
+	maxTurns?: number;
+	isolated?: boolean;
+	thinkingLevel?: ThinkingLevel;
+	isolation?: IsolationMode;
+	parentSession?: ParentSessionInfo;
+	isBackground?: boolean;
+	signal?: AbortSignal;
 }
 
 export class Agent {
@@ -82,11 +117,28 @@ export class Agent {
 	private _compactionCount: number;
 	get compactionCount(): number { return this._compactionCount; }
 
-	/** 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. */
+	/** AbortController for cancelling this agent. Created at construction. */
+	readonly abortController: AbortController;
+	/** Promise for the full agent run (including post-processing). Set by run(). */
 	promise?: Promise<void>;
 
+	// Shared deps — optional (required for run())
+	private readonly _runner?: AgentRunner;
+	private readonly _worktrees?: WorktreeManager;
+	readonly observer?: AgentLifecycleObserver;
+	private readonly _getRunConfig?: () => RunConfig;
+
+	// Run config — optional (required for run())
+	private readonly _snapshot?: ParentSnapshot;
+	private readonly _prompt?: string;
+	private readonly _model?: Model<any>;
+	private readonly _maxTurns?: number;
+	private readonly _isolated?: boolean;
+	private readonly _thinkingLevel?: ThinkingLevel;
+	private readonly _isolation?: IsolationMode;
+	private readonly _parentSession?: ParentSessionInfo;
+	private readonly _signal?: AbortSignal;
+
 	// Phase-specific collaborators — each born complete when their info becomes available
 	execution?: ExecutionState;
 	worktreeState?: WorktreeState;
@@ -96,10 +148,14 @@ export class Agent {
 	 * Create a git worktree for isolated execution, set worktreeState, and return the worktree path.
 	 * Returns undefined if isolation is not "worktree".
 	 * Throws if worktree creation fails (strict isolation).
+	 * Uses this._worktrees and this._isolation (set at construction).
 	 */
-	setupWorktree(worktrees: WorktreeManager, isolation: IsolationMode | undefined): string | undefined {
-		if (isolation !== "worktree") return undefined;
-		const wt = worktrees.create(this.id);
+	setupWorktree(): string | undefined {
+		if (this._isolation !== "worktree") return undefined;
+		if (!this._worktrees) {
+			throw new Error("Agent not configured for worktree isolation — missing worktrees dependency");
+		}
+		const wt = this._worktrees.create(this.id);
 		if (!wt) {
 			throw new Error(
 				'Cannot run with isolation: "worktree" — not a git repo, no commits yet, or `git worktree add` failed. ' +
@@ -126,22 +182,107 @@ export class Agent {
 	}
 
 	constructor(init: AgentInit) {
+		// Identity
 		this.id = init.id;
 		this.type = init.type;
 		this.description = init.description;
 		this.invocation = init.invocation;
 
+		// Status
 		this._status = init.status ?? "queued";
 		this._result = init.result;
 		this._error = init.error;
 		this._startedAt = init.startedAt ?? Date.now();
 		this._completedAt = init.completedAt;
 
+		// Stats
 		this._toolUses = 0;
 		this._lifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
 		this._compactionCount = 0;
-		this.abortController = init.abortController;
-		this.promise = init.promise;
+
+		// Abort controller — always created, never injected
+		this.abortController = new AbortController();
+
+		// Shared deps
+		this._runner = init.runner;
+		this._worktrees = init.worktrees;
+		this.observer = init.observer;
+		this._getRunConfig = init.getRunConfig;
+
+		// Run config
+		this._snapshot = init.snapshot;
+		this._prompt = init.prompt;
+		this._model = init.model;
+		this._maxTurns = init.maxTurns;
+		this._isolated = init.isolated;
+		this._thinkingLevel = init.thinkingLevel;
+		this._isolation = init.isolation;
+		this._parentSession = init.parentSession;
+		this._signal = init.signal;
+
+		// Notification state — created from parentSession.toolCallId if present
+		if (init.parentSession?.toolCallId) {
+			this.notification = new NotificationState(init.parentSession.toolCallId);
+		}
+	}
+
+	/**
+	 * Execute the full agent lifecycle: worktree setup, runner invocation,
+	 * session-creation handling, observer wiring, worktree cleanup, and
+	 * status transitions.
+	 *
+	 * Requires runner and snapshot to be set at construction.
+	 * The returned promise always resolves (errors are captured internally).
+	 */
+	async run(): Promise<void> {
+		if (!this._runner) {
+			throw new Error("Agent not configured for execution — missing runner");
+		}
+		if (!this._snapshot || !this._prompt) {
+			throw new Error("Agent not configured for execution — missing snapshot or prompt");
+		}
+
+		this.markRunning(Date.now());
+		this.observer?.onStarted?.(this);
+		this.wireSignal(this._signal, () => this.abort());
+
+		try {
+			this.setupWorktree();
+		} catch (err) {
+			this.markError(err);
+			this.observer?.onRunFinished?.(this);
+			return;
+		}
+
+		const runConfig = this._getRunConfig?.();
+		try {
+			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
+				context: {
+					cwd: this.worktreeState?.path,
+					parentSession: this._parentSession,
+				},
+				model: this._model,
+				maxTurns: this._maxTurns,
+				defaultMaxTurns: runConfig?.defaultMaxTurns,
+				graceTurns: runConfig?.graceTurns,
+				isolated: this._isolated,
+				thinkingLevel: this._thinkingLevel,
+				signal: this.abortController.signal,
+				onSessionCreated: (session) => {
+					// 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;
+					this.execution = { session, outputFile };
+					this.flushPendingSteers(session);
+					this.attachObserver(subscribeAgentObserver(session, this, {
+						onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+					}));
+					this.observer?.onSessionCreated?.(this, session);
+				},
+			});
+			this.completeRun(result);
+		} catch (err) {
+			this.failRun(err);
+		}
 	}
 
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
@@ -226,7 +367,7 @@ export class Agent {
 	 */
 	abort(): boolean {
 		if (this._status !== "running") return false;
-		this.abortController?.abort();
+		this.abortController.abort();
 		this.markStopped();
 		return true;
 	}
@@ -258,13 +399,11 @@ export class Agent {
 		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 {
@@ -287,25 +426,13 @@ export class Agent {
 		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 {
+	/** Complete a run: release listeners, worktree cleanup, status transition, execution update, notify observer. */
+	completeRun(result: RunResult): void {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
-		if (this.worktreeState) {
-			const wtResult = this.worktreeState.performCleanup(worktrees, this.description);
+		if (this.worktreeState && this._worktrees) {
+			const wtResult = this.worktreeState.performCleanup(this._worktrees, this.description);
 			if (wtResult.hasChanges && wtResult.branch) {
 				finalResult += `\n\n---\nChanges saved to branch \`${wtResult.branch}\`. Merge with: \`git merge ${wtResult.branch}\``;
 			}
@@ -320,20 +447,20 @@ export class Agent {
 			outputFile: result.sessionFile ?? this.execution?.outputFile,
 		};
 
-		this.fireOnRunFinished();
+		this.observer?.onRunFinished?.(this);
 	}
 
-	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, fire onRunFinished. */
-	failRun(err: unknown, worktrees: WorktreeManager): void {
+	/** Fail a run: mark error, release listeners, best-effort worktree cleanup, notify observer. */
+	failRun(err: unknown): void {
 		this.markError(err);
 		this.releaseListeners();
 
-		if (this.worktreeState) {
+		if (this.worktreeState && this._worktrees) {
 			try {
-				this.worktreeState.performCleanup(worktrees, this.description);
+				this.worktreeState.performCleanup(this._worktrees, this.description);
 			} catch (cleanupErr) { debugLog("cleanupWorktree on agent error", cleanupErr); }
 		}
 
-		this.fireOnRunFinished();
+		this.observer?.onRunFinished?.(this);
 	}
 }

package/src/observation/record-observer.ts

@@ -6,8 +6,7 @@
  */
 
 import type { Agent } from "#src/lifecycle/agent";
-import type { CompactionInfo } from "#src/lifecycle/agent-manager";
-import type { SubscribableSession } from "#src/types";
+import type { CompactionInfo, SubscribableSession } from "#src/types";
 
 export interface AgentObserverOptions {
   onCompact?: (record: Agent, info: CompactionInfo) => void;

package/src/tools/agent-tool.ts

@@ -4,14 +4,14 @@ import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
 import { buildDetails, buildTypeListText, textResult } from "#src/tools/helpers";
 import { renderAgentResult } from "#src/tools/result-renderer";
 import { type ModelInfo, resolveSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent } from "#src/types";
+import type { Agent, ParentSessionInfo } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { type UICtx } from "#src/ui/agent-widget";
 import { type AgentDetails, getDisplayName } from "#src/ui/display";

package/src/tools/background-spawner.ts

@@ -1,9 +1,9 @@
-import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent } from "#src/types";
+import type { Agent, ParentSessionInfo } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import { subscribeUIObserver } from "#src/ui/ui-observer";
 
@@ -54,9 +54,11 @@ export function spawnBackground(
       isBackground: true,
       isolation: execution.isolation,
       invocation: execution.agentInvocation,
-      onSessionCreated: (session) => {
-        bgState.setSession(session);
-        subscribeUIObserver(session, bgState);
+      observer: {
+        onSessionCreated: (_agent, session) => {
+          bgState.setSession(session);
+          subscribeUIObserver(session, bgState);
+        },
       },
     });
   } catch (err) {

package/src/tools/foreground-runner.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
-import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import {
@@ -9,7 +9,7 @@ import {
   textResult,
 } from "#src/tools/helpers";
 import type { ResolvedSpawnConfig } from "#src/tools/spawn-config";
-import type { Agent } from "#src/types";
+import type { Agent, ParentSessionInfo } from "#src/types";
 import { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import {
   type AgentDetails,
@@ -109,13 +109,15 @@ export async function runForeground(
         invocation: execution.agentInvocation,
         signal,
         parentSession: params.parentSession,
-        onSessionCreated: (session, record) => {
-          fgState.setSession(session);
-          recordRef = record;
-          unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
-          fgId = record.id;
-          agentActivity.set(record.id, fgState);
-          widget.ensureTimer();
+        observer: {
+          onSessionCreated: (agent, session) => {
+            fgState.setSession(session);
+            recordRef = agent;
+            unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+            fgId = agent.id;
+            agentActivity.set(agent.id, fgState);
+            widget.ensureTimer();
+          },
         },
       },
     );

package/src/types.ts

@@ -105,3 +105,16 @@ export type ShellExec = (
   args: string[],
   options?: { cwd?: string; timeout?: number },
 ) => Promise<{ stdout: string; stderr: string; code: number }>;
+
+/** Parent session identity — grouped fields that travel together from the tool boundary. */
+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;
+}
+
+/** Compaction event info passed through lifecycle observers. */
+export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };