@gotgenes/pi-subagents 16.0.0 → 16.1.1

package/src/lifecycle/subagent-state.ts

@@ -0,0 +1,156 @@
+/**
+ * subagent-state.ts — SubagentState value object: lifecycle status and metrics.
+ *
+ * Owns the passive, readable state of a subagent — status, result, error,
+ * timestamps, and stats (toolUses, lifetimeUsage, compactionCount) — together
+ * with the transition methods (markRunning, markCompleted, …) and accumulation
+ * methods (incrementToolUses, addUsage, incrementCompactions) that mutate it.
+ *
+ * State is encapsulated behind getters; external code reads through them but
+ * mutates only via the transition/accumulation methods. The value object owns
+ * all of its own mutations — no field is written from outside.
+ *
+ * Subagent holds one of these privately and delegates its getters and mutation
+ * methods to it. Extracting it lets the lifecycle state machine and the
+ * session-event observer be unit-tested without constructing an executor.
+ */
+
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import { addUsage } from "#src/lifecycle/usage";
+
+export type SubagentStatus =
+	| "queued"
+	| "running"
+	| "completed"
+	| "steered"
+	| "aborted"
+	| "stopped"
+	| "error";
+
+export interface SubagentStateInit {
+	status?: SubagentStatus;
+	result?: string;
+	error?: string;
+	startedAt?: number;
+	completedAt?: number;
+}
+
+export class SubagentState {
+	// Transition state — encapsulated behind getters, mutated only via transition methods
+	private _status: SubagentStatus;
+	get status(): SubagentStatus { return this._status; }
+
+	private _result?: string;
+	get result(): string | undefined { return this._result; }
+
+	private _error?: string;
+	get error(): string | undefined { return this._error; }
+
+	private _startedAt: number;
+	get startedAt(): number { return this._startedAt; }
+
+	private _completedAt?: number;
+	get completedAt(): number | undefined { return this._completedAt; }
+
+	// Stats — accumulated via mutation methods, readable via getters
+	private _toolUses = 0;
+	get toolUses(): number { return this._toolUses; }
+
+	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
+	get lifetimeUsage(): Readonly<LifetimeUsage> { return this._lifetimeUsage; }
+
+	private _compactionCount = 0;
+	get compactionCount(): number { return this._compactionCount; }
+
+	constructor(init: SubagentStateInit = {}) {
+		this._status = init.status ?? "queued";
+		this._result = init.result;
+		this._error = init.error;
+		this._startedAt = init.startedAt ?? Date.now();
+		this._completedAt = init.completedAt;
+	}
+
+	/** Increment tool use count. Called by record-observer on tool_execution_end. */
+	incrementToolUses(): void {
+		this._toolUses++;
+	}
+
+	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
+	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
+		addUsage(this._lifetimeUsage, delta);
+	}
+
+	/** Increment compaction count. Called by record-observer on compaction_end. */
+	incrementCompactions(): void {
+		this._compactionCount++;
+	}
+
+	/** Transition to running state. Sets status and startedAt. */
+	markRunning(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+	}
+
+	/**
+	 * Transition to completed state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markCompleted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "completed";
+		}
+	}
+
+	/**
+	 * Transition to aborted state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markAborted(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "aborted";
+		}
+	}
+
+	/**
+	 * Transition to steered state.
+	 * Always sets result and completedAt (??=). Only changes status if not stopped.
+	 */
+	markSteered(result: string, completedAt?: number): void {
+		this._result = result;
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "steered";
+		}
+	}
+
+	/**
+	 * Transition to error state.
+	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
+	 */
+	markError(error: unknown, completedAt?: number): void {
+		this._error = error instanceof Error ? error.message : String(error);
+		this._completedAt ??= completedAt ?? Date.now();
+		if (this._status !== "stopped") {
+			this._status = "error";
+		}
+	}
+
+	/** Transition to stopped state. Always valid — no guard. */
+	markStopped(completedAt?: number): void {
+		this._status = "stopped";
+		this._completedAt = completedAt ?? Date.now();
+	}
+
+	/** Reset for resume: running status, new startedAt, clear completedAt/result/error. */
+	resetForResume(startedAt: number): void {
+		this._status = "running";
+		this._startedAt = startedAt;
+		this._completedAt = undefined;
+		this._result = undefined;
+		this._error = undefined;
+	}
+}

package/src/lifecycle/subagent.ts

@@ -24,8 +24,8 @@ import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { SubagentSession, TurnLoopResult } from "#src/lifecycle/subagent-session";
+import { SubagentState, type SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { LifetimeUsage } from "#src/lifecycle/usage";
-import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
@@ -44,50 +44,48 @@ export interface SubagentLifecycleObserver {
 	onCompacted?(agent: Subagent, info: CompactionInfo): void;
 }
 
-export type SubagentStatus =
-	| "queued"
-	| "running"
-	| "completed"
-	| "steered"
-	| "aborted"
-	| "stopped"
-	| "error";
+export type { SubagentStatus } from "#src/lifecycle/subagent-state";
 
-export interface SubagentInit {
-	// Identity
-	id: string;
-	type: SubagentType;
-	description: string;
-	invocation?: AgentInvocation;
-
-	// Status (for tests and restore scenarios)
-	status?: SubagentStatus;
-	startedAt?: number;
-	completedAt?: number;
-	result?: string;
-	error?: string;
-
-	// Shared deps (required for run(), optional for tests)
+/**
+ * The execution machinery a Subagent needs to run. A single mandatory
+ * collaborator: production (SubagentManager.spawn) always supplies it, so run()
+ * needs no "not configured" guards. The genuinely-optional behavior knobs stay
+ * optional; the four inputs run() cannot proceed without are required.
+ */
+export interface SubagentExecution {
 	/** Assembly factory that produces a born-complete SubagentSession. */
-	createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+	createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+	/** Immutable spawn-time parent snapshot handed to the session factory. */
+	snapshot: ParentSnapshot;
+	/** Initial prompt for the turn loop. */
+	prompt: string;
+	/** Parent working directory handed to a workspace provider's prepare(). */
+	baseCwd: string;
 	observer?: SubagentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
 	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
-	/** Parent working directory handed to a workspace provider's prepare(). */
-	baseCwd?: string;
-
-	// Run config (required for run(), optional for tests)
-	snapshot?: ParentSnapshot;
-	prompt?: string;
 	model?: Model<any>;
 	maxTurns?: number;
 	thinkingLevel?: ThinkingLevel;
 	parentSession?: ParentSessionInfo;
-	isBackground?: boolean;
 	signal?: AbortSignal;
 }
 
+export interface SubagentInit {
+	// Identity
+	id: string;
+	type: SubagentType;
+	description: string;
+	invocation?: AgentInvocation;
+
+	/** Execution machinery — always supplied; construct-complete, no test fallbacks. */
+	execution: SubagentExecution;
+
+	/** Lifecycle status and metrics. Defaults to a fresh queued state. */
+	state?: SubagentState;
+}
+
 export class Subagent {
 	// Identity — set once at construction
 	readonly id: string;
@@ -95,55 +93,28 @@ export class Subagent {
 	readonly description: string;
 	readonly invocation?: AgentInvocation;
 
-	// Transition state — encapsulated behind getters, mutated only via transition methods
-	private _status: SubagentStatus;
-	get status(): SubagentStatus { return this._status; }
-
-	private _result?: string;
-	get result(): string | undefined { return this._result; }
-
-	private _error?: string;
-	get error(): string | undefined { return this._error; }
-
-	private _startedAt: number;
-	get startedAt(): number { return this._startedAt; }
-
-	private _completedAt?: number;
-	get completedAt(): number | undefined { return this._completedAt; }
-
-	// Stats — accumulated via mutation methods, readable via getters
-	private _toolUses: number;
-	get toolUses(): number { return this._toolUses; }
-
-	private _lifetimeUsage: LifetimeUsage;
-	get lifetimeUsage(): Readonly<LifetimeUsage> { return this._lifetimeUsage; }
-
-	private _compactionCount: number;
-	get compactionCount(): number { return this._compactionCount; }
+	// Lifecycle status and metrics — owned by a private value object; getters and
+	// mutation methods below delegate to it one line.
+	private readonly state: SubagentState;
+	get status(): SubagentStatus { return this.state.status; }
+	get result(): string | undefined { return this.state.result; }
+	get error(): string | undefined { return this.state.error; }
+	get startedAt(): number { return this.state.startedAt; }
+	get completedAt(): number | undefined { return this.state.completedAt; }
+	get toolUses(): number { return this.state.toolUses; }
+	get lifetimeUsage(): Readonly<LifetimeUsage> { return this.state.lifetimeUsage; }
+	get compactionCount(): number { return this.state.compactionCount; }
 
 	/** 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 _createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
-	readonly observer?: SubagentLifecycleObserver;
-	private readonly _getRunConfig?: () => RunConfig;
-	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
-	private readonly _baseCwd: string;
+	// Execution machinery — a single mandatory collaborator (no per-field fallbacks).
+	private readonly execution: SubagentExecution;
 	/** Workspace prepared at run-start by a provider — undefined when none is registered. */
 	private _workspace?: Workspace;
 
-	// 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 _thinkingLevel?: ThinkingLevel;
-	private readonly _parentSession?: ParentSessionInfo;
-	private readonly _signal?: AbortSignal;
-
 	// Phase-specific collaborators — each born complete when their info becomes available
 	/** The born-complete child session — set when the factory returns inside run(). */
 	subagentSession?: SubagentSession;
@@ -207,40 +178,19 @@ export class Subagent {
 		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;
+		// Lifecycle status and metrics — fresh queued state unless one is supplied
+		this.state = init.state ?? new SubagentState();
 
 		// Abort controller — always created, never injected
 		this.abortController = new AbortController();
 
-		// Shared deps
-		this._createSubagentSession = init.createSubagentSession;
-		this.observer = init.observer;
-		this._getRunConfig = init.getRunConfig;
-		this._getWorkspaceProvider = init.getWorkspaceProvider;
-		this._baseCwd = init.baseCwd ?? "";
-
-		// Run config
-		this._snapshot = init.snapshot;
-		this._prompt = init.prompt;
-		this._model = init.model;
-		this._maxTurns = init.maxTurns;
-		this._thinkingLevel = init.thinkingLevel;
-		this._parentSession = init.parentSession;
-		this._signal = init.signal;
+		// Execution machinery — a single mandatory collaborator
+		this.execution = init.execution;
 
 		// Notification state — created from parentSession.toolCallId if present
-		if (init.parentSession?.toolCallId) {
-			this.notification = new NotificationState(init.parentSession.toolCallId);
+		const toolCallId = init.execution.parentSession?.toolCallId;
+		if (toolCallId) {
+			this.notification = new NotificationState(toolCallId);
 		}
 	}
 
@@ -249,31 +199,25 @@ export class Subagent {
 	 * via the factory, observer wiring, the turn loop, workspace disposal, and
 	 * status transitions.
 	 *
-	 * Requires the session factory and snapshot to be set at construction.
-	 * The returned promise always resolves (errors are captured internally).
+	 * Execution is supplied at construction (mandatory), so run() needs no
+	 * "not configured" guards. The returned promise always resolves (errors are
+	 * captured internally).
 	 */
 	async run(): Promise<void> {
-		if (!this._createSubagentSession) {
-			throw new Error("Subagent not configured for execution — missing session factory");
-		}
-		if (!this._snapshot || !this._prompt) {
-			throw new Error("Subagent not configured for execution — missing snapshot or prompt");
-		}
-
 		this.markRunning(Date.now());
-		this.observer?.onStarted?.(this);
-		this.wireSignal(this._signal, () => this.abort());
+		this.execution.observer?.onStarted?.(this);
+		this.wireSignal(this.execution.signal, () => this.abort());
 
 		let cwd: string | undefined;
 		try {
 			// A registered workspace provider supplies the child's cwd and owns its
 			// teardown; with no provider the child runs in the parent cwd.
-			const provider = this._getWorkspaceProvider?.();
+			const provider = this.execution.getWorkspaceProvider?.();
 			if (provider) {
 				this._workspace = await provider.prepare({
 					agentId: this.id,
 					agentType: this.type,
-					baseCwd: this._baseCwd,
+					baseCwd: this.execution.baseCwd,
 					invocation: this.invocation,
 				});
 				cwd = this._workspace?.cwd;
@@ -281,18 +225,18 @@ export class Subagent {
 		} catch (err) {
 			this.markError(err);
 			this.releaseListeners();
-			this.observer?.onRunFinished?.(this);
+			this.execution.observer?.onRunFinished?.(this);
 			return;
 		}
 
 		try {
-			this.subagentSession = await this._createSubagentSession({
-				snapshot: this._snapshot,
+			this.subagentSession = await this.execution.createSubagentSession({
+				snapshot: this.execution.snapshot,
 				type: this.type,
 				cwd,
-				parentSession: this._parentSession,
-				model: this._model,
-				thinkingLevel: this._thinkingLevel,
+				parentSession: this.execution.parentSession,
+				model: this.execution.model,
+				thinkingLevel: this.execution.thinkingLevel,
 			});
 		} catch (err) {
 			// The factory disposed its own session on a post-creation failure.
@@ -301,15 +245,15 @@ export class Subagent {
 		}
 
 		this.flushPendingSteers();
-		this.attachObserver(subscribeSubagentObserver(this.subagentSession, this, {
-			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		this.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
+			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
-		this.observer?.onSessionCreated?.(this);
+		this.execution.observer?.onSessionCreated?.(this);
 
-		const runConfig = this._getRunConfig?.();
+		const runConfig = this.execution.getRunConfig?.();
 		try {
-			const result = await this.subagentSession.runTurnLoop(this._prompt, {
-				maxTurns: this._maxTurns,
+			const result = await this.subagentSession.runTurnLoop(this.execution.prompt, {
+				maxTurns: this.execution.maxTurns,
 				defaultMaxTurns: runConfig?.defaultMaxTurns,
 				graceTurns: runConfig?.graceTurns,
 				signal: this.abortController.signal,
@@ -336,8 +280,8 @@ export class Subagent {
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeSubagentObserver(subagentSession, this, {
-			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		this.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
+			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 
 		try {
@@ -352,23 +296,22 @@ export class Subagent {
 
 	/** Increment tool use count. Called by record-observer on tool_execution_end. */
 	incrementToolUses(): void {
-		this._toolUses++;
+		this.state.incrementToolUses();
 	}
 
 	/** Accumulate a usage delta into lifetimeUsage. Called by record-observer on message_end. */
 	addUsage(delta: { input: number; output: number; cacheWrite: number }): void {
-		addUsage(this._lifetimeUsage, delta);
+		this.state.addUsage(delta);
 	}
 
 	/** Increment compaction count. Called by record-observer on compaction_end. */
 	incrementCompactions(): void {
-		this._compactionCount++;
+		this.state.incrementCompactions();
 	}
 
 	/** Transition to running state. Sets status and startedAt. */
 	markRunning(startedAt: number): void {
-		this._status = "running";
-		this._startedAt = startedAt;
+		this.state.markRunning(startedAt);
 	}
 
 	/**
@@ -376,11 +319,7 @@ export class Subagent {
 	 * Always sets result and completedAt (??=). Only changes status if not stopped.
 	 */
 	markCompleted(result: string, completedAt?: number): void {
-		this._result = result;
-		this._completedAt ??= completedAt ?? Date.now();
-		if (this._status !== "stopped") {
-			this._status = "completed";
-		}
+		this.state.markCompleted(result, completedAt);
 	}
 
 	/**
@@ -388,11 +327,7 @@ export class Subagent {
 	 * Always sets result and completedAt (??=). Only changes status if not stopped.
 	 */
 	markAborted(result: string, completedAt?: number): void {
-		this._result = result;
-		this._completedAt ??= completedAt ?? Date.now();
-		if (this._status !== "stopped") {
-			this._status = "aborted";
-		}
+		this.state.markAborted(result, completedAt);
 	}
 
 	/**
@@ -400,11 +335,7 @@ export class Subagent {
 	 * Always sets result and completedAt (??=). Only changes status if not stopped.
 	 */
 	markSteered(result: string, completedAt?: number): void {
-		this._result = result;
-		this._completedAt ??= completedAt ?? Date.now();
-		if (this._status !== "stopped") {
-			this._status = "steered";
-		}
+		this.state.markSteered(result, completedAt);
 	}
 
 	/**
@@ -412,26 +343,22 @@ export class Subagent {
 	 * Always sets error (formatted) and completedAt (??=). Only changes status if not stopped.
 	 */
 	markError(error: unknown, completedAt?: number): void {
-		this._error = error instanceof Error ? error.message : String(error);
-		this._completedAt ??= completedAt ?? Date.now();
-		if (this._status !== "stopped") {
-			this._status = "error";
-		}
+		this.state.markError(error, completedAt);
 	}
 
 	/** Transition to stopped state. Always valid — no guard. */
 	markStopped(completedAt?: number): void {
-		this._status = "stopped";
-		this._completedAt = completedAt ?? Date.now();
+		this.state.markStopped(completedAt);
 	}
 
 	/**
 	 * Abort a running agent: fire AbortController and transition to stopped.
 	 * Returns false if the agent is not running.
-	 * Queue removal is handled by SubagentManager via ConcurrencyQueue.dequeue().
+	 * A still-queued agent is stopped by SubagentManager; its scheduled thunk
+	 * then no-ops on the queued-status guard.
 	 */
 	abort(): boolean {
-		if (this._status !== "running") return false;
+		if (this.status !== "running") return false;
 		this.abortController.abort();
 		this.markStopped();
 		return true;
@@ -458,11 +385,7 @@ export class Subagent {
 
 	/** 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.state.resetForResume(startedAt);
 		this.releaseListeners();
 	}
 
@@ -510,7 +433,7 @@ export class Subagent {
 		else if (result.steered) this.markSteered(finalResult);
 		else this.markCompleted(finalResult);
 
-		this.observer?.onRunFinished?.(this);
+		this.execution.observer?.onRunFinished?.(this);
 	}
 
 	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
@@ -527,6 +450,6 @@ export class Subagent {
 			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
 		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
-		this.observer?.onRunFinished?.(this);
+		this.execution.observer?.onRunFinished?.(this);
 	}
 }

package/src/observation/record-observer.ts

@@ -1,40 +1,42 @@
 /**
- * record-observer.ts — Subscribes to session events and updates Subagent stats.
+ * record-observer.ts — Subscribes to session events and accumulates SubagentState stats.
  *
  * Replaces the scattered callback-wrapping logic in SubagentManager's startAgent()
- * and resume() with a single direct subscription.
+ * and resume() with a single direct subscription. The observer targets the
+ * SubagentState value object directly, so it carries no dependency on Subagent;
+ * the caller forwards itself to its own lifecycle observer via onCompact.
  */
 
-import type { Subagent } from "#src/lifecycle/subagent";
+import type { SubagentState } from "#src/lifecycle/subagent-state";
 import type { CompactionInfo, SubscribableSession } from "#src/types";
 
 export interface SubagentObserverOptions {
-  onCompact?: (record: Subagent, info: CompactionInfo) => void;
+  onCompact?: (info: CompactionInfo) => void;
 }
 
 /**
- * Subscribe to session events and accumulate stats on the subagent record.
+ * Subscribe to session events and accumulate stats on the subagent state.
  *
  * Handles:
- * - `tool_execution_end` → `record.incrementToolUses()`
- * - `message_end` (assistant, with usage) → `record.addUsage(…)`
- * - `compaction_end` (not aborted) → `record.incrementCompactions()`, call `onCompact`
+ * - `tool_execution_end` → `state.incrementToolUses()`
+ * - `message_end` (assistant, with usage) → `state.addUsage(…)`
+ * - `compaction_end` (not aborted) → `state.incrementCompactions()`, call `onCompact`
  *
  * @returns An unsubscribe function.
  */
 export function subscribeSubagentObserver(
   session: SubscribableSession,
-  record: Subagent,
+  state: SubagentState,
   options?: SubagentObserverOptions,
 ): () => void {
   return session.subscribe((event) => {
     if (event.type === "tool_execution_end") {
-      record.incrementToolUses();
+      state.incrementToolUses();
     }
 
     if (event.type === "message_end" && event.message.role === "assistant") {
       const u = event.message.usage;
-      record.addUsage({
+      state.addUsage({
         input: u.input,
         output: u.output,
         cacheWrite: u.cacheWrite,
@@ -42,8 +44,8 @@ export function subscribeSubagentObserver(
     }
 
     if (event.type === "compaction_end" && !event.aborted && event.result) {
-      record.incrementCompactions();
-      options?.onCompact?.(record, {
+      state.incrementCompactions();
+      options?.onCompact?.({
         reason: event.reason,
         tokensBefore: event.result.tokensBefore,
       });