@shanepadgett/tau-agent 0.1.0

package/extensions/web/webfetch.ts

@@ -0,0 +1,177 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+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 { htmlToMarkdown, htmlToText } from "./html.ts";
+import { normalizeTimeout } from "./limits.ts";
+import { renderWebToolResult, truncateCallSummary, truncateToolOutput } from "./tool-output.ts";
+
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+interface FetchResponse {
+	ok: boolean;
+	status: number;
+	headers: { get(name: string): string | null };
+	body: ReadableStream<Uint8Array> | null;
+}
+
+const webFetchParams = Type.Object(
+	{
+		url: Type.String({ description: "URL to fetch (http:// or https://)" }),
+		format: Type.Optional(
+			StringEnum(["markdown", "text", "html"] as const, { description: "Output format (default: markdown)" }),
+		),
+		timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 30, max: 600)" })),
+	},
+	{ additionalProperties: false },
+);
+
+type WebFetchParams = Static<typeof webFetchParams>;
+interface WebFetchDetails {
+	url: string;
+	format: "markdown" | "text" | "html";
+	mime: string;
+	bytes: number;
+	truncation?: TruncationResult;
+}
+
+async function readResponseBody(response: FetchResponse): Promise<Uint8Array> {
+	if (!response.body) return new Uint8Array();
+	const reader = response.body.getReader();
+	const chunks: Uint8Array[] = [];
+	let bytes = 0;
+	try {
+		while (true) {
+			const next = await reader.read();
+			if (next.done) break;
+			bytes += next.value.byteLength;
+			if (bytes > MAX_RESPONSE_BYTES) {
+				await reader.cancel().catch(() => undefined);
+				throw new Error("Response too large (limit is 5MB)");
+			}
+			chunks.push(next.value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks, bytes);
+}
+
+function renderCallSummary(args: WebFetchParams): string {
+	return truncateCallSummary((args.url ?? "").trim());
+}
+
+export function createWebFetchTool(rowState: ToolRowStateStore) {
+	return defineTool<typeof webFetchParams, WebFetchDetails | undefined>({
+		name: "webfetch",
+		label: "Web Fetch",
+		description:
+			"Fetch a known HTTP(S) URL as Markdown, text, or HTML. Supports inline images, limits response bodies to 5 MB, and truncates text to 2,000 lines or 50 KB.",
+		promptSnippet: "Fetch a specific URL and extract readable content",
+		promptGuidelines: [
+			"Use webfetch when you already have a URL and need its content.",
+			"Use websearch for broad discovery and codesearch for implementation-oriented lookups.",
+			"Use a separate research workflow instead of webfetch when several searches, fetches, and synthesis are needed.",
+		],
+		parameters: webFetchParams,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			let url: URL;
+			try {
+				url = new URL(params.url);
+			} catch {
+				throw new Error(`Invalid URL: ${params.url}`);
+			}
+			if (url.protocol !== "http:" && url.protocol !== "https:") {
+				throw new Error("URL must use http:// or https://");
+			}
+
+			const format = params.format ?? "markdown";
+			const timeout = normalizeTimeout(params.timeout, 30);
+			await onUpdate?.({ content: [{ type: "text", text: "Fetching page..." }], details: undefined });
+			const timeoutSignal = AbortSignal.timeout(timeout * 1000);
+			const requestSignal = signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+
+			try {
+				const accept =
+					format === "markdown"
+						? "text/markdown;q=1.0, text/plain;q=0.8, text/html;q=0.7, */*;q=0.1"
+						: format === "text"
+							? "text/plain;q=1.0, text/markdown;q=0.9, text/html;q=0.8, */*;q=0.1"
+							: "text/html;q=1.0, application/xhtml+xml;q=0.9, */*;q=0.1";
+				const headers = {
+					"User-Agent":
+						"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36",
+					Accept: accept,
+					"Accept-Language": "en-US,en;q=0.9",
+				};
+				const first = (await fetch(url.toString(), {
+					method: "GET",
+					headers,
+					signal: requestSignal,
+				})) as FetchResponse;
+				let response = first;
+				if (first.status === 403 && first.headers.get("cf-mitigated")?.toLowerCase() === "challenge") {
+					await first.body?.cancel().catch(() => undefined);
+					response = (await fetch(url.toString(), {
+						method: "GET",
+						headers: { ...headers, "User-Agent": "pi" },
+						signal: requestSignal,
+					})) as FetchResponse;
+				}
+				if (!response.ok) throw new Error(`Request failed with status ${response.status}`);
+
+				const declaredLength = response.headers.get("content-length");
+				if (declaredLength !== null) {
+					const bytes = Number.parseInt(declaredLength, 10);
+					if (Number.isFinite(bytes) && bytes > MAX_RESPONSE_BYTES) {
+						await response.body?.cancel().catch(() => undefined);
+						throw new Error("Response too large (limit is 5MB)");
+					}
+				}
+
+				const body = await readResponseBody(response);
+				const mime = (response.headers.get("content-type")?.split(";", 1)[0] ?? "").trim().toLowerCase();
+				const details = { url: url.toString(), format, mime, bytes: body.byteLength } satisfies WebFetchDetails;
+				if (mime.startsWith("image/") && mime !== "image/svg+xml") {
+					return {
+						content: [
+							{ type: "text", text: `Fetched image from ${url.toString()} (${mime})` },
+							{ type: "image", data: Buffer.from(body).toString("base64"), mimeType: mime },
+						],
+						details,
+					};
+				}
+
+				const raw = new TextDecoder().decode(body);
+				const isHtml = mime === "text/html" || mime === "application/xhtml+xml";
+				const output =
+					format === "html" ? raw : isHtml ? (format === "text" ? htmlToText(raw) : htmlToMarkdown(raw)) : raw;
+				const truncated = truncateToolOutput(output);
+				return {
+					content: [{ type: "text", text: truncated.text }],
+					details: {
+						...details,
+						...(truncated.truncation ? { truncation: truncated.truncation } : {}),
+					},
+				};
+			} catch (error) {
+				if (timeoutSignal.aborted && signal?.aborted !== true) {
+					throw new Error(`Web fetch timed out after ${timeout}s`);
+				}
+				throw error;
+			}
+		},
+		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, "webfetch", theme);
+			text.setText(
+				`${title} ${theme.fg("accent", renderCallSummary(args) || "…")} ${theme.fg("muted", `(${args.format ?? "markdown"})`)}`,
+			);
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			return renderWebToolResult(result, options, theme, context);
+		},
+	});
+}

package/extensions/web/websearch.ts

@@ -0,0 +1,100 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+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 webSearchParams = Type.Object(
+	{
+		query: Type.String({ description: "Web search query" }),
+		numResults: Type.Optional(Type.Number({ description: "Number of results (default: 8, max: 12)" })),
+		livecrawl: Type.Optional(
+			StringEnum(["fallback", "preferred"] as const, { description: "Live-crawl mode (default: fallback)" }),
+		),
+		type: Type.Optional(StringEnum(["auto", "fast"] as const, { description: "Search type (default: auto)" })),
+		contextMaxCharacters: Type.Optional(Type.Number({ description: "Context character budget (500-30000)" })),
+		timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (default: 25, max: 600)" })),
+	},
+	{ additionalProperties: false },
+);
+
+type WebSearchParams = Static<typeof webSearchParams>;
+interface WebSearchDetails {
+	query: string;
+	numResults: number;
+	livecrawl: "fallback" | "preferred";
+	type: "auto" | "fast";
+	contextMaxCharacters?: number;
+	truncation?: TruncationResult;
+}
+
+export function createWebSearchTool(rowState: ToolRowStateStore) {
+	return defineTool<typeof webSearchParams, WebSearchDetails | undefined>({
+		name: "websearch",
+		label: "Web Search",
+		description:
+			"Search the public web through Exa for current information and relevant pages. Output is truncated to 2,000 lines or 50 KB.",
+		promptSnippet: "Search the public web for current or external information",
+		promptGuidelines: [
+			"Use websearch for broad discovery, then webfetch when you have a specific URL.",
+			"Use codesearch for implementation-oriented code and documentation context.",
+			"Use a separate research workflow instead of websearch when several searches, fetches, and synthesis are needed.",
+		],
+		parameters: webSearchParams,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const timeout = normalizeTimeout(params.timeout, 25);
+			const numResults = clampInteger(params.numResults, 8, 1, 12);
+			const livecrawl = params.livecrawl ?? "fallback";
+			const type = params.type ?? "auto";
+			const contextMaxCharacters =
+				params.contextMaxCharacters === undefined
+					? undefined
+					: clampInteger(params.contextMaxCharacters, 500, 500, 30_000);
+			await onUpdate?.({ content: [{ type: "text", text: "Searching web..." }], details: undefined });
+			try {
+				const output =
+					(await callExa(
+						{
+							toolName: "web_search_exa",
+							arguments: { query: params.query, type, numResults, livecrawl, contextMaxCharacters },
+						},
+						signal,
+						timeout,
+					)) ?? "No search results found. Try a more specific query.";
+				const truncated = truncateToolOutput(output);
+				return {
+					content: [{ type: "text", text: truncated.text }],
+					details: {
+						query: params.query,
+						numResults,
+						livecrawl,
+						type,
+						...(contextMaxCharacters === undefined ? {} : { contextMaxCharacters }),
+						...(truncated.truncation ? { truncation: truncated.truncation } : {}),
+					},
+				};
+			} catch (error) {
+				if (error instanceof Error && error.name === "TimeoutError") {
+					throw new Error(`Web search timed out after ${timeout}s`);
+				}
+				throw error;
+			}
+		},
+		renderCall(args: WebSearchParams, 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, "websearch", theme);
+			const summary = truncateCallSummary((args.query ?? "").trim()) || "…";
+			text.setText(
+				`${title} ${theme.fg("accent", summary)} ${theme.fg("muted", `(${args.type ?? "auto"}, n=${clampInteger(args.numResults, 8, 1, 12)})`)}`,
+			);
+			return text;
+		},
+		renderResult(result, options, theme, context) {
+			return renderWebToolResult(result, options, theme, context);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@shanepadgett/tau-agent",
+	"version": "0.1.0",
+	"description": "Tau is a custom agentic harness built with pi extensions",
+	"type": "module",
+	"license": "MIT",
+	"keywords": [
+		"pi-package",
+		"tau",
+		"coding-agent"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/shanepadgett/tau-agent.git",
+		"directory": "packages/agent"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"extensions/**/*",
+		"shared/**/*",
+		"prompts/**/*",
+		"skills/**/*",
+		"themes/**/*",
+		"docs/**/*",
+		"schemas/**/*",
+		"README.md"
+	],
+	"dependencies": {
+		"@shanepadgett/tau-tui": "0.1.0",
+		"@toon-format/toon": "2.3.0"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-ai": "*",
+		"@earendil-works/pi-coding-agent": "*",
+		"@earendil-works/pi-tui": "*",
+		"typebox": "*"
+	},
+	"pi": {
+		"extensions": [
+			"./extensions/*/index.ts"
+		],
+		"skills": [
+			"./skills"
+		],
+		"prompts": [
+			"./prompts"
+		],
+		"themes": [
+			"./themes"
+		]
+	},
+	"engines": {
+		"node": ">=22.19.0"
+	}
+}

package/prompts/.gitkeep

@@ -0,0 +1 @@
+

package/prompts/cavemanify.md

@@ -0,0 +1,25 @@
+---
+description: Compress prose while preserving meaning
+argument-hint: "<target>"
+---
+
+Cavemanify $ARGUMENTS.
+
+Compress prose. Preserve meaning.
+
+Target is required. If missing, ask for target.
+
+If target is file or directory, edit in place. If target is pasted text, return rewritten text in chat.
+
+Rules:
+
+- Drop filler, hedging, pleasantries, throat clearing, repeated examples.
+- Keep technical terms, paths, commands, APIs, flags, regexes, constraints, quoted errors exact.
+- Keep code blocks unchanged unless user explicitly asks to rewrite code.
+- Keep decision logic and branching conditions.
+- Keep frontmatter keys. Rewrite values only when meaning stays same.
+- Long sentence -> short sentence or fragment.
+- Paragraphs -> bullets when clearer.
+- If editing scripts, change comments only unless user asks for code changes.
+
+After file edits, report changed paths only.

package/prompts/implement.md

@@ -0,0 +1,25 @@
+---
+description: Execute an approved simple or full implementation plan
+argument-hint: "[slug-or-artifact-path]"
+---
+
+Implement: $ARGUMENTS
+
+Resolve the slug or artifact path from the invocation or conversation. Ask one practical question when ambiguous.
+
+Require either:
+
+- One `docs/plans/<slug>.plan.md`; or
+- Both `docs/plans/<slug>.spec.md` and `docs/plans/<slug>.technical.md`.
+
+This invocation authorizes execution of the identified artifacts. Read them in full. For a full plan, read the spec before the technical plan.
+
+Stop on conflicting artifacts, unresolved decisions, or code evidence that invalidates the planned design. Do not invent public behavior or silently redesign. State the conflict and ask for a decision.
+
+Implement only the planned scope. Follow the technical plan's boundaries and order. Read additional code only when a named owner, direct dependency, or contradiction requires it.
+
+Choose the lowest-token accurate mutation path. Use the available patch tool for hand-authored changes. Use standard-library scripts, native tools, or shell commands for mechanical bulk changes when clearer and safer. Inspect generated or scripted results before further hand edits.
+
+Remove replaced code, stale references, unused exports, and obsolete resources in the same change. Preserve validation, data safety, security, accessibility, explicit requirements, and hardware calibration.
+
+After implementation, report only non-obvious caveats. Do not restate the plan.

package/prompts/interview.md

@@ -0,0 +1,48 @@
+---
+description: Interview the user one question at a time until shared understanding is complete
+argument-hint: "<topic>"
+---
+
+Run a structured interview about: $ARGUMENTS
+
+The argument is the interview subject. If it is empty, ask for the subject before setup.
+
+Ask only one question at a time.
+
+First search `.agents/interviews/` for a matching interview. If one exists, ask whether to resume it or start fresh. For a resume, read `decisions.md`, `open-questions.md`, and `scratchpad.md`; briefly restate the goal, exit condition, and current state; then continue at the next open question.
+
+For a fresh interview:
+
+1. Confirm the interview goal: what user and agent must agree on.
+2. Confirm the exit condition: which resolved decisions mean the interview is done. Keep it separate from the goal.
+3. Derive a concise kebab-case slug only after the goal and exit condition are confirmed. Create `.agents/interviews/<slug>/` with:
+
+```markdown
+# decisions.md
+
+## Goal
+
+<what must be understood>
+
+## Exit Condition
+
+<what must be resolved for the interview to end>
+
+## Decisions
+
+- None yet.
+```
+
+Create `open-questions.md` for unresolved questions that surface and `scratchpad.md` for useful ideas, observations, and things to revisit that fit neither decisions nor open questions. `decisions.md` contains concrete, confirmed, fully reconciled decisions only. It is never a Q&A log.
+
+Question loop:
+
+1. Pick the most important open question or unresolved point toward the exit condition. Inspect relevant material first when it informs the question. Findings do not settle a decision without user agreement.
+2. Ask exactly one question. Use yes/no for binary decisions. Use multiple choice only for a known complete set of valid alternatives: list every genuinely valid option, whether that means two or ten. Do not pad the list, add decoys, or omit a valid path. Use open-ended questions when the user's framing matters.
+3. Give a recommendation after the question or options. Explain the tradeoff in one or two sentences. Compare real tradeoffs when several choices are good.
+4. The user may think aloud, explore, or raise another topic. Respond and explore when useful. Capture legitimate new questions in `open-questions.md` and useful ideas in `scratchpad.md`, then return to the current question.
+5. Update a record only when new information belongs in it: concrete confirmed decisions in `decisions.md`; unresolved questions in `open-questions.md`; useful remainder in `scratchpad.md`. Do not edit records merely because a response arrived.
+6. If a response contradicts a decision, surface and reconcile the conflict before recording it. Revise or remove stale decisions, or reopen the point. If the correct resolution is unclear, leave it open.
+7. If the goal or exit condition shifts, confirm the shift with the user and update `decisions.md`.
+
+Finish only when the exit condition is met and `open-questions.md` is empty. Sweep `scratchpad.md` for final questions or decisions, summarize `decisions.md`, and confirm shared understanding. Do not chase unrelated edge cases after that.

package/prompts/plan-feature.md

@@ -0,0 +1,30 @@
+---
+description: Plan a feature as a brief implementation plan or full behavioral spec
+argument-hint: "[topic-or-plan]"
+---
+
+Plan the feature described by: $ARGUMENTS
+
+Begin with rough conversation. Establish what the user means before searching plan files or asking pointed questions. If continuation status remains unclear after framing, ask whether this is new work or an existing plan. Read only the plan the user identifies.
+
+Confirm these separately:
+
+1. Goal: the feature outcome.
+2. Exit condition: what must be resolved and documented before feature planning ends.
+
+Inspect only current behavior, constraints, and user-facing seams relevant to that boundary. Confirm the feature needs to exist. Cut speculative scope.
+
+Choose the smallest sufficient planning path with the user:
+
+- Simple work: write `docs/plans/<slug>.plan.md`. Keep it brief and self-contained. Include the goal, behavior, scope, relevant code, implementation direction, edge cases, and completion criteria. This artifact goes directly to `/implement`.
+- Full work: use `docs/plans/<slug>.scratch.md` for open questions, temporary research, and unsettled material. Write `docs/plans/<slug>.spec.md` as EARS-style system-behavior statements. This artifact goes to `/plan-implementation`.
+
+Derive a concise kebab-case slug after the work is framed. Planning state belongs only in those `docs/plans/` artifacts.
+
+Once the problem boundary is clear enough, ask one pointed question at a time. Inspect relevant material before asking when it can sharpen the question. Planning is not a Q&A transcript. Promote only reconciled truth into the plan or spec. Keep unresolved questions and temporary research in scratch. Continuously prune scratch as material is settled.
+
+The full spec defines required system behavior. Exclude PRD material, implementation design, unresolved choices, transcripts, and stale research.
+
+Finish only when feature outcomes, boundaries, and completion criteria are clear. For full planning, every scratch item must be promoted, discarded with user agreement, or moved to an agreed destination. Leave no unresolved or leftover scratch material.
+
+Write substantive content into the artifacts. Return only a short chat summary and the handoff command.

package/prompts/plan-implementation.md

@@ -0,0 +1,50 @@
+---
+description: Turn a feature spec into an executable technical design
+argument-hint: "[slug-or-spec-path]"
+---
+
+Plan implementation for: $ARGUMENTS
+
+Begin with rough conversational framing. Establish what the user means before searching plan files. If continuation status remains unclear after framing, ask which work to continue. Read only the plan the user identifies.
+
+Require one `docs/plans/<slug>.spec.md`. Stop if it is missing, contradictory, or leaves feature behavior undecided. Simple `docs/plans/<slug>.plan.md` artifacts go directly to `/implement`.
+
+Confirm these separately:
+
+1. Goal: the technical design to produce.
+2. Exit condition: what must be resolved before a fresh implementation chat can execute it.
+
+Reuse `docs/plans/<slug>.scratch.md` for open questions, repository findings, and temporary design work. Research only the framed feature's code ownership, callers where needed, repository patterns, dependencies, refactor opportunities, and concrete implementation paths. Ask one pointed question at a time after the boundary is clear. Continuously promote settled material and prune scratch.
+
+Climb the Code Ladder. Stop at the first rung that satisfies the spec cleanly:
+
+1. Reuse code or a repository pattern that already exists.
+2. Make a small refactor first when it removes special cases or makes the change safer and clearer.
+3. Use the standard library.
+4. Use the native platform.
+5. Use an existing dependency.
+6. Use one line when one line is clear and correct.
+7. Otherwise, write the smallest code that works.
+
+For non-trivial structure, design it twice. Compare the current or first viable shape with at least one serious alternative. Choose by concrete ownership, control flow, change surface, and failure behavior.
+
+Keep implementation shape plain. Every file, function, class, interface, setting, command, and abstraction must earn its boundary through naming, reuse, or a simpler caller. Avoid one-implementation interfaces, one-product factories, empty wrappers, fixed-value configuration, and scaffolding for hypothetical work. Prefer focused files whose names make repository search useful. Refactor only where it reduces the planned change or removes special cases.
+
+Write `docs/plans/<slug>.technical.md` with:
+
+- Goal and completion condition.
+- Chosen design plus serious alternatives and tradeoffs.
+- Exact files and owners.
+- Data and control flow.
+- Existing code to reuse and any required refactors.
+- Replaced code and resources to delete.
+- Implementation order.
+- Edge cases and boundaries.
+- Validation.
+- Exact code references where useful.
+
+Make it self-contained and precise enough for a less-capable agent without prescribing every line of code.
+
+Finish only when no basic design question remains, `technical.md` can guide a fresh implementation chat, and every scratch item has been promoted, discarded with user agreement, or moved to an agreed destination. Leave no unresolved or leftover scratch material.
+
+Write substantive content into the artifacts. Return only a short chat summary and the `/implement` handoff.