@shanepadgett/tau-agent 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.37.0",
+	"version": "0.39.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -34,13 +34,13 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@ast-grep/wasm": "0.45.0",
-		"@shanepadgett/tau-tui": "0.37.0",
+		"@ast-grep/wasm": "0.45.1",
+		"@shanepadgett/tau-tui": "0.39.0",
 		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
-		"smol-toml": "1.7.1",
+		"smol-toml": "1.8.0",
 		"unbash": "4.0.10",
-		"web-tree-sitter": "0.26.11"
+		"web-tree-sitter": "0.26.12"
 	},
 	"peerDependencies": {
 		"@earendil-works/pi-ai": "*",

package/schemas/tau.schema.json

@@ -12,22 +12,17 @@
 		"extensions": {
 			"type": "object",
 			"properties": {
-				"checkpoint": {
+				"autoCompact": {
 					"type": "object",
 					"required": [
-						"checkpointTokenLimit"
+						"tokenLimit"
 					],
 					"properties": {
-						"showToolRows": {
-							"type": "boolean",
-							"default": false,
-							"description": "Show checkpoint and injected-file rows in the TUI for debugging."
-						},
-						"checkpointTokenLimit": {
+						"tokenLimit": {
 							"type": "integer",
 							"minimum": 1,
-							"default": 150000,
-							"description": "Context-token ceiling before a checkpoint is required."
+							"default": 175000,
+							"description": "Absolute context-token count that triggers compaction before the next model turn."
 						}
 					},
 					"additionalProperties": false
@@ -254,16 +249,31 @@
 				},
 				"soul": {
 					"type": "object",
+					"required": [
+						"overseer"
+					],
 					"properties": {
-						"ponytail": {
-							"type": "boolean",
-							"default": true,
-							"description": "Add the lazy-senior-dev build ethos to Tau's system prompt."
-						},
-						"simplified": {
-							"type": "boolean",
-							"default": true,
-							"description": "Add Simplified Technical English and small-chunk explanations to Tau's system prompt."
+						"overseer": {
+							"type": "object",
+							"required": [
+								"enabled",
+								"toolCallInterval"
+							],
+							"properties": {
+								"enabled": {
+									"type": "boolean",
+									"default": true,
+									"description": "Run hidden primary-directive reviews during long tool-using work."
+								},
+								"toolCallInterval": {
+									"type": "integer",
+									"minimum": 1,
+									"maximum": 100,
+									"default": 20,
+									"description": "Unreviewed tool calls required before the next primary-directive review."
+								}
+							},
+							"additionalProperties": false
 						}
 					},
 					"additionalProperties": false

package/extensions/checkpoint/README.md

@@ -1,9 +0,0 @@
-# Checkpoint
-
-Keeps long-running agent work focused by letting the agent checkpoint durable working context while disposable conversation history is retired. The agent writes a short resume directive that is appended to the hidden continuation message after each checkpoint.
-
-Checkpoint rows are hidden by default. Set `extensions.checkpoint.showToolRows` to `true` before `/reload` to watch checkpoint and newly injected-file rows while working. Existing injected-file rows keep their saved display state.
-
-Checkpoint nudges the agent at 50% and 75% of `extensions.checkpoint.checkpointTokenLimit`, which defaults to 150,000 context tokens. At the limit, it blocks non-checkpoint tools until the agent checkpoints.
-
-After changing this extension, run `/reload` before testing it.

package/extensions/checkpoint/checkpoint-budget.ts

@@ -1,66 +0,0 @@
-export const DEFAULT_CHECKPOINT_TOKEN_LIMIT = 150_000;
-
-export type CheckpointBudgetLevel = 0 | 50 | 75 | 100;
-export type CheckpointBudgetNoticeLevel = Exclude<CheckpointBudgetLevel, 0>;
-
-export interface CheckpointBudget {
-	configure(limit: number): void;
-	beginTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined;
-	finishTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined;
-	shouldBlockTool(toolName: string, checkpointToolName: string): boolean;
-	reset(): void;
-}
-
-export function createCheckpointBudget(initialLimit = DEFAULT_CHECKPOINT_TOKEN_LIMIT): CheckpointBudget {
-	let limit = validateLimit(initialLimit);
-	let highestNoticed: CheckpointBudgetLevel = 0;
-	let forced = false;
-
-	return {
-		configure(nextLimit: number): void {
-			limit = validateLimit(nextLimit);
-			highestNoticed = 0;
-			forced = false;
-		},
-
-		beginTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
-			return observe(tokens);
-		},
-
-		finishTurn(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
-			return observe(tokens);
-		},
-
-		shouldBlockTool(toolName: string, checkpointToolName: string): boolean {
-			return forced && toolName !== checkpointToolName;
-		},
-
-		reset(): void {
-			highestNoticed = 0;
-			forced = false;
-		},
-	};
-
-	function observe(tokens: number | null): CheckpointBudgetNoticeLevel | undefined {
-		if (tokens === null) return undefined;
-		const level = levelFor(tokens, limit);
-		if (level === 100) forced = true;
-		if (level <= highestNoticed) return undefined;
-		highestNoticed = level;
-		return level === 0 ? undefined : level;
-	}
-}
-
-function levelFor(tokens: number, limit: number): CheckpointBudgetLevel {
-	if (tokens >= limit) return 100;
-	if (tokens >= limit * 0.75) return 75;
-	if (tokens >= limit * 0.5) return 50;
-	return 0;
-}
-
-function validateLimit(limit: number): number {
-	if (!Number.isSafeInteger(limit) || limit <= 0) {
-		throw new Error("Checkpoint token limit must be a positive safe integer");
-	}
-	return limit;
-}

package/extensions/checkpoint/checkpoint.ts

@@ -1,279 +0,0 @@
-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

@@ -1,102 +0,0 @@
-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" },
-			);
-	}
-}