@shanepadgett/tau-agent 0.1.0

package/extensions/explore/index.ts

@@ -0,0 +1,17 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { registerAutoread } from "./autoread.ts";
+import { createFindTool } from "./find.ts";
+import { createGrepTool } from "./grep.ts";
+import { createLsTool } from "./ls.ts";
+import { createExploreReadTool } from "./read.ts";
+
+export default function exploreExtension(pi: ExtensionAPI): void {
+	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
+	registerAutoread(pi, rowState);
+	pi.registerTool(createLsTool(rowState));
+	pi.registerTool(createFindTool(rowState));
+	pi.registerTool(createGrepTool(rowState));
+	pi.registerTool(createExploreReadTool(rowState));
+	pi.on("session_start", () => rowState.clear());
+}

package/extensions/explore/limits.ts

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

@@ -0,0 +1,113 @@
+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/path-display.ts

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

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

package/extensions/explore/read.ts

@@ -0,0 +1,160 @@
+import {
+	createReadToolDefinition,
+	DEFAULT_MAX_BYTES,
+	formatSize,
+	truncateHead,
+	type ReadToolDetails,
+	type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { readFile } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+import { Type, type Static } from "typebox";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
+import { normalizeCountLimit } from "./limits.ts";
+import { stripLeadingAt } from "./path-display.ts";
+
+const readSchema = Type.Object({
+	path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
+	offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+	limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+	lineNumbers: Type.Optional(Type.Boolean({ description: "Prefix text lines with their 1-indexed file line number" })),
+});
+
+type ReadToolInput = Static<typeof readSchema>;
+type BaseReadDefinition = ReturnType<typeof createReadToolDefinition>;
+type ReadDefinition = ToolDefinition<typeof readSchema, ReadToolDetails | undefined>;
+type ReadExecute = ReadDefinition["execute"];
+type ReadRenderCall = NonNullable<ReadDefinition["renderCall"]>;
+type ReadRenderResult = NonNullable<ReadDefinition["renderResult"]>;
+
+const readDefinitionByCwd = new Map<string, BaseReadDefinition>();
+
+function readDefinitionForCwd(cwd: string): BaseReadDefinition {
+	const existing = readDefinitionByCwd.get(cwd);
+	if (existing) return existing;
+	const definition = createReadToolDefinition(cwd);
+	readDefinitionByCwd.set(cwd, definition);
+	return definition;
+}
+
+function normalizeReadParams(params: ReadToolInput): ReadToolInput {
+	return {
+		...params,
+		path: stripLeadingAt(params.path),
+		limit: params.limit === undefined ? undefined : normalizeCountLimit(params.limit, 1),
+	};
+}
+
+function isSupportedImage(buffer: Buffer): boolean {
+	return (
+		(buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) ||
+		buffer.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) ||
+		buffer.subarray(0, 6).toString("ascii") === "GIF87a" ||
+		buffer.subarray(0, 6).toString("ascii") === "GIF89a" ||
+		(buffer.subarray(0, 4).toString("ascii") === "RIFF" && buffer.subarray(8, 12).toString("ascii") === "WEBP") ||
+		buffer.subarray(0, 2).toString("ascii") === "BM"
+	);
+}
+
+function renderCallSummary(args: ReadToolInput | undefined): string {
+	if (!args) return "";
+	const path = stripLeadingAt(args.path);
+	if (args.offset === undefined && args.limit === undefined) return path;
+	const start = args.offset ?? 1;
+	const limit = args.limit === undefined ? undefined : normalizeCountLimit(args.limit, 1);
+	const end = limit === undefined ? "" : start + limit - 1;
+	return `${path}:${start}${end === "" ? "" : `-${end}`}`;
+}
+
+export function createExploreReadTool(rowState: ToolRowStateStore): ReadDefinition {
+	const baseDefinition = readDefinitionForCwd(process.cwd());
+	return {
+		...baseDefinition,
+		parameters: readSchema,
+		async execute(
+			toolCallId: Parameters<ReadExecute>[0],
+			params: Parameters<ReadExecute>[1],
+			signal: Parameters<ReadExecute>[2],
+			onUpdate: Parameters<ReadExecute>[3],
+			ctx: Parameters<ReadExecute>[4],
+		) {
+			const definition = readDefinitionForCwd(ctx.cwd);
+			const normalized = normalizeReadParams(params);
+			const path = isAbsolute(normalized.path) ? normalized.path : resolve(ctx.cwd, normalized.path);
+			const buffer = await readFile(path);
+			if (isSupportedImage(buffer)) {
+				return definition.execute(
+					toolCallId,
+					{ path: normalized.path, offset: normalized.offset, limit: normalized.limit },
+					signal,
+					onUpdate,
+					ctx,
+				);
+			}
+
+			if (signal?.aborted) throw new Error("Operation aborted");
+			const allLines = buffer.toString("utf-8").split("\n");
+			const startLine = normalized.offset ? Math.max(0, normalized.offset - 1) : 0;
+			const startLineDisplay = startLine + 1;
+			if (startLine >= allLines.length) {
+				throw new Error(`Offset ${normalized.offset} is beyond end of file (${allLines.length} lines total)`);
+			}
+
+			const endLine =
+				normalized.limit === undefined ? allLines.length : Math.min(startLine + normalized.limit, allLines.length);
+			const selectedLines = allLines.slice(startLine, endLine);
+			const selectedContent = selectedLines
+				.map((line, index) => (normalized.lineNumbers ? `${startLineDisplay + index}: ${line}` : line))
+				.join("\n");
+			const truncation = truncateHead(selectedContent);
+			let outputText: string;
+			let details: ReadToolDetails | undefined;
+			if (truncation.firstLineExceedsLimit) {
+				const firstLineSize = formatSize(Buffer.byteLength(selectedLines[0] ?? "", "utf-8"));
+				outputText = `[Line ${startLineDisplay} is ${firstLineSize}, exceeds ${formatSize(DEFAULT_MAX_BYTES)} limit. Use bash: sed -n '${startLineDisplay}p' ${normalized.path} | head -c ${DEFAULT_MAX_BYTES}]`;
+				details = { truncation };
+			} else if (truncation.truncated) {
+				const endLineDisplay = startLineDisplay + truncation.outputLines - 1;
+				const nextOffset = endLineDisplay + 1;
+				outputText = truncation.content;
+				outputText +=
+					truncation.truncatedBy === "lines"
+						? `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${allLines.length}. Use offset=${nextOffset} to continue.]`
+						: `\n\n[Showing lines ${startLineDisplay}-${endLineDisplay} of ${allLines.length} (${formatSize(DEFAULT_MAX_BYTES)} limit). Use offset=${nextOffset} to continue.]`;
+				details = { truncation };
+			} else if (endLine < allLines.length) {
+				outputText = `${truncation.content}\n\n[${allLines.length - endLine} more lines in file. Use offset=${endLine + 1} to continue.]`;
+			} else {
+				outputText = truncation.content;
+			}
+
+			return { content: [{ type: "text", text: outputText }], details };
+		},
+		renderCall(
+			args: Parameters<ReadRenderCall>[0],
+			theme: Parameters<ReadRenderCall>[1],
+			context: Parameters<ReadRenderCall>[2],
+		) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+			const title = formatToolRowTitle(rowState, context.toolCallId, "read", theme);
+			text.setText(`${title} ${theme.fg("muted", renderCallSummary(args))}`);
+			return text;
+		},
+		renderResult(
+			result: Parameters<ReadRenderResult>[0],
+			options: Parameters<ReadRenderResult>[1],
+			theme: Parameters<ReadRenderResult>[2],
+			context: Parameters<ReadRenderResult>[3],
+		) {
+			if (!context.expanded) {
+				const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+				text.setText("");
+				return text;
+			}
+			const definition = readDefinitionForCwd(context.cwd);
+			return definition.renderResult?.(result, { ...options, expanded: true }, theme, context) ?? new Text("", 0, 0);
+		},
+	};
+}

package/extensions/explore/result.ts

@@ -0,0 +1,29 @@
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
+
+export interface ExploreTextDetails {
+	humanText?: string;
+}
+
+export function createExploreTextResult(
+	agentText: string,
+	humanText?: string,
+): AgentToolResult<ExploreTextDetails | undefined> {
+	return {
+		content: [{ type: "text", text: agentText }],
+		details: humanText !== undefined && humanText !== agentText ? { humanText } : undefined,
+	};
+}
+
+export function firstTextContent(result: { content: readonly { type: string; text?: string }[] }): string {
+	for (const item of result.content) {
+		if (item.type === "text" && typeof item.text === "string") return item.text;
+	}
+	return "";
+}
+
+export function expandedExploreText(result: {
+	content: readonly { type: string; text?: string }[];
+	details?: ExploreTextDetails;
+}): string {
+	return result.details?.humanText ?? firstTextContent(result);
+}