@shanepadgett/tau-agent 0.13.0 → 0.14.0

package/extensions/context/README.md

@@ -2,7 +2,7 @@
 
 Context stores reusable repository work scopes in `.pi/contexts`. Folder names become selector tabs, TOML files become concepts, and TOML sections become selectable entries.
 
-Use `/context` to select entries and inject their files through Tau autoread. Use `/context-sync` to reconcile affected scopes from the current Git changes. Tau validates context membership after agent turns and asks the agent to sync uncovered changed files or stale references automatically.
+Use `/context` to select entries. Entry `files` are injected through Tau autoread. Entry `anchors` supply lazy navigation paths that the agent can grep or read in ranges when needed. Use `/context-sync` to reconcile affected scopes from the current Git changes. Tau validates both file classes as context membership after agent turns and asks the agent to sync uncovered changed files or stale references automatically.
 
 Validation is disabled by default. Enable it globally or per project in Tau settings:
 
@@ -30,6 +30,7 @@ files = ["src/player/input.ts"]
 [movement]
 description = "Player locomotion and collision"
 files = ["src/player/movement.ts"]
+anchors = ["src/runtime/fetch-handler.ts"]
 ```
 
-For example, `.pi/contexts/gameplay/player.toml` appears in the `gameplay` tab as the `Player` concept with `input` and `movement` entries.
+For example, `.pi/contexts/gameplay/player.toml` appears in the `gameplay` tab as the `Player` concept with `input` and `movement` entries. When `movement` is selected, Tau autoreads `src/player/movement.ts` and lists `src/runtime/fetch-handler.ts` as an unloaded anchor. If one selected entry marks a path as a file and another marks it as an anchor, autoread wins.

package/extensions/context/definitions.ts

@@ -13,6 +13,7 @@ export interface ContextEntry {
 	name: string;
 	description: string;
 	files: string[];
+	anchors: string[];
 	path: string;
 }
 
@@ -36,6 +37,7 @@ const CONTEXT_IGNORED_FILENAMES = new Set([
 	"uv.lock",
 	"yarn.lock",
 ]);
+const CONTEXT_ENTRY_FIELDS = new Set(["description", "files", "anchors"]);
 
 export function isContextEligiblePath(path: string, ignoreGlobs: readonly string[] = []): boolean {
 	return (
@@ -97,6 +99,10 @@ function sortedUnique(values: readonly string[]): string[] {
 	return [...new Set(values)].sort((a, b) => a.localeCompare(b));
 }
 
+export function contextEntryPaths(entry: Pick<ContextEntry, "files" | "anchors">): string[] {
+	return sortedUnique([...entry.files, ...entry.anchors]);
+}
+
 export async function requireFiles(root: string, inputs: readonly string[]): Promise<string[]> {
 	const files = sortedUnique(inputs.map((input) => normalizeProjectPath(root, input)));
 	for (const file of files) {
@@ -132,15 +138,24 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 				if (!value || typeof value !== "object" || Array.isArray(value))
 					throw new Error(`Invalid context entry: ${path} [${name}]`);
 				const record = value as Record<string, unknown>;
+				const unknownField = Object.keys(record).find((field) => !CONTEXT_ENTRY_FIELDS.has(field));
+				if (unknownField) throw new Error(`Invalid context entry field: ${path} [${name}] ${unknownField}`);
+				const anchors = record.anchors ?? [];
 				if (
 					typeof record.description !== "string" ||
 					!record.description.trim() ||
 					!Array.isArray(record.files) ||
-					record.files.length === 0 ||
-					record.files.some((item) => typeof item !== "string")
+					record.files.some((item) => typeof item !== "string") ||
+					!Array.isArray(anchors) ||
+					anchors.some((item) => typeof item !== "string") ||
+					(record.files.length === 0 && anchors.length === 0)
 				)
 					throw new Error(`Invalid context entry: ${path} [${name}]`);
 				const entry = validSlug(name, "Context entry");
+				const entryFiles = sortedUnique((record.files as string[]).map((item) => normalizeProjectPath(root, item)));
+				const entryAnchors = sortedUnique((anchors as string[]).map((item) => normalizeProjectPath(root, item)));
+				const overlap = entryFiles.find((item) => entryAnchors.includes(item));
+				if (overlap) throw new Error(`Context path cannot be both file and anchor: ${path} [${name}] ${overlap}`);
 				result.push({
 					id: `${tab}/${concept}/${entry}`,
 					tab,
@@ -149,7 +164,8 @@ export async function loadContextEntries(root: string): Promise<ContextEntry[]>
 					conceptDescription,
 					name: entry,
 					description: record.description.trim(),
-					files: sortedUnique((record.files as string[]).map((item) => normalizeProjectPath(root, item))),
+					files: entryFiles,
+					anchors: entryAnchors,
 					path,
 				});
 			}

package/extensions/context/index.ts

@@ -53,19 +53,35 @@ export default function contextExtension(pi: ExtensionAPI): void {
 			);
 			if (!selected?.length) return;
 			const files = [...new Set(selected.flatMap((entry) => entry.files))].sort();
+			const fileSet = new Set(files);
+			const anchors = [...new Set(selected.flatMap((entry) => entry.anchors))]
+				.filter((path) => !fileSet.has(path))
+				.sort();
 			pi.sendMessage(
 				createInjectedContext(
-					"Treat the autoread files as the authoritative project context and current snapshots. Do not reread them or search for coverage around them. Start work from them immediately. Explore outside them only when the user's request or concrete evidence in those files requires missing code or information.",
+					[
+						"Selected repository context:",
+						...selected.map((entry) => `- ${entry.id}: ${entry.description}`),
+						"",
+						"Eager snapshots supplied through autoread:",
+						...(files.length ? files.map((path) => `- ${path}`) : ["(none)"]),
+						"",
+						"Lazy navigation anchors whose contents have not been loaded:",
+						...(anchors.length ? anchors.map((path) => `- ${path}`) : ["(none)"]),
+						"",
+						"Treat eager snapshots as authoritative current project context. Do not reread them or search for coverage around them. Inspect only the anchors needed for the request, using grep or bounded reads. Explore elsewhere only when the request or concrete evidence requires missing information.",
+					].join("\n"),
 					{ source: "context", title: "Project context" },
 				),
 			);
-			emitTauEvent(pi, "tau:autoread.requested", {
-				source: "context",
-				title: "Project context",
-				cwd: root,
-				batchId: randomUUID(),
-				files: files.map((path) => ({ path })),
-			});
+			if (files.length)
+				emitTauEvent(pi, "tau:autoread.requested", {
+					source: "context",
+					title: "Project context",
+					cwd: root,
+					batchId: randomUUID(),
+					files: files.map((path) => ({ path })),
+				});
 		},
 	});
 

package/extensions/context/panel.ts

@@ -73,14 +73,15 @@ export class ContextPanel implements Component {
 		const list = this.activeList();
 		if (!list?.isFilterFocused()) {
 			const keys = getKeybindings();
-			const pageSize = this.filePageSize();
-			if (this.current.files.length > pageSize && matchesKey(data, Key.alt("up"))) {
+			const paths = this.currentPaths();
+			const pageSize = this.pathPageSize();
+			if (paths.length > pageSize && matchesKey(data, Key.alt("up"))) {
 				this.fileOffset = Math.max(0, this.fileOffset - pageSize);
 				this.sync();
 				return;
 			}
-			if (this.current.files.length > pageSize && matchesKey(data, Key.alt("down"))) {
-				this.fileOffset = Math.min(this.current.files.length - pageSize, this.fileOffset + pageSize);
+			if (paths.length > pageSize && matchesKey(data, Key.alt("down"))) {
+				this.fileOffset = Math.min(paths.length - pageSize, this.fileOffset + pageSize);
 				this.sync();
 				return;
 			}
@@ -122,35 +123,51 @@ export class ContextPanel implements Component {
 		return {
 			render: (width) => {
 				const tabs = this.tabs.render(width);
-				const pageSize = this.filePageSize(tabs.length);
-				const maxOffset = Math.max(0, this.current.files.length - pageSize);
+				const paths = this.currentPaths();
+				const pageSize = this.pathPageSize(tabs.length);
+				const maxOffset = Math.max(0, paths.length - pageSize);
 				this.fileOffset = Math.min(this.fileOffset, maxOffset);
-				const files = this.current.files.slice(this.fileOffset, this.fileOffset + pageSize);
+				const visible = paths.slice(this.fileOffset, this.fileOffset + pageSize);
 				const range =
-					this.current.files.length > pageSize
+					paths.length > pageSize
 						? this.theme.fg(
 								"dim",
-								`${this.fileOffset + 1}-${this.fileOffset + files.length} of ${this.current.files.length} files`,
+								`${this.fileOffset + 1}-${this.fileOffset + visible.length} of ${paths.length} paths`,
 							)
 						: undefined;
 				return [
 					...tabs,
 					"",
 					...(range ? [truncateToWidth(range, width, "…")] : []),
-					...files.map((file) => truncateToWidth(this.theme.fg("muted", `• ${file}`), width, "…")),
+					...visible.map(({ kind, path }) =>
+						truncateToWidth(
+							this.theme.fg(
+								kind === "read" ? "muted" : "dim",
+								`${kind === "read" ? "read" : "anchor"} • ${path}`,
+							),
+							width,
+							"…",
+						),
+					),
 				];
 			},
 			invalidate: () => this.tabs.invalidate(),
 		};
 	}
-	private filePageSize(tabLines = this.tabs.render(this.tui.terminal.columns).length): number {
+	private currentPaths(): Array<{ kind: "read" | "anchor"; path: string }> {
+		return [
+			...this.current.files.map((path) => ({ kind: "read" as const, path })),
+			...this.current.anchors.map((path) => ({ kind: "anchor" as const, path })),
+		];
+	}
+	private pathPageSize(tabLines = this.tabs.render(this.tui.terminal.columns).length): number {
 		const overlayHeight = Math.floor(this.tui.terminal.rows * 0.8);
 		const available = Math.max(1, overlayHeight - tabLines - 7);
 		const pageSize = Math.min(8, available);
-		return this.current.files.length > pageSize ? Math.max(1, pageSize - 1) : pageSize;
+		return this.currentPaths().length > pageSize ? Math.max(1, pageSize - 1) : pageSize;
 	}
 	private secondary(): string {
-		return `${[...this.selected.values()].reduce((sum, items) => sum + items.length, 0)} selected`;
+		return `${[...this.selected.values()].reduce((sum, items) => sum + items.length, 0)} selected · ${this.current.files.length} read · ${this.current.anchors.length} anchors`;
 	}
 	private hints() {
 		const list = this.activeList();
@@ -158,7 +175,7 @@ export class ContextPanel implements Component {
 			? list.getKeyHints()
 			: [
 					...this.tabs.getKeyHints(),
-					...(this.current.files.length > this.filePageSize() ? [rawHint("option+↑/↓", "scroll files")] : []),
+					...(this.currentPaths().length > this.pathPageSize() ? [rawHint("option+↑/↓", "scroll paths")] : []),
 					rawHint("ctrl+c", "clear all"),
 					bindingHint("tui.select.confirm", "inject"),
 					bindingHint("tui.select.cancel", "cancel"),

package/extensions/context/sync.ts

@@ -10,6 +10,7 @@ import { loadTauExtensionSettings } from "../../shared/settings/load.ts";
 import { truncAt } from "../../shared/text.ts";
 import { XAI_CHAT_MODEL, XAI_PROVIDER } from "../xai/constants.ts";
 import {
+	contextEntryPaths,
 	isContextEligiblePath,
 	isSensitiveContextPath,
 	loadContextEntries,
@@ -216,13 +217,14 @@ async function collectSyncEvidence(
 	for (const path of dependencies) if (!isContextEligiblePath(path, ignoreGlobs)) dependencies.delete(path);
 	const missingPaths = new Set<string>();
 	for (const entry of entries)
-		for (const path of entry.files)
+		for (const path of contextEntryPaths(entry))
 			if (isContextEligiblePath(path, ignoreGlobs) && !(await isFile(join(root, path)))) missingPaths.add(path);
 	const affectedIds = new Set<string>();
 	for (const entry of entries) {
+		const paths = contextEntryPaths(entry);
 		if (
-			entry.files.some((path) => missingPaths.has(path)) ||
-			entry.files.some(
+			paths.some((path) => missingPaths.has(path)) ||
+			paths.some(
 				(path) => files.some((file) => file.path === path || file.oldPath === path) || dependencies.has(path),
 			)
 		)
@@ -231,7 +233,7 @@ async function collectSyncEvidence(
 	const affectedConcepts = new Set([...affectedIds].map((id) => id.split("/").slice(0, 2).join("/")));
 	const siblingEntries = entries.filter((entry) => affectedConcepts.has(`${entry.tab}/${entry.concept}`));
 	const siblingFiles = siblingEntries
-		.flatMap((entry) => entry.files)
+		.flatMap((entry) => contextEntryPaths(entry))
 		.filter((path) => !missingPaths.has(path) && isContextEligiblePath(path, ignoreGlobs));
 	const eligibleFiles = new Set([...dirtyExisting, ...dependencies, ...siblingFiles]);
 	const structuralPreviews = new Map<string, string>();
@@ -327,9 +329,13 @@ async function collectDirtyFiles(
 				sorted.slice(offset, offset + EVIDENCE_CONCURRENCY).map(async (file, inner) => ({
 					...file,
 					id: offset + inner + 1,
-					memberships: entries.filter((entry) => entry.files.includes(file.path)).map((entry) => entry.id),
+					memberships: entries
+						.filter((entry) => contextEntryPaths(entry).includes(file.path))
+						.map((entry) => entry.id),
 					oldMemberships: file.oldPath
-						? entries.filter((entry) => entry.files.includes(file.oldPath ?? "")).map((entry) => entry.id)
+						? entries
+								.filter((entry) => contextEntryPaths(entry).includes(file.oldPath ?? ""))
+								.map((entry) => entry.id)
 						: [],
 					evidence: await dirtyEvidence(git, root, file),
 				})),
@@ -431,7 +437,9 @@ async function isFile(path: string): Promise<boolean> {
 
 function buildContextSyncPrompt(evidence: SyncEvidence): string {
 	const stale = evidence.entries.flatMap((entry) =>
-		entry.files.filter((path) => evidence.missingPaths.has(path)).map((path) => `${entry.id}: ${path}`),
+		contextEntryPaths(entry)
+			.filter((path) => evidence.missingPaths.has(path))
+			.map((path) => `${entry.id}: ${path}`),
 	);
 	const affected = evidence.entries.filter((entry) => evidence.affectedIds.has(entry.id));
 	const previews = [...evidence.structuralPreviews].map(([path, preview]) => `${path}\n${preview}`);
@@ -441,6 +449,7 @@ function buildContextSyncPrompt(evidence: SyncEvidence): string {
 			"Call submit_context_sync exactly once and produce no prose response.",
 			"Return no-change only when every eligible changed file has context membership and no stale catalog paths remain.",
 			"Context entries are reusable work scopes, not inventories of every touched file. Prefer updating an existing entry over creating a near-duplicate. Do not create one entry per file.",
+			"The files field in your changes is desired membership, including eager files and lazy anchors. Paths already classified anywhere in the catalog preserve their loading class; new paths become eager files. Do not change loading policy.",
 			"Follow direct local dependency candidates only when needed. Do not add package dependencies, generated files, incidental imports, or recursive dependencies.",
 			"Reconsider granularity only inside affected concepts. Preserve broad entries when splitting would duplicate files without improving future work.",
 			"Every eligible changed file must belong to at least one entry. Remove every stale catalog path. Use only supplied candidate paths.",
@@ -457,8 +466,9 @@ function buildContextSyncPrompt(evidence: SyncEvidence): string {
 					conceptName: entry.conceptName,
 					conceptDescription: entry.conceptDescription,
 					description: entry.description,
-					files: entry.files,
-					missingFiles: entry.files.filter((path) => evidence.missingPaths.has(path)),
+					eagerFiles: entry.files,
+					anchors: entry.anchors,
+					missingFiles: contextEntryPaths(entry).filter((path) => evidence.missingPaths.has(path)),
 				})),
 			),
 			"Changed files with no membership:",
@@ -540,7 +550,7 @@ export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence)
 				throw new Error(`Entry is unrelated: ${id}`);
 			if (conceptName !== existing.conceptName || conceptDescription !== existing.conceptDescription)
 				throw new Error(`Existing concept metadata cannot change: ${conceptId}`);
-			if (description === existing.description && files.join("\0") === existing.files.join("\0"))
+			if (description === existing.description && files.join("\0") === contextEntryPaths(existing).join("\0"))
 				throw new Error(`Set-entry is identical: ${id}`);
 		} else {
 			const existingConcept = evidence.entries.find((item) => item.tab === tab && item.concept === concept);
@@ -560,7 +570,7 @@ export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence)
 		}
 		changes.push({ action: "set-entry", tab, concept, conceptName, conceptDescription, entry, description, files });
 	}
-	const final = new Map(evidence.entries.map((entry) => [entry.id, [...entry.files]]));
+	const final = new Map(evidence.entries.map((entry) => [entry.id, contextEntryPaths(entry)]));
 	for (const change of changes) {
 		const id = `${change.tab}/${change.concept}/${change.entry}`;
 		if (change.action === "delete-entry") final.delete(id);
@@ -571,7 +581,7 @@ export function normalizeContextSyncPlan(input: unknown, evidence: SyncEvidence)
 	)) {
 		const old = current.get(`${change.tab}/${change.concept}/${change.entry}`);
 		if (!old) continue;
-		for (const path of old.files)
+		for (const path of contextEntryPaths(old))
 			if (evidence.eligibleFiles.has(path) && ![...final.values()].some((files) => files.includes(path)))
 				throw new Error(`Deleting entry would orphan surviving file: ${path}`);
 	}
@@ -640,6 +650,8 @@ export async function applyContextSyncPlan(
 ): Promise<ContextSyncDetails> {
 	for (const change of plan.changes) if (change.action === "set-entry") await requireFiles(root, change.files);
 	const concepts = [...new Set(plan.changes.map((change) => `${change.tab}/${change.concept}`))].sort();
+	const eagerPaths = new Set(entries.flatMap((entry) => entry.files));
+	const anchorPaths = new Set(entries.flatMap((entry) => entry.anchors).filter((path) => !eagerPaths.has(path)));
 	const outputs = new Map<string, string | undefined>();
 	for (const key of concepts) {
 		const [tab, concept] = key.split("/");
@@ -653,7 +665,12 @@ export async function applyContextSyncPlan(
 			else {
 				if (raw.name === undefined) raw.name = change.conceptName;
 				if (raw.description === undefined) raw.description = change.conceptDescription;
-				raw[change.entry] = { description: change.description, files: change.files };
+				const anchors = change.files.filter((path) => anchorPaths.has(path));
+				raw[change.entry] = {
+					description: change.description,
+					files: change.files.filter((path) => !anchors.includes(path)),
+					...(anchors.length ? { anchors } : {}),
+				};
 			}
 		}
 		outputs.set(

package/extensions/context/validation.ts

@@ -1,7 +1,7 @@
 import { stat } from "node:fs/promises";
 import { join } from "node:path";
 import type { GitRunner } from "../../shared/git.ts";
-import { isContextEligiblePath, isSensitiveContextPath, loadContextEntries } from "./definitions.ts";
+import { contextEntryPaths, isContextEligiblePath, isSensitiveContextPath, loadContextEntries } from "./definitions.ts";
 
 export interface ContextValidationResult {
 	stale: Array<{ path: string; ids: string[] }>;
@@ -16,7 +16,7 @@ export async function validateContextCatalog(
 	const entries = await loadContextEntries(root);
 	const memberships = new Map<string, string[]>();
 	for (const entry of entries)
-		for (const file of entry.files) memberships.set(file, [...(memberships.get(file) ?? []), entry.id]);
+		for (const file of contextEntryPaths(entry)) memberships.set(file, [...(memberships.get(file) ?? []), entry.id]);
 
 	const stale: Array<{ path: string; ids: string[] }> = [];
 	for (const [path, ids] of memberships) {

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. Context validation is disabled by default; when enabled, Tau checks changed-file membership and stale references after agent turns. 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. Entry `files` are autoread; entry `anchors` are unloaded navigation paths the agent can inspect when needed. Context validation is disabled by default; when enabled, Tau checks both classes for changed-file membership and stale references after agent turns. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
 ## explore
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"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.13.0",
+		"@shanepadgett/tau-tui": "0.14.0",
 		"@toon-format/toon": "2.3.0",
 		"smol-toml": "1.7.0"
 	},