@shanepadgett/tau-agent 0.7.2 → 0.9.1

package/extensions/tau-help/help.md

@@ -28,7 +28,7 @@ Adds `/commit` for semantic commit grouping, review, and committing selected rep
 
 ## context
 
-Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` to reconcile affected scopes from current Git changes. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+Adds `/context` to select reusable repository work scopes from `.pi/contexts`, and `/context-sync` to reconcile affected scopes from current Git changes. Tau automatically validates changed-file membership and stale references after agent turns. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
 ## explore
 
@@ -74,13 +74,17 @@ Adds `/reference` to manage separate repositories kept outside the current proje
 
 Shows a compact display-only marker after each run with wall time and model cost. It does not enter agent context.
 
+## runtime-context
+
+Supplies the agent with the current local date and an initial root directory snapshot as hidden session 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.
+Adds Rok’s persona and operating rules to Pi’s native assistant prompt.
 
 ## stash
 
@@ -98,13 +102,17 @@ Adds `/tau-help` to show this guide as rendered Markdown in the chat.
 
 Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup and diagnostics.
 
+## tool-loader
+
+Progressively exposes specialist tools through `load_tools`. Tau normally loads the fixed `web`, `image`, and `appshot` groups itself when needed; supported providers can preserve more prompt-cache reuse.
+
 ## 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.
+Gives the agent compact `websearch`, `webfetch`, and `codesearch` tools for web and implementation research.
 
 ## Prompts
 

package/extensions/tau-help/index.ts

@@ -4,6 +4,14 @@ import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { Markdown, type Component, visibleWidth } from "@earendil-works/pi-tui";
 
+const TAU_DOCS_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "docs");
+const TAU_DOCS_GUIDANCE = `Tau Agent documentation (read only when the user asks about Tau Agent, Rok, Tau extensions, Tau event APIs, harness behavior, or extending Tau Agent):
+- Tau Agent docs: ${TAU_DOCS_PATH}
+- When asked about: public events / external integration (docs/extending-tau-agent.md), custom subagents (docs/subagents.md), Tau TUI components (docs/tui.md)
+- Resolve Tau docs/... under Tau Agent docs, not the current working directory
+- When working on Tau topics, read the docs and follow .md cross-references before implementing
+- Do not read Tau Agent docs for normal coding tasks`;
+
 const TAU_SYMBOL = [
 	"            %%%%%%%%#######*******+++++",
 	"        @@%%%%%%%########*******+++++++",
@@ -46,6 +54,10 @@ class TauHelpMessage implements Component {
 }
 
 export default function tauHelpExtension(pi: ExtensionAPI): void {
+	pi.on("before_agent_start", (event) => ({
+		systemPrompt: `${event.systemPrompt}\n\n${TAU_DOCS_GUIDANCE}`,
+	}));
+
 	pi.registerMessageRenderer("tau-help", (message, _options, _theme) => {
 		if (typeof message.content !== "string") return undefined;
 		return new TauHelpMessage(message.content, getMarkdownTheme());

package/extensions/tool-loader/README.md

@@ -0,0 +1,13 @@
+# Tool Loader
+
+Tau progressively exposes specialist tools. Most coding turns do not need web, image, or macOS application schemas, so Pi can load those tools later without discarding supported provider cache prefixes.
+
+The agent normally calls `load_tools` itself. Users can also ask Tau to load one of these groups:
+
+- `web` for public web and implementation research
+- `image` for raster image generation and editing
+- `appshot` for macOS window discovery, capture, and activation
+
+Supported models optimize prompt caching when a group loads. Other models keep the same functional behavior.
+
+After changing this extension during development, run `/reload` before testing.

package/extensions/tool-loader/index.ts

@@ -0,0 +1,134 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+
+const CAPABILITIES = ["web", "image", "appshot"] as const;
+type Capability = (typeof CAPABILITIES)[number];
+
+const CAPABILITY_TOOLS: Record<Capability, readonly string[]> = {
+	web: ["webfetch", "websearch", "codesearch"],
+	image: ["image_gen"],
+	appshot: ["list_windows", "screenshot_window", "activate_app"],
+};
+const SPECIALIST_TOOLS = CAPABILITIES.flatMap((capability) => CAPABILITY_TOOLS[capability]);
+
+const loadToolsSchema = Type.Object(
+	{
+		capability: StringEnum(CAPABILITIES, {
+			description: "Specialist group to load: web, image, or appshot",
+		}),
+	},
+	{ additionalProperties: false },
+);
+
+type LoadToolsParams = Static<typeof loadToolsSchema>;
+
+interface LoadToolsDetails {
+	version: 1;
+	capability: Capability;
+	requestedToolNames: string[];
+	addedToolNames: string[];
+}
+
+export default function toolLoaderExtension(pi: ExtensionAPI): void {
+	let managed = false;
+	let allowedSpecialistNames = new Set<string>();
+
+	pi.registerTool(
+		defineTool<typeof loadToolsSchema, LoadToolsDetails>({
+			name: "load_tools",
+			label: "Load Tools",
+			description:
+				"Load one Tau specialist tool group for the current session. Groups: web for public web and implementation research; image for raster generation and editing; appshot for macOS window discovery, capture, and activation.",
+			promptSnippet: "Load a specialist Tau tool group for web research, image generation, or macOS app inspection",
+			promptGuidelines: [
+				"Use load_tools before attempting a specialist capability whose tools are not currently available.",
+			],
+			parameters: loadToolsSchema,
+			async execute(_toolCallId, params: LoadToolsParams) {
+				const before = pi.getActiveTools();
+				const requested = [...CAPABILITY_TOOLS[params.capability]];
+				const registered = new Set(pi.getAllTools().map((tool) => tool.name));
+				const loadable = requested.filter((name) => registered.has(name) && allowedSpecialistNames.has(name));
+				if (loadable.length === 0) {
+					throw new Error(`No ${params.capability} tools are available in this session's tool configuration.`);
+				}
+				const beforeSet = new Set(before);
+				const next = [...before, ...loadable.filter((name) => !beforeSet.has(name))];
+				pi.setActiveTools(next);
+				const after = pi.getActiveTools();
+				const addedToolNames = after.filter((name) => !beforeSet.has(name));
+				const available = requested.filter((name) => after.includes(name));
+				const unavailable = requested.filter((name) => !after.includes(name));
+				const label = `${params.capability[0]?.toUpperCase()}${params.capability.slice(1)}`;
+				const text =
+					addedToolNames.length > 0
+						? `Loaded ${params.capability} tools: ${addedToolNames.join(", ")}.`
+						: `${label} tools are already loaded: ${available.join(", ")}.`;
+				return {
+					content: [
+						{
+							type: "text",
+							text: unavailable.length ? `${text} Unavailable: ${unavailable.join(", ")}.` : text,
+						},
+					],
+					details: {
+						version: 1,
+						capability: params.capability,
+						requestedToolNames: requested,
+						addedToolNames,
+					},
+				};
+			},
+		}),
+	);
+
+	pi.on("session_start", (_event, ctx) => {
+		const initial = pi.getActiveTools();
+		const initialSet = new Set(initial);
+		allowedSpecialistNames = new Set(SPECIALIST_TOOLS.filter((name) => initialSet.has(name)));
+		managed = initialSet.has("load_tools") && SPECIALIST_TOOLS.every((name) => initialSet.has(name));
+		if (managed) restoreActiveTools(pi, initial, loadedCapabilities(ctx.sessionManager.getBranch()));
+	});
+
+	pi.on("session_tree", (_event, ctx) => {
+		if (managed) restoreActiveTools(pi, pi.getActiveTools(), loadedCapabilities(ctx.sessionManager.getBranch()));
+	});
+}
+
+function restoreActiveTools(pi: ExtensionAPI, current: readonly string[], loaded: ReadonlySet<Capability>): void {
+	const specialist = new Set(SPECIALIST_TOOLS);
+	const next = current.filter((name) => !specialist.has(name));
+	for (const capability of CAPABILITIES) {
+		if (loaded.has(capability)) next.push(...CAPABILITY_TOOLS[capability]);
+	}
+	pi.setActiveTools([...new Set(next)]);
+}
+
+function loadedCapabilities(entries: readonly unknown[]): Set<Capability> {
+	const loaded = new Set<Capability>();
+	for (const value of entries) {
+		if (!value || typeof value !== "object") continue;
+		const entry = value as Record<string, unknown>;
+		if (entry.type !== "message" || !entry.message || typeof entry.message !== "object") continue;
+		const message = entry.message as Record<string, unknown>;
+		if (message.role !== "toolResult" || message.toolName !== "load_tools" || message.isError === true) continue;
+		if (!isLoadToolsDetails(message.details)) continue;
+		loaded.add(message.details.capability);
+	}
+	return loaded;
+}
+
+function isLoadToolsDetails(value: unknown): value is LoadToolsDetails {
+	if (!value || typeof value !== "object") return false;
+	const details = value as Record<string, unknown>;
+	return (
+		details.version === 1 &&
+		typeof details.capability === "string" &&
+		CAPABILITIES.includes(details.capability as Capability) &&
+		Array.isArray(details.requestedToolNames) &&
+		details.requestedToolNames.every((name) => typeof name === "string") &&
+		Array.isArray(details.addedToolNames) &&
+		details.addedToolNames.every((name) => typeof name === "string")
+	);
+}

package/extensions/turn-budget/index.ts

@@ -41,13 +41,6 @@ export default function turnBudgetExtension(pi: ExtensionAPI): void {
 		});
 	});
 
-	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));
 	});
@@ -96,7 +89,6 @@ export default function turnBudgetExtension(pi: ExtensionAPI): void {
 	pi.on("after_provider_response", () => {
 		activeMarkerSequence = undefined;
 	});
-
 	function markerIsActive(value: unknown): boolean {
 		if (activeMarkerSequence === undefined) return false;
 		const details = readMarkerDetails(value);
@@ -114,10 +106,12 @@ function sendTurnBudgetMessage(pi: ExtensionAPI, hint: Hint, sequence: number):
 }
 
 function formatSteeringMessage(hint: Hint): string {
+	const instruction =
+		"Internal steering instruction. Work within it silently. Do not mention or acknowledge turn counts, budget messages, or budget summaries.";
 	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 `${instruction} 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.`;
+	return `${instruction} 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 {

package/extensions/web/codesearch.ts

@@ -27,13 +27,7 @@ export function createCodeSearchTool(rowState: ToolRowStateStore) {
 		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.",
-		],
+			"Search Exa for API usage, code examples, and implementation-oriented documentation context. Use websearch for broad discovery and webfetch for a known URL. Use a separate research workflow when several searches, fetches, and synthesis are needed. Output is truncated to 2,000 lines or 50 KB.",
 		parameters: codeSearchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			const timeout = normalizeTimeout(params.timeout, 25);

package/extensions/web/webfetch.ts

@@ -66,13 +66,7 @@ export function createWebFetchTool(rowState: ToolRowStateStore) {
 		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.",
-		],
+			"Fetch a known HTTP(S) URL as Markdown, text, or HTML. Use webfetch when you already have a URL; use websearch for broad discovery and codesearch for implementation-oriented lookups. Use a separate research workflow when several searches, fetches, and synthesis are needed. Supports inline images, limits response bodies to 5 MB, and truncates text to 2,000 lines or 50 KB.",
 		parameters: webFetchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			let url: URL;

package/extensions/web/websearch.ts

@@ -36,13 +36,7 @@ export function createWebSearchTool(rowState: ToolRowStateStore) {
 		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.",
-		],
+			"Search the public web through Exa for current information and relevant pages. Use websearch for broad discovery, then webfetch for a known URL; use codesearch for implementation-oriented code and documentation context. Use a separate research workflow when several searches, fetches, and synthesis are needed. Output is truncated to 2,000 lines or 50 KB.",
 		parameters: webSearchParams,
 		async execute(_toolCallId, params, signal, onUpdate) {
 			const timeout = normalizeTimeout(params.timeout, 25);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.7.2",
+	"version": "0.9.1",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"license": "MIT",
@@ -28,7 +28,7 @@
 		"README.md"
 	],
 	"dependencies": {
-		"@shanepadgett/tau-tui": "0.7.2",
+		"@shanepadgett/tau-tui": "0.9.1",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},

package/schemas/tau.schema.json

@@ -12,6 +12,31 @@
 		"extensions": {
 			"type": "object",
 			"properties": {
+				"context": {
+					"type": "object",
+					"properties": {
+						"validation": {
+							"type": "object",
+							"properties": {
+								"enabled": {
+									"type": "boolean",
+									"default": true,
+									"description": "Validate context membership after agent turns."
+								},
+								"ignoreGlobs": {
+									"type": "array",
+									"items": {
+										"type": "string"
+									},
+									"default": [],
+									"description": "Project-relative files excluded from context membership validation and sync."
+								}
+							},
+							"additionalProperties": false
+						}
+					},
+					"additionalProperties": false
+				},
 				"footer": {
 					"type": "object",
 					"properties": {

package/shared/glob.ts

@@ -0,0 +1,34 @@
+import { sep } from "node:path";
+
+export function matchGlob(pattern: string, path: string): boolean {
+	return matchSegments(normalizeGlob(pattern).split("/"), normalizeGlob(path).split("/"));
+}
+
+function matchSegments(pattern: readonly string[], path: readonly string[]): boolean {
+	const [head, ...tail] = pattern;
+	if (head === undefined) return path.length === 0;
+	if (head === "**") return matchSegments(tail, path) || (path.length > 0 && matchSegments(pattern, path.slice(1)));
+	const [pathHead, ...pathTail] = path;
+	return pathHead !== undefined && matchSegment(head, pathHead) && matchSegments(tail, pathTail);
+}
+
+function matchSegment(pattern: string, value: string): boolean {
+	const source = [...pattern]
+		.map((char) => {
+			if (char === "*") return "[^/]*";
+			if (char === "?") return "[^/]";
+			return char.replace(/[\\^$.*+?()[\]{}|]/g, "\\$&");
+		})
+		.join("");
+	return new RegExp(`^${source}$`).test(value);
+}
+
+function normalizeGlob(value: string): string {
+	return posixPath(value.trim())
+		.replace(/^\.\//, "")
+		.replace(/^\/+|\/+$/g, "");
+}
+
+export function posixPath(value: string): string {
+	return sep === "/" ? value : value.split(sep).join("/");
+}

package/shared/model-fallback/index.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import type { Api, AssistantMessage, Message, Model, ThinkingLevel, Tool } from "@earendil-works/pi-ai";
 import { completeSimple } from "@earendil-works/pi-ai/compat";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -13,7 +14,6 @@ const SEVEN_DAYS_MS = 604_800_000;
 interface GenerationContext {
 	ui: ExtensionContext["ui"];
 	signal: AbortSignal | undefined;
-	sessionManager?: { getSessionId(): string };
 }
 
 interface ModelFallbackOptions {
@@ -131,9 +131,10 @@ async function requestValidated<T>(
 ): Promise<T> {
 	const userMessage: Message = { role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() };
 	const messages: Message[] = [userMessage];
+	const sessionId = randomUUID();
 
 	for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-		const response = await completeCandidate(ctx, candidate, messages);
+		const response = await completeCandidate(ctx, candidate, messages, sessionId);
 		const text = responseText(response);
 		if (response.stopReason === "error") {
 			const error = new Error(response.errorMessage || "model returned an error");
@@ -169,9 +170,10 @@ async function requestToolValidated<T>(
 	maxAttempts = MAX_TOOL_ATTEMPTS,
 ): Promise<T> {
 	const messages: Message[] = [{ role: "user", content: [{ type: "text", text: prompt }], timestamp: Date.now() }];
+	const sessionId = randomUUID();
 
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-		const response = await completeCandidate(ctx, candidate, messages, [tool]);
+		const response = await completeCandidate(ctx, candidate, messages, sessionId, [tool]);
 		const text = responseText(response);
 		const toolCalls = response.content.flatMap((part) => (part.type === "toolCall" ? [part] : []));
 		const output = text || formatToolCalls(toolCalls);
@@ -206,6 +208,7 @@ function completeCandidate(
 	ctx: GenerationContext,
 	candidate: ModelCandidate,
 	messages: readonly Message[],
+	sessionId: string,
 	tools?: Tool[],
 ): Promise<AssistantMessage> {
 	return completeSimple(candidate.model, tools ? { messages: [...messages], tools } : { messages: [...messages] }, {
@@ -213,7 +216,7 @@ function completeCandidate(
 		headers: candidate.headers,
 		signal: ctx.signal,
 		reasoning: candidate.reasoning,
-		sessionId: ctx.sessionManager?.getSessionId(),
+		sessionId,
 	});
 }