@shanepadgett/tau-agent 0.1.0

package/extensions/subagent/run.ts

@@ -0,0 +1,325 @@
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import {
+	createAgentSession,
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	SessionManager,
+	truncateHead,
+	type AgentSession,
+	type AgentSessionEvent,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { AgentDefinition } from "./agents.ts";
+
+const PREVIEW_LIMIT = 600;
+const VALUE_LIMIT = 180;
+
+export interface SubagentAction {
+	tool: string;
+	summary: string;
+	error: boolean;
+}
+export interface SubagentUsage {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+export interface SubagentDetails {
+	agent: string;
+	status: "waiting" | "running" | "completed" | "failed" | "aborted";
+	phase: "discovery" | "queue" | "startup" | "run" | "output";
+	completionState?: string;
+	task: string;
+	model: string;
+	thinkingLevel: string;
+	response?: string;
+	error?: string;
+	currentActivity?: string;
+	toolCalls: number;
+	actions: SubagentAction[];
+	omittedActions: number;
+	omittedErrors: number;
+	usage: SubagentUsage;
+	durationMs: number;
+	truncation?: {
+		truncated: boolean;
+		path?: string;
+		outputLines: number;
+		totalLines: number;
+		outputBytes: number;
+		totalBytes: number;
+	};
+}
+
+export class FifoGate {
+	private active = 0;
+	private readonly waiters: Array<{
+		signal: AbortSignal;
+		resolve: (release: () => void) => void;
+		reject: (error: Error) => void;
+	}> = [];
+	private readonly limit: number;
+	constructor(limit = 4) {
+		this.limit = limit;
+	}
+	acquire(signal: AbortSignal): Promise<() => void> {
+		if (signal.aborted) return Promise.reject(new Error("Subagent call aborted while waiting"));
+		if (this.active < this.limit) {
+			this.active += 1;
+			return Promise.resolve(this.releaseOnce());
+		}
+		return new Promise((resolve, reject) => {
+			const waiter = { signal, resolve: (_release: () => void) => {}, reject };
+			const abort = () => {
+				const index = this.waiters.indexOf(waiter);
+				if (index >= 0) this.waiters.splice(index, 1);
+				reject(new Error("Subagent call aborted while waiting"));
+			};
+			signal.addEventListener("abort", abort, { once: true });
+			waiter.resolve = (release) => {
+				signal.removeEventListener("abort", abort);
+				resolve(release);
+			};
+			this.waiters.push(waiter);
+		});
+	}
+	private releaseOnce(): () => void {
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const next = this.waiters.shift();
+			if (next) next.resolve(this.releaseOnce());
+			else this.active -= 1;
+		};
+	}
+}
+
+function capped(value: unknown, limit = VALUE_LIMIT): string {
+	let text: string;
+	try {
+		text = typeof value === "string" ? value : (JSON.stringify(value) ?? String(value));
+	} catch {
+		text = "[unavailable]";
+	}
+	return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+
+function textOf(message: AssistantMessage): string {
+	return message.content
+		.filter((part) => part.type === "text")
+		.map((part) => part.text)
+		.join("");
+}
+
+function assistants(session: AgentSession): AssistantMessage[] {
+	return session.messages.filter((message): message is AssistantMessage => message.role === "assistant");
+}
+
+export async function runSubagent(options: {
+	definition: AgentDefinition;
+	task: string;
+	ctx: ExtensionContext;
+	thinkingLevel: string;
+	signal: AbortSignal;
+	onUpdate?: (details: SubagentDetails) => void | Promise<void>;
+	onWarning?: (warning: string) => void;
+}): Promise<{ content: string; details: SubagentDetails }> {
+	const { definition, task, ctx, thinkingLevel: parentThinkingLevel, signal, onUpdate, onWarning } = options;
+	const started = Date.now();
+	let model = ctx.model;
+	let thinkingLevel = parentThinkingLevel;
+	if (definition.model) {
+		const separator = definition.model.indexOf("/");
+		const configured = ctx.modelRegistry.find(
+			definition.model.slice(0, separator),
+			definition.model.slice(separator + 1),
+		);
+		if (!configured) onWarning?.(`model ${definition.model} is unavailable; using parent model`);
+		else {
+			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configured);
+			if (!auth.ok) onWarning?.(`model ${definition.model} is unavailable: ${auth.error}; using parent model`);
+			else model = configured;
+		}
+	}
+	if (definition.thinking) {
+		const mapped = model?.thinkingLevelMap?.[definition.thinking];
+		const unsupported =
+			!model?.reasoning ||
+			mapped === null ||
+			((definition.thinking === "xhigh" || definition.thinking === "max") && mapped === undefined);
+		if (unsupported)
+			onWarning?.(`thinking ${definition.thinking} is unavailable for the selected model; using parent thinking`);
+		else thinkingLevel = definition.thinking;
+	}
+	const modelName = model ? `${model.provider}/${model.id}` : "unavailable";
+	const usage: SubagentUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+	const details: SubagentDetails = {
+		agent: definition.name,
+		status: "running",
+		phase: "startup",
+		task,
+		model: modelName,
+		thinkingLevel,
+		toolCalls: 0,
+		actions: [],
+		omittedActions: 0,
+		omittedErrors: 0,
+		usage,
+		durationMs: 0,
+	};
+	let session: AgentSession | undefined;
+	let unsubscribe: (() => void) | undefined;
+	let updateChain = Promise.resolve();
+	let lastTextUpdate = 0;
+	const publish = (force = false) => {
+		const now = Date.now();
+		if (!force && now - lastTextUpdate < 100) return;
+		lastTextUpdate = now;
+		details.durationMs = now - started;
+		const snapshot = structuredClone(details);
+		snapshot.actions = snapshot.actions.slice(-5);
+		updateChain = updateChain.then(() => onUpdate?.(snapshot)).catch(() => undefined);
+	};
+	try {
+		if (!model) throw new Error(`Agent ${definition.name} startup failed: parent has no model`);
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) throw new Error(`Agent ${definition.name} startup failed: ${auth.error}`);
+		if (signal.aborted) throw new Error(`Agent ${definition.name} startup aborted`);
+		const created = await createAgentSession({
+			cwd: ctx.cwd,
+			model,
+			thinkingLevel: thinkingLevel as "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max",
+			modelRegistry: ctx.modelRegistry,
+			tools: definition.tools,
+			excludeTools: ["subagent"],
+			sessionManager: SessionManager.inMemory(ctx.cwd),
+		});
+		session = created.session;
+		await session.bindExtensions({ mode: "print" });
+		const active = session.getActiveToolNames().sort();
+		const expected = [...definition.tools].sort();
+		if (active.join("\0") !== expected.join("\0") || active.includes("subagent")) {
+			const missing = expected.filter((tool) => !active.includes(tool));
+			throw new Error(
+				`Agent ${definition.name} startup failed: unavailable tools: ${missing.join(", ") || "active tool mismatch"}`,
+			);
+		}
+		details.phase = "run";
+		const actionById = new Map<string, string>();
+		unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+			if (event.type === "message_update" && event.message.role === "assistant") {
+				details.response = capped(textOf(event.message), PREVIEW_LIMIT);
+				publish();
+			} else if (event.type === "tool_execution_start") {
+				details.toolCalls += 1;
+				const summary = `${event.toolName} ${capped(event.args)}`.trim();
+				actionById.set(event.toolCallId, summary);
+				details.currentActivity = summary;
+				publish(true);
+			} else if (event.type === "tool_execution_end") {
+				const action = {
+					tool: event.toolName,
+					summary: actionById.get(event.toolCallId) ?? event.toolName,
+					error: event.isError,
+				};
+				details.actions.push(action);
+				if (details.actions.length > 20) {
+					const removable = details.actions.findIndex((item) => !item.error);
+					const [removed] = details.actions.splice(removable >= 0 ? removable : 0, 1);
+					details.omittedActions += 1;
+					if (removed?.error) details.omittedErrors += 1;
+				}
+				details.currentActivity = undefined;
+				publish(true);
+			}
+		});
+		const abort = () => {
+			void session?.abort();
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		try {
+			await session.prompt(
+				`You are an isolated delegated child agent. Stay within the delegated task and return only the requested result.\n\n## Agent instructions\n${definition.prompt}\n\n## Delegated task\n${task}`,
+				{ expandPromptTemplates: false },
+			);
+		} finally {
+			signal.removeEventListener("abort", abort);
+		}
+		const messages = assistants(session);
+		for (const message of messages) {
+			usage.input += message.usage.input;
+			usage.output += message.usage.output;
+			usage.cacheRead += message.usage.cacheRead;
+			usage.cacheWrite += message.usage.cacheWrite;
+			usage.cost += message.usage.cost.total;
+			usage.turns += 1;
+		}
+		const terminal = messages.at(-1);
+		if (!terminal) throw new Error(`Agent ${definition.name} run failed: no terminal assistant response`);
+		const response = textOf(terminal);
+		if (terminal.stopReason === "aborted") {
+			details.status = "aborted";
+			details.completionState = "aborted";
+			details.error = capped(terminal.errorMessage ?? "Child aborted");
+		} else if (terminal.stopReason === "error") {
+			details.status = "failed";
+			details.completionState = "error";
+			details.error = capped(terminal.errorMessage ?? "Child terminal error");
+		} else if ((terminal.stopReason === "stop" || terminal.stopReason === "length") && response.trim()) {
+			details.status = "completed";
+			details.completionState = terminal.stopReason;
+			details.phase = "output";
+			const truncation = truncateHead(response, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+			let returned = truncation.content;
+			let path: string | undefined;
+			if (truncation.truncated) {
+				const directory = await mkdtemp(join(tmpdir(), "tau-subagent-"));
+				path = join(directory, "output.md");
+				await writeFile(path, response, { encoding: "utf8", mode: 0o600 });
+				returned += `\n\n[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). Full output saved to: ${path}]`;
+			}
+			details.response = returned;
+			details.truncation = {
+				truncated: truncation.truncated,
+				path,
+				outputLines: truncation.outputLines,
+				totalLines: truncation.totalLines,
+				outputBytes: truncation.outputBytes,
+				totalBytes: truncation.totalBytes,
+			};
+		} else {
+			details.status = "failed";
+			details.completionState = terminal.stopReason;
+			details.error = `Agent ${definition.name} run failed: empty or non-terminal response`;
+		}
+		details.durationMs = Date.now() - started;
+		publish(true);
+		await updateChain;
+		return {
+			content:
+				details.status === "completed"
+					? (details.response ?? "")
+					: (details.error ?? `Agent ${definition.name} failed`),
+			details,
+		};
+	} catch (error) {
+		details.status = signal.aborted ? "aborted" : "failed";
+		details.error = capped(error instanceof Error ? error.message : "Subagent failed");
+		details.durationMs = Date.now() - started;
+		publish(true);
+		await updateChain;
+		return { content: details.error, details };
+	} finally {
+		unsubscribe?.();
+		if (session?.isStreaming) await session.abort().catch(() => undefined);
+		session?.dispose();
+	}
+}

package/extensions/tau/README.md

@@ -0,0 +1,17 @@
+# Tau
+
+Tau utility commands for configuration setup and diagnostics.
+
+## Usage
+
+```text
+/tau
+/tau init [--global|--project]
+/tau doctor
+```
+
+## Behavior
+
+- `/tau` opens a TUI picker when available.
+- `/tau init` writes a Tau settings file if one does not already exist.
+- `/tau doctor` checks Tau settings JSON and extension settings sections.

package/extensions/tau/index.ts

@@ -0,0 +1,122 @@
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+import { readJsonStatus, writeJsonObject } from "../../shared/settings/json.ts";
+import { exists, globalTauSettingsPath, projectTauSettingsPath, TAU_SCHEMA_URL } from "../../shared/settings/paths.ts";
+import { discoverTauSettingsSpecs } from "../../shared/settings/specs.ts";
+
+type Finding = { level: "global" | "project"; message: string; startup: boolean };
+
+export default function tauExtension(pi: ExtensionAPI): void {
+	pi.registerCommand("tau", {
+		description: "Tau utilities. Usage: /tau [init [--global|--project]|doctor]",
+		handler: async (args, ctx) => run(ctx, args),
+	});
+
+	pi.on("session_start", async (event, ctx) => {
+		if (event.reason !== "startup" && event.reason !== "reload") return;
+		const findings = (await inspect(ctx)).filter((finding) => finding.startup);
+		if (findings.length > 0 && ctx.hasUI) ctx.ui.notify(renderDoctor(findings), "warning");
+	});
+}
+
+async function run(ctx: ExtensionCommandContext, args: string): Promise<void> {
+	const parts = args.trim().split(/\s+/).filter(Boolean);
+	if (parts.length === 0) return runPicker(ctx);
+
+	if (parts[0] === "doctor" && parts.length === 1) {
+		const findings = await inspect(ctx);
+		ctx.ui.notify(renderDoctor(findings), findings.length > 0 ? "warning" : "info");
+		return;
+	}
+
+	if (parts[0] === "init") {
+		const scope = parts.includes("--global") ? "global" : "project";
+		await init(ctx, scope);
+		return;
+	}
+
+	ctx.ui.notify("Usage: /tau [init [--global|--project]|doctor]", "warning");
+}
+
+async function runPicker(ctx: ExtensionCommandContext): Promise<void> {
+	if (ctx.mode !== "tui") {
+		ctx.ui.notify("Usage: /tau [init [--global|--project]|doctor]", "info");
+		return;
+	}
+
+	const choice = await ctx.ui.select("Tau", ["init project config", "init global config", "doctor"]);
+	if (choice === "init project config") await init(ctx, "project");
+	else if (choice === "init global config") await init(ctx, "global");
+	else if (choice === "doctor") {
+		const findings = await inspect(ctx);
+		ctx.ui.notify(renderDoctor(findings), findings.length > 0 ? "warning" : "info");
+	}
+}
+
+async function init(ctx: ExtensionCommandContext, scope: "global" | "project"): Promise<void> {
+	const path = scope === "global" ? globalTauSettingsPath() : await projectTauSettingsPath(ctx.cwd);
+	if (await exists(path)) {
+		ctx.ui.notify(`tau init skipped: ${path} already exists`, "warning");
+		return;
+	}
+
+	await writeJsonObject(path, { $schema: TAU_SCHEMA_URL, extensions: {} });
+	ctx.ui.notify(`tau init wrote ${path}`, "info");
+}
+
+async function inspect(ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Promise<Finding[]> {
+	const findings: Finding[] = [];
+	const specs = await discoverTauSettingsSpecs(ctx.cwd);
+	const paths = [
+		{ level: "global" as const, path: globalTauSettingsPath(), trusted: true },
+		{ level: "project" as const, path: await projectTauSettingsPath(ctx.cwd), trusted: ctx.isProjectTrusted() },
+	];
+
+	for (const item of paths) {
+		const status = await readJsonStatus(item.path);
+		if (!status.exists) continue;
+		if (!item.trusted) {
+			findings.push({
+				level: item.level,
+				message: `project Tau settings ignored because project is not trusted: ${item.path}. Run /trust, then /reload.`,
+				startup: true,
+			});
+			continue;
+		}
+		if (!status.ok) {
+			findings.push({ level: item.level, message: `malformed JSON: ${item.path}: ${status.error}`, startup: true });
+			continue;
+		}
+		if (typeof status.value.$schema !== "string") {
+			findings.push({ level: item.level, message: `missing $schema: ${item.path}`, startup: false });
+		}
+		const extensions = status.value.extensions;
+		if (extensions !== undefined && (!extensions || typeof extensions !== "object" || Array.isArray(extensions))) {
+			findings.push({ level: item.level, message: `extensions must be an object: ${item.path}`, startup: true });
+			continue;
+		}
+		const extensionRecord = (extensions ?? {}) as Record<string, unknown>;
+		for (const spec of specs) {
+			const section = extensionRecord[spec.key];
+			if (section === undefined) continue;
+			if (!Value.Check(spec.schema, section)) {
+				findings.push({
+					level: item.level,
+					message: `invalid extensions.${spec.key}: ${item.path}`,
+					startup: true,
+				});
+			}
+		}
+	}
+
+	return findings;
+}
+
+function renderDoctor(findings: readonly Finding[]): string {
+	if (findings.length === 0) return "tau doctor\nNo issues found.";
+	return [
+		"tau doctor",
+		`Found ${findings.length} issue(s):`,
+		...findings.map((finding) => `- ${finding.message}`),
+	].join("\n");
+}

package/extensions/tau-help/README.md

@@ -0,0 +1,3 @@
+# Tau Help
+
+`/tau-help` displays a short Markdown guide to Tau’s extensions and prompts in the chat. The guide is visible to the user and is not sent to the agent as context.

package/extensions/tau-help/help.md

@@ -0,0 +1,125 @@
+# Tau
+
+Tau is a coding agent built to be a reliable partner during software work. It cares about quality code, explicit standards, efficient token use, and decisions that hold up after the chat ends. Extensions add focused capabilities; prompts expand into instructions for the next request.
+
+## appshot
+
+Gives the agent macOS window discovery, screenshots, and app activation tools for visual validation. Requires macOS 14 and Screen & System Audio Recording permission.
+
+## attention
+
+Shows attention state when Tau needs the user to look at the chat.
+
+## auto-name
+
+Names sessions from their first request so saved sessions remain findable.
+
+## branch
+
+Adds `/branch` to create and switch Git branches from the TUI.
+
+## clear-screen
+
+Adds `/clear-screen` to clear terminal output without changing the session.
+
+## commit
+
+Adds `/commit` for semantic commit grouping, review, and committing selected repository changes.
+
+## explore
+
+Replaces Pi’s filesystem inspection tools with compact Tau versions: `ls`, `find`, `grep`, and `read`. They produce smaller model payloads and readable tool rows. `read` includes focused line ranges; `grep`, `find`, and `ls` keep discovery output compact so the agent spends fewer tokens rereading directory and search results.
+
+## footer
+
+Adds `/footer` to toggle and refresh Tau’s status footer.
+
+## ideas
+
+Adds `/ideas` to log rough ideas or open the ideas browser.
+
+## image-gen
+
+Gives the agent an image-generation tool using the configured image service. Generated images are saved for inspection.
+
+## manage-sessions
+
+Adds `/manage-sessions` to browse saved sessions and `/sweep` to archive or delete the current session after starting a new one.
+
+## patch
+
+Replaces separate edit/write operations with one multi-file `patch` tool. It can create, rewrite, edit, move, and delete files in one structured call. Fewer tool calls means fewer turns, and each avoided turn prevents the full chat context from being sent again.
+
+## publish
+
+Adds `/publish` to create a tagged release, trigger trusted npm publishing in GitHub Actions, and show its status. It recommends a semantic version bump from commits since the prior release tag, but you must confirm the release type and publish action.
+
+## qna
+
+Adds `/qna` for when the agent has asked you several questions in chat and you want a friendly UI for answering them on your own terms. It is only active when you manually run the command.
+
+## reference
+
+Adds `/reference` to manage separate repositories kept outside the current project for inspiration or comparison. Add one with `/reference new <git-url>`, update it, switch its referenced branch, or open it in an editor. Select references and explain why they matter; Tau then puts their paths and that reason into the editor for the agent. References stay outside the project so the agent does not wander into unrelated code unless you explicitly point it there.
+
+## run-summary
+
+Shows a compact display-only marker after each run with wall time and model cost. It does not enter agent context.
+
+## silent-command-runner
+
+Runs configured commands while keeping their output out of agent context when that is useful.
+
+## soul
+
+Manages the session’s soul prompt and its persistent working guidance.
+
+## stash
+
+Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed drafts and put one back in the editor.
+
+## subagent
+
+Gives Tau a subagent delegation tool for isolated, focused work. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in `scout` and `web-research` subagents show the pattern. Each subagent can register its own model and the tools it is allowed to use.
+
+## tau-help
+
+Adds `/tau-help` to show this guide as rendered Markdown in the chat.
+
+## tau
+
+Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup and diagnostics.
+
+## turn-budget
+
+Tracks and limits agent turns to keep work bounded.
+
+## web
+
+Gives the agent compact `web_search`, `web_fetch`, and `code_search` tools for web and implementation research.
+
+## Prompts
+
+Prompt commands expand into instructions before the request reaches the agent.
+
+### cavemanify
+
+`/cavemanify` makes prose short, blunt, and direct.
+
+### implement
+
+`/implement` provides the implementation workflow for an approved change.
+
+### interview
+
+`/interview` drives practical questions when a request is underspecified.
+
+### plan-feature
+
+`/plan-feature` explores a feature and produces a scoped plan before editing.
+
+### plan-implementation
+
+`/plan-implementation` turns an approved plan into concrete implementation steps.
+
+Keep this file updated when an extension or prompt is added, removed, renamed, or its basic usage changes.

package/extensions/tau-help/index.ts

@@ -0,0 +1,68 @@
+import { getMarkdownTheme, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { Markdown, type Component, visibleWidth } from "@earendil-works/pi-tui";
+
+const TAU_SYMBOL = [
+	"            %%%%%%%%#######*******+++++",
+	"        @@%%%%%%%########*******+++++++",
+	"      @@%%%%%%%########*******+++++++=",
+	"     @%%%%%%%#######********+++++++==",
+	"    %%%%%%%#######********+++++++===",
+	"   %%           *******+",
+	"               ******+++",
+	"              *****++++",
+	"              ***+++++",
+	"             *+++++++",
+	"            ++++++++=",
+	"           ++++++===",
+	"           ++++=====",
+	"          +++=======       -:",
+	"          +=======--------::",
+	"          ======-------::::",
+	"            ==-------::::",
+	"               ----:::",
+].join("\n");
+
+class TauHelpMessage implements Component {
+	private readonly markdown: Markdown;
+
+	constructor(content: string, theme: ReturnType<typeof getMarkdownTheme>) {
+		this.markdown = new Markdown(content, 0, 0, theme);
+	}
+
+	render(width: number): string[] {
+		const symbolLines = TAU_SYMBOL.split("\n");
+		const symbolWidth = Math.max(...symbolLines.map((line) => visibleWidth(line)));
+		const padding = Math.max(0, Math.floor((width - symbolWidth) / 2));
+		const symbol = symbolLines.map((line) => " ".repeat(padding) + line);
+		return [...symbol, "", ...this.markdown.render(width)];
+	}
+
+	invalidate(): void {
+		this.markdown.invalidate();
+	}
+}
+
+export default function tauHelpExtension(pi: ExtensionAPI): void {
+	pi.registerMessageRenderer("tau-help", (message, _options, _theme) => {
+		if (typeof message.content !== "string") return undefined;
+		return new TauHelpMessage(message.content, getMarkdownTheme());
+	});
+
+	pi.registerCommand("tau-help", {
+		description: "Show the Tau extension and prompt guide",
+		handler: async (_args, _ctx) => {
+			const content = await readFile(join(dirname(fileURLToPath(import.meta.url)), "help.md"), "utf8");
+			await pi.sendMessage(
+				{
+					customType: "tau-help",
+					content,
+					display: true,
+				},
+				{ triggerTurn: false },
+			);
+		},
+	});
+}

package/extensions/turn-budget/README.md

@@ -0,0 +1,14 @@
+# Turn Budget
+
+Adds soft turn budget hints for Tau sessions.
+
+Turn Budget helps agents spend fewer provider cycles by nudging them to batch related tool work. It counts
+tool-using turns per user prompt, sends visible steering messages at configured intervals, and extends the soft cap
+instead of blocking work.
+
+## Settings
+
+- `enabled`: defaults to `true`
+- `turnLimit`: defaults to `30`
+- `nudgeEveryTurns`: defaults to `5`
+- `softCapIncrement`: defaults to `10`