@jopqior/pi-subagents 1.0.0

package/src/lifecycle/parent-snapshot.ts

@@ -0,0 +1,119 @@
+/**
+ * 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";
+
+/**
+ * The parent session's operator-authored prompt parts, as Pi reports them on
+ * `before_agent_start`.
+ *
+ * A narrow structural slice of Pi's `BuildSystemPromptOptions` holding the
+ * layers an operator wrote and nothing Pi or a tool contributed. `skills` is
+ * excluded for the reason ADR 0006 cuts the catalogue: the child loads its
+ * own. `promptGuidelines` is excluded because Pi derives it per session from
+ * the tools actually in the registry, so inheriting the parent's would assert
+ * guidance for tools the child may not hold — the defect ADR 0008 removed with
+ * the `<sub_agent_context>` block. `selectedTools` and `toolSnippets` are
+ * excluded because the tool surface is node-local prose.
+ */
+export interface ParentPromptOptions {
+  /** Context files (AGENTS.md and kin) Pi loaded for the parent session. */
+  contextFiles?: Array<{ path: string; content: string }>;
+  /** Custom system prompt (`--system-prompt`), when the parent runs one. */
+  customPrompt?: string;
+  /** Appended system prompt text (`--append-system-prompt`). */
+  appendSystemPrompt?: string;
+}
+
+/**
+ * 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;
+  /**
+   * The parent's operator-authored parts, rendered as an identity a child on a
+   * re-homing provider may adopt in place of the assembled prompt (ADR 0009).
+   * Undefined when Pi has assembled no prompt yet, or when the parent has no
+   * such parts.
+   */
+  portablePrompt?: 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,
+  promptOptions?: ParentPromptOptions,
+): 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,
+    portablePrompt: buildPortablePrompt(promptOptions),
+  };
+}
+
+/**
+ * Compose the parent's operator-authored parts into an identity a child may
+ * adopt, in the order Pi's own `buildSystemPrompt` composes them: the custom
+ * prompt, then the appended prompt, then the project-context block.
+ *
+ * The result is what Pi would assemble for a session with a custom prompt and
+ * no tools or skills, so a host that re-homes it sees text shaped the way its
+ * own harness produces — not Pi's base preamble.
+ *
+ * Returns undefined when no part survives, which routes the caller to the
+ * generic base rather than back to the full prompt.
+ */
+function buildPortablePrompt(options?: ParentPromptOptions): string | undefined {
+  if (!options) return undefined;
+  const sections: string[] = [];
+  const custom = options.customPrompt?.trim();
+  if (custom) sections.push(custom);
+  const appended = options.appendSystemPrompt?.trim();
+  if (appended) sections.push(appended);
+  const projectContext = renderProjectContext(options.contextFiles);
+  if (projectContext) sections.push(projectContext);
+  return sections.length > 0 ? sections.join("\n\n") : undefined;
+}
+
+/**
+ * Render context files as Pi's `<project_context>` block, byte for byte.
+ *
+ * Pi writes a lead-in sentence and separates each `<project_instructions>`
+ * block with a blank line; matching it exactly is what keeps a portable child's
+ * project instructions indistinguishable from a parent's.
+ */
+function renderProjectContext(
+  contextFiles: ParentPromptOptions["contextFiles"],
+): string | undefined {
+  if (!contextFiles || contextFiles.length === 0) return undefined;
+  const blocks = contextFiles.map(
+    ({ path, content }) =>
+      `<project_instructions path="${path}">\n${content}\n</project_instructions>\n`,
+  );
+  return `<project_context>\n\nProject-specific instructions and guidelines:\n\n${blocks.join("\n")}\n</project_context>`;
+}

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

package/src/lifecycle/selection-scope.ts

@@ -0,0 +1,116 @@
+/**
+ * selection-scope.ts — Shared construction-context carrier for spawn selection.
+ *
+ * The carrier is the one piece of selection state that must survive separate
+ * module evaluations: Pi jiti-loads extension sources per session (and clears
+ * its module cache when consecutive children resolve different cwds), so a
+ * module-level carrier would hand a child core a channel its root never
+ * established. The carrier therefore lives on `globalThis` behind a
+ * `Symbol.for()` key — every instance of this module in the process shares it.
+ *
+ * Its stored value is a scope handle, never a process-wide flag or singleton:
+ * ownership, lease state, and registration live on the handle (see
+ * `spawn-selection.ts`), one per root runtime generation.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { SpawnSelectionProvider, SpawnSelectionRegistration } from "#src/service/service";
+
+/** What a core factory captures at initialization and retains as a runtime dependency. */
+export interface SelectionScopeHandle {
+	/** Root generation identity — shared by every handle derived from one root. */
+	readonly rootId: string;
+	/**
+	 * The registration boundary: `owned` on a root lease, `inherited` (nothing
+	 * installed) on a descendant handle, whatever the root's state.
+	 */
+	register(provider: SpawnSelectionProvider): SpawnSelectionRegistration;
+	/**
+	 * The root lease's provider while new runs must select — undefined when the
+	 * lease is unconfigured or revoked, and on any handle whose root's is.
+	 */
+	activeSelectionProvider(): SpawnSelectionProvider | undefined;
+	/**
+	 * Aborts once this handle closes — its own shutdown, or the root lease's
+	 * revocation. A gated run combines this with its own abort signal for the
+	 * provider call and the pre-creation checks.
+	 */
+	readonly closureSignal: AbortSignal;
+	/**
+	 * Wrap the complete child factory call in the construction context: the
+	 * context is active for everything the thunk does, including the resource
+	 * loader's reload and the child extension factories it awaits.
+	 *
+	 * The thunk is invoked synchronously, so the no-provider timing pins hold.
+	 * Rejects when this handle is already closed — a revoked lease prohibits
+	 * subsequent creation.
+	 */
+	constructChild<T>(thunk: () => Promise<T>): Promise<T>;
+	/**
+	 * Invalidate this handle and its pending subtree. Owner-aware: on a root it
+	 * revokes the lease (signalling descendants); on a child it frees only that
+	 * child's subtree, never the root or a sibling.
+	 */
+	close(): void;
+	/**
+	 * Record that a runtime now owns this handle, so the construction wrapper
+	 * that created it leaves it open once the factory call settles. Internal
+	 * machinery — called by {@link captureInheritedSelectionScope}.
+	 */
+	retain(): void;
+}
+
+/** The process-wide construction carrier behind the shared symbol. */
+interface SelectionCarrier {
+	als: AsyncLocalStorage<SelectionScopeHandle>;
+}
+
+const CARRIER_KEY = Symbol.for("@gotgenes/pi-subagents:selection-construction-carrier");
+
+function carrier(): SelectionCarrier {
+	const globals = globalThis as Record<symbol, unknown>;
+	let existing = globals[CARRIER_KEY] as SelectionCarrier | undefined;
+	if (existing === undefined) {
+		existing = { als: new AsyncLocalStorage<SelectionScopeHandle>() };
+		globals[CARRIER_KEY] = existing;
+	}
+	return existing;
+}
+
+/**
+ * The ambient scope handle, visible only inside a construction context —
+ * a child core factory calls this during its initialization and retains the
+ * result for its whole lifetime. Retains the handle: capturing is the
+ * retention point, so the construction wrapper leaves it open once the factory
+ * call settles.
+ */
+export function captureInheritedSelectionScope(): SelectionScopeHandle | undefined {
+	const handle = carrier().als.getStore();
+	handle?.retain();
+	return handle;
+}
+
+/**
+ * Run `thunk` with `handle` as the ambient construction context, releasing the
+ * handle again if no runtime captured it.
+ *
+ * Failure always releases the handle; success releases it only when nobody
+ * retained it (a child that never loaded this core has no runtime to close the
+ * handle later, so the wrapper is its only cleanup).
+ */
+export function runInConstructionContext<T>(
+	handle: SelectionScopeHandle & { wasRetained(): boolean },
+	thunk: () => Promise<T>,
+): Promise<T> {
+	const settled = carrier().als.run(handle, thunk);
+	return settled.then(
+		(result) => {
+			if (!handle.wasRetained()) handle.close();
+			return result;
+		},
+		(err: unknown) => {
+			handle.close();
+			throw err;
+		},
+	);
+}

package/src/lifecycle/spawn-selection.ts

@@ -0,0 +1,259 @@
+/**
+ * spawn-selection.ts — Lease ownership for per-spawn selection.
+ *
+ * `SpawnSelectionScope` is one root runtime generation's provider lease; a
+ * descendant runtime never gets its own lease but a `ChildSelectionScope`
+ * handle to the root's. The lease distinguishes never-configured, active, and
+ * revoked: a revoked lease is denied forever (a new root session is a new
+ * scope), and closing a child frees only that child's subtree — never the root
+ * or a sibling.
+ *
+ * The construction wrapper is deliberately unconditional: it establishes a
+ * child handle before any loader activity even when the root has never
+ * configured a provider, so a descendant's registration is `inherited` by
+ * construction rather than by a configured-only branch.
+ */
+
+import { randomUUID } from "node:crypto";
+import { runInConstructionContext, type SelectionScopeHandle } from "#src/lifecycle/selection-scope";
+import type { SpawnSelectionProvider, SpawnSelectionRegistration } from "#src/service/service";
+
+/** Marker distinguishing a cancelled selection from an infrastructure error. */
+const CANCELLATION_MARKER = Symbol.for(
+	"@gotgenes/pi-subagents:spawn-selection-cancelled",
+);
+
+/**
+ * A gated run's selection phase ended without a pair: the user cancelled the
+ * dialog, the run aborted, or the lease closed while the chooser was open.
+ *
+ * Distinct from an infrastructure failure, which is an error: a cancellation
+ * stops the record, it does not fail it. The marker (rather than a plain
+ * `instanceof`) keeps the classification working even if the throwing and
+ * catching module instances differ.
+ */
+export class SelectionCancelledError extends Error {
+	readonly [CANCELLATION_MARKER] = true;
+
+	constructor(message = "The spawn selection was cancelled.") {
+		super(message);
+	}
+}
+
+/** Whether an error means a cancelled selection rather than a failed one. */
+export function isSelectionCancellation(err: unknown): boolean {
+	return (
+		typeof err === "object" &&
+		err !== null &&
+		(err as Record<symbol, unknown>)[CANCELLATION_MARKER] === true
+	);
+}
+
+/** The three lease states a root's selection scope moves through, in order. */
+export type SelectionLeaseState = "unconfigured" | "active" | "revoked";
+
+/** A handle a construction wrapper created and a runtime may or may not retain. */
+interface ConstructedHandle extends SelectionScopeHandle {
+	/** True once a runtime captured this handle as its retained dependency. */
+	wasRetained(): boolean;
+}
+
+/** The closed-handle denial every new construction from a closed scope reads. */
+function closedScopeError(): Error {
+	return new Error("Spawn selection scope is closed; no further child can be created from it.");
+}
+
+/**
+ * The root runtime generation's selection lease.
+ *
+ * Created by the extension factory when no ambient construction context exists
+ * (the root); captured — never re-created — when one does (a descendant).
+ */
+export class SpawnSelectionScope implements SelectionScopeHandle {
+	readonly rootId: string;
+
+	private leaseState: SelectionLeaseState = "unconfigured";
+	private provider?: SpawnSelectionProvider;
+	private readonly children = new Set<ChildSelectionScope>();
+	private readonly closure = new AbortController();
+
+	constructor() {
+		this.rootId = `spawn-selection-${randomUUID()}`;
+	}
+
+	/** The lease's current state — unconfigured, active, or revoked. */
+	get state(): SelectionLeaseState {
+		return this.leaseState;
+	}
+
+	/** The registered provider, defined only while the lease is active. */
+	get activeProvider(): SpawnSelectionProvider | undefined {
+		return this.leaseState === "active" ? this.provider : undefined;
+	}
+
+	/** Aborts when the lease is revoked — the root's own closure. */
+	get closureSignal(): AbortSignal {
+		return this.closure.signal;
+	}
+
+	/** How many direct child handles are still open (diagnostics and tests). */
+	get openChildCount(): number {
+		return this.children.size;
+	}
+
+	/**
+	 * Register the single provider this root's tree will consult. Only an
+	 * unconfigured root accepts one: a second registration on an active lease
+	 * and any registration on a revoked lease are both refused — a closed
+	 * generation cannot reactivate itself.
+	 */
+	register(provider: SpawnSelectionProvider): SpawnSelectionRegistration {
+		if (this.leaseState === "active") {
+			throw new Error("A spawn selection provider is already registered for this session.");
+		}
+		if (this.leaseState === "revoked") {
+			throw new Error(
+				"This session's spawn selection scope is closed; a new session is required to register a provider.",
+			);
+		}
+		this.provider = provider;
+		this.leaseState = "active";
+		let disposed = false;
+		return {
+			kind: "owned",
+			dispose: () => {
+				if (disposed) return;
+				disposed = true;
+				this.revoke();
+			},
+		};
+	}
+
+	/**
+	 * Revoke the lease: deny every later registration and construction, and
+	 * close all descendant handles. Idempotent. Aborts the closure signal so a
+	 * pending chooser is dismissed rather than awaited by manager disposal.
+	 */
+	revoke(): void {
+		if (this.leaseState === "revoked") return;
+		this.leaseState = "revoked";
+		this.provider = undefined;
+		this.closure.abort();
+		const children = [...this.children];
+		this.children.clear();
+		for (const child of children) child.close();
+	}
+
+	/** The root lease's provider — selection is required while it is defined. */
+	activeSelectionProvider(): SpawnSelectionProvider | undefined {
+		return this.activeProvider;
+	}
+
+	constructChild<T>(thunk: () => Promise<T>): Promise<T> {
+		if (this.leaseState === "revoked") return Promise.reject(closedScopeError());
+		return this.adoptChild(new ChildSelectionScope(this), thunk);
+	}
+
+	close(): void {
+		this.revoke();
+	}
+
+	/** A root is never retained by a construction wrapper — it owns itself. */
+	retain(): void {
+		/* no-op: the root's lifetime is the runtime's, not a thunk's */
+	}
+
+	/** Wrap a freshly created child handle and track it as open. */
+	private adoptChild<T>(child: ChildSelectionScope, thunk: () => Promise<T>): Promise<T> {
+		this.children.add(child);
+		return runInConstructionContext(child, thunk).finally(() => {
+			if (child.isClosed()) this.children.delete(child);
+		});
+	}
+
+	/** Detach a child that closed itself (its own shutdown path). */
+	detach(child: ChildSelectionScope): void {
+		this.children.delete(child);
+	}
+}
+
+/**
+ * A descendant's non-owning handle to the root's lease. Captured during the
+ * child core factory's initialization and retained for the child runtime's
+ * lifetime; registration is denied here (`inherited`) whatever the root's
+ * state, so a child can neither install nor revoke the root's provider.
+ */
+export class ChildSelectionScope implements ConstructedHandle {
+	readonly rootId: string;
+
+	private closed = false;
+	private retained = false;
+	private readonly children = new Set<ChildSelectionScope>();
+	private readonly closure = new AbortController();
+
+	/** Created only by a construction wrapper — the root or a parent child handle. */
+	constructor(private readonly root: SpawnSelectionScope) {
+		this.rootId = root.rootId;
+	}
+
+	/** Aborts when this handle closes — its own shutdown or the root's revocation. */
+	// fallow-ignore-next-line unused-class-member -- reached via SelectionScopeHandle dispatch (gated run abort)
+	get closureSignal(): AbortSignal {
+		return this.closure.signal;
+	}
+
+	/** The root lease's provider — a descendant asks with the same authority. */
+	// fallow-ignore-next-line unused-class-member -- reached via SelectionScopeHandle dispatch (gated run consults the root lease)
+	activeSelectionProvider(): SpawnSelectionProvider | undefined {
+		return this.root.activeSelectionProvider();
+	}
+
+	// fallow-ignore-next-line unused-class-member -- reached via SelectionScopeHandle dispatch (a descendant's own spawns)
+	constructChild<T>(thunk: () => Promise<T>): Promise<T> {
+		if (this.closed) return Promise.reject(closedScopeError());
+		const grandchild = new ChildSelectionScope(this.root);
+		this.children.add(grandchild);
+		return runInConstructionContext(grandchild, thunk).finally(() => {
+			if (grandchild.isClosed()) this.children.delete(grandchild);
+		});
+	}
+
+	/**
+	 * The denied registration: installs nothing, touches nothing. Applies to a
+	 * live handle and a closed one alike — a closed inherited lease stays
+	 * denied rather than becoming installable or throwing.
+	 */
+	// fallow-ignore-next-line unused-class-member -- reached via SelectionScopeHandle dispatch (runtime.registerSpawnSelectionProvider)
+	register(_provider: SpawnSelectionProvider): SpawnSelectionRegistration {
+		return { kind: "inherited", dispose: () => {} };
+	}
+
+	// fallow-ignore-next-line unused-class-member -- reached via SelectionScopeHandle dispatch (captureInheritedSelectionScope)
+	retain(): void {
+		this.retained = true;
+	}
+
+	wasRetained(): boolean {
+		return this.retained;
+	}
+
+	/** True once this handle (or the root's revocation) closed it. */
+	isClosed(): boolean {
+		return this.closed;
+	}
+
+	/**
+	 * Close this handle and its subtree only. The root's lease and unrelated
+	 * siblings are untouched; the root stops tracking this child. Aborts the
+	 * closure signal so this subtree's pending selections are invalidated.
+	 */
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.closure.abort();
+		const children = [...this.children];
+		this.children.clear();
+		for (const child of children) child.close();
+		this.root.detach(this);
+	}
+}