@shanepadgett/tau-agent 0.20.2 → 0.22.0

package/extensions/context-pruning/render.ts

@@ -1,7 +1,7 @@
 import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
 import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { Marker } from "@shanepadgett/tau-tui";
-import { parseContextPruneDetailsV1 } from "../../shared/context-pruning-state.ts";
+import { parseContextPruneDetailsV2 } from "../../shared/context-pruning-state.ts";
 import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.ts";
 import type { ContextPruneInput } from "./prune.ts";
 
@@ -10,22 +10,48 @@ const MAX_EXPANDED_LINE_CHARACTERS = 240;
 const MAX_EXPANDED_TEXT_CHARACTERS = 3_000;
 const MAX_WARNING_CHARACTERS = 1_000;
 
-export interface ContextPruningNudgeDetailsV1 {
-	v: 1;
-	kind: "automatic" | "manual";
-	percent: number | null;
-	boundary: number | null;
-	pressure: boolean;
-	anchorToolCallId: string | null;
-	growthBaselinePercent: number | null;
-}
+export type ContextPruningNudgeDetailsV2 =
+	| {
+			v: 2;
+			kind: "automatic";
+			percent: number;
+			boundary: number;
+			reminder: number;
+			tier: number;
+			tierCount: number;
+			tierFloor: number;
+			anchorToolCallId: string | null;
+			growthBaselinePercent: number;
+	  }
+	| {
+			v: 2;
+			kind: "manual";
+			percent: null;
+			boundary: null;
+			reminder: null;
+			tier: null;
+			tierCount: null;
+			tierFloor: null;
+			anchorToolCallId: string | null;
+			growthBaselinePercent: null;
+	  };
 
-export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPruningNudgeDetailsV1 | undefined {
+export function parseContextPruningNudgeDetailsV2(value: unknown): ContextPruningNudgeDetailsV2 | undefined {
 	if (!isRecord(value)) return undefined;
-	const keys = ["v", "kind", "percent", "boundary", "pressure", "anchorToolCallId", "growthBaselinePercent"];
+	const keys = [
+		"v",
+		"kind",
+		"percent",
+		"boundary",
+		"reminder",
+		"tier",
+		"tierCount",
+		"tierFloor",
+		"anchorToolCallId",
+		"growthBaselinePercent",
+	];
 	if (Object.keys(value).length !== keys.length || !keys.every((key) => Object.hasOwn(value, key))) return undefined;
-	if (value.v !== 1 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
-	if (typeof value.pressure !== "boolean") return undefined;
+	if (value.v !== 2 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
 	if (
 		value.anchorToolCallId !== null &&
 		(typeof value.anchorToolCallId !== "string" || value.anchorToolCallId.length === 0)
@@ -33,14 +59,25 @@ export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPrunin
 		return undefined;
 	}
 	if (value.kind === "manual") {
-		if (value.percent !== null || value.boundary !== null || value.growthBaselinePercent !== null || value.pressure)
+		if (
+			value.percent !== null ||
+			value.boundary !== null ||
+			value.reminder !== null ||
+			value.tier !== null ||
+			value.tierCount !== null ||
+			value.tierFloor !== null ||
+			value.growthBaselinePercent !== null
+		)
 			return undefined;
 		return {
-			v: 1,
+			v: 2,
 			kind: "manual",
 			percent: null,
 			boundary: null,
-			pressure: false,
+			reminder: null,
+			tier: null,
+			tierCount: null,
+			tierFloor: null,
 			anchorToolCallId: value.anchorToolCallId,
 			growthBaselinePercent: null,
 		};
@@ -48,25 +85,39 @@ export function parseContextPruningNudgeDetailsV1(value: unknown): ContextPrunin
 	if (
 		!isPercent(value.percent) ||
 		!isBoundary(value.boundary) ||
+		!isReminder(value.reminder) ||
+		!isTier(value.tier) ||
+		!isTier(value.tierCount) ||
+		!isTierFloor(value.tierFloor) ||
 		!isPercent(value.growthBaselinePercent) ||
 		value.boundary > value.percent ||
-		value.growthBaselinePercent > value.percent
+		value.boundary <= value.growthBaselinePercent ||
+		value.tier > value.tierCount ||
+		value.tierFloor > value.tierCount ||
+		value.tier !== Math.max(Math.min(value.reminder, value.tierCount), value.tierFloor) ||
+		(value.anchorToolCallId === null && value.growthBaselinePercent !== 0)
 	) {
 		return undefined;
 	}
+	const interval = (value.boundary - value.growthBaselinePercent) / value.reminder;
+	if (!Number.isInteger(interval) || interval < 1 || interval > 100 || value.percent - value.boundary >= interval)
+		return undefined;
 	return {
-		v: 1,
+		v: 2,
 		kind: "automatic",
 		percent: value.percent,
 		boundary: value.boundary,
-		pressure: value.pressure,
+		reminder: value.reminder,
+		tier: value.tier,
+		tierCount: value.tierCount,
+		tierFloor: value.tierFloor,
 		anchorToolCallId: value.anchorToolCallId,
 		growthBaselinePercent: value.growthBaselinePercent,
 	};
 }
 
 export function renderContextPruningNudge(details: unknown, theme: Theme): Marker | undefined {
-	const parsed = parseContextPruningNudgeDetailsV1(details);
+	const parsed = parseContextPruningNudgeDetailsV2(details);
 	if (!parsed) return undefined;
 	return new Marker({
 		theme,
@@ -75,7 +126,10 @@ export function renderContextPruningNudge(details: unknown, theme: Theme): Marke
 		parts:
 			parsed.kind === "manual"
 				? ["Prune requested."]
-				: [`${parsed.percent}%`, ...(parsed.pressure ? ["Prune suggested."] : [])],
+				: [
+						`${parsed.percent}%`,
+						...(parsed.tier === parsed.tierCount ? ["Prune now."] : parsed.tier > 1 ? ["Prune soon."] : []),
+					],
 	});
 }
 
@@ -108,7 +162,7 @@ export function renderContextPruneResult(
 	lastComponent: unknown,
 ): Text {
 	const component = lastComponent instanceof Text ? lastComponent : new Text("", 0, 0);
-	const details = parseContextPruneDetailsV1(result.details);
+	const details = parseContextPruneDetailsV2(result.details);
 	if (!details) {
 		component.setText(
 			theme.fg(
@@ -118,27 +172,21 @@ export function renderContextPruneResult(
 		);
 		return component;
 	}
-	if (details.status === "skipped") {
-		component.setText(
-			theme.fg("warning", boundedText(firstResultText(result) || "Prune skipped", MAX_WARNING_CHARACTERS)),
-		);
-		return component;
-	}
-
-	const pruned = details.newlyPrunedToolCallIds.length + details.newlyPrunedAutoreadRowIds.length;
+	const pruned = details.prunedToolCallIds.length + details.prunedAutoreadRowIds.length;
 	const retained = details.retainedToolCallIds.length + details.retainedAutoreadRowIds.length;
 	let text = theme.fg(
-		"success",
-		`Pruned ${pruned} · retained ${retained} · refreshed ${details.refreshedFiles.length} · deferred ${details.deferredFiles.length}`,
+		details.warnings.length === 0 ? "success" : "warning",
+		`Checkpoint · pruned ${pruned} · retained ${retained} · refreshed ${details.refreshedFiles.length} · deferred ${details.deferredFiles.length}${details.warnings.length === 0 ? "" : ` · warnings ${details.warnings.length}`}`,
 	);
 	if (expanded) {
 		const lines = [
-			...details.newlyPrunedToolCallIds.map((id) => `pruned tool: ${id}`),
-			...details.newlyPrunedAutoreadRowIds.map((id) => `pruned autoread: ${id}`),
+			...details.prunedToolCallIds.map((id) => `pruned tool: ${id}`),
+			...details.prunedAutoreadRowIds.map((id) => `pruned autoread: ${id}`),
 			...details.retainedToolCallIds.map((id) => `retained tool: ${id}`),
 			...details.retainedAutoreadRowIds.map((id) => `retained autoread: ${id}`),
 			...details.refreshedFiles.map((file) => `refreshed: ${file.path} (${file.rowId})`),
 			...details.deferredFiles.map((file) => `deferred: ${file.path} — ${file.reason}; when ${file.relevantWhen}`),
+			...details.warnings.map((warning) => `warning: ${warning}`),
 		];
 		const shown = lines.slice(0, MAX_EXPANDED_ITEMS).map((line) => boundedText(line, MAX_EXPANDED_LINE_CHARACTERS));
 		if (lines.length > shown.length) shown.push(`… ${lines.length - shown.length} more`);
@@ -174,6 +222,18 @@ function isBoundary(value: unknown): value is number {
 	return isPercent(value) && value > 0;
 }
 
+function isReminder(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 100;
+}
+
+function isTier(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= 5;
+}
+
+function isTierFloor(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 5;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/extensions/context-pruning/settings.ts

@@ -1,13 +1,18 @@
 import { Type } from "typebox";
 import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
 
+const DEFAULT_NUDGE_INSTRUCTIONS: [string, ...string[]] = [
+	"No prune is required yet unless broad exploration has converged or substantial evidence is already irrelevant. Continue coherent work.",
+	"Move toward a pruning point now. Finish the current coherent step, then prune before starting another broad exploration. Managed context is materially increasing model cost.",
+	"Prune now before further tool work. Continuing with stale managed context is wasting money.",
+];
+
 export default defineTauExtensionSettings({
 	key: "contextPruning",
 	defaults: {
 		enabled: true as boolean,
 		nudgeEveryPercent: 20 as number,
-		pressurePercent: 50 as number,
-		minimumReclaimTokens: 8000 as number,
+		nudgeInstructions: DEFAULT_NUDGE_INSTRUCTIONS,
 	},
 	schema: Type.Object(
 		{
@@ -20,19 +25,13 @@ export default defineTauExtensionSettings({
 					description: "Context growth interval between automatic pruning hints.",
 				}),
 			),
-			pressurePercent: Type.Optional(
-				Type.Integer({
-					default: 50,
-					minimum: 1,
-					maximum: 99,
-					description: "Context usage above which pruning hints become urgent.",
-				}),
-			),
-			minimumReclaimTokens: Type.Optional(
-				Type.Integer({
-					default: 8000,
-					minimum: 1,
-					description: "Minimum estimated tokens a prune must reclaim.",
+			nudgeInstructions: Type.Optional(
+				Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), {
+					default: DEFAULT_NUDGE_INSTRUCTIONS,
+					minItems: 1,
+					maxItems: 5,
+					description:
+						"Ordered automatic pruning instructions. Later reminders repeat the final instruction, and the final tier requires an anchor before further tool work.",
 				}),
 			),
 		},

package/extensions/explore/read-cache.ts

@@ -67,6 +67,7 @@ export function createReadCacheStore(): ReadCacheStore {
 			}
 			const pruning = replayContextPruningState(manager.getBranch());
 			const ignoredRowIds = new Set([...pruning.prunedToolCallIds, ...pruning.prunedAutoreadRowIds]);
+			for (const id of pruning.retainedToolCallIds) ignoredRowIds.delete(id);
 			const state = replayReadCache(manager.buildContextEntries(), ctx.cwd, ignoredRowIds);
 			const trust = state.scopeTrust.get(pathKey)?.get(scopeKey);
 			return {
@@ -127,17 +128,21 @@ export function replayReadCache(
 		if (entry.type === "message" && "message" in entry) message = entry.message;
 		else if (entry.type === "custom_message") message = entry;
 		else continue;
-		const parsedMeta = readMetaFromMessage(message);
-		if (parsedMeta) {
-			const rowId = readRowId(message);
-			if (rowId && ignoredRowIds.has(rowId)) continue;
+		const candidates = carriedFileMessages(message);
+		let acceptedCarryForward = false;
+		for (const candidate of candidates ?? [message]) {
+			const parsedMeta = readMetaFromMessage(candidate);
+			if (!parsedMeta) continue;
+			acceptedCarryForward = true;
+			const candidateRowId = readRowId(candidate);
+			if (candidateRowId && ignoredRowIds.has(candidateRowId)) continue;
 			const pathKey = resolve(cwd, parsedMeta.pathKey);
 			const meta = pathKey === parsedMeta.pathKey ? parsedMeta : { ...parsedMeta, pathKey };
-			if (rowId && applyReadMeta(trust, failedPatchRecoveryPaths, message, meta, rowId)) {
+			if (candidateRowId && applyReadMeta(trust, failedPatchRecoveryPaths, candidate, meta, candidateRowId)) {
 				const acceptedTrust = trust.get(meta.pathKey)?.get(meta.scopeKey);
 				if (acceptedTrust) {
 					acceptedRows.push({
-						rowId,
+						rowId: candidateRowId,
 						pathKey: meta.pathKey,
 						scopeKey: meta.scopeKey,
 						meta,
@@ -145,8 +150,8 @@ export function replayReadCache(
 					});
 				}
 			}
-			continue;
 		}
+		if (acceptedCarryForward) continue;
 		for (const path of failedPatchPaths(message, cwd)) failedPatchRecoveryPaths.add(path);
 	}
 	const completeFileChains = new Map<string, CompleteFileDependencyChain>();
@@ -163,6 +168,25 @@ export function replayReadCache(
 	return { scopeTrust: trust, acceptedRows, completeFileChains, failedPatchRecoveryPaths };
 }
 
+function carriedFileMessages(message: unknown): unknown[] | undefined {
+	if (!isRecord(message) || message.role !== "toolResult" || message.toolName !== "context_prune") return undefined;
+	if (!isRecord(message.details) || message.details.v !== 2 || !Array.isArray(message.details.refreshedFiles)) {
+		return undefined;
+	}
+	if (!Array.isArray(message.content)) {
+		return undefined;
+	}
+	const messages: unknown[] = [];
+	for (let index = 0; index < message.details.refreshedFiles.length; index += 1) {
+		const file = message.details.refreshedFiles[index];
+		const part = message.content[index + 1];
+		if (!isRecord(file) || !isRecord(file.autoreadDetails)) continue;
+		if (!isRecord(part) || part.type !== "text" || typeof part.text !== "string") continue;
+		messages.push({ customType: "tau.autoread", content: part.text, details: file.autoreadDetails });
+	}
+	return messages;
+}
+
 function applyReadMeta(
 	trust: Map<string, Map<string, ReadCacheScopeTrust>>,
 	failedPatchRecoveryPaths: Set<string>,

package/extensions/handoff/README.md

@@ -0,0 +1,7 @@
+# Handoff
+
+Start a fresh chat from an idea already understood in the current conversation.
+
+Run `/handoff <goal for the new chat>`. Tau generates a focused opening prompt, starts a new linked session, and asks Tau autoread to preload the relevant project files selected from the current context. The prompt stays in the editor so you can review or change it before submitting.
+
+The original session remains available through Pi's session history. Press Escape while Tau generates the handoff to cancel.

package/extensions/handoff/index.ts

@@ -0,0 +1,145 @@
+import { randomUUID } from "node:crypto";
+import {
+	BorderedLoader,
+	buildSessionContext,
+	convertToLlm,
+	type ExtensionAPI,
+	serializeConversation,
+} from "@earendil-works/pi-coding-agent";
+import { prepareAutoreadMessage, type AutoreadDetails } from "../explore/autoread.ts";
+import { generateToolValidated, resolveCandidates } from "../../shared/model-fallback/index.ts";
+import { errorText } from "../../shared/text.ts";
+import { buildHandoffRequest, type HandoffDraft, handoffDraftFromToolInput, HANDOFF_TOOL } from "./model.ts";
+
+export default function handoffExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("handoff", {
+		description: "Start a fresh chat with a generated prompt and autoread files",
+		handler: async (args, ctx) => {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/handoff requires TUI mode.", "error");
+				return;
+			}
+			const goal = args.trim();
+			if (!goal) {
+				ctx.ui.notify("Usage: /handoff <goal for the new chat>", "error");
+				return;
+			}
+			await ctx.waitForIdle();
+			const model = ctx.model;
+			if (!model) {
+				ctx.ui.notify("No model selected.", "error");
+				return;
+			}
+			const currentSessionFile = ctx.sessionManager.getSessionFile();
+			if (!currentSessionFile) {
+				ctx.ui.notify("The current session must be persisted before handoff.", "error");
+				return;
+			}
+			const messages = buildSessionContext(ctx.sessionManager.getEntries(), ctx.sessionManager.getLeafId()).messages;
+			if (messages.length === 0) {
+				ctx.ui.notify("No conversation context to hand off.", "error");
+				return;
+			}
+
+			let generationError: string | undefined;
+			const draft = await ctx.ui.custom<HandoffDraft | null>((tui, theme, _keys, done) => {
+				const loader = new BorderedLoader(tui, theme, "Generating handoff");
+				loader.onAbort = () => done(null);
+				void (async () => {
+					try {
+						const thinking = pi.getThinkingLevel();
+						const candidates = await resolveCandidates(
+							ctx,
+							[
+								{
+									provider: model.provider,
+									model: model.id,
+									reasoning: thinking === "off" ? undefined : thinking,
+								},
+							],
+							false,
+						);
+						const conversation = serializeConversation(convertToLlm(messages));
+						const result = await generateToolValidated(
+							{ ui: ctx.ui, signal: loader.signal },
+							candidates,
+							buildHandoffRequest(conversation, goal, ctx.cwd),
+							HANDOFF_TOOL,
+							handoffDraftFromToolInput,
+							(error, output) =>
+								[
+									`The handoff failed validation: ${error.message}`,
+									`Call ${HANDOFF_TOOL.name} again with corrected arguments only.`,
+									"Previous response:",
+									output,
+								].join("\n"),
+							{ maxAttempts: 3 },
+						);
+						done(result);
+					} catch (error) {
+						if (!loader.signal.aborted) generationError = errorText(error);
+						done(null);
+					}
+				})();
+				return loader;
+			});
+
+			if (!draft) {
+				ctx.ui.notify(
+					generationError ? `Handoff failed: ${generationError}` : "Handoff cancelled.",
+					generationError ? "error" : "info",
+				);
+				return;
+			}
+
+			const batchId = randomUUID();
+			const cwd = ctx.cwd;
+			const result = await ctx.newSession({
+				parentSession: currentSessionFile,
+				setup: async (sessionManager) => {
+					const messages = await Promise.all(
+						draft.files.map(async (path, index) => {
+							const details = {
+								rowId: `${batchId}:${index}`,
+								path,
+								cwd,
+								source: "handoff",
+								batchId,
+							};
+							try {
+								return await prepareAutoreadMessage({
+									...details,
+									signal: undefined,
+									isLifecycleCurrent: () => true,
+								});
+							} catch (error) {
+								const message = errorText(error);
+								return {
+									customType: "tau.autoread" as const,
+									content: `${path}\nAutoread failed: ${message}`,
+									display: true as const,
+									details: { ...details, status: "failed", error: message } satisfies AutoreadDetails,
+								};
+							}
+						}),
+					);
+					for (const message of messages) {
+						sessionManager.appendCustomMessageEntry(
+							message.customType,
+							message.content,
+							message.display,
+							message.details,
+						);
+					}
+				},
+				withSession: async (replacementCtx) => {
+					replacementCtx.ui.setEditorText(draft.prompt);
+					replacementCtx.ui.notify("Handoff ready. Review the draft and submit when ready.", "info");
+				},
+			});
+			if (result.cancelled) {
+				ctx.ui.notify("New session cancelled.", "info");
+			}
+		},
+	});
+}

package/extensions/handoff/model.ts

@@ -0,0 +1,71 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import { posix } from "node:path";
+import { Type } from "typebox";
+
+export interface HandoffDraft {
+	prompt: string;
+	files: string[];
+}
+
+export const HANDOFF_TOOL = {
+	name: "submit_handoff",
+	description: "Submit the prompt and project files for the new chat. This is the only allowed response.",
+	parameters: Type.Object(
+		{
+			prompt: Type.String({ description: "Self-contained opening prompt for the new chat" }),
+			files: Type.Array(
+				Type.String({ description: "Project-relative file path already known from the current conversation" }),
+				{ description: "Focused files Tau should autoread in the new chat" },
+			),
+		},
+		{ additionalProperties: false },
+	),
+} satisfies Tool;
+
+export function buildHandoffRequest(conversation: string, goal: string, cwd: string): string {
+	return [
+		"You prepare a handoff from the current coding chat into a fresh chat.",
+		`Call ${HANDOFF_TOOL.name} exactly once. Write no prose outside the tool call.`,
+		"",
+		"Build the handoff only from the supplied conversation and goal. Do not research, invent findings, or assume file contents that are absent from the conversation.",
+		"The prompt must give the new agent the relevant decisions, progress, constraints, unresolved questions, and exact next task.",
+		"Keep it focused. The selected files will be autoread separately, so summarize why they matter without copying their contents into the prompt.",
+		`Every file must be a path under ${cwd}, relative to that directory, and must already be known from the conversation. Return only files relevant to the goal.`,
+		"Return an empty files array when no known file is clearly relevant.",
+		"",
+		"## Handoff goal",
+		goal,
+		"",
+		"## Current effective conversation",
+		conversation,
+	].join("\n");
+}
+
+export function handoffDraftFromToolInput(input: unknown): HandoffDraft {
+	if (!input || typeof input !== "object") throw new Error("Handoff output must be an object.");
+	const record = input as Record<string, unknown>;
+	if (typeof record.prompt !== "string" || !record.prompt.trim()) {
+		throw new Error("Handoff prompt must be a non-empty string.");
+	}
+	if (!Array.isArray(record.files) || !record.files.every((path) => typeof path === "string")) {
+		throw new Error("Handoff files must be an array of strings.");
+	}
+
+	const files: string[] = [];
+	for (const rawPath of record.files) {
+		const path = posix.normalize(rawPath.trim().replace(/^@/, "").replace(/^\.\//, ""));
+		if (
+			path === "." ||
+			path.startsWith("/") ||
+			/^[a-z]:\//i.test(path) ||
+			path === ".." ||
+			path.startsWith("../") ||
+			path.includes("\\")
+		) {
+			throw new Error(`Handoff file must be a project-relative path: ${rawPath}`);
+		}
+		if (!files.includes(path)) files.push(path);
+	}
+
+	return { prompt: record.prompt.trim(), files };
+}