@gotgenes/pi-subagents 13.0.0 → 13.2.0

package/src/lifecycle/agent.ts

@@ -14,16 +14,16 @@
  * 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 (execution, notification) are attached
+ * Phase-specific collaborators (subagentSession, notification) are attached
  * 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 type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
-import type { AgentRunner, RunResult } from "#src/lifecycle/agent-runner";
-import type { ExecutionState } from "#src/lifecycle/execution-state";
+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 type { LifetimeUsage } from "#src/lifecycle/usage";
 import { addUsage } from "#src/lifecycle/usage";
 import type { Workspace, WorkspaceProvider } from "#src/lifecycle/workspace";
@@ -36,8 +36,8 @@ import type { AgentInvocation, CompactionInfo, ParentSessionInfo, SubagentType,
 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 the session is created — the agent's subagentSession is now available. */
+	onSessionCreated?(agent: Agent): void;
 	/** Fires once when the run completes or fails (for concurrency drain). */
 	onRunFinished?(agent: Agent): void;
 	/** Fires on compaction events during the run. */
@@ -68,7 +68,8 @@ export interface AgentInit {
 	error?: string;
 
 	// Shared deps (required for run(), optional for tests)
-	runner?: AgentRunner;
+	/** Assembly factory that produces a born-complete SubagentSession. */
+	createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	observer?: AgentLifecycleObserver;
 	getRunConfig?: () => RunConfig;
 	/** Resolves the registered workspace provider (if any) at run-start. */
@@ -126,7 +127,7 @@ export class Agent {
 	promise?: Promise<void>;
 
 	// Shared deps — optional (required for run())
-	private readonly _runner?: AgentRunner;
+	private readonly _createSubagentSession?: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
 	readonly observer?: AgentLifecycleObserver;
 	private readonly _getRunConfig?: () => RunConfig;
 	private readonly _getWorkspaceProvider?: () => WorkspaceProvider | undefined;
@@ -144,7 +145,8 @@ export class Agent {
 	private readonly _signal?: AbortSignal;
 
 	// Phase-specific collaborators — each born complete when their info becomes available
-	execution?: ExecutionState;
+	/** The born-complete child session — set when the factory returns inside run(). */
+	subagentSession?: SubagentSession;
 	notification?: NotificationState;
 
 	// Steer buffer — messages queued before the session is ready
@@ -152,14 +154,50 @@ export class Agent {
 	/** Number of steer messages waiting to be delivered. */
 	get pendingSteerCount(): number { return this._pendingSteers.length; }
 
-	/** The active agent session, or undefined before the session is created. */
-	get session(): AgentSession | undefined {
-		return this.execution?.session;
-	}
-
 	/** Path to the agent's session JSONL file, or undefined if not yet available. */
 	get outputFile(): string | undefined {
-		return this.execution?.outputFile;
+		return this.subagentSession?.outputFile;
+	}
+
+	/** Returns true when a SubagentSession is available (session is ready). */
+	isSessionReady(): boolean {
+		return this.subagentSession != null;
+	}
+
+	/**
+	 * Deliver or buffer a steer message.
+	 * Returns true when delivered immediately; false when buffered for later delivery.
+	 */
+	async steer(message: string): Promise<boolean> {
+		if (!this.subagentSession) {
+			this.queueSteer(message);
+			return false;
+		}
+		await this.subagentSession.steer(message);
+		return true;
+	}
+
+	/** Return the session conversation as formatted text, or undefined if no session. */
+	getConversation(): string | undefined {
+		return this.subagentSession?.getConversation();
+	}
+
+	/** Return the session context window utilization (0-100), or null if unavailable. */
+	getContextPercent(): number | null {
+		return this.subagentSession?.getContextPercent() ?? null;
+	}
+
+	/**
+	 * Subscribe to session events for live updates (e.g., conversation viewer).
+	 * Returns an unsubscribe function, or undefined if no session is available.
+	 */
+	subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined {
+		return this.subagentSession?.subscribe(fn);
+	}
+
+	/** The session's message history, or an empty array if no session. */
+	get messages(): readonly unknown[] {
+		return this.subagentSession?.messages ?? [];
 	}
 
 	constructor(init: AgentInit) {
@@ -185,7 +223,7 @@ export class Agent {
 		this.abortController = new AbortController();
 
 		// Shared deps
-		this._runner = init.runner;
+		this._createSubagentSession = init.createSubagentSession;
 		this.observer = init.observer;
 		this._getRunConfig = init.getRunConfig;
 		this._getWorkspaceProvider = init.getWorkspaceProvider;
@@ -207,16 +245,16 @@ export class Agent {
 	}
 
 	/**
-	 * Execute the full agent lifecycle: workspace preparation, runner invocation,
-	 * session-creation handling, observer wiring, workspace disposal, and
+	 * Execute the full agent lifecycle: workspace preparation, session creation
+	 * via the factory, observer wiring, the turn loop, workspace disposal, and
 	 * status transitions.
 	 *
-	 * Requires runner and snapshot to be set at construction.
+	 * Requires the session factory 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._createSubagentSession) {
+			throw new Error("Agent not configured for execution — missing session factory");
 		}
 		if (!this._snapshot || !this._prompt) {
 			throw new Error("Agent not configured for execution — missing snapshot or prompt");
@@ -247,29 +285,34 @@ export class Agent {
 			return;
 		}
 
-		const runConfig = this._getRunConfig?.();
 		try {
-			const result = await this._runner.run(this._snapshot, this.type, this._prompt, {
-				context: {
-					cwd,
-					parentSession: this._parentSession,
-				},
+			this.subagentSession = await this._createSubagentSession({
+				snapshot: this._snapshot,
+				type: this.type,
+				cwd,
+				parentSession: this._parentSession,
 				model: this._model,
+				thinkingLevel: this._thinkingLevel,
+			});
+		} catch (err) {
+			// The factory disposed its own session on a post-creation failure.
+			this.failRun(err);
+			return;
+		}
+
+		this.flushPendingSteers();
+		this.attachObserver(subscribeAgentObserver(this.subagentSession, this, {
+			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
+		}));
+		this.observer?.onSessionCreated?.(this);
+
+		const runConfig = this._getRunConfig?.();
+		try {
+			const result = await this.subagentSession.runTurnLoop(this._prompt, {
 				maxTurns: this._maxTurns,
 				defaultMaxTurns: runConfig?.defaultMaxTurns,
 				graceTurns: runConfig?.graceTurns,
-				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) {
@@ -281,27 +324,24 @@ export class Agent {
 	 * Resume an existing session with a new prompt, managing the observer
 	 * subscription lifecycle internally (same wiring as run()).
 	 *
-	 * Requires runner and an existing session (set when the original run created it).
+	 * Requires an existing SubagentSession (set when the original run created it).
 	 * The returned promise always resolves (errors are captured internally).
-	 * The parent signal flows straight through to runner.resume — resume does not
+	 * The parent signal flows straight through to resumeTurnLoop — resume does not
 	 * route through this.abortController.
 	 */
 	async resume(prompt: string, signal?: AbortSignal): Promise<void> {
-		if (!this._runner) {
-			throw new Error("Agent not configured for execution — missing runner");
-		}
-		const session = this.session;
-		if (!session) {
+		const subagentSession = this.subagentSession;
+		if (!subagentSession) {
 			throw new Error("Agent not configured for resume — missing session");
 		}
 
 		this.resetForResume(Date.now());
-		this.attachObserver(subscribeAgentObserver(session, this, {
+		this.attachObserver(subscribeAgentObserver(subagentSession, this, {
 			onCompact: (r, info) => this.observer?.onCompacted?.(r, info),
 		}));
 
 		try {
-			const responseText = await this._runner.resume(session, prompt, { signal });
+			const responseText = await subagentSession.resumeTurnLoop(prompt, signal);
 			this.markCompleted(responseText);
 		} catch (err) {
 			this.markError(err);
@@ -399,19 +439,19 @@ export class Agent {
 
 	/**
 	 * Buffer a steer message for delivery once the session is ready.
-	 * Called when steer is requested before onSessionCreated fires.
+	 * Called internally from steer() before the session is ready.
 	 */
-	queueSteer(message: string): void {
+	private queueSteer(message: string): void {
 		this._pendingSteers.push(message);
 	}
 
 	/**
 	 * Flush all buffered steer messages to the session and clear the buffer.
-	 * Called from onSessionCreated once the session is available.
+	 * Called once the session is available (inside run()).
 	 */
-	flushPendingSteers(session: AgentSession): void {
+	private flushPendingSteers(): void {
 		for (const msg of this._pendingSteers) {
-			session.steer(msg).catch(() => {});
+			this.subagentSession?.steer(msg).catch(() => {});
 		}
 		this._pendingSteers = [];
 	}
@@ -451,8 +491,8 @@ export class Agent {
 		this._detachFn = undefined;
 	}
 
-	/** Complete a run: release listeners, dispose the workspace, status transition, execution update, notify observer. */
-	completeRun(result: RunResult): void {
+	/** Complete a run: release listeners, dispose the workspace, status transition, notify observer. */
+	completeRun(result: TurnLoopResult): void {
 		this.releaseListeners();
 
 		let finalResult = result.responseText;
@@ -470,14 +510,14 @@ export class Agent {
 		else if (result.steered) this.markSteered(finalResult);
 		else this.markCompleted(finalResult);
 
-		this.execution = {
-			session: result.session,
-			outputFile: result.sessionFile ?? this.execution?.outputFile,
-		};
-
 		this.observer?.onRunFinished?.(this);
 	}
 
+	/** Dispose the wrapped session, firing the `disposed` lifecycle event. */
+	disposeSession(): void {
+		this.subagentSession?.dispose();
+	}
+
 	/** Fail a run: mark error, release listeners, best-effort workspace dispose, notify observer. */
 	failRun(err: unknown): void {
 		this.markError(err);

package/src/lifecycle/create-subagent-session.ts

@@ -0,0 +1,242 @@
+/**
+ * create-subagent-session.ts — Assembly factory for born-complete child sessions (issue #265).
+ *
+ * `createSubagentSession()` does the assembly portion that the old runner's
+ * `runAgent()` did up front: detect the environment, assemble the session config,
+ * create the SDK session, publish `spawning`/`session-created`, bind extensions,
+ * and apply the recursion guard. It returns a fully usable `SubagentSession` —
+ * `Agent` then only coordinates (turn loop, steer, dispose).
+ *
+ * The factory takes a resolved `cwd` value, never the WorkspaceProvider: `cwd`
+ * is a value the factory consumes directly (detectEnv, assembleSessionConfig,
+ * createSession), so threading the provider through here would be a relay smell.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  type AgentSession,
+  type SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import { SubagentSession } from "#src/lifecycle/subagent-session";
+import type { EnvInfo } from "#src/session/env";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
+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"];
+
+/**
+ * Apply the recursion guard: remove this extension's dispatch tools from the
+ * child's active set. Runs after `bindExtensions` so extension-registered tools
+ * are also covered. Unconditional: children always load the parent's extensions.
+ */
+function applyRecursionGuard(session: AgentSession): void {
+  const filtered = session
+    .getActiveToolNames()
+    .filter((t) => !EXCLUDED_TOOL_NAMES.includes(t));
+  session.setActiveToolsByName(filtered);
+}
+
+// ── IO boundary ───────────────────────────────────────────────────────────────
+
+/** Minimal resource-loader contract used by the factory. */
+export interface ResourceLoaderLike {
+  reload(): Promise<void>;
+}
+
+/** Minimal session-manager contract used by the factory. */
+export interface SessionManagerLike {
+  newSession(opts: { parentSession?: string }): void;
+  getSessionFile(): string | undefined;
+}
+
+/** Options passed to EnvironmentIO/SessionFactoryIO methods. */
+export interface ResourceLoaderOptions {
+  cwd: string;
+  agentDir: string;
+  noPromptTemplates?: boolean;
+  noThemes?: boolean;
+  noContextFiles?: boolean;
+  systemPromptOverride?: () => string;
+  /** Override the append system prompt. Receives the current base value; return the replacement. */
+  appendSystemPromptOverride?: (base: string[]) => string[];
+}
+
+/** Options passed to SessionFactoryIO.createSession. */
+export interface CreateSessionOptions {
+  cwd: string;
+  agentDir: string;
+  sessionManager: SessionManagerLike;
+  settingsManager: SettingsManager;
+  modelRegistry: unknown;
+  model?: unknown;
+  tools: string[];
+  resourceLoader: ResourceLoaderLike;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Environment discovery - detect runtime context and resolve directories.
+ *
+ * Decouples the factory from direct process/SDK reads so each can be stubbed
+ * independently in tests.
+ */
+export interface EnvironmentIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+}
+
+/**
+ * Session factory - create SDK objects for a child agent session.
+ *
+ * Decouples the factory from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface SessionFactoryIO {
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+
+/**
+ * IO boundary injected into createSubagentSession().
+ *
+ * Intersection of EnvironmentIO and SessionFactoryIO — callers satisfy both
+ * sub-interfaces via TypeScript's structural typing.
+ */
+export type SubagentSessionIO = EnvironmentIO & SessionFactoryIO;
+
+/**
+ * Dependencies injected at construction time — the IO boundary plus the two
+ * static domain deps (exec, registry) every creation needs.
+ */
+export interface SubagentSessionDeps {
+  io: SubagentSessionIO;
+  exec: ShellExec;
+  registry: AgentConfigLookup;
+  /** Publishes the child-execution lifecycle so consumers can observe it. */
+  lifecycle: ChildLifecyclePublisher;
+}
+
+/** Per-spawn parameters — the fields that vary per child session. */
+export interface CreateSubagentSessionParams {
+  snapshot: ParentSnapshot;
+  type: SubagentType;
+  /** Resolved workspace cwd; undefined → parent cwd. */
+  cwd?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+  model?: Model<any>;
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Build a born-complete SubagentSession: assemble config, create the SDK
+ * session, publish lifecycle events, bind extensions, apply the recursion guard.
+ */
+export async function createSubagentSession(
+  params: CreateSubagentSessionParams,
+  deps: SubagentSessionDeps,
+): Promise<SubagentSession> {
+  const { snapshot, type } = params;
+  const parentSessionId = params.parentSession?.parentSessionId;
+  deps.lifecycle.spawning({ agentName: type, parentSessionId });
+
+  // Resolve working directory upfront - needed for detectEnv before assembly.
+  const effectiveCwd = params.cwd ?? snapshot.cwd;
+  const env = await deps.io.detectEnv(deps.exec, effectiveCwd);
+
+  // Assemble session configuration (synchronous, no SDK objects).
+  const cfg = assembleSessionConfig(
+    type,
+    {
+      cwd: snapshot.cwd,
+      parentSystemPrompt: snapshot.systemPrompt,
+      parentModel: snapshot.model,
+      modelRegistry: snapshot.modelRegistry,
+    },
+    {
+      cwd: params.cwd,
+      model: params.model,
+      thinkingLevel: params.thinkingLevel,
+    },
+    env,
+    deps.registry,
+    deps.io.assemblerIO,
+  );
+
+  const agentDir = deps.io.getAgentDir();
+
+  // Children always load the parent's extensions and skills.
+  // Suppress AGENTS.md/CLAUDE.md and APPEND_SYSTEM.md - upstream's
+  // buildSystemPrompt() re-appends both AFTER systemPromptOverride, which
+  // would defeat prompt_mode: replace. Parent context, if wanted, reaches the
+  // subagent via prompt_mode: append (parentSystemPrompt is embedded in
+  // systemPromptOverride) or inherit_context (conversation).
+  const loader = deps.io.createResourceLoader({
+    cwd: cfg.effectiveCwd,
+    agentDir,
+    noPromptTemplates: true,
+    noThemes: true,
+    noContextFiles: true,
+    systemPromptOverride: () => cfg.systemPrompt,
+    appendSystemPromptOverride: () => [],
+  });
+  await loader.reload();
+
+  // 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 = deps.io.deriveSessionDir(params.parentSession?.parentSessionFile, cfg.effectiveCwd);
+  const sessionManager = deps.io.createSessionManager(cfg.effectiveCwd, sessionDir);
+  sessionManager.newSession({ parentSession: params.parentSession?.parentSessionId });
+
+  const { session } = await deps.io.createSession({
+    cwd: cfg.effectiveCwd,
+    agentDir,
+    sessionManager,
+    settingsManager: deps.io.createSettingsManager(cfg.effectiveCwd, agentDir),
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
+    tools: cfg.toolNames,
+    resourceLoader: loader,
+    thinkingLevel: cfg.thinkingLevel,
+  });
+
+  const subagentSession = new SubagentSession(session, {
+    outputFile: sessionManager.getSessionFile(),
+    sessionDir,
+    agentName: type,
+    agentMaxTurns: cfg.agentMaxTurns,
+    parentContext: snapshot.parentContext,
+    lifecycle: deps.lifecycle,
+  });
+
+  // Publish session-created before bindExtensions() so observers (e.g. the
+  // permission system) can register the child synchronously and have their
+  // entry in place for the first permission check during child extension
+  // initialization. The event bus dispatches synchronously, so a synchronous
+  // subscriber completes before this returns.
+  deps.lifecycle.sessionCreated({ sessionDir, agentName: type, parentSessionId });
+
+  try {
+    // Bind extensions so that session_start fires and extensions can initialize.
+    await session.bindExtensions({});
+    // Apply recursion guard after bindExtensions so extension-registered tools
+    // are included in the post-bind active set.
+    applyRecursionGuard(session);
+  } catch (err) {
+    // Binding failed after session-created — dispose (emit disposed +
+    // session.dispose()) before rethrowing so registration is never leaked.
+    subagentSession.dispose();
+    throw err;
+  }
+
+  return subagentSession;
+}