/** * In-process child sessions. * * A child is a pi `AgentSession` created inside the process that owns it: the * parent pi process for foreground children, the detached runner process for * background children. The factory is injectable so tests can script a child * without the real runtime; the default implementation wraps * `createAgentSession` from a pi package module. */ import * as fs from "node:fs"; import * as path from "node:path"; import { pathToFileURL } from "node:url"; import type { AgentMessage } from "@earendil-works/pi-agent-core"; import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import { pinChildCacheRetention } from "../../shared/child-cache-retention.ts"; import type { RequiredChildExtensionSnapshot } from "../../shared/required-child-extensions.ts"; import type { HerdrMachineReference, HerdrRemoteGitStatus } from "../../shared/types.ts"; import { PI_CODING_AGENT_PACKAGE_ROOT_ENV, getAgentDir } from "../../shared/utils.ts"; import { resolvePackageSubpath } from "../background/runner-aliases.ts"; import type { ChildRuntimeConfig } from "./child-runtime-config.ts"; import { PI_CODING_AGENT_PACKAGE, resolveInstalledPiPackageRoot, resolvePiPackageRoot } from "./pi-spawn.ts"; export interface ChildSessionEvent { type: string; [key: string]: unknown; } /** Mirror pi's JSON event projection: `message_update` drops the partial message. */ export function projectChildSessionEventForJson(event: ChildSessionEvent): unknown { if (event.type !== "message_update") return event; const assistantMessageEvent = event.assistantMessageEvent as Record | undefined; if (!assistantMessageEvent || typeof assistantMessageEvent !== "object") return event; const { partial: _partial, ...delta } = assistantMessageEvent; return { type: "message_update", usage: (event.message as { usage?: unknown } | undefined)?.usage, assistantMessageEvent: delta, }; } export interface ChildSessionExtensionError { extensionPath: string; event: string; error: unknown; } export interface ChildHookExtension { name: string; factory: (pi: ExtensionAPI) => void; } export type ChildSessionStorage = | { kind: "file"; sessionFile: string } | { kind: "dir"; sessionDir: string } | { kind: "default" } | { kind: "memory" }; export interface ChildSessionLaunch { cwd: string; /** Resolved pane-native placement. Local launches omit this field. */ machine?: HerdrMachineReference; /** Process-local provider source owned by the invoking foreground parent. */ parentProviderRegistry?: ParentProviderRegistry; /** Logical names resolved only by the remote ambient package. */ remoteResources?: { agent: string; skills?: string[]; toolCeiling?: string[]; reads?: string[] | false }; storage: ChildSessionStorage; /** Model reference as the agent config names it (`provider/id`, optionally `:thinking`). */ model?: string; /** Explicit tool allowlist; undefined keeps pi's defaults. */ tools?: string[]; excludeTools?: string[]; /** Extension files loaded for this child in addition to the inline hooks. */ extensionPaths: string[]; /** Canonical required paths and safe evidence identities for fail-closed loading. */ requiredExtensions?: RequiredChildExtensionSnapshot; /** * Discover the ambient extensions (agent dir, project, settings) the way a * `pi` process would. False loads only `extensionPaths` and `hooks`. */ ambientExtensions: boolean; hooks: ChildHookExtension[]; noSkills: boolean; noContextFiles: boolean; systemPrompt?: string; appendSystemPrompt?: string; /** * Environment values that extensions loaded into the child read from * `process.env`. Applied to the hosting process while the session is created * and its extensions load and start; launches in one process take that * window one at a time. An undefined value removes the variable. */ processEnv?: Record; /** The typed runtime config the hooks were built from; informational for factories. */ runtime: ChildRuntimeConfig; onExtensionError?: (error: ChildSessionExtensionError) => void; } export interface ChildSession { subscribe(listener: (event: ChildSessionEvent) => void): () => void; /** Resolves when the run ends, including after abort. */ prompt(text: string): Promise; steer(text: string): Promise; followUp(text: string): Promise; abort(): Promise; /** Emits `session_shutdown` to the child's extensions and disposes the session; resolves once that shutdown work is done. */ dispose(): Promise; /** True while Pi still has steering or follow-up input that has not started a turn. */ hasQueuedMessages?(): boolean; readonly messages: readonly AgentMessage[]; readonly sessionFile: string | undefined; readonly sessionId: string; readonly modelId: string | undefined; readonly machineEvidence?: { machineId: string; initial?: HerdrRemoteGitStatus; final?: HerdrRemoteGitStatus }; /** Event-updated pane-native status; reading it performs no network work. */ readonly placementSnapshot?: unknown; /** Set by the foreground host once the run detached; `factory.dispose()` leaves such children running. */ detached?: boolean; /** Set by `factory.dispose()` before it aborts the child, so the host can report the stop truthfully. */ shutDown?: boolean; } export function childSessionHasQueuedMessages(session: ChildSession | undefined): boolean { try { return session?.hasQueuedMessages?.() === true; } catch { return false; } } export interface ChildSessionFactory { create(launch: ChildSessionLaunch): Promise; /** Abort and dispose every live attached child; detached children keep running and hold the shared runtime. */ dispose(): Promise; } export type PiCodingAgentModule = typeof import("@earendil-works/pi-coding-agent"); export interface DefaultChildSessionFactoryOptions { /** * Loads the pi package the sessions are created from. The parent process * uses the host's in-process module; the detached runner imports the * installed package by absolute path. */ loadPiCodingAgent?: () => Promise; /** * Overrides built-in extension discovery for child loaders. The default reads * the host package's `extensions/index.js`, but only when pi itself is loaded * by the default loader: an injected `loadPiCodingAgent` is a scripted or * embedded module whose loader does not consume host built-ins. */ loadBuiltinExtensions?: () => Promise; /** Upper bound on a disposed child's `session_shutdown` handlers before the session is dropped anyway. */ shutdownTimeoutMs?: number; } type ModelRuntimeInstance = Awaited>; export type ParentProviderRegistry = Pick< ModelRuntimeInstance, "getRegisteredProviderIds" | "getRegisteredProviderConfig" | "getRegisteredNativeProvider" >; function inheritParentProviders( modelRuntime: ModelRuntimeInstance, parentProviders: ParentProviderRegistry, claimedProviderIds: ReadonlySet, onError: ((error: ChildSessionExtensionError) => void) | undefined, ): boolean { let providerIds: readonly string[]; try { providerIds = parentProviders.getRegisteredProviderIds(); } catch (error) { onError?.({ extensionPath: "", event: "inherit_provider", error }); throw new Error(`Failed to enumerate parent providers: ${error instanceof Error ? error.message : String(error)}`, { cause: error, }); } let registered = false; for (const providerId of new Set(providerIds)) { if (claimedProviderIds.has(providerId)) continue; try { const native = parentProviders.getRegisteredNativeProvider(providerId); const config = native ? undefined : parentProviders.getRegisteredProviderConfig(providerId); if (native) modelRuntime.registerNativeProvider(native); else if (config) modelRuntime.registerProvider(providerId, config); else throw new Error(`Parent provider '${providerId}' has no registered native provider or config.`); registered = true; } catch (error) { onError?.({ extensionPath: ``, event: "inherit_provider", error }); throw new Error( `Failed to inherit parent provider '${providerId}': ${error instanceof Error ? error.message : String(error)}`, { cause: error }, ); } } return registered; } const CHILD_PROMPT_RUNTIME_EXTENSION_PATH = ""; /** The prompt runtime filters parent-only context before ambient extensions inspect * the child prompt. Other inline hooks keep their normal position after ambient * extensions, and ambient extension order stays unchanged. */ function prioritizeChildPromptRuntime }>(result: T): T { const index = result.extensions.findIndex(({ path }) => path === CHILD_PROMPT_RUNTIME_EXTENSION_PATH); if (index <= 0) return result; const extensions = [...result.extensions]; const [promptRuntime] = extensions.splice(index, 1); if (!promptRuntime) return result; extensions.unshift(promptRuntime); return { ...result, extensions }; } /** One launch at a time from env application through `session_start`, so parallel launches never observe each other's `processEnv` while their extensions load and start. */ let loading: Promise = Promise.resolve(); /** * pi caches extension factories per process and clears that cache only when a * loader reloads a second time, so every child in one process would share each * extension's module state. Marking the child's loader as already loaded makes * its first `reload()` clear the cache, so the child gets its own instances the * way a separate process had them. The flag is a private field of pi's loader. */ function resetExtensionCacheOnReload(loader: object): boolean { if (!("loaded" in loader)) return false; (loader as { loaded: boolean }).loaded = true; return true; } function applyProcessEnv(values: Record | undefined): void { if (!values) return; for (const [name, value] of Object.entries(values)) { if (value === undefined) delete process.env[name]; else process.env[name] = value; } } function flushQueuedProviderRegistrations( loader: InstanceType, modelRuntime: ModelRuntimeInstance, onError: ((error: ChildSessionExtensionError) => void) | undefined, requiredPaths: ReadonlySet, ): { claimedProviderIds: Set; registered: boolean } { const claimedProviderIds = new Set(); if (!("getExtensions" in loader) || typeof loader.getExtensions !== "function") return { claimedProviderIds, registered: false }; const { runtime } = loader.getExtensions(); let registered = false; for (const { name, config, extensionPath } of runtime.pendingProviderRegistrations ?? []) { claimedProviderIds.add(name); try { modelRuntime.registerProvider(name, config); registered = true; } catch (error) { onError?.({ extensionPath, event: "register_provider", error }); if (requiredPaths.has(extensionPath)) throw new Error( `Required child extension provider registration failed for '${extensionPath}': ${error instanceof Error ? error.message : String(error)}`, ); } } if (Array.isArray(runtime.pendingProviderRegistrations)) runtime.pendingProviderRegistrations = []; for (const { provider, extensionPath } of runtime.pendingNativeProviderRegistrations ?? []) { claimedProviderIds.add(provider.id); try { modelRuntime.registerNativeProvider(provider); registered = true; } catch (error) { onError?.({ extensionPath, event: "register_provider", error }); if (requiredPaths.has(extensionPath)) throw new Error( `Required child extension provider registration failed for '${extensionPath}': ${error instanceof Error ? error.message : String(error)}`, ); } } if (Array.isArray(runtime.pendingNativeProviderRegistrations)) runtime.pendingNativeProviderRegistrations = []; return { claimedProviderIds, registered }; } /** * Load the host-owned pi-coding-agent module by absolute package entry so a * child cannot resolve an extension-owned copy. Root precedence is the running * host, an explicit override, then the install tree. Once any root is selected, * its manifest, package identity, entry, and import must all succeed; the bare * specifier is used only when no root resolves. */ /** Root precedence shared by the host SDK load and built-in extension discovery: running host, explicit override, then the install tree. */ function resolveHostPiRoot(): { root: string; overrideRoot: string | undefined } | undefined { const overrideRoot = process.env[PI_CODING_AGENT_PACKAGE_ROOT_ENV]?.trim() || undefined; const runningRoot = resolvePiPackageRoot(); const selectedOverride = runningRoot === undefined ? overrideRoot : undefined; const root = runningRoot ?? selectedOverride ?? resolveInstalledPiPackageRoot(); return root ? { root, overrideRoot: selectedOverride } : undefined; } export async function loadHostPiCodingAgent(): Promise { const host = resolveHostPiRoot(); if (host) { const entry = fs.realpathSync(resolveHostPackageEntry(host.root, host.overrideRoot)); return import(pathToFileURL(entry).href); } return import(PI_CODING_AGENT_PACKAGE); } function resolveHostPackageEntry(root: string, overrideRoot: string | undefined): string { const packageJson = path.join(root, "package.json"); const source = fs.readFileSync(packageJson, "utf8"); let parsed: unknown; try { parsed = JSON.parse(source); } catch (error) { throw new Error(`invalid host SDK manifest at ${packageJson}: malformed JSON`, { cause: error }); } if (!isUnknownRecord(parsed)) throw new Error(`invalid host SDK manifest at ${packageJson}: expected a JSON object`); const pkg = parsed; if (pkg.name !== PI_CODING_AGENT_PACKAGE) { const source = overrideRoot !== undefined ? ` (${PI_CODING_AGENT_PACKAGE_ROOT_ENV} override)` : ""; throw new Error( `refusing to load the host SDK from ${root}${source}: package.json name is "${String(pkg.name ?? "(none)")}", expected "${PI_CODING_AGENT_PACKAGE}"`, ); } const entry = resolvePackageSubpath(root, "."); if (!entry) throw new Error(`host SDK manifest at ${packageJson} has no resolvable root export`); return entry; } function isUnknownRecord(value: unknown): value is Record { return typeof value === "object" && value !== null && !Array.isArray(value); } /** Named inline extension a host pi package ships in `extensions/index.js` (`builtin`/`replaceable` exist on newer hosts only). */ export interface HostBuiltinExtension { name: string; factory: (pi: ExtensionAPI) => void | Promise; hidden?: boolean; builtin?: boolean; replaceable?: boolean; } let hostBuiltinExtensions: readonly HostBuiltinExtension[] | undefined; function isHostBuiltinExtension(value: unknown): value is HostBuiltinExtension { return isUnknownRecord(value) && typeof value.name === "string" && typeof value.factory === "function"; } /** * pi's CLI entry merges its built-in extension factories (mcp, codemode, * tool-search, ...) into every resource loader it builds; without the same * merge, child sessions silently miss `builtin:*` extensions even when * settings enable them. The array is read from the host package at runtime, * so built-ins pi adds later need no change here. Hosts without the module * (before pi shipped built-ins) degrade quietly; a module that exists but * fails to load warns once. */ export async function loadHostBuiltinExtensions(): Promise { hostBuiltinExtensions ??= await readHostBuiltinExtensions(); return hostBuiltinExtensions; } async function readHostBuiltinExtensions(): Promise { const host = resolveHostPiRoot(); if (!host) return []; let entry: string; try { entry = fs.realpathSync(resolveHostPackageEntry(host.root, host.overrideRoot)); } catch { return []; } const modulePath = path.join(path.dirname(entry), "extensions", "index.js"); if (!fs.existsSync(modulePath)) return []; try { const loaded = (await import(pathToFileURL(fs.realpathSync(modulePath)).href)) as { builtInExtensions?: unknown; }; const listed = loaded.builtInExtensions; if (!Array.isArray(listed)) throw new Error("builtInExtensions export is not an array"); return listed.filter(isHostBuiltinExtension); } catch (error) { console.warn( `[pi-subagents] failed to load host built-in extensions from ${modulePath}: ${ error instanceof Error ? error.message : String(error) }; child sessions will not load pi's built-in extensions.`, ); return []; } } /** * Default factory: detached/background sessions retain the existing shared * runtime; each parent-bound foreground launch gets an isolated runtime. */ export function createDefaultChildSessionFactory(options: DefaultChildSessionFactoryOptions = {}): ChildSessionFactory { const loadPiCodingAgent = options.loadPiCodingAgent ?? loadHostPiCodingAgent; const shutdownTimeoutMs = options.shutdownTimeoutMs ?? 5_000; let runtime: ReturnType | undefined; const live = new Set(); /** Extension shutdowns still running for disposed children; `dispose()` waits for them. */ const shutdowns = new Set>(); const sharedRuntime = async (pi: PiCodingAgentModule) => { runtime ??= pi.ModelRuntime.create().catch((error: unknown) => { runtime = undefined; throw error; }); return runtime; }; return { async create(launch) { const pi = await loadPiCodingAgent(); const loadBuiltins = options.loadBuiltinExtensions ?? (options.loadPiCodingAgent ? undefined : loadHostBuiltinExtensions); const builtinFactories = loadBuiltins ? await loadBuiltins() : []; const modelRuntime = launch.parentProviderRegistry ? await pi.ModelRuntime.create() : await sharedRuntime(pi); const agentDir = getAgentDir(); const settingsManager = pi.SettingsManager.create(launch.cwd, agentDir); // Foreground children share Pi's global theme with the parent, so reinitializing it // would overwrite the parent's active light/dark appearance. Detached runners have // no initialized theme and must initialize one for headless extension renderers. const themeKey = Symbol.for("@earendil-works/pi-coding-agent:theme"); const themeInitialized = Boolean((globalThis as Record)[themeKey]); if (!themeInitialized && typeof pi.initTheme === "function") pi.initTheme(settingsManager.getTheme()); const loader = new pi.DefaultResourceLoader({ cwd: launch.cwd, agentDir, settingsManager, noExtensions: !launch.ambientExtensions, noSkills: launch.noSkills, noPromptTemplates: true, noThemes: true, noContextFiles: launch.noContextFiles, additionalExtensionPaths: launch.extensionPaths, extensionFactories: [...builtinFactories, ...launch.hooks], extensionsOverride: prioritizeChildPromptRuntime, ...(launch.systemPrompt !== undefined ? { systemPrompt: launch.systemPrompt } : {}), ...(launch.appendSystemPrompt !== undefined ? { appendSystemPrompt: [launch.appendSystemPrompt] } : {}), }); const open = async () => { const requiredPaths = new Set((launch.requiredExtensions ?? []).map(({ path }) => path)); applyProcessEnv(launch.processEnv); if (!resetExtensionCacheOnReload(loader) && (launch.ambientExtensions || launch.extensionPaths.length)) launch.onExtensionError?.({ extensionPath: "", event: "load", error: new Error( "pi's extension cache reset is unavailable; extensions loaded into this child share module state with other sessions in this process.", ), }); await loader.reload(); const loadErrors = requiredPaths.size > 0 ? loader.getExtensions().errors.filter(({ path }) => requiredPaths.has(path)) : []; if (loadErrors.length > 0) throw new Error( `Required child extension failed to load: ${loadErrors.map(({ path, error }) => `${path}: ${error}`).join("; ")}`, ); const queued = flushQueuedProviderRegistrations(loader, modelRuntime, launch.onExtensionError, requiredPaths); const inherited = launch.parentProviderRegistry ? inheritParentProviders( modelRuntime, launch.parentProviderRegistry, queued.claimedProviderIds, launch.onExtensionError, ) : false; if (queued.registered || inherited) { try { await modelRuntime.refresh({ allowNetwork: false }); } catch (error) { launch.onExtensionError?.({ extensionPath: "", event: "refresh_providers", error }); throw new Error( `Failed to refresh child providers: ${error instanceof Error ? error.message : String(error)}`, { cause: error }, ); } } const sessionManager = launch.storage.kind === "file" ? pi.SessionManager.open(launch.storage.sessionFile, undefined, launch.cwd) : launch.storage.kind === "dir" ? pi.SessionManager.create(launch.cwd, launch.storage.sessionDir) : launch.storage.kind === "memory" ? pi.SessionManager.inMemory(launch.cwd) : pi.SessionManager.create(launch.cwd); const resolvedModel = launch.model ? pi.resolveCliModel({ cliModel: launch.model, modelRuntime }) : undefined; if (resolvedModel?.error) throw new Error(resolvedModel.error); const { session } = await pi.createAgentSession({ cwd: launch.cwd, agentDir, modelRuntime, ...(resolvedModel?.model ? { model: resolvedModel.model } : {}), ...(resolvedModel?.thinkingLevel ? { thinkingLevel: resolvedModel.thinkingLevel } : {}), ...(launch.tools ? { tools: launch.tools } : {}), ...(launch.excludeTools?.length ? { excludeTools: launch.excludeTools } : {}), resourceLoader: loader, sessionManager, settingsManager, sessionStartEvent: { type: "session_start", reason: "startup" }, }); pinChildCacheRetention(session.agent); try { await session.bindExtensions({ mode: "print", onError: (error) => launch.onExtensionError?.({ extensionPath: error.extensionPath, event: error.event, error: error.error }), }); } catch (error) { session.dispose(); throw error; } return session; }; const opened = loading.catch(() => {}).then(open); loading = opened; const session = await opened; let pending: Promise | undefined; // pi's own hosts emit `session_shutdown` before disposing a session so the // extensions loaded into it (ambient extensions included) release their // watchers, servers, and timers. Do the same, then dispose. const shutdown = async (): Promise => { try { const runner = session.extensionRunner; if (runner.hasHandlers("session_shutdown")) { await Promise.race([ runner.emit({ type: "session_shutdown", reason: "quit" }), new Promise((resolve) => setTimeout(resolve, shutdownTimeoutMs).unref?.()), ]); } } catch (error) { launch.onExtensionError?.({ extensionPath: "", event: "session_shutdown", error }); } finally { session.dispose(); } }; const child: ChildSession = { subscribe: (listener) => session.subscribe((event) => listener(event as unknown as ChildSessionEvent)), prompt: (text) => session.prompt(text), steer: (text) => session.steer(text), followUp: (text) => session.followUp(text), abort: () => session.abort(), hasQueuedMessages: () => session.agent?.hasQueuedMessages?.() === true, dispose: () => { if (!pending) { live.delete(child); const shutdownDone = shutdown(); pending = shutdownDone; shutdowns.add(shutdownDone); void shutdownDone.finally(() => shutdowns.delete(shutdownDone)); } return pending; }, get messages() { return session.messages; }, get sessionFile() { return session.sessionFile; }, get sessionId() { return session.sessionId; }, get modelId() { return session.model ? `${session.model.provider}/${session.model.id}` : undefined; }, }; live.add(child); return child; }, async dispose() { const children = [...live].filter((child) => !child.detached); for (const child of children) child.shutDown = true; await Promise.allSettled(children.map((child) => child.abort())); for (const child of children) { try { void child.dispose(); } catch { /* best effort */ } } await Promise.allSettled([...shutdowns]); if (live.size === 0) runtime = undefined; }, }; } let activeFactory: ChildSessionFactory | undefined; let activeFactoryModule: string | undefined; /** The process-wide factory foreground runs use unless a run passes its own. */ export function childSessionFactory(): ChildSessionFactory { activeFactory ??= createLazyPlacementFactory(createDefaultChildSessionFactory()); return activeFactory; } function createLazyPlacementFactory(local: ChildSessionFactory): ChildSessionFactory { let placed: ChildSessionFactory | undefined; const factory = async () => (placed ??= (await import("./herdr-placed-run.ts")).createPlacementAwareChildSessionFactory(local)); return { async create(launch) { return launch.machine ? (await factory()).create(launch) : local.create(launch); }, async dispose() { if (placed) await placed.dispose(); else await local.dispose(); }, }; } /** Default factory including pane-native placement; detached runners use the same boundary. */ export function createPlacementChildSessionFactory( options: DefaultChildSessionFactoryOptions = {}, ): ChildSessionFactory { return createLazyPlacementFactory(createDefaultChildSessionFactory(options)); } /** * Replace the process-wide factory. Tests install a scripted factory; passing * undefined restores the default on next use. */ export function setChildSessionFactory(factory: ChildSessionFactory | undefined): void { activeFactory = factory; } /** * Module path the detached background runner imports its child session factory * from. Tests point it at a scripted factory; production launches leave it * unset and the runner creates real sessions from the installed pi package. */ export function childSessionFactoryModule(): string | undefined { return activeFactoryModule; } export function setChildSessionFactoryModule(modulePath: string | undefined): void { activeFactoryModule = modulePath; } /** Abort and dispose every live in-process child and release the shared runtime. */ export async function disposeChildSessions(): Promise { const factory = activeFactory; if (!factory) return; await factory.dispose(); }