one-code-extension 0.4.0 → 0.5.0

package/extensions/lib/powershell-parser.ts

@@ -0,0 +1,344 @@
+/**
+ * PowerShell's own parser as a service: one long-lived parse server per
+ * process, run on the PowerShell the tool itself runs, so the gate reads a
+ * line exactly as it will execute (decisions/windows.md "The PowerShell
+ * pre-gate reads PowerShell's own parse"; the tree-sitter grammars it replaces
+ * are measured in findings §41).
+ *
+ * {@link PowerShellParser.parse} never rejects. Anything short of a clean
+ * answer, whether the server could not start, timed out, crashed, runs in
+ * Constrained Language Mode or stopped for good after too many crashes,
+ * resolves to `{ ok: false, reason }`, and the caller treats the line as
+ * unparsed (the classifier decides). A parse with errors is still `ok: true`:
+ * the tree and its `errors` are PowerShell's answer; judging them is the
+ * caller's job.
+ *
+ * Lifecycle. The server starts on the first request and stops after
+ * `idleMs` without one; the next request starts it again. A crash, or a
+ * request that times out (the server is then killed), counts toward
+ * `maxRestarts`; past it the parser stays unavailable for the life of the
+ * process. The child, its pipes and every timer are unref'd, so an idle
+ * server never holds a finished one-shot run open; a caller that awaits a
+ * parse in one holds its own ref (`withKeepAlive`). The server also exits on
+ * its own when this process ends, because its stdin closes.
+ *
+ * Pure: no pi imports. The caller supplies `spawnServer`, which starts the
+ * right executable with the bootstrap after `-Command`, so the BI fork can use
+ * its own launcher.
+ */
+
+import type { ChildProcess } from "node:child_process";
+import { POWERSHELL_PARSE_BOOTSTRAP, POWERSHELL_PARSE_WALKER } from "./powershell-parse-script.ts";
+import { unrefHandle } from "./process-tree.ts";
+
+/** One syntax-tree node, as the walker reports it (powershell-parse-script.ts). */
+export interface PowerShellAstNode {
+	/** The .NET type name: `CommandAst`, `StringConstantExpressionAst`, … */
+	type: string;
+	/** Index of the parent node in `nodes`; -1 for the root. */
+	parent: number;
+	/** Extent as UTF-16 offsets into the command (JS string indices). */
+	start: number;
+	end: number;
+	/** CommandAst: the static command name (null when not static). CommandParameterAst: the parameter. VariableExpressionAst: the variable path. Type nodes: the type's full name. */
+	name?: string | null;
+	/** String and constant nodes: the value PowerShell resolved (quotes and escapes applied). */
+	value?: string | null;
+	/** String nodes: `BareWord`, `SingleQuoted`, `DoubleQuoted`, `SingleQuotedHereString`, `DoubleQuotedHereString`. */
+	kind?: string;
+	/** CommandAst: the invocation operator (`Unknown`, `Ampersand`, `Dot`). Operator nodes: the operator. */
+	operator?: string;
+	/** VariableExpressionAst: `@name` splatting. */
+	splatted?: boolean;
+	/** Redirections: the stream redirected (`Output`, `Error`, `All`, …) and, for a merge, where to. */
+	from?: string;
+	to?: string;
+	/** FileRedirectionAst: `>>`. */
+	append?: boolean;
+	/** Pipelines and pipeline chains: a trailing `&` (PowerShell 7). */
+	background?: boolean;
+	/** Member access: `::`. */
+	static?: boolean;
+	/** CommandAst with a static name that resolves in this PowerShell: the resolved command's type (`Cmdlet`, `Application`, `Function`, …), after an alias. */
+	commandType?: string;
+	/** CommandAst: the name was an alias. */
+	alias?: boolean;
+	/** CommandAst: the resolved cmdlet's name, or an application's full path. */
+	resolvedName?: string;
+	/** CommandAst: the resolved command's module (empty for an application). */
+	module?: string;
+	/**
+	 * CommandAst of a cmdlet: PowerShell's static parameter binding. `value` is
+	 * the bound argument's node index, -1 for a switch given alone, and -2 for a
+	 * value the binder built itself: the arguments a remaining-arguments
+	 * parameter collects (`Write-Output a b`), whose node indices are
+	 * `elements` (-1 for one that matched no argument).
+	 */
+	bindings?: Array<{ parameter: string; value: number; elements?: number[] }>;
+	/** CommandAst of a cmdlet: the arguments or parameters the binder could not bind (an unknown or ambiguous name, a surplus positional, a repeat). */
+	bindingErrors?: string[];
+	/** CommandAst of a cmdlet: the static binder is missing or threw. */
+	bindingUnavailable?: boolean;
+}
+
+export interface PowerShellParse {
+	/** The tree in pre-order, root first. */
+	nodes: PowerShellAstNode[];
+	/** Each parse error's ErrorId. PowerShell runs nothing from a line that has one. */
+	errors: string[];
+}
+
+export type PowerShellParseOutcome = { ok: true; parse: PowerShellParse } | { ok: false; reason: string };
+
+export interface PowerShellParserOptions {
+	/** Start the server: the PowerShell executable with `bootstrap` as the argument after `-Command`, stdio all piped. */
+	spawnServer: (bootstrap: string) => ChildProcess;
+	/** How long the first request waits while the server starts. */
+	startTimeoutMs?: number;
+	/** How long a request waits once the server is ready. */
+	requestTimeoutMs?: number;
+	/** Crashes and timeouts tolerated before the parser stays unavailable. */
+	maxRestarts?: number;
+	/** Stop the server after this long without a request. */
+	idleMs?: number;
+}
+
+export const POWERSHELL_PARSE_START_TIMEOUT_MS = 5_000;
+export const POWERSHELL_PARSE_REQUEST_TIMEOUT_MS = 2_000;
+export const POWERSHELL_PARSE_MAX_RESTARTS = 3;
+export const POWERSHELL_PARSE_IDLE_MS = 10 * 60_000;
+
+interface Pending {
+	resolve: (outcome: PowerShellParseOutcome) => void;
+	timer: ReturnType<typeof setTimeout>;
+}
+
+interface Server {
+	child: ChildProcess;
+	ready: boolean;
+	/** Set once the server is gone or being stopped; its late output and exit are ignored. */
+	stopped: boolean;
+	/** Why it stopped. */
+	reason?: string;
+	buffer: string;
+	pending: Map<number, Pending>;
+}
+
+const encode = (text: string) => Buffer.from(text, "utf8").toString("base64");
+
+export class PowerShellParser {
+	private readonly options: Required<PowerShellParserOptions>;
+	private server: Server | undefined;
+	private nextId = 1;
+	private failures = 0;
+	/** Why the parser is unavailable for good; set past `maxRestarts`, or when the server runs in a restricted language mode. */
+	private disabled: string | undefined;
+	private idleTimer: ReturnType<typeof setTimeout> | undefined;
+
+	constructor(options: PowerShellParserOptions) {
+		this.options = {
+			startTimeoutMs: POWERSHELL_PARSE_START_TIMEOUT_MS,
+			requestTimeoutMs: POWERSHELL_PARSE_REQUEST_TIMEOUT_MS,
+			maxRestarts: POWERSHELL_PARSE_MAX_RESTARTS,
+			idleMs: POWERSHELL_PARSE_IDLE_MS,
+			...options,
+		};
+	}
+
+	/** Why the parser cannot answer at all, or undefined while it can (or can still start). */
+	unavailable(): string | undefined {
+		return this.disabled;
+	}
+
+	/** Parse `command` with PowerShell's own parser. Never rejects. */
+	parse(command: string): Promise<PowerShellParseOutcome> {
+		if (this.disabled) return Promise.resolve({ ok: false, reason: this.disabled });
+		let server: Server;
+		try {
+			server = this.server ?? this.start();
+		} catch (error) {
+			return Promise.resolve({ ok: false, reason: this.fail(`PowerShell could not start: ${message(error)}`) });
+		}
+		// A server can fail while it starts (a spawn error, a restricted language
+		// mode) before this request is registered with it.
+		if (server.stopped) return Promise.resolve({ ok: false, reason: this.disabled ?? server.reason ?? "the PowerShell parser stopped" });
+		this.touch();
+		const id = this.nextId++;
+		return new Promise((resolve) => {
+			const timeoutMs = server.ready ? this.options.requestTimeoutMs : this.options.startTimeoutMs;
+			const timer = setTimeout(() => {
+				server.pending.delete(id);
+				resolve({ ok: false, reason: `the PowerShell parser did not answer within ${timeoutMs} ms` });
+				this.crashed(server, `the PowerShell parser timed out after ${timeoutMs} ms`);
+			}, timeoutMs);
+			unrefHandle(timer);
+			server.pending.set(id, { resolve, timer });
+			server.child.stdin?.write(`${id} ${encode(command)}\n`);
+		});
+	}
+
+	/** Stop the server. The next request starts a new one. */
+	stop(): void {
+		const server = this.server;
+		if (!server) return;
+		this.server = undefined;
+		this.clearIdle();
+		this.settleAll(server, "the PowerShell parser was stopped");
+		server.stopped = true;
+		server.child.stdin?.end();
+		server.child.kill();
+	}
+
+	private start(): Server {
+		const child = this.options.spawnServer(POWERSHELL_PARSE_BOOTSTRAP);
+		const server: Server = { child, ready: false, stopped: false, buffer: "", pending: new Map() };
+		this.server = server;
+		child.stdin?.on("error", () => {});
+		child.stdout?.setEncoding("ascii");
+		child.stdout?.on("data", (chunk: string) => this.receive(server, chunk));
+		// PowerShell's own error output is not part of the protocol; drain it so
+		// the pipe never fills.
+		child.stderr?.on("data", () => {});
+		child.on("error", (error) => this.crashed(server, `PowerShell could not start: ${message(error)}`));
+		child.on("exit", (code, signal) => this.crashed(server, `the PowerShell parser exited (${signal ?? `code ${code}`})`));
+		unrefHandle(child);
+		unrefHandle(child.stdin);
+		unrefHandle(child.stdout);
+		unrefHandle(child.stderr);
+		child.stdin?.write(`${encode(POWERSHELL_PARSE_WALKER)}\n`);
+		return server;
+	}
+
+	private receive(server: Server, chunk: string): void {
+		if (server.stopped) return;
+		server.buffer += chunk;
+		for (let newline = server.buffer.indexOf("\n"); newline >= 0; newline = server.buffer.indexOf("\n")) {
+			const line = server.buffer.slice(0, newline).trim();
+			server.buffer = server.buffer.slice(newline + 1);
+			if (line) this.record(server, line);
+			if (server.stopped) return;
+		}
+	}
+
+	private record(server: Server, line: string): void {
+		let record: Record<string, unknown>;
+		try {
+			record = JSON.parse(Buffer.from(line, "base64").toString("utf8")) as Record<string, unknown>;
+		} catch {
+			this.crashed(server, "the PowerShell parser wrote a line that is not part of its protocol");
+			return;
+		}
+		if (record.id === 0) {
+			if (record.language !== "FullLanguage") {
+				// Constrained Language Mode (or stricter) is a machine policy, so a
+				// restart cannot change it.
+				this.disabled = `PowerShell runs in ${String(record.language)} mode, where the parser is not available`;
+				this.crashed(server, this.disabled);
+				return;
+			}
+			// Failures are not reset here: a line that hangs the walker would
+			// otherwise restart it forever.
+			server.ready = true;
+			return;
+		}
+		const pending = typeof record.id === "number" ? server.pending.get(record.id) : undefined;
+		if (!pending) return;
+		server.pending.delete(record.id as number);
+		clearTimeout(pending.timer);
+		if (typeof record.failure === "string") {
+			pending.resolve({ ok: false, reason: `the PowerShell parser failed: ${record.failure}` });
+			return;
+		}
+		pending.resolve({ ok: true, parse: { nodes: asArray(record.nodes).map(normalizeNode), errors: asArray(record.errors).map(String) } });
+	}
+
+	/** The server is gone or unusable: settle what waits on it and count the failure. */
+	private crashed(server: Server, reason: string): void {
+		if (server.stopped) return;
+		server.stopped = true;
+		server.reason = reason;
+		if (this.server === server) this.server = undefined;
+		this.clearIdle();
+		this.settleAll(server, reason);
+		server.child.stdin?.end();
+		server.child.kill();
+		this.fail(reason);
+	}
+
+	private fail(reason: string): string {
+		this.failures++;
+		if (!this.disabled && this.failures > this.options.maxRestarts) {
+			this.disabled = `the PowerShell parser is off after ${this.failures} failures (last: ${reason})`;
+		}
+		return reason;
+	}
+
+	private settleAll(server: Server, reason: string): void {
+		for (const pending of server.pending.values()) {
+			clearTimeout(pending.timer);
+			pending.resolve({ ok: false, reason });
+		}
+		server.pending.clear();
+	}
+
+	private touch(): void {
+		this.clearIdle();
+		this.idleTimer = setTimeout(() => this.stop(), this.options.idleMs);
+		unrefHandle(this.idleTimer);
+	}
+
+	private clearIdle(): void {
+		if (this.idleTimer) clearTimeout(this.idleTimer);
+		this.idleTimer = undefined;
+	}
+}
+
+/**
+ * A node with its list fields made lists: ConvertTo-Json may write a
+ * one-element list as the element. A binding list that is not one after
+ * that marks the binding unavailable, which the gate refuses.
+ */
+function normalizeNode(value: unknown): PowerShellAstNode {
+	const node = { ...(value as PowerShellAstNode) };
+	if (node.bindingErrors !== undefined) node.bindingErrors = asArray(node.bindingErrors).map(String);
+	if (node.bindings !== undefined) {
+		const bindings = asArray(node.bindings) as Array<{ parameter?: unknown; value?: unknown; elements?: unknown }>;
+		if (bindings.every((b) => b !== null && typeof b === "object" && typeof b.parameter === "string" && typeof b.value === "number")) {
+			node.bindings = bindings.map((b) => ({ parameter: b.parameter as string, value: b.value as number, ...(b.elements === undefined ? {} : { elements: asArray(b.elements).map(Number) }) }));
+		} else {
+			delete node.bindings;
+			node.bindingUnavailable = true;
+		}
+	}
+	return node;
+}
+
+function asArray(value: unknown): unknown[] {
+	if (Array.isArray(value)) return value;
+	// ConvertTo-Json writes a one-element array as that element on some
+	// PowerShell versions, and an empty one as null.
+	return value === undefined || value === null ? [] : [value];
+}
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+const STATE_KEY = Symbol.for("one-code.powershell-parser");
+
+/**
+ * The process-wide parser for one PowerShell executable. It lives on
+ * `globalThis`, not in module state: jiti gives each extension, and each
+ * in-process child session, its own instance of this module (findings §3), and
+ * one server per process is the point.
+ */
+export function sharedPowerShellParser(executable: string, create: () => PowerShellParser): PowerShellParser {
+	const store = globalThis as { [STATE_KEY]?: Map<string, PowerShellParser> };
+	const parsers = (store[STATE_KEY] ??= new Map());
+	let parser = parsers.get(executable);
+	if (!parser) {
+		parser = create();
+		parsers.set(executable, parser);
+	}
+	return parser;
+}

package/extensions/lib/process-tree.ts

@@ -14,9 +14,22 @@
  * The producer spawns `detached` (own process group; `detachedSpawnOptions`)
  * and stops it with `killProcessTree`, which signals the negative pid — the
  * whole group — falling back to the child alone when the group is already gone.
- * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL if the leader
- * has not exited by then (a command that ignores SIGTERM still closes late,
- * which is exactly the late callback the shutdown paths guard against).
+ * `stopProcessTree` adds the grace period: SIGTERM now, SIGKILL to the group
+ * when it ends, whether or not the leader is still alive. The leader is often
+ * only the `bash -c` wrapper, which dies on TERM at once while the command it
+ * forked (a dev server in its graceful-shutdown handler) keeps the group and
+ * its port; a leader-only check skipped the SIGKILL exactly then
+ * (LIFECYCLE-BACKGROUND-REVIEW-2026-09-26 M1, measured). A group whose SIGKILL
+ * is still pending when the process exits (pi's quit calls `process.exit`,
+ * and the grace timer is unref'd) is SIGKILLed from a `process.on("exit")`
+ * hook, so nothing One Code stopped outlives it.
+ *
+ * `rememberProcessGroup` owns a background shell's group for the lifetime of
+ * this process, including descendants left by a successfully exited leader.
+ * Session replacement must not kill those intentionally launched daemons.
+ * Each module instance keeps its own groups through process listeners (never
+ * through a session context or cross-extension module state), reaps empty
+ * groups, and sends TERM synchronously on process exit or termination signals.
  *
  * `waitForChildExit` is the counterpart on the waiting side: it settles on
  * `exit` plus a short stdio grace, never on `close` alone — a descendant the
@@ -37,6 +50,16 @@ export const EXIT_STDIO_GRACE_MS = 200;
 /** ...and the most it may keep arriving in total: a straggler writing continuously must not keep re-arming the grace. */
 export const EXIT_STDIO_MAX_MS = 2_000;
 
+/**
+ * Unref a child process, one of its stdio streams or a timer, so it never
+ * holds the event loop open on its own (a finished one-shot run can exit);
+ * a caller awaiting it holds its own ref. Child pipes are sockets at run
+ * time and carry `unref()` even though their stream types do not declare it.
+ */
+export function unrefHandle(handle: unknown): void {
+	(handle as { unref?: () => void } | null | undefined)?.unref?.();
+}
+
 /**
  * `detached` everywhere but Windows, where process groups do not exist — except
  * for a child that must outlive an exiting parent (a fire-and-forget hook),
@@ -95,20 +118,120 @@ export function killProcessTree(child: ChildProcess, signal: NodeJS.Signals = "S
 	}
 }
 
+/** Groups owned by this producer, retained by process listeners across session replacement. */
+const rememberedGroups = new Set<ChildProcess>();
+let groupReaper: NodeJS.Timeout | undefined;
+const terminationSignals = ["SIGINT", "SIGTERM", "SIGHUP"] as const;
+const groupSignalHandlers = new Map<NodeJS.Signals, () => void>();
+
+/**
+ * Whether a remembered tree still needs killing at exit. Windows has no
+ * process groups, so only a live leader is worth a `taskkill /T`; it is judged
+ * by the child's own exit state, because once the leader exits Windows may
+ * hand its pid to an unrelated process that a pid probe would then find. On
+ * POSIX a group id stays reserved while any member lives, and the reaper
+ * forgets an emptied group within a second, far sooner than sequential pid
+ * allocation wraps around to it.
+ */
+export function rememberedGroupAlive(child: ChildProcess): boolean {
+	if (child.pid == null) return false;
+	if (process.platform === "win32") return child.exitCode === null && child.signalCode === null;
+	try {
+		process.kill(-child.pid, 0);
+		return true;
+	} catch (error) {
+		return (error as NodeJS.ErrnoException).code !== "ESRCH";
+	}
+}
+
+function releaseGroupListeners(): void {
+	if (groupReaper) clearInterval(groupReaper);
+	groupReaper = undefined;
+	process.removeListener("exit", terminateRememberedGroups);
+	for (const [signal, handler] of groupSignalHandlers) process.removeListener(signal, handler);
+	groupSignalHandlers.clear();
+}
+
+/** Exit handlers cannot await a grace period. Existing explicit stops retain their TERM/KILL escalation below. */
+function terminateRememberedGroups(): void {
+	for (const child of rememberedGroups) {
+		if (rememberedGroupAlive(child)) killProcessTree(child, "SIGTERM");
+	}
+	rememberedGroups.clear();
+	releaseGroupListeners();
+}
+
 /**
- * SIGTERM the tree, then SIGKILL it after `graceMs` unless the leader exited.
- * The timer is unref'd: it must never be what keeps a one-shot process alive.
+ * Remember a detached background tree from spawn until its group becomes empty.
+ * Register before awaiting its leader, so even immediate process exit covers
+ * running work. The unref'd reaper cannot keep a print run alive. No session
+ * shutdown handler touches this set; process listeners keep its module instance
+ * alive even when jiti builds a new extension instance after /clear.
+ */
+export function rememberProcessGroup(child: ChildProcess): void {
+	if (child.pid == null || rememberedGroups.has(child)) return;
+	rememberedGroups.add(child);
+	if (groupReaper) return;
+	process.on("exit", terminateRememberedGroups);
+	for (const signal of terminationSignals) {
+		const handler = () => {
+			terminateRememberedGroups();
+			// Do not swallow Node's default signal termination when there is no
+			// pi handler. With isolated producers, the last listener re-raises it.
+			if (process.listenerCount(signal) === 0) process.kill(process.pid, signal);
+		};
+		groupSignalHandlers.set(signal, handler);
+		// Run before signal-exit observers: after we remove ourselves they must
+		// still see the original listener count and preserve default termination.
+		process.prependOnceListener(signal, handler);
+	}
+	groupReaper = setInterval(() => {
+		for (const child of rememberedGroups) {
+			if (!rememberedGroupAlive(child)) rememberedGroups.delete(child);
+		}
+		if (rememberedGroups.size === 0) releaseGroupListeners();
+	}, 1_000);
+	groupReaper.unref?.();
+}
+
+/**
+ * Trees sent SIGTERM whose SIGKILL has not run yet. Keyed by the child, not
+ * its pid, so a pid the OS hands to a new child during the grace does not
+ * make that child look already scheduled. Per module instance on purpose
+ * (each extension force-kills its own children); one `exit` listener per
+ * instance, installed on first use.
+ */
+const pendingKills = new Set<ChildProcess>();
+let exitHookInstalled = false;
+
+/** The process is exiting: the grace timers will never fire, so force-kill every tree still pending. */
+function killPendingAtExit(): void {
+	for (const child of pendingKills) killProcessTree(child, "SIGKILL");
+	pendingKills.clear();
+}
+
+/**
+ * SIGTERM the tree, then SIGKILL the whole group after `graceMs`, whatever
+ * the leader's state: a group already gone makes that an ESRCH, and a live
+ * group keeps its id reserved, so the id cannot name anyone else. The timer
+ * is unref'd (it must never be what keeps a one-shot process alive); a
+ * process exit before it fires runs the SIGKILL from the `exit` hook.
  */
 export function stopProcessTree(child: ChildProcess, graceMs: number): void {
 	killProcessTree(child, "SIGTERM");
 	// taskkill /F is already forceful; there is no gentler first signal to grace.
 	if (process.platform === "win32") return;
-	if (child.exitCode !== null || child.signalCode !== null) return;
+	if (child.pid == null || pendingKills.has(child)) return;
+	pendingKills.add(child);
+	if (!exitHookInstalled) {
+		exitHookInstalled = true;
+		process.on("exit", killPendingAtExit);
+	}
 	const timer = setTimeout(() => {
-		if (child.exitCode === null && child.signalCode === null) killProcessTree(child, "SIGKILL");
+		if (!pendingKills.delete(child)) return;
+		killProcessTree(child, "SIGKILL");
 	}, graceMs);
 	timer.unref?.();
-	child.once("exit", () => clearTimeout(timer));
 }
 
 export interface ChildExit {

package/extensions/lib/prompt-options.ts

@@ -0,0 +1,82 @@
+/**
+ * pi's system-prompt options for a session no `prompt()` has run in yet.
+ *
+ * A turn an extension opens from idle skips `before_agent_start`, the one
+ * event that carries the options (upstream ask #17). After the first typed
+ * prompt the extensions rebuild from what that event saw (system-prompt's
+ * idle-turn.ts). Before it they have nothing, so a background completion that
+ * opens a session's first turn used to go out as a user message, which takes
+ * the prompt path and renders as a user bubble.
+ *
+ * A command handler's context does carry the options
+ * (`getSystemPromptOptions`, the same base object `before_agent_start`
+ * receives). So the command that starts background work announces them here:
+ * system-prompt builds the prompt from them, the skill extension lists its
+ * skills, and the notifier opens the turn with the notification itself as a
+ * custom message, rendered like every later one. Pure: no pi imports.
+ *
+ * The same module carries the fork's system-prompt request (below).
+ */
+
+export const PROMPT_OPTIONS_CHANNEL = "one-code:prompt-options";
+
+/**
+ * Whether a `before_agent_start` event opens a run the user typed. pi 1.2.0
+ * also fires the event for a run an extension opens from idle with
+ * `sendMessage(…, { triggerTurn: true })` (a notification, the Stop hook's
+ * continuation, a scheduled fire), marked `messageType: "custom"` and without
+ * `prompt`. Older pi fires it only for prompts and sends no `messageType`.
+ */
+export function isUserRun<E>(event: E): event is Exclude<E, { messageType: "custom" }> {
+	return (event as { messageType?: unknown } | undefined)?.messageType !== "custom";
+}
+
+/** The payload: pi's base options, and the session cwd they were read in. */
+export interface PromptOptionsAnnouncement {
+	options: unknown;
+	cwd: string;
+}
+
+/**
+ * Emit the options of a command context. A context without
+ * `getSystemPromptOptions` (an event handler's, or an older pi) announces
+ * nothing, and the listeners keep their first-turn fallbacks.
+ */
+export function announcePromptOptions(events: { emit(channel: string, data: unknown): void }, ctx: unknown): void {
+	const context = ctx as { getSystemPromptOptions?: () => unknown; cwd?: string } | undefined;
+	if (typeof context?.getSystemPromptOptions !== "function") return;
+	let options: unknown;
+	try {
+		options = context.getSystemPromptOptions();
+	} catch {
+		return; // A torn-down session: nothing to announce.
+	}
+	if (!options || typeof options !== "object") return;
+	events.emit(PROMPT_OPTIONS_CHANNEL, { options, cwd: context.cwd ?? "" } satisfies PromptOptionsAnnouncement);
+}
+
+/**
+ * The system prompt a fork inherits. `ctx.getSystemPrompt()` is pi's own
+ * prompt whenever One Code's is not installed on pi's run: between turns (pi
+ * drops a run's options when it settles), before the first prompt, and in a
+ * turn opened from idle (installed on the wire only, by context_with_system).
+ * A fork started then ran on pi's stock prompt. The system-prompt extension
+ * answers this request synchronously with the prompt the session's next
+ * request carries; no answer (not loaded, a named agent's own prompt, nothing
+ * to build from) leaves the caller's fallback.
+ */
+export const SYSTEM_PROMPT_REQUEST_CHANNEL = "one-code:system-prompt-request";
+
+export interface SystemPromptRequest {
+	/** The requester's context: cwd and model shape the prompt. */
+	ctx: unknown;
+	/** Set by the listener before it returns. */
+	prompt?: string;
+}
+
+/** Ask for One Code's system prompt; `undefined` when nobody answered. */
+export function requestSystemPrompt(events: { emit(channel: string, data: unknown): void }, ctx: unknown): string | undefined {
+	const request: SystemPromptRequest = { ctx };
+	events.emit(SYSTEM_PROMPT_REQUEST_CHANNEL, request);
+	return typeof request.prompt === "string" ? request.prompt : undefined;
+}

package/extensions/lib/queued-delivery.ts

@@ -0,0 +1,44 @@
+/**
+ * Hold something for a message the user queued mid-turn until pi delivers it.
+ *
+ * Since pi 0.86 the `input` event also fires for a message queued while a turn
+ * runs (`streamingBehavior` set; interactive queue, RPC steer/follow_up). A
+ * one-shot reminder emitted there is taken by whatever the model reads next,
+ * usually the running tool's result, so it lands before the message it is
+ * about, a request or more early for a follow-up. A context message of its
+ * own is no better: pi drains one queued message per request, so it arrives a
+ * request late. Instead the caller holds the payload here, keyed by the typed
+ * text, and releases it from `message_start` when pi delivers the user message
+ * with that text (compare with pi-ai's `contentText(content, "")`, the
+ * comparison pi uses for its own queue). pi awaits `message_start` before the
+ * request that carries the message, so a `last-append` one-shot emitted then
+ * is pinned to that message.
+ *
+ * A queued message pi expands first (a prompt template) never matches, nor
+ * does one an extension replaces, unless its replacement carries the typed
+ * text (the skill extension's `details.input`, which hooks matches). Clear on `agent_settled` so its payload
+ * never rides a later, unrelated prompt, and on `session_start`.
+ *
+ * Pure (no pi imports); each extension keeps its own instance.
+ */
+export class QueuedDelivery<T> {
+	private entries: Array<{ text: string; payload: T }> = [];
+
+	hold(text: string, payload: T): void {
+		this.entries.push({ text, payload });
+	}
+
+	/** The payload held for the delivered message with this text, oldest first; removed once released. */
+	release(text: string): T | undefined {
+		const index = this.entries.findIndex((entry) => entry.text === text);
+		return index === -1 ? undefined : this.entries.splice(index, 1)[0].payload;
+	}
+
+	get isEmpty(): boolean {
+		return this.entries.length === 0;
+	}
+
+	clear(): void {
+		this.entries = [];
+	}
+}