@shanepadgett/tau-agent 0.27.0 → 0.28.0

package/extensions/explore/limits.ts

@@ -1,22 +0,0 @@
-export function normalizeNonNegativeInteger(value: number | undefined, fallback: number): number {
-	if (value === undefined) return fallback;
-	if (!Number.isFinite(value)) return fallback;
-	return Math.max(0, Math.floor(value));
-}
-
-export function normalizeCountLimit(value: number | undefined, fallback: number): number {
-	if (value === undefined) return fallback;
-	if (!Number.isFinite(value)) return fallback;
-	return Math.max(1, Math.floor(value));
-}
-
-export function divideBudget(limit: number, count: number): number[] {
-	if (count <= 0) return [];
-	const base = Math.max(1, Math.floor(limit / count));
-	let remainder = Math.max(0, limit - base * count);
-	return Array.from({ length: count }, () => {
-		const extra = remainder > 0 ? 1 : 0;
-		if (remainder > 0) remainder -= 1;
-		return base + extra;
-	});
-}

package/extensions/explore/ls.ts

@@ -1,113 +0,0 @@
-import { defineTool, formatSize } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
-import { type Static, Type } from "typebox";
-import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
-import { divideBudget, normalizeCountLimit, normalizeNonNegativeInteger } from "./limits.ts";
-import { formatPathForDisplay, pathResolutionError, resolveExplorePath, stripLeadingAt } from "./path-display.ts";
-import { type PathTreeEntry, renderPathTree } from "./path-tree.ts";
-import { createExploreTextResult, type ExploreTextDetails, expandedExploreText } from "./result.ts";
-import { collectPaths, type TraversalEntry } from "./traverse.ts";
-
-const lsParams = Type.Object(
-	{
-		paths: Type.Optional(Type.Array(Type.String())),
-		depth: Type.Optional(Type.Number()),
-		limit: Type.Optional(Type.Number()),
-		all: Type.Optional(Type.Boolean()),
-		long: Type.Optional(Type.Boolean()),
-	},
-	{ additionalProperties: false },
-);
-
-type LsParams = Static<typeof lsParams>;
-
-function formatTime(date: Date): string {
-	return date.toISOString().slice(0, 10);
-}
-
-function entryMetadata(entry: TraversalEntry, long: boolean): string | undefined {
-	if (!long) return undefined;
-	const size = entry.type === "dir" ? "dir" : formatSize(entry.stats.size);
-	return `${size} ${formatTime(entry.stats.mtime)}`;
-}
-
-function pathTreeEntry(entry: TraversalEntry, long: boolean): PathTreeEntry {
-	return {
-		displayPath: entry.displayPath,
-		type: entry.type,
-		metadata: entryMetadata(entry, long),
-		empty: entry.empty,
-	};
-}
-
-function renderCallSummary(args: LsParams | undefined): string {
-	const paths = args?.paths && args.paths.length > 0 ? args.paths.map(stripLeadingAt).join(" ") : ".";
-	const depth = normalizeNonNegativeInteger(args?.depth, 1);
-	const limit = normalizeCountLimit(args?.limit, 100);
-	const flags = [args?.all ? "all" : "", args?.long ? "long" : ""].filter(Boolean).join(" ");
-	return `paths=${paths} depth=${depth} limit=${limit}${flags ? ` ${flags}` : ""}`;
-}
-
-export function createLsTool(rowState: ToolRowStateStore) {
-	return defineTool<typeof lsParams, ExploreTextDetails | undefined>({
-		name: "ls",
-		label: "ls",
-		description: "List files and directories with compact path output.",
-		promptSnippet: "List files and directories",
-		parameters: lsParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const requestedPaths = params.paths && params.paths.length > 0 ? params.paths : ["."];
-			const depth = normalizeNonNegativeInteger(params.depth, 1);
-			const limit = normalizeCountLimit(params.limit, 100);
-			const budgets = divideBudget(limit, requestedPaths.length);
-			const all = params.all === true;
-			const humanParts: string[] = [];
-			const agentParts: string[] = [];
-
-			for (let i = 0; i < requestedPaths.length; i += 1) {
-				const input = requestedPaths[i] ?? ".";
-				const root = resolveExplorePath(ctx.cwd, input);
-				const entries = await collectPaths({
-					cwd: ctx.cwd,
-					root,
-					maxDepth: depth,
-					includeRoot: true,
-					includeHidden: all,
-					includeIgnored: all,
-					includeNoise: all,
-				}).catch((error: unknown) => {
-					throw pathResolutionError(error, input);
-				});
-
-				const budget = budgets[i] ?? limit;
-				const shown = entries.slice(0, budget);
-				const omitted = entries.length - shown.length;
-				const notice = omitted > 0 ? `… omitted ${omitted} entries (limit ${budget})` : undefined;
-				const rootPath = formatPathForDisplay(root, ctx.cwd);
-				const tree = renderPathTree(
-					shown.map((entry) => pathTreeEntry(entry, params.long === true)),
-					{
-						rootPath,
-						omissionNotice: notice,
-					},
-				);
-				humanParts.push(tree.humanText);
-				agentParts.push(tree.agentText);
-			}
-
-			return createExploreTextResult(agentParts.join("\n\n"), humanParts.join("\n\n"));
-		},
-		renderCall(args, theme, context) {
-			rowState.watch(context.toolCallId, context.invalidate);
-			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-			const title = formatToolRowTitle(rowState, context.toolCallId, "ls", theme);
-			text.setText(`${title} ${theme.fg("muted", renderCallSummary(args))}`);
-			return text;
-		},
-		renderResult(result, _options, _theme, context) {
-			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
-			text.setText(context.expanded ? expandedExploreText(result) : "");
-			return text;
-		},
-	});
-}

package/extensions/explore/orientation-state.ts

@@ -1,280 +0,0 @@
-import { createHash } from "node:crypto";
-import { realpathSync } from "node:fs";
-import { resolve } from "node:path";
-import { astLanguageForPath, type AstLanguage } from "./ast-languages.ts";
-
-export type StructuralAttemptKind =
-	| "directOutline"
-	| "symbol"
-	| "apiCandidate"
-	| "structuralMatch"
-	| "relationshipLocation"
-	| "relationshipScope";
-export type ReadGateDecision = StructuralAttemptKind | "fatalFallback" | "blocked";
-export type ReadPermission = Exclude<ReadGateDecision, "blocked"> | "postPatchDiff" | "ungated";
-
-export interface OrientationTelemetry {
-	blockedReadAttempts: number;
-	permittedReadAttempts: number;
-	fallbackReadAttempts: number;
-	permissionReadAttempts: Record<Exclude<ReadPermission, "ungated">, number>;
-	workerInputBytes: number;
-	completeRenderedBytes: number;
-	modelVisibleAstBytes: number;
-	sourceBytesDeflected: number;
-	temporaryOutputBytes: number;
-	directReadBytes: number;
-	overflowReadBytes: number;
-}
-
-interface AttemptRecord {
-	fingerprint: string;
-	kind: StructuralAttemptKind;
-}
-
-interface FatalFallbackRecord {
-	fingerprint: string;
-	includePrivate: boolean;
-	names: readonly string[];
-	diagnostic: {
-		code: "outline_failed" | "outlineFailed" | "response_too_large" | "resultFrameTooLarge";
-		message: string;
-	};
-}
-
-interface FileState {
-	attempt: AttemptRecord | undefined;
-	fallback: FatalFallbackRecord | undefined;
-	patchFingerprint: string | undefined;
-}
-
-type TelemetryEvent =
-	| {
-			toolCallId: string;
-			kind: "outline";
-			workerInputBytes: number;
-			completeRenderedBytes: number;
-			modelVisibleAstBytes: number;
-			temporaryOutputBytes: number;
-	  }
-	| {
-			toolCallId: string;
-			kind: "structuralAttempt";
-			sourceBytesDeflected: number;
-	  }
-	| {
-			toolCallId: string;
-			kind: "blockedRead";
-	  }
-	| {
-			toolCallId: string;
-			kind: "read";
-			permission: ReadPermission;
-			returnedBytes: number;
-			overflow: boolean;
-	  };
-
-export interface OrientationState {
-	supports(path: string): Promise<boolean>;
-	check(path: string, fingerprint: string): ReadGateDecision;
-	checkPatch(path: string, fingerprint: string): boolean;
-	recordAttempts(
-		records: readonly {
-			path: string;
-			fingerprint: string;
-			kind: StructuralAttemptKind;
-			toolCallId: string;
-			sourceBytesDeflected: number;
-		}[],
-	): void;
-	recordFatal(input: {
-		path: string;
-		fingerprint: string;
-		includePrivate: boolean;
-		names: readonly string[];
-		code: "outline_failed" | "outlineFailed" | "response_too_large" | "resultFrameTooLarge";
-		message: string;
-	}): void;
-	recordPatched(records: readonly { path: string; resultingFingerprint: string | null }[]): void;
-	recordOutlineTelemetry(
-		toolCallId: string,
-		metrics: {
-			workerInputBytes: number;
-			completeRenderedBytes: number;
-			modelVisibleAstBytes: number;
-			temporaryOutputBytes: number;
-		},
-	): void;
-	recordBlockedRead(toolCallId: string, path: string): void;
-	recordRead(toolCallId: string, path: string, permission: ReadPermission, returnedBytes: number): void;
-	recordTemporaryOutput(path: string): void;
-	telemetry(includedToolCallIds: ReadonlySet<string> | undefined): OrientationTelemetry;
-	invalidate(paths: readonly string[]): void;
-	clear(): void;
-	resetGate(): void;
-}
-
-export function sourceFingerprint(source: Uint8Array): string {
-	return `sha256:${createHash("sha256").update(source).digest("hex")}`;
-}
-
-export function createOrientationState(workerLanguages: () => Promise<readonly AstLanguage[]>): OrientationState {
-	const files = new Map<string, FileState>();
-	const temporaryOutputs = new Set<string>();
-	const events: TelemetryEvent[] = [];
-
-	function stateFor(path: string): FileState {
-		const canonicalPath = canonicalPathForState(path);
-		const existing = files.get(canonicalPath);
-		if (existing) return existing;
-		const state: FileState = { attempt: undefined, fallback: undefined, patchFingerprint: undefined };
-		files.set(canonicalPath, state);
-		return state;
-	}
-
-	return {
-		async supports(path) {
-			const language = astLanguageForPath(canonicalPathForState(path));
-			if (!language) return false;
-			try {
-				return (await workerLanguages()).includes(language);
-			} catch {
-				return false;
-			}
-		},
-		check(path, fingerprint) {
-			const state = files.get(canonicalPathForState(path));
-			if (!state) return "blocked";
-			if (state.attempt && state.attempt.fingerprint !== fingerprint) state.attempt = undefined;
-			if (state.fallback && state.fallback.fingerprint !== fingerprint) state.fallback = undefined;
-			if (state.attempt?.fingerprint === fingerprint) return state.attempt.kind;
-			return state.fallback?.fingerprint === fingerprint ? "fatalFallback" : "blocked";
-		},
-		checkPatch(path, fingerprint) {
-			const state = files.get(canonicalPathForState(path));
-			if (!state?.patchFingerprint) return false;
-			if (state.patchFingerprint === fingerprint) return true;
-			state.patchFingerprint = undefined;
-			return false;
-		},
-		recordAttempts(records) {
-			for (const record of records) {
-				const state = stateFor(record.path);
-				state.attempt = { fingerprint: record.fingerprint, kind: record.kind };
-				state.fallback = undefined;
-				events.push({
-					toolCallId: record.toolCallId,
-					kind: "structuralAttempt",
-					sourceBytesDeflected: record.sourceBytesDeflected,
-				});
-			}
-		},
-		recordFatal(input) {
-			const state = stateFor(input.path);
-			state.fallback = {
-				fingerprint: input.fingerprint,
-				includePrivate: input.includePrivate,
-				names: [...input.names],
-				diagnostic: { code: input.code, message: input.message },
-			};
-		},
-		recordPatched(records) {
-			for (const record of records) {
-				if (record.resultingFingerprint === null) continue;
-				stateFor(record.path).patchFingerprint = record.resultingFingerprint;
-			}
-		},
-		recordOutlineTelemetry(toolCallId, metrics) {
-			events.push({ toolCallId, kind: "outline", ...metrics });
-		},
-		recordBlockedRead(toolCallId, path) {
-			stateFor(path);
-			events.push({ toolCallId, kind: "blockedRead" });
-		},
-		recordRead(toolCallId, path, permission, returnedBytes) {
-			events.push({
-				toolCallId,
-				kind: "read",
-				permission,
-				returnedBytes,
-				overflow: temporaryOutputs.has(canonicalPathForState(path)),
-			});
-		},
-		recordTemporaryOutput(path) {
-			temporaryOutputs.add(canonicalPathForState(path));
-		},
-		telemetry(includedToolCallIds) {
-			const permissionReadAttempts: OrientationTelemetry["permissionReadAttempts"] = {
-				directOutline: 0,
-				symbol: 0,
-				apiCandidate: 0,
-				structuralMatch: 0,
-				relationshipLocation: 0,
-				relationshipScope: 0,
-				fatalFallback: 0,
-				postPatchDiff: 0,
-			};
-			const result: OrientationTelemetry = {
-				blockedReadAttempts: 0,
-				permittedReadAttempts: 0,
-				fallbackReadAttempts: 0,
-				permissionReadAttempts,
-				workerInputBytes: 0,
-				completeRenderedBytes: 0,
-				modelVisibleAstBytes: 0,
-				sourceBytesDeflected: 0,
-				temporaryOutputBytes: 0,
-				directReadBytes: 0,
-				overflowReadBytes: 0,
-			};
-			for (const event of events) {
-				if (includedToolCallIds && !includedToolCallIds.has(event.toolCallId)) continue;
-				if (event.kind === "outline") {
-					result.workerInputBytes += event.workerInputBytes;
-					result.completeRenderedBytes += event.completeRenderedBytes;
-					result.modelVisibleAstBytes += event.modelVisibleAstBytes;
-					result.temporaryOutputBytes += event.temporaryOutputBytes;
-				} else if (event.kind === "structuralAttempt") {
-					result.sourceBytesDeflected += event.sourceBytesDeflected;
-				} else if (event.kind === "blockedRead") {
-					result.blockedReadAttempts += 1;
-				} else {
-					result.directReadBytes += event.returnedBytes;
-					if (event.overflow) result.overflowReadBytes += event.returnedBytes;
-					if (event.permission !== "ungated") {
-						result.permittedReadAttempts += 1;
-						result.permissionReadAttempts[event.permission] += 1;
-					}
-					if (event.permission === "fatalFallback") result.fallbackReadAttempts += 1;
-				}
-			}
-			return result;
-		},
-		invalidate(paths) {
-			for (const path of paths) {
-				const state = files.get(canonicalPathForState(path));
-				if (!state) continue;
-				state.attempt = undefined;
-				state.fallback = undefined;
-				state.patchFingerprint = undefined;
-			}
-		},
-		clear() {
-			files.clear();
-			temporaryOutputs.clear();
-			events.length = 0;
-		},
-		resetGate() {
-			files.clear();
-		},
-	};
-}
-
-function canonicalPathForState(path: string): string {
-	const absolutePath = resolve(path);
-	try {
-		return realpathSync(absolutePath);
-	} catch {
-		return absolutePath;
-	}
-}

package/extensions/explore/path-display.ts

@@ -1,41 +0,0 @@
-import { isAbsolute, relative, resolve } from "node:path";
-
-export function stripLeadingAt(value: string): string {
-	return value.startsWith("@") ? value.slice(1) : value;
-}
-
-export function toSlashPath(value: string): string {
-	return value.replace(/\\/g, "/");
-}
-
-export function resolveExplorePath(cwd: string, input: string): string {
-	const path = stripLeadingAt(input);
-	if (path.length === 0) return resolve(cwd);
-	return isAbsolute(path) ? resolve(path) : resolve(cwd, path);
-}
-
-export function pathResolutionError(error: unknown, input: string): Error {
-	if (error instanceof Error && "code" in error && error.code === "ENOENT") {
-		return new Error(`Path not found: ${stripLeadingAt(input)}`);
-	}
-	return error instanceof Error ? error : new Error(String(error));
-}
-
-export function isWithinPath(parent: string, child: string): boolean {
-	const rel = relative(resolve(parent), resolve(child));
-	return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
-}
-
-export function formatPathForDisplay(absolutePath: string, cwd: string): string {
-	const resolvedCwd = resolve(cwd);
-	const resolvedPath = resolve(absolutePath);
-	const rel = relative(resolvedCwd, resolvedPath);
-	if (rel === "") return ".";
-	if (!rel.startsWith("..") && !isAbsolute(rel)) return toSlashPath(rel);
-	return toSlashPath(resolvedPath);
-}
-
-export function relativeSlash(from: string, to: string): string {
-	const rel = relative(resolve(from), resolve(to));
-	return rel === "" ? "." : toSlashPath(rel);
-}

package/extensions/explore/path-tree.ts

@@ -1,150 +0,0 @@
-export type PathTreeEntryType = "file" | "dir";
-
-export interface PathTreeEntry {
-	displayPath: string;
-	type: PathTreeEntryType;
-	metadata?: string;
-	empty?: boolean;
-}
-
-export interface PathTreeRenderOptions {
-	rootPath?: string;
-	omissionNotice?: string;
-}
-
-export interface PathTreeRender {
-	humanText: string;
-	agentText: string;
-}
-
-interface TreeNode {
-	name: string;
-	type: PathTreeEntryType;
-	metadata?: string;
-	empty?: boolean;
-	children: Map<string, TreeNode>;
-}
-
-function splitDisplayPath(displayPath: string): string[] {
-	if (displayPath === ".") return [];
-	if (displayPath === "/") return ["/"];
-	if (displayPath.startsWith("/")) return ["/", ...displayPath.slice(1).split("/").filter(Boolean)];
-	return displayPath.split("/").filter(Boolean);
-}
-
-function isUnderRoot(rootPath: string, displayPath: string): boolean {
-	if (rootPath === "/") return displayPath.startsWith("/");
-	if (rootPath === ".") return !displayPath.startsWith("/");
-	return displayPath === rootPath || displayPath.startsWith(`${rootPath}/`);
-}
-
-function relativeToRoot(rootPath: string, displayPath: string): string {
-	if (rootPath === "/") return displayPath === "/" ? "" : displayPath.slice(1);
-	if (rootPath === ".") return displayPath === "." ? "" : displayPath;
-	if (displayPath === rootPath) return "";
-	return displayPath.slice(rootPath.length + 1);
-}
-
-function entryLabel(node: TreeNode): string {
-	const name = node.name === "/" ? "/" : node.type === "dir" ? `${node.name}/` : node.name;
-	return node.metadata ? `${name} ${node.metadata}` : name;
-}
-
-function sortChildren(node: TreeNode): TreeNode[] {
-	return [...node.children.values()].sort((a, b) => {
-		if (a.type !== b.type) return a.type === "dir" ? -1 : 1;
-		return a.name.localeCompare(b.name);
-	});
-}
-
-function createNode(name: string, type: PathTreeEntryType): TreeNode {
-	return { name, type, children: new Map() };
-}
-
-function insert(root: TreeNode, relativePath: string, entry: PathTreeEntry): void {
-	const parts = splitDisplayPath(relativePath);
-	if (parts.length === 0) {
-		root.type = entry.type;
-		root.metadata = entry.metadata;
-		root.empty = entry.empty;
-		return;
-	}
-
-	let current = root;
-	for (let i = 0; i < parts.length; i += 1) {
-		const part = parts[i];
-		if (!part) continue;
-		const isLeaf = i === parts.length - 1;
-		const type = isLeaf ? entry.type : "dir";
-		let child = current.children.get(part);
-		if (!child) {
-			child = createNode(part, type);
-			current.children.set(part, child);
-		}
-		if (isLeaf) {
-			child.type = entry.type;
-			child.metadata = entry.metadata;
-			child.empty = entry.empty;
-		}
-		current = child;
-	}
-}
-
-function renderHumanNode(node: TreeNode, depth: number, lines: string[]): void {
-	lines.push(`${"  ".repeat(depth)}${entryLabel(node)}`);
-	if (node.empty && node.children.size === 0) lines.push(`${"  ".repeat(depth + 1)}[empty]`);
-	for (const child of sortChildren(node)) renderHumanNode(child, depth + 1, lines);
-}
-
-function renderAgentNode(node: TreeNode, depth: number, lines: string[]): void {
-	if (node.type === "file") {
-		lines.push(`${"  ".repeat(depth)}${entryLabel(node)}`);
-		return;
-	}
-
-	const children = sortChildren(node);
-	const files = children.filter((child) => child.type === "file").map(entryLabel);
-	let line = `${"  ".repeat(depth)}${entryLabel(node)}`;
-	if (files.length > 0) line += `: ${files.join(", ")}`;
-	else if (node.empty && children.length === 0) line += " [empty]";
-	lines.push(line);
-
-	for (const child of children) {
-		if (child.type === "dir") renderAgentNode(child, depth + 1, lines);
-	}
-}
-
-function buildTree(entries: readonly PathTreeEntry[], rootPath: string | undefined): TreeNode {
-	const rootName = rootPath === undefined ? "" : rootPath === "." ? "." : rootPath;
-	const root = createNode(rootName, "dir");
-	for (const entry of entries) {
-		if (rootPath !== undefined && isUnderRoot(rootPath, entry.displayPath)) {
-			insert(root, relativeToRoot(rootPath, entry.displayPath), entry);
-		} else {
-			insert(root, entry.displayPath, entry);
-		}
-	}
-	return root;
-}
-
-function appendNotice(lines: string[], notice: string | undefined): void {
-	if (notice) lines.push(notice);
-}
-
-export function renderPathTree(entries: readonly PathTreeEntry[], options: PathTreeRenderOptions = {}): PathTreeRender {
-	const root = buildTree(entries, options.rootPath);
-	const humanLines: string[] = [];
-	const agentLines: string[] = [];
-
-	if (options.rootPath === undefined) {
-		for (const child of sortChildren(root)) renderHumanNode(child, 0, humanLines);
-		for (const child of sortChildren(root)) renderAgentNode(child, 0, agentLines);
-	} else {
-		renderHumanNode(root, 0, humanLines);
-		renderAgentNode(root, 0, agentLines);
-	}
-
-	appendNotice(humanLines, options.omissionNotice);
-	appendNotice(agentLines, options.omissionNotice);
-	return { humanText: humanLines.join("\n"), agentText: agentLines.join("\n") };
-}