@shanepadgett/tau-agent 0.1.0

package/extensions/turn-budget/index.ts

@@ -0,0 +1,150 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
+import { Marker } from "@shanepadgett/tau-tui";
+import turnBudgetSettings from "./settings.ts";
+
+const MARKER_TYPE = "tau.turn-budget.marker";
+
+interface Settings {
+	enabled: boolean;
+	turnLimit: number;
+	nudgeEveryTurns: number;
+	softCapIncrement: number;
+}
+
+type Hint =
+	| { kind: "normal"; used: number; cap: number }
+	| { kind: "extended"; used: number; previousCap: number; newCap: number };
+
+interface MarkerDetails {
+	used: number;
+	cap: number;
+	extended: boolean;
+	sequence: number;
+}
+
+export default function turnBudgetExtension(pi: ExtensionAPI): void {
+	let settings = normalizeSettings(turnBudgetSettings.defaults);
+	let turnCount = 0;
+	let softCap = settings.turnLimit;
+	let nextMarkerSequence = 1;
+	let activeMarkerSequence: number | undefined;
+
+	pi.registerMessageRenderer<MarkerDetails>(MARKER_TYPE, (message, _options, theme) => {
+		const details = readMarkerDetails(message.details);
+		if (!details) return undefined;
+		return new Marker({
+			theme,
+			state: "muted",
+			label: "Turn Budget:",
+			parts: [`${details.used}/${details.cap}`, ...(details.extended ? ["Soft cap extended."] : [])],
+		});
+	});
+
+	pi.on("before_agent_start", (event) => {
+		if (!settings.enabled) return undefined;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\nTurn-budget steering messages are internal instructions. Work within them silently. Do not mention or acknowledge turn counts, budget messages, or budget summaries.`,
+		};
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		settings = normalizeSettings(await loadTauExtensionSettings(ctx, turnBudgetSettings));
+	});
+
+	pi.on("agent_start", () => {
+		turnCount = 0;
+		softCap = settings.turnLimit;
+		activeMarkerSequence = undefined;
+	});
+
+	pi.on("turn_end", (event) => {
+		if (!settings.enabled) return undefined;
+		if (event.toolResults.length === 0) return undefined;
+		turnCount += 1;
+		if (turnCount >= softCap) {
+			const hint: Hint = {
+				kind: "extended",
+				used: turnCount,
+				previousCap: softCap,
+				newCap: turnCount + settings.softCapIncrement,
+			};
+			activeMarkerSequence = nextMarkerSequence;
+			sendTurnBudgetMessage(pi, hint, nextMarkerSequence);
+			nextMarkerSequence += 1;
+			softCap = hint.newCap;
+			return undefined;
+		}
+		if (turnCount % settings.nudgeEveryTurns === 0) {
+			const hint: Hint = { kind: "normal", used: turnCount, cap: softCap };
+			activeMarkerSequence = nextMarkerSequence;
+			sendTurnBudgetMessage(pi, hint, nextMarkerSequence);
+			nextMarkerSequence += 1;
+		}
+		return undefined;
+	});
+
+	pi.on("context", (event) => {
+		const messages = event.messages.filter(
+			(message) =>
+				message.role !== "custom" || message.customType !== MARKER_TYPE || markerIsActive(message.details),
+		);
+		if (messages.length === event.messages.length) return undefined;
+		return { messages };
+	});
+
+	pi.on("after_provider_response", () => {
+		activeMarkerSequence = undefined;
+	});
+
+	function markerIsActive(value: unknown): boolean {
+		if (activeMarkerSequence === undefined) return false;
+		const details = readMarkerDetails(value);
+		return details?.sequence === activeMarkerSequence;
+	}
+}
+
+function sendTurnBudgetMessage(pi: ExtensionAPI, hint: Hint, sequence: number): void {
+	pi.sendMessage<MarkerDetails>({
+		customType: MARKER_TYPE,
+		content: formatSteeringMessage(hint),
+		display: true,
+		details: markerDetails(hint, sequence),
+	});
+}
+
+function formatSteeringMessage(hint: Hint): string {
+	if (hint.kind === "extended") {
+		return `Turn budget: ${hint.used}/${hint.previousCap} turns used for this user prompt. Soft cap extended to ${hint.newCap}. Batch tools when more tool work remains.`;
+	}
+	return `Turn budget: ${hint.used}/${hint.cap} turns used for this user prompt. Batch tools when more tool work remains.`;
+}
+
+function normalizeSettings(value: typeof turnBudgetSettings.defaults): Settings {
+	return {
+		enabled: value.enabled ?? true,
+		turnLimit: Number.isInteger(value.turnLimit) && value.turnLimit > 0 ? value.turnLimit : 30,
+		nudgeEveryTurns: Number.isInteger(value.nudgeEveryTurns) && value.nudgeEveryTurns > 0 ? value.nudgeEveryTurns : 5,
+		softCapIncrement:
+			Number.isInteger(value.softCapIncrement) && value.softCapIncrement > 0 ? value.softCapIncrement : 10,
+	};
+}
+
+function markerDetails(hint: Hint, sequence: number): MarkerDetails {
+	return hint.kind === "extended"
+		? { used: hint.used, cap: hint.newCap, extended: true, sequence }
+		: { used: hint.used, cap: hint.cap, extended: false, sequence };
+}
+
+function readMarkerDetails(value: unknown): MarkerDetails | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	const used = record.used;
+	const cap = record.cap;
+	const sequence = record.sequence;
+	if (typeof used !== "number" || !Number.isInteger(used) || used < 0) return undefined;
+	if (typeof cap !== "number" || !Number.isInteger(cap) || cap < 1) return undefined;
+	if (typeof sequence !== "number" || !Number.isInteger(sequence) || sequence < 1) return undefined;
+	if (typeof record.extended !== "boolean") return undefined;
+	return { used, cap, extended: record.extended, sequence };
+}

package/extensions/turn-budget/settings.ts

@@ -0,0 +1,35 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+export default defineTauExtensionSettings({
+	key: "turnBudget",
+	defaults: {
+		enabled: true as boolean,
+		turnLimit: 30 as number,
+		nudgeEveryTurns: 5 as number,
+		softCapIncrement: 10 as number,
+	},
+	schema: Type.Object(
+		{
+			enabled: Type.Optional(Type.Boolean({ default: true, description: "Enable turn-budget hints." })),
+			turnLimit: Type.Optional(
+				Type.Integer({
+					default: 30,
+					minimum: 1,
+					description: "Initial soft cap for tool-using turns per user prompt.",
+				}),
+			),
+			nudgeEveryTurns: Type.Optional(
+				Type.Integer({
+					default: 5,
+					minimum: 1,
+					description: "Tool-using turn interval between turn-budget hints.",
+				}),
+			),
+			softCapIncrement: Type.Optional(
+				Type.Integer({ default: 10, minimum: 1, description: "Turns added when the soft cap is reached." }),
+			),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/web/README.md

@@ -0,0 +1,13 @@
+# Web
+
+The web extension adds three low-level tools:
+
+- `webfetch` retrieves a known HTTP(S) URL as Markdown, text, raw HTML, or an inline image.
+- `websearch` discovers public pages and current external information through Exa.
+- `codesearch` retrieves code examples and implementation-focused documentation context through Exa.
+
+Keeping these jobs separate lets agents fetch a known source without searching, or search for the kind of context the task needs. Agents invoke each tool directly and can combine them in a separate research workflow.
+
+`websearch` and `codesearch` can use an optional `EXA_API_KEY`. The key does not apply to `webfetch`.
+
+The extension permits outbound HTTP(S) requests. It has no domain allowlist.

package/extensions/web/codesearch.ts

@@ -0,0 +1,79 @@
+import { defineTool, type TruncationResult } 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 { callExa } from "./exa.ts";
+import { clampInteger, normalizeTimeout } from "./limits.ts";
+import { renderWebToolResult, truncateCallSummary, truncateToolOutput } from "./tool-output.ts";
+
+const codeSearchParams = Type.Object(
+	{
+		query: Type.String({ description: "Code or documentation search query" }),
+		tokensNum: Type.Optional(Type.Number({ description: "Target context token budget (default: 5000)" })),
+		timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 25, max: 600)" })),
+	},
+	{ additionalProperties: false },
+);
+
+type CodeSearchParams = Static<typeof codeSearchParams>;
+interface CodeSearchDetails {
+	query: string;
+	tokensNum: number;
+	truncation?: TruncationResult;
+}
+
+export function createCodeSearchTool(rowState: ToolRowStateStore) {
+	return defineTool<typeof codeSearchParams, CodeSearchDetails | undefined>({
+		name: "codesearch",
+		label: "Code Search",
+		description:
+			"Search Exa for implementation-oriented code and documentation context. Output is truncated to 2,000 lines or 50 KB.",
+		promptSnippet: "Search code and documentation context for implementation details",
+		promptGuidelines: [
+			"Use codesearch for API usage, code examples, and implementation-oriented documentation.",
+			"Use websearch for broad discovery and webfetch for a known URL.",
+			"Use a separate research workflow instead of codesearch when several searches, fetches, and synthesis are needed.",
+		],
+		parameters: codeSearchParams,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const timeout = normalizeTimeout(params.timeout, 25);
+			const tokensNum = clampInteger(params.tokensNum, 5000, 500, 20_000);
+			await onUpdate?.({ content: [{ type: "text", text: "Searching code context..." }], details: undefined });
+			try {
+				const output =
+					(await callExa(
+						{ toolName: "get_code_context_exa", arguments: { query: params.query, tokensNum } },
+						signal,
+						timeout,
+					)) ?? "No code context found. Try a more specific query with library/language names.";
+				const truncated = truncateToolOutput(output);
+				return {
+					content: [{ type: "text", text: truncated.text }],
+					details: {
+						query: params.query,
+						tokensNum,
+						...(truncated.truncation ? { truncation: truncated.truncation } : {}),
+					},
+				};
+			} catch (error) {
+				if (error instanceof Error && error.name === "TimeoutError") {
+					throw new Error(`Code search timed out after ${timeout}s`);
+				}
+				throw error;
+			}
+		},
+		renderCall(args: CodeSearchParams, 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, "codesearch", theme);
+			const summary = truncateCallSummary((args.query ?? "").trim()) || "…";
+			text.setText(
+				`${title} ${theme.fg("accent", summary)} ${theme.fg("muted", `(tokens=${clampInteger(args.tokensNum, 5000, 500, 20_000)})`)}`,
+			);
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			return renderWebToolResult(result, options, theme, context);
+		},
+	});
+}

package/extensions/web/exa.ts

@@ -0,0 +1,101 @@
+const EXA_ENDPOINT = "https://mcp.exa.ai/mcp";
+
+interface FetchResponse {
+	ok: boolean;
+	status: number;
+	text(): Promise<string>;
+}
+
+export interface ExaRequest {
+	toolName: "web_search_exa" | "get_code_context_exa";
+	arguments: Record<string, unknown>;
+}
+
+function objectValue(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : undefined;
+}
+
+function extractText(payload: unknown): string | undefined {
+	const root = objectValue(payload);
+	if (!root) return undefined;
+	const error = objectValue(root.error);
+	if (error) {
+		const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
+		throw new Error(`Exa JSON-RPC error: ${message}`);
+	}
+
+	const result = objectValue(root.result);
+	if (!result || !Array.isArray(result.content)) return undefined;
+	const text = result.content
+		.map((item) => objectValue(item))
+		.filter((item): item is Record<string, unknown> => item !== undefined)
+		.filter((item) => item.type === "text" && typeof item.text === "string")
+		.map((item) => item.text as string)
+		.join("\n");
+	return text.length > 0 ? text : undefined;
+}
+
+function parseSse(raw: string): string | undefined {
+	for (const event of raw.split(/\r?\n\r?\n/)) {
+		const data = event
+			.split(/\r?\n/)
+			.filter((line) => line.startsWith("data:"))
+			.map((line) => line.slice(5).replace(/^ /, ""))
+			.join("\n");
+		if (!data || data === "[DONE]") continue;
+		try {
+			const text = extractText(JSON.parse(data) as unknown);
+			if (text !== undefined) return text;
+		} catch (error) {
+			if (error instanceof SyntaxError) continue;
+			throw error;
+		}
+	}
+	return undefined;
+}
+
+export async function callExa(
+	request: ExaRequest,
+	signal: AbortSignal | undefined,
+	timeoutSeconds: number,
+): Promise<string | undefined> {
+	const timeoutSignal = AbortSignal.timeout(timeoutSeconds * 1000);
+	const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+	const headers: Record<string, string> = {
+		accept: "application/json, text/event-stream",
+		"content-type": "application/json",
+	};
+	const apiKey = process.env.EXA_API_KEY?.trim();
+	if (apiKey) headers["x-api-key"] = apiKey;
+
+	try {
+		const response = (await fetch(EXA_ENDPOINT, {
+			method: "POST",
+			headers,
+			body: JSON.stringify({
+				jsonrpc: "2.0",
+				id: 1,
+				method: "tools/call",
+				params: { name: request.toolName, arguments: request.arguments },
+			}),
+			signal: requestSignal,
+		})) as FetchResponse;
+		if (!response.ok) {
+			throw new Error(`Exa request failed (${response.status}): ${await response.text()}`);
+		}
+
+		const raw = await response.text();
+		try {
+			const direct = extractText(JSON.parse(raw) as unknown);
+			if (direct !== undefined) return direct;
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+		}
+		return parseSse(raw);
+	} catch (error) {
+		if (timeoutSignal.aborted && signal?.aborted !== true) {
+			throw new DOMException("Exa request timed out", "TimeoutError");
+		}
+		throw error;
+	}
+}

package/extensions/web/html.ts

@@ -0,0 +1,67 @@
+function decodeCodePoint(value: number): string {
+	if (!Number.isFinite(value) || value < 0 || value > 0x10ffff || (value >= 0xd800 && value <= 0xdfff)) {
+		return "";
+	}
+	return String.fromCodePoint(value);
+}
+
+function decodeEntities(text: string): string {
+	return text
+		.replace(/&nbsp;/gi, " ")
+		.replace(/&amp;/gi, "&")
+		.replace(/&lt;/gi, "<")
+		.replace(/&gt;/gi, ">")
+		.replace(/&quot;/gi, '"')
+		.replace(/&apos;/gi, "'")
+		.replace(/&#39;/gi, "'")
+		.replace(/&#(\d+);/g, (_match, value: string) => decodeCodePoint(Number.parseInt(value, 10)))
+		.replace(/&#x([\da-f]+);/gi, (_match, value: string) => decodeCodePoint(Number.parseInt(value, 16)));
+}
+
+function removeNoise(html: string): string {
+	return html
+		.replace(/<(head|script|style|noscript|iframe|object|embed)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "")
+		.replace(/<(head|script|style|noscript|iframe|object|embed)\b[^>]*\/?\s*>/gi, "");
+}
+
+function normalize(text: string): string {
+	return decodeEntities(text)
+		.replace(/\r\n?/g, "\n")
+		.replace(/\t/g, " ")
+		.split("\n")
+		.map((line) => line.replace(/[^\S\n]+/g, " ").trim())
+		.join("\n")
+		.replace(/\n{3,}/g, "\n\n")
+		.trim();
+}
+
+export function htmlToText(html: string): string {
+	return normalize(
+		removeNoise(html)
+			.replace(/<br\s*\/?>/gi, "\n")
+			.replace(/<\/p\s*>/gi, "\n\n")
+			.replace(/<li\b[^>]*>/gi, "\n- ")
+			.replace(/<\/li\s*>/gi, "")
+			.replace(/<\/(div|section|article|header|footer|main|aside|tr|h[1-6]|ul|ol|table)\s*>/gi, "\n")
+			.replace(/<[^>]+>/g, " "),
+	);
+}
+
+export function htmlToMarkdown(html: string): string {
+	return normalize(
+		removeNoise(html)
+			.replace(
+				/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1\s*>/gi,
+				(_match, level: string, body: string) => `\n${"#".repeat(Number(level))} ${body}\n`,
+			)
+			.replace(/<a\b[^>]*href\s*=\s*["']([^"']+)["'][^>]*>([\s\S]*?)<\/a\s*>/gi, "[$2]($1)")
+			.replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1\s*>/gi, "**$2**")
+			.replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1\s*>/gi, "*$2*")
+			.replace(/<code\b[^>]*>([\s\S]*?)<\/code\s*>/gi, "`$1`")
+			.replace(/<li\b[^>]*>/gi, "\n- ")
+			.replace(/<\/li\s*>/gi, "")
+			.replace(/<br\s*\/?>/gi, "\n")
+			.replace(/<\/(p|div|section|article|header|footer|main|aside|ul|ol|table|tr)\s*>/gi, "\n")
+			.replace(/<[^>]+>/g, " "),
+	);
+}

package/extensions/web/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { createCodeSearchTool } from "./codesearch.ts";
+import { createWebFetchTool } from "./webfetch.ts";
+import { createWebSearchTool } from "./websearch.ts";
+
+export default function webExtension(pi: ExtensionAPI): void {
+	const rowState = createToolRowStateStore(pi, "web.tool-row-state");
+	pi.registerTool(createWebFetchTool(rowState));
+	pi.registerTool(createWebSearchTool(rowState));
+	pi.registerTool(createCodeSearchTool(rowState));
+	pi.on("session_start", () => rowState.clear());
+}

package/extensions/web/limits.ts

@@ -0,0 +1,11 @@
+const MAX_TIMEOUT_SECONDS = 600;
+
+export function clampInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {
+	const effective = value === undefined || !Number.isFinite(value) ? fallback : value;
+	return Math.max(minimum, Math.min(Math.floor(effective), maximum));
+}
+
+export function normalizeTimeout(value: number | undefined, fallback: number): number {
+	if (value === undefined || !Number.isFinite(value) || value <= 0) return fallback;
+	return Math.min(Math.floor(value), MAX_TIMEOUT_SECONDS);
+}

package/extensions/web/tool-output.ts

@@ -0,0 +1,54 @@
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type AgentToolResult,
+	type Theme,
+	type ToolRenderResultOptions,
+	type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+import { type Component, Text } from "@earendil-works/pi-tui";
+
+export function truncateToolOutput(text: string): { text: string; truncation?: TruncationResult } {
+	const truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	if (!truncation.truncated) return { text: truncation.content };
+
+	return {
+		text:
+			truncation.content +
+			`\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines ` +
+			`(${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)})]`,
+		truncation,
+	};
+}
+
+export function truncateCallSummary(text: string): string {
+	return text.length <= 90 ? text : `${text.slice(0, 89)}…`;
+}
+
+export function renderWebToolResult(
+	result: AgentToolResult<unknown>,
+	options: ToolRenderResultOptions,
+	theme: Theme,
+	context: { lastComponent: Component | undefined },
+): Text {
+	const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+	const firstText = result.content.find((item) => item.type === "text");
+
+	if (options.isPartial) {
+		text.setText("");
+		return text;
+	}
+	if (!options.expanded || firstText?.type !== "text") {
+		text.setText("");
+		return text;
+	}
+
+	const output = firstText.text
+		.split("\n")
+		.map((line) => theme.fg("toolOutput", line))
+		.join("\n");
+	text.setText(output ? `\n${output}` : "");
+	return text;
+}