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

package/src/programs/sandbox.ts

@@ -0,0 +1,90 @@
+import { randomBytes } from "node:crypto";
+import type { CodemodeTool } from "@earendil-works/pi-codemode";
+
+export interface AgentOptions {
+	name?: string;
+	cwd?: string;
+	context?: "fresh" | "fork";
+	model?: string;
+	thinkingLevel?: string;
+}
+
+export interface SendOptions {
+	deliverAs?: "followUp" | "steer" | "write";
+	schema?: unknown;
+}
+
+/** What `agent()` and its handles do on the host. */
+export interface ProgramAgentHost {
+	create(id: string, name: string, options: AgentOptions): Promise<void>;
+	send(id: string, message: string, options: SendOptions): Promise<unknown>;
+	abort(id: string): Promise<void>;
+}
+
+// One line, so line numbers in errors match the script as written. The ID is
+// a UUIDv4 made in the script because `agent()` returns its handle before the
+// host has created the Agent. QuickJS seeds Math.random from the clock, so
+// the random bits come from the host; a counter, spread by an odd multiplier,
+// gives each Agent of the Program a distinct first group.
+function agentPrefix(): string {
+	const bytes = randomBytes(16);
+	bytes[6] = 0x40 | (bytes[6]! & 0x0f);
+	bytes[8] = 0x80 | (bytes[8]! & 0x3f);
+	const hex = bytes.toString("hex");
+	const head = bytes.readUInt32BE(0);
+	const rest = `${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+	return [
+		"const agent = ((create, send, abort) => {",
+		"const names = new Set(); let count = 0; let serial = 0;",
+		`const newId = () => \`\${((${head} + ++serial * 2654435761) % 2 ** 32).toString(16).padStart(8, '0')}-${rest}\`;`,
+		"return (options = {}) => {",
+		"let name = options.name;",
+		"if (name === undefined) { do name = `agent-${++count}`; while (names.has(name)); }",
+		"names.add(name);",
+		"const id = newId();",
+		"create(id, name, options).catch(() => {});",
+		"return Object.freeze({ id, name, send: (message, sendOptions) => send(id, message, sendOptions), abort: () => abort(id) });",
+		"};",
+		"})(__agent.create, __agent.send, __agent.abort);",
+	].join(" ");
+}
+
+export function withAgentPrefix(code: string): string {
+	return `${agentPrefix()}${code}`;
+}
+
+/** Globals behind `agent()`. A handle's calls wait for its Agent to be created. */
+export function agentGlobals(host: ProgramAgentHost): CodemodeTool[] {
+	const created = new Map<string, Promise<void>>();
+	const ready = (id: string) => created.get(id) ?? Promise.reject(new Error(`Unknown Agent ${id}`));
+	return [
+		{
+			name: "__agent.create",
+			spread: true,
+			execute: (args) => {
+				const [id, name, options] = args as [string, string, AgentOptions];
+				const creation = host.create(id, name, options ?? {});
+				created.set(id, creation);
+				return creation;
+			},
+		},
+		{
+			name: "__agent.send",
+			spread: true,
+			execute: async (args) => {
+				const [id, message, options] = args as [string, string, SendOptions | undefined];
+				await ready(id);
+				return host.send(id, message, options ?? {});
+			},
+		},
+		{
+			name: "__agent.abort",
+			spread: true,
+			execute: async (args) => {
+				const [id] = args as [string];
+				await ready(id);
+				await host.abort(id);
+			},
+		},
+	];
+}

package/src/programs/scope.ts

@@ -0,0 +1,94 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Agents, settlesBy, SUBMIT_RESULT_TOOL_NAME, THINKING_LEVELS, type Limits } from "../agents/agents.ts";
+import { label, messageText, nodes, treeChanged, visibleIds, type AgentNode } from "../agents/registry.ts";
+import type { AgentOptions, ProgramAgentHost, SendOptions } from "./sandbox.ts";
+
+const CLEANUP_TIMEOUT_MS = 15_000;
+const DELIVERIES = ["followUp", "steer", "write"];
+
+export interface ProgramScope {
+	host: ProgramAgentHost;
+	/** Aborts unfinished inputs and takes the Agents offline; work not stopped within the timeout is abandoned, and this throws. */
+	close(): Promise<void>;
+}
+
+/**
+ * The Agents a Program creates with `agent()`. They count toward the caller's tree, each sees
+ * only itself and the Agents under it, and they are never persisted: when the Program ends they
+ * go offline for good.
+ */
+export function programScope(
+	id: string,
+	caller: AgentNode,
+	pi: ExtensionAPI,
+	ctx: ExtensionContext,
+	options: { agentDir: string; limits: Limits; extensions: string[]; background: boolean },
+): ProgramScope {
+	const self = { id, rootId: caller.rootId, scopeId: id, ownerId: caller.id, name: () => "program" };
+	const agents = new Agents(pi, self, options.agentDir, options.limits, options.extensions, true);
+	agents.setContext(ctx);
+	nodes.set(id, {
+		...self,
+		program: true,
+		background: options.background,
+		createdAt: new Date().toISOString(),
+		agents,
+		cwd: () => ctx.cwd,
+		busy: () => true,
+		sessionFile: () => undefined,
+		receive: () => { throw new Error("A Program does not receive messages."); },
+	});
+	treeChanged();
+	const from = { id, name: self.name() };
+	const host: ProgramAgentHost = {
+		create: async (agentId, name, agentOptions: AgentOptions) => {
+			const { cwd, context, model, thinkingLevel } = agentOptions;
+			if (typeof name !== "string" || !name.trim()) throw new Error("agent() name must be a non-empty string");
+			if (cwd !== undefined && typeof cwd !== "string") throw new Error("agent() cwd must be a string");
+			if (context !== undefined && context !== "fresh" && context !== "fork") throw new Error('agent() context must be "fresh" or "fork"');
+			if (model !== undefined && typeof model !== "string") throw new Error("agent() model must be provider/modelId");
+			if (thinkingLevel !== undefined && !(THINKING_LEVELS as readonly unknown[]).includes(thinkingLevel)) {
+				throw new Error(`agent() thinkingLevel must be one of ${THINKING_LEVELS.join(", ")}`);
+			}
+			agents.create({ name, cwd, context, model, thinkingLevel: thinkingLevel as (typeof THINKING_LEVELS)[number] | undefined }, agentId);
+		},
+		send: async (agentId, message, sendOptions: SendOptions) => {
+			const delivery = sendOptions.deliverAs ?? "followUp";
+			const { schema } = sendOptions;
+			if (typeof message !== "string" || !message.trim()) throw new Error("send() requires a non-empty message");
+			if (!DELIVERIES.includes(delivery)) throw new Error('send() deliverAs must be "followUp", "steer", or "write"');
+			if (schema !== undefined) {
+				if (delivery !== "followUp") throw new Error('send() accepts schema only with deliverAs "followUp"');
+				if (typeof schema !== "boolean" && (typeof schema !== "object" || schema === null || Array.isArray(schema))) {
+					throw new Error("send() schema must be a JSON Schema object or boolean");
+				}
+			}
+			const agent = agents.ownedTarget(agentId).record;
+			const body = schema === undefined ? message : `${message}\n\nWhen done, call \`${SUBMIT_RESULT_TOOL_NAME}\` with a \`value\` that matches this JSON Schema:\n${JSON.stringify(schema)}`;
+			const text = messageText(from, true, delivery, body, visibleIds(agentId, false));
+			if (delivery === "write") {
+				agents.accept(agentId, text, "write", { fromOwner: true, notification: false });
+				return undefined;
+			}
+			const record = await agents.request(agentId, text, delivery, schema);
+			if (record.state === "completed") return schema === undefined ? record.result : record.value;
+			throw new Error(record.state === "failed" ? `Agent ${label(agent, agents.ids())} failed: ${record.result}` : `Agent ${label(agent, agents.ids())} was aborted.`);
+		},
+		abort: async (agentId) => {
+			await agents.abort(agents.ownedTarget(agentId));
+		},
+	};
+	return {
+		host,
+		close: async () => {
+			try {
+				if (!await settlesBy(agents.shutdown(), Date.now() + CLEANUP_TIMEOUT_MS)) {
+					throw new Error(`The Program's Agents did not stop within the timeout and may still be running.`);
+				}
+			} finally {
+				nodes.delete(id);
+				treeChanged();
+			}
+		},
+	};
+}

package/src/programs/tool.ts

@@ -0,0 +1,198 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { SUBMIT_RESULT_TOOL_NAME, type Limits } from "../agents/agents.ts";
+import { nodes, type AgentNode } from "../agents/registry.ts";
+import { rejectFields } from "../params.ts";
+import { programScope } from "./scope.ts";
+import type { PiCodemode } from "./codemode.ts";
+import { executeProgram, PROGRAM_TOOL_NAME, type ProgramRunOptions } from "./execute.ts";
+import { programDescription, programLoadout, programRenderers } from "./loadout.ts";
+import { randomUUID } from "node:crypto";
+import { CLEANUP_ERROR, programListLine, Programs, renderProgramWait } from "./programs.ts";
+import { agentGlobals, withAgentPrefix } from "./sandbox.ts";
+
+const PROGRAM_DESCRIPTION = `Run JavaScript that composes tool calls and Agents; only its output and return value reach the caller. \`run\` runs a Program in the foreground, or in the background with \`background\`; \`wait\` waits for background Programs and returns their results; \`list\` lists background Programs; \`stop\` stops a running Program. When a background Program ends while its caller is not waiting for it, the caller receives a notification; \`wait\` returns the result.
+
+Program code is the body of an async function. It calls the caller's tools through \`tools.*\`, which excludes \`program\`, and creates Agents through \`agent()\`. These Agents belong to the Program, are isolated from other Agents, and go offline when it ends.
+
+\`program\` replaces the \`codemode\` tool; wherever \`codemode\` is mentioned, use \`program\`.`;
+
+const AGENT_API = `Agent API:
+\`\`\`ts
+type JsonSchema = boolean | Record<string, unknown>;
+interface AgentOptions {
+  /** Default: generated, unique within the Program. */
+  name?: string;
+  /** Default: the caller's cwd. */
+  cwd?: string;
+  /** \`fresh\` starts without the caller's conversation; \`fork\` snapshots it. Default: \`fresh\`. */
+  context?: "fresh" | "fork";
+  /** provider/modelId. Default: the caller's model. */
+  model?: string;
+  /** Default: the caller's level. */
+  thinkingLevel?: string;
+}
+interface SendOptions {
+  /** Default: \`followUp\`. */
+  deliverAs?: "followUp" | "steer" | "write";
+  /** \`followUp\` only. The Agent must submit a value matching it. */
+  schema?: JsonSchema;
+}
+interface AgentHandle {
+  readonly id: string;
+  readonly name: string;
+  /** Resolves with the answer, or with the submitted value when \`schema\` is set; a write resolves with undefined once accepted. Throws if the input fails or is aborted. */
+  send(message: string, options?: SendOptions): Promise<unknown>;
+  /** Aborts the Agent's current turn and queued inputs; the Agent stays usable. */
+  abort(): Promise<void>;
+}
+
+/** Creates an idle Agent that belongs to the Program. */
+declare function agent(options?: AgentOptions): AgentHandle;
+\`\`\``;
+
+/** Registers the `program` tool and `submit_result`, which Agents of Programs use. */
+export function registerProgramTools(
+	pi: ExtensionAPI,
+	{ agentDir, settings, piCodemode, requireNode, programs: getPrograms }: {
+		agentDir: string;
+		settings: Limits & { extensions: string[] };
+		piCodemode: PiCodemode;
+		requireNode: (current: ExtensionContext) => AgentNode;
+		programs: () => Programs | undefined;
+	},
+): void {
+	/** Runs a Program whose Agents go offline when it ends. */
+	const runProgram = async (
+		id: string,
+		caller: AgentNode,
+		toolCallId: string,
+		code: string,
+		signal: AbortSignal,
+		current: Parameters<typeof executeProgram>[3],
+		options: Pick<ProgramRunOptions, "timeout" | "onUpdate" | "background" | "abort">,
+	) => {
+		const scope = programScope(id, caller, pi, current, { agentDir, limits: settings, extensions: settings.extensions, background: options.background === true });
+		let run: Awaited<ReturnType<typeof executeProgram>> | undefined;
+		try {
+			run = await executeProgram(toolCallId, code, signal, current, {
+				...options,
+				globals: agentGlobals(scope.host),
+				prepare: withAgentPrefix,
+				appendEntry: (customType, data) => pi.appendEntry(customType, data),
+				getToolNamespace: (name) => pi.getAllTools().find((tool) => tool.name === name)?.namespace,
+			});
+		} finally {
+			// A cleanup failure ends the result, which keeps the Program's output and calls.
+			await scope.close().catch(() => {
+				if (!run) return;
+				run.result.content.push({ type: "text", text: CLEANUP_ERROR });
+				run.result.isError = true;
+				run.abandoned = true;
+			});
+		}
+		return run;
+	};
+
+	pi.registerTool({
+		name: SUBMIT_RESULT_TOOL_NAME,
+		label: "Submit Result",
+		description: "Submit the result that the current input asks for. `value` must match the JSON Schema given in the input; an invalid value is rejected with the reasons.",
+		promptSnippet: "Submit the result that the current input asks for",
+		exposure: "model-only",
+		defaultActive: false,
+		parameters: Type.Object({
+			value: Type.Unknown({ description: "The result, matching the JSON Schema given in the input." }),
+		}),
+		async execute(_toolCallId, params, _signal, _onUpdate, current) {
+			const self = requireNode(current);
+			const owner = self.ownerId === undefined ? undefined : nodes.get(self.ownerId);
+			if (!owner) throw new Error("No current input asks for a result.");
+			owner.agents.submit(self.id, params.value);
+			return { content: [{ type: "text", text: "Result submitted." }], details: {} };
+		},
+	});
+
+	pi.registerTool({
+		name: PROGRAM_TOOL_NAME,
+		label: "Program",
+		// Programs must not start Programs.
+		exposure: "model-only",
+		defaultActive: false,
+		prepareLoadout: programLoadout(pi, piCodemode, PROGRAM_DESCRIPTION, AGENT_API),
+		...programRenderers(piCodemode),
+		description: programDescription(piCodemode, PROGRAM_DESCRIPTION, AGENT_API),
+		promptSnippet: "Run JavaScript that composes tool calls and Agents",
+		promptGuidelines: [
+			"Use `program(action='run', code=...)` to call tools or Agents several times without a model turn between the calls, for example to read many files, filter large tool output, fan out Agents, or loop until a condition holds.",
+			"Use `Promise.allSettled` for independent calls. Return only what the caller needs; use `text()` for progress worth reading.",
+			"Use `background=true` for long Programs, and `program(action='wait', ...)` when the next step depends on their results.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(["run", "wait", "list", "stop"] as const, { description: "Operation and applicable parameters: `run(code, background?, timeout?)`, `wait(target?, timeout?)`, `list(limit?, offset?)`, or `stop(target)`." }),
+			code: Type.Optional(Type.String({ description: "JavaScript async-function body for `run`." })),
+			background: Type.Optional(Type.Boolean({ description: "Whether `run` returns the Program ID at once (default: false)." })),
+			timeout: Type.Optional(Type.Number({ exclusiveMinimum: 0, description: "Maximum seconds. For `run` (default: none), expiry stops the Program. For `wait` (default: 30, min: 10, max: 3600), expiry does not stop Programs." })),
+			target: Type.Optional(Type.Union([Type.String(), Type.Array(Type.String())], { description: "Program ID or unique ID prefix for `wait` or `stop`. `wait` also accepts an array. When omitted for `wait`, selects running Programs and ended Programs whose result has not been returned." })),
+			limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 200, description: "Maximum Programs returned by `list` (default: 20, max: 200)." })),
+			offset: Type.Optional(Type.Integer({ minimum: 0, description: "Number of Programs to skip for `list` (default: 0)." })),
+		}),
+		async execute(toolCallId, params, signal, onUpdate, current) {
+			const self = requireNode(current);
+			const programs = getPrograms();
+			if (!programs) throw new Error("pi-agents is not initialized");
+			const targets = params.target === undefined ? undefined : Array.isArray(params.target) ? params.target : [params.target];
+			switch (params.action) {
+				case "run": {
+					rejectFields(params, "run", ["target", "limit", "offset"]);
+					if (!params.code?.trim()) throw new Error("run requires code");
+					const code = params.code;
+					if (params.background) {
+						const record = programs.start((id, programSignal, abort) => runProgram(id, self, toolCallId, code, programSignal, current, { timeout: params.timeout, background: true, abort }));
+						return { content: [{ type: "text", text: `Program ${programs.label(record)} started.` }], details: { id: record.id } };
+					}
+					const { result } = await self.agents.whileSuspended(() => runProgram(randomUUID(), self, toolCallId, code, signal ?? new AbortController().signal, current, {
+						timeout: params.timeout,
+						onUpdate,
+					}), signal);
+					return result;
+				}
+				case "wait": {
+					rejectFields(params, "wait", ["code", "background", "limit", "offset"]);
+					const timeout = params.timeout ?? 30;
+					if (timeout < 10 || timeout > 3600) throw new Error("wait timeout must be between 10 and 3600 seconds");
+					const selected = programs.select(targets);
+					onUpdate?.({ content: [], details: undefined });
+					const waitFor = () => programs!.wait(selected, timeout, signal);
+					const outcome = programs.running(selected) ? await self.agents.whileSuspended(waitFor, signal, true) : await waitFor();
+					const rendered = renderProgramWait(outcome, programs.ids());
+					programs.markReturned(rendered.returned);
+					return { content: rendered.content, details: { running: outcome.running.map((record) => record.id) } };
+				}
+				case "list": {
+					rejectFields(params, "list", ["code", "background", "timeout", "target"]);
+					const offset = params.offset ?? 0;
+					const limit = params.limit ?? 20;
+					const records = programs.list();
+					if (records.length === 0) return { content: [{ type: "text", text: "No Programs." }], details: { total: 0 } };
+					const page = records.slice(offset, offset + limit);
+					const lines = page.map((record) => programListLine(record, programs!.ids()));
+					const remaining = records.length - offset - page.length;
+					if (remaining > 0) lines.push(`[${remaining} more results. Use offset=${offset + page.length} to continue.]`);
+					return { content: [{ type: "text", text: lines.join("\n") }], details: { total: records.length } };
+				}
+				case "stop": {
+					rejectFields(params, "stop", ["code", "background", "timeout", "limit", "offset"]);
+					if (targets?.length !== 1) throw new Error("stop requires one target");
+					const program = programs.target(targets[0]!);
+					const stopped = await programs.stop(program);
+					return {
+						content: [{ type: "text", text: `Program ${programs.label(program.record)} ${stopped ? "stopped" : "has already ended"}.` }],
+						details: { id: program.record.id, stopped },
+					};
+				}
+			}
+		},
+	});
+}

package/src/render-call.ts

@@ -0,0 +1,90 @@
+import { keyHint } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+
+type ToolCallTheme = {
+	bold(text: string): string;
+	fg(color: "toolTitle" | "text", text: string): string;
+};
+
+/** A call in function-call form, like `agent(action="wait", target="w1")`, as in pi-control. */
+export function formatToolCall(name: string, args: unknown, theme: ToolCallTheme): string {
+	const entries = Object.entries((args ?? {}) as Record<string, unknown>).filter(([, value]) => value !== undefined);
+	const fields = entries.map(([key, value]) => `${key}=${JSON.stringify(value) ?? String(value)}`).join(", ");
+	return `${theme.fg("toolTitle", theme.bold(name))}${theme.fg("text", `(${fields})`)}`;
+}
+
+export function renderToolCall(name: string, args: unknown, theme: ToolCallTheme, lastComponent?: unknown): Text {
+	const component = lastComponent instanceof Text ? lastComponent : new Text("", 0, 0);
+	component.setText(formatToolCall(name, args, theme));
+	return component;
+}
+
+const RESULT_PREVIEW_LINES = 10;
+
+/** The notice below a collapsed preview: the number of hidden lines and the key that expands it. */
+export function moreLines(hidden: number, theme: { fg(color: "muted", text: string): string }): string {
+	return `${theme.fg("muted", `... (${hidden} more lines,`)} ${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`;
+}
+
+/** Per-row state of a timed call: when it started executing and when its result arrived. */
+export interface DurationState {
+	startedAt?: number;
+	endedAt?: number;
+	interval?: ReturnType<typeof setInterval>;
+}
+
+export function startDuration(state: DurationState, enabled: boolean, executionStarted: boolean): void {
+	if (enabled && executionStarted && state.startedAt === undefined) state.startedAt = Date.now();
+}
+
+function formatDuration(ms: number): string {
+	const seconds = ms / 1000;
+	if (seconds < 60) return `${seconds.toFixed(1)}s`;
+	const totalSeconds = Math.floor(seconds);
+	const minutes = Math.floor(totalSeconds / 60);
+	if (minutes < 60) return `${minutes}m ${totalSeconds % 60}s`;
+	return `${Math.floor(minutes / 60)}h ${minutes % 60}m ${totalSeconds % 60}s`;
+}
+
+/** "Elapsed …" while the call runs, refreshed every second, then "Took …" from Pi's recorded `durationMs` when present. */
+function updateDuration(state: DurationState, isPartial: boolean, durationMs: number | undefined, invalidate: () => void): string | undefined {
+	if (state.startedAt === undefined) return undefined;
+	if (isPartial && !state.interval) state.interval = setInterval(invalidate, 1000);
+	if (!isPartial) {
+		state.endedAt ??= Date.now();
+		clearInterval(state.interval);
+		state.interval = undefined;
+	}
+	const ms = !isPartial && durationMs !== undefined ? durationMs : (state.endedAt ?? Date.now()) - state.startedAt;
+	return `${isPartial ? "Elapsed" : "Took"} ${formatDuration(ms)}`;
+}
+
+interface ResultTheme {
+	fg(color: "toolOutput" | "muted", text: string): string;
+}
+
+/**
+ * The text output like Pi's default result, with the duration of a timed call below it.
+ * Like Pi's `bash` result, a blank line precedes the output and the duration.
+ */
+export function renderTextResult(
+	result: { content: Array<{ type: string; text?: string }> },
+	options: { expanded: boolean; isPartial: boolean },
+	theme: ResultTheme,
+	context: { state: unknown; invalidate: () => void; lastComponent?: unknown; durationMs?: number },
+): Text {
+	const output = result.content.flatMap((part) => part.type === "text" && part.text ? [part.text] : []).join("\n").trim();
+	const lines = output ? output.split("\n") : [];
+	const shown = options.expanded ? lines : lines.slice(0, RESULT_PREVIEW_LINES);
+	const sections: string[] = [];
+	if (shown.length > 0) {
+		let text = shown.map((line) => theme.fg("toolOutput", line)).join("\n");
+		if (shown.length < lines.length) text += `\n${moreLines(lines.length - shown.length, theme)}`;
+		sections.push(text);
+	}
+	const duration = updateDuration(context.state as DurationState, options.isPartial, context.durationMs, context.invalidate);
+	if (duration) sections.push(theme.fg("muted", duration));
+	const component = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+	component.setText(sections.map((section) => `\n${section}`).join("\n"));
+	return component;
+}

package/src/roots/discovery.mjs

@@ -0,0 +1,113 @@
+import { createReadStream } from 'node:fs';
+import { readdir, stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { join } from 'node:path';
+
+const cache = new Map();
+
+/** The first line of a message's text, for the workbench row. */
+function firstLine(content) {
+  const text = typeof content === 'string' ? content
+    : Array.isArray(content) ? content.filter(block => block?.type === 'text').map(block => block.text).join('\n') : '';
+  const line = text.trim().split('\n')[0];
+  return line.length > 200 ? `${line.slice(0, 199)}…` : line;
+}
+
+export function isOwnedSession(entries) {
+  return entries.some(entry => entry.type === 'custom' && entry.customType === 'pi-agents-tree'
+    && typeof entry.data?.rootId === 'string');
+}
+
+// Read-only discovery must never open a SessionManager: opening can migrate or
+// repair the very session another runtime is currently writing.
+export async function readRootFile(sessionFile, { signal } = {}) {
+  signal?.throwIfAborted();
+  let metadata;
+  try { metadata = await stat(sessionFile); }
+  catch (error) { if (error.code === 'ENOENT') { cache.delete(sessionFile); return; } throw error; }
+  const stamp = `${metadata.dev}:${metadata.ino}:${metadata.size}:${metadata.mtimeMs}:${metadata.ctimeMs}`;
+  const previous = cache.get(sessionFile);
+  if (previous?.stamp === stamp) return previous.root ? { ...previous.root } : undefined;
+  function remember(root) {
+    cache.set(sessionFile, { stamp, root });
+    return root ? { ...root } : undefined;
+  }
+  const input = createReadStream(sessionFile, { encoding: 'utf8', signal });
+  const lines = createInterface({ input, crlfDelay: Infinity });
+  let header, name, summary, title, reply;
+  try {
+    for await (const line of lines) {
+      signal?.throwIfAborted();
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (!entry || typeof entry !== 'object') continue;
+      if (!header) {
+        if (entry.type !== 'session' || typeof entry.id !== 'string' || !entry.id || typeof entry.cwd !== 'string') return remember();
+        header = entry;
+      }
+      if (isOwnedSession([entry])) return remember();
+      if (entry.type === 'session_info') name = typeof entry.name === 'string' ? entry.name : undefined;
+      if (entry.type === 'compaction' && typeof entry.summary === 'string') summary = entry.summary;
+      if (entry.type === 'message' && entry.message?.role === 'user') title ??= firstLine(entry.message.content);
+      if (entry.type === 'message' && entry.message?.role === 'assistant') reply = firstLine(entry.message.content) || firstLine(entry.message.errorMessage) || reply;
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') { cache.delete(sessionFile); return; }
+    throw error;
+  } finally {
+    lines.close();
+    input.destroy();
+  }
+  if (!header) return remember();
+  return remember({ id: header.id, name, title: title || undefined, reply, cwd: header.cwd, summary, sessionFile, updatedAt: metadata.mtime.toISOString(), state: 'unknown' });
+}
+
+async function sessionFiles(sessionDir, extraFiles, signal) {
+  signal?.throwIfAborted();
+  let directories;
+  try { directories = await readdir(sessionDir, { withFileTypes: true }); }
+  catch (error) { if (error.code === 'ENOENT') directories = []; else throw error; }
+  const files = new Set(extraFiles);
+  for (const directory of directories) {
+    signal?.throwIfAborted();
+    // A configured sessionDir holds roots directly, and child runtimes in subagents/.
+    if (directory.isFile() && directory.name.endsWith('.jsonl')) files.add(join(sessionDir, directory.name));
+    if ((!directory.isDirectory() && !directory.isSymbolicLink()) || directory.name === 'subagents') continue;
+    const path = join(sessionDir, directory.name);
+    let entries;
+    try { entries = await readdir(path, { withFileTypes: true }); }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') continue; throw error; }
+    // Pi's default layout keeps roots one level below sessions/. Child runtimes use nested
+    // directories; parentSession alone cannot distinguish children from forks.
+    for (const entry of entries) {
+      if ((entry.isFile() || entry.isSymbolicLink()) && entry.name.endsWith('.jsonl')) files.add(join(path, entry.name));
+    }
+  }
+  return files;
+}
+
+/**
+ * Root Sessions in `sessionDir` and `extraFiles`; with `ids`, only those. A file Pi named
+ * `<timestamp>_<id>.jsonl` is skipped by its name; others are read for their ID.
+ */
+export async function discoverRoots(sessionDir, { extraFiles = [], ids, skip, signal } = {}) {
+  const roots = [];
+  for (const file of await sessionFiles(sessionDir, extraFiles, signal)) {
+    const named = /_([0-9a-f-]{36})\.jsonl$/.exec(file)?.[1];
+    if (skip?.has(file) || (ids && named && !ids.has(named))) continue;
+    const root = await readRootFile(file, { signal });
+    if (root && (!ids || ids.has(root.id))) roots.push(root);
+  }
+  return roots;
+}
+
+// Pi names Session files `<timestamp>_<id>.jsonl`; read those first and scan every
+// Session only when no such file is the root.
+export async function findRoot(sessionDir, id, { extraFiles = [], signal } = {}) {
+  for (const file of await sessionFiles(sessionDir, extraFiles, signal)) {
+    if (!file.endsWith(`_${id}.jsonl`)) continue;
+    const root = await readRootFile(file, { signal });
+    if (root?.id === id) return root;
+  }
+  return (await discoverRoots(sessionDir, { extraFiles, signal })).find(entry => entry.id === id);
+}