pi-squire 0.11.0 → 0.13.0

package/src/resume-checks.ts

@@ -0,0 +1,159 @@
+// The checks a resume makes before it launches anything, shared by `resume`
+// and the resume picker so both accept the same delegations: the call-wide
+// prerequisites once, then per record the window, session file, agent, thinking
+// level and model. None of them changes anything; killing an exited window and
+// deciding trust stay with the resume itself.
+import { statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { Agent } from "./agents.ts";
+import { sessionHeaderCwd, sessionIdOf } from "./result-sessions.ts";
+import { deriveState, finishedModel, locateSession, type StartedRecorded } from "./results.ts";
+import type { ResumeDeps, ResumeRequest } from "./resume.ts";
+import { requireTmuxVersion, type TmuxWindow } from "./tmux.ts";
+import { ownWindow, windowState } from "./tracking.ts";
+import type { WindowPlacement } from "./window-placement.ts";
+
+/**
+ * Steps 3 and 4: no process of this delegate is left. A running delegate is
+ * mailed instead; tmux that cannot be asked proves nothing; a window with the
+ * record's id and name that still runs its program is refused, and one whose
+ * program exited is killed first.
+ */
+export function windowCheck(record: StartedRecorded, windows: TmuxWindow[] | undefined): TmuxWindow | undefined {
+	const state = deriveState(record, windowState(windows, record));
+	if (state === "running") {
+		throw new Error(`delegation ${record.id} is running; send it a message instead of resuming it`);
+	}
+	if (windows === undefined || state === "unknown") {
+		throw new Error(`could not ask tmux whether delegation ${record.id}'s window is open, so it is not resumed`);
+	}
+	const own = ownWindow(windows, record);
+	if (own !== undefined && !own.exited) {
+		throw new Error(
+			`delegation ${record.id}'s window ${record.windowName} (${record.windowId}) is still open; its Pi may still be running, so it is not resumed. Close it with delegation_close, or send it a message`,
+		);
+	}
+	return own;
+}
+
+/** Whether `path` is an existing directory. */
+export function isDirectory(path: string): boolean {
+	try {
+		return statSync(path).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** A delegate's session file, the directory its header says Pi runs it in, and the session directory to pass. */
+export type SessionFile = { path: string; cwd: string; dir: string };
+
+/** Step 5: the session file, and the directory its header says Pi will run it in. */
+export function sessionFor(record: StartedRecorded, ctx: ExtensionContext): SessionFile {
+	const dir = record.sessionDir ?? ctx.sessionManager.getSessionDir();
+	const path = locateSession(record, ctx.sessionManager.getSessionDir());
+	if (path === undefined) {
+		throw new Error(
+			`no session file for session ${sessionIdOf(record)} was found in ${dir}, so delegation ${record.id} is not resumable`,
+		);
+	}
+	if (!isAbsolute(path) || !isAbsolute(dir)) {
+		throw new Error(
+			`the session file ${path} or its directory ${dir} is not an absolute path, so delegation ${record.id} is not resumable`,
+		);
+	}
+	const cwd = sessionHeaderCwd(path);
+	if (cwd === undefined) {
+		throw new Error(
+			`could not read a working directory from the header of ${path}, so delegation ${record.id} is not resumable`,
+		);
+	}
+	if (!isDirectory(cwd)) {
+		throw new Error(
+			`delegation ${record.id}'s session runs in ${cwd}, which no longer exists, so it is not resumable (a removed worktree cannot be resumed)`,
+		);
+	}
+	return { path, cwd, dir };
+}
+
+/** The model choices: an explicit model alone, else where the delegate ended, then the agent's fallbacks. */
+export function preferredModels(record: StartedRecorded, agent: Agent, sessionPath: string): string[] {
+	const ended = finishedModel(sessionPath) ?? record.result?.finishedModel ?? record.model;
+	return [...new Set([ended, ...agent.fallback])];
+}
+
+/** Steps 5 and 6: the session file and the agent, and no resume of the delegation already under way. */
+export function recordCheck(
+	deps: ResumeDeps,
+	record: StartedRecorded,
+	ctx: ExtensionContext,
+): { session: SessionFile; agent: Agent } {
+	const session = sessionFor(record, ctx);
+	const agent = deps.roster(ctx).agents.find((item) => item.name === record.agent);
+	if (agent === undefined) {
+		throw new Error(
+			`agent ${JSON.stringify(record.agent)} is no longer in the roster, so delegation ${record.id} is not resumed`,
+		);
+	}
+	if (inFlight.has(record.id)) throw new Error(`delegation ${record.id} is already being resumed`);
+	return { session, agent };
+}
+
+/** The thinking level and model a resume runs with; throws when the level is invalid or no model can be used. */
+export async function settleModel(
+	deps: ResumeDeps,
+	input: {
+		record: StartedRecorded;
+		agent: Agent;
+		session: SessionFile;
+		request: Pick<ResumeRequest, "model" | "thinking">;
+	},
+	ctx: ExtensionContext,
+): Promise<{ thinking: string; chosen: Awaited<ReturnType<ResumeDeps["chooseModel"]>> }> {
+	const { record, agent, session, request } = input;
+	const thinking = request.thinking ?? record.thinking;
+	const badThinking = deps.thinkingProblem(thinking);
+	if (badThinking !== undefined) throw new Error(badThinking);
+	const preferred = preferredModels(record, agent, session.path);
+	return { thinking, chosen: await deps.chooseModel(request.model, agent, ctx.modelRegistry, preferred) };
+}
+
+/** The call-wide prerequisites of a resume: inside tmux, a new enough tmux, a valid placement setting (read once). */
+export async function preflight(deps: ResumeDeps): Promise<WindowPlacement> {
+	if (!deps.tmux.insideTmux()) throw new Error(deps.notInTmux);
+	await requireTmuxVersion(deps.tmux);
+	return deps.placement();
+}
+
+/** The delegation ids with a resume under way in this process. */
+export const inFlight = new Set<string>();
+
+/** Whether `record` passes every check a resume makes that changes nothing; the resume's own kill of an exited window and trust prompt are left to it. */
+export async function passes(
+	deps: ResumeDeps,
+	record: StartedRecorded,
+	windows: TmuxWindow[],
+	ctx: ExtensionContext,
+	models: Map<string, boolean>,
+): Promise<boolean> {
+	try {
+		windowCheck(record, windows);
+		const { session, agent } = recordCheck(deps, record, ctx);
+		// Model choice depends on the agent and where the delegate ended, so records alike share one answer.
+		const key = JSON.stringify([record.thinking, agent.name, preferredModels(record, agent, session.path)]);
+		let ok = models.get(key);
+		if (ok === undefined) {
+			ok = await settleModel(deps, { record, agent, session, request: {} }, ctx).then(
+				() => true,
+				() => false,
+			);
+			models.set(key, ok);
+		}
+		return ok;
+	} catch {
+		return false;
+	}
+}

package/src/resume-picker.ts

@@ -0,0 +1,50 @@
+// `/delegate-resume` with no arguments: pick one of the delegations a resume
+// would accept, write the follow-up in the multi-line editor, then resume it
+// the way the command does.
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { recordedName, type StartedRecorded } from "./results.ts";
+
+/** What the picker reads from the resume path in `index.ts`. */
+export type ResumePickerDeps = {
+	/** Why nothing can resume now (not inside tmux), or undefined. */
+	unavailable(): string | undefined;
+	/** The delegations a resume accepts now, newest first. */
+	eligible(ctx: ExtensionContext): Promise<StartedRecorded[]>;
+	/** Resume as the command does, notifying the start or the refusal. */
+	resume(request: { id: string; task: string }, ctx: ExtensionContext): Promise<void>;
+};
+
+/** One picker line; the id prefix keeps two delegations with one name apart. */
+const optionFor = (record: StartedRecorded): string =>
+	`${recordedName(record)} · ${record.agent} · ${record.id.slice(0, 8)}`;
+
+export async function pickResume(ctx: ExtensionContext, deps: ResumePickerDeps): Promise<void> {
+	const unavailable = deps.unavailable();
+	if (unavailable !== undefined) {
+		ctx.ui.notify(`delegate: ${unavailable}`, "error");
+		return;
+	}
+	let records: StartedRecorded[];
+	try {
+		records = await deps.eligible(ctx);
+	} catch (err) {
+		ctx.ui.notify(`delegate: ${(err as Error).message}`, "error");
+		return;
+	}
+	if (records.length === 0) {
+		ctx.ui.notify("delegate: no delegation can be resumed now", "info");
+		return;
+	}
+	const options = records.map(optionFor);
+	const picked = await ctx.ui.select("Resume which delegation?", options);
+	const record = records[options.indexOf(picked ?? "")];
+	if (record === undefined) return;
+	const task = await ctx.ui.editor(`Follow-up for ${recordedName(record)}`);
+	if (task === undefined) return;
+	if (task.trim() === "") {
+		ctx.ui.notify("delegate: a task is required", "error");
+		return;
+	}
+	await deps.resume({ id: record.id, task }, ctx);
+}

package/src/resume.ts

@@ -5,25 +5,25 @@
 // `index.ts` supplies the pieces it shares with a launch: model choice, trust,
 // the task mail and the window.
 import { randomUUID } from "node:crypto";
-import { statSync } from "node:fs";
-import { isAbsolute } from "node:path";
 
 import type { ExtensionContext, ModelRegistry } from "@earendil-works/pi-coding-agent";
 import { type TObject, Type } from "typebox";
 
 import { type Agent, type Roster, THINKING_LEVELS } from "./agents.ts";
-import { sessionHeaderCwd, sessionIdOf } from "./result-sessions.ts";
+import { sessionIdOf } from "./result-sessions.ts";
+import { isStarted, type Results, recordedName, type StartedRecorded } from "./results.ts";
 import {
-	deriveState,
-	finishedModel,
-	isStarted,
-	locateSession,
-	type Results,
-	recordedName,
-	type StartedRecorded,
-} from "./results.ts";
-import type { TmuxClient } from "./tmux.ts";
-import { listWindows, ownWindow, type ToolDef, toolResult, windowState } from "./tracking.ts";
+	inFlight,
+	passes,
+	preflight,
+	recordCheck,
+	type SessionFile,
+	settleModel,
+	windowCheck,
+} from "./resume-checks.ts";
+import type { OpenedWindow, TmuxClient } from "./tmux.ts";
+import { listWindows, type ToolDef, toolResult } from "./tracking.ts";
+import type { WindowPlacement } from "./window-placement.ts";
 import type { Workspace } from "./workspace.ts";
 
 /** What a resume asks for; the fields after `task` are optional overrides. */
@@ -49,6 +49,8 @@ export type ResumeDeps = {
 	/** The refusal text for a session outside tmux. */
 	notInTmux: string;
 	startPolling(): void;
+	/** The window placement for this call; throws on an invalid setting. */
+	placement(): WindowPlacement;
 	roster(ctx: ExtensionContext): Roster;
 	chooseModel(
 		explicit: string | undefined,
@@ -65,7 +67,7 @@ export type ResumeDeps = {
 	): Promise<{ workspace: Workspace; trusted: boolean }>;
 	/** Mail the task to a session id; returns the request id. */
 	sendTask(to: string, task: string): string;
-	/** Open the window with `--session <path>`; returns its id. */
+	/** Open the window with `--session <path>`; returns its id and session. */
 	open(input: {
 		id: string;
 		name: string;
@@ -77,7 +79,8 @@ export type ResumeDeps = {
 		start: { agent: Agent; model: string; rest: string[]; thinking: string; autoExit: boolean };
 		toolCallId: string | undefined;
 		ctx: ExtensionContext;
-	}): Promise<string>;
+		placement: WindowPlacement;
+	}): Promise<OpenedWindow>;
 };
 
 /** A started resume: what the tool and the command report. */
@@ -92,6 +95,8 @@ export type Resumed = {
 	autoExit: boolean;
 	windowId: string;
 	windowName: string;
+	/** The session the window opened in, when tmux could say. */
+	windowSession?: string;
 	cwd: string;
 	sessionDir: string;
 	workspace: Workspace;
@@ -136,28 +141,10 @@ function newestStarted(results: Results, id: string): StartedRecorded {
 	return record;
 }
 
-/**
- * Steps 3 and 4: no process of this delegate is left. A running delegate is
- * mailed instead; tmux that cannot be asked proves nothing; a window with the
- * record's id and name that still runs its program is refused, and one whose
- * program exited is killed first.
- */
+/** Steps 3 and 4, then the kill of an exited window; `windowCheck` is the part the picker shares. */
 async function ensureExited(record: StartedRecorded, tmux: TmuxClient): Promise<void> {
-	const windows = await listWindows(tmux);
-	const state = deriveState(record, windowState(windows, record));
-	if (state === "running") {
-		throw new Error(`delegation ${record.id} is running; send it a message instead of resuming it`);
-	}
-	if (windows === undefined || state === "unknown") {
-		throw new Error(`could not ask tmux whether delegation ${record.id}'s window is open, so it is not resumed`);
-	}
-	const own = ownWindow(windows, record);
+	const own = windowCheck(record, await listWindows(tmux));
 	if (own === undefined) return;
-	if (!own.exited) {
-		throw new Error(
-			`delegation ${record.id}'s window ${record.windowName} (${record.windowId}) is still open; its Pi may still be running, so it is not resumed. Close it with delegation_close, or send it a message`,
-		);
-	}
 	try {
 		await tmux.kill(own.id);
 	} catch (err) {
@@ -167,52 +154,6 @@ async function ensureExited(record: StartedRecorded, tmux: TmuxClient): Promise<
 	}
 }
 
-/** Whether `path` is an existing directory. */
-function isDirectory(path: string): boolean {
-	try {
-		return statSync(path).isDirectory();
-	} catch {
-		return false;
-	}
-}
-
-/** A delegate's session file, the directory its header says Pi runs it in, and the session directory to pass. */
-type SessionFile = { path: string; cwd: string; dir: string };
-
-/** Step 5: the session file, and the directory its header says Pi will run it in. */
-function sessionFor(record: StartedRecorded, ctx: ExtensionContext): SessionFile {
-	const dir = record.sessionDir ?? ctx.sessionManager.getSessionDir();
-	const path = locateSession(record, ctx.sessionManager.getSessionDir());
-	if (path === undefined) {
-		throw new Error(
-			`no session file for session ${sessionIdOf(record)} was found in ${dir}, so delegation ${record.id} is not resumable`,
-		);
-	}
-	if (!isAbsolute(path) || !isAbsolute(dir)) {
-		throw new Error(
-			`the session file ${path} or its directory ${dir} is not an absolute path, so delegation ${record.id} is not resumable`,
-		);
-	}
-	const cwd = sessionHeaderCwd(path);
-	if (cwd === undefined) {
-		throw new Error(
-			`could not read a working directory from the header of ${path}, so delegation ${record.id} is not resumable`,
-		);
-	}
-	if (!isDirectory(cwd)) {
-		throw new Error(
-			`delegation ${record.id}'s session runs in ${cwd}, which no longer exists, so it is not resumable (a removed worktree cannot be resumed)`,
-		);
-	}
-	return { path, cwd, dir };
-}
-
-/** The model choices: an explicit model alone, else where the delegate ended, then the agent's fallbacks. */
-function preferredModels(record: StartedRecorded, agent: Agent, sessionPath: string): string[] {
-	const ended = finishedModel(sessionPath) ?? record.result?.finishedModel ?? record.model;
-	return [...new Set([ended, ...agent.fallback])];
-}
-
 /** The tool's result: the `delegate` tool's plus the delegation it resumed. */
 function resultSchema(delegateSchema: TObject): TObject {
 	return Type.Object({
@@ -237,11 +178,7 @@ async function planResume(
 	signal: AbortSignal | undefined,
 ): Promise<Plan> {
 	const { record, agent, session, request } = input;
-	const thinking = request.thinking ?? record.thinking;
-	const badThinking = deps.thinkingProblem(thinking);
-	if (badThinking !== undefined) throw new Error(badThinking);
-	const preferred = preferredModels(record, agent, session.path);
-	const chosen = await deps.chooseModel(request.model, agent, ctx.modelRegistry, preferred);
+	const { thinking, chosen } = await settleModel(deps, input, ctx);
 	const autoExit = request.autoExit ?? record.autoExit === true;
 	const prepared = await deps.prepareDirectory(session.cwd, ctx, signal);
 	// A managed worktree keeps its launch facts while the session still runs in it.
@@ -273,15 +210,22 @@ async function mailTask(deps: ResumeDeps, windowId: string, sessionId: string, t
 
 async function startResume(
 	deps: ResumeDeps,
-	input: { record: StartedRecorded; session: SessionFile; plan: Plan; task: string; toolCallId: string | undefined },
+	input: {
+		record: StartedRecorded;
+		session: SessionFile;
+		plan: Plan;
+		task: string;
+		toolCallId: string | undefined;
+		placement: WindowPlacement;
+	},
 	ctx: ExtensionContext,
 ): Promise<Resumed> {
-	const { record, session, plan, task, toolCallId } = input;
+	const { record, session, plan, task, toolCallId, placement } = input;
 	const { start, chosen, workspace } = plan;
 	const id = randomUUID();
 	const sessionId = sessionIdOf(record);
 	const name = recordedName(record);
-	const windowId = await deps.open({
+	const { id: windowId, session: windowSession } = await deps.open({
 		id,
 		name,
 		sessionPath: session.path,
@@ -292,6 +236,7 @@ async function startResume(
 		start,
 		toolCallId,
 		ctx,
+		placement,
 	});
 	const requestId = await mailTask(deps, windowId, sessionId, task);
 	deps.results.recordStart(
@@ -325,6 +270,7 @@ async function startResume(
 		autoExit: start.autoExit,
 		windowId,
 		windowName: name,
+		...(windowSession === undefined ? {} : { windowSession }),
 		cwd: workspace.cwd,
 		sessionDir: session.dir,
 		workspace,
@@ -335,9 +281,6 @@ async function startResume(
 	};
 }
 
-/** The delegation ids with a resume under way in this process. */
-const inFlight = new Set<string>();
-
 /** Resume `request.id`: every eligibility check in order, then the launch. */
 async function resume(
 	deps: ResumeDeps,
@@ -345,30 +288,49 @@ async function resume(
 	ctx: ExtensionContext,
 	signal: AbortSignal | undefined,
 ): Promise<Resumed> {
-	if (!deps.tmux.insideTmux()) throw new Error(deps.notInTmux);
+	const placement = await preflight(deps); // read once, before the exited window is killed or anything is mailed
 	if (request.task.trim() === "") throw new Error("a task is required");
 	const record = newestStarted(deps.results, request.id);
 	await ensureExited(record, deps.tmux);
-	const session = sessionFor(record, ctx);
-	const agent = deps.roster(ctx).agents.find((item) => item.name === record.agent);
-	if (agent === undefined) {
-		throw new Error(
-			`agent ${JSON.stringify(record.agent)} is no longer in the roster, so delegation ${record.id} is not resumed`,
-		);
-	}
-	if (inFlight.has(record.id)) throw new Error(`delegation ${record.id} is already being resumed`);
+	const { session, agent } = recordCheck(deps, record, ctx);
 	inFlight.add(record.id);
 	try {
 		const plan = await planResume(deps, { record, agent, session, request }, ctx, signal);
-		return await startResume(deps, { record, session, plan, task: request.task, toolCallId: request.toolCallId }, ctx);
+		return await startResume(
+			deps,
+			{ record, session, plan, task: request.task, toolCallId: request.toolCallId, placement },
+			ctx,
+		);
 	} finally {
 		inFlight.delete(record.id);
 	}
 }
 
+/**
+ * The delegations that pass every check `resume` makes, newest first, read
+ * with one `listWindows` and changing nothing: an exited window is left for
+ * the resume itself to kill and trust is left for its prompt. The call-wide
+ * prerequisites are checked once and refuse as `resume` does.
+ */
+async function eligible(deps: ResumeDeps, ctx: ExtensionContext): Promise<StartedRecorded[]> {
+	await preflight(deps);
+	const windows = await listWindows(deps.tmux);
+	if (windows === undefined) return [];
+	const ids = new Set(resumableIds(deps.results));
+	const models = new Map<string, boolean>();
+	const found: StartedRecorded[] = [];
+	for (const record of startedRecords(deps.results)) {
+		if (ids.has(record.id) && (await passes(deps, record, windows, ctx, models))) found.push(record);
+	}
+	return found.reverse();
+}
+
+/** The session a window opened in, for the start text. */
+const inSession = (session: string | undefined): string => (session === undefined ? "" : ` in session ${session}`);
+
 /** The one line the command and the tool tell the user. */
 export function startedLine(resumed: Resumed): string {
-	return `delegate: resumed ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} in window ${resumed.windowName}${resumed.fallbackNote === "" ? "" : `. ${resumed.fallbackNote}`}${resumed.notices.map((line) => `. ${line}`).join("")}`;
+	return `delegate: resumed ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} in window ${resumed.windowName}${inSession(resumed.windowSession)}${resumed.fallbackNote === "" ? "" : `. ${resumed.fallbackNote}`}${resumed.notices.map((line) => `. ${line}`).join("")}`;
 }
 
 /** The `delegation_resume` tool. */
@@ -410,7 +372,7 @@ function resumeTool(deps: ResumeDeps): ToolDef {
 			const { fallbackNote, ...details } = resumed;
 			ctx.ui.notify(startedLine(resumed), "info");
 			return toolResult(
-				`Resumed delegation ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} (${resumed.model}, thinking ${resumed.thinking}) in window ${resumed.windowName}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${fallbackNote === "" ? "" : ` ${fallbackNote}`}${resumed.notices.map((line) => ` ${line}`).join("")}`,
+				`Resumed delegation ${resumed.resumedFrom} as ${resumed.id}: ${resumed.agent} (${resumed.model}, thinking ${resumed.thinking}) in window ${resumed.windowName}${inSession(resumed.windowSession)}. It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${fallbackNote === "" ? "" : ` ${fallbackNote}`}${resumed.notices.map((line) => ` ${line}`).join("")}`,
 				{ outcome: "started", ...details },
 			);
 		},
@@ -439,9 +401,12 @@ function requestFrom(params: {
 /** Resuming as a function for the command, and the tool for the model. */
 export function createResume(deps: ResumeDeps): {
 	resume(request: ResumeRequest, ctx: ExtensionContext, signal?: AbortSignal): Promise<Resumed>;
+	/** The delegations a resume would accept now, newest first. */
+	eligible(ctx: ExtensionContext): Promise<StartedRecorded[]>;
 	tool(): ToolDef;
 } {
 	return {
+		eligible: (ctx: ExtensionContext) => eligible(deps, ctx),
 		resume: (request: ResumeRequest, ctx: ExtensionContext, signal?: AbortSignal) => resume(deps, request, ctx, signal),
 		tool: () => resumeTool(deps),
 	};