pi-squire 0.10.0 → 0.12.0

package/src/index.ts

@@ -21,7 +21,7 @@
 // session has no tool for leaves the agent out of the roster. Its `tools` goes
 // as `--tools` and each of its `extensions` as `-e`, both for the child alone.
 //
-// The model gets three tools. `delegate` takes agent, task and optional model
+// The model gets four tools. `delegate` takes agent, task and optional model
 // and thinking, validates them the way the command does, and starts the
 // delegation at once, opening no dialog, so parallel calls cannot block one
 // another; the one exception is a `cwd` whose project trust is unresolved,
@@ -29,7 +29,9 @@
 // reports each delegation as running (window open, no result yet), done (with
 // its result status) or closed, with the session name, window, session and
 // envelope paths.
-// `delegation_close` kills the window and records the close. Inside a delegate
+// `delegation_close` kills the window and records the close. `delegation_resume`
+// (`resume.ts`) reopens an exited delegate's session in a new window with a
+// follow-up task, recorded as a new delegation. Inside a delegate
 // (`PI_DELEGATE_PARENT` set) the extension registers only `child.ts`'s
 // `/auto-exit` and handlers, so a delegate cannot delegate.
 //
@@ -53,9 +55,11 @@ import { AGENT_ENV, AUTO_EXIT_ENV, FALLBACK_ENV, registerChild } from "./child.t
 import { activeMark, clearMarks, isFree, readMarks } from "./limits.ts";
 import { dirtyNotice, renderDelegateCall, renderDelegateResult, resourceLine } from "./render.ts";
 import { createResults, delegateName, type WorkspaceAttempt } from "./results.ts";
-import { createTmuxClient, type TmuxClient, WindowOpenError } from "./tmux.ts";
+import { createResume, type ResumeRequest, resumableIds, startedLine } from "./resume.ts";
+import { createTmuxClient, type OpenedWindow, requireTmuxVersion, type TmuxClient, WindowOpenError } from "./tmux.ts";
 import { createTracking, toolResult } from "./tracking.ts";
 import { createProactive, createUsageClient, type Proactive, type UsageClient } from "./usage.ts";
+import { type WindowPlacement, windowPlacement } from "./window-placement.ts";
 import {
 	normalizeWorkspaceValue,
 	prepareDirectory,
@@ -146,6 +150,9 @@ export const DelegateSchema = Type.Object({
 	autoExit: Type.Boolean(),
 	windowId: Type.String(),
 	windowName: Type.String(),
+	windowSession: Type.Optional(
+		Type.String({ description: "The tmux session the window opened in, as tmux named it then." }),
+	),
 	cwd: Type.String({ description: "The directory the delegate's window opened in." }),
 	sessionDir: Type.String({ description: "The session-storage directory the delegate was told to use." }),
 	workspace: WorkspaceSchema,
@@ -156,9 +163,20 @@ const NOT_IN_TMUX = "this session is not inside tmux; start it in a tmux pane to
 const USAGE =
 	"usage: /delegate <agent> [--model <provider/id>] [--thinking <level>] [--label <name>] [--cwd <dir> | --worktree <branch> [--worktree-source <dir>] [--worktree-base <commit-ish>] ] [--auto-exit | --no-auto-exit] <task>";
 
+/** The flags `/delegate-resume` takes before the task. */
+const RESUME_FLAGS = ["--model", "--thinking", "--auto-exit", "--no-auto-exit"] as const;
+const RESUME_USAGE =
+	"usage: /delegate-resume <id> [--model <provider/id>] [--thinking <level>] [--auto-exit | --no-auto-exit] <task>";
+
 type SendPayload = { to: unknown; body: unknown; envelope?: { id?: unknown }; error?: unknown };
 /** `cwd` is informational: the window opens in the launch's own value, whatever a listener assigns. */
-type LaunchPayload = { args: string[]; env: Record<string, string>; agent: string; readonly cwd: string };
+type LaunchPayload = {
+	args: string[];
+	env: Record<string, string>;
+	agent: string;
+	readonly cwd: string;
+	readonly toolCallId: string | undefined;
+};
 type Parsed = {
 	agent: string;
 	model?: string;
@@ -194,12 +212,16 @@ type Start = {
 };
 /** A candidate model passed over: `why` finishes "<model> is …", `reason` is the long form for a refusal. */
 type Skipped = { model: string; why: string; reason: string };
+/** What opening a delegate's window reads from a request: a `Start`, or the parts of one a resume decides. */
+type ChildStart = Pick<Start, "agent" | "model" | "rest" | "thinking" | "autoExit">;
 /** A delegation that is open in a tmux window. */
 type Launched = {
 	id: string;
 	name: string;
 	windowId: string;
 	windowName: string;
+	/** The session the window opened in; undefined when tmux could not say. */
+	windowSession: string | undefined;
 	requestId: string;
 	cwd: string;
 	sessionDir: string;
@@ -276,9 +298,14 @@ function word(text: string, from: number): { text: string; start: number; end: n
  * A flag's value at or after `from`: a plain word, or a double-quoted string
  * in which `\"` and `\\` stand for `"` and `\`. No shell expansion of any kind.
  */
-function flagValue(text: string, from: number, flag: string): { value: string; end: number } | { error: string } {
+function flagValue(
+	text: string,
+	from: number,
+	flag: string,
+	usage: string = USAGE,
+): { value: string; end: number } | { error: string } {
 	const next = word(text, from);
-	if (next === undefined || next.text.startsWith("--")) return { error: `${flag} needs a value; ${USAGE}` };
+	if (next === undefined || next.text.startsWith("--")) return { error: `${flag} needs a value; ${usage}` };
 	if (!next.text.startsWith('"')) return { value: next.text, end: next.end };
 	let value = "";
 	let i = next.start + 1;
@@ -287,9 +314,9 @@ function flagValue(text: string, from: number, flag: string): { value: string; e
 		value += escaped ? text[i + 1] : text[i];
 		i += escaped ? 2 : 1;
 	}
-	if (i >= text.length) return { error: `${flag}'s value has no closing quote; ${USAGE}` };
+	if (i >= text.length) return { error: `${flag}'s value has no closing quote; ${usage}` };
 	if (i + 1 < text.length && !/\s/.test(text[i + 1])) {
-		return { error: `${flag}'s quoted value must be followed by a space; ${USAGE}` };
+		return { error: `${flag}'s quoted value must be followed by a space; ${usage}` };
 	}
 	return { value, end: i + 1 };
 }
@@ -336,6 +363,32 @@ function parse(text: string): { parsed: Parsed } | { error: string } {
 	return { parsed };
 }
 
+/** `/delegate-resume`'s arguments: a delegation id, optional flags, then a verbatim task. */
+function parseResume(text: string): { request: ResumeRequest } | { error: string } {
+	const id = word(text, 0);
+	if (id === undefined) return { error: RESUME_USAGE };
+	if (id.text.startsWith("-")) return { error: `the first argument is the delegation id; ${RESUME_USAGE}` };
+	const request: ResumeRequest = { id: id.text, task: "" };
+	let at = id.end;
+	for (let next = word(text, at); next?.text.startsWith("-"); next = word(text, at)) {
+		const flag = next.text;
+		if (flag === "--auto-exit" || flag === "--no-auto-exit") {
+			request.autoExit = flag === "--auto-exit";
+			at = next.end;
+			continue;
+		}
+		if (flag !== "--model" && flag !== "--thinking") return { error: `unknown flag ${flag}; ${RESUME_USAGE}` };
+		const read = flagValue(text, next.end, flag, RESUME_USAGE);
+		if ("error" in read) return read;
+		if (flag === "--model") request.model = read.value;
+		else request.thinking = read.value;
+		at = read.end;
+	}
+	request.task = text.slice(word(text, at)?.start ?? text.length).trim();
+	if (request.task === "") return { error: `a task is required after the id and flags; ${RESUME_USAGE}` };
+	return { request };
+}
+
 /** Why `value` is not a usable model, or undefined when it is. */
 function modelProblem(value: string, registry: ModelRegistry): string | undefined {
 	const slash = value.indexOf("/");
@@ -356,15 +409,17 @@ function modelProblem(value: string, registry: ModelRegistry): string | undefine
  * `modelProblem` and has no active mark wins; the rest are returned as skipped.
  * A paid candidate on a provider with a quota check is read first, and
  * skipped when its quota is used up. Refuses, listing every candidate, when
- * none is left.
+ * none is left. `preferred` replaces the agent's own list when there is no
+ * explicit model, as a resume does.
  */
 async function chooseModel(
 	explicit: string | undefined,
 	agent: Agent,
 	models: ModelRegistry,
 	proactive: Proactive,
+	preferred: readonly string[] = [agent.model, ...agent.fallback],
 ): Promise<{ model: string; skipped: Skipped[]; notices: string[]; rest: string[] }> {
-	const candidates = explicit !== undefined ? [explicit] : [agent.model, ...agent.fallback];
+	const candidates = explicit !== undefined ? [explicit] : [...preferred];
 	const skipped: Skipped[] = [];
 	const notices: string[] = [];
 	for (const model of candidates) {
@@ -475,7 +530,7 @@ function toolDescription(agents: readonly Agent[]): string {
 		),
 		"",
 		"`cwd` runs the delegate in another existing directory. Alternatively, `worktree` creates a new local branch and checkout from this repository's committed HEAD, or `worktree_source` selects another existing Git checkout; `worktree_base` selects a commit in that source. Source dirt is reported but not copied. `cwd` and `worktree` are mutually exclusive, and source/base require worktree.",
-		"`model` and `thinking` override the agent's defaults for this call; an unknown value is refused with close matches. `label` names the delegate's window and session; give one that says what the task is. `delegation_status` reports a delegation, and `delegation_close` ends one.",
+		"`model` and `thinking` override the agent's defaults for this call; an unknown value is refused with close matches. `label` names the delegate's window and session; give one that says what the task is. `delegation_status` reports a delegation, and `delegation_close` ends one. `delegation_resume` continues an exited delegate in its own session with a follow-up task, for work that needs the context it already built.",
 		"`auto_exit` (default the agent's, normally true) closes the delegate's window once it finishes. Set it false when you mean to keep talking to the delegate by mail after its result; the user can also keep a window open by typing in it.",
 		"",
 		"Writing the task: the delegate sees nothing of this session, so the task must stand alone. State the question, the decision its answer feeds, what is already known or ruled out, and the files or paths to start from. When the work produces a report, name the path to write it to and ask for the conclusion back, not the contents.",
@@ -575,20 +630,57 @@ export default function delegate(
 		};
 	}
 
-	async function launchWindow(input: {
+	/** Write the task to the delegate's inbox and return its request id; the delegate finds it at session start. */
+	function sendTask(to: string, task: string): string {
+		const sent: SendPayload = { to, body: task };
+		pi.events.emit(SEND, sent);
+		if (typeof sent.error === "string") throw new Error(`could not send the task to ${to}: ${sent.error}`);
+		if (sent.envelope === undefined)
+			throw new Error(
+				"needs a provider of message:* to send the task; install a mailbox extension (for example pi-session-mail)",
+			);
+		const requestId = sent.envelope.id;
+		if (typeof requestId !== "string") throw new Error(`the message:send provider wrote no request id for ${to}`);
+		return requestId;
+	}
+
+	/**
+	 * Build the delegate's command line and environment, emit `session:launch`
+	 * and open its window; returns the window id and session. A launch and a resume share
+	 * it and differ only in `session`, the arguments that choose the session:
+	 * `--session-id <id> --name <name>` for a new one, `--session <path>` to reopen.
+	 */
+	async function openChild(input: {
 		id: string;
-		requestId: string;
+		name: string;
+		session: string[];
 		workspace: Workspace;
 		trusted: boolean;
 		cwd: string;
 		sessionDir: string;
-		start: Start;
+		start: ChildStart;
+		/** The tool call that started this launch or resume; undefined from a command. */
+		toolCallId: string | undefined;
 		ctx: ExtensionContext;
-		onWindowOpened: () => void;
-	}): Promise<Launched> {
-		const { id, requestId, workspace, trusted, cwd, sessionDir, start, ctx, onWindowOpened } = input;
+		/** Chosen once, when the launch or resume began, so no later settings change can refuse it after mail. */
+		placement: WindowPlacement;
+		onWindowOpened?: () => void;
+	}): Promise<OpenedWindow> {
+		const {
+			id,
+			name,
+			session,
+			workspace,
+			trusted,
+			cwd,
+			sessionDir,
+			start,
+			toolCallId,
+			ctx,
+			placement,
+			onWindowOpened,
+		} = input;
 		const parent = ctx.sessionManager.getSessionId();
-		const name = delegateName(start.agent.name, id, start.label);
 		const managedContext =
 			workspace.mode === "managed"
 				? `\n\nYour managed worktree is ${workspace.cwd}, branch ${workspace.createdBranch}, based on commit ${workspace.baseCommit}.`
@@ -598,10 +690,7 @@ export default function delegate(
 		const prompt = writePromptFile(`${start.agent.prompt}\n\n${FINAL_LINE}\n\n${parentTrust(parent)}${managedContext}`);
 		const argv = [
 			...parentCommand(),
-			"--session-id",
-			id,
-			"--name",
-			name,
+			...session,
 			// Always explicit, so a permissive global default cannot trust what the parent does not.
 			trusted ? "--approve" : "--no-approve",
 			"--session-dir",
@@ -629,18 +718,51 @@ export default function delegate(
 		const envSessionDir = process.env[SESSION_DIR_ENV];
 		if (envSessionDir !== undefined && envSessionDir !== "") env[SESSION_DIR_ENV] = envSessionDir;
 		// Listeners may only append to `args` and add to `env`; there is no veto.
-		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name, cwd };
+		const payload: LaunchPayload = { args: argv, env, agent: start.agent.name, cwd, toolCallId };
 		pi.events.emit(LAUNCH, payload);
-		let windowId: string;
+		let opened: OpenedWindow;
 		try {
-			windowId = await tmux.openWindow({ name, cwd, argv: payload.args, env: payload.env });
-			onWindowOpened();
+			opened = await tmux.openWindow({ name, cwd, argv: payload.args, env: payload.env }, placement);
+			onWindowOpened?.();
 		} catch (err) {
 			if (err instanceof WindowOpenError) {
 				throw new WindowOpenError(`could not open window ${name} for ${id}: ${err.message}`, err.certainty);
 			}
 			throw new WindowOpenError(`could not open window ${name} for ${id}: ${(err as Error).message}`, "unknown");
 		}
+		return opened;
+	}
+
+	async function launchWindow(input: {
+		id: string;
+		requestId: string;
+		workspace: Workspace;
+		trusted: boolean;
+		cwd: string;
+		sessionDir: string;
+		start: Start;
+		toolCallId: string | undefined;
+		ctx: ExtensionContext;
+		placement: WindowPlacement;
+		onWindowOpened: () => void;
+	}): Promise<Launched> {
+		const { id, requestId, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, placement, onWindowOpened } =
+			input;
+		const name = delegateName(start.agent.name, id, start.label);
+		const { id: windowId, session: windowSession } = await openChild({
+			id,
+			name,
+			session: ["--session-id", id, "--name", name],
+			workspace,
+			trusted,
+			cwd,
+			sessionDir,
+			start,
+			toolCallId,
+			ctx,
+			placement,
+			onWindowOpened,
+		});
 		// No task text in the record: the request copy in `sent/` has it.
 		results.recordStart(
 			{
@@ -660,11 +782,19 @@ export default function delegate(
 			ctx,
 		);
 		tracking.startPolling();
-		return { id, name, windowId, windowName: name, requestId, cwd, sessionDir, workspace };
+		return { id, name, windowId, windowName: name, windowSession, requestId, cwd, sessionDir, workspace };
 	}
 
-	async function launch(start: Start, ctx: ExtensionContext, signal?: AbortSignal): Promise<Launched> {
+	async function launch(
+		start: Start,
+		ctx: ExtensionContext,
+		signal?: AbortSignal,
+		toolCallId?: string,
+	): Promise<Launched> {
 		if (!tmux.insideTmux()) throw new Error(NOT_IN_TMUX);
+		await requireTmuxVersion(tmux);
+		// Read once, before anything is created or mailed; the launch keeps this value.
+		const placement = windowPlacement(getAgentDir());
 		const sessionDir = ctx.sessionManager.getSessionDir();
 		if (!isAbsolute(sessionDir))
 			throw new Error(
@@ -760,15 +890,7 @@ export default function delegate(
 			// The task goes on disk before the window exists: the delegate finds it
 			// at session start without a handshake, and a window that fails leaves
 			// mail that is reported rather than cleaned up.
-			const sent: SendPayload = { to: id, body: start.task };
-			pi.events.emit(SEND, sent);
-			if (typeof sent.error === "string") throw new Error(`could not send the task to ${id}: ${sent.error}`);
-			if (sent.envelope === undefined)
-				throw new Error(
-					"needs a provider of message:* to send the task; install a mailbox extension (for example pi-session-mail)",
-				);
-			const requestId = sent.envelope.id;
-			if (typeof requestId !== "string") throw new Error(`the message:send provider wrote no request id for ${id}`);
+			const requestId = sendTask(id, start.task);
 			if (attempt !== undefined) {
 				attempt = { ...attempt, requestId };
 				results.recordAttempt(attempt, ctx);
@@ -781,7 +903,9 @@ export default function delegate(
 				cwd: workspace.cwd,
 				sessionDir,
 				start,
+				toolCallId,
 				ctx,
+				placement,
 				onWindowOpened: () => {
 					windowOpened = true;
 				},
@@ -847,12 +971,43 @@ export default function delegate(
 		return inQueue(plan.source.commonDir, combined, runWithRollback);
 	}
 
+	const resumer = createResume({
+		results,
+		tmux,
+		delegateSchema: DelegateSchema,
+		notInTmux: NOT_IN_TMUX,
+		startPolling: tracking.startPolling,
+		placement: () => windowPlacement(getAgentDir()),
+		roster: rosterFor,
+		chooseModel: (explicit, agent, models, preferred) => chooseModel(explicit, agent, models, proactive, preferred),
+		thinkingProblem,
+		prepareDirectory: (cwd, ctx, signal) => prepareDirectory({ cwd, signal }, ctx, getAgentDir()),
+		sendTask,
+		open: ({ id, name, sessionPath, workspace, trusted, cwd, sessionDir, start, toolCallId, ctx, placement }) =>
+			openChild({
+				id,
+				name,
+				session: ["--session", sessionPath],
+				workspace,
+				trusted,
+				cwd,
+				sessionDir,
+				start,
+				toolCallId,
+				ctx,
+				placement,
+			}),
+	});
+
+	/** The session a window opened in, for the start text. */
+	const inSession = (session: string | undefined): string => (session === undefined ? "" : ` in session ${session}`);
+
 	/** Where a selected directory put the delegate, for the start text; inherited starts stay compact. */
 	const placedIn = (launched: Launched): string =>
 		launched.workspace.mode !== "inherited" ? ` in ${launched.cwd}` : "";
 
 	const started = (launched: Launched, start: Start): string =>
-		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
+		`delegate: ${start.agent.name} ${launched.id} started in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}${launched.workspace.mode === "managed" ? `. Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""}${start.skipped.length > 0 ? `. ${fallbackNote(start)}` : ""}${start.notices.map((line) => `. ${line}`).join("")}`;
 
 	async function command(input: string, ctx: ExtensionContext): Promise<void> {
 		const fail = (message: string) => ctx.ui.notify(`delegate: ${message}`, "error");
@@ -880,6 +1035,19 @@ export default function delegate(
 		}
 	}
 
+	async function resumeCommand(input: string, ctx: ExtensionContext): Promise<void> {
+		const outcome = parseResume(input);
+		if ("error" in outcome) {
+			ctx.ui.notify(`delegate: ${outcome.error}`, "error");
+			return;
+		}
+		try {
+			ctx.ui.notify(startedLine(await resumer.resume(outcome.request, ctx)), "info");
+		} catch (err) {
+			ctx.ui.notify(`delegate: ${(err as Error).message}`, "error");
+		}
+	}
+
 	/** The roster description last registered, so unchanged metadata is not registered again. */
 	let registeredDescription: string | undefined;
 
@@ -937,7 +1105,7 @@ export default function delegate(
 		// Opens a new window each call and removes nothing. Open world: the delegate calls a remote model and runs its agent's tools unattended.
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 		async execute(
-			_toolCallId: string,
+			toolCallId: string,
 			params: {
 				agent: string;
 				task: string;
@@ -977,10 +1145,10 @@ export default function delegate(
 				rosterFor(ctx),
 				ctx.modelRegistry,
 			);
-			const launched = await launch(start, ctx, signal);
+			const launched = await launch(start, ctx, signal, toolCallId);
 			ctx.ui.notify(started(launched, start), "info");
 			return toolResult(
-				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}${placedIn(launched)}.${launched.workspace.mode === "managed" ? ` Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""} It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
+				`Started delegation ${launched.id}: ${start.agent.name} (${start.model}, thinking ${start.thinking}) in window ${launched.windowName}${inSession(launched.windowSession)}${placedIn(launched)}.${launched.workspace.mode === "managed" ? ` Branch ${launched.workspace.createdBranch} starts at ${launched.workspace.baseCommit}. ${dirtyNotice(launched.workspace.sourceDirty)}` : ""} It runs in the background, and its result arrives as a message that starts your next turn on its own; delegation_close ends it.${start.skipped.length > 0 ? ` ${fallbackNote(start)}` : ""}${start.notices.map((line) => ` ${line}`).join("")}`,
 				{
 					outcome: "started",
 					id: launched.id,
@@ -992,6 +1160,7 @@ export default function delegate(
 					autoExit: start.autoExit,
 					windowId: launched.windowId,
 					windowName: launched.windowName,
+					...(launched.windowSession === undefined ? {} : { windowSession: launched.windowSession }),
 					cwd: launched.cwd,
 					sessionDir: launched.sessionDir,
 					workspace: launched.workspace,
@@ -1054,6 +1223,26 @@ export default function delegate(
 		handler: command,
 	});
 
+	/** Delegation ids, flags, model ids and thinking levels, at the cursor's token. */
+	function resumeCompletions(prefix: string): { value: string; label: string }[] | null {
+		const partial = /(?:^|\s)(\S*)$/.exec(prefix)?.[1] ?? "";
+		const head = prefix.slice(0, prefix.length - partial.length);
+		const tokens = head.trim() === "" ? [] : head.trim().split(/\s+/);
+		const previous = tokens[tokens.length - 1];
+		let values: readonly string[] = RESUME_FLAGS;
+		if (tokens.length === 0) values = resumableIds(results);
+		else if (previous === "--model") values = modelIds(registry);
+		else if (previous === "--thinking") values = THINKING_LEVELS;
+		const hits = values.filter((value) => value.startsWith(partial));
+		return hits.length > 0 ? hits.map((value) => ({ value: head + value, label: value })) : null;
+	}
+
+	pi.registerCommand("delegate-resume", {
+		description: `Reopen an exited delegate's session in a new window with a follow-up task: ${RESUME_USAGE}`,
+		getArgumentCompletions: resumeCompletions,
+		handler: resumeCommand,
+	});
+
 	pi.registerCommand("delegate-clear", {
 		description: "Clear usage-limit marks: all, a provider, or a provider/model",
 		getArgumentCompletions: (prefix: string) => {
@@ -1084,4 +1273,5 @@ export default function delegate(
 
 	registerDelegate(toolDescription(currentRoster().agents));
 	tracking.registerTools();
+	pi.registerTool(resumer.tool() as never);
 }

package/src/render.ts

@@ -154,6 +154,7 @@ function plainLines(text: string): string[] {
 
 function idLines(details: MessageDetails): string[] {
 	const lines = [`delegation ${details.id}`, `request ${details.requestId}`];
+	if (details.resumedFrom !== undefined) lines.splice(1, 0, `resumed from ${details.resumedFrom}`);
 	if (details.kind === "result") lines.push(`envelope ${tilde(details.envelopePath)}`);
 	else lines.push(`window ${details.windowName}`);
 	lines.push(`cwd ${details.cwd === undefined ? cwdLine(undefined) : tilde(details.cwd)}`);
@@ -163,7 +164,7 @@ function idLines(details: MessageDetails): string[] {
 		lines.push(`checkout when the result arrived: ${first}`, ...rest.map((line) => `  ${line}`));
 	}
 	lines.push(
-		`session ${details.sessionPath === undefined ? `${details.id} (no session file found)` : tilde(details.sessionPath)}`,
+		`session ${details.sessionPath === undefined ? `${details.sessionId ?? details.id} (no session file found)` : tilde(details.sessionPath)}`,
 	);
 	return lines;
 }
@@ -281,7 +282,7 @@ export function renderDelegateResult(
 	const lines = [
 		`${theme.fg("accent", "●")} ${theme.fg("toolTitle", theme.bold(started.windowName))}${theme.fg(
 			"dim",
-			` (${started.model}) — started`,
+			`${started.windowSession === undefined ? "" : ` in session ${started.windowSession}`} (${started.model}) — started`,
 		)}`,
 	];
 	const task = taskLine(context.args.task, theme);
@@ -292,7 +293,7 @@ export function renderDelegateResult(
 			...[
 				...started.notices,
 				`delegation ${started.id}`,
-				`window ${started.windowName} (${started.windowId})`,
+				`window ${started.windowName} (${started.windowId})${started.windowSession === undefined ? "" : ` in session ${started.windowSession}`}`,
 				// Results saved before cwd was recorded have none.
 				`cwd ${(started.cwd as string | undefined) === undefined ? cwdLine(undefined) : tilde(started.cwd)}`,
 				// Results saved before workspaces were recorded have none.

package/src/result-message.ts

@@ -0,0 +1,120 @@
+// The text and details of the one message the parent receives for a settled delegation.
+import { readMarks } from "./limits.ts";
+import { cwdLine, modelLabel, snapshotLines, workspaceLine } from "./render.ts";
+import { sessionIdOf } from "./result-sessions.ts";
+import type { StartedRecorded } from "./result-types.ts";
+import type { Inbound, MessageDetails, TaskQuote } from "./results.ts";
+import type { WorkspaceSnapshot } from "./snapshot.ts";
+
+/** 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;
+
+type ResultDetails = Extract<MessageDetails, { kind: "result" }>;
+
+/** 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 line naming a usage-limit mark this delegation recorded, if any; a `done` delegation finished on a fallback. */
+function limitLine(sessionId: string, status: string): string | undefined {
+	const now = Date.now();
+	const mark = readMarks(now).find((item) => item.delegations.includes(sessionId));
+	if (mark === undefined) return undefined;
+	const scope = mark.scope.includes("/") ? `model ${mark.scope}` : `provider ${mark.scope}`;
+	const until = new Date(mark.clearsAt).toISOString();
+	return `Usage limit: the delegate hit a usage limit on ${scope}; ${
+		mark.clearsAt > now ? `it is marked until ${until} and later delegations skip it.` : `it was marked until ${until}.`
+	}${status === "done" ? " It finished on a fallback model; its session names which." : ""}`;
+}
+
+/** The details that say a delegation reopened an earlier one's session. */
+export function resumeDetails(record: StartedRecorded): { resumedFrom?: string; sessionId?: string } {
+	return {
+		...(record.resumedFrom === undefined ? {} : { resumedFrom: record.resumedFrom }),
+		...(record.sessionId === undefined ? {} : { sessionId: record.sessionId }),
+	};
+}
+
+/** The details of a settled delegation's result message. */
+export function resultDetails(
+	delegation: StartedRecorded,
+	name: string,
+	payload: Inbound,
+	session: string | undefined,
+	finished: string | undefined,
+	snapshot: WorkspaceSnapshot,
+): ResultDetails {
+	const reply = payload.envelope;
+	const copy = payload.requests.find((request) => request.envelope?.id === delegation.requestId);
+	let task: TaskQuote;
+	if (copy === undefined) {
+		task = { note: `[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 text =
+			cut === undefined ? copy.envelope.body : `${cut}\n[delegate] Task cut at 2 KiB; the full copy is ${copy.path}`;
+		task = { text, path: copy.path };
+	}
+	const cut = cap(reply.body, BODY_CAP);
+	const body =
+		cut === undefined ? reply.body : `${cut}\n[delegate] Body cut at 32 KiB; the full envelope is ${payload.path}`;
+	const limit = reply.status === "stopped" ? undefined : limitLine(sessionIdOf(delegation), reply.status);
+	return {
+		kind: "result",
+		status: reply.status,
+		name,
+		agent: delegation.agent,
+		model: delegation.model,
+		...(finished === undefined ? {} : { finishedModel: finished }),
+		id: delegation.id,
+		...resumeDetails(delegation),
+		requestId: delegation.requestId,
+		envelopePath: payload.path,
+		...(session === undefined ? {} : { sessionPath: session }),
+		...(delegation.cwd === undefined ? {} : { cwd: delegation.cwd }),
+		...(delegation.sessionDir === undefined ? {} : { sessionDir: delegation.sessionDir }),
+		...(delegation.workspace === undefined ? {} : { workspace: delegation.workspace }),
+		...(limit === undefined ? {} : { limit }),
+		task,
+		body,
+		workspaceSnapshot: snapshot,
+	};
+}
+
+/** The snapshot lines of the result text: a heading line, then its path lists indented. */
+function checkoutText(snapshot: WorkspaceSnapshot): string[] {
+	const [first, ...rest] = snapshotLines(snapshot);
+	return [`Checkout when the result arrived: ${first}`, ...rest.map((line) => `  ${line}`)];
+}
+
+/** The one message the parent model reads for a settled delegation. */
+export function resultText(details: ResultDetails): string {
+	const { task } = details;
+	const quote =
+		"note" in task
+			? task.note
+			: `Task, quoted from ${task.path}:\n${task.text
+					.split("\n")
+					.map((line) => `> ${line}`)
+					.join("\n")}`;
+	return [
+		`[delegate] Result from ${details.agent} (${modelLabel(details.model, details.finishedModel)}), delegation ${details.id}${details.resumedFrom === undefined ? "" : ` (resumed from ${details.resumedFrom})`}, request ${details.requestId}.`,
+		`Status: ${details.status}`,
+		...(details.limit === undefined ? [] : [details.limit]),
+		quote,
+		`Working directory: ${cwdLine(details.cwd)}`,
+		...(details.workspace === undefined ? [] : [`Workspace: ${workspaceLine(details.workspace)}`]),
+		...(details.workspaceSnapshot === undefined ? [] : checkoutText(details.workspaceSnapshot)),
+		`Envelope: ${details.envelopePath}`,
+		`Delegate session: ${details.sessionPath ?? details.sessionId ?? details.id}`,
+		"",
+		details.body,
+	].join("\n");
+}