@tshu-w/pi-agents 0.0.0-stage → 0.1.0

package/src/programs/execute.ts

@@ -0,0 +1,131 @@
+/**
+ * Runs one Program with Pi's `codemode` executor, so the script API, result format, and
+ * truncation are Pi's own. Programs add globals such as `agent()`, a `timeout`, and calls
+ * that outlive the `program` tool call; `withSandboxExtras` passes them to the sandbox.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CodemodeResult, CodemodeTool } from "@earendil-works/pi-codemode";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionToolContext } from "@earendil-works/pi-coding-agent";
+import { loadCodemode, loadPiCodemode } from "./codemode.ts";
+import type { DetachedCallOptions } from "./host-patches.ts";
+
+export const PROGRAM_TOOL_NAME = "program";
+
+export type ProgramOutcome = "completed" | "failed" | "stopped";
+
+/** Paths passed to `read`, `write`, and `edit`, which compaction lists like Pi's file operations. */
+export interface ProgramFiles {
+	read: string[];
+	written: string[];
+	edited: string[];
+}
+
+export interface ProgramRunResult {
+	outcome: ProgramOutcome;
+	result: AgentToolResult<unknown> & { isError?: boolean };
+	files: ProgramFiles;
+	/** Whether some of the Program's work did not stop during cleanup. */
+	abandoned?: boolean;
+}
+
+export interface ProgramRunOptions {
+	/** Seconds until the Program stops; the script's `timeout_ms` option applies as well. */
+	timeout?: number;
+	/** Globals added to the script, such as the host side of `agent()`. */
+	globals?: CodemodeTool[];
+	/** Rewrites the code before it runs, such as prepending the `agent()` prelude. */
+	prepare?: (code: string) => string;
+	onUpdate?: AgentToolUpdateCallback<unknown>;
+	/**
+	 * Whether the Program runs after its tool call returns. Its calls then get their own IDs,
+	 * since Pi records nested calls only until the calling tool call returns.
+	 */
+	background?: boolean;
+	/** Stops a background Program; `ctx.abort()` of its calls' hooks and tools calls it. */
+	abort?: () => void;
+	appendEntry(customType: string, data: unknown): void;
+	getToolNamespace(name: string): { name: string } | undefined;
+}
+
+interface SandboxExtras {
+	globals: CodemodeTool[];
+	prepare: (code: string) => string;
+	timeoutMs: number;
+	result?: CodemodeResult;
+	used: boolean;
+}
+
+const sandboxExtras = new AsyncLocalStorage<SandboxExtras>();
+let sandboxPatched = false;
+
+/**
+ * Pi's executor creates and runs one sandbox per script. Its first execution in `extras`' async
+ * context gets the extras; later sandboxes there, such as those of Agents the Program created,
+ * do not.
+ */
+async function withSandboxExtras<T>(extras: SandboxExtras, run: () => Promise<T>): Promise<T> {
+	if (!sandboxPatched) {
+		sandboxPatched = true;
+		const proto = (await loadCodemode()).CodemodeSandbox.prototype as unknown as Record<string, any>;
+		const execute = proto.execute;
+		proto.execute = function (this: Record<string, any>, code: string, options: Record<string, unknown> = {}) {
+			const current = sandboxExtras.getStore();
+			if (!current || current.used) return execute.call(this, code, options);
+			current.used = true;
+			for (const global of current.globals) this.globalsByName.set(global.name, global);
+			const timeoutMs = Math.min(current.timeoutMs, (options.timeoutMs as number | undefined) ?? this.timeoutMs);
+			return execute.call(this, current.prepare(code), { ...options, timeoutMs }).then((result: CodemodeResult) => {
+				current.result = result;
+				return result;
+			});
+		};
+	}
+	return sandboxExtras.run(extras, run);
+}
+
+/**
+ * Runs one Program. The signal stops it; `ctx` must stay usable until the Program ends,
+ * which holds after the `program` tool call returns while the Session is loaded.
+ */
+export async function executeProgram(
+	toolCallId: string,
+	source: string,
+	signal: AbortSignal,
+	ctx: ExtensionToolContext,
+	options: ProgramRunOptions,
+): Promise<ProgramRunResult> {
+	const { executeCodemode } = await loadPiCodemode();
+	const files: ProgramFiles = { read: [], written: [], edited: [] };
+	const addFile = (name: string, args: unknown) => {
+		const path = (args as { path?: unknown } | undefined)?.path;
+		const list = name === "read" ? files.read : name === "write" ? files.written : name === "edit" ? files.edited : undefined;
+		if (typeof path === "string" && list && !list.includes(path)) list.push(path);
+	};
+	let detachedCalls = 0;
+	const programCtx = Object.create(ctx, {
+		tools: { get: () => ctx.tools.filter((tool) => tool.name !== PROGRAM_TOOL_NAME) },
+		executeTool: {
+			value: (name: string, args: unknown, callOptions: { signal?: AbortSignal } = {}) => {
+				if (!options.background) return ctx.executeTool(name, args, callOptions);
+				addFile(name, args);
+				const detachedOptions = { ...callOptions, detachedCallerId: `${toolCallId}:${++detachedCalls}`, detachedAbort: () => options.abort?.() } satisfies DetachedCallOptions;
+				return ctx.executeTool(name, args, detachedOptions as never);
+			},
+		},
+	}) as ExtensionToolContext;
+	const extras: SandboxExtras = {
+		globals: options.globals ?? [],
+		prepare: options.prepare ?? ((code) => code),
+		timeoutMs: options.timeout === undefined ? Number.POSITIVE_INFINITY : options.timeout * 1000,
+		used: false,
+	};
+	const result = await withSandboxExtras(extras, () => executeCodemode(toolCallId, { code: source }, signal, options.onUpdate, programCtx, {
+		models: true,
+		appendEntry: options.appendEntry,
+		getToolNamespace: options.getToolNamespace,
+	}));
+	const outcome: ProgramOutcome = extras.result?.ok
+		? "completed"
+		: extras.result?.error.kind === "timeout" || extras.result?.error.kind === "aborted" ? "stopped" : "failed";
+	return { outcome, result, files };
+}

package/src/programs/host-patches.ts

@@ -0,0 +1,128 @@
+/**
+ * Patches of Pi internals that background Programs need. They rely on private members of
+ * `AgentSession` and `ExtensionRunner`, so check them when Pi is updated.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { AgentSession, ExtensionRunner } from "@earendil-works/pi-coding-agent";
+import { CODEMODE_TOOL_NAME } from "./codemode.ts";
+import { PROGRAM_TOOL_NAME } from "./execute.ts";
+
+const PATCHED = Symbol.for("pi-agents:patched");
+const MCP_EXTENSION_PATH = "builtin:mcp";
+
+interface DetachedCall {
+	signal?: AbortSignal;
+	abort?: () => void;
+	active: boolean;
+}
+
+const detached = new AsyncLocalStorage<DetachedCall>();
+/** Set while the built-in MCP extension runs, including work it started. */
+const inMcp = new AsyncLocalStorage<true>();
+
+/** `ctx.executeTool()` options that run a call outside the calling tool call's record. */
+export interface DetachedCallOptions {
+	/** Replaces the calling tool call's ID, so the call gets the ID `<callerId>/1`. */
+	detachedCallerId: string;
+	/** What `ctx.abort()` of hooks and tools does during the call. */
+	detachedAbort: () => void;
+}
+
+type Patchable = Record<PropertyKey, any>;
+
+/**
+ * - A call with `detachedCallerId` runs under that ID: Pi numbers nested calls per caller and
+ *   resets the numbers when the calling tool call returns and when the turn ends, which would
+ *   repeat IDs across the calls of a background Program. While it runs, `ctx.signal` and
+ *   `ctx.abort()` of hooks and tools act on the call instead of the caller's turn.
+ * - The built-in MCP extension sees `program` as `codemode`: it activates `program` when its tools
+ *   need a script tool and neither is active, counts an active `program` as reaching its tools,
+ *   and makes a Program wait for the servers its code names, as it does for `codemode` scripts.
+ */
+export function installHostPatches(
+	session: typeof AgentSession,
+	runner: typeof ExtensionRunner,
+	codemodeSchema: unknown,
+): void {
+	const sessionProto = session.prototype as unknown as Patchable;
+	if (!sessionProto[PATCHED]) {
+		sessionProto[PATCHED] = true;
+		const execute = sessionProto._executeNestedToolCall;
+		sessionProto._executeNestedToolCall = async function (this: Patchable, callerId: string, name: string, args: unknown, options: Record<string, unknown> = {}) {
+			const { detachedCallerId, detachedAbort, ...rest } = options;
+			if (typeof detachedCallerId !== "string") return execute.call(this, callerId, name, args, options);
+			const extensions = this._extensionRunner as Patchable;
+			const getSignal = extensions.getSignalFn;
+			if (!getSignal[PATCHED]) {
+				const patched = () => {
+					const call = detached.getStore();
+					return call?.active ? call.signal : getSignal();
+				};
+				(patched as Patchable)[PATCHED] = true;
+				extensions.getSignalFn = patched;
+			}
+			const abort = extensions.abortFn;
+			if (!abort[PATCHED]) {
+				const patched = () => {
+					const call = detached.getStore();
+					return call?.active ? call.abort?.() : abort();
+				};
+				(patched as Patchable)[PATCHED] = true;
+				extensions.abortFn = patched;
+			}
+			const call: DetachedCall = { signal: rest.signal as AbortSignal | undefined, abort: detachedAbort as (() => void) | undefined, active: true };
+			try {
+				return await detached.run(call, () => execute.call(this, detachedCallerId, name, args, rest));
+			} finally {
+				// Work the call started, such as a turn it queued, keeps the store but not the signal.
+				call.active = false;
+			}
+		};
+	}
+	const runnerProto = runner.prototype as unknown as Patchable;
+	if (!runnerProto[PATCHED]) {
+		runnerProto[PATCHED] = true;
+		const bindCore = runnerProto.bindCore;
+		runnerProto.bindCore = function (this: Patchable, ...args: unknown[]) {
+			bindCore.apply(this, args);
+			const mcp = (this.extensions as Patchable[]).find((extension) => extension.path === MCP_EXTENSION_PATH);
+			if (mcp) aliasProgramForMcp(this, mcp, codemodeSchema);
+		};
+	}
+}
+
+function aliasProgramForMcp(runner: Patchable, mcp: Patchable, codemodeSchema: unknown): void {
+	if (!mcp[PATCHED]) {
+		mcp[PATCHED] = true;
+		const asCodemodeCall = (event: Patchable) => event.toolName === PROGRAM_TOOL_NAME && event.input?.action === "run"
+			? { ...event, toolName: CODEMODE_TOOL_NAME, input: { code: event.input.code } }
+			: event;
+		for (const [type, handlers] of mcp.handlers as Map<string, Function[]>) {
+			handlers.forEach((handler, index) => {
+				handlers[index] = (event: Patchable, ctx: unknown) => inMcp.run(true, () => handler(type === "tool_call" ? asCodemodeCall(event) : event, ctx));
+			});
+		}
+		for (const command of (mcp.commands as Map<string, Patchable>).values()) {
+			const handler = command.handler;
+			command.handler = (args: unknown, ctx: unknown) => inMcp.run(true, () => handler(args, ctx));
+		}
+	}
+	// `bindCore` sets these each time, so wrap the current ones.
+	const runtime = runner.runtime as Patchable;
+	const { getActiveTools, getAllTools, setActiveTools } = runtime;
+	runtime.getActiveTools = () => {
+		const active: string[] = getActiveTools();
+		return inMcp.getStore() && active.includes(PROGRAM_TOOL_NAME) && !active.includes(CODEMODE_TOOL_NAME) ? [...active, CODEMODE_TOOL_NAME] : active;
+	};
+	runtime.getAllTools = () => {
+		const tools: Patchable[] = getAllTools();
+		const program = inMcp.getStore() && tools.find((tool) => tool.name === PROGRAM_TOOL_NAME);
+		return program ? [...tools, { ...program, name: CODEMODE_TOOL_NAME, parameters: codemodeSchema }] : tools;
+	};
+	runtime.setActiveTools = (names: string[]) => {
+		if (inMcp.getStore() && names.includes(CODEMODE_TOOL_NAME) && !getActiveTools().includes(CODEMODE_TOOL_NAME)) {
+			names = [...new Set(names.map((name) => name === CODEMODE_TOOL_NAME ? PROGRAM_TOOL_NAME : name))];
+		}
+		return setActiveTools(names);
+	};
+}

package/src/programs/loadout.ts

@@ -0,0 +1,99 @@
+import { highlightCode, type ExtensionAPI, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { CODEMODE_TOOL_NAME, type PiCodemode } from "./codemode.ts";
+import { PROGRAM_TOOL_NAME } from "./execute.ts";
+import { formatToolCall, moreLines, renderTextResult, startDuration, type DurationState } from "../render-call.ts";
+
+/** The first line of the `codemode` description, which the `program` intro replaces. */
+const CODEMODE_FIRST_LINE = "Run JavaScript code to orchestrate/compose tool calls\n";
+const MODEL_API_START = "\n\nModel API:";
+const TOOL_LIST_START = "\n\nNested tools:";
+
+type Loadout = Parameters<NonNullable<ToolDefinition["prepareLoadout"]>>[0];
+type Changes = ReturnType<NonNullable<ToolDefinition["prepareLoadout"]>>;
+type Renderers = Pick<ToolDefinition, "renderCall" | "renderResult">;
+
+const CODE_PREVIEW_LINES = 10;
+
+export const PROGRAM_ONLY_FLAG = "program-only";
+// Owned Agents run in their owner's process without its CLI flags, so the flag holds for the process.
+const PROGRAM_ONLY = Symbol.for("pi-agents:program-only");
+
+/** Applies `--program-only` to this process once a Session sees it, and activates `program`. */
+export function applyProgramOnlyFlag(pi: ExtensionAPI): void {
+	if (pi.getFlag(PROGRAM_ONLY_FLAG) === true) (globalThis as Record<symbol, unknown>)[PROGRAM_ONLY] = true;
+	const active = pi.getActiveTools();
+	if (programOnly(pi) && !active.includes(PROGRAM_TOOL_NAME)) pi.setActiveTools([...active, PROGRAM_TOOL_NAME]);
+}
+
+function programOnly(pi: ExtensionAPI): boolean {
+	return pi.getFlag(PROGRAM_ONLY_FLAG) === true || (globalThis as Record<symbol, unknown>)[PROGRAM_ONLY] === true;
+}
+
+function codemodeSettings(pi: ExtensionAPI): { mode: "on" | "only"; inlineBudget?: number } {
+	const settings = pi.getSettings().codemode;
+	const budget = settings?.inlineBudget;
+	return {
+		mode: programOnly(pi) || settings?.mode === "only" ? "only" : "on",
+		inlineBudget: typeof budget === "number" && Number.isFinite(budget) && budget >= 0 ? budget : undefined,
+	};
+}
+
+/**
+ * The `program` description: the intro, then the `codemode` script API with the Agent API before
+ * its Model API, or before its tool list when it has no Model API.
+ */
+function describeProgram(intro: string, agentApi: string, codemodeDescription: string): string {
+	const description = codemodeDescription.startsWith(CODEMODE_FIRST_LINE) ? codemodeDescription.slice(CODEMODE_FIRST_LINE.length) : codemodeDescription;
+	const modelApi = description.indexOf(MODEL_API_START);
+	const at = modelApi >= 0 ? modelApi : description.indexOf(TOOL_LIST_START);
+	const [before, after] = at < 0 ? [description, ""] : [description.slice(0, at), description.slice(at)];
+	return `${intro}\n\n${before}\n\n${agentApi}${after}`;
+}
+
+/**
+ * Presents the loadout with Pi's `codemode` `prepareLoadout`, following `codemode.mode`, and
+ * moves its `codemode` description to `program`.
+ */
+export function programLoadout(pi: ExtensionAPI, piCodemode: PiCodemode, intro: string, agentApi: string): (loadout: Loadout) => Changes {
+	const { prepareLoadout } = piCodemode.createCodemodeToolDefinition({
+		models: true,
+		getMode: () => codemodeSettings(pi).mode,
+		getInlineBudget: () => codemodeSettings(pi).inlineBudget,
+	});
+	return (loadout) => {
+		const changes = prepareLoadout!(loadout) ?? {};
+		const { [CODEMODE_TOOL_NAME]: codemodeDescription, ...descriptions }: Record<string, string> = { ...changes.descriptions };
+		if (codemodeDescription !== undefined) descriptions[PROGRAM_TOOL_NAME] = describeProgram(intro, agentApi, codemodeDescription);
+		return { descriptions, hiddenDeclarations: changes.hiddenDeclarations };
+	};
+}
+
+/** The program description before the loadout is prepared. */
+export function programDescription(piCodemode: PiCodemode, intro: string, agentApi: string): string {
+	return describeProgram(intro, agentApi, piCodemode.createCodemodeDescription([], { models: true }));
+}
+
+/** Calls render in function-call form, with the `run` script below it. Results render like `codemode`. */
+export function programRenderers(piCodemode: PiCodemode): Renderers {
+	return {
+		renderCall(args, theme, context) {
+			const { code, ...rest } = (args ?? {}) as Record<string, unknown>;
+			startDuration(context.state as DurationState, rest.action === "wait", context.executionStarted);
+			let text = formatToolCall(PROGRAM_TOOL_NAME, rest, theme);
+			if (typeof code === "string" && code) {
+				const lines = highlightCode(code.replace(/\r/g, "").replace(/\t/g, "   ").trimEnd(), "javascript");
+				const shown = context.expanded ? lines : lines.slice(0, CODE_PREVIEW_LINES);
+				text += `\n${shown.join("\n")}`;
+				if (shown.length < lines.length) text += `\n${moreLines(lines.length - shown.length, theme)}`;
+			}
+			const component = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			component.setText(text);
+			return component;
+		},
+		// `wait` shows how long it has waited; the other results render like `codemode`.
+		renderResult: (result, options, theme, context) => (context.args as { action?: string }).action === "wait"
+			? renderTextResult(result, options, theme, context)
+			: piCodemode.renderResult(result, options, theme, context) as Text,
+	};
+}

package/src/programs/programs.ts

@@ -0,0 +1,284 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { deferred, settlesBy, waitForChange, type Deferred } from "../agents/agents.ts";
+import { shortId, trackTreeWork } from "../agents/registry.ts";
+import { boundBlocks, boundText } from "../output.ts";
+import type { ProgramFiles, ProgramOutcome, ProgramRunResult } from "./execute.ts";
+
+const PROGRAM_ENTRY = "pi-agents-program";
+const CLEANUP_TIMEOUT_MS = 15_000;
+/** Ends the result of a Program some of whose work did not stop. */
+export const CLEANUP_ERROR = "Cleanup error: some of the Program's work did not stop within the timeout and may still be running.";
+
+type Item = ProgramRunResult["result"]["content"][number];
+
+export type ProgramState = "running" | ProgramOutcome;
+
+export interface ProgramRecord {
+	id: string;
+	state: ProgramState;
+	startedAt: number;
+	content?: Item[];
+	isError?: boolean;
+	/** Files the Program's tool calls used, for compaction. */
+	files?: ProgramFiles;
+	/** Whether `wait` has returned the result. */
+	returned: boolean;
+	notified: boolean;
+}
+
+interface Running {
+	record: ProgramRecord;
+	controller?: AbortController;
+	done?: Promise<void>;
+	/** Stops counting the Program as the tree's work. */
+	release?: () => void;
+	/** Whether some of its work did not stop. */
+	abandoned?: boolean;
+	waiters: number;
+}
+
+export interface ProgramWaitOutcome {
+	results: ProgramRecord[];
+	running: ProgramRecord[];
+}
+
+function ended(record: ProgramRecord): boolean {
+	return record.state !== "running";
+}
+
+/** The text of a result: the "Script completed" header, then the output items on their own lines. */
+function textOf(content: Item[] | undefined): string {
+	const [header = "", ...rest] = (content ?? []).flatMap((item) => item.type === "text" ? [item.text] : []);
+	return header.endsWith("\n") ? header + rest.join("\n") : [header, ...rest].join("\n");
+}
+
+/** A caller's background Programs: they run on after `run` returns and stop when the caller goes offline. */
+export class Programs {
+	private programs = new Map<string, Running>();
+	private change: Deferred = deferred();
+	private closing = false;
+
+	constructor(
+		private rootId: string,
+		private hooks: {
+			appendEntry(customType: string, data: unknown): void;
+			notify(text: string): void;
+			/** Called when a Program starts, ends, or has its result returned. */
+			changed?(): void;
+		},
+	) {}
+
+	restore(ctx: ExtensionContext): void {
+		for (const entry of ctx.sessionManager.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== PROGRAM_ENTRY) continue;
+			const record = entry.data as ProgramRecord;
+			this.programs.set(record.id, { record, waiters: 0 });
+		}
+		for (const program of this.programs.values()) {
+			const { record } = program;
+			if (ended(record)) continue;
+			record.state = "stopped";
+			record.content = [{ type: "text", text: "Script failed\nOutput:\nScript error:\nScript aborted: the caller went offline" }];
+			record.isError = true;
+			record.notified = true;
+			this.persist(record);
+		}
+	}
+
+	/** Starts a background Program, which `run` executes with its ID, and returns its record. */
+	start(run: (id: string, signal: AbortSignal, abort: () => void) => Promise<ProgramRunResult>): ProgramRecord {
+		const record: ProgramRecord = { id: randomUUID(), state: "running", startedAt: Date.now(), returned: false, notified: false };
+		const controller = new AbortController();
+		const program: Running = { record, controller, waiters: 0 };
+		this.programs.set(record.id, program);
+		// The tree stays busy until the Program ends and its notification is delivered.
+		const release = program.release = trackTreeWork(this.rootId);
+		this.persist(record);
+		this.hooks.changed?.();
+		program.done = run(record.id, controller.signal, () => controller.abort(new Error("Program stopped"))).then(
+			({ outcome, result, files, abandoned }) => {
+				if (abandoned) program.abandoned = true;
+				this.end(program, outcome, result.content, result.isError === true, files);
+			},
+			(error: unknown) => this.end(program, "failed", [{ type: "text", text: `Script failed\nOutput:\nScript error:\n${error instanceof Error ? error.message : String(error)}` }], true),
+		).finally(release);
+		return record;
+	}
+
+	/** Resolves an ID or a unique ID prefix. */
+	target(id: string): Running {
+		const exact = this.programs.get(id);
+		if (exact) return exact;
+		const matches = [...this.programs.values()].filter(({ record }) => record.id.startsWith(id));
+		if (matches.length === 0) throw new Error(`No Program matches "${id}". Use list to find Programs.`);
+		if (matches.length > 1) {
+			throw new Error(`"${id}" matches several Programs: ${matches.map(({ record }) => this.label(record)).join(", ")}. Retry with a longer ID prefix.`);
+		}
+		return matches[0]!;
+	}
+
+	ids(): string[] {
+		return [...this.programs.keys()];
+	}
+
+	/** A Program's short ID among this caller's Programs. */
+	label(record: ProgramRecord): string {
+		return shortId(record.id, this.ids());
+	}
+
+	list(): ProgramRecord[] {
+		return [...this.programs.values()].map((program) => program.record).sort((a, b) => b.startedAt - a.startedAt);
+	}
+
+	/**
+	 * Returns whether the Program was running; it has ended when this resolves. A Program that has
+	 * not stopped within the timeout is abandoned and ends as stopped; this throws when some of its
+	 * work did not stop.
+	 */
+	async stop(program: Running, reason = "Program stopped"): Promise<boolean> {
+		if (ended(program.record)) return false;
+		program.controller?.abort(new Error(reason));
+		if (!await settlesBy(program.done!, Date.now() + CLEANUP_TIMEOUT_MS)) {
+			program.abandoned = true;
+			this.end(program, "stopped", [{ type: "text", text: "Script failed\nOutput:\n" }, { type: "text", text: CLEANUP_ERROR }], true);
+			program.release?.();
+		}
+		if (program.abandoned) throw new Error(`Program ${this.label(program.record)} did not stop within the timeout and may still be running.`);
+		return true;
+	}
+
+	/** The given Programs, or running Programs and ended ones whose result has not been returned. */
+	select(ids: string[] | undefined): Running[] {
+		return [...new Set(ids?.map((id) => this.target(id)) ?? [...this.programs.values()].filter(({ record }) => !ended(record) || !record.returned))];
+	}
+
+	running(programs: Running[]): boolean {
+		return programs.some(({ record }) => !ended(record));
+	}
+
+	async wait(unique: Running[], timeoutSeconds: number, signal?: AbortSignal): Promise<ProgramWaitOutcome> {
+		for (const program of unique) program.waiters += 1;
+		let returned = false;
+		try {
+			const deadline = Date.now() + timeoutSeconds * 1000;
+			while (unique.some(({ record }) => !ended(record))) {
+				const remaining = deadline - Date.now();
+				if (remaining <= 0) break;
+				signal?.throwIfAborted();
+				await waitForChange(this.change.promise, remaining, signal);
+			}
+			signal?.throwIfAborted();
+			returned = true;
+			return {
+				results: unique.filter(({ record }) => ended(record)).map(({ record }) => record),
+				running: unique.filter(({ record }) => !ended(record)).map(({ record }) => record),
+			};
+		} finally {
+			for (const program of unique) {
+				program.waiters -= 1;
+				const { record } = program;
+				if (!ended(record) || record.notified) continue;
+				if (returned) {
+					record.notified = true;
+					this.persist(record);
+				} else if (program.waiters === 0) {
+					this.notify(record);
+				}
+			}
+		}
+	}
+
+	markReturned(records: ProgramRecord[]): void {
+		for (const record of records) {
+			if (record.returned) continue;
+			record.returned = true;
+			this.persist(record);
+		}
+		this.hooks.changed?.();
+	}
+
+	async shutdown(): Promise<void> {
+		this.closing = true;
+		const stopped = await Promise.allSettled([...this.programs.values()].map((program) => this.stop(program, "the caller went offline")));
+		const errors = stopped.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+		if (errors.length > 0) throw new Error(errors.map((error) => error instanceof Error ? error.message : String(error)).join("\n"));
+	}
+
+	private end(program: Running, outcome: ProgramOutcome, content: Item[], isError: boolean, files?: ProgramFiles): void {
+		const { record } = program;
+		// An abandoned Program may end later.
+		if (ended(record)) return;
+		record.state = outcome;
+		record.content = content;
+		record.isError = isError;
+		if (files && (files.read.length > 0 || files.written.length > 0 || files.edited.length > 0)) record.files = files;
+		program.controller = undefined;
+		this.persist(record);
+		if (program.waiters === 0) this.notify(record);
+		const previous = this.change;
+		this.change = deferred();
+		previous.resolve();
+		this.hooks.changed?.();
+	}
+
+	private notify(record: ProgramRecord): void {
+		if (this.closing || record.notified) return;
+		record.notified = true;
+		this.persist(record);
+		this.hooks.notify(`Program ${this.label(record)} ${record.state}.`);
+	}
+
+	private persist(record: ProgramRecord): void {
+		this.hooks.appendEntry(PROGRAM_ENTRY, record);
+	}
+}
+
+/**
+ * Adds the files of the background Programs that ended in the entries compaction summarizes: after
+ * the previous compaction's kept entries start and before `firstKeptEntryId`. Pi finds file
+ * operations in the nested calls of tool results, which do not hold calls made after `run` returns.
+ */
+export function addProgramFiles(
+	entries: Array<{ id: string; type: string; customType?: string; data?: unknown; firstKeptEntryId?: string }>,
+	firstKeptEntryId: string,
+	fileOps: { read: Set<string>; written: Set<string>; edited: Set<string> },
+): void {
+	const end = entries.findIndex((entry) => entry.id === firstKeptEntryId);
+	const previous = entries.findLast((entry) => entry.type === "compaction");
+	const start = previous ? Math.max(0, entries.findIndex((entry) => entry.id === previous.firstKeptEntryId)) : 0;
+	for (const entry of entries.slice(start, end < 0 ? undefined : end)) {
+		if (entry.type !== "custom" || entry.customType !== PROGRAM_ENTRY) continue;
+		const files = (entry.data as ProgramRecord).files;
+		for (const path of files?.read ?? []) fileOps.read.add(path);
+		for (const path of files?.written ?? []) fileOps.written.add(path);
+		for (const path of files?.edited ?? []) fileOps.edited.add(path);
+	}
+}
+
+function resultBlock(record: ProgramRecord, ids: string[]): string {
+	return `<program-result id="${shortId(record.id, ids)}" status="${record.state}">\n${textOf(record.content)}\n</program-result>`;
+}
+
+/** Renders wait results; returns the content and the results the caller has now received. */
+export function renderProgramWait({ results, running }: ProgramWaitOutcome, ids: string[]): { content: Item[]; returned: ProgramRecord[]; isError?: boolean } {
+	const runningLine = running.length > 0 ? `Still running: ${running.map((record) => shortId(record.id, ids)).join(", ")}` : "";
+	if (results.length === 0) return { content: [{ type: "text", text: runningLine || "No results." }], returned: [] };
+	const images = (shown: ProgramRecord[]) => shown.flatMap((record) => (record.content ?? []).filter((item) => item.type === "image"));
+	const only = results[0]!;
+	if (results.length === 1 && running.length === 0 && only.state === "completed") {
+		const bounded = boundText(textOf(only.content), "pi-agents-program-wait");
+		return { content: [{ type: "text", text: bounded.text }, ...images(results)], returned: results };
+	}
+	const bounded = boundBlocks(results.map((record) => resultBlock(record, ids)), "program-result", "pi-agents-program-wait");
+	let text = bounded.text;
+	const returned = results.slice(0, bounded.shown);
+	const omitted = results.slice(bounded.shown);
+	if (omitted.length > 0) text += `\n\n[Results omitted: ${omitted.map((record) => shortId(record.id, ids)).join(", ")}. Use wait with fewer targets.]`;
+	if (runningLine) text += `\n\n${runningLine}`;
+	return { content: [{ type: "text", text }, ...images(returned)], returned };
+}
+
+export function programListLine(record: ProgramRecord, ids: string[]): string {
+	return `${shortId(record.id, ids)}  ${record.state}`;
+}