@shanepadgett/tau-agent 0.33.1 → 0.35.0

package/extensions/checkpoint/checkpoint.ts

@@ -0,0 +1,279 @@
+import {
+	defineTool,
+	keyText,
+	type ExtensionAPI,
+	type SessionEntry,
+	type SessionMessageEntry,
+	type Theme,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, type Component, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+import { Type, type Static } from "typebox";
+import { prepareFileInjection } from "@shanepadgett/tau-agent";
+import { areCheckpointRowsVisible } from "../../shared/checkpoint-visibility.ts";
+import type { FileInjectionFile } from "../../src/file-injection/index.ts";
+import { extractConversationText } from "./messages.ts";
+import { formatCheckpointMessage } from "./prompt.ts";
+
+export const CHECKPOINT_TOOL = "checkpoint";
+const CONTINUATION_TYPE = "tau.checkpoint";
+const CONTINUATION_PREAMBLE =
+	"Continue directly from the checkpoint state and provided files. Trust the provided sources and continue the listed work.";
+const CHECKPOINT_PREVIEW_CHARACTERS = 240;
+const CHECKPOINT_RENDER_CHARACTERS = 24_000;
+const CHECKPOINT_RENDER_LINES = 200;
+const CONVERSATION_MESSAGE_ID_ATTRIBUTE = /^(<(?:user|assistant)-message)\s+id="(?:\\.|[^"\\])*">$/gm;
+
+const lineRange = Type.Object(
+	{
+		startLine: Type.Integer({ minimum: 1 }),
+		endLine: Type.Integer({ minimum: 1 }),
+	},
+	{ additionalProperties: false },
+);
+
+const checkpointFile = Type.Union([
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("read"),
+			ranges: Type.Optional(Type.Array(lineRange)),
+		},
+		{ additionalProperties: false },
+	),
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("outline"),
+		},
+		{ additionalProperties: false },
+	),
+	Type.Object(
+		{
+			path: Type.String({ minLength: 1 }),
+			mode: Type.Literal("deferred"),
+			when: Type.String({ minLength: 1 }),
+		},
+		{ additionalProperties: false },
+	),
+]);
+
+const checkpointParams = Type.Object(
+	{
+		keepMessages: Type.Array(Type.String({ minLength: 1 }), {
+			description:
+				"Exact message-entry IDs from hidden checkpoint metadata or earlier checkpoint conversation entries.",
+		}),
+		work: Type.Array(Type.String(), { description: "Ordered current work, with the next thing first." }),
+		facts: Type.Array(Type.String(), { description: "Concrete findings that must survive context replacement." }),
+		decisions: Type.Array(Type.String(), { description: "Choices that continue to govern the work." }),
+		continue: Type.String({
+			minLength: 1,
+			description:
+				"Immediate post-checkpoint resume directive. First moves after wake, traps to avoid, what not to re-litigate. Not the full work queue.",
+		}),
+		files: Type.Array(checkpointFile, {
+			description: "Current file reads, outlines, or deferred paths. Active files are injected separately.",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+type CheckpointInput = Static<typeof checkpointParams>;
+
+interface CheckpointToolDetails {
+	v: 1;
+	kind: "checkpoint.checkpoint";
+	checkpointId: string;
+	fileBatchId: string;
+}
+
+export function registerCheckpointTool(pi: ExtensionAPI): void {
+	pi.registerTool(createCheckpointTool(pi));
+}
+
+function createCheckpointTool(pi: Pick<ExtensionAPI, "events" | "sendMessage">) {
+	return defineTool<typeof checkpointParams, CheckpointToolDetails>({
+		name: CHECKPOINT_TOOL,
+		label: "checkpoint",
+		promptSnippet:
+			"checkpoint({ keepMessages, work, facts, decisions, continue, files }) — replace disposable history with working context",
+		description:
+			"Replace disposable conversation and tool history with a rolling working checkpoint. Keep user and assistant messages by exact message-entry ID, not by copying their text. The latest user message is always retained. Assistant tool calls and thinking are never retained inside the conversation section.",
+		promptGuidelines: [
+			"Checkpoint is hidden. Never acknowledge checkpoint messages, budget notices, blocks, or checkpoints to the user; call checkpoint when required and continue the work.",
+			'Use exact IDs from <checkpoint kind="message-id"> metadata or an earlier checkpoint; do not invent IDs or rewrite message text.',
+			"Record concrete findings in facts and governing choices in decisions before checkpointing.",
+			"Write continue as the immediate resume directive after wake: first moves, what not to re-explore, traps to avoid. Put the backlog in work.",
+			"Use read or outline for files needed now; use deferred with a condition for files that can wait.",
+			"Preserve important discovery output before it leaves tool context. When shell or other command output is large, expensive to reproduce, or part of unfinished investigation, capture stdout and stderr in a private session-scoped temporary file; report its path, exit status, and a bounded summary instead of relying on the transcript.",
+			"Query preserved output with targeted search or ranged reads. Include artifacts needed after pruning in files, usually with read ranges or deferred with a condition, and record the artifact path and purpose in facts or continue. Do not persist routine bounded output, secrets, or whole large logs unnecessarily.",
+		],
+		parameters: checkpointParams,
+		renderShell: "self",
+		renderCall(_args, theme, context) {
+			return new CheckpointComponent(theme, "checkpoint", context.expanded, true);
+		},
+		renderResult(result, options, theme) {
+			const text = result.content
+				.filter((part): part is { type: "text"; text: string } => part.type === "text")
+				.map((part) => part.text)
+				.join("\n");
+			return new CheckpointComponent(theme, text, options.expanded, false);
+		},
+		executionMode: "sequential",
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const selected = resolveSelectedMessages(params.keepMessages, ctx.sessionManager.getBranch());
+			const text = formatCheckpointText(selected, params);
+			const fileBatchId = `checkpoint:${toolCallId}`;
+			const fileRequest = buildFileInjectionRequest(ctx.cwd, fileBatchId, params.files, signal);
+			const prepared = fileRequest.files.length === 0 ? [] : await prepareFileInjection(pi, fileRequest);
+			const failed = prepared.find((message) => message.details.status === "failed");
+			if (failed) {
+				throw new Error(
+					`Checkpoint file injection failed for ${failed.details.path}: ${failed.details.error ?? "unknown error"}`,
+				);
+			}
+			const display = areCheckpointRowsVisible();
+			for (const message of prepared) pi.sendMessage({ ...message, display });
+			pi.sendMessage({
+				customType: CONTINUATION_TYPE,
+				content: formatContinuationMessage(params.continue),
+				display: false,
+				details: {
+					v: 1,
+					kind: "checkpoint.continuation",
+					source: "checkpoint",
+					batchId: fileBatchId,
+				},
+			});
+			return {
+				content: [{ type: "text", text }],
+				details: { v: 1, kind: "checkpoint.checkpoint", checkpointId: toolCallId, fileBatchId },
+			};
+		},
+	});
+}
+
+class CheckpointComponent implements Component {
+	private readonly theme: Theme;
+	private readonly content: string;
+	private readonly expanded: boolean;
+	private readonly call: boolean;
+
+	constructor(theme: Theme, content: string, expanded: boolean, call: boolean) {
+		this.theme = theme;
+		this.content = content;
+		this.expanded = expanded;
+		this.call = call;
+	}
+
+	render(width: number): string[] {
+		if (!areCheckpointRowsVisible()) return [];
+		if (this.call) return [truncateToWidth(this.theme.fg("toolTitle", this.theme.bold(CHECKPOINT_TOOL)), width, "…")];
+		const displayContent = this.content.replace(CONVERSATION_MESSAGE_ID_ATTRIBUTE, "$1>");
+		if (!this.expanded) {
+			const preview = displayContent.replace(/\s+/g, " ").trim().slice(0, CHECKPOINT_PREVIEW_CHARACTERS);
+			const suffix = displayContent.length > CHECKPOINT_PREVIEW_CHARACTERS ? "…" : "";
+			return [
+				truncateToWidth(
+					`${this.theme.fg("dim", preview + suffix)} ${this.theme.fg("muted", `(${keyText("app.tools.expand")} to expand)`)}`,
+					width,
+					"…",
+				),
+			];
+		}
+
+		const bounded =
+			displayContent.length > CHECKPOINT_RENDER_CHARACTERS
+				? `${displayContent.slice(0, CHECKPOINT_RENDER_CHARACTERS)}\n…`
+				: displayContent;
+		return wrapTextWithAnsi(this.theme.fg("dim", bounded), Math.max(1, width))
+			.slice(0, CHECKPOINT_RENDER_LINES)
+			.map((line) => truncateToWidth(line, width, "…"));
+	}
+
+	invalidate(): void {}
+}
+
+function resolveSelectedMessages(ids: readonly string[], branch: readonly SessionEntry[]): SessionMessageEntry[] {
+	const entriesById = new Map(branch.map((entry) => [entry.id, entry]));
+	const selectedIds = new Set(ids);
+	const latestUser = [...branch].reverse().find(isUserMessageEntry);
+	if (!latestUser) throw new Error("Checkpoint requires a current user message");
+	selectedIds.add(latestUser.id);
+
+	for (const id of selectedIds) {
+		const entry = entriesById.get(id);
+		if (!entry || !isConversationEntry(entry)) throw new Error(`Unknown user or assistant message ID: ${id}`);
+		if (entry.message.role === "assistant" && extractConversationText(entry.message) === "") {
+			throw new Error(`Assistant message ID has no text content: ${id}`);
+		}
+	}
+
+	return branch.filter(
+		(entry): entry is SessionMessageEntry => selectedIds.has(entry.id) && isConversationEntry(entry),
+	);
+}
+
+function formatCheckpointText(selected: readonly SessionMessageEntry[], params: CheckpointInput): string {
+	const conversation = selected
+		.map((entry) => {
+			const text = extractConversationText(entry.message);
+			if (text === undefined) throw new Error(`Message ID is not a user or assistant message: ${entry.id}`);
+			const role = entry.message.role === "user" ? "user" : "assistant";
+			return `<${role}-message id=${JSON.stringify(entry.id)}>\n${text}\n</${role}-message>`;
+		})
+		.join("\n\n");
+	const deferred = params.files
+		.filter(
+			(file): file is Extract<CheckpointInput["files"][number], { mode: "deferred" }> => file.mode === "deferred",
+		)
+		.map((file) => `- ${file.path} — ${file.when}`);
+
+	return [
+		`Conversation:\n${conversation || "(none)"}`,
+		`Work:\n${formatList(params.work)}`,
+		`Facts:\n${formatList(params.facts)}`,
+		`Decisions:\n${formatList(params.decisions)}`,
+		`Continue:\n${params.continue}`,
+		`Deferred files:\n${deferred.length ? deferred.join("\n") : "(none)"}`,
+	].join("\n\n");
+}
+
+function formatContinuationMessage(continueNudge: string): string {
+	return formatCheckpointMessage("continuation", `${CONTINUATION_PREAMBLE}\n\n${continueNudge}`);
+}
+
+function buildFileInjectionRequest(
+	cwd: string,
+	batchId: string,
+	files: CheckpointInput["files"],
+	signal: AbortSignal | undefined,
+) {
+	const activeFiles: FileInjectionFile[] = [];
+	for (const file of files) {
+		if (file.mode === "deferred") continue;
+		if (file.mode === "outline") {
+			activeFiles.push({ path: file.path, mode: "outline" });
+			continue;
+		}
+		activeFiles.push({
+			path: file.path,
+			mode: "full",
+			...(file.ranges === undefined ? {} : { ranges: file.ranges }),
+		});
+	}
+	return { cwd, source: "checkpoint", batchId, files: activeFiles, signal };
+}
+
+function formatList(items: readonly string[]): string {
+	return items.length ? items.map((item) => `- ${item}`).join("\n") : "(none)";
+}
+
+function isConversationEntry(entry: SessionEntry): entry is SessionMessageEntry {
+	return entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant");
+}
+
+function isUserMessageEntry(entry: SessionEntry): entry is SessionMessageEntry {
+	return entry.type === "message" && entry.message.role === "user";
+}

package/extensions/checkpoint/index.ts

@@ -0,0 +1,102 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { setCheckpointRowsVisible } from "../../shared/checkpoint-visibility.ts";
+import { CHECKPOINT_TOOL, registerCheckpointTool } from "./checkpoint.ts";
+import { createCheckpointBudget, type CheckpointBudgetNoticeLevel } from "./checkpoint-budget.ts";
+import { projectContextMessages } from "./messages.ts";
+import { CHECKPOINT_SYSTEM_GUIDANCE, formatCheckpointMessage } from "./prompt.ts";
+import checkpointSettings from "./settings.ts";
+
+export default function checkpointExtension(pi: ExtensionAPI): void {
+	const budget = createCheckpointBudget();
+	let checkpointSucceeded = false;
+
+	const resetBudget = (): void => {
+		checkpointSucceeded = false;
+		budget.reset();
+	};
+
+	registerCheckpointTool(pi);
+	pi.on("session_start", async (_event, ctx) => {
+		const settings = await loadTauExtensionSettings(ctx, checkpointSettings);
+		budget.configure(settings.checkpointTokenLimit);
+		setCheckpointRowsVisible(settings.showToolRows);
+	});
+	pi.on("session_shutdown", () => {
+		setCheckpointRowsVisible(false);
+		resetBudget();
+	});
+	pi.on("session_compact", resetBudget);
+	pi.on("session_tree", resetBudget);
+	pi.on("session_before_fork", resetBudget);
+	pi.on("session_before_switch", resetBudget);
+	pi.on("before_agent_start", (event) => ({
+		systemPrompt: `${event.systemPrompt}\n\n${CHECKPOINT_SYSTEM_GUIDANCE}`,
+	}));
+	pi.on("turn_start", (_event, ctx) => {
+		if (checkpointSucceeded) resetBudget();
+		const noticeLevel = budget.beginTurn(ctx.getContextUsage()?.tokens ?? null);
+		if (noticeLevel !== undefined) sendCheckpointBudgetNotice(pi, noticeLevel);
+	});
+	pi.on("turn_end", (_event, ctx) => {
+		if (checkpointSucceeded) {
+			resetBudget();
+			return;
+		}
+		const noticeLevel = budget.finishTurn(ctx.getContextUsage()?.tokens ?? null);
+		if (noticeLevel !== undefined) sendCheckpointBudgetNotice(pi, noticeLevel);
+	});
+	pi.on("tool_result", (event) => {
+		if (event.toolName === CHECKPOINT_TOOL && !event.isError) checkpointSucceeded = true;
+	});
+	pi.on("tool_call", (event) => {
+		if (checkpointSucceeded || !budget.shouldBlockTool(event.toolName, CHECKPOINT_TOOL)) return;
+		return {
+			block: true,
+			reason: formatCheckpointMessage(
+				"block",
+				"Checkpoint required before using other tools. Call checkpoint, then continue the user's work.",
+			),
+		};
+	});
+	pi.on("context", (event, ctx) => ({
+		messages: projectContextMessages(event.messages, ctx.sessionManager.buildContextEntries()),
+	}));
+}
+
+function sendCheckpointBudgetNotice(pi: ExtensionAPI, level: CheckpointBudgetNoticeLevel): void {
+	pi.sendMessage({
+		customType: "tau.checkpoint",
+		content: checkpointBudgetMessage(level),
+		display: false,
+		details: {
+			v: 1,
+			kind: "checkpoint.checkpoint-budget",
+			source: "checkpoint",
+			level,
+		},
+	});
+}
+
+function checkpointBudgetMessage(level: CheckpointBudgetNoticeLevel): string {
+	switch (level) {
+		case 50:
+			return formatCheckpointMessage(
+				"budget",
+				"Context usage reached 50% of the configured checkpoint limit. Continue current work and checkpoint when convenient.",
+				{ level: "50" },
+			);
+		case 75:
+			return formatCheckpointMessage(
+				"budget",
+				"Context usage reached 75% of the configured checkpoint limit. Run checkpoint soon. At 100%, non-checkpoint tool calls will be blocked until checkpoint succeeds.",
+				{ level: "75" },
+			);
+		case 100:
+			return formatCheckpointMessage(
+				"budget",
+				"Checkpoint budget reached. Call checkpoint now before using any other tool. Do not call other tools.",
+				{ level: "100" },
+			);
+	}
+}

package/extensions/checkpoint/messages.ts

@@ -0,0 +1,170 @@
+import type { AssistantMessage, TextContent, UserMessage } from "@earendil-works/pi-ai";
+import { sessionEntryToContextMessages, type ContextEvent, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { formatCheckpointMessage } from "./prompt.ts";
+
+type AgentMessage = ContextEvent["messages"][number];
+type ContextPair = { entry: SessionEntry; message: AgentMessage };
+
+const CHECKPOINT_KIND = "checkpoint.checkpoint";
+const MESSAGE_ID_METADATA_TYPE = "tau.checkpoint.message-id";
+
+type CheckpointMetadataMessage = Extract<AgentMessage, { role: "custom" }>;
+
+type CheckpointAnchor = {
+	call: ContextPair;
+	result: ContextPair;
+	resultIndex: number;
+	toolCallIds: Set<string>;
+};
+
+function pairsAlignWithMessages(pairs: readonly ContextPair[], messages: readonly AgentMessage[]): boolean {
+	if (pairs.length !== messages.length) return false;
+	return !pairs.some((pair, index) => {
+		const expected = messageKey(pair.message);
+		const actual = messageKey(messages[index]);
+		return expected === undefined || actual === undefined || expected !== actual;
+	});
+}
+
+function findCheckpointResult(
+	pairs: readonly ContextPair[],
+): { result: ContextPair; resultIndex: number; checkpointId: string; fileBatchId: string } | undefined {
+	for (let resultIndex = pairs.length - 1; resultIndex >= 0; resultIndex--) {
+		const result = pairs[resultIndex];
+		if (result.entry.type !== "message" || result.message.role !== "toolResult") continue;
+		const details = checkpointDetails(result.message.details);
+		if (details === undefined) continue;
+		return { result, resultIndex, checkpointId: details.checkpointId, fileBatchId: details.fileBatchId };
+	}
+	return undefined;
+}
+
+function resolveCheckpointCall(
+	pairs: readonly ContextPair[],
+	resultIndex: number,
+	checkpointId: string,
+): { call: ContextPair; toolCallIds: Set<string> } | "misaligned" {
+	let callIndex = resultIndex - 1;
+	while (callIndex >= 0 && !hasCheckpointToolCall(pairs[callIndex].message, checkpointId)) callIndex--;
+	if (callIndex < 0) return "misaligned";
+	const call = pairs[callIndex];
+	if (call.message.role !== "assistant") return "misaligned";
+	const toolCallIds = new Set<string>();
+	for (const part of call.message.content) {
+		if (part.type === "toolCall") toolCallIds.add(part.id);
+	}
+	return { call, toolCallIds };
+}
+
+function findCheckpointAnchor(pairs: readonly ContextPair[]): CheckpointAnchor | "misaligned" | undefined {
+	const found = findCheckpointResult(pairs);
+	if (found === undefined) return undefined;
+	const resolved = resolveCheckpointCall(pairs, found.resultIndex, found.checkpointId);
+	if (resolved === "misaligned") return "misaligned";
+	return {
+		call: resolved.call,
+		result: found.result,
+		resultIndex: found.resultIndex,
+		toolCallIds: resolved.toolCallIds,
+	};
+}
+
+function keepCheckpointPair(
+	checkpoint: CheckpointAnchor | undefined,
+	entry: SessionEntry,
+	message: AgentMessage,
+	index: number,
+): boolean {
+	if (checkpoint === undefined) return true;
+	if (index > checkpoint.resultIndex) return true;
+	if (entry.id === checkpoint.call.entry.id || entry.id === checkpoint.result.entry.id) return true;
+	return message.role === "toolResult" && checkpoint.toolCallIds.has(message.toolCallId);
+}
+
+function expandPairMessages(entry: SessionEntry, message: AgentMessage): AgentMessage[] {
+	if (entry.type === "message" && (entry.message.role === "user" || entry.message.role === "assistant")) {
+		if (message.role === "assistant" && extractConversationText(message) === "") return [message];
+		return [createMessageIdMetadata(entry.id, message), message];
+	}
+	return [message];
+}
+
+/** Prunes completed checkpoint history and adds hidden provider-context message IDs. */
+export function projectContextMessages(
+	messages: readonly AgentMessage[],
+	entries: readonly SessionEntry[],
+): AgentMessage[] {
+	const pairs: ContextPair[] = [];
+	for (const entry of entries) {
+		for (const message of sessionEntryToContextMessages(entry)) pairs.push({ entry, message });
+	}
+
+	const checkpoint = findCheckpointAnchor(pairs);
+	if (checkpoint === "misaligned") return [...messages];
+	if (checkpoint === undefined && !pairsAlignWithMessages(pairs, messages)) return [...messages];
+
+	return pairs
+		.filter(({ entry, message }, index) => keepCheckpointPair(checkpoint, entry, message, index))
+		.flatMap(({ entry, message }) => expandPairMessages(entry, message));
+}
+
+/** Extracts only the original text from a user or assistant message. */
+export function extractConversationText(message: AgentMessage): string | undefined {
+	if (message.role === "user") return userText(message);
+	if (message.role === "assistant") return assistantText(message);
+	return undefined;
+}
+
+function messageKey(message: AgentMessage): string | undefined {
+	return JSON.stringify(message, (key, value) => (key === "timestamp" ? undefined : value));
+}
+
+function checkpointDetails(details: unknown): { checkpointId: string; fileBatchId: string } | undefined {
+	if (typeof details !== "object" || details === null) return undefined;
+	const value = details as Record<string, unknown>;
+	if (
+		value.v !== 1 ||
+		value.kind !== CHECKPOINT_KIND ||
+		typeof value.checkpointId !== "string" ||
+		typeof value.fileBatchId !== "string"
+	)
+		return undefined;
+	return { checkpointId: value.checkpointId, fileBatchId: value.fileBatchId };
+}
+
+function hasCheckpointToolCall(message: AgentMessage, checkpointId: string): boolean {
+	return (
+		message.role === "assistant" &&
+		message.content.some((part) => part.type === "toolCall" && part.name === "checkpoint" && part.id === checkpointId)
+	);
+}
+
+function createMessageIdMetadata(id: string, message: AgentMessage): CheckpointMetadataMessage {
+	const role = message.role === "user" ? "user" : "assistant";
+	return {
+		role: "custom",
+		customType: MESSAGE_ID_METADATA_TYPE,
+		content: formatCheckpointMessage(
+			"message-id",
+			`<message-id>${JSON.stringify(id)}</message-id>\n<message-role>${role}</message-role>`,
+		),
+		display: false,
+		details: { v: 1, kind: "checkpoint.message-id", id, role },
+		timestamp: message.timestamp,
+	};
+}
+
+function userText(message: UserMessage): string {
+	if (typeof message.content === "string") return message.content;
+	return message.content
+		.filter((part): part is TextContent => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}
+
+function assistantText(message: AssistantMessage): string {
+	return message.content
+		.filter((part): part is TextContent => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}

package/extensions/checkpoint/prompt.ts

@@ -0,0 +1,24 @@
+/** Standing checkpoint guidance appended to the system prompt. */
+export const CHECKPOINT_SYSTEM_GUIDANCE = `## Checkpoint
+
+Checkpoint is a hidden context-management system. It retires disposable history so long-running work can continue without user-visible ceremony.
+
+Messages wrapped in \`<checkpoint>...</checkpoint>\` are internal control signals, not conversation with the user.
+
+- Never acknowledge checkpoint system messages, budget notices, blocked tools, checkpoint metadata or IDs, injected checkpoint files as a transition, or context replacement.
+- Never mention the checkpoint system itself.
+- When checkpoint asks you to run the checkpoint tool, or when non-checkpoint tools are blocked, call \`checkpoint\` and continue the user's work immediately. Do not narrate the system.
+- Stay focused on the work the user wants done.
+- Use exact IDs from \`<checkpoint kind="message-id">\` metadata only in \`checkpoint.keepMessages\`.`;
+
+/** Wraps an internal checkpoint control payload for the model. */
+export function formatCheckpointMessage(
+	kind: string,
+	body: string,
+	attributes: Readonly<Record<string, string>> = {},
+): string {
+	const attrs = Object.entries(attributes)
+		.map(([key, value]) => ` ${key}=${JSON.stringify(value)}`)
+		.join("");
+	return `<checkpoint kind=${JSON.stringify(kind)}${attrs}>\n${body}\n</checkpoint>`;
+}

package/extensions/checkpoint/settings.ts

@@ -0,0 +1,27 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+import { DEFAULT_CHECKPOINT_TOKEN_LIMIT } from "./checkpoint-budget.ts";
+
+export default defineTauExtensionSettings({
+	key: "checkpoint",
+	defaults: {
+		showToolRows: false as boolean,
+		checkpointTokenLimit: DEFAULT_CHECKPOINT_TOKEN_LIMIT,
+	},
+	schema: Type.Object(
+		{
+			showToolRows: Type.Optional(
+				Type.Boolean({
+					default: false,
+					description: "Show checkpoint and injected-file rows in the TUI for debugging.",
+				}),
+			),
+			checkpointTokenLimit: Type.Integer({
+				minimum: 1,
+				default: DEFAULT_CHECKPOINT_TOKEN_LIMIT,
+				description: "Context-token ceiling before a checkpoint is required.",
+			}),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/commit/commit-effort.ts

@@ -6,9 +6,9 @@ const LOW_EFFORT_MAX_CHANGED_LINES = 500;
 export function commitEffort(files: readonly Pick<DirtyFile, "changeSize">[]): ModelEffort {
 	let changedLines = 0;
 	for (const file of files) {
-		if (file.changeSize === "binary") return "medium";
+		if (file.changeSize === "binary") return "standard";
 		changedLines += file.changeSize;
-		if (changedLines > LOW_EFFORT_MAX_CHANGED_LINES) return "medium";
+		if (changedLines > LOW_EFFORT_MAX_CHANGED_LINES) return "standard";
 	}
-	return "low";
+	return "quick";
 }

package/extensions/commit/commit-plan.ts

@@ -54,7 +54,7 @@ export async function generatePlan(
 	const prompt = buildPlanPrompt(evidence, previousPlan, regenerationNote);
 	return generateToolValidated(
 		ctx,
-		await resolveEffortCandidates(ctx, commitEffort(evidence.files), true),
+		await resolveEffortCandidates(ctx, commitEffort(evidence.files), { includeParentModel: true }),
 		prompt,
 		COMMIT_PLAN_TOOL,
 		(input) => commitGroupsFromToolInput(input, evidence.files),
@@ -84,7 +84,7 @@ export async function regenerateMessage(
 	const prompt = buildMessagePrompt(evidence, selected, previousPlan, selectedGroupId, regenerationNote);
 	return generateValidated(
 		ctx,
-		await resolveEffortCandidates(ctx, commitEffort(selected), true),
+		await resolveEffortCandidates(ctx, commitEffort(selected), { includeParentModel: true }),
 		prompt,
 		requireCommitMessage,
 		undefined,