@gotgenes/pi-subagents 16.2.0 → 16.2.2

package/src/lifecycle/run-listeners.ts

@@ -0,0 +1,37 @@
+/**
+ * run-listeners.ts — Per-run observer-unsubscribe and signal-detach handles.
+ *
+ * Owns the two teardown handles that a Subagent wires at run start (signal
+ * listener) and after session creation (record-observer unsub), releasing
+ * both atomically when the run ends or the agent is resumed.
+ */
+
+/** Owns the per-run observer-unsubscribe and signal-detach handles. */
+export class RunListeners {
+	private unsub?: () => void;
+	private detach?: () => void;
+
+	/**
+	 * Wire a parent AbortSignal so it triggers onAbort when fired.
+	 * No-op when signal is undefined.
+	 */
+	wireSignal(signal: AbortSignal | undefined, onAbort: () => void): void {
+		if (!signal) return;
+		const listener = () => onAbort();
+		signal.addEventListener("abort", listener, { once: true });
+		this.detach = () => signal.removeEventListener("abort", listener);
+	}
+
+	/** Store the record-observer unsubscribe handle. */
+	attachObserver(unsub: () => void): void {
+		this.unsub = unsub;
+	}
+
+	/** Release the observer + signal handles. Idempotent. */
+	release(): void {
+		this.unsub?.();
+		this.unsub = undefined;
+		this.detach?.();
+		this.detach = undefined;
+	}
+}

package/src/lifecycle/subagent-manager.ts

@@ -168,12 +168,14 @@ export class SubagentManager {
     }
 
     if (options.isBackground && !options.bypassQueue) {
-      // Schedule on the limiter — start() guards against abort-while-queued.
-      void this.limiter.schedule(() => record.start());
+      // Schedule on the limiter — scheduleVia captures the limiter promise
+      // eagerly, so a queued agent is awaitable from spawn; guardedRun guards
+      // against abort-while-queued when the slot frees.
+      record.scheduleVia((thunk) => this.limiter.schedule(thunk));
       return id;
     }
 
-    void record.start();
+    record.start();
     return id;
   }
 

package/src/lifecycle/subagent.ts

@@ -1,21 +1,9 @@
 /**
- * subagent.ts — Subagent class with encapsulated status-transition logic and per-subagent behavior.
+ * subagent.ts — Subagent class: identity, lifecycle status, and per-subagent behavior.
  *
- * Status transitions (status, result, error, startedAt, completedAt) are owned
- * by the class and exposed via transition methods. External code reads these
- * fields through public properties but cannot write them directly.
- *
- * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
- * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
- *
- * Behavior (abort, steer buffering) lives on the subagent rather than on
- * SubagentManager — each subagent manages its own lifecycle concerns.
- *
- * The child's working directory is supplied by a registered WorkspaceProvider
- * (the workspace seam); with no provider the child runs in the parent cwd.
- *
- * Phase-specific collaborators (subagentSession, notification) are attached
- * after construction as lifecycle information becomes available.
+ * Status/stats are delegated to the SubagentState value object; listener
+ * lifecycle to RunListeners; workspace prepare/dispose to WorkspaceBracket.
+ * Behavior (abort, steer buffering) lives here rather than on SubagentManager.
  */
 
 import type { Model } from "@earendil-works/pi-ai";
@@ -23,10 +11,12 @@ import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { RunListeners } from "#src/lifecycle/run-listeners";
 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 type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+import { WorkspaceBracket } from "#src/lifecycle/workspace-bracket";
 import { NotificationState } from "#src/observation/notification-state";
 import { subscribeSubagentObserver } from "#src/observation/record-observer";
 import type { RunConfig } from "#src/runtime";
@@ -105,23 +95,16 @@ export class Subagent {
 	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;
-	/** Backing store for the run promise. Set by start(). */
 	private _promise?: Promise<void>;
-	/** Awaitable handle to the running promise. Set by start(). */
 	get promise(): Promise<void> | undefined { return this._promise; }
 
-	// 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;
+	private readonly listeners = new RunListeners();
+	private readonly workspaceBracket: WorkspaceBracket;
 
-	// 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;
 	private _notification?: NotificationState;
-	/** Notification state for background agents — wired from parentSession.toolCallId. */
 	get notification(): NotificationState | undefined { return this._notification; }
 
 	// Steer buffer — messages queued before the session is ready
@@ -191,6 +174,11 @@ export class Subagent {
 		// Execution machinery — a single mandatory collaborator
 		this.execution = init.execution;
 
+		// Per-run lifecycle collaborators
+		this.workspaceBracket = new WorkspaceBracket(
+			this.execution.getWorkspaceProvider ?? (() => undefined),
+		);
+
 		// Notification state — created from parentSession.toolCallId if present
 		const toolCallId = init.execution.parentSession?.toolCallId;
 		if (toolCallId) {
@@ -210,27 +198,26 @@ export class Subagent {
 	async run(): Promise<void> {
 		this.markRunning(Date.now());
 		this.execution.observer?.onStarted?.(this);
-		this.wireSignal(this.execution.signal, () => this.abort());
+		this.listeners.wireSignal(this.execution.signal, () => this.abort());
 
+		// Guard the await so the no-provider path stays synchronous, preserving
+		// the original run() timing: the factory is called in the same turn as
+		// spawn() when no workspace provider is registered.
 		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.execution.getWorkspaceProvider?.();
-			if (provider) {
-				this._workspace = await provider.prepare({
+		if (this.workspaceBracket.hasProvider()) {
+			try {
+				cwd = await this.workspaceBracket.prepare({
 					agentId: this.id,
 					agentType: this.type,
 					baseCwd: this.execution.baseCwd,
 					invocation: this.invocation,
 				});
-				cwd = this._workspace?.cwd;
+			} catch (err) {
+				this.markError(err);
+				this.listeners.release();
+				this.execution.observer?.onRunFinished?.(this);
+				return;
 			}
-		} catch (err) {
-			this.markError(err);
-			this.releaseListeners();
-			this.execution.observer?.onRunFinished?.(this);
-			return;
 		}
 
 		try {
@@ -249,7 +236,7 @@ export class Subagent {
 		}
 
 		this.flushPendingSteers();
-		this.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
+		this.listeners.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
 			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 		this.execution.observer?.onSessionCreated?.(this);
@@ -269,19 +256,32 @@ export class Subagent {
 	}
 
 	/**
-	 * Start execution: call run(), store the promise internally, and return it.
-	 *
-	 * Guards against non-active states (e.g. abort-while-queued): if the agent
-	 * is neither queued nor running, the promise resolves immediately (no-op).
-	 * This folds the inline status guard out of SubagentManager's limiter callback.
+	 * Start execution immediately (foreground / bypassQueue paths).
+	 * Stores the run promise so it is awaitable via the `promise` getter.
 	 */
-	start(): Promise<void> {
-		if (this.status !== "queued" && this.status !== "running") {
-			this._promise = Promise.resolve();
-			return this._promise;
-		}
-		this._promise = this.run();
-		return this._promise;
+	start(): void {
+		this._promise = this.guardedRun();
+	}
+
+	/**
+	 * Schedule execution through an external concurrency scheduler (the limiter).
+	 * Captures the scheduler's promise eagerly, so a still-queued agent is
+	 * awaitable via the `promise` getter from spawn — not only once its slot opens.
+	 * The guard in guardedRun() makes an abort-while-queued run a no-op when the
+	 * slot finally frees.
+	 */
+	scheduleVia(schedule: (thunk: () => Promise<void>) => Promise<void>): void {
+		this._promise = schedule(() => this.guardedRun());
+	}
+
+	/**
+	 * Run unless the agent left the active set before its slot opened
+	 * (e.g. abort-while-queued): a non-queued, non-running status resolves
+	 * immediately without running.
+	 */
+	private guardedRun(): Promise<void> {
+		if (this.status !== "queued" && this.status !== "running") return Promise.resolve();
+		return this.run();
 	}
 
 	/**
@@ -300,7 +300,7 @@ export class Subagent {
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
+		this.listeners.attachObserver(subscribeSubagentObserver(subagentSession, this.state, {
 			onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
 		}));
 
@@ -310,7 +310,7 @@ export class Subagent {
 		} catch (err) {
 			this.markError(err);
 		} finally {
-			this.releaseListeners();
+			this.listeners.release();
 		}
 	}
 
@@ -406,48 +406,21 @@ export class Subagent {
 	/** Reset for resume: running status, new startedAt, clear completedAt/result/error/listeners. */
 	resetForResume(startedAt: number): void {
 		this.state.resetForResume(startedAt);
-		this.releaseListeners();
-	}
-
-	// --- Per-run listener state (released on completion or resume reset) ---
-	private _unsub?: () => void;
-	private _detachFn?: () => 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;
+		this.listeners.release();
 	}
 
 	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
 	completeRun(result: TurnLoopResult): void {
-		this.releaseListeners();
-
-		let finalResult = result.responseText;
-		if (this._workspace) {
-			const finalStatus: SubagentStatus = result.aborted
-				? "aborted"
-				: result.steered
-					? "steered"
-					: "completed";
-			const disposeResult = this._workspace.dispose({ status: finalStatus, description: this.description });
-			if (disposeResult?.resultAddendum) finalResult += disposeResult.resultAddendum;
-		}
+		this.listeners.release();
+
+		const finalStatus: SubagentStatus = result.aborted
+			? "aborted"
+			: result.steered
+				? "steered"
+				: "completed";
+		const finalResult =
+			result.responseText +
+			this.workspaceBracket.dispose({ status: finalStatus, description: this.description });
 
 		if (result.aborted) this.markAborted(finalResult);
 		else if (result.steered) this.markSteered(finalResult);
@@ -464,10 +437,10 @@ export class Subagent {
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);
-		this.releaseListeners();
+		this.listeners.release();
 
 		try {
-			if (this._workspace) this._workspace.dispose({ status: "error", description: this.description });
+			this.workspaceBracket.dispose({ status: "error", description: this.description });
 		} catch (cleanupErr) { debugLog("workspace dispose on agent error", cleanupErr); }
 
 		this.execution.observer?.onRunFinished?.(this);

package/src/lifecycle/workspace-bracket.ts

@@ -0,0 +1,59 @@
+/**
+ * workspace-bracket.ts — Owned prepare/dispose lifecycle for a child workspace.
+ *
+ * Captures the provider resolver (not the provider itself) so provider
+ * resolution stays lazy at run-start. The prepared Workspace is held
+ * privately; dispose() centralises the guard and addendum-unwrap so callers
+ * never reach through to workspace.dispose().resultAddendum directly.
+ *
+ * dispose() deliberately does NOT catch errors — the best-effort try/catch
+ * for failRun() belongs at the call site, preserving the per-caller semantics.
+ */
+
+import type {
+	Workspace,
+	WorkspaceDisposeOutcome,
+	WorkspacePrepareContext,
+	WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+/** Owns the child workspace lifecycle: prepare at run-start, dispose at run-end. */
+export class WorkspaceBracket {
+	private prepared?: Workspace;
+
+	constructor(private readonly resolveProvider: () => WorkspaceProvider | undefined) {}
+
+	/**
+	 * Returns true when a workspace provider is currently registered.
+	 * Use to guard the `await prepare(...)` call and avoid an unnecessary
+	 * microtask boundary in the no-provider path.
+	 */
+	hasProvider(): boolean {
+		return this.resolveProvider() !== undefined;
+	}
+
+	/**
+	 * Resolve the registered provider and prepare the child workspace.
+	 * Returns the workspace's cwd, or undefined when no provider is registered
+	 * or the provider resolves to undefined.
+	 */
+	async prepare(ctx: WorkspacePrepareContext): Promise<string | undefined> {
+		const provider = this.resolveProvider();
+		if (!provider) return undefined;
+		this.prepared = await provider.prepare(ctx);
+		return this.prepared?.cwd;
+	}
+
+	/**
+	 * Dispose the prepared workspace (if any) and return the result addendum
+	 * verbatim. Returns an empty string when no workspace was prepared or when
+	 * the workspace returns no addendum.
+	 *
+	 * Throws propagate — wrap in try/catch at the call site when best-effort
+	 * disposal is desired (e.g. failRun).
+	 */
+	dispose(outcome: WorkspaceDisposeOutcome): string {
+		if (!this.prepared) return "";
+		return this.prepared.dispose(outcome)?.resultAddendum ?? "";
+	}
+}

package/src/observation/subagent-events-observer.ts

@@ -0,0 +1,97 @@
+import type { SubagentManagerObserver } from "#src/lifecycle/subagent-manager";
+import { buildEventData, type NotificationSystem } from "#src/observation/notification";
+import type { CompactionInfo, Subagent } from "#src/types";
+
+/** Emit callback — a subset of `pi.events.emit`. */
+export type EventEmit = (channel: string, data: unknown) => void;
+
+/** Append callback — a subset of `pi.appendEntry`. */
+export type AppendEntry = (customType: string, data: unknown) => void;
+
+export interface SubagentEventsObserverDeps {
+	emit: EventEmit;
+	appendEntry: AppendEntry;
+	notifications: NotificationSystem;
+}
+
+/**
+ * Receives agent lifecycle notifications from SubagentManager and dispatches
+ * them to three concerns: pi.events lifecycle events, session-entry persistence,
+ * and completion notifications.
+ *
+ * Constructed with narrow deps (emit, appendEntry, NotificationSystem) so all
+ * three concerns are unit-testable without booting the extension.
+ */
+export class SubagentEventsObserver implements SubagentManagerObserver {
+	private readonly emit: EventEmit;
+	private readonly appendEntry: AppendEntry;
+	private readonly notifications: NotificationSystem;
+
+	constructor(deps: SubagentEventsObserverDeps) {
+		this.emit = deps.emit;
+		this.appendEntry = deps.appendEntry;
+		this.notifications = deps.notifications;
+	}
+
+	onSubagentStarted(record: Subagent): void {
+		// Emit started event when agent transitions to running (including from queue).
+		this.emit("subagents:started", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+		});
+	}
+
+	onSubagentCompleted(record: Subagent): void {
+		// Emit lifecycle event based on terminal status.
+		const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
+		const eventData = buildEventData(record);
+		if (isError) {
+			this.emit("subagents:failed", eventData);
+		} else {
+			this.emit("subagents:completed", eventData);
+		}
+
+		// Persist final record for cross-extension history reconstruction.
+		this.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.notification?.resultConsumed) {
+			this.notifications.cleanupCompleted(record.id);
+			return;
+		}
+
+		this.notifications.sendCompletion(record);
+	}
+
+	onSubagentCompacted(record: Subagent, info: CompactionInfo): void {
+		// Emit compacted event when agent's session compacts (preserves count on record).
+		this.emit("subagents:compacted", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			reason: info.reason,
+			tokensBefore: info.tokensBefore,
+			compactionCount: record.compactionCount,
+		});
+	}
+
+	onSubagentCreated(record: Subagent): void {
+		// Emit created event for background agents (before limiter admission).
+		this.emit("subagents:created", {
+			id: record.id,
+			type: record.type,
+			description: record.description,
+			isBackground: true,
+		});
+	}
+}