@shanepadgett/tau-agent 0.26.0 → 0.27.0

package/schemas/tau.schema.json

@@ -61,12 +61,11 @@
 							"default": true,
 							"description": "Enable context pruning."
 						},
-						"nudgeEveryPercent": {
+						"nudgeEveryTokens": {
 							"type": "integer",
-							"default": 20,
+							"default": 30000,
 							"minimum": 1,
-							"maximum": 100,
-							"description": "Context growth interval between automatic pruning hints."
+							"description": "Active-context token interval between automatic pruning hints."
 						},
 						"nudgeInstructions": {
 							"type": "array",
@@ -87,6 +86,47 @@
 					},
 					"additionalProperties": false
 				},
+				"explore": {
+					"type": "object",
+					"required": [
+						"readGate"
+					],
+					"properties": {
+						"readGate": {
+							"type": "object",
+							"required": [
+								"includeGlobs",
+								"excludeGlobs"
+							],
+							"properties": {
+								"includeGlobs": {
+									"type": "array",
+									"items": {
+										"type": "string"
+									},
+									"default": [
+										"**/*"
+									],
+									"description": "Working-directory-relative supported source paths that require a structural attempt before read."
+								},
+								"excludeGlobs": {
+									"type": "array",
+									"items": {
+										"type": "string"
+									},
+									"default": [
+										"**/*.md",
+										"**/*.markdown",
+										"**/*.mdown"
+									],
+									"description": "Working-directory-relative paths excluded from the Explore read gate. Exclusions win."
+								}
+							},
+							"additionalProperties": false
+						}
+					},
+					"additionalProperties": false
+				},
 				"footer": {
 					"type": "object",
 					"properties": {

package/shared/bounded-text-result.ts

@@ -0,0 +1,304 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	truncateTail,
+} from "@earendil-works/pi-coding-agent";
+import {
+	TemporaryOutputError,
+	type TemporaryOutputStore,
+	type TemporaryOutputWriter,
+} from "./temporary-output-store.ts";
+
+export type BoundedTextStrategy = "head" | "tail" | "completeBlocks";
+
+export interface BoundedTextOverflowDetails {
+	strategy: BoundedTextStrategy;
+	truncated: boolean;
+	shownLines: number;
+	totalLines: number;
+	shownBytes: number;
+	totalBytes: number;
+	fullOutputComplete: boolean;
+	temporaryPath: string | undefined;
+	failure: "quota" | "write" | undefined;
+}
+
+export interface BoundedTextResult {
+	content: string;
+	overflow: BoundedTextOverflowDetails;
+	visibleUnitIds: string[];
+}
+
+export function truncateBoundedHead(content: string): ReturnType<typeof truncateHead> {
+	return truncateHead(content, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+}
+
+interface VisibleBlock {
+	id: string | undefined;
+	label: string;
+	text: string;
+}
+
+export class BoundedTextResultBuilder {
+	private readonly store: TemporaryOutputStore;
+	private readonly strategy: BoundedTextStrategy;
+	private snapshot = "";
+	private blocks: VisibleBlock[] = [];
+	private requiredBlocks: VisibleBlock[] = [];
+	private totalBytes = 0;
+	private newlineCount = 0;
+	private hasContent = false;
+	private endsWithNewline = false;
+	private overflowed = false;
+	private modelClosed = false;
+	private oversizedBlockLabel: string | undefined;
+	private output: TemporaryOutputWriter | undefined;
+	private persistenceFailure: "quota" | "write" | undefined;
+	private finished = false;
+
+	constructor(store: TemporaryOutputStore, strategy: BoundedTextStrategy) {
+		this.store = store;
+		this.strategy = strategy;
+	}
+
+	async append(text: string): Promise<void> {
+		if (this.strategy === "completeBlocks") throw new Error("Complete-block results require appendBlock");
+		this.requireOpen();
+		this.count(text);
+		if (!this.overflowed) {
+			const candidate = `${this.snapshot}${text}`;
+			const truncation = this.strategy === "head" ? truncateHead(candidate) : truncateTail(candidate);
+			this.snapshot = truncation.content;
+			if (!truncation.truncated) return;
+			this.overflowed = true;
+			await this.persist(candidate);
+			return;
+		}
+		if (this.strategy === "tail") this.snapshot = truncateTail(`${this.snapshot}${text}`).content;
+		await this.persist(text);
+	}
+
+	async appendBlock(id: string | undefined, label: string, text: string): Promise<void> {
+		if (this.strategy !== "completeBlocks") throw new Error("Text results require append");
+		this.requireOpen();
+		const prefix = this.hasContent ? "\n\n" : "";
+		const chunk = `${prefix}${text}`;
+		this.count(chunk);
+
+		if (!this.modelClosed) {
+			const candidate = `${this.snapshot}${chunk}`;
+			if (!truncateHead(candidate).truncated) {
+				this.snapshot = candidate;
+				this.blocks.push({ id, label, text });
+				return;
+			}
+			this.modelClosed = true;
+			this.overflowed = true;
+			if (this.blocks.length === 0) this.oversizedBlockLabel = label.replaceAll(/[\r\n]/g, " ");
+			await this.persist(candidate);
+			return;
+		}
+		await this.persist(chunk);
+	}
+
+	async appendRequiredBlock(label: string, text: string): Promise<void> {
+		if (this.strategy !== "completeBlocks") throw new Error("Required blocks need complete-block retention");
+		this.requireOpen();
+		const block = { id: undefined, label, text };
+		this.requiredBlocks.push(block);
+		const prefix = this.hasContent ? "\n\n" : "";
+		const chunk = `${prefix}${text}`;
+		this.count(chunk);
+		if (!this.overflowed) {
+			const candidate = `${this.snapshot}${chunk}`;
+			if (!truncateHead(candidate).truncated) {
+				this.snapshot = candidate;
+				return;
+			}
+			this.overflowed = true;
+			this.modelClosed = true;
+			await this.persist(candidate);
+			return;
+		}
+		await this.persist(chunk);
+	}
+
+	async finish(): Promise<BoundedTextResult> {
+		this.requireOpen();
+		this.finished = true;
+		let temporaryPath: string | undefined;
+		if (this.output) {
+			try {
+				temporaryPath = await this.output.finish();
+			} catch (error) {
+				this.persistenceFailure = error instanceof TemporaryOutputError ? error.code : "write";
+			}
+			this.output = undefined;
+		}
+
+		const totalLines = lineCount(this.hasContent, this.newlineCount, this.endsWithNewline);
+		if (!this.overflowed) {
+			return {
+				content: this.snapshot,
+				overflow: {
+					strategy: this.strategy,
+					truncated: false,
+					shownLines: totalLines,
+					totalLines,
+					shownBytes: this.totalBytes,
+					totalBytes: this.totalBytes,
+					fullOutputComplete: true,
+					temporaryPath: undefined,
+					failure: undefined,
+				},
+				visibleUnitIds: this.blocks.flatMap((block) => (block.id === undefined ? [] : [block.id])),
+			};
+		}
+
+		if (this.strategy === "completeBlocks") {
+			return this.finishBlocks(totalLines, temporaryPath);
+		}
+		return this.finishText(totalLines, temporaryPath);
+	}
+
+	async abort(): Promise<void> {
+		this.finished = true;
+		const output = this.output;
+		this.output = undefined;
+		if (output) await output.abort();
+	}
+
+	private finishBlocks(totalLines: number, temporaryPath: string | undefined): BoundedTextResult {
+		const blocks = [...this.blocks];
+		const required = this.requiredBlocks.map((block) => block.text).join("\n\n");
+		let retained = [...blocks.map((block) => block.text), required].filter(Boolean).join("\n\n");
+		let shownBytes = Buffer.byteLength(retained);
+		let shownLines = textLineCount(retained);
+		let notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		const oversized = this.oversizedBlockLabel
+			? `[File block omitted because it exceeds the model-output budget: ${this.oversizedBlockLabel}. Run a non-recursive outline for that file.]`
+			: "";
+		while (blocks.length > 0 && truncateHead([retained, oversized, notice].filter(Boolean).join("\n\n")).truncated) {
+			blocks.pop();
+			retained = [...blocks.map((block) => block.text), required].filter(Boolean).join("\n\n");
+			shownBytes = Buffer.byteLength(retained);
+			shownLines = textLineCount(retained);
+			notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		}
+		let content = [retained, oversized, notice].filter(Boolean).join("\n\n");
+		if (truncateHead(content).truncated) content = truncateHead(content).content;
+		return {
+			content,
+			overflow: this.overflowDetails(shownLines, shownBytes, totalLines, temporaryPath),
+			visibleUnitIds: blocks.flatMap((block) => (block.id === undefined ? [] : [block.id])),
+		};
+	}
+
+	private finishText(totalLines: number, temporaryPath: string | undefined): BoundedTextResult {
+		let retained = this.snapshot;
+		let shownBytes = Buffer.byteLength(retained);
+		let shownLines = textLineCount(retained);
+		let notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		for (let iteration = 0; iteration < 3; iteration += 1) {
+			const noticeLines = textLineCount(notice) + 1;
+			const noticeBytes = Buffer.byteLength(notice) + 2;
+			const options = {
+				maxLines: Math.max(0, DEFAULT_MAX_LINES - noticeLines),
+				maxBytes: Math.max(0, DEFAULT_MAX_BYTES - noticeBytes),
+			};
+			retained = (
+				this.strategy === "head" ? truncateHead(this.snapshot, options) : truncateTail(this.snapshot, options)
+			).content;
+			shownBytes = Buffer.byteLength(retained);
+			shownLines = textLineCount(retained);
+			notice = this.notice(shownLines, shownBytes, totalLines, temporaryPath);
+		}
+		return {
+			content: [retained, notice].filter(Boolean).join("\n\n"),
+			overflow: this.overflowDetails(shownLines, shownBytes, totalLines, temporaryPath),
+			visibleUnitIds: [],
+		};
+	}
+
+	private overflowDetails(
+		shownLines: number,
+		shownBytes: number,
+		totalLines: number,
+		temporaryPath: string | undefined,
+	): BoundedTextOverflowDetails {
+		return {
+			strategy: this.strategy,
+			truncated: true,
+			shownLines,
+			totalLines,
+			shownBytes,
+			totalBytes: this.totalBytes,
+			fullOutputComplete: temporaryPath !== undefined && this.persistenceFailure === undefined,
+			temporaryPath,
+			failure: this.persistenceFailure,
+		};
+	}
+
+	private notice(
+		shownLines: number,
+		shownBytes: number,
+		totalLines: number,
+		temporaryPath: string | undefined,
+	): string {
+		return formatBoundedTextOverflow({
+			strategy: this.strategy,
+			truncated: true,
+			shownLines,
+			totalLines,
+			shownBytes,
+			totalBytes: this.totalBytes,
+			fullOutputComplete: temporaryPath !== undefined && this.persistenceFailure === undefined,
+			temporaryPath,
+			failure: this.persistenceFailure,
+		});
+	}
+
+	private count(text: string): void {
+		if (text.length === 0) return;
+		this.totalBytes += Buffer.byteLength(text);
+		this.newlineCount += text.split("\n").length - 1;
+		this.hasContent = true;
+		this.endsWithNewline = text.endsWith("\n");
+	}
+
+	private async persist(text: string): Promise<void> {
+		if (this.persistenceFailure) return;
+		try {
+			this.output ??= await this.store.createOutput();
+			await this.output.write(text);
+		} catch (error) {
+			this.persistenceFailure = error instanceof TemporaryOutputError ? error.code : "write";
+			const output = this.output;
+			this.output = undefined;
+			if (output) await output.abort();
+		}
+	}
+
+	private requireOpen(): void {
+		if (this.finished) throw new Error("Bounded text result is already finished");
+	}
+}
+
+function formatBoundedTextOverflow(details: BoundedTextOverflowDetails): string {
+	const sizes = `${details.shownLines} of ${details.totalLines} lines (${formatSize(details.shownBytes)} of ${formatSize(details.totalBytes)})`;
+	if (details.fullOutputComplete && details.temporaryPath) {
+		return `[Output truncated: showing ${sizes}. Complete output: ${details.temporaryPath}\nTemporary output is valid only for the active session. Use targeted grep or ranged read; reading the whole file will hit the same output limits.]`;
+	}
+	const reason = details.failure === "quota" ? "disk quota exceeded" : "temporary-file write failed";
+	return `[Output truncated: showing ${sizes}. Complete temporary output unavailable: ${reason}.]`;
+}
+
+function textLineCount(text: string): number {
+	return lineCount(text.length > 0, text.split("\n").length - 1, text.endsWith("\n"));
+}
+
+function lineCount(hasContent: boolean, newlineCount: number, endsWithNewline: boolean): number {
+	return hasContent ? newlineCount + (endsWithNewline ? 0 : 1) : 0;
+}

package/shared/events.ts

@@ -15,7 +15,7 @@ export type TauAgentEvents = {
 		disposition: "notify" | "discard";
 	};
 	"tau:file-mutation.applied": {
-		source: "patch";
+		source: "patch" | "locatorEdit";
 		toolCallId: string;
 		cwd: string;
 		status: "completed" | "partial" | "failed";
@@ -25,6 +25,7 @@ export type TauAgentEvents = {
 			move?: { from: string; to: string };
 			linesAdded: number;
 			linesRemoved: number;
+			resultingFingerprint: string | null;
 			snapshotRanges?: Array<{ startLine: number; endLine: number }>;
 		}>;
 	};

package/shared/temporary-output-store.ts

@@ -0,0 +1,275 @@
+import { randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { mkdir, open, opendir, readFile, rename, rm, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const DIRECTORY_PREFIX = "tau-tool-output-v1-";
+const OWNER_FILE = ".tau-owner.json";
+
+const TEMPORARY_OUTPUT_FILE_QUOTA_BYTES = 64 * 1024 * 1024;
+const TEMPORARY_OUTPUT_SESSION_QUOTA_BYTES = 256 * 1024 * 1024;
+const TEMPORARY_OUTPUT_ORPHAN_LIFETIME_MS = 24 * 60 * 60 * 1000;
+
+export function createTemporaryOutputStore(): TemporaryOutputStore {
+	return new TemporaryOutputStore(
+		tmpdir(),
+		TEMPORARY_OUTPUT_FILE_QUOTA_BYTES,
+		TEMPORARY_OUTPUT_SESSION_QUOTA_BYTES,
+		TEMPORARY_OUTPUT_ORPHAN_LIFETIME_MS,
+	);
+}
+
+interface OwnerMarker {
+	kind: "tau-tool-output";
+	version: 1;
+	pid: number;
+	createdAt: number;
+}
+
+export class TemporaryOutputError extends Error {
+	readonly code: "quota" | "write";
+
+	constructor(code: "quota" | "write", message: string) {
+		super(message);
+		this.name = "TemporaryOutputError";
+		this.code = code;
+	}
+}
+
+export class TemporaryOutputStore {
+	private readonly baseDirectory: string;
+	private readonly fileQuotaBytes: number;
+	private readonly sessionQuotaBytes: number;
+	private readonly orphanLifetimeMs: number;
+	private started = false;
+	private startPromise: Promise<void> | undefined;
+	private directory: string | undefined;
+	private directoryPromise: Promise<string> | undefined;
+	private sessionBytes = 0;
+	private readonly active = new Set<TemporaryOutputWriter>();
+	private readonly creating = new Set<Promise<TemporaryOutputWriter>>();
+	private shuttingDown = false;
+	private shutdownPromise: Promise<void> | undefined;
+
+	constructor(baseDirectory: string, fileQuotaBytes: number, sessionQuotaBytes: number, orphanLifetimeMs: number) {
+		this.baseDirectory = baseDirectory;
+		this.fileQuotaBytes = fileQuotaBytes;
+		this.sessionQuotaBytes = sessionQuotaBytes;
+		this.orphanLifetimeMs = orphanLifetimeMs;
+	}
+
+	async start(): Promise<void> {
+		if (this.started) return;
+		this.startPromise ??= this.removeStaleOrphans().then(() => {
+			this.started = true;
+		});
+		try {
+			await this.startPromise;
+		} finally {
+			this.startPromise = undefined;
+		}
+	}
+
+	async createOutput(): Promise<TemporaryOutputWriter> {
+		if (this.shuttingDown) throw new TemporaryOutputError("write", "Temporary output session is shutting down");
+		const creation = this.createOutputFile();
+		this.creating.add(creation);
+		try {
+			return await creation;
+		} finally {
+			this.creating.delete(creation);
+		}
+	}
+
+	private async createOutputFile(): Promise<TemporaryOutputWriter> {
+		await this.start();
+		if (this.shuttingDown) throw new TemporaryOutputError("write", "Temporary output session is shutting down");
+		this.directoryPromise ??= (async () => {
+			const directory = join(this.baseDirectory, `${DIRECTORY_PREFIX}${randomUUID()}`);
+			try {
+				await mkdir(directory, { mode: 0o700 });
+				const marker = {
+					kind: "tau-tool-output",
+					version: 1,
+					pid: process.pid,
+					createdAt: Date.now(),
+				} satisfies OwnerMarker;
+				const markerFile = await open(
+					join(directory, OWNER_FILE),
+					constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+					0o600,
+				);
+				try {
+					await markerFile.writeFile(JSON.stringify(marker));
+				} finally {
+					await markerFile.close();
+				}
+				return directory;
+			} catch (error) {
+				await rm(directory, { recursive: true, force: true });
+				throw error;
+			}
+		})();
+		const directory = await this.directoryPromise;
+		this.directory = directory;
+
+		const partialPath = join(directory, `${randomUUID()}.partial`);
+		let file;
+		try {
+			file = await open(partialPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+		} catch (error) {
+			throw new TemporaryOutputError("write", `Cannot create temporary output: ${String(error)}`);
+		}
+		const writer = new TemporaryOutputWriter(this, file, partialPath, partialPath.replace(/\.partial$/, ".txt"));
+		this.active.add(writer);
+		return writer;
+	}
+
+	async shutdown(): Promise<void> {
+		if (this.shutdownPromise) return this.shutdownPromise;
+		this.shutdownPromise = this.performShutdown();
+		try {
+			await this.shutdownPromise;
+		} finally {
+			this.shutdownPromise = undefined;
+		}
+	}
+
+	private async performShutdown(): Promise<void> {
+		this.shuttingDown = true;
+		await Promise.allSettled(this.creating);
+		for (const writer of this.active) await writer.abort();
+		const directory = this.directory;
+		this.directory = undefined;
+		this.sessionBytes = 0;
+		this.started = false;
+		this.startPromise = undefined;
+		this.directoryPromise = undefined;
+		if (directory) await rm(directory, { recursive: true, force: true });
+		this.shuttingDown = false;
+	}
+
+	reserve(writer: TemporaryOutputWriter, bytes: number): void {
+		if (writer.byteLength + bytes > this.fileQuotaBytes) {
+			throw new TemporaryOutputError(
+				"quota",
+				`Temporary output exceeds the ${this.fileQuotaBytes}-byte per-file quota`,
+			);
+		}
+		if (this.sessionBytes + bytes > this.sessionQuotaBytes) {
+			throw new TemporaryOutputError(
+				"quota",
+				`Temporary output exceeds the ${this.sessionQuotaBytes}-byte per-session quota`,
+			);
+		}
+		writer.byteLength += bytes;
+		this.sessionBytes += bytes;
+	}
+
+	release(writer: TemporaryOutputWriter): void {
+		this.sessionBytes = Math.max(0, this.sessionBytes - writer.byteLength);
+		writer.byteLength = 0;
+		this.active.delete(writer);
+	}
+
+	complete(writer: TemporaryOutputWriter): void {
+		this.active.delete(writer);
+	}
+
+	private async removeStaleOrphans(): Promise<void> {
+		let directory;
+		try {
+			directory = await opendir(this.baseDirectory);
+		} catch {
+			return;
+		}
+		for await (const entry of directory) {
+			if (!entry.isDirectory() || !entry.name.startsWith(DIRECTORY_PREFIX)) continue;
+			const path = join(this.baseDirectory, entry.name);
+			try {
+				const metadata = await stat(path);
+				if (Date.now() - metadata.mtimeMs < this.orphanLifetimeMs) continue;
+				const marker = JSON.parse(await readFile(join(path, OWNER_FILE), "utf8")) as Partial<OwnerMarker>;
+				if (marker.kind !== "tau-tool-output" || marker.version !== 1 || typeof marker.pid !== "number") continue;
+				try {
+					process.kill(marker.pid, 0);
+					continue;
+				} catch (error) {
+					if (!isErrorCode(error, "ESRCH")) continue;
+				}
+				await rm(path, { recursive: true, force: true });
+			} catch {
+				// An untrusted or concurrently changing directory is not ours to remove.
+			}
+		}
+	}
+}
+
+export class TemporaryOutputWriter {
+	private readonly store: TemporaryOutputStore;
+	private readonly file: Awaited<ReturnType<typeof open>>;
+	private readonly partialPath: string;
+	private readonly completePath: string;
+	byteLength = 0;
+	private closed = false;
+
+	constructor(
+		store: TemporaryOutputStore,
+		file: Awaited<ReturnType<typeof open>>,
+		partialPath: string,
+		completePath: string,
+	) {
+		this.store = store;
+		this.file = file;
+		this.partialPath = partialPath;
+		this.completePath = completePath;
+	}
+
+	async write(text: string): Promise<void> {
+		if (this.closed) throw new TemporaryOutputError("write", "Temporary output is already closed");
+		const buffer = Buffer.from(text);
+		try {
+			this.store.reserve(this, buffer.byteLength);
+			let offset = 0;
+			while (offset < buffer.byteLength) {
+				const result = await this.file.write(buffer, offset, buffer.byteLength - offset);
+				if (result.bytesWritten === 0) throw new Error("write returned zero bytes");
+				offset += result.bytesWritten;
+			}
+		} catch (error) {
+			await this.abort();
+			if (error instanceof TemporaryOutputError) throw error;
+			throw new TemporaryOutputError("write", `Cannot write temporary output: ${String(error)}`);
+		}
+	}
+
+	async finish(): Promise<string> {
+		if (this.closed) throw new TemporaryOutputError("write", "Temporary output is already closed");
+		this.closed = true;
+		try {
+			await this.file.close();
+			await rename(this.partialPath, this.completePath);
+			this.store.complete(this);
+			return this.completePath;
+		} catch (error) {
+			this.closed = false;
+			await this.abort();
+			throw new TemporaryOutputError("write", `Cannot complete temporary output: ${String(error)}`);
+		}
+	}
+
+	async abort(): Promise<void> {
+		if (!this.closed) {
+			this.closed = true;
+			await this.file.close().catch(() => {});
+		}
+		await rm(this.partialPath, { force: true }).catch(() => {});
+		await rm(this.completePath, { force: true }).catch(() => {});
+		this.store.release(this);
+	}
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+	return error instanceof Error && "code" in error && error.code === code;
+}