@shanepadgett/tau-agent 0.1.0

package/extensions/commit/commit-plan.ts

@@ -0,0 +1,328 @@
+import { randomUUID } from "node:crypto";
+import { type ThinkingLevel, type Tool, Type } from "@earendil-works/pi-ai";
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { generateToolValidated, generateValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { truncAt } from "../../shared/text.ts";
+import type { CommitEvidence, DirtyFile } from "./git-change-set.ts";
+
+const MAX_PLAN_EVIDENCE_CHARS = 48_000;
+const CONVENTIONAL_COMMIT_TYPES = ["feat", "fix", "docs", "refactor", "test", "chore", "perf", "ci", "build", "revert"];
+const COMMIT_MODELS: ReadonlyArray<{ provider: string; model: string; reasoning: ThinkingLevel }> = [
+	{ provider: "openai-codex", model: "gpt-5.6-terra", reasoning: "low" },
+];
+const COMMIT_PLAN_TOOL = {
+	name: "create_commit_plan",
+	description: "Submit the commit plan for the dirty repository files.",
+	parameters: Type.Object({
+		commits: Type.Array(
+			Type.Object({
+				message: Type.String({ description: "Git commit message." }),
+				allFiles: Type.Boolean({ description: "True only for a single commit that includes every dirty file." }),
+				files: Type.Array(Type.Integer({ description: "Numeric dirty file ID. Empty when allFiles is true." })),
+			}),
+		),
+	}),
+} satisfies Tool;
+
+export interface CommitGroup {
+	id: string;
+	message: string;
+	files: string[];
+}
+
+export interface CommitPlanState {
+	files: readonly DirtyFile[];
+	groups: CommitGroup[];
+	worktreeSignature: string;
+}
+
+interface CommitPlanToolInput {
+	commits: readonly CommitPlanToolCommit[];
+}
+
+interface CommitPlanToolCommit {
+	message: string;
+	allFiles: boolean;
+	files: readonly number[];
+}
+
+export async function generatePlan(
+	ctx: ExtensionCommandContext,
+	evidence: CommitEvidence,
+	previousPlan: readonly CommitGroup[] = [],
+	regenerationNote = "",
+): Promise<CommitGroup[]> {
+	const prompt = buildPlanPrompt(evidence, previousPlan, regenerationNote);
+	return generateToolValidated(
+		ctx,
+		await resolveCandidates(ctx, COMMIT_MODELS),
+		prompt,
+		COMMIT_PLAN_TOOL,
+		(input) => commitGroupsFromToolInput(input, evidence.files),
+		(error, text) =>
+			[
+				`That commit plan failed validation: ${error.message}`,
+				`Call ${COMMIT_PLAN_TOOL.name} again with corrected arguments only.`,
+				"Use only numeric file IDs provided in the prompt.",
+				"Include every dirty file ID exactly once across the plan.",
+				"Set allFiles true only for a single all-files commit; then set files to an empty array.",
+				"Previous response:",
+				text,
+			].join("\n"),
+		{ statusKey: "commit", notifyOnFallback: true },
+	);
+}
+
+export async function regenerateMessage(
+	ctx: ExtensionCommandContext,
+	evidence: CommitEvidence,
+	files: readonly string[],
+	previousPlan: readonly CommitGroup[] = [],
+	selectedGroupId: string | undefined = undefined,
+	regenerationNote = "",
+): Promise<string> {
+	const selected = evidence.files.filter((file) => files.includes(file.path));
+	const prompt = buildMessagePrompt(evidence, selected, previousPlan, selectedGroupId, regenerationNote);
+	return generateValidated(ctx, await resolveCandidates(ctx, COMMIT_MODELS), prompt, requireCommitMessage, undefined, {
+		statusKey: "commit",
+		notifyOnFallback: true,
+	});
+}
+
+export function requireCommitMessage(rawMessage: string): string {
+	const message = stripCodeFence(rawMessage)
+		.replace(/^commit message:\s*/i, "")
+		.trim()
+		.replace(/\r\n/g, "\n");
+	if (!message) throw new Error("Commit message is empty.");
+
+	const [subject, ...bodyLines] = message.split("\n");
+	if (!subject) throw new Error("Commit message subject is empty.");
+	const match = subject.match(
+		/^(feat|fix|docs|refactor|test|chore|perf|ci|build|revert)(\([a-z0-9]+(?:-[a-z0-9]+)*\))?(!)?: .+$/,
+	);
+	if (!match) throw new Error("Commit subject must be a valid conventional commit message.");
+
+	const body = bodyLines.join("\n");
+	if (!match[3]) {
+		if (body) throw new Error("Non-breaking commit messages must not have a body.");
+		return message;
+	}
+	if (!body.startsWith("\nBREAKING CHANGE:")) {
+		throw new Error("Breaking commit messages need one body paragraph starting with BREAKING CHANGE:.");
+	}
+	if (body.slice(1).includes("\n\n"))
+		throw new Error("Breaking commit messages must have exactly one body paragraph.");
+	return message;
+}
+
+function commitGroupsFromToolInput(input: unknown, files: readonly DirtyFile[]): CommitGroup[] {
+	if (!isCommitPlanToolInput(input)) throw new Error("Commit plan tool input is malformed.");
+	const pathById = new Map(files.map((file) => [file.id, file.path]));
+	const seen = new Set<string>();
+	const groups = input.commits.flatMap((commit) =>
+		groupFromToolCommit(commit, input.commits.length, files, pathById, seen),
+	);
+	if (groups.length === 0) throw new Error("Commit plan produced no non-empty commits.");
+	assertAllFilesAssigned(files, seen);
+	return groups;
+}
+
+function groupFromToolCommit(
+	commit: CommitPlanToolCommit,
+	commitCount: number,
+	files: readonly DirtyFile[],
+	pathById: ReadonlyMap<number, string>,
+	seen: Set<string>,
+): CommitGroup[] {
+	const paths = commit.allFiles
+		? allFilesForSingleCommit(commitCount, files, seen)
+		: listedFiles(commit.files, pathById, seen);
+	return paths.length > 0 ? [{ id: randomUUID(), message: requireCommitMessage(commit.message), files: paths }] : [];
+}
+
+function allFilesForSingleCommit(commitCount: number, files: readonly DirtyFile[], seen: Set<string>): string[] {
+	if (commitCount !== 1) throw new Error("allFiles is only valid for a single-commit plan.");
+	const paths = files.map((file) => file.path);
+	for (const path of paths) seen.add(path);
+	return paths;
+}
+
+function listedFiles(ids: readonly number[], pathById: ReadonlyMap<number, string>, seen: Set<string>): string[] {
+	const paths: string[] = [];
+	for (const id of ids) {
+		const path = pathById.get(id);
+		if (!path) throw new Error(`Unknown dirty file ID in commit plan: ${id}`);
+		if (seen.has(path)) throw new Error(`Dirty file ID is used more than once in commit plan: ${id}`);
+		seen.add(path);
+		paths.push(path);
+	}
+	return paths;
+}
+
+function assertAllFilesAssigned(files: readonly DirtyFile[], seen: ReadonlySet<string>): void {
+	const missing = files.filter((file) => !seen.has(file.path));
+	if (missing.length === 0) return;
+	throw new Error(`Commit plan omitted dirty file IDs: ${missing.map((file) => file.id).join(", ")}`);
+}
+
+function buildPlanPrompt(
+	evidence: CommitEvidence,
+	previousPlan: readonly CommitGroup[],
+	regenerationNote: string,
+): string {
+	return [
+		"Create the fewest useful commits for the dirty repository files.",
+		`You have exactly one job: call ${COMMIT_PLAN_TOOL.name} once with the final plan.`,
+		"Do not answer in text. Do not explain. Do not include markdown.",
+		`Any response except a single ${COMMIT_PLAN_TOOL.name} tool call is invalid.`,
+		"File references must be numeric IDs only, never paths.",
+		"Every dirty file ID from the File catalog must appear in exactly one commit.",
+		"If any dirty file ID is missing from the plan, validation fails.",
+		"Tool argument shape:",
+		"commits: [{ message: string, allFiles: boolean, files: number[] }]",
+		"For one commit containing all dirty files: { message, allFiles: true, files: [] }",
+		"Otherwise: { message, allFiles: false, files: [numeric IDs from File catalog] }",
+		"Commit ladder:",
+		"1. Can all dirty files be committed together with one honest conventional commit message a user would understand?",
+		"   If yes, return one commit.",
+		"2. For one all-files commit, set allFiles true and files to an empty array instead of listing every ID.",
+		"3. If one message would be misleading, split off only files with a clearly different purpose.",
+		"4. Keep README/docs/tests/prompts/UI text with the code change they describe or verify.",
+		"5. Do not split by file type, directory, or conventional commit type alone.",
+		"6. Every dirty file must belong to one of the commits.",
+		"7. Use the minimum number of commits that preserves meaning.",
+		"Rules:",
+		"- Prefer fewer coherent commits over tidy-looking categories.",
+		"- Use each dirty file exactly once.",
+		"- Use only numeric file IDs listed below.",
+		"- Prefer conventional commit messages.",
+		`- Allowed conventional commit types: ${CONVENTIONAL_COMMIT_TYPES.join(", ")}.`,
+		"- Optional scope must be lowercase kebab-case, singular, and useful; omit it for broad or unrelated changes.",
+		"- Subject must be one concise imperative line, no trailing period, max 100 characters.",
+		"- Prefer exactly one line for non-breaking changes.",
+		"- For breaking changes, prefer ! plus one body paragraph starting with BREAKING CHANGE:.",
+		"Recent commit subjects are style guidance. User intent explains why. File evidence is authoritative.",
+		"When regenerating, use the previous plan and user note to understand what to change; do not copy mistakes.",
+		"",
+		"Recent commit subjects:",
+		evidence.recentSubjects || "(none)",
+		"",
+		"User intent since last commit:",
+		formatIntent(evidence.intent),
+		"",
+		...formatRegenerationContext(evidence.files, previousPlan, undefined, regenerationNote),
+		"File catalog:",
+		formatFileCatalog(evidence.files),
+		"",
+		"File evidence:",
+		truncAt(evidence.files.map(formatFileEvidence).join("\n\n"), MAX_PLAN_EVIDENCE_CHARS),
+	].join("\n");
+}
+
+function buildMessagePrompt(
+	evidence: CommitEvidence,
+	files: readonly DirtyFile[],
+	previousPlan: readonly CommitGroup[],
+	selectedGroupId: string | undefined,
+	regenerationNote: string,
+): string {
+	return [
+		"Write one git commit message for the selected dirty files.",
+		"Prefer this conventional commit format:",
+		"<type>[optional scope][!]: <description>",
+		`Allowed conventional commit types: ${CONVENTIONAL_COMMIT_TYPES.join(", ")}.`,
+		"Prefer lowercase kebab-case scopes only when useful; omit for broad or unrelated changes.",
+		"For non-breaking changes, output one subject line and no body.",
+		"For breaking changes, use ! plus one body paragraph starting with BREAKING CHANGE:.",
+		"Do not wrap the message in markdown or code fences.",
+		"",
+		"Recent commit subjects:",
+		evidence.recentSubjects || "(none)",
+		"",
+		"User intent since last commit:",
+		formatIntent(evidence.intent),
+		"",
+		...formatRegenerationContext(evidence.files, previousPlan, selectedGroupId, regenerationNote),
+		"Selected files:",
+		truncAt(files.map(formatFileEvidence).join("\n\n"), MAX_PLAN_EVIDENCE_CHARS),
+	].join("\n");
+}
+
+function formatFileCatalog(files: readonly DirtyFile[]): string {
+	const groups = new Map<string, string[]>();
+	for (const file of files) {
+		const slash = file.path.lastIndexOf("/");
+		const folder = slash >= 0 ? `${file.path.slice(0, slash)}/` : "./";
+		const name = slash >= 0 ? file.path.slice(slash + 1) : file.path;
+		const lines = groups.get(folder) ?? [];
+		lines.push(`  [${file.id}] ${file.status} ${name}${file.renamedFrom ? ` ← ${file.renamedFrom}` : ""}`);
+		groups.set(folder, lines);
+	}
+	return [...groups.entries()].map(([folder, lines]) => [folder, ...lines].join("\n")).join("\n");
+}
+
+function formatFileEvidence(file: DirtyFile): string {
+	return [
+		`[${file.id}] ${file.status} ${file.path}`,
+		file.renamedFrom && `Renamed from: ${file.renamedFrom}`,
+		`Kind: ${file.kind}`,
+		file.evidence,
+	]
+		.filter(Boolean)
+		.join("\n");
+}
+
+function formatIntent(intent: readonly string[]): string {
+	return intent.length > 0 ? intent.map((message, index) => `[${index + 1}]\n${message}`).join("\n\n") : "(none)";
+}
+
+function formatRegenerationContext(
+	files: readonly DirtyFile[],
+	previousPlan: readonly CommitGroup[],
+	selectedGroupId: string | undefined,
+	regenerationNote: string,
+): string[] {
+	if (previousPlan.length === 0 && !regenerationNote.trim()) return [];
+	const idByPath = new Map(files.map((file) => [file.path, file.id]));
+	return [
+		"Previous commit plan:",
+		previousPlan.length > 0
+			? previousPlan
+					.map((group, index) => {
+						const selected = group.id === selectedGroupId ? " (selected)" : "";
+						const groupFiles = group.files.map((file) => `- [${idByPath.get(file) ?? "?"}] ${file}`).join("\n");
+						return `[${index + 1}]${selected}\nMessage: ${group.message}\nFiles:\n${groupFiles}`;
+					})
+					.join("\n\n")
+			: "(none)",
+		"",
+		"User regeneration note:",
+		regenerationNote.trim() || "(none)",
+		"",
+	];
+}
+
+function stripCodeFence(raw: string): string {
+	const text = raw.trim();
+	const fenced = text.match(/^```(?:gitcommit|json|text)?\s*\n([\s\S]*?)\n```$/i);
+	return fenced?.[1]?.trim() ?? text;
+}
+
+function isCommitPlanToolInput(value: unknown): value is CommitPlanToolInput {
+	return isRecord(value) && Array.isArray(value.commits) && value.commits.every(isCommitPlanToolCommit);
+}
+
+function isCommitPlanToolCommit(value: unknown): value is CommitPlanToolCommit {
+	return (
+		isRecord(value) &&
+		typeof value.message === "string" &&
+		typeof value.allFiles === "boolean" &&
+		Array.isArray(value.files) &&
+		value.files.every((file) => typeof file === "number" && Number.isInteger(file))
+	);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/extensions/commit/git-change-set.ts

@@ -0,0 +1,268 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rm, stat, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Message } from "@earendil-works/pi-ai";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import type { GitRunner } from "../../shared/git.ts";
+import { truncAt } from "../../shared/text.ts";
+
+const COMMIT_TIMEOUT_MS = 120_000;
+const EVIDENCE_CONCURRENCY = 4;
+const MAX_FILE_EVIDENCE_CHARS = 4_000;
+const MAX_INTENT_CHARS = 8_000;
+const MAX_UNTRACKED_PREVIEW_BYTES = 12_000;
+
+export interface CommitEvidence {
+	recentSubjects: string;
+	intent: readonly string[];
+	files: readonly DirtyFile[];
+}
+
+export interface DirtyFile {
+	id: number;
+	path: string;
+	status: string;
+	kind: "modified" | "added" | "deleted" | "renamed" | "untracked";
+	untracked: boolean;
+	evidence: string;
+	renamedFrom?: string;
+}
+
+interface ParsedDirtyFile {
+	path: string;
+	status: string;
+	untracked: boolean;
+	renamedFrom?: string;
+}
+
+export async function loadChangeSet(
+	git: GitRunner,
+	root: string,
+	entries: readonly SessionEntry[],
+	markerType: string,
+): Promise<CommitEvidence> {
+	const [raw, head, recentSubjects] = await Promise.all([
+		git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root }),
+		git.run(["rev-parse", "--verify", "HEAD"], { cwd: root, optional: true }),
+		git.run(["log", "-12", "--pretty=format:%s"], { cwd: root, optional: true }),
+	]);
+	const files = parsePorcelainV2Z(raw);
+	return {
+		recentSubjects,
+		intent: collectIntent(entries, markerType),
+		files: await collectFileEvidence(git, root, files, Boolean(head)),
+	};
+}
+
+export async function computeWorktreeSignature(
+	git: GitRunner,
+	root: string,
+	files: readonly DirtyFile[],
+): Promise<string> {
+	const hash = createHash("sha256");
+	const [status, stagedDiff, unstagedDiff] = await Promise.all([
+		git.run(["status", "--porcelain=v2", "-z", "--untracked-files=all"], { cwd: root }),
+		git.run(["diff", "--cached", "--no-color", "--no-ext-diff"], { cwd: root, optional: true }),
+		git.run(["diff", "--no-color", "--no-ext-diff"], { cwd: root, optional: true }),
+	]);
+	hash.update(status);
+	hash.update("\0staged\0");
+	hash.update(stagedDiff);
+	hash.update("\0unstaged\0");
+	hash.update(unstagedDiff);
+
+	for (const file of files.filter((item) => item.untracked)) await hashUntrackedFile(hash, root, file.path);
+	return hash.digest("hex");
+}
+
+export async function stageFilesOnly(git: GitRunner, root: string, files: readonly DirtyFile[]): Promise<void> {
+	await git.run(["reset", "--mixed", "--quiet"], { cwd: root });
+	const paths = files.flatMap((file) => (file.renamedFrom ? [file.renamedFrom, file.path] : [file.path]));
+	if (paths.length > 0) await git.run(["add", "--", ...paths], { cwd: root });
+}
+
+export async function commitStaged(git: GitRunner, root: string, message: string): Promise<string> {
+	const messageFile = join(tmpdir(), `pi-commit-${randomUUID()}.txt`);
+	try {
+		await writeFile(messageFile, `${message}\n`, "utf8");
+		await git.run(["commit", "-F", messageFile], { cwd: root, timeout: COMMIT_TIMEOUT_MS });
+		return await git.run(["rev-parse", "--short", "HEAD"], { cwd: root });
+	} finally {
+		await rm(messageFile, { force: true });
+	}
+}
+
+export function assertCommittableState(files: readonly DirtyFile[]): void {
+	const deletedStagedAdds = files.filter((file) => file.status === "AD").map((file) => file.path);
+	if (deletedStagedAdds.length === 0) return;
+	throw new Error(
+		[
+			"Staged additions were deleted from the working tree.",
+			"Unstage or restore them before /commit:",
+			...deletedStagedAdds.map((path) => `- ${path}`),
+		].join("\n"),
+	);
+}
+
+async function collectFileEvidence(
+	git: GitRunner,
+	root: string,
+	files: readonly DirtyFile[],
+	hasHead: boolean,
+): Promise<DirtyFile[]> {
+	const withEvidence: DirtyFile[] = [];
+	for (let index = 0; index < files.length; index += EVIDENCE_CONCURRENCY) {
+		withEvidence.push(
+			...(await Promise.all(
+				files
+					.slice(index, index + EVIDENCE_CONCURRENCY)
+					.map(async (file) => ({ ...file, evidence: await loadEvidenceForFile(git, root, file, hasHead) })),
+			)),
+		);
+	}
+	return withEvidence;
+}
+
+function parsePorcelainV2Z(raw: string): DirtyFile[] {
+	if (!raw) return [];
+	const parts = raw.split("\0").filter(Boolean);
+	const parsed: ParsedDirtyFile[] = [];
+
+	for (let index = 0; index < parts.length; index++) {
+		const entry = parts[index];
+		if (!entry) continue;
+		if (entry[0] === "u") throw new Error("Unmerged conflict entries detected; resolve conflicts before committing.");
+		if (entry[0] === "?") {
+			parsed.push({ path: entry.slice(2), status: "??", untracked: true });
+			continue;
+		}
+
+		const fields = entry.split(" ");
+		if (entry[0] === "1")
+			parsed.push({ path: fields.slice(8).join(" "), status: statusText(fields), untracked: false });
+		if (entry[0] === "2") {
+			const renamedFrom = parts[index + 1];
+			parsed.push({
+				path: fields.slice(9).join(" "),
+				status: statusText(fields),
+				untracked: false,
+				...(renamedFrom ? { renamedFrom } : {}),
+			});
+			index++;
+		}
+	}
+
+	return parsed
+		.sort((left, right) => left.path.localeCompare(right.path))
+		.map((file, index) => ({ ...file, id: index + 1, kind: changeKind(file), evidence: "" }));
+}
+
+function statusText(fields: readonly string[]): string {
+	return (fields[1] ?? "  ").replace(/\./g, " ");
+}
+
+async function loadEvidenceForFile(git: GitRunner, root: string, file: DirtyFile, hasHead: boolean): Promise<string> {
+	if (file.untracked) return untrackedEvidence(root, file.path);
+	if (file.kind === "deleted") return "deleted file; contents omitted";
+	if (file.renamedFrom && !/[MAD]/.test(file.status)) return "renamed file; contents unchanged";
+
+	const paths = file.renamedFrom ? [file.renamedFrom, file.path] : [file.path];
+	if (!hasHead) return diffFromIndexAndWorktree(git, root, paths);
+	const diff = await git.run(["diff", "--stat", "--patch", "--no-color", "--no-ext-diff", "HEAD", "--", ...paths], {
+		cwd: root,
+		optional: true,
+	});
+	return truncAt(diff || "metadata-only change", MAX_FILE_EVIDENCE_CHARS);
+}
+
+async function diffFromIndexAndWorktree(git: GitRunner, root: string, paths: readonly string[]): Promise<string> {
+	const [staged, unstaged] = await Promise.all([
+		git.run(["diff", "--cached", "--stat", "--patch", "--no-color", "--no-ext-diff", "--", ...paths], {
+			cwd: root,
+			optional: true,
+		}),
+		git.run(["diff", "--stat", "--patch", "--no-color", "--no-ext-diff", "--", ...paths], {
+			cwd: root,
+			optional: true,
+		}),
+	]);
+	return truncAt(
+		[staged && `staged diff:\n${staged}`, unstaged && `unstaged diff:\n${unstaged}`].filter(Boolean).join("\n\n") ||
+			"metadata-only change",
+		MAX_FILE_EVIDENCE_CHARS,
+	);
+}
+
+async function untrackedEvidence(root: string, path: string): Promise<string> {
+	try {
+		const fullPath = join(root, path);
+		const info = await stat(fullPath);
+		if (!info.isFile()) return `untracked ${info.isDirectory() ? "directory" : "non-file"}`;
+		if (info.size > MAX_UNTRACKED_PREVIEW_BYTES) return `untracked file, ${info.size} bytes`;
+		const bytes = await readFile(fullPath);
+		if (bytes.includes(0)) return `untracked binary file, ${info.size} bytes`;
+		return truncAt(`untracked file preview:\n${bytes.toString("utf8")}`, MAX_FILE_EVIDENCE_CHARS);
+	} catch (error) {
+		return `untracked file preview unavailable: ${error instanceof Error ? error.message : String(error)}`;
+	}
+}
+
+async function hashUntrackedFile(hash: ReturnType<typeof createHash>, root: string, path: string): Promise<void> {
+	const fullPath = join(root, path);
+	try {
+		const info = await stat(fullPath);
+		hash.update(`\0${path}:${info.size}:${info.mtimeMs}`);
+		if (info.isFile() && info.size <= MAX_UNTRACKED_PREVIEW_BYTES) hash.update(await readFile(fullPath));
+	} catch {
+		hash.update(`\0${path}:missing`);
+	}
+}
+
+function changeKind(file: ParsedDirtyFile): DirtyFile["kind"] {
+	if (file.untracked) return "untracked";
+	if (file.renamedFrom) return "renamed";
+	if (file.status.includes("D")) return "deleted";
+	if (file.status.includes("A")) return "added";
+	return "modified";
+}
+
+function collectIntent(entries: readonly SessionEntry[], markerType: string): string[] {
+	let intent: string[] = [];
+	for (const entry of entries) {
+		if (entry.type === "custom" && entry.customType === markerType) {
+			intent = [];
+			continue;
+		}
+		if (entry.type !== "message" || entry.message.role !== "user") continue;
+		const text = extractUserText(entry.message.content).trim();
+		if (text && !/^\/commit(?:\s|$)/.test(text)) intent.push(text);
+	}
+	return boundIntent(intent);
+}
+
+function boundIntent(intent: readonly string[]): string[] {
+	const bounded: string[] = [];
+	let used = 0;
+	for (let index = intent.length - 1; index >= 0; index--) {
+		const message = intent[index];
+		if (!message) continue;
+		const remaining = MAX_INTENT_CHARS - used;
+		if (remaining <= 0) break;
+		const clipped = message.length > remaining ? truncAt(message, remaining) : message;
+		bounded.push(clipped);
+		used += clipped.length;
+	}
+	return bounded.reverse();
+}
+
+function extractUserText(content: string | Message["content"]): string {
+	if (typeof content === "string") return content;
+	return content
+		.flatMap((part) => {
+			if (part.type === "text") return [part.text];
+			if (part.type === "image") return ["[image omitted]"];
+			return [];
+		})
+		.join("\n");
+}