@jopqior/pi-subagents 1.0.0

package/src/lifecycle/child-lifecycle.ts

@@ -0,0 +1,115 @@
+/**
+ * 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`.
+ *
+ * `spawning`, `session-created`, `completed`, and `disposed` are the announcement
+ * a consumer may rely on. `bound` is additional: it reports that a child finished
+ * binding its extensions, which is the only moment a parent can observe what those
+ * extensions did or did not install.
+ */
+
+/** 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 once the child's extensions have bound, after every child
+ * `session_start` handler has run and before the child takes its first turn.
+ *
+ * Skipped when binding throws: that child never runs, so there is nothing to
+ * report about it.
+ */
+export const SUBAGENT_CHILD_BOUND = "subagents:child:bound";
+
+/** 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:bound`. */
+export interface ChildBoundEvent {
+  /** Child session id — the same key `session-created` carried. */
+  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;
+  bound(event: ChildBoundEvent): 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);
+    },
+    bound(event) {
+      emit(SUBAGENT_CHILD_BOUND, event);
+    },
+    completed(event) {
+      emit(SUBAGENT_CHILD_COMPLETED, event);
+    },
+    disposed(event) {
+      emit(SUBAGENT_CHILD_DISPOSED, event);
+    },
+  };
+}

package/src/lifecycle/child-shutdown.ts

@@ -0,0 +1,105 @@
+/**
+ * child-shutdown.ts — Bounded `session_shutdown` emission for a child session (issue #709).
+ *
+ * A child session binds the full extension set, so `session_start` fires and every
+ * inherited extension initializes. Pi's `AgentSession.dispose()` does not emit the
+ * matching `session_shutdown` — only `AgentSessionRuntime` does, and children do not
+ * use that path — so extension-owned subprocesses, timers, and sockets outlive the
+ * child. This module supplies the missing half of the pair.
+ *
+ * Two constraints shape it:
+ *
+ * 1. `AgentSession.dispose()` invalidates the extension runner, and every `ctx`
+ *    accessor throws once invalidated. The emit must therefore be awaited to
+ *    completion *before* disposal, never fired and forgotten alongside it.
+ * 2. Pi's runner catches each handler's errors but does not bound a handler that
+ *    hangs. An unbounded await here would stall the parent's teardown and Pi's exit,
+ *    so the emit races a timeout and teardown proceeds either way.
+ *
+ * Nothing here throws: a child that will not shut down cleanly must still be disposed.
+ */
+
+import { debugLog } from "#src/debug";
+
+/** Upper bound on how long one child's shutdown handlers may take. */
+export const CHILD_SHUTDOWN_TIMEOUT_MS = 5_000;
+
+const SESSION_SHUTDOWN = "session_shutdown";
+
+/** The event a disposed child session dispatches to its extensions. */
+interface ChildSessionShutdownEvent {
+  type: typeof SESSION_SHUTDOWN;
+  reason: "quit";
+}
+
+/**
+ * Narrow session seam — only what child shutdown reads.
+ *
+ * Both members are optional so the emitter stays safe against a Pi build that
+ * predates them; either absence means "nothing to emit."
+ */
+export interface ShutdownCapableSession {
+  hasExtensionHandlers?(eventType: string): boolean;
+  readonly extensionRunner?: {
+    emit(event: ChildSessionShutdownEvent): Promise<unknown>;
+  };
+}
+
+/**
+ * Dispatch one `session_shutdown` to a child's extensions and await it, bounded
+ * by `timeoutMs`. Resolves quietly on every failure mode — no runner, no handlers,
+ * a rejected emit, or a handler that never settles — so disposal always proceeds.
+ */
+export async function emitChildSessionShutdown(
+  session: ShutdownCapableSession,
+  timeoutMs: number = CHILD_SHUTDOWN_TIMEOUT_MS,
+): Promise<void> {
+  const runner = session.extensionRunner;
+  if (!runner || !hasShutdownHandlers(session)) return;
+
+  try {
+    const emitted = runner.emit({ type: SESSION_SHUTDOWN, reason: "quit" });
+    if ((await settleWithinBound(emitted, timeoutMs)) === "timed-out") {
+      debugLog("child session_shutdown exceeded its bound (ms)", timeoutMs);
+    }
+  } catch (err) {
+    debugLog("child session_shutdown emit", err);
+  }
+}
+
+/** Whether the child has anything to hear the event; unknown counts as yes. */
+function hasShutdownHandlers(session: ShutdownCapableSession): boolean {
+  return session.hasExtensionHandlers?.(SESSION_SHUTDOWN) ?? true;
+}
+
+type ShutdownOutcome = "settled" | "timed-out";
+
+/**
+ * Resolve when `emitted` settles or when `timeoutMs` elapses, whichever is first.
+ * A rejection counts as settled (the caller logs it); the timer is always cleared,
+ * so a prompt shutdown leaves nothing holding the event loop.
+ */
+async function settleWithinBound(
+  emitted: Promise<unknown>,
+  timeoutMs: number,
+): Promise<ShutdownOutcome> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const bound = new Promise<ShutdownOutcome>((resolve) => {
+    timer = setTimeout(() => {
+      resolve("timed-out");
+    }, timeoutMs);
+  });
+  const settled = emitted.then(
+    (): ShutdownOutcome => "settled",
+    (err: unknown): ShutdownOutcome => {
+      debugLog("child session_shutdown handler", err);
+      return "settled";
+    },
+  );
+
+  try {
+    return await Promise.race([settled, bound]);
+  } finally {
+    clearTimeout(timer);
+  }
+}

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,335 @@
+/**
+ * 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,
+  type ToolDefinition,
+} 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 { SelectionCancelledError } from "#src/lifecycle/spawn-selection";
+import { SubagentSession } from "#src/lifecycle/subagent-session";
+import { AskParentTool, type QuestionRecorder } from "#src/session/ask-parent-tool";
+import type { EnvInfo } from "#src/session/env";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import { NotifyParentTool, type UpdateAnnouncer } from "#src/session/notify-parent-tool";
+import { type AssemblerIO, assembleSessionConfig } from "#src/session/session-config";
+import type {
+  ParentSessionInfo,
+  PromptInheritance,
+  ShellExec,
+  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[];
+  /**
+   * Tool definitions supplied directly rather than by an extension. The SDK
+   * filters these through `tools` too, so every name here must also be listed
+   * there or the definition is silently dropped.
+   */
+  customTools?: ToolDefinition[];
+  /** 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;
+  /**
+   * Which prompt-inheritance strategy a child on the given provider adopts.
+   *
+   * Resolved at the composition root from the operator's settings, so this
+   * factory stays policy-free — the same shape the extension-exclusion policy
+   * reaches it in.
+   */
+  resolvePromptInheritance: (provider: string | undefined) => PromptInheritance;
+}
+
+/** 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;
+  /**
+   * Combined abort signal for a gated run (a selection was required). Checked
+   * after the asynchronous preparation awaits and immediately before the SDK
+   * session-creation call; a session that creation returned anyway is disposed
+   * before binding. Absent on the ordinary no-provider path.
+   */
+  selectionSignal?: AbortSignal;
+  /**
+   * Records a question the child declares with `ask_parent`. Supplied for every
+   * child; its absence installs no ask-back tool.
+   */
+  askParent?: QuestionRecorder;
+  /**
+   * Announces a mid-run update the child sends with `notify_parent`. Supplied
+   * only for a background child whose operator left the channel on; its absence
+   * installs no update tool.
+   */
+  notifyParent?: UpdateAnnouncer;
+}
+
+/**
+ * The core's own child-facing tools, built for whichever callbacks this run
+ * supplied. An agent's `tools:` list is its complete capability allowlist, so
+ * these are appended to it rather than drawn from it: they are protocol the
+ * core installs in every child, and neither reaches the filesystem, the shell,
+ * or the network.
+ */
+function buildChildTools(params: CreateSubagentSessionParams): ToolDefinition[] {
+  const tools: ToolDefinition[] = [];
+  if (params.askParent) tools.push(new AskParentTool(params.askParent).toToolDefinition());
+  if (params.notifyParent)
+    tools.push(new NotifyParentTool(params.notifyParent).toToolDefinition());
+  return tools;
+}
+
+/**
+ * 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,
+      parentPortablePrompt: snapshot.portablePrompt,
+      parentModel: snapshot.model,
+      modelRegistry: snapshot.modelRegistry,
+      resolvePromptInheritance: deps.resolvePromptInheritance,
+    },
+    {
+      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();
+
+  // A gated run rechecks its signal after the environment/loader awaits:
+  // revocation during loader.reload() must not reach SDK creation.
+  if (params.selectionSignal?.aborted) {
+    throw new SelectionCancelledError();
+  }
+
+  const childTools = buildChildTools(params);
+  const { session } = await deps.io.createSession({
+    cwd: cfg.effectiveCwd,
+    agentDir,
+    sessionManager,
+    settingsManager: sessionSettings,
+    modelRegistry: snapshot.modelRegistry,
+    model: cfg.model,
+    tools: [...cfg.toolNames, ...childTools.map((tool) => tool.name)],
+    customTools: childTools,
+    excludeTools: EXCLUDED_TOOL_NAMES,
+    resourceLoader: loader,
+    thinkingLevel: cfg.thinkingLevel,
+  });
+
+  // Creation had already begun when the cancellation landed; the SDK call
+  // cannot be undone, but its session is torn down before binding or prompting.
+  if (params.selectionSignal?.aborted) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations
+    session.dispose?.();
+    throw new SelectionCancelledError();
+  }
+
+  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({});
+  } 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;
+  }
+
+  // Every child session_start handler has now run, so this is the first — and
+  // only — moment a parent can observe what the child's extensions installed.
+  // Deliberately outside the try above: a child whose binding threw never ran.
+  deps.lifecycle.bound({ sessionId, parentSessionId });
+
+  return subagentSession;
+}