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

package/src/roots/report.ts

@@ -0,0 +1,156 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { onTreeChange, treeMetadata } from "../agents/registry.ts";
+import { ensureDaemon } from "../daemon/client.mjs";
+import { statePaths, sessionDir as resolveSessionDir } from "./paths.mjs";
+import { openStream } from "./transport.mjs";
+
+const RECONNECT_MS = 1000;
+const SEND_DELAY_MS = 50;
+const TEXT_LIMIT = 200;
+
+export interface ReportHooks {
+	/** Whether the tree has no live work. */
+	treeIdle(): boolean;
+	/** The tree's running owned Agents and background Programs. */
+	liveWork(): number;
+	/** The host this Pi runs in, if any. */
+	host?: { socket: string; attached(): boolean; onChange(listener: () => void): void };
+}
+
+function firstLine(text: string, limit = TEXT_LIMIT): string {
+	const line = text.trim().split("\n")[0] ?? "";
+	return line.length > limit ? `${line.slice(0, limit - 1)}…` : line;
+}
+
+function textOf(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content.filter((block) => block?.type === "text").map((block) => block.text).join("\n");
+}
+
+function toolLabel(name: string, args: unknown): string {
+	const detail = args && typeof args === "object" ? Object.values(args).find((value) => typeof value === "string" && value.trim()) : undefined;
+	return detail ? `${name} ${firstLine(detail as string, 80)}` : name;
+}
+
+/**
+ * Reports this root Session's state to the daemon while it is loaded: whether it works, its
+ * running tool, its last reply and finished turn, and whether a terminal shows it. The daemon
+ * forwards interrupts from the workbench.
+ */
+export function createReporter(pi: ExtensionAPI, hooks: ReportHooks): void {
+	const paths = statePaths();
+	const sessionDir = resolveSessionDir();
+	let ctx: ExtensionContext | undefined;
+	let stream: { send(message: object): void; close(): void } | undefined;
+	let generation = 0;
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	let dialogs = 0;
+	let tools = new Map<string, string>();
+	let turn: { at: number; failed: boolean } | undefined;
+	let reply: string | undefined;
+	let title: string | undefined;
+	let unsubscribe: (() => void) | undefined;
+
+	function state() {
+		const current = ctx!;
+		const manager = current.sessionManager;
+		if (title === undefined) {
+			const first = manager.getEntries().find((entry) => entry.type === "message" && entry.message.role === "user");
+			if (first?.type === "message") title = firstLine(textOf((first.message as { content?: unknown }).content));
+		}
+		return {
+			id: manager.getSessionId(),
+			sessionFile: manager.getSessionFile(),
+			cwd: current.cwd,
+			name: pi.getSessionName(),
+			title,
+			host: hooks.host?.socket,
+			attached: hooks.host ? hooks.host.attached() : true,
+			working: !current.isIdle() || current.hasPendingMessages() || !hooks.treeIdle() || dialogs > 0,
+			blocked: dialogs > 0,
+			tool: [...tools.values()].at(-1),
+			reply,
+			agents: hooks.liveWork(),
+			turn,
+		};
+	}
+
+	function changed(): void {
+		if (timer || !ctx) return;
+		timer = setTimeout(() => {
+			timer = undefined;
+			if (ctx && stream) stream.send({ type: "state", state: state() });
+		}, SEND_DELAY_MS);
+		timer.unref();
+	}
+
+	async function connect(current: number): Promise<void> {
+		try {
+			await ensureDaemon(paths, { sessionDir });
+			const opened = await openStream(paths.daemon, { action: "stream", role: "session" }, {
+				onMessage: (message: { type?: string; id?: string }) => {
+					if (message?.type === "interrupt" && ctx && message.id === ctx.sessionManager.getSessionId()) ctx.abort();
+				},
+				onClose: () => {
+					if (stream !== opened) return;
+					stream = undefined;
+					retry(current);
+				},
+			});
+			opened.unref();
+			if (current !== generation) return opened.close();
+			stream = opened;
+			changed();
+		} catch {
+			retry(current);
+		}
+	}
+
+	// A daemon that exits, for example to update, is replaced by the next connection.
+	function retry(current: number): void {
+		if (current === generation) setTimeout(() => { if (current === generation) void connect(current); }, RECONNECT_MS).unref();
+	}
+
+	pi.on("session_start", (_event, current) => {
+		if (!current.sessionManager.getSessionFile() || treeMetadata(current)) return;
+		ctx = current;
+		unsubscribe ??= onTreeChange(() => changed());
+		void connect(++generation);
+	});
+	pi.on("session_shutdown", () => {
+		if (!ctx) return;
+		stream?.send({ type: "end", id: ctx.sessionManager.getSessionId() });
+		stream?.close();
+		stream = undefined;
+		generation++;
+		ctx = undefined;
+		unsubscribe?.();
+		unsubscribe = undefined;
+		dialogs = 0;
+		tools = new Map();
+		turn = reply = title = undefined;
+	});
+	pi.on("session_info_changed", () => changed());
+	pi.on("agent_start", () => changed());
+	pi.on("tool_execution_start", (event) => {
+		if (event.parentToolCallId) return;
+		tools.set(event.toolCallId, toolLabel(event.toolName, event.args));
+		changed();
+	});
+	pi.on("tool_execution_end", (event) => {
+		if (tools.delete(event.toolCallId)) changed();
+	});
+	pi.on("ui_prompt_start", () => { dialogs += 1; changed(); });
+	pi.on("ui_prompt_end", () => { dialogs = Math.max(0, dialogs - 1); changed(); });
+	pi.on("agent_settled", (event) => {
+		if (!ctx) return;
+		const last = ctx.sessionManager.getBranch().findLast((entry) => entry.type === "message" && entry.message.role === "assistant");
+		const message = last?.type === "message" && last.message.role === "assistant" ? last.message : undefined;
+		reply = message ? firstLine(textOf(message.content)) || firstLine(message.errorMessage ?? "") : undefined;
+		turn = { at: Date.now(), failed: !event.aborted && message?.stopReason === "error" };
+		tools = new Map();
+		changed();
+	});
+	hooks.host?.onChange(() => changed());
+}

package/src/roots/runtime.ts

@@ -0,0 +1,174 @@
+import { buildSessionContext, getPackageDir, hasTrustRequiringProjectResources, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { trackTreeWork, treeMetadata } from "../agents/registry.ts";
+import { sendViaDaemon } from "../daemon/client.mjs";
+import { prepareDirectory, statePaths, sessionDir as resolveSessionDir } from "./paths.mjs";
+import { rootSnapshot } from "./snapshot.mjs";
+import { recoverSocket } from "./socket-recovery.mjs";
+import { listen, request } from "./transport.mjs";
+
+export type RootDelivery = "followUp" | "steer" | "write";
+
+export interface RootMessage {
+	id: string;
+	/** Absent on a message from the user, which `user` marks. */
+	sender?: { id: string; name?: string };
+	user?: true;
+	recipient: string;
+	body: string;
+	deliverAs?: RootDelivery;
+}
+
+export interface RootEntry {
+	id: string;
+	name?: string;
+	cwd: string;
+	state: "running" | "idle";
+	sessionFile: string;
+}
+
+export interface RootHooks {
+	/** Adds a message from another root to this Session. */
+	receive(message: RootMessage): void | Promise<void>;
+	/** Whether this root's tree has no inputs that have not ended. */
+	treeIdle(): boolean;
+	/** IDs of messages from other roots already in this Session. */
+	receivedIds(ctx: ExtensionContext): Iterable<string>;
+}
+
+function piCli(): string {
+	const dir = getPackageDir();
+	const bundled = join(dir, "dist/bundle/cli.js");
+	return existsSync(bundled) ? bundled : join(dir, "dist/cli.js");
+}
+
+/**
+ * Makes this root Agent reachable from other processes: it answers status requests,
+ * and accepts messages from other roots.
+ */
+export function createRootRuntime(pi: ExtensionAPI, hooks: RootHooks) {
+	const paths = statePaths();
+	const sessionDir = resolveSessionDir();
+	let active: ExtensionContext | undefined;
+	let server: Awaited<ReturnType<typeof listen>> | undefined;
+	let ready = false;
+	let seen = new Set<string>();
+
+	function availabilityError(): string | undefined {
+		const ctx = active!;
+		if (!ctx.model) return "The recipient has no available model. Open the Session interactively and select a model.";
+		const saved = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).model;
+		if (saved && (saved.provider !== ctx.model.provider || saved.modelId !== ctx.model.id)) {
+			return `Saved model ${saved.provider}/${saved.modelId} is unavailable; refusing model fallback.`;
+		}
+		if (hasTrustRequiringProjectResources(ctx.cwd) && !ctx.isProjectTrusted()) {
+			return `Interactive project authorization is required in ${ctx.cwd}. Open the Session interactively first.`;
+		}
+	}
+
+	function idle(): boolean {
+		return active !== undefined && active.isIdle() && !active.hasPendingMessages() && hooks.treeIdle();
+	}
+
+	function current() {
+		const ctx = active!;
+		return {
+			id: ctx.sessionManager.getSessionId(),
+			name: pi.getSessionName(),
+			cwd: ctx.cwd,
+			sessionFile: ctx.sessionManager.getSessionFile()!,
+			state: idle() ? "idle" : "running",
+			ready,
+			pid: process.pid,
+			model: ctx.model ? { provider: ctx.model.provider, modelId: ctx.model.id } : undefined,
+			availabilityError: availabilityError(),
+		};
+	}
+
+	async function accept(message: RootMessage, { signal }: { signal: AbortSignal }) {
+		if (!ready || !active) throw new Error("The recipient is not ready.");
+		if (message.recipient !== active.sessionManager.getSessionId()) throw new Error("Message recipient does not match this Agent.");
+		const error = availabilityError();
+		if (error) throw new Error(error);
+		signal.throwIfAborted();
+		if (!seen.has(message.id)) {
+			seen.add(message.id);
+			// The tree stays busy until the message is in the Session.
+			const release = trackTreeWork(message.recipient);
+			try {
+				await hooks.receive(message);
+			} finally {
+				release();
+			}
+		}
+		return { accepted: true, messageId: message.id };
+	}
+
+	pi.on("resources_discover", () => {
+		if (!active || !server) return;
+		ready = true;
+	});
+
+	return {
+		/** Other root Agents with their state. Only a root Agent sees them. */
+		async roots(signal?: AbortSignal): Promise<RootEntry[]> {
+			if (!active || !ready) return [];
+			const self = current();
+			const records = await rootSnapshot(paths, sessionDir, { signal, current: self });
+			return records
+				.filter((root: { id: string }) => root.id !== self.id)
+				.map(({ id, name, cwd, state, sessionFile }: RootEntry) => ({ id, name, cwd, state, sessionFile }));
+		},
+
+		/** Sends to another root: inputs start it in a host through the daemon, writes reach it only while it runs. */
+		async send(target: { id: string; label: string }, delivery: RootDelivery, body: string, signal?: AbortSignal): Promise<void> {
+			if (!active || !ready) throw new Error("Root messaging is not ready; only persistent root Sessions participate.");
+			const sender = { id: active.sessionManager.getSessionId(), ...(pi.getSessionName() ? { name: pi.getSessionName() } : {}) };
+			const message: RootMessage = { id: randomUUID(), sender, recipient: target.id, body, deliverAs: delivery };
+			let receipt: { accepted?: boolean; messageId?: string };
+			if (delivery === "write") {
+				try {
+					receipt = await request(paths.session(target.id), { action: "deliver", message }, { signal });
+				} catch (error) {
+					const code = (error as NodeJS.ErrnoException).code;
+					if (code === "ENOENT" || code === "ECONNREFUSED") throw new Error(`${target.label} is offline.`);
+					throw error;
+				}
+			} else {
+				// The recipient runs with this Session's Pi, environment, and pi-agents, which Pi loads once.
+				const extension = pi.getAllTools().find((tool) => tool.name === "agent")!.sourceInfo.path;
+				const env = Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined));
+				const launch = { command: process.execPath, args: [piCli(), "-e", extension], env };
+				receipt = await sendViaDaemon(paths, message, { sessionDir, launch, signal });
+			}
+			if (receipt?.accepted !== true || receipt.messageId !== message.id) {
+				throw new Error(`Invalid acknowledgement from ${target.label}; it may have received the message.`);
+			}
+		},
+
+		async start(ctx: ExtensionContext): Promise<void> {
+			if (server && active?.sessionManager === ctx.sessionManager) {
+				active = ctx;
+				return;
+			}
+			if (!ctx.sessionManager.getSessionFile() || treeMetadata(ctx)) return;
+			active = ctx;
+			seen = new Set(hooks.receivedIds(ctx));
+			await prepareDirectory(paths.runtime);
+			const socket = paths.session(ctx.sessionManager.getSessionId());
+			await recoverSocket(socket);
+			server = await listen(socket, { status: current, accept });
+		},
+
+		async stop(): Promise<void> {
+			ready = false;
+			await server?.close();
+			server = undefined;
+			active = undefined;
+		},
+	};
+}
+
+export type RootRuntime = ReturnType<typeof createRootRuntime>;

package/src/roots/snapshot.mjs

@@ -0,0 +1,46 @@
+import { readdir, realpath } from 'node:fs/promises';
+import { join } from 'node:path';
+import { discoverRoots } from './discovery.mjs';
+import { isLocked } from './locks.mjs';
+import { markedFiles } from '../daemon/sessions.mjs';
+import { request } from './transport.mjs';
+
+/**
+ * Root Agents on disk with their state: `running` or `idle` when their runtime answers,
+ * `running` when another runtime holds the Session without answering, `idle` otherwise.
+ */
+export async function rootSnapshot(paths, sessionDir, { signal, current } = {}) {
+  let sockets;
+  try { sockets = (await readdir(paths.runtime)).filter(name => /^s-[a-f0-9]{24}\.sock$/.test(name)); }
+  catch (error) { if (error.code === 'ENOENT') sockets = []; else throw error; }
+  const online = new Map();
+  for (const socket of sockets) {
+    signal?.throwIfAborted();
+    try {
+      const root = await request(join(paths.runtime, socket), { action: 'status' }, { signal, timeoutMs: 1000 });
+      if (root?.ready === true && typeof root.id === 'string' && typeof root.cwd === 'string' && typeof root.sessionFile === 'string'
+        && ['idle', 'running'].includes(root.state) && paths.session(root.id) === join(paths.runtime, socket)) online.set(root.id, root);
+    } catch (error) {
+      signal?.throwIfAborted();
+      if (!['ENOENT', 'ECONNREFUSED', 'ETIMEDOUT', 'CONNECTION_CLOSED', 'INVALID_FRAME'].includes(error.code)) throw error;
+    }
+  }
+  if (current) online.set(current.id, current);
+  // Online roots report their own metadata; skip reparsing their growing Session files.
+  const skip = new Set([...online.values()].map(root => root.sessionFile));
+  const records = await discoverRoots(sessionDir, { extraFiles: await markedFiles(paths), skip, signal });
+  const roots = [];
+  for (const record of records) {
+    signal?.throwIfAborted();
+    if (online.has(record.id)) continue;
+    try {
+      record.state = isLocked(paths.locks, await realpath(record.sessionFile), record.id) ? 'running' : 'idle';
+    } catch (error) {
+      if (error.code === 'ENOENT') continue;
+      throw error;
+    }
+    roots.push(record);
+  }
+  roots.push(...online.values());
+  return roots;
+}

package/src/roots/socket-recovery.mjs

@@ -0,0 +1,21 @@
+import { lstat, unlink } from 'node:fs/promises';
+import { request } from './transport.mjs';
+
+// Call only while holding the endpoint's lock. A missing registry
+// entry or stale PID alone never authorizes removing a socket.
+export async function recoverSocket(path) {
+  let before;
+  try { before = await lstat(path); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  if (!before.isSocket() || before.uid !== process.getuid()) throw new Error(`Refusing to replace a non-owned socket: ${path}`);
+  try {
+    await request(path, { action: 'status' }, { timeoutMs: 1000 });
+    throw new Error(`Another runtime is responding at ${path}`);
+  } catch (error) {
+    if (error.code !== 'ECONNREFUSED') throw error;
+  }
+  const after = await lstat(path);
+  if (after.dev !== before.dev || after.ino !== before.ino) throw new Error(`Socket changed during recovery: ${path}`);
+  await unlink(path);
+}
+