@shanepadgett/tau-agent 0.1.0

package/extensions/subagent/agents/web-research.md

@@ -0,0 +1,95 @@
+---
+name: web-research
+description: Perform multi-step web and code research with source-backed synthesis
+tools:
+  - websearch
+  - codesearch
+  - webfetch
+model: openai-codex/gpt-5.6-sol
+thinking: medium
+---
+
+Stay inside delegated task. Answer exactly what was asked. No broader research, background collection, unrequested recommendations, or implementation work.
+
+Delegating prompt is output contract. Requested shape wins. Otherwise use the smallest matching shape below.
+
+## Effort and depth
+
+Use the least research and fewest tokens needed for a reliable answer. Match depth to the question, not the agent's available tools.
+
+- For a simple lookup, verify the value and return it with a direct source URL in one line.
+- For a focused question, give the direct answer and only the evidence or qualification needed to support it.
+- For a comparison or recommendation, explain the decision criteria, strongest supported reasons, meaningful tradeoffs, and why plausible alternatives fit worse. Include only factors relevant to the requested use case.
+- For a multi-part or explicitly deep task, synthesize across suitable sources using the relevant structured result shape.
+
+Do not turn a lookup into a survey. Do not compress a consequential recommendation until its reasoning becomes unusable. Do not produce a research brief unless the delegating prompt requests depth or the question requires synthesis across multiple sources.
+
+## Research discipline
+
+1. Extract the exact question, scope, freshness requirement, and required output before searching.
+2. Start with the most specific query that could answer the question. Refine queries from evidence instead of searching the whole topic.
+3. Use `websearch` for discovery, `codesearch` for implementation details and API usage, and `webfetch` to inspect authoritative pages found during discovery.
+4. Every search or fetch must resolve a pending question. Stop when each requested claim has sufficient evidence.
+5. Prefer primary sources: official documentation, specifications, source repositories, release notes, and first-party statements. Use secondary sources only when primary sources are unavailable or the task asks for outside analysis.
+6. Check publication and version context when facts may have changed. Do not combine claims from incompatible versions without saying so.
+7. Corroborate consequential claims with independent sources when practical. A page repeating another source is not independent evidence.
+8. Put unresolved or conflicting facts under `Unknowns`. Do not fill gaps with plausible synthesis.
+
+## Result shapes
+
+Use only relevant sections. Omit empty sections.
+
+### Answer a factual question
+
+- `Answer:` direct answer
+- `Evidence:` claim — source URL
+- `Qualification:` limits, version, or date context when needed
+
+### Explain a topic
+
+- `Summary:` concise explanation
+- `Key facts:` source-backed facts
+- `Implications:` requested consequences only
+- `Unknowns:` unresolved facts
+
+### Compare
+
+- `Shared:` source-backed similarities
+- `Differences:` differences by requested aspect
+- `Relevant consequence:` requested consequences only
+
+### Find an implementation approach
+
+- `Recommended approach:` approach supported by current documentation or examples
+- `API or mechanism:` relevant interfaces, behavior, and constraints
+- `Example sources:` direct documentation or source links
+- `Unknowns:` missing version or environment details
+
+### Verify a claim
+
+- `Verdict:` `yes`, `no`, `partially`, or `unknown`
+- `Evidence:` source-backed facts
+- `Qualification:` only when needed
+
+### Survey options
+
+`Option` — relevant capability — constraint — source URL
+
+State selection criteria. Do not rank options unless the task asks for a recommendation.
+
+### Research brief
+
+- `Findings:` ordered by relevance
+- `Evidence:` source URLs attached to each material claim
+- `Conflicts:` disagreements between credible sources
+- `Unknowns:` evidence still needed
+
+## Reporting rules
+
+- Cite every material factual claim with a direct source URL.
+- Link to the page containing the evidence, not a search result page.
+- Separate source claims from inference. Label inference.
+- Quote only the smallest fragment needed to preserve exact wording.
+- Describe source quality or limitations when they affect confidence.
+- Use exact dates and versions when freshness matters.
+- No preamble, search log, generic topic summary, repeated evidence, or unrequested next steps.

package/extensions/subagent/agents.ts

@@ -0,0 +1,196 @@
+import { access, readdir, readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, extname, join, parse, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+
+export interface AgentDefinition {
+	name: string;
+	description: string;
+	tools: string[];
+	model?: string;
+	thinking?: ThinkingLevel;
+	prompt: string;
+	path: string;
+}
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export interface AgentDiagnostic {
+	path: string;
+	name: string;
+	reason: string;
+}
+
+export interface AgentDiscovery {
+	agents: Map<string, AgentDefinition>;
+	invalid: Map<string, AgentDiagnostic[]>;
+	diagnostics: AgentDiagnostic[];
+}
+
+const BUILTIN_AGENTS_DIR = join(dirname(fileURLToPath(import.meta.url)), "agents");
+
+async function directoryExists(path: string): Promise<boolean> {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+export async function findProjectAgentsDir(cwd: string): Promise<string | undefined> {
+	const home = resolve(homedir());
+	let current = resolve(cwd);
+	while (current !== home) {
+		const candidate = join(current, ".pi", "tau", "agents");
+		if (await directoryExists(candidate)) return candidate;
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return undefined;
+}
+
+function parseDefinition(
+	path: string,
+	content: string,
+): { definition?: AgentDefinition; diagnostic?: AgentDiagnostic } {
+	const fallbackName = basename(path, extname(path));
+	try {
+		const parsed = parseFrontmatter(content);
+		const fields = Object.keys(parsed.frontmatter);
+		const rawName = parsed.frontmatter.name;
+		const name = typeof rawName === "string" && rawName.trim() ? rawName.trim() : fallbackName;
+		const reasons: string[] = [];
+		for (const field of fields) {
+			if (!new Set(["name", "description", "tools", "model", "thinking"]).has(field))
+				reasons.push(`unsupported field "${field}"`);
+		}
+		if (typeof rawName !== "string" || !rawName.trim()) reasons.push("name must be a non-empty string");
+		const rawDescription = parsed.frontmatter.description;
+		if (typeof rawDescription !== "string" || !rawDescription.trim())
+			reasons.push("description must be a non-empty string");
+		const rawTools = parsed.frontmatter.tools;
+		if (!Array.isArray(rawTools) || rawTools.length === 0) reasons.push("tools must be a non-empty array");
+		else {
+			const tools = rawTools
+				.filter((tool): tool is string => typeof tool === "string" && tool.trim().length > 0)
+				.map((tool) => tool.trim());
+			if (tools.length !== rawTools.length) reasons.push("tools must contain non-empty strings");
+			if (new Set(tools).size !== tools.length) reasons.push("tools must be unique");
+			if (tools.includes("subagent")) reasons.push("tool subagent is forbidden");
+		}
+		if (!parsed.body.trim()) reasons.push("prompt body must be non-empty");
+		const rawModel = parsed.frontmatter.model;
+		if (rawModel !== undefined && (typeof rawModel !== "string" || !/^[^/\s]+\/[^/\s]+$/.test(rawModel.trim())))
+			reasons.push("model must be a provider/model string");
+		const rawThinking = parsed.frontmatter.thinking;
+		const thinkingLevels: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+		if (rawThinking !== undefined && !thinkingLevels.includes(rawThinking as ThinkingLevel))
+			reasons.push(`thinking must be one of ${thinkingLevels.join(", ")}`);
+		if (reasons.length > 0) return { diagnostic: { path, name, reason: reasons.join("; ") } };
+		return {
+			definition: {
+				name,
+				description: (rawDescription as string).trim(),
+				tools: (rawTools as string[]).map((tool) => tool.trim()),
+				model: typeof rawModel === "string" ? rawModel.trim() : undefined,
+				thinking: rawThinking as ThinkingLevel | undefined,
+				prompt: parsed.body.trim(),
+				path,
+			},
+		};
+	} catch (error) {
+		return {
+			diagnostic: {
+				path,
+				name: fallbackName,
+				reason: error instanceof Error ? error.message : "invalid frontmatter",
+			},
+		};
+	}
+}
+
+async function loadScope(
+	directory: string,
+	required: boolean,
+): Promise<Map<string, AgentDefinition | AgentDiagnostic[]>> {
+	let entries;
+	try {
+		entries = (await readdir(directory, { withFileTypes: true }))
+			.filter((entry) => entry.isFile() && extname(entry.name) === ".md")
+			.sort((a, b) => a.name.localeCompare(b.name));
+	} catch (error) {
+		if (!required) return new Map();
+		const reason = error instanceof Error ? error.message : "directory unavailable";
+		return new Map([
+			["scout", [{ path: directory, name: "scout", reason: `packaged agents unavailable: ${reason}` }]],
+			[
+				"web-research",
+				[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],
+			],
+		]);
+	}
+	const grouped = new Map<string, Array<AgentDefinition | AgentDiagnostic>>();
+	for (const entry of entries) {
+		const path = join(directory, entry.name);
+		let parsed;
+		try {
+			parsed = parseDefinition(path, await readFile(path, "utf8"));
+		} catch (error) {
+			parsed = {
+				diagnostic: {
+					path,
+					name: parse(entry.name).name,
+					reason: error instanceof Error ? error.message : "file unreadable",
+				},
+			};
+		}
+		const value = parsed.definition ?? parsed.diagnostic;
+		if (!value) continue;
+		const values = grouped.get(value.name) ?? [];
+		values.push(value);
+		grouped.set(value.name, values);
+	}
+	const scope = new Map<string, AgentDefinition | AgentDiagnostic[]>();
+	for (const [name, values] of grouped) {
+		if (values.length === 1 && "prompt" in values[0]) scope.set(name, values[0]);
+		else {
+			const diagnostics = values.map((value) =>
+				"reason" in value ? value : { path: value.path, name, reason: `duplicate name "${name}" in this scope` },
+			);
+			if (values.length > 1) {
+				for (const value of values)
+					if ("reason" in value) value.reason += `; duplicate name "${name}" in this scope`;
+			}
+			scope.set(name, diagnostics);
+		}
+	}
+	return scope;
+}
+
+export async function discoverAgents(cwd: string, trusted: boolean): Promise<AgentDiscovery> {
+	const scopes = [
+		await loadScope(BUILTIN_AGENTS_DIR, true),
+		await loadScope(join(getAgentDir(), "tau", "agents"), false),
+	];
+	if (trusted) {
+		const project = await findProjectAgentsDir(cwd);
+		if (project) scopes.push(await loadScope(project, false));
+	}
+	const agents = new Map<string, AgentDefinition>();
+	const invalid = new Map<string, AgentDiagnostic[]>();
+	const diagnostics = scopes.flatMap((scope) =>
+		[...scope.values()].flatMap((value) => (Array.isArray(value) ? value : [])),
+	);
+	for (const scope of scopes) {
+		for (const [name, value] of scope) {
+			agents.delete(name);
+			invalid.delete(name);
+			if (Array.isArray(value)) invalid.set(name, value);
+			else agents.set(name, value);
+		}
+	}
+	return { agents, invalid, diagnostics };
+}

package/extensions/subagent/index.ts

@@ -0,0 +1,214 @@
+import { defineTool, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { createToolRowStateStore } from "../../shared/tool-row-state.js";
+import { discoverAgents, type AgentDiscovery } from "./agents.ts";
+import { renderSubagentCall, renderSubagentResult } from "./render.ts";
+import { FifoGate, runSubagent, type SubagentDetails } from "./run.ts";
+
+const params = Type.Object(
+	{ agent: Type.String({ minLength: 1 }), task: Type.String({ minLength: 1 }) },
+	{ additionalProperties: false },
+);
+
+export default function subagentExtension(pi: ExtensionAPI): void {
+	const gate = new FifoGate(4);
+	const controllers = new Set<AbortController>();
+	const fingerprints = new Map<string, string>();
+	const runtimeWarnings = new Set<string>();
+	const rowState = createToolRowStateStore(pi, "subagent.tool-row-state");
+	const warn = (discovery: AgentDiscovery, ctx: ExtensionContext) => {
+		const current = new Set<string>();
+		const grouped = new Map<string, string[]>();
+		for (const diagnostic of discovery.diagnostics) {
+			const reasons = grouped.get(diagnostic.path) ?? [];
+			reasons.push(diagnostic.reason);
+			grouped.set(diagnostic.path, reasons);
+		}
+		for (const [path, reasons] of grouped) {
+			current.add(path);
+			const fingerprint = [...reasons].sort().join("\0");
+			if (fingerprints.get(path) !== fingerprint)
+				ctx.ui.notify(`Invalid subagent definition ${path}: ${reasons.join("; ").slice(0, 500)}`, "warning");
+			fingerprints.set(path, fingerprint);
+		}
+		for (const path of fingerprints.keys()) if (!current.has(path)) fingerprints.delete(path);
+	};
+	pi.registerTool(
+		defineTool<typeof params, SubagentDetails>({
+			name: "subagent",
+			label: "Subagent",
+			description:
+				"Delegate one focused task to a named isolated child agent. Output is limited to 50KB or 2,000 lines.",
+			promptSnippet: "Delegate one focused task to a named isolated child agent",
+			parameters: params,
+			executionMode: "parallel",
+			async execute(_id, raw, signal, onUpdate, ctx) {
+				const agent = raw.agent.trim();
+				const task = raw.task.trim();
+				const thinkingLevel = pi.getThinkingLevel();
+				if (!agent || !task)
+					return {
+						content: [{ type: "text", text: "Subagent input requires non-empty agent and task" }],
+						details: {
+							agent,
+							task,
+							status: "failed",
+							phase: "queue",
+							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
+							thinkingLevel,
+							toolCalls: 0,
+							actions: [],
+							omittedActions: 0,
+							omittedErrors: 0,
+							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+							durationMs: 0,
+							error: "Invalid input",
+						},
+					};
+				const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
+				warn(discovery, ctx);
+				const definition = discovery.agents.get(agent);
+				const invalid = discovery.invalid.get(agent);
+				if (!definition) {
+					const reason = invalid?.map((item) => item.reason).join("; ") ?? "unknown agent";
+					const names = [...discovery.agents.keys()].sort().join(", ") || "none";
+					const error = `Agent ${agent} discovery failed: ${reason}. Runnable agents: ${names}`;
+					return {
+						content: [{ type: "text", text: error }],
+						details: {
+							agent,
+							task,
+							status: "failed",
+							phase: "discovery",
+							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
+							thinkingLevel,
+							toolCalls: 0,
+							actions: [],
+							omittedActions: 0,
+							omittedErrors: 0,
+							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+							durationMs: 0,
+							error,
+						},
+					};
+				}
+				const controller = new AbortController();
+				controllers.add(controller);
+				const combined = AbortSignal.any([controller.signal, ...(signal ? [signal] : [])]);
+				let release: (() => void) | undefined;
+				try {
+					await onUpdate?.({
+						content: [{ type: "text", text: `${agent}: waiting` }],
+						details: {
+							agent,
+							task,
+							status: "waiting",
+							phase: "queue",
+							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
+							thinkingLevel,
+							toolCalls: 0,
+							actions: [],
+							omittedActions: 0,
+							omittedErrors: 0,
+							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+							durationMs: 0,
+						},
+					});
+					try {
+						release = await gate.acquire(combined);
+					} catch (error) {
+						const message = error instanceof Error ? error.message : `Agent ${agent} queue failed`;
+						const details: SubagentDetails = {
+							agent,
+							task,
+							status: combined.aborted ? "aborted" : "failed",
+							phase: "queue",
+							model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "unavailable",
+							thinkingLevel,
+							toolCalls: 0,
+							actions: [],
+							omittedActions: 0,
+							omittedErrors: 0,
+							usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 },
+							durationMs: 0,
+							error: message,
+						};
+						return { content: [{ type: "text", text: message }], details };
+					}
+					const result = await runSubagent({
+						definition,
+						task,
+						ctx,
+						thinkingLevel,
+						signal: combined,
+						onWarning: (warning) => {
+							const message = `Subagent definition ${definition.path}: ${warning}`;
+							if (runtimeWarnings.has(message)) return;
+							runtimeWarnings.add(message);
+							ctx.ui.notify(message, "warning");
+						},
+						onUpdate: (details) =>
+							onUpdate?.({
+								content: [
+									{
+										type: "text",
+										text: details.currentActivity ?? details.response ?? `${agent}: ${details.status}`,
+									},
+								],
+								details,
+							}),
+					});
+					return { content: [{ type: "text", text: result.content }], details: result.details };
+				} finally {
+					release?.();
+					controllers.delete(controller);
+				}
+			},
+			renderCall(args, theme, context) {
+				return renderSubagentCall(args, theme, {
+					executionStarted: context.executionStarted,
+					lastComponent: context.lastComponent,
+					rowState,
+					rowId: context.toolCallId,
+					invalidate: context.invalidate,
+				});
+			},
+			renderResult(result, options, theme, context) {
+				return renderSubagentResult(result, options.expanded, theme, {
+					lastComponent: context.lastComponent,
+					rowState,
+					rowId: context.toolCallId,
+					invalidate: context.invalidate,
+				});
+			},
+		}),
+	);
+	pi.on("before_agent_start", async (event, ctx) => {
+		if (!pi.getActiveTools().includes("subagent")) return;
+		const discovery = await discoverAgents(ctx.cwd, ctx.isProjectTrusted());
+		warn(discovery, ctx);
+		const lines = [...discovery.agents.values()]
+			.sort((a, b) => a.name.localeCompare(b.name))
+			.map((agent) => `- ${agent.name}: ${agent.description}`);
+		const prompt = `## Subagents\nUse \`subagent\` when an available agent matches a focused part of the task.\n\nAvailable agents for this turn:\n${lines.join("\n")}\n\nDelegate one focused task per call. Children do not inherit parent messages. Include exact absolute reference paths when a child must inspect a repository outside the current working directory.`;
+		event.systemPromptOptions.appendSystemPrompt = event.systemPromptOptions.appendSystemPrompt
+			? `${event.systemPromptOptions.appendSystemPrompt}\n\n${prompt}`
+			: prompt;
+		return {
+			systemPrompt: `${event.systemPrompt}\n\n${prompt}`,
+		};
+	});
+	pi.on("tool_result", (event) => {
+		if (event.toolName !== "subagent") return;
+		const details = event.details as SubagentDetails | undefined;
+		if (details?.status === "failed" || details?.status === "aborted") return { isError: true };
+	});
+	pi.on("session_start", () => {
+		rowState.clear();
+		runtimeWarnings.clear();
+	});
+	pi.on("session_shutdown", () => {
+		for (const controller of controllers) controller.abort();
+		controllers.clear();
+	});
+}

package/extensions/subagent/render.ts

@@ -0,0 +1,89 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.js";
+import type { SubagentDetails } from "./run.ts";
+
+const cap = (text: string | undefined, length = 240) =>
+	!text ? "" : text.length <= length ? text : `${text.slice(0, length - 1)}…`;
+class SubagentText implements Component {
+	private readonly text = new Text("", 0, 0);
+	private value = "";
+	private truncate = false;
+	setText(value: string, truncate = false): void {
+		this.value = value;
+		this.text.setText(value);
+		this.truncate = truncate;
+	}
+	render(width: number): string[] {
+		return this.truncate
+			? this.value.split("\n").map((line) => truncateToWidth(line, width))
+			: this.text.render(width);
+	}
+	invalidate(): void {
+		this.text.invalidate();
+	}
+}
+const component = (last: unknown) => (last as SubagentText | undefined) ?? new SubagentText();
+const title = (theme: Theme, rowState: ToolRowStateStore, rowId: string, invalidate: () => void) => {
+	rowState.watch(rowId, invalidate);
+	return formatToolRowTitle(rowState, rowId, "subagent", theme);
+};
+
+export function renderSubagentCall(
+	args: { agent?: string; task?: string },
+	theme: Theme,
+	context: {
+		executionStarted: boolean;
+		lastComponent?: unknown;
+		rowState: ToolRowStateStore;
+		rowId: string;
+		invalidate: () => void;
+	},
+): Component {
+	const text = component(context.lastComponent);
+	if (context.executionStarted) {
+		text.setText("");
+		return text;
+	}
+	text.setText(
+		`${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", args.agent ?? "")} ${theme.fg("muted", args.task ?? "")}`.trimEnd(),
+		true,
+	);
+	return text;
+}
+
+export function renderSubagentResult(
+	result: { details?: SubagentDetails },
+	expanded: boolean,
+	theme: Theme,
+	context: { lastComponent?: unknown; rowState: ToolRowStateStore; rowId: string; invalidate: () => void },
+): Component {
+	const text = component(context.lastComponent);
+	const details = result.details;
+	if (!details) {
+		text.setText("");
+		return text;
+	}
+	const header = `${title(theme, context.rowState, context.rowId, context.invalidate)}  ${theme.fg("accent", details.agent)}  ${theme.fg("muted", `$${details.usage.cost.toFixed(4)} · ${(details.durationMs / 1000).toFixed(1)}s · ${details.toolCalls} tools`)}`;
+	if (!expanded) {
+		text.setText(`${header}\n${theme.fg("muted", details.task)}`, true);
+		return text;
+	}
+	const lines = [header, theme.fg("muted", `Task: ${cap(details.task, 1000)}`)];
+	for (const action of details.actions)
+		lines.push(theme.fg(action.error ? "error" : "dim", `${action.error ? "!" : "·"} ${cap(action.summary)}`));
+	if (details.response) lines.push(theme.fg("toolOutput", details.response));
+	if (details.error) lines.push(theme.fg("error", cap(details.error, 1000)));
+	lines.push(theme.fg("muted", `Model: ${details.model} · thinking: ${details.thinkingLevel}`));
+	lines.push(
+		theme.fg(
+			"muted",
+			`Tokens: ${details.usage.input} in, ${details.usage.output} out, ${details.usage.cacheRead} cache read, ${details.usage.cacheWrite} cache write · ${details.usage.turns} turns`,
+		),
+	);
+	if (details.omittedActions)
+		lines.push(theme.fg("muted", `${details.omittedActions} actions omitted (${details.omittedErrors} errors)`));
+	if (details.truncation?.path) lines.push(theme.fg("warning", `Full output: ${details.truncation.path}`));
+	text.setText(lines.join("\n"));
+	return text;
+}