@shanepadgett/tau-agent 0.1.0

package/schemas/tau.schema.json

@@ -0,0 +1,205 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"$id": "https://raw.githubusercontent.com/shanepadgett/tau-agent/refs/heads/main/packages/agent/schemas/tau.schema.json",
+	"title": "Tau Configuration",
+	"description": "Configuration for Tau and Tau extensions.",
+	"type": "object",
+	"properties": {
+		"$schema": {
+			"type": "string",
+			"description": "Optional schema reference used by editors for validation and autocomplete."
+		},
+		"extensions": {
+			"type": "object",
+			"properties": {
+				"footer": {
+					"type": "object",
+					"properties": {
+						"enabled": {
+							"type": "boolean",
+							"default": true,
+							"description": "Enable Tau's compact footer."
+						}
+					},
+					"additionalProperties": false
+				},
+				"modelFallback": {
+					"type": "object",
+					"properties": {
+						"cooldowns": {
+							"type": "object",
+							"patternProperties": {
+								"^.*$": {
+									"type": "number",
+									"description": "Unix epoch milliseconds when the provider becomes available again."
+								}
+							}
+						}
+					},
+					"additionalProperties": false
+				},
+				"reference": {
+					"type": "object",
+					"properties": {
+						"editor": {
+							"anyOf": [
+								{
+									"type": "string",
+									"const": "default"
+								},
+								{
+									"type": "string",
+									"const": "code"
+								},
+								{
+									"type": "string",
+									"const": "zed"
+								}
+							],
+							"default": "default",
+							"description": "Editor used by the reference picker open action. default uses $VISUAL, $EDITOR, then code."
+						},
+						"branchChoices": {
+							"type": "integer",
+							"default": 5,
+							"minimum": 1,
+							"maximum": 50,
+							"description": "Maximum branch choices shown when switching a reference branch."
+						}
+					},
+					"additionalProperties": false
+				},
+				"silentCommandRunner": {
+					"type": "object",
+					"properties": {
+						"enabled": {
+							"type": "boolean",
+							"default": true,
+							"description": "Enable silent command runner."
+						},
+						"maxOutputBytes": {
+							"type": "integer",
+							"default": 51200,
+							"minimum": 1,
+							"description": "Maximum raw stdout/stderr bytes sent to the agent."
+						},
+						"commands": {
+							"type": "array",
+							"items": {
+								"type": "object",
+								"required": [
+									"name",
+									"command"
+								],
+								"properties": {
+									"name": {
+										"type": "string",
+										"description": "Short command name shown in notifications and failure messages."
+									},
+									"enabled": {
+										"type": "boolean",
+										"default": true,
+										"description": "Enable this command."
+									},
+									"command": {
+										"type": "string",
+										"description": "Shell command run with sh -lc after matching files change."
+									},
+									"cwd": {
+										"type": "string",
+										"default": ".",
+										"description": "Command working directory, relative to project root."
+									},
+									"env": {
+										"type": "object",
+										"patternProperties": {
+											"^.*$": {
+												"type": "string"
+											}
+										},
+										"description": "Extra environment values."
+									},
+									"details": {
+										"type": "string",
+										"description": "Free-text explanation of what this command checks or runs."
+									},
+									"includeGlobs": {
+										"type": "array",
+										"items": {
+											"type": "string"
+										},
+										"default": [
+											"**/*"
+										],
+										"description": "Project-relative files that trigger this command."
+									},
+									"excludeGlobs": {
+										"type": "array",
+										"items": {
+											"type": "string"
+										},
+										"default": [],
+										"description": "Project-relative files ignored for this command."
+									},
+									"timeoutMs": {
+										"type": "integer",
+										"default": 120000,
+										"minimum": 1,
+										"description": "Command timeout in milliseconds."
+									}
+								},
+								"additionalProperties": false
+							},
+							"default": [],
+							"description": "Commands run after matched files change."
+						}
+					},
+					"additionalProperties": false
+				},
+				"soul": {
+					"type": "object",
+					"properties": {
+						"enabled": {
+							"type": "boolean",
+							"default": true,
+							"description": "Enable Tau's Rok system prompt."
+						}
+					},
+					"additionalProperties": false
+				},
+				"turnBudget": {
+					"type": "object",
+					"properties": {
+						"enabled": {
+							"type": "boolean",
+							"default": true,
+							"description": "Enable turn-budget hints."
+						},
+						"turnLimit": {
+							"type": "integer",
+							"default": 30,
+							"minimum": 1,
+							"description": "Initial soft cap for tool-using turns per user prompt."
+						},
+						"nudgeEveryTurns": {
+							"type": "integer",
+							"default": 5,
+							"minimum": 1,
+							"description": "Tool-using turn interval between turn-budget hints."
+						},
+						"softCapIncrement": {
+							"type": "integer",
+							"default": 10,
+							"minimum": 1,
+							"description": "Turns added when the soft cap is reached."
+						}
+					},
+					"additionalProperties": false
+				}
+			},
+			"additionalProperties": true,
+			"default": {}
+		}
+	},
+	"additionalProperties": false
+}

package/shared/agent-blocked.ts

@@ -0,0 +1,12 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { emitTauEvent } from "./events.ts";
+
+export interface AgentBlockedNotice {
+	title?: string;
+	body?: string;
+	source?: string;
+}
+
+export function emitAgentBlocked(pi: Pick<ExtensionAPI, "events">, notice: AgentBlockedNotice = {}): void {
+	emitTauEvent(pi, "tau:agent.blocked", notice);
+}

package/shared/description.ts

@@ -0,0 +1,28 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { browseIdeas } from "../extensions/ideas/browser.ts";
+import { browseStash } from "../extensions/stash/browser.ts";
+
+export interface DescriptionPromptResult {
+	text: string;
+	source: "manual" | "idea" | "stash";
+}
+
+export async function promptForDescription(ctx: ExtensionCommandContext): Promise<DescriptionPromptResult | null> {
+	while (true) {
+		const choice = await ctx.ui.select("Description source", [
+			"Write description",
+			"Pull from ideas",
+			"Pull from stash",
+		]);
+		if (choice === undefined) return null;
+		if (choice === "Write description") return { text: "", source: "manual" };
+		if (choice === "Pull from ideas") {
+			const idea = await browseIdeas(ctx);
+			if (idea) return { text: idea.text, source: "idea" };
+		} else {
+			const stash = await browseStash(ctx);
+			if (stash) return { text: stash.text, source: "stash" };
+		}
+		// Browser cancelled without a pick; loop back to source select.
+	}
+}

package/shared/events.ts

@@ -0,0 +1,135 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ToolRowVisualState } from "./tool-row-state.js";
+
+export type TauAgentEvents = {
+	"tau:agent.blocked": {
+		title?: string;
+		body?: string;
+		source?: string;
+	};
+	"tau:file-mutation.applied": {
+		source: "patch";
+		toolCallId: string;
+		cwd: string;
+		status: "completed" | "partial" | "failed";
+		changes: Array<{
+			path: string;
+			kind: "add" | "replace" | "update" | "delete";
+			move?: { from: string; to: string };
+			linesAdded: number;
+			linesRemoved: number;
+			snapshotRanges?: Array<{ startLine: number; endLine: number }>;
+		}>;
+	};
+	"tau:autoread.requested": {
+		source: string;
+		title?: string;
+		cwd: string;
+		batchId: string;
+		files: Array<{ path: string }>;
+	};
+	"tau:footer-item": {
+		id: string;
+		text?: string;
+		priority?: number;
+	};
+	"tau:tool-row-state.set": {
+		rowId: string;
+		state?: ToolRowVisualState;
+	};
+};
+
+export interface TauFooterItem {
+	id: string;
+	text?: string;
+	priority?: number;
+}
+
+type EmitEventAPI = Pick<ExtensionAPI, "events">;
+
+interface TauEventAPI extends EmitEventAPI {
+	on(event: "session_start", handler: () => void): void;
+	on(event: "session_shutdown", handler: () => void): void;
+}
+
+type TauEventHandler<Name extends keyof TauAgentEvents> = (data: TauAgentEvents[Name]) => void | Promise<void>;
+
+interface TauEventSubscription {
+	stop(): void;
+}
+
+const tauEventSubscriptions = new WeakMap<
+	ExtensionAPI["events"],
+	Map<string, Map<keyof TauAgentEvents, TauEventSubscription>>
+>();
+
+export function emitTauEvent<Name extends keyof TauAgentEvents>(
+	pi: EmitEventAPI,
+	name: Name,
+	data: TauAgentEvents[Name],
+): void {
+	pi.events.emit(name, data);
+}
+
+export function onTauEvent<Name extends keyof TauAgentEvents>(
+	pi: TauEventAPI,
+	owner: string,
+	name: Name,
+	handler: TauEventHandler<Name>,
+): () => void {
+	if (owner.length === 0) throw new Error("Tau event owner is required.");
+
+	const subscriptions = getOwnerSubscriptions(pi.events, owner);
+	subscriptions.get(name)?.stop();
+
+	let unsubscribe: (() => void) | undefined;
+	let disposed = false;
+
+	function detach(): void {
+		unsubscribe?.();
+		unsubscribe = undefined;
+	}
+
+	const subscription: TauEventSubscription = {
+		stop() {
+			if (disposed) return;
+			disposed = true;
+			detach();
+			if (subscriptions.get(name) === subscription) subscriptions.delete(name);
+		},
+	};
+
+	function attach(): void {
+		if (disposed) return;
+		detach();
+		unsubscribe = pi.events.on(name, handler as (data: unknown) => void);
+	}
+
+	subscriptions.set(name, subscription);
+	pi.on("session_start", attach);
+	pi.on("session_shutdown", detach);
+	return subscription.stop;
+}
+
+export function setTauFooterItem(pi: EmitEventAPI, item: TauFooterItem): void {
+	emitTauEvent(pi, "tau:footer-item", item);
+}
+
+function getOwnerSubscriptions(
+	events: ExtensionAPI["events"],
+	owner: string,
+): Map<keyof TauAgentEvents, TauEventSubscription> {
+	let busSubscriptions = tauEventSubscriptions.get(events);
+	if (!busSubscriptions) {
+		busSubscriptions = new Map();
+		tauEventSubscriptions.set(events, busSubscriptions);
+	}
+
+	let ownerSubscriptions = busSubscriptions.get(owner);
+	if (!ownerSubscriptions) {
+		ownerSubscriptions = new Map();
+		busSubscriptions.set(owner, ownerSubscriptions);
+	}
+
+	return ownerSubscriptions;
+}

package/shared/git.ts

@@ -0,0 +1,41 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+const DEFAULT_GIT_TIMEOUT_MS = 10_000;
+
+export interface GitRunner {
+	cwd: string;
+	run(args: string[], options?: { cwd?: string; optional?: boolean; timeout?: number }): Promise<string>;
+}
+
+export function createGitRunner(pi: ExtensionAPI, ctx: ExtensionCommandContext): GitRunner {
+	return {
+		cwd: ctx.cwd,
+		async run(args, options = {}) {
+			const result = await pi.exec("git", args, {
+				cwd: options.cwd ?? this.cwd,
+				signal: ctx.signal,
+				timeout: options.timeout ?? DEFAULT_GIT_TIMEOUT_MS,
+			});
+			if (result.code === 0) return result.stdout.trim();
+			if (options.optional) return "";
+
+			const details = [result.stderr, result.stdout].filter(Boolean).join("\n").trim();
+			throw new Error(details || `git ${args.join(" ")} failed with exit code ${result.code}`);
+		},
+	};
+}
+
+export interface RepoStatus {
+	root: string;
+	fileCount: number;
+}
+
+// Resolves the repo root and counts dirty entries (staged, unstaged, and
+// untracked). Returns null outside a git repo; returns fileCount 0 when the
+// tree is clean. Callers surface each case.
+export async function loadRepoStatus(git: GitRunner): Promise<RepoStatus | null> {
+	const root = await git.run(["rev-parse", "--show-toplevel"], { optional: true });
+	if (!root) return null;
+	const status = await git.run(["status", "--porcelain=v1", "--untracked-files=all"], { cwd: root });
+	return { root, fileCount: status ? status.split("\n").filter(Boolean).length : 0 };
+}

package/shared/injected-context.ts

@@ -0,0 +1,69 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const INJECTED_CONTEXT_TYPE = "tau.injected-context";
+
+export interface InjectedContextDetails {
+	source: "review" | "tau-context";
+	title?: string;
+}
+
+export interface InjectedContext {
+	content: string;
+	details: InjectedContextDetails;
+}
+
+export interface InjectedContextMessage {
+	customType: typeof INJECTED_CONTEXT_TYPE;
+	content: string;
+	display: false;
+	details: InjectedContextDetails;
+}
+
+const pending: InjectedContextMessage[] = [];
+const emittedThisTurn: InjectedContextMessage[] = [];
+
+export function createInjectedContext(content: string, details: InjectedContextDetails): InjectedContextMessage {
+	return { customType: INJECTED_CONTEXT_TYPE, content, display: false, details };
+}
+
+export function queueInjectedContext(content: string, details: InjectedContextDetails): void {
+	pending.push(createInjectedContext(content, details));
+}
+
+export function shiftPendingInjectedContext(): InjectedContextMessage | undefined {
+	const message = pending.shift();
+	if (message) emittedThisTurn.push(message);
+	return message;
+}
+
+export function getPendingInjectedContexts(): InjectedContext[] {
+	return [...pending, ...emittedThisTurn].map(({ content, details }) => ({ content, details }));
+}
+
+export function clearEmittedInjectedContexts(): void {
+	emittedThisTurn.length = 0;
+}
+
+export function clearPendingInjectedContexts(): void {
+	pending.length = 0;
+	emittedThisTurn.length = 0;
+}
+
+export function getBranchInjectedContexts(entries: readonly SessionEntry[]): InjectedContext[] {
+	return entries.flatMap((entry) => {
+		if (entry.type !== "custom_message" || entry.customType !== INJECTED_CONTEXT_TYPE) return [];
+		if (typeof entry.content !== "string") return [];
+		const details = readDetails(entry.details);
+		return details ? [{ content: entry.content, details }] : [];
+	});
+}
+
+function readDetails(value: unknown): InjectedContextDetails | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const record = value as Record<string, unknown>;
+	if (record.source !== "review" && record.source !== "tau-context") return undefined;
+	return {
+		source: record.source,
+		...(typeof record.title === "string" ? { title: record.title } : {}),
+	};
+}

package/shared/jsonl-store.ts

@@ -0,0 +1,108 @@
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { resolveProjectRoot } from "./settings/paths.ts";
+
+// Shared storage for JSONL lists of `{ id, text, createdAt }` records.
+
+export interface DatedRecord {
+	id: string;
+	text: string;
+	createdAt: number;
+}
+
+export async function recordFilePath(cwd: string, filename: string): Promise<string> {
+	const root = await resolveProjectRoot(cwd);
+	return join(root, ".pi", "tau", filename);
+}
+
+export async function loadRecords(cwd: string, filename: string, label: string): Promise<DatedRecord[]> {
+	const path = await recordFilePath(cwd, filename);
+	return loadRecordsAtPath(path, label);
+}
+
+export async function loadRecordsAtPath(path: string, label: string): Promise<DatedRecord[]> {
+	let raw: string;
+	try {
+		raw = await readFile(path, "utf8");
+	} catch (error) {
+		if (isErrorCode(error, "ENOENT")) return [];
+		throw error;
+	}
+
+	return sortByNewest(parseRecords(raw, path, label));
+}
+
+export async function appendRecord(cwd: string, filename: string, text: string): Promise<DatedRecord> {
+	const path = await recordFilePath(cwd, filename);
+	return appendRecordAtPath(path, text);
+}
+
+export async function appendRecordAtPath(path: string, text: string): Promise<DatedRecord> {
+	const record: DatedRecord = { id: randomUUID(), text: text.trim(), createdAt: Date.now() };
+	await mkdir(dirname(path), { recursive: true });
+	await appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+	return record;
+}
+
+// Atomic rewrite for edits/removals: temp file in the same dir, then rename
+// over the target. Keeps on-disk order matching display (newest first).
+export async function saveRecords(cwd: string, filename: string, records: readonly DatedRecord[]): Promise<void> {
+	const path = await recordFilePath(cwd, filename);
+	return saveRecordsAtPath(path, records);
+}
+
+export async function saveRecordsAtPath(path: string, records: readonly DatedRecord[]): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	const content = sortByNewest([...records])
+		.map((record) => JSON.stringify(record))
+		.join("\n");
+	const tmp = `${path}.${randomUUID()}.tmp`;
+	await writeFile(tmp, content ? `${content}\n` : "", "utf8");
+	await rename(tmp, path);
+}
+
+function sortByNewest(records: readonly DatedRecord[]): DatedRecord[] {
+	return [...records].sort((left, right) => right.createdAt - left.createdAt);
+}
+
+function parseRecords(raw: string, path: string, label: string): DatedRecord[] {
+	const records: DatedRecord[] = [];
+	let lineNumber = 0;
+	for (const line of raw.split("\n")) {
+		lineNumber++;
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		records.push(parseRecord(trimmed, path, lineNumber, label));
+	}
+	return records;
+}
+
+function parseRecord(line: string, path: string, lineNumber: number, label: string): DatedRecord {
+	let value: unknown;
+	try {
+		value = JSON.parse(line);
+	} catch (error) {
+		throw new Error(`Invalid ${label} JSONL at ${path}:${lineNumber}: ${errorText(error)}`);
+	}
+	if (!value || typeof value !== "object") throw invalidRecord(path, lineNumber, label);
+	const record = value as Record<string, unknown>;
+	const { id, text, createdAt } = record;
+	if (typeof id !== "string" || typeof text !== "string" || typeof createdAt !== "number") {
+		throw invalidRecord(path, lineNumber, label);
+	}
+	if (!Number.isFinite(createdAt)) throw invalidRecord(path, lineNumber, label);
+	return { id, text, createdAt };
+}
+
+function invalidRecord(path: string, lineNumber: number, label: string): Error {
+	return new Error(`Invalid ${label} record at ${path}:${lineNumber}`);
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+	return typeof error === "object" && error !== null && "code" in error && error.code === code;
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}