@yefengr/pi-subagents 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,265 @@
+/**
+ * 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 (with the recursion guard as a tool denylist), publish
+ * `spawning`/`session-created`, and bind extensions. 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,
+  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 { ModelRegistry } from "#src/session/model-resolver";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
+import type {
+  ParentSessionInfo,
+  ShellExec,
+  SubagentSessionIdentity,
+  SubagentType,
+  ThinkingLevel,
+} from "#src/types";
+
+/**
+ * Recursion guard: names of tools registered by this extension that subagents
+ * must NOT inherit. Passed to the SDK as a denylist, which it applies whenever
+ * it rebuilds the child's tool registry — including the rebuild triggered by a
+ * child extension registering a tool of its own. Filtering the active set once
+ * after `bindExtensions` would be undone by that rebuild (#725).
+ */
+const EXCLUDED_TOOL_NAMES = ["subagent", "get_subagent_result", "steer_subagent"];
+
+// ── 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;
+  /** Settings the loader resolves packages from; defaults to the ambient ones when absent. */
+  settingsManager?: SettingsManager;
+  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: ModelRegistry;
+  model?: Model<any>;
+  /** Allowlist: only these tool names are enabled in the session. */
+  tools: string[];
+  /** Denylist applied after `tools`, on every tool-registry rebuild. */
+  excludeTools?: 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;
+  /**
+   * Settings view the child's resource loader resolves packages from.
+   * The composition root decides whether any package extensions are excluded;
+   * the identity function reproduces the child's default full inheritance.
+   */
+  createLoaderSettingsManager: (parent: SettingsManager) => 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;
+  /** Captures stable child identity before extension binding can fail. */
+  onSessionCreated?: (identity: SubagentSessionIdentity) => void;
+  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();
+  const sessionSettings = deps.io.createSettingsManager(cfg.effectiveCwd, agentDir);
+  const loaderSettings = deps.io.createLoaderSettingsManager(sessionSettings);
+
+  // Children inherit the parent's skills and every extension the composition
+  // root did not exclude (#696).
+  //
+  // 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,
+    settingsManager: loaderSettings,
+    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: sessionSettings,
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
+    tools: cfg.toolNames,
+    excludeTools: EXCLUDED_TOOL_NAMES,
+    resourceLoader: loader,
+    thinkingLevel: cfg.thinkingLevel,
+  });
+
+  const outputFile = sessionManager.getSessionFile();
+  const subagentSession = new SubagentSession(session, {
+    outputFile,
+    sessionId,
+    sessionDir,
+    agentName: type,
+    parentContext: snapshot.parentContext,
+    lifecycle: deps.lifecycle,
+  });
+
+  params.onSessionCreated?.({ sessionId, outputFile });
+
+  // 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({});
+  } catch (err) {
+    // Binding failed after session-created — dispose (child session_shutdown +
+    // session.dispose() + emit disposed) before rethrowing so neither the
+    // registration nor a partially-initialized extension's resources leak.
+    await subagentSession.dispose();
+    throw err;
+  }
+
+  return subagentSession;
+}

package/src/lifecycle/invocation-control.ts

@@ -0,0 +1,109 @@
+export class InvocationTimeoutError extends Error {
+  constructor(readonly timeoutMs: number) {
+    super(`Subagent invocation timed out after ${Math.ceil(timeoutMs / 1000)} seconds`);
+    this.name = "InvocationTimeoutError";
+  }
+}
+
+export class InvocationCancelledError extends Error {
+  constructor() {
+    super("Subagent invocation was cancelled");
+    this.name = "InvocationCancelledError";
+  }
+}
+
+export interface InvocationControlOptions {
+  maxDurationMs: number;
+  abortGraceMs: number;
+  cancelSignal: AbortSignal;
+  onTimeout: () => void;
+}
+
+/**
+ * Applies one wall-clock budget to a complete invocation. An in-flight timeout
+ * or cancellation first aborts cooperative work, then releases the waiter after
+ * the abort grace when that work does not settle.
+ */
+export class InvocationControl {
+  private readonly timeoutController = new AbortController();
+  private readonly timeoutError: InvocationTimeoutError;
+  private readonly failure: Promise<never>;
+  private deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  private graceTimer: ReturnType<typeof setTimeout> | undefined;
+  private rejectFailure!: (reason: unknown) => void;
+  private timedOut = false;
+  private cancelled = false;
+  private disposed = false;
+
+  readonly signal: AbortSignal;
+
+  constructor(private readonly options: InvocationControlOptions) {
+    this.timeoutError = new InvocationTimeoutError(options.maxDurationMs);
+    this.signal = AbortSignal.any([options.cancelSignal, this.timeoutController.signal]);
+    this.failure = new Promise<never>((_resolve, reject) => {
+      this.rejectFailure = reject;
+    });
+    void this.failure.catch(() => {});
+
+    if (options.cancelSignal.aborted) {
+      this.rejectFailure(new InvocationCancelledError());
+    } else {
+      options.cancelSignal.addEventListener("abort", this.handleCancel, { once: true });
+    }
+
+    this.deadlineTimer = setTimeout(this.handleDeadline, options.maxDurationMs);
+    this.deadlineTimer.unref?.();
+  }
+
+  get didTimeOut(): boolean {
+    return this.timedOut;
+  }
+
+  async waitFor<T>(operation: Promise<T>): Promise<T> {
+    try {
+      const value = await Promise.race([operation, this.failure]);
+      if (this.timedOut) throw this.timeoutError;
+      return value;
+    } catch (error) {
+      if (this.timedOut) throw this.timeoutError;
+      throw error;
+    }
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    if (this.deadlineTimer) clearTimeout(this.deadlineTimer);
+    if (this.graceTimer) clearTimeout(this.graceTimer);
+    this.options.cancelSignal.removeEventListener("abort", this.handleCancel);
+  }
+
+  private readonly handleCancel = (): void => {
+    if (this.disposed || this.cancelled) return;
+    this.cancelled = true;
+    if (this.deadlineTimer) clearTimeout(this.deadlineTimer);
+    this.deadlineTimer = undefined;
+    this.graceTimer = setTimeout(
+      () => this.rejectFailure(new InvocationCancelledError()),
+      this.options.abortGraceMs,
+    );
+    this.graceTimer.unref?.();
+  };
+
+  private readonly handleDeadline = (): void => {
+    if (this.disposed || this.timedOut) return;
+    this.timedOut = true;
+    this.options.onTimeout();
+    this.timeoutController.abort(this.timeoutError);
+    this.graceTimer = setTimeout(() => this.rejectFailure(this.timeoutError), this.options.abortGraceMs);
+    this.graceTimer.unref?.();
+  };
+}
+
+export function isInvocationTimeout(error: unknown): error is InvocationTimeoutError {
+  return error instanceof InvocationTimeoutError;
+}
+
+export function isInvocationCancelled(error: unknown): error is InvocationCancelledError {
+  return error instanceof InvocationCancelledError;
+}

package/src/lifecycle/lifecycle-record.ts

@@ -0,0 +1,159 @@
+import type { Subagent } from "#src/lifecycle/subagent";
+import type { SubagentOutcome, SubagentPhase } from "#src/lifecycle/subagent-state";
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+
+export const SUBAGENT_LIFECYCLE_RECORD_VERSION = 3 as const;
+
+export interface LifecycleUsageV3 {
+	input: number;
+	output: number;
+	cacheWrite: number;
+	total: number;
+}
+
+export interface SubagentLifecycleDataV3 {
+	recordVersion: typeof SUBAGENT_LIFECYCLE_RECORD_VERSION;
+	id: string;
+	type: string;
+	description: string;
+	phase: SubagentPhase;
+	outcome?: SubagentOutcome;
+	isBackground: boolean;
+	invocationKind: "fresh" | "resume";
+	invocationSource: "tool" | "service";
+	invocationIndex: number;
+	toolCallId?: string;
+	sessionState: "created" | "not-created";
+	sessionId?: string;
+	outputFile?: string;
+	startedAt: number;
+	completedAt?: number;
+	durationMs: number;
+	result?: string;
+	error?: string;
+	invocationTurnCount: number;
+	lifetimeTurnCount: number;
+	maxTurns: number;
+	wrapUpTurns: number;
+	maxDurationSeconds: number;
+	invocationToolUses: number;
+	invocationUsage: LifecycleUsageV3;
+	lifetimeToolUses: number;
+	lifetimeUsage: LifecycleUsageV3;
+}
+
+export interface SubagentLifecycleRecordV3 extends SubagentLifecycleDataV3 {
+	phase: "terminal";
+	outcome: SubagentOutcome;
+	completedAt: number;
+}
+
+/** Build the shared lifecycle-v3 payload used by public events. */
+export function buildLifecycleEventData(record: Subagent): SubagentLifecycleDataV3 {
+	const completedAt = record.completedAt;
+	const session = lifecycleSessionFields(record);
+	return {
+		recordVersion: SUBAGENT_LIFECYCLE_RECORD_VERSION,
+		id: record.id,
+		type: record.type,
+		description: sanitizeDescription(record.description),
+		phase: record.phase,
+		...(record.outcome ? { outcome: record.outcome } : {}),
+		isBackground: record.isBackground,
+		invocationKind: record.lifecycleInvocation.kind,
+		invocationSource: record.lifecycleInvocation.source,
+		invocationIndex: record.invocationIndex,
+		...(record.toolCallId ? { toolCallId: record.toolCallId } : {}),
+		...session,
+		startedAt: record.invocationStartedAt,
+		...(completedAt == null ? {} : { completedAt }),
+		durationMs: Math.max(0, (completedAt ?? Date.now()) - record.invocationStartedAt),
+		result: record.result,
+		error: record.error,
+		invocationTurnCount: record.invocationTurnCount,
+		lifetimeTurnCount: record.lifetimeTurnCount,
+		maxTurns: record.maxTurns,
+		wrapUpTurns: record.wrapUpTurns,
+		maxDurationSeconds: record.maxDurationSeconds,
+		invocationToolUses: record.invocationToolUses,
+		invocationUsage: usageWithTotal(record.invocationUsage),
+		lifetimeToolUses: record.toolUses,
+		lifetimeUsage: usageWithTotal(record.lifetimeUsage),
+	};
+}
+
+/** Build a persisted terminal record, rejecting unsupported lifecycle states. */
+export function buildLifecycleRecord(record: Subagent): SubagentLifecycleRecordV3 {
+	assertTerminal(record.phase, record.outcome);
+	if (record.completedAt == null) {
+		throw new Error(`Lifecycle v3 terminal record ${record.id} is missing completedAt`);
+	}
+	if (record.sessionState === "not-created" && !allowsMissingSession(record)) {
+		throw new Error(
+			`Lifecycle v3 ${record.outcome} record ${record.id} cannot omit sessionId`,
+		);
+	}
+	return buildLifecycleEventData(record) as SubagentLifecycleRecordV3;
+}
+
+/** Build a non-terminal steer event without inventing a separate invocation. */
+export function buildSteerLifecycleEvent(
+	record: Subagent,
+	instruction: string,
+): SubagentLifecycleDataV3 & { instruction: string } {
+	return { ...buildLifecycleEventData(record), instruction };
+}
+
+function lifecycleSessionFields(
+	record: Subagent,
+): Pick<SubagentLifecycleDataV3, "sessionState" | "sessionId" | "outputFile"> {
+	if (record.sessionState === "not-created") {
+		if (record.sessionId || record.outputFile) {
+			throw new Error(`Lifecycle v3 record ${record.id} has contradictory session identity`);
+		}
+		return { sessionState: "not-created" };
+	}
+	if (!record.sessionId?.trim()) {
+		throw new Error(`Lifecycle v3 record ${record.id} is missing sessionId`);
+	}
+	return {
+		sessionState: "created",
+		sessionId: record.sessionId,
+		...(record.outputFile ? { outputFile: record.outputFile } : {}),
+	};
+}
+
+function assertTerminal(phase: SubagentPhase, outcome: SubagentOutcome | undefined): void {
+	if (phase !== "terminal") {
+		throw new Error(`Lifecycle v3 records must be terminal; received phase ${phase}`);
+	}
+	if (outcome == null) {
+		throw new Error("Lifecycle v3 terminal records require an outcome");
+	}
+}
+
+/**
+ * A terminal record may omit the session identity only when no session can
+ * exist: failures before session creation, and never-started cancellations or
+ * queue timeouts (the agent was stopped while still queued).
+ */
+function allowsMissingSession(record: Subagent): boolean {
+	if (record.outcome === "error") return true;
+	return (
+		record.stoppedWhileQueued &&
+		(record.outcome === "cancelled" || record.outcome === "queue_timeout")
+	);
+}
+
+function usageWithTotal(usage: Readonly<LifetimeUsage>): LifecycleUsageV3 {
+	return {
+		input: usage.input,
+		output: usage.output,
+		cacheWrite: usage.cacheWrite,
+		total: usage.input + usage.output + usage.cacheWrite,
+	};
+}
+
+function sanitizeDescription(description: string): string {
+	return description.replace(/[\t\r\n]+/g, " ").replace(/\s{2,}/g, " ").trim();
+}

package/src/lifecycle/parent-snapshot.ts

@@ -0,0 +1,46 @@
+/**
+ * parent-snapshot.ts — Capture parent session state as a plain data snapshot.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { buildParentContext } from "#src/session/context";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import type { SessionContext } from "#src/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: Model<any> | undefined;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: ModelRegistry;
+  /** 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,41 @@
+/**
+ * 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;
+		if (signal.aborted) {
+			onAbort();
+			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;
+	}
+}