pi-squire 0.1.0 → 0.2.1

package/{index.ts → src/index.ts}

@@ -33,6 +33,8 @@
 // The `session:launch` contract this package provides, and the `message:*`
 // hooks it consumes, live in this package's README.
 import { randomUUID } from "node:crypto";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 
 import {
@@ -45,17 +47,14 @@ import { Type } from "typebox";
 
 import { type Agent, isThinking, type Roster, readRoster, THINKING_LEVELS } from "./agents.ts";
 import { AUTO_EXIT_ENV, registerChild } from "./child.ts";
-import { createResults, findSession, type Recorded } from "./results.ts";
+import { createResults, delegateName } from "./results.ts";
 import { createTmuxClient, type TmuxClient } from "./tmux.ts";
+import { createTracking, toolResult } from "./tracking.ts";
 
 /** The hook a provider of `message:*` answers with the written request. */
 const SEND = "message:send";
 /** The hook emitted just before a delegate's window opens. */
 const LAUNCH = "session:launch";
-/** The hook a tick emits so the provider claims waiting replies before windows are checked. */
-const SCAN = "message:scan";
-/** How often the parent checks its running delegations. */
-const POLL_MS = 5000;
 /** Set in a delegate's environment, so this extension stays off there. */
 const PARENT_ENV = "PI_DELEGATE_PARENT";
 /** Forwarded to the child when the parent has it set. */
@@ -63,22 +62,12 @@ const SESSION_DIR_ENV = "PI_CODING_AGENT_SESSION_DIR";
 /** Asked of every delegate, so the parent gets an answer it can use alone. */
 const FINAL_LINE =
 	"End with one self-contained final message: the parent session sees only that message, never this conversation.";
-/** How much of a delegation id a delegate's session name carries. */
-const SHORT_ID = 8;
 
 /** The longest label a delegation can carry. */
 const LABEL_MAX = 32;
 /** A label is one safe tmux window name and session name segment. */
 const LABEL = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
 
-/**
- * A delegate's name, used for both its session and its window: its agent and
- * the label, or the first 8 characters of its id when there is no label.
- */
-function delegateName(agent: string, id: string, label?: string): string {
-	return `${agent}-${label ?? id.slice(0, SHORT_ID)}`;
-}
-
 /** Why `value` is not a usable label, or undefined when it is. */
 function labelProblem(value: string): string | undefined {
 	if (LABEL.test(value) && value.length <= LABEL_MAX) return undefined;
@@ -112,13 +101,30 @@ const USAGE =
 	"usage: /delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--auto-exit | --no-auto-exit] <task>";
 
 type SendPayload = { to: unknown; body: unknown; envelope?: { id?: unknown }; error?: unknown };
-type LaunchPayload = { args: string[]; env: Record<string, string> };
+type LaunchPayload = { args: string[]; env: Record<string, string>; agent: string };
 type Parsed = { agent: string; model?: string; thinking?: string; label?: string; autoExit?: boolean; task: string };
 /** A request that passed the roster, model, thinking and label checks. */
 type Start = { agent: Agent; model: string; thinking: string; label?: string; autoExit: boolean; task: string };
 /** A delegation that is open in a tmux window. */
 type Launched = { id: string; name: string; windowId: string; windowName: string; requestId: string };
 
+/**
+ * Write the appended system prompt to a fresh owner-only directory under the
+ * system temporary folder and return the file's path. Pi reads an existing
+ * path as a file, so the prompt stays off the delegate's command line and out
+ * of `ps`. The directory comes from `mkdtemp`, which no other user can
+ * pre-create or swap.
+ *
+ * ponytail: one file per launch accumulates until the operating system clears
+ * its temporary folder; the upgrade path is to delete the file once the poll
+ * finds the window gone.
+ */
+function writePromptFile(prompt: string): string {
+	const path = join(mkdtempSync(join(tmpdir(), "pi-squire-")), "prompt.md");
+	writeFileSync(path, prompt, { mode: 0o600 });
+	return path;
+}
+
 /** The runtimes whose executable needs the script from `process.argv[1]`. */
 const RUNTIMES = new Set(["node", "nodejs", "bun", "deno"]);
 
@@ -193,7 +199,11 @@ function parse(text: string): { parsed: Parsed } | { error: string } {
 function modelProblem(value: string, registry: ModelRegistry): string | undefined {
 	const slash = value.indexOf("/");
 	if (slash <= 0 || slash === value.length - 1) return `--model takes provider/id, got ${JSON.stringify(value)}`;
-	if (registry.find(value.slice(0, slash), value.slice(slash + 1)) !== undefined) return undefined;
+	const known = registry.find(value.slice(0, slash), value.slice(slash + 1));
+	if (known !== undefined) {
+		if (registry.hasConfiguredAuth(known)) return undefined;
+		return `no credentials for model ${JSON.stringify(value)}; log in to the provider ${JSON.stringify(known.provider)} (/login), then try again`;
+	}
 	const names = registry.getAll().map((model) => `${model.provider}/${model.id}`);
 	const close = closest(value, names);
 	return `unknown model ${JSON.stringify(value)}${close.length > 0 ? `; close matches: ${close.join(", ")}` : ""}`;
@@ -238,14 +248,6 @@ function toolDescription(agents: readonly Agent[]): string {
 	].join("\n");
 }
 
-/** The one result every tool returns. */
-function toolResult(
-	payload: string,
-	details: unknown = {},
-): { content: { type: "text"; text: string }[]; details: unknown } {
-	return { content: [{ type: "text", text: payload }], details };
-}
-
 /**
  * Register `/delegate` and the three tools. The second parameter is a
  * test-only seam for tmux: Pi passes only `pi`, so it is not part of the
@@ -253,57 +255,15 @@ function toolResult(
  */
 export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmuxClient()): void {
 	// A delegate registers only its auto-exit side: `delegate` is one level deep (Q27).
-	if ((process.env[PARENT_ENV] ?? "") !== "") {
-		registerChild(pi);
+	const parentId = process.env[PARENT_ENV] ?? "";
+	if (parentId !== "") {
+		registerChild(pi, parentId);
 		return;
 	}
 
 	const results = createResults(pi);
 
-	/** The poll timer; set only while some delegation is running. */
-	let poll: ReturnType<typeof setInterval> | undefined;
-	let ticking = false;
-	/** False once the session shuts down, so a tick still awaiting tmux declares nothing. */
-	let live = true;
-
-	function stopPolling(): void {
-		if (poll !== undefined) clearInterval(poll);
-		poll = undefined;
-	}
-
-	/** Claim waiting replies first, then declare gone every window that is missing with still no result. */
-	async function tick(): Promise<void> {
-		if (ticking) return;
-		ticking = true;
-		try {
-			if (results.running().length === 0) return stopPolling();
-			const scan: { scanned?: boolean } = {};
-			pi.events.emit(SCAN, scan);
-			if (scan.scanned !== true) return; // no message:* provider: a waiting reply cannot be ruled out
-			for (const record of results.running()) {
-				let alive: boolean;
-				try {
-					alive = await tmux.isAlive(record.windowId);
-				} catch {
-					continue; // tmux could not be asked; never read that as gone
-				}
-				if (alive || !live) continue;
-				// A reply may have landed while the windows before this one were checked.
-				pi.events.emit(SCAN, {});
-				results.recordGone(record.id);
-			}
-			if (results.running().length === 0) stopPolling();
-		} finally {
-			ticking = false;
-		}
-	}
-
-	/** Start the timer when something is running; it never keeps the process alive. */
-	function startPolling(): void {
-		if (poll !== undefined || results.running().length === 0) return;
-		poll = setInterval(() => void tick(), POLL_MS);
-		poll.unref?.();
-	}
+	const tracking = createTracking(pi, results, tmux);
 
 	/** Captured because `getArgumentCompletions` is called without a context. */
 	let registry: ModelRegistry | undefined;
@@ -391,6 +351,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 
 		const parent = ctx.sessionManager.getSessionId();
 		const name = delegateName(start.agent.name, id, start.label);
+		const prompt = writePromptFile(`${start.agent.prompt}\n\n${FINAL_LINE}\n\n${parentTrust(parent)}`);
 		const argv = [
 			...parentCommand(),
 			"--session-id",
@@ -403,7 +364,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			start.thinking,
 			...(start.agent.excludeTools.length > 0 ? ["--exclude-tools", start.agent.excludeTools.join(",")] : []),
 			"--append-system-prompt",
-			`${start.agent.prompt}\n\n${FINAL_LINE}\n\n${parentTrust(parent)}`,
+			prompt,
 		];
 		const env: Record<string, string> = {
 			PI_CODING_AGENT_DIR: getAgentDir(),
@@ -413,7 +374,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 		const sessionDir = process.env[SESSION_DIR_ENV];
 		if (sessionDir !== undefined && sessionDir !== "") env[SESSION_DIR_ENV] = sessionDir;
 		// Listeners may only append to `args` and add to `env`; there is no veto.
-		const payload: LaunchPayload = { args: argv, env };
+		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name };
 		pi.events.emit(LAUNCH, payload);
 
 		const windowName = name;
@@ -439,7 +400,7 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 			},
 			ctx,
 		);
-		startPolling();
+		tracking.startPolling();
 		return { id, name, windowId, windowName, requestId };
 	}
 
@@ -526,167 +487,15 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 		},
 	});
 
-	/** One delegation's state, from its records and the window tmux reports. */
-	async function describe(record: Recorded, ctx: ExtensionContext): Promise<string> {
-		let alive: boolean | undefined;
-		try {
-			alive = await tmux.isAlive(record.windowId);
-		} catch {
-			alive = undefined; // tmux could not be asked; never read that as gone
-		}
-		const state =
-			record.closed === true
-				? "closed"
-				: record.result !== undefined
-					? "done"
-					: record.gone === true
-						? "gone"
-						: alive === true
-							? "running"
-							: alive === false
-								? "closed"
-								: "unknown";
-		const session = record.result?.sessionPath ?? findSession(ctx.sessionManager.getSessionDir(), record.id);
-		const lines = [
-			`${record.id} ${record.agent} (${record.model}, thinking ${record.thinking})`,
-			`  name: ${record.name ?? delegateName(record.agent, record.id)}`,
-			`  state: ${stateLine(state, record)}`,
-			`  window: ${record.windowName} (${record.windowId})`,
-			`  auto-exit: ${autoExitLine(record)}`,
-			`  session: ${session ?? `${record.id} (no session file yet)`}`,
-		];
-		if (record.result !== undefined) lines.push(`  envelope: ${record.result.envelopePath}`);
-		return lines.join("\n");
-	}
-
-	/** Records from before auto-exit existed kept their windows open, so they read off. */
-	function autoExitLine(record: Recorded): string {
-		return record.autoExit === true
-			? "on — the delegate closes its window after a normal completion unless the user took over there"
-			: "off — the window stays open after the result";
-	}
-
-	function stateLine(state: string, record: Recorded): string {
-		if (state === "running") return "running — the window is open and no result has arrived";
-		if (state === "gone")
-			return "closed without a result — the window is gone and no reply arrived; a late reply would make it done";
-		if (state === "done") return `done — result status: ${record.result?.status ?? "unknown"}`;
-		if (state === "closed") {
-			return record.closed === true ? "closed — delegation_close recorded it" : "closed — the window is gone";
-		}
-		return "unknown — tmux could not be asked whether the window is open";
-	}
-
-	const statusTool = {
-		name: "delegation_status",
-		label: "Delegation status",
-		description:
-			"The delegations this session started, each reported as running (the window is open and no result has arrived yet), done (with the result envelope's status) or closed (closed with delegation_close, or its window is gone). A delegation whose window went with no reply is reported closed without a result until a late reply makes it done. Names the delegation id, agent, session name, model, thinking, window, delegate session path and result envelope path. A delegate's window being open means it is connected, not that its task is unfinished or finished; only a result means done.",
-		parameters: Type.Object({
-			id: Type.Optional(Type.String({ description: "One delegation id; omit to report every delegation." })),
-		}),
-		async execute(
-			_toolCallId: string,
-			params: { id?: string },
-			_signal: unknown,
-			_onUpdate: unknown,
-			ctx: ExtensionContext,
-		) {
-			const all = results.list();
-			const records = params.id === undefined ? all : all.filter((record) => record.id === params.id);
-			if (params.id !== undefined && records.length === 0) {
-				throw new Error(
-					`no delegation ${JSON.stringify(params.id)}; known: ${all.map((record) => record.id).join(", ") || "none"}`,
-				);
-			}
-			const details = records.map((record) => ({
-				id: record.id,
-				name: delegateName(record.agent, record.id),
-				agent: record.agent,
-				model: record.model,
-				thinking: record.thinking,
-				autoExit: record.autoExit === true,
-				windowId: record.windowId,
-				windowName: record.windowName,
-				closed: record.closed === true,
-				closedWithoutResult: record.gone === true && record.result === undefined && record.closed !== true,
-				status: record.result?.status,
-				envelopePath: record.result?.envelopePath,
-				sessionPath: record.result?.sessionPath ?? findSession(ctx.sessionManager.getSessionDir(), record.id),
-			}));
-			if (records.length === 0)
-				return toolResult("No delegations are recorded in this session.", { delegations: details });
-			const blocks: string[] = [];
-			for (const record of records) blocks.push(await describe(record, ctx));
-			const heading = `${records.length} delegation${records.length === 1 ? "" : "s"}:`;
-			return toolResult(`${heading}\n\n${blocks.join("\n\n")}`, { delegations: details });
-		},
-	};
-
-	const closeTool = {
-		name: "delegation_close",
-		label: "Close delegation",
-		description:
-			"Close one delegation: kill its tmux window through tmux and record the close, so delegation_status reports it closed. The delegate's session file and result envelope stay on disk. An unknown or already closed id returns a message with nothing killed.",
-		parameters: Type.Object({
-			id: Type.String({ description: "The delegation id to close." }),
-		}),
-		async execute(
-			_toolCallId: string,
-			params: { id: string },
-			_signal: unknown,
-			_onUpdate: unknown,
-			_ctx: ExtensionContext,
-		) {
-			const record = results.find(params.id);
-			if (record === undefined) {
-				const known =
-					results
-						.list()
-						.map((item) => item.id)
-						.join(", ") || "none";
-				throw new Error(`no delegation ${JSON.stringify(params.id)}; known: ${known}`);
-			}
-			if (record.closed === true)
-				return toolResult(`Delegation ${record.id} is already closed.`, { id: record.id, closed: true });
-			let alive: boolean;
-			try {
-				alive = await tmux.isAlive(record.windowId);
-			} catch (err) {
-				throw new Error(`could not ask tmux about window ${record.windowName}: ${(err as Error).message}`);
-			}
-			if (alive) {
-				try {
-					await tmux.kill(record.windowId);
-				} catch (err) {
-					throw new Error(`could not kill window ${record.windowName} (${record.windowId}): ${(err as Error).message}`);
-				}
-			}
-			results.recordClose(record.id);
-			const how = alive
-				? `killed window ${record.windowName} (${record.windowId})`
-				: `its window ${record.windowName} was already gone`;
-			return toolResult(`Closed delegation ${record.id}: ${how}.`, {
-				id: record.id,
-				windowId: record.windowId,
-				killed: alive,
-			});
-		},
-	};
-
 	pi.on("session_start", (_event, ctx) => {
 		registry = ctx.modelRegistry;
-		stopPolling();
-		live = true;
-		results.restore(ctx);
-		startPolling();
+		tracking.restore(ctx);
 		// The roster is read at call time; the description can only be fixed here.
 		pi.registerTool(delegateTool() as never);
 	});
 
 	pi.on("session_shutdown", () => {
-		live = false;
-		stopPolling();
+		tracking.stop();
 	});
 
 	/** Agent names, flags, model ids and thinking levels, at the cursor's token. */
@@ -712,6 +521,5 @@ export default function delegate(pi: ExtensionAPI, tmux: TmuxClient = createTmux
 	});
 
 	pi.registerTool(delegateTool() as never);
-	pi.registerTool(statusTool as never);
-	pi.registerTool(closeTool as never);
+	tracking.registerTools();
 }

package/{results.ts → src/results.ts}

@@ -87,8 +87,8 @@ export type Results = {
 	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";
+	/** Record a close; does nothing when there is no such delegation or it is already closed. */
+	recordClose(id: string): void;
 	/** 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. */
@@ -97,10 +97,44 @@ export type Results = {
 	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;
 };
 
+/** What tmux reported for a delegation's window: listed, not listed, or not askable. */
+export type WindowState = "open" | "gone" | "unknown";
+
+/**
+ * A delegation's state. `closed` is a recorded `delegation_close`; `gone` is
+ * closed without a result (the poll found the window missing); `window-closed`
+ * is a window tmux no longer lists, seen when asked directly.
+ */
+export type DelegationState = "closed" | "done" | "gone" | "running" | "window-closed" | "unknown";
+
+/** How much of a delegation id a delegate's session name carries. */
+const SHORT_ID = 8;
+
+/**
+ * A delegate's name, used for both its session and its window: its agent and
+ * the label, or the first 8 characters of its id when there is no label.
+ */
+export function delegateName(agent: string, id: string, label?: string): string {
+	return `${agent}-${label ?? id.slice(0, SHORT_ID)}`;
+}
+
+/** The recorded name, or the pre-label name for records from before labels. */
+export function recordedName(record: Recorded): string {
+	return record.name ?? delegateName(record.agent, record.id);
+}
+
+/** A delegation's state: a recorded close, then a result, then a gone record, then the window. */
+export function deriveState(record: Recorded, window: WindowState): DelegationState {
+	if (record.closed === true) return "closed";
+	if (record.result !== undefined) return "done";
+	if (record.gone === true) return "gone";
+	if (window === "open") return "running";
+	if (window === "gone") return "window-closed";
+	return "unknown";
+}
+
 /** 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");
@@ -219,14 +253,12 @@ export function createResults(pi: ExtensionAPI): Results {
 		updateFooter();
 	}
 
-	function recordClose(id: string): "closed" | "already-closed" | "unknown" {
+	function recordClose(id: string): void {
 		const record = byId.get(id);
-		if (record === undefined) return "unknown";
-		if (record.closed === true) return "already-closed";
+		if (record === undefined || record.closed === true) return;
 		pi.appendEntry(CUSTOM_TYPE, { id, closed: true });
 		record.closed = true;
 		updateFooter();
-		return "closed";
 	}
 
 	function recordGone(id: string): boolean {
@@ -256,7 +288,8 @@ export function createResults(pi: ExtensionAPI): Results {
 		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));
+		// Only the delegate's own reply counts: `from` must be the delegation's id.
+		const requestId = reply.in_reply_to.find((id) => byRequest.get(id)?.id === reply.from);
 		if (requestId === undefined) return;
 		payload.handled = true;
 		if (shown.has(reply.id)) return;
@@ -288,6 +321,5 @@ export function createResults(pi: ExtensionAPI): Results {
 		recordGone,
 		list: () => [...byId.values()],
 		find: (id) => byId.get(id),
-		takeReply,
 	};
 }

package/{tmux.ts → src/tmux.ts}

@@ -10,13 +10,16 @@ export type WindowSpec = {
 	env: Readonly<Record<string, string>>;
 };
 
+/** One window as tmux lists it: its id, its name, and whether the program in its pane has exited. */
+export type TmuxWindow = { id: string; name: string; exited: boolean };
+
 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>;
+	/** Every window on the server, in one tmux call. */
+	listWindows(): Promise<TmuxWindow[]>;
 	/** Kill a window. */
 	kill(windowId: string): Promise<void>;
 }
@@ -63,9 +66,16 @@ export function createTmuxClient(): TmuxClient {
 			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 listWindows() {
+			// The name goes last: it is the one field that could hold a tab.
+			const out = await run(["list-windows", "-a", "-F", "#{window_id}\t#{pane_dead}\t#{window_name}"]);
+			return out
+				.split("\n")
+				.filter((line) => line.trim() !== "")
+				.map((line) => {
+					const [id, dead, ...name] = line.split("\t");
+					return { id, name: name.join("\t"), exited: dead === "1" };
+				});
 		},
 
 		async kill(windowId) {