@shanepadgett/tau-agent 0.28.1 → 0.30.0

package/extensions/working-memory/render.ts

@@ -0,0 +1,178 @@
+import type { AgentToolResult, Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { Marker } from "@shanepadgett/tau-tui";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../shared/tool-row-state.ts";
+import type { WorkingMemoryInput } from "./checkpoint.ts";
+import { parseWorkingMemoryDetails } from "./state.ts";
+
+const MAX_ITEMS = 20;
+const MAX_LINE = 240;
+const MAX_TEXT = 4_000;
+
+export type WorkingMemoryNudgeDetails =
+	| {
+			v: 1;
+			kind: "automatic";
+			tokens: number;
+			boundaryTokens: number;
+			reminder: number;
+			tier: number;
+			tierCount: number;
+			anchorToolCallId: string | null;
+	  }
+	| {
+			v: 1;
+			kind: "manual";
+			tokens: null;
+			boundaryTokens: null;
+			reminder: null;
+			tier: null;
+			tierCount: null;
+			anchorToolCallId: string | null;
+	  };
+
+export function parseWorkingMemoryNudge(value: unknown): WorkingMemoryNudgeDetails | undefined {
+	if (!isRecord(value) || value.v !== 1 || (value.kind !== "automatic" && value.kind !== "manual")) return undefined;
+	if (value.anchorToolCallId !== null && !nonempty(value.anchorToolCallId)) return undefined;
+	if (value.kind === "manual") {
+		if (
+			value.tokens !== null ||
+			value.boundaryTokens !== null ||
+			value.reminder !== null ||
+			value.tier !== null ||
+			value.tierCount !== null
+		) {
+			return undefined;
+		}
+		return {
+			v: 1,
+			kind: "manual",
+			tokens: null,
+			boundaryTokens: null,
+			reminder: null,
+			tier: null,
+			tierCount: null,
+			anchorToolCallId: value.anchorToolCallId,
+		};
+	}
+	if (
+		!count(value.tokens, 0) ||
+		!count(value.boundaryTokens, 1) ||
+		!count(value.reminder, 1) ||
+		!count(value.tier, 1, 5) ||
+		!count(value.tierCount, 1, 5) ||
+		value.boundaryTokens > value.tokens ||
+		value.tier > value.tierCount ||
+		value.tier !== Math.min(value.reminder, value.tierCount)
+	) {
+		return undefined;
+	}
+	return {
+		v: 1,
+		kind: "automatic",
+		tokens: value.tokens,
+		boundaryTokens: value.boundaryTokens,
+		reminder: value.reminder,
+		tier: value.tier,
+		tierCount: value.tierCount,
+		anchorToolCallId: value.anchorToolCallId,
+	};
+}
+
+export function renderWorkingMemoryNudge(details: unknown, theme: Theme): Marker | undefined {
+	const parsed = parseWorkingMemoryNudge(details);
+	if (!parsed) return undefined;
+	return new Marker({
+		theme,
+		state: "muted",
+		label: "Memory:",
+		parts:
+			parsed.kind === "manual" ? ["Reassessment requested."] : [formatTokens(parsed.boundaryTokens), "Reassess."],
+	});
+}
+
+export function renderWorkingMemoryCall(
+	args: WorkingMemoryInput,
+	theme: Theme,
+	context: {
+		rowState: ToolRowStateStore;
+		rowId: string;
+		invalidate: () => void;
+		lastComponent: unknown;
+	},
+): Text {
+	context.rowState.watch(context.rowId, context.invalidate);
+	const component = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+	const kept = Array.isArray(args.keep) ? args.keep.length : 0;
+	const outlined = Array.isArray(args.outlineFiles) ? args.outlineFiles.length : 0;
+	const deferred = Array.isArray(args.deferFiles) ? args.deferFiles.length : 0;
+	component.setText(
+		`${formatToolRowTitle(context.rowState, context.rowId, "working_memory", theme)} ${theme.fg("muted", `${kept} kept · ${outlined} outline · ${deferred} deferred`)}`,
+	);
+	return component;
+}
+
+export function renderWorkingMemoryResult(
+	result: AgentToolResult<unknown>,
+	expanded: boolean,
+	theme: Theme,
+	lastComponent: unknown,
+): Text {
+	const component = lastComponent instanceof Text ? lastComponent : new Text("", 0, 0);
+	const details = parseWorkingMemoryDetails(result.details);
+	if (!details) {
+		component.setText(
+			theme.fg("warning", bounded(firstText(result) || "working_memory returned invalid details", 1_000)),
+		);
+		return component;
+	}
+	let text = theme.fg(
+		details.warnings.length === 0 ? "success" : "warning",
+		`Checkpoint · kept ${details.retainedRefs.length} · outlined ${details.outlinedFiles.length} · deferred ${details.deferredFiles.length} · removed ${details.removedUnits}${details.warnings.length === 0 ? "" : ` · warnings ${details.warnings.length}`}`,
+	);
+	if (expanded) {
+		const lines = [
+			bounded(firstText(result), 1_500),
+			...details.retainedLabels.map((item) => `${item.ref} ${item.label}: ${item.preview}`),
+			...details.outlinedFiles.map((file) => `outlined: ${file.path}`),
+			...details.deferredFiles.map((file) => `deferred: ${file.path} — ${file.reason}; when ${file.relevantWhen}`),
+			...details.warnings.map((warning) => `warning: ${warning}`),
+		].filter(Boolean);
+		let remaining = MAX_TEXT - visibleWidth(text);
+		for (const line of lines.slice(0, MAX_ITEMS)) {
+			if (remaining <= 1) break;
+			const styled = theme.fg("dim", bounded(line, MAX_LINE));
+			text += `\n${truncateToWidth(styled, remaining - 1, "…")}`;
+			remaining -= 1 + Math.min(visibleWidth(styled), remaining - 1);
+		}
+		if (lines.length > MAX_ITEMS && remaining > 10)
+			text += `\n${theme.fg("dim", `… ${lines.length - MAX_ITEMS} more`)}`;
+	}
+	component.setText(text);
+	return component;
+}
+
+function firstText(result: AgentToolResult<unknown>): string {
+	for (const part of result.content) if (part.type === "text") return part.text;
+	return "";
+}
+
+function bounded(text: string, maximum: number): string {
+	return text.length <= maximum ? text : `${text.slice(0, maximum - 1)}…`;
+}
+
+function formatTokens(tokens: number): string {
+	return tokens < 1_000 ? `${tokens}` : `${Math.round(tokens / 1_000)}k`;
+}
+
+function count(value: unknown, minimum: number, maximum = Number.MAX_SAFE_INTEGER): value is number {
+	return Number.isSafeInteger(value) && (value as number) >= minimum && (value as number) <= maximum;
+}
+
+function nonempty(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/extensions/working-memory/settings.ts

@@ -0,0 +1,38 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+const DEFAULT_NUDGE_INSTRUCTIONS: [string, ...string[]] = [
+	"Reassess working memory. Continue coherent exploration when its evidence remains useful; otherwise prune known dead ends, obsolete outputs, and other context with no expected value.",
+	"Context is materially larger. Prune stale or bulky irrelevant evidence when safe, but keep active working evidence that would otherwise need to be reread.",
+	"Strongly reassess before more broad work. Remove accumulated waste and carry useful information at cheapest sufficient fidelity without scrubbing the active working set.",
+];
+
+export default defineTauExtensionSettings({
+	key: "workingMemory",
+	defaults: {
+		enabled: true as boolean,
+		nudgeEveryTokens: 40_000 as number,
+		nudgeInstructions: DEFAULT_NUDGE_INSTRUCTIONS,
+	},
+	schema: Type.Object(
+		{
+			enabled: Type.Optional(Type.Boolean({ default: true, description: "Enable working-memory checkpoints." })),
+			nudgeEveryTokens: Type.Optional(
+				Type.Integer({
+					default: 40_000,
+					minimum: 1,
+					description: "Active-context token interval between advisory working-memory reminders.",
+				}),
+			),
+			nudgeInstructions: Type.Optional(
+				Type.Array(Type.String({ minLength: 1, maxLength: 2_000 }), {
+					default: DEFAULT_NUDGE_INSTRUCTIONS,
+					minItems: 1,
+					maxItems: 5,
+					description: "Ordered advisory working-memory instructions. Later reminders repeat final instruction.",
+				}),
+			),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/working-memory/state.ts

@@ -0,0 +1,152 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const WORKING_MEMORY_TOOL = "working_memory";
+
+export interface DeferredFile {
+	path: string;
+	reason: string;
+	relevantWhen: string;
+}
+
+export interface RetainedLabel {
+	ref: string;
+	label: string;
+	preview: string;
+}
+
+export interface WorkingMemoryCheckpointDetailsV1 {
+	v: 1;
+	anchorToolCallId: string;
+	retainedRefs: string[];
+	retainedLabels: RetainedLabel[];
+	prunedRowIds: string[];
+	outlinedFiles: Array<{ path: string; rowId: string }>;
+	deferredFiles: DeferredFile[];
+	removedUnits: number;
+	warnings: string[];
+}
+
+export interface ActiveWorkingMemoryState {
+	latestAnchorToolCallId: string | undefined;
+	retainedRefs: readonly string[];
+	prunedRowIds: ReadonlySet<string>;
+}
+
+export function parseWorkingMemoryDetails(value: unknown): WorkingMemoryCheckpointDetailsV1 | undefined {
+	if (!isRecord(value) || value.v !== 1 || !nonempty(value.anchorToolCallId)) return undefined;
+	const keys = [
+		"v",
+		"anchorToolCallId",
+		"retainedRefs",
+		"retainedLabels",
+		"prunedRowIds",
+		"outlinedFiles",
+		"deferredFiles",
+		"removedUnits",
+		"warnings",
+	];
+	if (Object.keys(value).length !== keys.length || !keys.every((key) => Object.hasOwn(value, key))) return undefined;
+	const retainedRefs = uniqueStrings(value.retainedRefs);
+	const prunedRowIds = uniqueStrings(value.prunedRowIds);
+	const warnings = strings(value.warnings);
+	const retainedLabels = parseRetainedLabels(value.retainedLabels);
+	const outlinedFiles = parseOutlinedFiles(value.outlinedFiles);
+	const deferredFiles = parseDeferredFiles(value.deferredFiles);
+	if (
+		!retainedRefs ||
+		!prunedRowIds ||
+		!warnings ||
+		!retainedLabels ||
+		retainedLabels.length !== retainedRefs.length ||
+		retainedLabels.some((label, index) => label.ref !== retainedRefs[index]) ||
+		!outlinedFiles ||
+		!deferredFiles ||
+		!Number.isSafeInteger(value.removedUnits) ||
+		(value.removedUnits as number) < 0
+	) {
+		return undefined;
+	}
+	return {
+		v: 1,
+		anchorToolCallId: value.anchorToolCallId,
+		retainedRefs,
+		retainedLabels,
+		prunedRowIds,
+		outlinedFiles,
+		deferredFiles,
+		removedUnits: value.removedUnits as number,
+		warnings,
+	};
+}
+
+export function replayWorkingMemoryState(branch: readonly SessionEntry[], enabled: boolean): ActiveWorkingMemoryState {
+	let prunedRowIds = new Set<string>();
+	let latestAnchorToolCallId: string | undefined;
+	let retainedRefs: readonly string[] = [];
+	if (enabled) {
+		for (const entry of branch) {
+			if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
+			if (entry.message.toolName !== WORKING_MEMORY_TOOL) continue;
+			const details = parseWorkingMemoryDetails(entry.message.details);
+			if (!details || details.anchorToolCallId !== entry.message.toolCallId) continue;
+			prunedRowIds = new Set(details.prunedRowIds);
+			latestAnchorToolCallId = details.anchorToolCallId;
+			retainedRefs = details.retainedRefs;
+		}
+	}
+	return { latestAnchorToolCallId, retainedRefs, prunedRowIds };
+}
+
+function parseRetainedLabels(value: unknown): RetainedLabel[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const labels: RetainedLabel[] = [];
+	for (const item of value) {
+		if (!isRecord(item) || !nonempty(item.ref) || !nonempty(item.label) || typeof item.preview !== "string") {
+			return undefined;
+		}
+		labels.push({ ref: item.ref, label: item.label, preview: item.preview });
+	}
+	return labels;
+}
+
+function parseOutlinedFiles(value: unknown): Array<{ path: string; rowId: string }> | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const files: Array<{ path: string; rowId: string }> = [];
+	for (const item of value) {
+		if (!isRecord(item) || !nonempty(item.path) || !nonempty(item.rowId)) return undefined;
+		files.push({ path: item.path, rowId: item.rowId });
+	}
+	return files;
+}
+
+function parseDeferredFiles(value: unknown): DeferredFile[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	const files: DeferredFile[] = [];
+	for (const item of value) {
+		if (!isRecord(item) || !nonempty(item.path) || !nonempty(item.reason) || !nonempty(item.relevantWhen)) {
+			return undefined;
+		}
+		files.push({ path: item.path, reason: item.reason, relevantWhen: item.relevantWhen });
+	}
+	return files;
+}
+
+function uniqueStrings(value: unknown): string[] | undefined {
+	const parsed = strings(value, true);
+	if (!parsed || new Set(parsed).size !== parsed.length) return undefined;
+	return parsed;
+}
+
+function strings(value: unknown, requireNonempty = false): string[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (!value.every((item) => typeof item === "string" && (!requireNonempty || item.length > 0))) return undefined;
+	return [...value];
+}
+
+function nonempty(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.28.1",
+	"version": "0.30.0",
 	"description": "Tau is a custom agentic harness built with pi extensions",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -35,7 +35,7 @@
 	],
 	"dependencies": {
 		"@ast-grep/wasm": "0.45.0",
-		"@shanepadgett/tau-tui": "0.28.1",
+		"@shanepadgett/tau-tui": "0.30.0",
 		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0",

package/schemas/tau.schema.json

@@ -53,39 +53,6 @@
 					},
 					"additionalProperties": false
 				},
-				"contextPruning": {
-					"type": "object",
-					"properties": {
-						"enabled": {
-							"type": "boolean",
-							"default": true,
-							"description": "Enable context pruning."
-						},
-						"nudgeEveryTokens": {
-							"type": "integer",
-							"default": 30000,
-							"minimum": 1,
-							"description": "Active-context token interval between automatic pruning hints."
-						},
-						"nudgeInstructions": {
-							"type": "array",
-							"items": {
-								"type": "string",
-								"minLength": 1,
-								"maxLength": 2000
-							},
-							"default": [
-								"No prune is required yet unless broad exploration has converged or substantial evidence is already irrelevant. Continue coherent work.",
-								"Move toward a pruning point now. Finish the current coherent step, then prune before starting another broad exploration. Managed context is materially increasing model cost.",
-								"Prune now before further tool work. Continuing with stale managed context is wasting money."
-							],
-							"minItems": 1,
-							"maxItems": 5,
-							"description": "Ordered automatic pruning instructions. Later reminders repeat the final instruction, and the final tier requires an anchor before further tool work."
-						}
-					},
-					"additionalProperties": false
-				},
 				"explore": {
 					"type": "object",
 					"properties": {
@@ -114,12 +81,6 @@
 									"default": 200,
 									"minimum": 1,
 									"description": "Registered source at or under this line count may be full-read. Above it, full read model-visible result is outline only."
-								},
-								"maxRangeLines": {
-									"type": "integer",
-									"default": 200,
-									"minimum": 1,
-									"description": "Maximum lines returned by one ranged read on registered source."
 								}
 							},
 							"additionalProperties": false
@@ -287,31 +248,50 @@
 					},
 					"additionalProperties": false
 				},
-				"turnBudget": {
+				"subagent": {
+					"type": "object",
+					"properties": {
+						"disabled": {
+							"type": "array",
+							"items": {
+								"type": "string",
+								"minLength": 1
+							},
+							"default": [],
+							"description": "Agent names unavailable for delegation."
+						}
+					},
+					"additionalProperties": false
+				},
+				"workingMemory": {
 					"type": "object",
 					"properties": {
 						"enabled": {
 							"type": "boolean",
 							"default": true,
-							"description": "Enable turn-budget hints."
+							"description": "Enable working-memory checkpoints."
 						},
-						"turnLimit": {
+						"nudgeEveryTokens": {
 							"type": "integer",
-							"default": 30,
+							"default": 40000,
 							"minimum": 1,
-							"description": "Initial soft cap for tool-using turns per user prompt."
+							"description": "Active-context token interval between advisory working-memory reminders."
 						},
-						"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."
+						"nudgeInstructions": {
+							"type": "array",
+							"items": {
+								"type": "string",
+								"minLength": 1,
+								"maxLength": 2000
+							},
+							"default": [
+								"Reassess working memory. Continue coherent exploration when its evidence remains useful; otherwise prune known dead ends, obsolete outputs, and other context with no expected value.",
+								"Context is materially larger. Prune stale or bulky irrelevant evidence when safe, but keep active working evidence that would otherwise need to be reread.",
+								"Strongly reassess before more broad work. Remove accumulated waste and carry useful information at cheapest sufficient fidelity without scrubbing the active working set."
+							],
+							"minItems": 1,
+							"maxItems": 5,
+							"description": "Ordered advisory working-memory instructions. Later reminders repeat final instruction."
 						}
 					},
 					"additionalProperties": false

package/shared/context-messages.ts

@@ -0,0 +1,19 @@
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+type ContextMessage = ContextEvent["messages"][number];
+
+export const CONTEXT_PROJECTION_TYPE = "tau.context.projection";
+
+export function isContextProjectionMessage(message: ContextMessage): boolean {
+	return message.role === "custom" && message.customType === CONTEXT_PROJECTION_TYPE;
+}
+
+export function isLegacyContextMessage(message: ContextMessage): boolean {
+	if (message.role !== "custom") return false;
+	if (message.customType !== "tau.injected-context" && message.customType !== "tau.autoread") return false;
+	return (
+		message.details !== undefined &&
+		typeof message.details === "object" &&
+		(message.details as Record<string, unknown>).source === "context"
+	);
+}

package/shared/events.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { OutlineInjectionRequest, OutlineInjectionResponse } from "./outline-injection.js";
 import type { ToolRowVisualState } from "./tool-row-state.js";
 
 export type TauAgentEvents = {
@@ -36,6 +37,10 @@ export type TauAgentEvents = {
 		batchId: string;
 		files: Array<{ path: string }>;
 	};
+	"tau:outline-injection.requested": {
+		request: OutlineInjectionRequest;
+		accept(response: Promise<OutlineInjectionResponse>): void;
+	};
 	"tau:footer-item": {
 		id: string;
 		text?: string;

package/shared/full-file-knowledge.ts

@@ -16,7 +16,6 @@ export interface ReadCacheMetaV1 {
 }
 
 const COMPLETE_FILE_SCOPE = "full";
-export const MAX_COMPLETE_FILE_SNAPSHOT_BYTES = 1024 * 1024;
 
 export function createCompleteFileMeta(options: {
 	pathKey: string;

package/shared/injected-context.ts

@@ -3,7 +3,7 @@ import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 export const INJECTED_CONTEXT_TYPE = "tau.injected-context";
 
 export interface InjectedContextDetails {
-	source: "review" | "context";
+	source: "review";
 	title?: string;
 }
 
@@ -61,7 +61,7 @@ export function getBranchInjectedContexts(entries: readonly SessionEntry[]): Inj
 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 !== "context") return undefined;
+	if (record.source !== "review") return undefined;
 	return {
 		source: record.source,
 		...(typeof record.title === "string" ? { title: record.title } : {}),