pi-squire 0.1.0

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "pi-squire",
+	"version": "0.1.0",
+	"description": "Starts a delegate Pi session in a background tmux window, sends it the task over message:*, and shows the parent its result",
+	"keywords": [
+		"pi-package",
+		"pi",
+		"pi-extension"
+	],
+	"license": "MIT",
+	"author": "Gage Vander Clay <gvanderclay@gmail.com>",
+	"homepage": "https://github.com/gvanderclay/pi-squire#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/gvanderclay/pi-squire.git"
+	},
+	"bugs": {
+		"url": "https://github.com/gvanderclay/pi-squire/issues"
+	},
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"packageManager": "pnpm@10.33.0",
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"files": [
+		"index.ts",
+		"child.ts",
+		"agents.ts",
+		"tmux.ts",
+		"results.ts",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"lint": "biome ci .",
+		"typecheck": "tsc -p .",
+		"test": "node --test test/*.test.ts",
+		"check": "pnpm lint && pnpm typecheck && pnpm test",
+		"release": "node scripts/release.mjs"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": "*",
+		"typebox": "*"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.14",
+		"@earendil-works/pi-coding-agent": "1.0.0",
+		"@types/node": "26.6.3",
+		"typebox": "1.3.27",
+		"typescript": "7.0.2"
+	}
+}

package/results.ts

@@ -0,0 +1,293 @@
+// The delegation records and the result message. A delegation is recorded in
+// the parent session when it starts, and again when it is closed; when the
+// provider claims a reply that answers a recorded task, this listener takes
+// the message over, shows the parent one delegate result and records the
+// result. The records are the one source of truth for a delegation's state,
+// for the footer, `delegation_status` and `delegation_close`.
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/** The session entry type both delegation records and results use. */
+export const CUSTOM_TYPE = "delegate";
+/** The footer entry that counts delegations whose result has not arrived. */
+export const STATUS_KEY = "delegate";
+/** A task quoted into the result header is cut at this many UTF-8 bytes. */
+const TASK_CAP = 2 * 1024;
+/** A result body is cut at this many UTF-8 bytes. */
+const BODY_CAP = 32 * 1024;
+/** The `pi.events` channel a provider emits claimed envelopes on. */
+const INBOUND = "message:inbound";
+
+/** One delegation, as recorded and rebuilt on resume. It holds no task text. */
+export type Delegation = {
+	id: string;
+	agent: string;
+	model: string;
+	thinking: string;
+	/** The delegate's session and window name; absent in records from before labels, where it was `<agent>-<8 id characters>`. */
+	name?: string;
+	windowId: string;
+	windowName: string;
+	requestId: string;
+	/** Whether the delegate closes its own window after a normal completion; absent in records from before auto-exit. */
+	autoExit?: boolean;
+};
+
+/**
+ * An envelope on the `message:inbound` payload. `delegate` declares its own
+ * copy of the provider's shape; the provider's README owns the contract.
+ */
+export type Envelope = {
+	id: string;
+	from: string;
+	to: string;
+	in_reply_to: string[];
+	status: string;
+	ts: string;
+	body: string;
+};
+
+/** A reply's request copy from the parent's `sent/`. */
+export type RequestCopy = { envelope: Envelope; path: string };
+
+/** A result, appended to the session so it is shown once and survives a resume. */
+export type Result = {
+	/** The envelope's status: `done`, `failed` or `stopped`. */
+	status: string;
+	/** The reply envelope's id, so the same reply is never shown twice. */
+	replyId: string;
+	/** The reply envelope's path in the parent's `cur/`. */
+	envelopePath: string;
+	/** The delegate's session file, when it could be found. */
+	sessionPath?: string;
+};
+
+/** One delegation as it stands: what was recorded at its start, plus what came after. */
+export type Recorded = Delegation & {
+	/** Set when a result arrived. */
+	result?: Result;
+	/** Set when `delegation_close` recorded a close. */
+	closed?: boolean;
+	/** Set when the poll found the window gone with no result; a result outranks it. */
+	gone?: boolean;
+};
+
+/** The provider's payload on `message:inbound`. */
+export type Inbound = {
+	envelope: Envelope;
+	path: string;
+	requests: RequestCopy[];
+	handled: boolean;
+};
+
+export type Results = {
+	/** Rebuild the records from the session's custom entries, as on a resume. */
+	restore(ctx: ExtensionContext): void;
+	/** Record a delegation and show it as running. */
+	recordStart(delegation: Delegation, ctx: ExtensionContext): void;
+	/** Record a close. `unknown` when no such delegation, `already-closed` when one was recorded. */
+	recordClose(id: string): "closed" | "already-closed" | "unknown";
+	/** Delegations with no result, no recorded close and no gone-window record. */
+	running(): Recorded[];
+	/** Record that the window is gone with no result, and tell the parent once. False when it no longer applies. */
+	recordGone(id: string): boolean;
+	/** Every delegation, in the order it was recorded. */
+	list(): Recorded[];
+	/** One delegation by id. */
+	find(id: string): Recorded | undefined;
+	/** Take over a reply that answers a recorded delegation, if any. */
+	takeReply(payload: Inbound): void;
+};
+
+/** Cut `text` to at most `max` UTF-8 bytes on a character boundary; undefined when it already fits. */
+function cap(text: string, max: number): string | undefined {
+	const bytes = Buffer.from(text, "utf8");
+	if (bytes.length <= max) return undefined;
+	let end = max;
+	while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--; // back off a split character
+	return bytes.subarray(0, end).toString("utf8");
+}
+
+/** The delegate's session file in `dir`, found by its `_<id>.jsonl` suffix. */
+export function findSession(dir: string | undefined, id: string): string | undefined {
+	if (dir === undefined) return undefined;
+	let names: string[];
+	try {
+		names = readdirSync(dir);
+	} catch {
+		return undefined;
+	}
+	const name = names.find((candidate) => candidate.endsWith(`_${id}.jsonl`));
+	return name === undefined ? undefined : join(dir, name);
+}
+
+/** The one message the parent sees for a settled delegation. */
+function resultText(delegation: Delegation, payload: Inbound, session: string | undefined): string {
+	const reply = payload.envelope;
+	const copy = payload.requests.find((request) => request.envelope?.id === delegation.requestId);
+	let quote: string;
+	if (copy === undefined) {
+		quote = `[delegate] The task ${delegation.requestId} has no copy in sent/; only its id is known.`;
+	} else {
+		const cut = cap(copy.envelope.body, TASK_CAP);
+		const lines =
+			cut === undefined ? copy.envelope.body : `${cut}\n[delegate] Task cut at 2 KiB; the full copy is ${copy.path}`;
+		quote = `Task, quoted from ${copy.path}:\n${lines
+			.split("\n")
+			.map((line) => `> ${line}`)
+			.join("\n")}`;
+	}
+	const cut = cap(reply.body, BODY_CAP);
+	const result =
+		cut === undefined ? reply.body : `${cut}\n[delegate] Body cut at 32 KiB; the full envelope is ${payload.path}`;
+	return [
+		`[delegate] Result from ${delegation.agent} (${delegation.model}), delegation ${delegation.id}, request ${delegation.requestId}.`,
+		`Status: ${reply.status}`,
+		quote,
+		`Envelope: ${payload.path}`,
+		`Delegate session: ${session ?? delegation.id}`,
+		"",
+		result,
+	].join("\n");
+}
+
+export function createResults(pi: ExtensionAPI): Results {
+	/** Every recorded delegation by its id, in the order recorded. */
+	const byId = new Map<string, Recorded>();
+	/** The same records by their request's envelope id, for matching replies. */
+	const byRequest = new Map<string, Recorded>();
+	/** Reply envelope ids a result message has already been sent for. */
+	const shown = new Set<string>();
+	/** The latest session context, for the footer and the session directory. */
+	let ctx: ExtensionContext | undefined;
+	/** Whether the footer currently shows the entry, so a clear is sent only when needed. */
+	let footerShown = false;
+
+	/** A delegation still going: no result and no recorded close. */
+	const running = (): Recorded[] =>
+		[...byId.values()].filter(
+			(record) => record.result === undefined && record.closed !== true && record.gone !== true,
+		);
+
+	/** The footer counts the running delegations, and hides itself at zero. */
+	function updateFooter(): void {
+		if (ctx?.hasUI !== true) return;
+		const count = running().length;
+		const visible = count > 0;
+		if (!visible && !footerShown) return;
+		footerShown = visible;
+		ctx.ui.setStatus(STATUS_KEY, visible ? `⇄ ${count} running` : undefined);
+	}
+
+	/** Rebuild the records from the session's entries, so a resume still recognises replies. */
+	function restore(context: ExtensionContext): void {
+		ctx = context;
+		byId.clear();
+		byRequest.clear();
+		shown.clear();
+		for (const entry of context.sessionManager.getEntries()) {
+			if (entry.type !== "custom" || entry.customType !== CUSTOM_TYPE) continue;
+			const data = entry.data as Partial<Delegation & { result: Result; closed: boolean; gone: boolean }> | undefined;
+			if (data === undefined || typeof data.id !== "string") continue;
+			if (typeof data.requestId === "string") {
+				const record: Recorded = { ...(data as Delegation) };
+				byId.set(record.id, record);
+				byRequest.set(record.requestId, record);
+			} else if (typeof data.result?.replyId === "string") {
+				shown.add(data.result.replyId);
+				const record = byId.get(data.id);
+				if (record !== undefined) record.result = data.result;
+			} else if (data.closed === true) {
+				const record = byId.get(data.id);
+				if (record !== undefined) record.closed = true;
+			} else if (data.gone === true) {
+				const record = byId.get(data.id);
+				if (record !== undefined) record.gone = true;
+			}
+		}
+		updateFooter();
+	}
+
+	function recordStart(delegation: Delegation, context: ExtensionContext): void {
+		ctx = context;
+		pi.appendEntry(CUSTOM_TYPE, delegation);
+		const record: Recorded = { ...delegation };
+		byId.set(record.id, record);
+		byRequest.set(record.requestId, record);
+		updateFooter();
+	}
+
+	function recordClose(id: string): "closed" | "already-closed" | "unknown" {
+		const record = byId.get(id);
+		if (record === undefined) return "unknown";
+		if (record.closed === true) return "already-closed";
+		pi.appendEntry(CUSTOM_TYPE, { id, closed: true });
+		record.closed = true;
+		updateFooter();
+		return "closed";
+	}
+
+	function recordGone(id: string): boolean {
+		const record = byId.get(id);
+		if (record === undefined || record.result !== undefined || record.closed === true || record.gone === true)
+			return false;
+		const session = findSession(ctx?.sessionManager.getSessionDir(), record.id);
+		pi.appendEntry(CUSTOM_TYPE, { id, gone: true });
+		record.gone = true;
+		pi.sendMessage(
+			{
+				customType: CUSTOM_TYPE,
+				content: [
+					`[delegate] Delegation ${record.id} (${record.agent}, ${record.model}), request ${record.requestId}, closed without a result: its window ${record.windowName} is gone and no reply arrived.`,
+					`Delegate session: ${session ?? record.id}`,
+					"A reply that arrives later is still delivered.",
+				].join("\n"),
+				display: true,
+			},
+			{ triggerTurn: true, deliverAs: "followUp" },
+		);
+		updateFooter();
+		return true;
+	}
+
+	function takeReply(payload: Inbound): void {
+		if (payload?.handled === true) return;
+		const reply = payload?.envelope;
+		if (reply === undefined || !Array.isArray(reply.in_reply_to) || reply.in_reply_to.length === 0) return;
+		const requestId = reply.in_reply_to.find((id) => byRequest.has(id));
+		if (requestId === undefined) return;
+		payload.handled = true;
+		if (shown.has(reply.id)) return;
+		const delegation = byRequest.get(requestId) as Recorded;
+		shown.add(reply.id);
+		const session = findSession(ctx?.sessionManager.getSessionDir(), delegation.id);
+		pi.sendMessage(
+			{ customType: CUSTOM_TYPE, content: resultText(delegation, payload, session), display: true },
+			{ triggerTurn: true, deliverAs: "followUp" },
+		);
+		const result: Result = {
+			status: reply.status,
+			replyId: reply.id,
+			envelopePath: payload.path,
+			...(session === undefined ? {} : { sessionPath: session }),
+		};
+		pi.appendEntry(CUSTOM_TYPE, { id: delegation.id, result });
+		delegation.result = result;
+		updateFooter();
+	}
+
+	pi.events.on(INBOUND, (data) => takeReply(data as Inbound));
+
+	return {
+		restore,
+		recordStart,
+		recordClose,
+		running,
+		recordGone,
+		list: () => [...byId.values()],
+		find: (id) => byId.get(id),
+		takeReply,
+	};
+}

package/tmux.ts

@@ -0,0 +1,75 @@
+// The tmux operations `delegate` needs, behind an interface so tests can use a
+// fake. This client talks to tmux with `execFile` and no shell.
+import { execFile } from "node:child_process";
+
+/** One window to open: its name, working directory, command and environment. */
+export type WindowSpec = {
+	name: string;
+	cwd: string;
+	argv: readonly string[];
+	env: Readonly<Record<string, string>>;
+};
+
+export interface TmuxClient {
+	/** Whether this process runs in a tmux pane. */
+	insideTmux(): boolean;
+	/** Open a detached window and return its id (for example `@3`). */
+	openWindow(spec: WindowSpec): Promise<string>;
+	/** Whether a window id is still listed. */
+	isAlive(windowId: string): Promise<boolean>;
+	/** Kill a window. */
+	kill(windowId: string): Promise<void>;
+}
+
+/** Run one tmux command and return its stdout; never a shell. */
+function run(args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		execFile("tmux", args, { encoding: "utf8" }, (error, stdout, stderr) => {
+			if (error) {
+				const detail = typeof stderr === "string" && stderr.trim() !== "" ? stderr.trim() : error.message;
+				reject(new Error(detail));
+				return;
+			}
+			resolve(stdout);
+		});
+	});
+}
+
+/**
+ * The real client. A window is opened in the session of the pane in
+ * `TMUX_PANE`, not in whatever session a client happens to have attached, so
+ * it works with several clients on one server.
+ */
+export function createTmuxClient(): TmuxClient {
+	/** The id of the session this pane belongs to, when known. */
+	async function targetSession(): Promise<string | undefined> {
+		const pane = process.env.TMUX_PANE;
+		if (pane === undefined || pane === "") return undefined;
+		const sessionId = (await run(["display-message", "-p", "-t", pane, "-F", "#{session_id}"])).trim();
+		return sessionId === "" ? undefined : sessionId;
+	}
+
+	return {
+		insideTmux: () => (process.env.TMUX ?? "") !== "",
+
+		async openWindow(spec) {
+			const args = ["new-window", "-d", "-P", "-F", "#{window_id}", "-n", spec.name, "-c", spec.cwd];
+			for (const [key, value] of Object.entries(spec.env)) args.push("-e", `${key}=${value}`);
+			const session = await targetSession();
+			if (session !== undefined) args.push("-t", session);
+			args.push("--", ...spec.argv);
+			const windowId = (await run(args)).trim();
+			if (windowId === "") throw new Error("tmux reported no window id");
+			return windowId;
+		},
+
+		async isAlive(windowId) {
+			const ids = (await run(["list-windows", "-a", "-F", "#{window_id}"])).split("\n");
+			return ids.some((id) => id.trim() === windowId);
+		},
+
+		async kill(windowId) {
+			await run(["kill-window", "-t", windowId]);
+		},
+	};
+}