@yandy0725/pi-subagents 0.1.0

package/src/lifecycle/child-lifecycle.ts

@@ -0,0 +1,88 @@
+/**
+ * child-lifecycle.ts — Child-execution lifecycle event contract and publisher.
+ *
+ * The core publishes its child-execution lifecycle as ordered events on the Pi
+ * event bus; reactive consumers (permissions, telemetry, UI) subscribe rather
+ * than the core reaching out to them (ADR 0002). This module owns the channel
+ * names, payload shapes, and the publisher that emits them.
+ *
+ * The publisher takes an injected `emit` callback so this module stays free of
+ * Pi SDK imports — `index.ts` wires it to `pi.events.emit`.
+ */
+
+/** Emitted at the start of a child run, before the session is created. */
+export const SUBAGENT_CHILD_SPAWNING = "subagents:child:spawning";
+
+/**
+ * Emitted after the child session is created, immediately before
+ * `bindExtensions()`. Carries the child session id consumers need to register
+ * the session in `SubagentSessionRegistry`. Subscribers must register
+ * synchronously so the entry lands before binding proceeds (see ADR 0002 /
+ * the event-bus synchronous-dispatch guarantee).
+ */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted after the child's prompt resolves (normal, steered, or aborted). */
+export const SUBAGENT_CHILD_COMPLETED = "subagents:child:completed";
+
+/** Emitted in the run's `finally` — always fires, on success and error. */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Payload for `subagents:child:spawning`. */
+export interface ChildSpawningEvent {
+	agentName: string;
+	parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:session-created`. */
+export interface ChildSessionCreatedEvent {
+	/** Child session id — the registry key. Unique per child; concurrent
+	 * siblings of the same parent occupy distinct keys. */
+	sessionId: string;
+	parentSessionId?: string;
+}
+
+/** Payload for `subagents:child:completed`. */
+export interface ChildCompletedEvent {
+	sessionDir: string;
+	agentName: string;
+	/** True if the run was hard-aborted (max turns + grace exceeded). */
+	aborted: boolean;
+	/** True if the run was steered to wrap up (soft turn limit) but finished. */
+	steered: boolean;
+}
+
+/** Payload for `subagents:child:disposed`. */
+export interface ChildDisposedEvent {
+	/** Child session id — the registry key. Must match `session-created`. */
+	sessionId: string;
+}
+
+/** Narrow emit seam — injected, never imports the Pi SDK. */
+export type LifecycleEmit = (channel: string, data: unknown) => void;
+
+/** Publishes the child-execution lifecycle on the event bus. */
+export interface ChildLifecyclePublisher {
+	spawning(event: ChildSpawningEvent): void;
+	sessionCreated(event: ChildSessionCreatedEvent): void;
+	completed(event: ChildCompletedEvent): void;
+	disposed(event: ChildDisposedEvent): void;
+}
+
+/** Build a publisher backed by an injected `emit` callback. */
+export function createChildLifecyclePublisher(emit: LifecycleEmit): ChildLifecyclePublisher {
+	return {
+		spawning(event) {
+			emit(SUBAGENT_CHILD_SPAWNING, event);
+		},
+		sessionCreated(event) {
+			emit(SUBAGENT_CHILD_SESSION_CREATED, event);
+		},
+		completed(event) {
+			emit(SUBAGENT_CHILD_COMPLETED, event);
+		},
+		disposed(event) {
+			emit(SUBAGENT_CHILD_DISPOSED, event);
+		},
+	};
+}

package/src/lifecycle/concurrency-limiter.ts

@@ -0,0 +1,55 @@
+/**
+ * concurrency-limiter.ts — FIFO admission gate for background work.
+ *
+ * Schedules run closures (thunks) against a dynamic limit, running them in
+ * scheduling order as slots free. The limiter knows nothing about agents, IDs,
+ * or the manager — it owns only the active count and the pending queue.
+ *
+ * Every scheduled promise settles: it follows the task's settlement when the
+ * task runs, or resolves early if clear() drops it before it starts.
+ */
+
+export class ConcurrencyLimiter {
+	private active = 0;
+	private readonly pending: Array<{ start: () => void; settle: () => void }> = [];
+
+	constructor(private readonly getLimit: () => number) {}
+
+	/**
+	 * Schedule a task to run FIFO once a slot is free.
+	 * Returns a promise that settles with the task, or resolves early if the
+	 * task is dropped by clear() before it starts.
+	 */
+	schedule(task: () => Promise<void>): Promise<void> {
+		const { promise, resolve, reject } = Promise.withResolvers<void>(); // eslint-disable-line @typescript-eslint/no-invalid-void-type -- Promise.withResolvers<void> is valid; rule does not allow void in generic fn call type args
+		this.pending.push({
+			start: () => {
+				this.active++;
+				task()
+					.then(resolve, reject)
+					.finally(() => {
+						this.active--;
+						this.recheck();
+					});
+			},
+			settle: resolve,
+		});
+		this.recheck();
+		return promise;
+	}
+
+	/** Start pending tasks until the limit is reached. Call when the limit may have grown. */
+	recheck(): void {
+		while (this.active < this.getLimit()) {
+			const next = this.pending.shift();
+			if (!next) break;
+			next.start();
+		}
+	}
+
+	/** Drop all pending tasks, resolving their promises without running them. */
+	clear(): void {
+		const dropped = this.pending.splice(0);
+		for (const task of dropped) task.settle();
+	}
+}

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

@@ -0,0 +1,240 @@
+/**
+ * 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` —
+ * `Subagent` 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, SettingsManager } from "@earendil-works/pi-coding-agent";
+import type { AgentConfigLookup } from "../config/agent-types";
+import type { ChildLifecyclePublisher } from "../lifecycle/child-lifecycle";
+import type { ParentSnapshot } from "../lifecycle/parent-snapshot";
+import { SubagentSession } from "../lifecycle/subagent-session";
+import type { EnvInfo } from "../session/env";
+import { type AssemblerIO, assembleSessionConfig } from "../session/session-config";
+import type { ParentSessionInfo, ShellExec, SubagentType, ThinkingLevel } from "../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;
+	getSessionId(): string;
+}
+
+/** 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 sessionId = sessionManager.getSessionId();
+
+	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(),
+		sessionId,
+		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({ sessionId, 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;
+}

package/src/lifecycle/parent-snapshot.ts

@@ -0,0 +1,45 @@
+/**
+ * parent-snapshot.ts — Capture parent session state as a plain data snapshot.
+ */
+
+import { buildParentContext } from "../session/context";
+import type { SessionContext } from "../types";
+
+/**
+ * Plain data snapshot of the parent session state captured at spawn time.
+ * Replaces live `ExtensionContext` references so queued agents don't read stale state.
+ */
+export interface ParentSnapshot {
+	/** Parent working directory. */
+	cwd: string;
+	/** Parent's effective system prompt (for append-mode agents). */
+	systemPrompt: string;
+	/** Parent's current model instance (fallback when agent config has no model). */
+	model: unknown;
+	/** Model registry for resolving config.model strings and creating sessions. */
+	modelRegistry: {
+		find(provider: string, modelId: string): unknown;
+		getAvailable?(): Array<{ provider: string; id: string }>;
+	};
+	/** Pre-built parent conversation text (when inheritContext was requested). */
+	parentContext?: string;
+}
+
+/**
+ * Build an immutable snapshot of the parent session state.
+ *
+ * Called once at spawn time so queued agents capture state as it existed
+ * when the user requested the agent, not when a queue slot opens.
+ */
+export function buildParentSnapshot(ctx: SessionContext, inheritContext?: boolean): ParentSnapshot {
+	const parentContext = inheritContext ? buildParentContext(ctx) : undefined;
+	return {
+		cwd: ctx.cwd,
+		systemPrompt: ctx.getSystemPrompt(),
+		model: ctx.model,
+
+		modelRegistry: ctx.modelRegistry!,
+		// eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: converts empty string to undefined as well as null/undefined
+		parentContext: parentContext || undefined,
+	};
+}

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;
+	}
+}