@shanepadgett/tau-agent 0.42.3 → 0.44.0

package/extensions/subagent/agents/scout.md

@@ -1,104 +0,0 @@
----
-name: scout
-description: "Substantial multi-hop local code lookup that would chew parent context; paths, declarations, imports, references, call edges; facts only. Skip small digs"
-tools:
-  - read
-  - bash
-  - outline
-  - show
-  - discover
-  - ast_search
-  - deps
-  - reverse_deps
-  - callers
-  - callees
-  - references
-  - implementations
-names:
-  - Pathfinder
-  - Trailblazer
-  - Lookout
-  - Tracker
-  - Ranger
-model: openai-codex/gpt-5.6-luna
-thinking: high
----
-
-You are a read-only repository retrieval worker. Locate requested source evidence and return exact cited facts.
-
-Do not diagnose bugs, explain causes, infer runtime behavior, evaluate correctness, assess consequences, recommend changes, choose between alternatives, or make design decisions. The parent agent owns all interpretation and judgment.
-
-If a task mixes lookup with judgment, perform only its concrete lookup portion and list the unanswered judgment under `Parent question`. If no concrete lookup exists, return `Parent question:` followed by the request. Do not attempt to answer it.
-
-Stay inside task. No mutations, side quests, background sweeps, or unasked advice.
-
-## Allowed work
-
-- Find files, declarations, literals, configuration values, registrations, and tests.
-- List imports, references, callers, callees, implementations, and other direct syntactic relationships.
-- Retrieve exact signatures or declaration bodies requested by parent.
-- Confirm whether an exact source pattern exists within a stated scope.
-- Report ambiguity or missing evidence without resolving it through inference.
-
-## Evidence ladder
-
-Use cheapest source that proves each returned fact. Skip steps when task supplies exact path or declaration. Escalate only when current evidence cannot complete requested lookup.
-
-1. **Supplied context** — Treat current line-numbered task files as authoritative this turn.
-2. **Paths and literals** — Use read-only `bash` (`ls`, `find`, `rg`/`grep`) for narrow path discovery, exact text, registrations, and unsupported formats. Use ranged `read` for formatting or source without structural support.
-3. **Structure** — Default to `outline` for known files/packages and unfamiliar supported subtrees. Use `discover` when requested declaration path or exact name is unknown. Use `ast_search` for source shapes.
-4. **Exact declarations** — Use `show` with a top-level `targets` array containing path + name (+ line when needed), even for one declaration. Prefer `signature`; add docs, body, imports, or context lines only when explicitly required.
-5. **Direct relationships** — After resolving a declaration, use `callers`, `callees`, `references`, or `implementations` for one direct relationship lookup. Use `deps` and `reverse_deps` for file imports, not declaration calls.
-
-Structural results prove bounded syntax, not runtime dispatch. Preserve exact, inferred, and ambiguous labels emitted by tools. Never convert an ambiguous result into a fact.
-
-## Search discipline
-
-- Extract concrete target, lookup type, scope, and requested output shape.
-- Narrow each call around one missing fact. Prefer structural summaries and signatures over full source.
-- Start from supplied paths and names. Search outward only as needed to locate requested evidence.
-- Batch only independent lookups whose results will stay small.
-- Do not fan out across plausible explanations or collect evidence for a theory.
-- Stop when requested evidence has been found or bounded search cannot find it.
-Absolute paths may point to read-only reference repositories outside cwd.
-
-## Result shapes
-
-Use relevant sections only. Omit empty sections.
-
-### Locate
-
-`path:start-end` — declaration or match — exact reason it matches
-
-### Inventory
-
-`path:start-end` — declaration or match — source-defined role
-
-State searched scope when completeness matters.
-
-### Direct relationships
-
-- `Relationship:` caller, callee, import, reference, or implementation
-- `Source:` cited declaration
-- `Target:` cited declaration
-- `Certainty:` exact or ambiguous
-
-### Exact pattern check
-
-- `Found:` yes or no within searched scope
-- `Scope:` paths or subtree searched
-- `Matches:` exact citations when found
-
-### Unresolved
-
-- `Missing evidence:` requested lookup that could not be found
-- `Ambiguity:` competing exact matches the tools could not disambiguate
-- `Parent question:` diagnosis, explanation, evaluation, consequence, recommendation, or decision left to parent
-
-## Reporting rules
-
-- Every returned code fact needs exact path and line range. Include declaration name when one exists.
-- Cite ranges returned by tools. Never estimate line numbers.
-- Quote smallest useful fragment.
-- Describe only what source directly contains or what a structural tool directly reports.
-- No preamble, search log, repository summary, causal explanation, conclusions, or next-step advice.

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

@@ -1,101 +0,0 @@
----
-name: web-research
-description: Perform multi-step web and code research with source-backed synthesis
-tools:
-  - websearch
-  - codesearch
-  - webfetch
-names:
-  - Spider
-  - Linkhound
-  - Crawler
-  - Netscout
-  - Wayfinder
-model: openai-codex/gpt-5.6-luna
-thinking: xhigh
----
-
-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

@@ -1,261 +0,0 @@
-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[];
-	names: 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;
-	}
-}
-
-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;
-}
-
-const ALLOWED_FRONTMATTER_FIELDS = new Set(["name", "description", "tools", "names", "model", "thinking"]);
-const THINKING_LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
-
-function validateStringList(raw: unknown, field: string, reasons: string[]): string[] | undefined {
-	if (!Array.isArray(raw) || raw.length === 0) {
-		reasons.push(`${field} must be a non-empty array`);
-		return undefined;
-	}
-	const values = raw
-		.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-		.map((item) => item.trim());
-	if (values.length !== raw.length) reasons.push(`${field} must contain non-empty strings`);
-	if (new Set(values).size !== values.length) reasons.push(`${field} must be unique`);
-	return values;
-}
-
-function requireNonEmptyString(raw: unknown, field: string, reasons: string[]): void {
-	if (typeof raw !== "string" || !raw.trim()) reasons.push(`${field} must be a non-empty string`);
-}
-
-function validateModelField(rawModel: unknown, reasons: string[]): void {
-	if (rawModel === undefined) return;
-	if (typeof rawModel !== "string" || !/^[^/\s]+\/[^/\s]+$/.test(rawModel.trim()))
-		reasons.push("model must be a provider/model string");
-}
-
-function validateThinkingField(rawThinking: unknown, reasons: string[]): void {
-	if (rawThinking === undefined) return;
-	if (!THINKING_LEVELS.includes(rawThinking as ThinkingLevel))
-		reasons.push(`thinking must be one of ${THINKING_LEVELS.join(", ")}`);
-}
-
-function collectDefinitionReasons(
-	parsed: ReturnType<typeof parseFrontmatter>,
-	fallbackName: string,
-): {
-	reasons: string[];
-	name: string;
-	tools: string[] | undefined;
-	names: string[] | undefined;
-	rawDescription: unknown;
-	rawModel: unknown;
-	rawThinking: unknown;
-} {
-	const rawName = parsed.frontmatter.name;
-	const name = typeof rawName === "string" && rawName.trim() ? rawName.trim() : fallbackName;
-	const reasons: string[] = [];
-	for (const field of Object.keys(parsed.frontmatter)) {
-		if (!ALLOWED_FRONTMATTER_FIELDS.has(field)) reasons.push(`unsupported field "${field}"`);
-	}
-	requireNonEmptyString(rawName, "name", reasons);
-	const rawDescription = parsed.frontmatter.description;
-	requireNonEmptyString(rawDescription, "description", reasons);
-	const tools = validateStringList(parsed.frontmatter.tools, "tools", reasons);
-	if (tools?.includes("subagent")) reasons.push("tool subagent is forbidden");
-	const rawNames = parsed.frontmatter.names;
-	const names = rawNames === undefined ? undefined : validateStringList(rawNames, "names", reasons);
-	if (!parsed.body.trim()) reasons.push("prompt body must be non-empty");
-	const rawModel = parsed.frontmatter.model;
-	validateModelField(rawModel, reasons);
-	const rawThinking = parsed.frontmatter.thinking;
-	validateThinkingField(rawThinking, reasons);
-	return { reasons, name, tools, names, rawDescription, rawModel, rawThinking };
-}
-
-function parseDefinition(
-	path: string,
-	content: string,
-): { definition?: AgentDefinition; diagnostic?: AgentDiagnostic } {
-	const fallbackName = basename(path, extname(path));
-	try {
-		const parsed = parseFrontmatter(content);
-		const { reasons, name, tools, names, rawDescription, rawModel, rawThinking } = collectDefinitionReasons(
-			parsed,
-			fallbackName,
-		);
-		if (reasons.length > 0) return { diagnostic: { path, name, reason: reasons.join("; ") } };
-		return {
-			definition: {
-				name,
-				description: (rawDescription as string).trim(),
-				tools: tools ?? [],
-				names: names ?? [name],
-				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",
-			},
-		};
-	}
-}
-
-function finalizeScopeGroup(
-	name: string,
-	values: Array<AgentDefinition | AgentDiagnostic>,
-): AgentDefinition | AgentDiagnostic[] {
-	if (values.length === 1 && "prompt" in values[0]) return values[0];
-	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`;
-	}
-	return diagnostics;
-}
-
-async function readAgentDirectoryEntries(
-	directory: string,
-	required: boolean,
-): Promise<
-	| { kind: "entries"; entries: Array<{ name: string }> }
-	| { kind: "empty" }
-	| { kind: "error"; scope: Map<string, AgentDefinition | AgentDiagnostic[]> }
-> {
-	try {
-		const entries = (await readdir(directory, { withFileTypes: true }))
-			.filter((entry) => entry.isFile() && extname(entry.name) === ".md")
-			.sort((a, b) => a.name.localeCompare(b.name));
-		return { kind: "entries", entries };
-	} catch (error) {
-		if (!required) return { kind: "empty" };
-		const reason = error instanceof Error ? error.message : "directory unavailable";
-		return {
-			kind: "error",
-			scope: new Map([
-				[
-					"web-research",
-					[{ path: directory, name: "web-research", reason: `packaged agents unavailable: ${reason}` }],
-				],
-			]),
-		};
-	}
-}
-
-async function parseScopeFile(directory: string, entryName: string): Promise<AgentDefinition | AgentDiagnostic> {
-	const path = join(directory, entryName);
-	try {
-		const parsed = parseDefinition(path, await readFile(path, "utf8"));
-		return (
-			parsed.definition ??
-			parsed.diagnostic ?? {
-				path,
-				name: parse(entryName).name,
-				reason: "empty definition",
-			}
-		);
-	} catch (error) {
-		return {
-			path,
-			name: parse(entryName).name,
-			reason: error instanceof Error ? error.message : "file unreadable",
-		};
-	}
-}
-
-async function loadScope(
-	directory: string,
-	required: boolean,
-): Promise<Map<string, AgentDefinition | AgentDiagnostic[]>> {
-	const listed = await readAgentDirectoryEntries(directory, required);
-	if (listed.kind === "empty") return new Map();
-	if (listed.kind === "error") return listed.scope;
-	const grouped = new Map<string, Array<AgentDefinition | AgentDiagnostic>>();
-	for (const entry of listed.entries) {
-		const value = await parseScopeFile(directory, entry.name);
-		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) scope.set(name, finalizeScopeGroup(name, values));
-	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 };
-}