pi-squire 0.9.5 → 0.11.0

package/src/render.ts

@@ -18,13 +18,106 @@ import { Box, type Component, Container, Markdown, Spacer, Text, TruncatedText }
 import type { Static } from "typebox";
 
 import type { DelegateSchema } from "./index.ts";
-import type { MessageDetails } from "./results.ts";
+import type { MessageDetails, ResourceFacts, WorkspaceAttempt } from "./results.ts";
+import type { WorkspaceSnapshot } from "./snapshot.ts";
+import type { PathSummary, Workspace } from "./workspace.ts";
 
 /** The launch model, or `launch → finished` when the delegate finished on another one. */
 export function modelLabel(model: string, finished: string | undefined): string {
 	return finished === undefined || finished === model ? model : `${model} → ${finished}`;
 }
 
+const displayReason = (reason: string): string => JSON.stringify(reason).slice(1, -1);
+
+/** Where a delegation ran, or that its record, from before cwd was kept, does not say. */
+export function cwdLine(cwd: string | undefined): string {
+	return cwd ?? "unknown (not recorded)";
+}
+
+/** How a delegation's directory was chosen and its Git checkout at launch, on one line. */
+export function workspaceLine(workspace: Workspace): string {
+	if (workspace.mode === "managed") {
+		const { createdBranch, requestedBase, baseCommit, source, cwd } = workspace;
+		return `managed worktree ${cwd}, new branch ${createdBranch} created from ${requestedBase} (${baseCommit}) of ${source.checkoutRoot}; ${dirtyNotice(workspace.sourceDirty)}`;
+	}
+	const { mode, git } = workspace;
+	const how = mode === "inherited" ? "the parent's directory" : "existing directory";
+	if (git.kind === "non-git") return `${how}; not a Git checkout`;
+	if (git.kind === "unknown") return `${how}; Git state unknown (${displayReason(git.reason)})`;
+	const { mainRoot, checkoutRoot } = git.identity;
+	const linked = checkoutRoot === mainRoot ? "" : ` (linked worktree ${checkoutRoot})`;
+	const at = git.position.detached ? "detached HEAD" : `branch ${git.position.branch}`;
+	return `${how}; Git checkout ${mainRoot}${linked}, ${at}, launch commit ${git.baseline ?? "none (no commits yet)"}`;
+}
+
+/** The source's uncommitted paths a worktree does not carry, bounded to a few names. */
+export function dirtyNotice({ paths, total }: PathSummary): string {
+	if (total === 0) return "the source had no uncommitted files";
+	const shown = paths.slice(0, 5).map((path) => JSON.stringify(path));
+	const rest = total > shown.length ? `, and ${total - shown.length} more` : "";
+	return `${total} uncommitted source path${total === 1 ? " is" : "s are"} not copied into it (${shown.join(", ")}${rest})`;
+}
+
+/** What is known to exist for an attempt, in words. */
+export function resourceLine(resources: ResourceFacts): string {
+	switch (resources.kind) {
+		case "none":
+			return "nothing created by this attempt remains";
+		case "branch":
+			return `the branch ${resources.branch} remains at ${resources.head}; its worktree is gone`;
+		case "worktree":
+			return `the worktree ${resources.cwd} and its branch ${resources.branch} (at ${resources.head}) remain`;
+		case "unknown":
+			return `unknown: ${displayReason(resources.reason)}; observed paths ${JSON.stringify(resources.observedPaths)}, refs ${JSON.stringify(resources.observedRefs)}`;
+	}
+}
+
+/** The lines that describe an attempt without a window: its plan, what exists, why it stopped and recovery. */
+export function attemptLines({ plan, attempt, requestId }: WorkspaceAttempt): string[] {
+	let why: string[] = [];
+	if ("cause" in attempt) why = [`cause: ${attempt.cause}`];
+	else if ("reason" in attempt) why = [`reason: ${attempt.reason}`];
+	return [
+		`source: ${plan.sourceCwd} (repository ${plan.source.mainRoot})`,
+		`worktree: ${plan.destination} on new branch ${plan.branch} from ${plan.requestedBase} (${plan.baseCommit})`,
+		`resources: ${resourceLine(attempt.resources)}`,
+		...why,
+		...(attempt.phase === "retained" && attempt.recovery.length > 0
+			? ["recovery (non-forced; check each command's result):", ...attempt.recovery.map((line) => `  ${line}`)]
+			: []),
+		...(requestId === undefined
+			? []
+			: [`request: ${requestId} (the task was mailed; no window id/start was recorded and a window may still exist)`]),
+	];
+}
+
+/** A path list as data: each name JSON-quoted, so spaces, quotes and newlines stay inside one line. */
+function pathList({ paths, total }: PathSummary): string {
+	if (total === 0) return "none";
+	const more = total > paths.length ? `, and ${total - paths.length} more not listed` : "";
+	return `${total} path${total === 1 ? "" : "s"}: ${paths.map((path) => JSON.stringify(path)).join(", ")}${more}`;
+}
+
+/**
+ * A checkout observation: a summary line, then for Git one line per path
+ * category. Committed changes are counted from the launch commit; pending
+ * ones are the index and working tree now.
+ */
+export function snapshotLines(snapshot: WorkspaceSnapshot): string[] {
+	if (snapshot.kind === "non-git") return ["not a Git checkout"];
+	if (snapshot.kind === "unknown") return [`Git state unknown (${displayReason(snapshot.reason)})`];
+	const { position, head, baseline, ahead, workingState, committed, pending } = snapshot;
+	const at = position.detached ? "detached HEAD" : `branch ${position.branch}`;
+	return [
+		`${at}, head ${head}, launch commit ${baseline}, ${ahead} commit${ahead === 1 ? "" : "s"} since launch, working tree ${workingState}`,
+		`committed since launch: ${pathList(committed)}`,
+		`staged: ${pathList(pending.staged)}`,
+		`unstaged: ${pathList(pending.unstaged)}`,
+		`untracked: ${pathList(pending.untracked)}`,
+		`conflicted: ${pathList(pending.conflicted)}`,
+	];
+}
+
 /** Lines of a result the collapsed message previews. */
 const PREVIEW_LINES = 5;
 /** Characters of the task's first line the call row shows. */
@@ -61,10 +154,17 @@ 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)}`);
+	if (details.workspace !== undefined) lines.push(`workspace ${workspaceLine(details.workspace)}`);
+	if (details.kind === "result" && details.workspaceSnapshot !== undefined) {
+		const [first, ...rest] = snapshotLines(details.workspaceSnapshot);
+		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;
 }
@@ -194,6 +294,12 @@ export function renderDelegateResult(
 				...started.notices,
 				`delegation ${started.id}`,
 				`window ${started.windowName} (${started.windowId})`,
+				// 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.
+				...((started.workspace as Workspace | undefined) === undefined
+					? []
+					: [`workspace ${workspaceLine(started.workspace)}`]),
 				`thinking ${started.thinking}, auto-exit ${started.autoExit ? "on" : "off"}`,
 			].map((line) => theme.fg("dim", line)),
 		);

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");
+}

package/src/result-sessions.ts

@@ -0,0 +1,79 @@
+import { closeSync, openSync, readdirSync, readFileSync, readSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import type { StartedRecorded } from "./result-types.ts";
+
+/**
+ * The Pi session id a delegation's mail, replies, usage-limit marks and file
+ * name use. A resumed delegation has its own id but reopens the first one's
+ * session; records from before resuming have no `sessionId`, and it is their `id`.
+ */
+export function sessionIdOf(record: { id: string; sessionId?: string }): string {
+	return record.sessionId ?? record.id;
+}
+
+/** The delegate session file in a directory, found by its `_<id>.jsonl` suffix, `id` being a session id. */
+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);
+}
+/** Use a recorded absolute session path, otherwise search its recorded session directory. */
+export function locateSession(record: StartedRecorded, fallbackDir: string | undefined): string | undefined {
+	const known = record.sessionPath ?? record.result?.sessionPath;
+	if (known !== undefined) return known;
+	const found = findSession(record.sessionDir ?? fallbackDir, sessionIdOf(record));
+	if (found !== undefined && isAbsolute(found)) record.sessionPath = found;
+	return found;
+}
+/** How much of a session file's start is read to find its header line. */
+const HEADER_BYTES = 64 * 1024;
+
+/** The working directory a session file's header stores, which Pi runs the session in; undefined when the file or the field is missing. */
+export function sessionHeaderCwd(sessionPath: string): string | undefined {
+	let fd: number;
+	try {
+		fd = openSync(sessionPath, "r");
+	} catch {
+		return undefined;
+	}
+	try {
+		const buffer = Buffer.alloc(HEADER_BYTES);
+		const text = buffer.subarray(0, readSync(fd, buffer, 0, HEADER_BYTES, 0)).toString("utf8");
+		const header = JSON.parse(text.split("\n", 1)[0]) as { type?: unknown; cwd?: unknown };
+		return header.type === "session" && typeof header.cwd === "string" && header.cwd !== "" ? header.cwd : undefined;
+	} catch {
+		return undefined;
+	} finally {
+		closeSync(fd);
+	}
+}
+
+/** The provider/model of the last assistant message in the delegate session, if available. */
+export function finishedModel(sessionPath: string | undefined): string | undefined {
+	if (sessionPath === undefined) return undefined;
+	let lines: string[];
+	try {
+		lines = readFileSync(sessionPath, "utf8").split("\n");
+	} catch {
+		return undefined;
+	}
+	for (let i = lines.length - 1; i >= 0; i--) {
+		let entry: { type?: unknown; message?: { role?: unknown; provider?: unknown; model?: unknown } };
+		try {
+			entry = JSON.parse(lines[i]);
+		} catch {
+			continue;
+		}
+		const message = entry?.message;
+		if (entry?.type !== "message" || message?.role !== "assistant") continue;
+		if (typeof message.provider === "string" && typeof message.model === "string")
+			return `${message.provider}/${message.model}`;
+	}
+	return undefined;
+}

package/src/result-types.ts

@@ -0,0 +1,36 @@
+import type { Delegation } from "./results.ts";
+import type { WorktreePlan } from "./worktree.ts";
+
+/** One started delegation as it stands: what was recorded at its start, plus what came after. */
+export type StartedRecorded = Delegation & { result?: import("./results.ts").Result; closed?: boolean; gone?: boolean };
+/** What is known to exist for an attempt; facts, not authorization to remove anything. */
+export type ResourceFacts =
+	| { kind: "none" }
+	| { kind: "branch"; branch: string; head: string }
+	| { kind: "worktree"; cwd: string; branch: string; head: string }
+	| { kind: "unknown"; reason: string; observedPaths: string[]; observedRefs: string[] };
+/** Where a managed launch stands before, or instead of, a window. */
+export type AttemptState =
+	| { phase: "planned"; resources: ResourceFacts }
+	| { phase: "created"; resources: ResourceFacts }
+	| { phase: "rolled-back"; resources: { kind: "none" }; cause: string }
+	| { phase: "retained"; resources: ResourceFacts; cause: string; recovery: string[] }
+	| { phase: "interrupted"; resources: ResourceFacts; lastPhase: "planned" | "created"; reason: string };
+/** A managed launch with no window; its request id exists only if mail returned one. */
+export type WorkspaceAttempt = {
+	kind: "workspace-attempt";
+	id: string;
+	parentId: string;
+	agent: string;
+	model: string;
+	thinking: string;
+	name?: string;
+	sessionDir: string;
+	plan: WorktreePlan;
+	attempt: AttemptState;
+	requestId?: string;
+};
+export type Recorded = StartedRecorded | WorkspaceAttempt;
+export function isStarted(record: Recorded): record is StartedRecorded {
+	return !("kind" in record && record.kind === "workspace-attempt");
+}