@shanepadgett/tau-agent 0.31.1 → 0.33.0

package/extensions/working-memory/checkpoint.ts

@@ -2,17 +2,38 @@ import { resolve } from "node:path";
 import { type ExtensionAPI, type ExtensionContext, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { type Static, Type } from "typebox";
 import { truncateBoundedHead } from "../../shared/bounded-text-result.ts";
+import { emitTauEvent } from "../../shared/events.ts";
 import { requestOutlineInjections, type PreparedOutlineInjection } from "../../shared/outline-injection.ts";
 import { buildMemoryCatalog, collectPrunedRowIds } from "./memory.ts";
-import { WORKING_MEMORY_TOOL, type DeferredFile, type WorkingMemoryCheckpointDetailsV1 } from "./state.ts";
+import {
+	replayWorkingMemoryState,
+	WORKING_MEMORY_TOOL,
+	type DeferredFile,
+	type WorkingMemoryCheckpointDetailsV2,
+} from "./state.ts";
 
 const PATH = Type.String({ minLength: 1, maxLength: 500, pattern: "\\S" });
 
 export const workingMemoryParameters = Type.Object(
 	{
-		continuation: Type.String({ minLength: 1, maxLength: 8_000, pattern: "\\S" }),
-		keep: Type.Array(Type.String({ minLength: 3, maxLength: 100 }), { maxItems: 100 }),
-		outlineFiles: Type.Array(PATH, { maxItems: 12 }),
+		continuation: Type.String({
+			minLength: 1,
+			maxLength: 8_000,
+			pattern: "\\S",
+			description:
+				"Working note for resuming mid-task. Carry durable decisions, concrete findings, live reasoning, unresolved questions, remaining work, and next action; include enough detail to continue without rereading discarded results.",
+		}),
+		keep: Type.Array(Type.String({ minLength: 3, maxLength: 100 }), { minItems: 1, maxItems: 100 }),
+		readFiles: Type.Array(PATH, {
+			maxItems: 12,
+			description:
+				"Files whose source should be auto-read into the next turn. Use when the next work needs the complete file; do not also outline or defer these files.",
+		}),
+		outlineFiles: Type.Array(PATH, {
+			maxItems: 12,
+			description:
+				"Files whose structural outline should be carried into the next turn. Use when symbols and locations will guide later scoped inspection; do not use when the full source is still needed.",
+		}),
 		deferFiles: Type.Array(
 			Type.Object(
 				{
@@ -22,7 +43,11 @@ export const workingMemoryParameters = Type.Object(
 				},
 				{ additionalProperties: false },
 			),
-			{ maxItems: 8 },
+			{
+				maxItems: 8,
+				description:
+					"Files to leave out of active context. Record why they are inactive and the concrete condition that would make them relevant.",
+			},
 		),
 	},
 	{ additionalProperties: false },
@@ -43,7 +68,7 @@ interface ExecuteWorkingMemoryOptions {
 export interface WorkingMemoryExecution {
 	result: {
 		content: Array<{ type: "text"; text: string }>;
-		details: WorkingMemoryCheckpointDetailsV1;
+		details: WorkingMemoryCheckpointDetailsV2;
 	};
 	outlines: PreparedOutlineInjection[];
 }
@@ -52,6 +77,12 @@ export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions)
 	assertCurrent(options);
 	const branch = options.ctx.sessionManager.getBranch();
 	const catalog = buildMemoryCatalog(branch);
+	const anchorIndex = findAnchorEntry(branch, options.toolCallId);
+	const previousState = replayWorkingMemoryState(branch, true);
+	const previousAnchorIndex =
+		previousState.latestAnchorToolCallId === undefined
+			? -1
+			: findAnchorEntry(branch, previousState.latestAnchorToolCallId);
 	const requestedRefs = [...new Set(options.params.keep)];
 	const retained = requestedRefs
 		.flatMap((ref) => {
@@ -60,11 +91,32 @@ export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions)
 		})
 		.sort((left, right) => left.order - right.order);
 	const retainedRefs = retained.map((unit) => unit.ref);
+	if (retained.length === 0) {
+		throw new Error("working_memory requires at least one valid keep reference");
+	}
 	const warnings = requestedRefs
 		.filter((ref) => !catalog.has(ref))
 		.map((ref) => `${ref}: memory reference is unavailable and was not retained`);
 
-	const outlinePaths = dedupePaths(options.params.outlineFiles, options.ctx.cwd);
+	const rootInstructionsKey = resolve(options.ctx.cwd, "AGENTS.md");
+	const requestedRootInstructions = [
+		...options.params.readFiles,
+		...options.params.outlineFiles,
+		...options.params.deferFiles.map((file) => file.path),
+	].some((path) => resolve(options.ctx.cwd, normalizePath(path)) === rootInstructionsKey);
+	if (requestedRootInstructions) {
+		warnings.push(
+			"AGENTS.md: omitted from working-memory checkpoint because it is already in your context window. Read it directly only when actively changing it.",
+		);
+	}
+
+	const readPaths = dedupePaths(options.params.readFiles, options.ctx.cwd).filter(
+		(path) => resolve(options.ctx.cwd, path) !== rootInstructionsKey,
+	);
+	const readKeys = new Set(readPaths.map((path) => resolve(options.ctx.cwd, path)));
+	const outlinePaths = dedupePaths(options.params.outlineFiles, options.ctx.cwd).filter(
+		(path) => resolve(options.ctx.cwd, path) !== rootInstructionsKey && !readKeys.has(resolve(options.ctx.cwd, path)),
+	);
 	const outlineResponse = await requestOutlineInjections(options.pi, {
 		cwd: options.ctx.cwd,
 		batchId: options.toolCallId,
@@ -75,34 +127,50 @@ export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions)
 	warnings.push(...outlineResponse.warnings.map((warning) => boundedWarning(warning)));
 	assertCurrent(options);
 
-	const outlinedKeys = new Set(
-		outlineResponse.messages.map((message) => resolve(options.ctx.cwd, message.details.path)),
-	);
+	const carriedKeys = new Set([
+		...readKeys,
+		...outlineResponse.messages.map((message) => resolve(options.ctx.cwd, message.details.path)),
+	]);
 	const deferredFiles: DeferredFile[] = [];
 	const deferredKeys = new Set<string>();
 	for (const file of options.params.deferFiles) {
 		const path = normalizePath(file.path);
 		const key = resolve(options.ctx.cwd, path);
-		if (outlinedKeys.has(key) || deferredKeys.has(key)) continue;
+		if (key === rootInstructionsKey || carriedKeys.has(key) || deferredKeys.has(key)) continue;
 		deferredKeys.add(key);
 		deferredFiles.push({ path, reason: file.reason.trim(), relevantWhen: file.relevantWhen.trim() });
 	}
 
-	const anchorIndex = findAnchorEntry(branch, options.toolCallId);
-	const preAnchorUnits = [...catalog.values()].filter((unit) => unit.order < anchorIndex);
+	if (readPaths.length > 0) {
+		emitTauEvent(options.pi, "tau:autoread.requested", {
+			source: WORKING_MEMORY_TOOL,
+			title: "Working-memory checkpoint",
+			cwd: options.ctx.cwd,
+			batchId: options.toolCallId,
+			files: readPaths.map((path) => ({ path })),
+		});
+	}
+
 	const prunedRowIds = collectPrunedRowIds(branch, anchorIndex);
-	const details: WorkingMemoryCheckpointDetailsV1 = {
-		v: 1,
+	const activeRefs = new Set(previousState.retainedRefs.filter((ref) => catalog.has(ref)));
+	for (const unit of catalog.values()) {
+		if (unit.order > previousAnchorIndex && unit.order < anchorIndex) activeRefs.add(unit.ref);
+	}
+	const newlyPrunedRows = prunedRowIds.filter((rowId) => !previousState.prunedRowIds.has(rowId));
+	const droppedBlocks = [...activeRefs].filter((ref) => !retainedRefs.includes(ref)).length + newlyPrunedRows.length;
+	const details: WorkingMemoryCheckpointDetailsV2 = {
+		v: 2,
 		anchorToolCallId: options.toolCallId,
 		retainedRefs,
 		retainedLabels: retained.map((unit) => ({ ref: unit.ref, label: unit.label, preview: unit.preview })),
 		prunedRowIds,
+		readFiles: readPaths,
 		outlinedFiles: outlineResponse.messages.map((message) => ({
 			path: message.details.path,
 			rowId: message.details.rowId,
 		})),
 		deferredFiles,
-		removedUnits: Math.max(0, preAnchorUnits.length - retained.length),
+		removedUnits: droppedBlocks,
 		warnings,
 	};
 	const markdown = formatResult(options.params.continuation.trim(), deferredFiles, warnings);

package/extensions/working-memory/index.ts

@@ -17,12 +17,12 @@ import {
 	type WorkingMemoryNudgeDetails,
 } from "./render.ts";
 import workingMemorySettings from "./settings.ts";
-import { replayWorkingMemoryState, WORKING_MEMORY_TOOL, type WorkingMemoryCheckpointDetailsV1 } from "./state.ts";
+import { replayWorkingMemoryState, WORKING_MEMORY_TOOL, type WorkingMemoryCheckpointDetailsV2 } from "./state.ts";
 
 const NUDGE_TYPE = "tau.working-memory.nudge";
 const BASELINE_TYPE = "tau.working-memory.nudge-baseline";
 const TOOL_DESCRIPTION =
-	"Create a selective hard checkpoint for future model context. Keep valuable user and visible assistant messages, carry file structure as outlines, defer conditionally relevant files without reading them, and distill exploration findings into one compact continuation note.";
+	"Create a selective hard checkpoint for future model context. Retain one or more valuable user or visible assistant messages, auto-read full source or carry file structure as needed, defer conditionally relevant files, and distill exploration findings into one compact continuation note.";
 
 interface NudgeState {
 	anchorToolCallId: string | undefined;
@@ -91,7 +91,7 @@ export default function workingMemoryExtension(pi: ExtensionAPI): void {
 		instructions = settings.nudgeInstructions;
 		if (enabled && !toolRegistered) {
 			pi.registerTool(
-				defineTool<typeof workingMemoryParameters, WorkingMemoryCheckpointDetailsV1>({
+				defineTool<typeof workingMemoryParameters, WorkingMemoryCheckpointDetailsV2>({
 					name: WORKING_MEMORY_TOOL,
 					label: WORKING_MEMORY_TOOL,
 					description: TOOL_DESCRIPTION,
@@ -99,8 +99,10 @@ export default function workingMemoryExtension(pi: ExtensionAPI): void {
 					promptGuidelines: [
 						"Use working_memory when stale evidence has accumulated or a memory reminder asks for reassessment; continue coherent exploration when current evidence remains useful.",
 						"A hidden working-memory reference catalog provides keep refs only for user messages and visible assistant text. Tool calls, tool results, hidden reasoning, and framework messages cannot be retained.",
-						"Outline files that remain in the repository working set, defer paths whose relevance is conditional, and discard exploration history after extracting its useful conclusions.",
-						"Everything before working_memory leaves future model context unless selected in keep. Put findings from tools, durable decisions, constraints, unresolved matters, and next action in continuation without duplicating retained messages.",
+						"Every checkpoint must retain at least one relevant referenced message. Keep task framing, constraints, decisions, and immediate work chain when needed; continuation and file tiers supplement retained conversation and cannot replace it.",
+						"Choose one file tier: readFiles auto-reads source into the next turn when its body is needed; outlineFiles carries symbols and locations for later scoped inspection; deferFiles records inactive conditional paths. Do not read a file merely to decide whether to outline it.",
+						"Choose readFiles instead of outlineFiles when next work will require the complete file. Do not list a path in more than one file tier.",
+						"Use continuation as a working note for resuming mid-task. Carry durable decisions, concrete findings, live reasoning, unresolved questions, remaining work, and next action in as much detail as needed to continue without rereading discarded results. Do not make it a user-facing status update or narrate the checkpoint.",
 					],
 					parameters: workingMemoryParameters,
 					executionMode: "sequential",
@@ -123,6 +125,7 @@ export default function workingMemoryExtension(pi: ExtensionAPI): void {
 							rowId: context.toolCallId,
 							invalidate: context.invalidate,
 							lastComponent: context.lastComponent,
+							executionStarted: context.executionStarted,
 						});
 					},
 					renderResult(result, options, theme, context) {

package/extensions/working-memory/memory.ts

@@ -64,7 +64,7 @@ export function collectPrunedRowIds(branch: readonly SessionEntry[], before: num
 			}
 			if (
 				message.role === "custom" &&
-				message.customType === "tau.explore.outline" &&
+				(message.customType === "tau.explore.outline" || message.customType === "tau.autoread") &&
 				isRecord(message.details) &&
 				typeof message.details.rowId === "string"
 			) {

package/extensions/working-memory/render.ts

@@ -99,15 +99,21 @@ export function renderWorkingMemoryCall(
 		rowId: string;
 		invalidate: () => void;
 		lastComponent: unknown;
+		executionStarted: boolean;
 	},
 ): Text {
 	context.rowState.watch(context.rowId, context.invalidate);
 	const component = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+	if (context.executionStarted) {
+		component.setText("");
+		return component;
+	}
 	const kept = Array.isArray(args.keep) ? args.keep.length : 0;
+	const read = Array.isArray(args.readFiles) ? args.readFiles.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`)}`,
+		`${formatToolRowTitle(context.rowState, context.rowId, "working_memory", theme)} ${theme.fg("muted", `${kept} kept · ${read} read · ${outlined} outline · ${deferred} deferred`)}`,
 	);
 	return component;
 }
@@ -128,12 +134,13 @@ export function renderWorkingMemoryResult(
 	}
 	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}`}`,
+		`Checkpoint · kept ${details.retainedRefs.length} · read ${details.readFiles.length} · outlined ${details.outlinedFiles.length} · deferred ${details.deferredFiles.length} · pruned ${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.readFiles.map((path) => `read: ${path}`),
 			...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}`),

package/extensions/working-memory/state.ts

@@ -14,12 +14,13 @@ export interface RetainedLabel {
 	preview: string;
 }
 
-export interface WorkingMemoryCheckpointDetailsV1 {
-	v: 1;
+export interface WorkingMemoryCheckpointDetailsV2 {
+	v: 2;
 	anchorToolCallId: string;
 	retainedRefs: string[];
 	retainedLabels: RetainedLabel[];
 	prunedRowIds: string[];
+	readFiles: string[];
 	outlinedFiles: Array<{ path: string; rowId: string }>;
 	deferredFiles: DeferredFile[];
 	removedUnits: number;
@@ -32,14 +33,15 @@ export interface ActiveWorkingMemoryState {
 	prunedRowIds: ReadonlySet<string>;
 }
 
-export function parseWorkingMemoryDetails(value: unknown): WorkingMemoryCheckpointDetailsV1 | undefined {
-	if (!isRecord(value) || value.v !== 1 || !nonempty(value.anchorToolCallId)) return undefined;
+export function parseWorkingMemoryDetails(value: unknown): WorkingMemoryCheckpointDetailsV2 | undefined {
+	if (!isRecord(value) || value.v !== 2 || !nonempty(value.anchorToolCallId)) return undefined;
 	const keys = [
 		"v",
 		"anchorToolCallId",
 		"retainedRefs",
 		"retainedLabels",
 		"prunedRowIds",
+		"readFiles",
 		"outlinedFiles",
 		"deferredFiles",
 		"removedUnits",
@@ -48,13 +50,16 @@ export function parseWorkingMemoryDetails(value: unknown): WorkingMemoryCheckpoi
 	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 readFiles = uniqueStrings(value.readFiles);
 	const warnings = strings(value.warnings);
 	const retainedLabels = parseRetainedLabels(value.retainedLabels);
 	const outlinedFiles = parseOutlinedFiles(value.outlinedFiles);
 	const deferredFiles = parseDeferredFiles(value.deferredFiles);
 	if (
 		!retainedRefs ||
+		retainedRefs.length === 0 ||
 		!prunedRowIds ||
+		!readFiles ||
 		!warnings ||
 		!retainedLabels ||
 		retainedLabels.length !== retainedRefs.length ||
@@ -67,11 +72,12 @@ export function parseWorkingMemoryDetails(value: unknown): WorkingMemoryCheckpoi
 		return undefined;
 	}
 	return {
-		v: 1,
+		v: 2,
 		anchorToolCallId: value.anchorToolCallId,
 		retainedRefs,
 		retainedLabels,
 		prunedRowIds,
+		readFiles,
 		outlinedFiles,
 		deferredFiles,
 		removedUnits: value.removedUnits as number,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shanepadgett/tau-agent",
-	"version": "0.31.1",
+	"version": "0.33.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.31.1",
+		"@shanepadgett/tau-tui": "0.33.0",
 		"@vscode/tree-sitter-wasm": "0.3.1",
 		"image-size": "2.0.2",
 		"smol-toml": "1.7.0",

package/shared/events.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ModelEffort } from "./model-effort.ts";
 import type { OutlineInjectionRequest, OutlineInjectionResponse } from "./outline-injection.js";
 import type { ToolRowVisualState } from "./tool-row-state.js";
 
@@ -46,6 +47,10 @@ export type TauAgentEvents = {
 		text?: string;
 		priority?: number;
 	};
+	"tau:model-effort.changed": {
+		effort: ModelEffort | undefined;
+	};
+	"tau:model-effort.snapshot.requested": Record<string, never>;
 	"tau:tool-row-state.set": {
 		rowId: string;
 		state?: ToolRowVisualState;

package/shared/model-effort.ts

@@ -0,0 +1,116 @@
+import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveCandidates } from "./model-fallback/index.ts";
+import type { ModelCandidate } from "./model-fallback/types.ts";
+
+export type ModelEffort = "low" | "medium" | "high";
+
+interface ModelPreference {
+	model: string;
+	reasoning: ThinkingLevel;
+}
+
+interface ProviderPreference {
+	provider: string;
+	models: readonly ModelPreference[];
+}
+
+export interface EffortProviderCandidates {
+	provider: string;
+	label: string;
+	candidates: ReadonlyArray<{
+		model: Model<Api>;
+		reasoning: ThinkingLevel;
+	}>;
+}
+
+const MODEL_PREFERENCES: Record<ModelEffort, readonly ProviderPreference[]> = {
+	low: [
+		{
+			provider: "openai-codex",
+			models: [
+				{ model: "gpt-5.6-luna", reasoning: "high" },
+				{ model: "gpt-5.5", reasoning: "low" },
+			],
+		},
+		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "medium" }] },
+		{ provider: "anthropic", models: [{ model: "claude-haiku-4-5", reasoning: "high" }] },
+	],
+	medium: [
+		{
+			provider: "openai-codex",
+			models: [
+				{ model: "gpt-5.6-terra", reasoning: "high" },
+				{ model: "gpt-5.5", reasoning: "medium" },
+			],
+		},
+		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "high" }] },
+		{ provider: "anthropic", models: [{ model: "claude-sonnet-5", reasoning: "high" }] },
+	],
+	high: [
+		{
+			provider: "openai-codex",
+			models: [
+				{ model: "gpt-5.6-sol", reasoning: "high" },
+				{ model: "gpt-5.5", reasoning: "high" },
+			],
+		},
+		{ provider: "xai", models: [{ model: "grok-4.5", reasoning: "high" }] },
+		{
+			provider: "anthropic",
+			models: [
+				{ model: "claude-opus-5", reasoning: "high" },
+				{ model: "claude-opus-4-8", reasoning: "high" },
+			],
+		},
+	],
+};
+
+export function effortForSelection(
+	provider: string | undefined,
+	model: string | undefined,
+	reasoning: string | undefined,
+): ModelEffort | undefined {
+	if (!provider || !model || !reasoning) return undefined;
+	for (const effort of ["high", "medium", "low"] as const) {
+		const preference = MODEL_PREFERENCES[effort].find((item) => item.provider === provider);
+		if (preference?.models.some((item) => item.model === model && item.reasoning === reasoning)) return effort;
+	}
+	return undefined;
+}
+
+export function resolveEffortProviders(
+	ctx: Pick<ExtensionContext, "modelRegistry">,
+	effort: ModelEffort,
+): EffortProviderCandidates[] {
+	const available = new Map(ctx.modelRegistry.getAvailable().map((model) => [`${model.provider}/${model.id}`, model]));
+	return MODEL_PREFERENCES[effort].flatMap((preference) => {
+		const candidates = preference.models.flatMap(({ model, reasoning }) => {
+			const availableModel = available.get(`${preference.provider}/${model}`);
+			return availableModel ? [{ model: availableModel, reasoning }] : [];
+		});
+		return candidates.length
+			? [
+					{
+						provider: preference.provider,
+						label: ctx.modelRegistry.getProviderDisplayName(preference.provider),
+						candidates,
+					},
+				]
+			: [];
+	});
+}
+
+export function resolveEffortCandidates(
+	ctx: Pick<ExtensionContext, "modelRegistry" | "model" | "cwd" | "isProjectTrusted">,
+	effort: ModelEffort,
+	includeParentModel: boolean,
+): Promise<ModelCandidate[]> {
+	return resolveCandidates(
+		ctx,
+		MODEL_PREFERENCES[effort].flatMap((preference) =>
+			preference.models.map((model) => ({ provider: preference.provider, ...model })),
+		),
+		includeParentModel,
+	);
+}

package/extensions/publish/README.md

@@ -1,13 +0,0 @@
-# Publish
-
-Create a tagged Tau release and monitor its GitHub Actions npm publish run.
-
-## Usage
-
-```text
-/publish
-```
-
-`/publish` requires a clean Git working tree, authenticated GitHub CLI, and public approved npm package sources. It recommends a semantic version bump from commits since the previous release tag, asks for confirmation, then pushes a release tag. GitHub Actions publishes the TUI package before the agent package through npm trusted publishing.
-
-If publishing fails, the agent runs read-only diagnostics and recommends a solution. It does not apply the fix or retry the release.