@shanepadgett/tau-agent 0.28.1 → 0.30.0

package/extensions/subagent/runtime.ts

@@ -1,5 +1,6 @@
 import type { Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { createIsolatedSessionResource, type IsolatedSessionResource } from "../../shared/isolated-session.ts";
 import type { AgentDefinition } from "./agents.ts";
 import { buildColdResumePrompt, retainSubagentTurn } from "./resume.ts";
 import {
@@ -15,7 +16,6 @@ import {
 	type SubagentPhase,
 	type SubagentThread,
 } from "./run.ts";
-import { createSubagentSessionResource, type SubagentSessionResource } from "./session-resource.ts";
 
 const MAX_RETAINED_THREADS = 16;
 const GLOBAL_CONCURRENCY = 4;
@@ -216,7 +216,7 @@ export class SubagentRuntime {
 		definition?: AgentDefinition;
 		ctx: ExtensionContext;
 		parentModel: string;
-		parentThinking: string;
+		parentThinking: NonNullable<ExtensionContext["thinkingLevel"]>;
 		signal?: AbortSignal;
 		onUpdate?: (details: SubagentDetails) => void | Promise<void>;
 		resolveFreshDefinition: () => Promise<
@@ -286,7 +286,7 @@ export class SubagentRuntime {
 			threadKey?: string;
 			ctx: ExtensionContext;
 			parentModel: string;
-			parentThinking: string;
+			parentThinking: NonNullable<ExtensionContext["thinkingLevel"]>;
 			definition?: AgentDefinition;
 			signal?: AbortSignal;
 			onUpdate?: (details: SubagentDetails) => void | Promise<void>;
@@ -316,7 +316,7 @@ export class SubagentRuntime {
 		let releaseGlobal: (() => void) | undefined;
 		let reservedThread: TrackedThread | undefined;
 		let provisionalThread: TrackedThread | undefined;
-		let provisionalResource: SubagentSessionResource | undefined;
+		let provisionalResource: IsolatedSessionResource | undefined;
 		let reservationToken: symbol | undefined;
 		let admitAdvanced = false;
 		let phase: SubagentPhase = "queue";
@@ -513,7 +513,7 @@ export class SubagentRuntime {
 				phase = "startup";
 				fanOut({ ...active.snapshot, status: "starting", phase: "startup", agent, threadId: thread.id }, true);
 				const oldResource = thread.resource;
-				provisionalResource = await createSubagentSessionResource(thread.sessionInputs, combined);
+				provisionalResource = await createIsolatedSessionResource(thread.sessionInputs, combined);
 				if (!this.isLive(generation, combined) || thread.disposed || this.threads.get(thread.id) !== thread) {
 					await provisionalResource.dispose();
 					provisionalResource = undefined;

package/extensions/subagent/session-resource.ts

@@ -1,12 +1,5 @@
-import {
-	createAgentSession,
-	DefaultResourceLoader,
-	getAgentDir,
-	ModelRuntime,
-	SessionManager,
-	type AgentSession,
-	type ExtensionContext,
-} from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveIsolatedSessionModel, type IsolatedSessionInputs } from "../../shared/isolated-session.ts";
 import type { AgentDefinition, ThinkingLevel } from "./agents.ts";
 
 const CHILD_UI_BLOCKED_METHODS = new Set([
@@ -18,25 +11,10 @@ const CHILD_UI_BLOCKED_METHODS = new Set([
 	"setWorkingIndicator",
 ]);
 
-type SelectedModel = NonNullable<ExtensionContext["model"]>;
-type SelectedProvider = NonNullable<ReturnType<ExtensionContext["modelRegistry"]["getProvider"]>>;
-
-export interface SubagentSessionInputs {
+export interface SubagentSessionInputs extends IsolatedSessionInputs {
 	definition: AgentDefinition;
-	extensionPaths: readonly string[];
-	cwd: string;
-	model: SelectedModel;
 	modelName: string;
-	provider: SelectedProvider;
-	runtimeApiKey: string | undefined;
 	thinkingLevel: ThinkingLevel;
-	bindTarget: { mode: "print" } | { mode: "tui"; uiContext: ExtensionContext["ui"] };
-}
-
-export interface SubagentSessionResource {
-	readonly inputs: SubagentSessionInputs;
-	readonly session: AgentSession;
-	dispose(): Promise<void>;
 }
 
 function childUiContext(ui: ExtensionContext["ui"]): ExtensionContext["ui"] {
@@ -53,117 +31,31 @@ export async function resolveSubagentSessionInputs(options: {
 	definition: AgentDefinition;
 	extensionPaths: readonly string[];
 	ctx: ExtensionContext;
-	parentThinkingLevel: string;
+	parentThinkingLevel: NonNullable<ExtensionContext["thinkingLevel"]>;
 	signal: AbortSignal;
 	onWarning?: (warning: string) => void;
 }): Promise<SubagentSessionInputs> {
 	const { definition, extensionPaths, ctx, signal, onWarning } = options;
-	let model = ctx.model;
-	let thinkingLevel = options.parentThinkingLevel as ThinkingLevel;
-	let selectedAuth: Awaited<ReturnType<ExtensionContext["modelRegistry"]["getApiKeyAndHeaders"]>> | undefined;
-	if (definition.model) {
-		const separator = definition.model.indexOf("/");
-		const configured = ctx.modelRegistry.find(
-			definition.model.slice(0, separator),
-			definition.model.slice(separator + 1),
-		);
-		if (!configured) onWarning?.(`model ${definition.model} is unavailable; using parent model`);
-		else {
-			const auth = await ctx.modelRegistry.getApiKeyAndHeaders(configured);
-			if (!auth.ok) onWarning?.(`model ${definition.model} is unavailable: ${auth.error}; using parent model`);
-			else {
-				model = configured;
-				selectedAuth = auth;
-			}
-		}
-	}
-	if (definition.thinking) {
-		const mapped = model?.thinkingLevelMap?.[definition.thinking];
-		const unsupported =
-			!model?.reasoning ||
-			mapped === null ||
-			((definition.thinking === "xhigh" || definition.thinking === "max") && mapped === undefined);
-		if (unsupported)
-			onWarning?.(`thinking ${definition.thinking} is unavailable for the selected model; using parent thinking`);
-		else thinkingLevel = definition.thinking;
-	}
-	if (!model) throw new Error(`Agent ${definition.name} startup failed: parent has no model`);
-	const auth = selectedAuth ?? (await ctx.modelRegistry.getApiKeyAndHeaders(model));
-	if (!auth.ok) throw new Error(`Agent ${definition.name} startup failed: ${auth.error}`);
-	const provider = ctx.modelRegistry.getProvider(model.provider);
-	if (!provider) throw new Error(`Agent ${definition.name} startup failed: provider ${model.provider} is unavailable`);
-	if (signal.aborted) throw new Error(`Agent ${definition.name} startup aborted`);
+	const selected = await resolveIsolatedSessionModel({
+		label: `Agent ${definition.name}`,
+		preferredModel: definition.model,
+		preferredThinkingLevel: definition.thinking,
+		usePreferredThinkingAfterModelFallback: true,
+		ctx,
+		parentThinkingLevel: options.parentThinkingLevel,
+		signal,
+		...(onWarning === undefined ? {} : { onWarning }),
+	});
 	return {
+		...selected,
+		label: `Agent ${definition.name}`,
 		definition,
 		extensionPaths: [...extensionPaths],
 		cwd: ctx.cwd,
-		model,
-		modelName: `${model.provider}/${model.id}`,
-		provider,
-		runtimeApiKey:
-			auth.apiKey && provider.auth.apiKey && !ctx.modelRegistry.isUsingOAuth(model) ? auth.apiKey : undefined,
-		thinkingLevel,
+		modelName: `${selected.model.provider}/${selected.model.id}`,
+		tools: definition.tools,
+		customTools: [],
 		bindTarget:
 			ctx.mode === "tui" && ctx.hasUI ? { mode: "tui", uiContext: childUiContext(ctx.ui) } : { mode: "print" },
 	};
 }
-
-export async function createSubagentSessionResource(
-	inputs: SubagentSessionInputs,
-	signal: AbortSignal,
-): Promise<SubagentSessionResource> {
-	let session: AgentSession | undefined;
-	try {
-		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
-		const modelRuntime = await ModelRuntime.create();
-		modelRuntime.registerNativeProvider(inputs.provider);
-		if (inputs.runtimeApiKey !== undefined)
-			await modelRuntime.setRuntimeApiKey(inputs.model.provider, inputs.runtimeApiKey, { allowNetwork: false });
-		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
-		const resourceLoader = new DefaultResourceLoader({
-			cwd: inputs.cwd,
-			agentDir: getAgentDir(),
-			noExtensions: true,
-			additionalExtensionPaths: [...inputs.extensionPaths],
-		});
-		await resourceLoader.reload();
-		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
-		const created = await createAgentSession({
-			cwd: inputs.cwd,
-			model: inputs.model,
-			modelRuntime,
-			thinkingLevel: inputs.thinkingLevel,
-			tools: inputs.definition.tools,
-			excludeTools: ["subagent"],
-			resourceLoader,
-			sessionManager: SessionManager.inMemory(inputs.cwd),
-		});
-		session = created.session;
-		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
-		await session.bindExtensions(inputs.bindTarget);
-		if (signal.aborted) throw new Error(`Agent ${inputs.definition.name} startup aborted`);
-		const active = session.getActiveToolNames().sort();
-		const expected = [...inputs.definition.tools].sort();
-		if (active.join("\0") !== expected.join("\0") || active.includes("subagent")) {
-			const missing = expected.filter((tool) => !active.includes(tool));
-			throw new Error(
-				`Agent ${inputs.definition.name} startup failed: unavailable tools: ${missing.join(", ") || "active tool mismatch"}`,
-			);
-		}
-		let disposed = false;
-		return {
-			inputs,
-			session,
-			async dispose() {
-				if (disposed) return;
-				disposed = true;
-				if (session?.isStreaming) await session.abort().catch(() => undefined);
-				session?.dispose();
-			},
-		};
-	} catch (error) {
-		if (session?.isStreaming) await session.abort().catch(() => undefined);
-		session?.dispose();
-		throw error;
-	}
-}

package/extensions/subagent/settings.ts

@@ -0,0 +1,18 @@
+import { Type } from "typebox";
+import { defineTauExtensionSettings } from "../../shared/settings/define.ts";
+
+export default defineTauExtensionSettings({
+	key: "subagent",
+	defaults: { disabled: [] as string[] },
+	schema: Type.Object(
+		{
+			disabled: Type.Optional(
+				Type.Array(Type.String({ minLength: 1 }), {
+					default: [],
+					description: "Agent names unavailable for delegation.",
+				}),
+			),
+		},
+		{ additionalProperties: false },
+	),
+});

package/extensions/tau-help/help.md

@@ -32,11 +32,11 @@ 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` or `/context-sync <nudge>` for human-driven catalog sync (optional nudge). Escape cancels a running manual sync. When `sync.automation` is on, the coding agent can also run the `context-sync` subagent after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is the master switch for command, automation, and validation auto-run. Entry `files` are autoread; entry `anchors` are unloaded navigation paths. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
+Adds `/context` to set branch-local reusable repository work scopes from `.pi/contexts`, and `/context-sync` or `/context-sync <nudge>` for human-driven catalog sync. Active entries produce one ephemeral per-call projection instead of transcript messages. Entry `read` paths supply exact contents, `outline` paths use Explore, and `references` stay unloaded. Clear all selections and confirm to remove active context. Escape cancels a running manual sync. When `sync.automation` is on, coding agent can also run `context-sync` after meaningful uncommitted work. Sync catalogs durable code and long-lived documentation; recurring scratch, planning, interview, and rough-idea paths belong in `validation.ignoreGlobs`. `sync.enabled` is master switch for command, automation, and validation auto-run. Context validation is off by default; when on (and sync enabled), Tau auto-runs context-sync on failure. Folder names are tabs, TOML files are concepts, and TOML sections are selectable entries.
 
-## context-pruning
+## working-memory
 
-Gives the agent `context_prune` for creating a hard context checkpoint after broad exploration converges. Everything before the checkpoint leaves future model input unless the agent retains an exact tool exchange or carries a file forward as a fresh snapshot. File snapshot failures are reported without blocking the checkpoint. Deferred files remain as a small conditional note. Context markers use an ordered instruction ladder that escalates from informational guidance to pruning before further tool work. Run `/prune` with no arguments to request a checkpoint manually. Session history remains unchanged, and checkpoints, markers, and pruned-row state follow the active branch.
+Gives agent `working_memory` for selective hard checkpoints. Model-only references identify useful conversation evidence and complete tool exchanges. Requested source files return as structural outlines, while deferred files remain cheap conditional reminders. Everything else before checkpoint leaves future model input without changing saved session. Advisory reminders begin at 40k active-context tokens. Run `/prune` to request reassessment manually.
 
 ## explore
 
@@ -74,6 +74,10 @@ Adds `/publish` to create a tagged release, trigger trusted npm publishing in Gi
 
 Adds `/qna` for when the agent has asked you several questions in chat and you want a friendly UI for answering them on your own terms. It is only active when you manually run the command.
 
+## review
+
+Adds `/review` for explicit isolated review of current Git changes. Choose `simplify`, `architecture`, or `correctness`, or run a mode directly. Results stay outside agent context until you send them from result view, and can be exported under `.pi/tau/reviews/`. `/review show` reopens latest result on current session branch.
+
 ## reference
 
 Adds `/reference` to manage separate repositories kept outside the current project for inspiration or comparison. Add one with `/reference new <git-url>`, update it, switch its referenced branch, or open it in an editor. Select references and explain why they matter; Tau then puts their paths and that reason into the editor for the agent. References stay outside the project so the agent does not wander into unrelated code unless you explicitly point it there.
@@ -86,6 +90,10 @@ Shows a compact display-only marker after each run with wall time and model cost
 
 Supplies the agent with the current local date and an initial root directory snapshot as hidden session context.
 
+## script-runner
+
+Gives the agent a first-class `script_runner` tool to execute Python and TypeScript instead of bash. On failure it returns a `scriptId`; the agent retries with targeted `{oldText,newText}` edits against the script it already wrote rather than resending the whole script. Languages are detected from the environment (Python via `python3`/`python`; TypeScript via Node `--experimental-strip-types`, Node 22.6+). The tool registers only available languages and is hidden from the prompt if neither is present.
+
 ## silent-command-runner
 
 Runs configured commands while keeping their output out of agent context when that is useful.
@@ -100,7 +108,7 @@ Adds `Alt+S` to stash the current prompt draft and `/pop` to browse stashed draf
 
 ## subagent
 
-Gives Tau a subagent delegation tool for isolated, focused work. The built-in `review` agent performs adversarial, read-only code reviews; `scout` finds local files, symbols, data flow, constraints, and unknowns without changing anything; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in the supported subagent directories. Ask Tau how to do it and have it consult the extension’s own documentation; the built-in agents show the pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after the active cohort finishes.
+Gives Tau a subagent delegation tool for isolated, focused work. Run `/agents` to enable or disable individual agents for the current session, or set `extensions.subagent.disabled` in Tau settings for a persistent choice. `scout` is substantial multi-hop local code lookup that would chew parent context; facts only, not small digs; `web-research` handles external research. Known files can be autoread as line-numbered snapshots into a fresh or retained child turn. Tau can continue a retained child thread when follow-up work depends on its prior reads and reasoning. You can also create your own subagents in supported subagent directories. Ask Tau how to do it and have it consult extension documentation; built-in agents show pattern. Each subagent can register its own model, tools, and pool of display names. Reused pool names get numeric suffixes. In interactive cmux sessions, Tau opens one temporary Markdown dashboard for live subagent progress; it does not change how children run and closes shortly after active cohort finishes.
 
 ## tau-help
 
@@ -114,10 +122,6 @@ Adds `/tau`, `/tau init [--global|--project]`, and `/tau doctor` for Tau setup a
 
 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 `websearch`, `webfetch`, and `codesearch` tools for web and implementation research.

package/extensions/working-memory/README.md

@@ -0,0 +1,9 @@
+# Working Memory
+
+Working Memory gives agent selective checkpoints without changing saved conversation.
+
+`working_memory` keeps referenced conversation evidence and complete tool exchanges, carries requested source files as structural outlines, and records deferred files as conditional reminders. Everything else before checkpoint leaves future model context.
+
+Automatic reminders begin at 40,000 active-context tokens and remain advisory. Run `/prune` to request reassessment manually.
+
+Settings live under `extensions.workingMemory`.

package/extensions/working-memory/checkpoint.ts

@@ -0,0 +1,175 @@
+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 { requestOutlineInjections, type PreparedOutlineInjection } from "../../shared/outline-injection.ts";
+import { buildMemoryCatalog } from "./memory.ts";
+import { WORKING_MEMORY_TOOL, type DeferredFile, type WorkingMemoryCheckpointDetailsV1 } 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 }),
+		deferFiles: Type.Array(
+			Type.Object(
+				{
+					path: PATH,
+					reason: Type.String({ minLength: 1, maxLength: 300, pattern: "\\S" }),
+					relevantWhen: Type.String({ minLength: 1, maxLength: 300, pattern: "\\S" }),
+				},
+				{ additionalProperties: false },
+			),
+			{ maxItems: 8 },
+		),
+	},
+	{ additionalProperties: false },
+);
+
+export type WorkingMemoryInput = Static<typeof workingMemoryParameters>;
+
+interface ExecuteWorkingMemoryOptions {
+	pi: Pick<ExtensionAPI, "events">;
+	toolCallId: string;
+	params: WorkingMemoryInput;
+	signal: AbortSignal | undefined;
+	ctx: ExtensionContext;
+	generation: number;
+	currentGeneration(): number;
+}
+
+export interface WorkingMemoryExecution {
+	result: {
+		content: Array<{ type: "text"; text: string }>;
+		details: WorkingMemoryCheckpointDetailsV1;
+	};
+	outlines: PreparedOutlineInjection[];
+}
+
+export async function executeWorkingMemory(options: ExecuteWorkingMemoryOptions): Promise<WorkingMemoryExecution> {
+	assertCurrent(options);
+	const branch = options.ctx.sessionManager.getBranch();
+	const catalog = buildMemoryCatalog(branch);
+	const requestedRefs = [...new Set(options.params.keep)];
+	const retained = requestedRefs
+		.flatMap((ref) => {
+			const unit = catalog.get(ref);
+			return unit ? [unit] : [];
+		})
+		.sort((left, right) => left.order - right.order || left.suborder - right.suborder);
+	const retainedRefs = retained.map((unit) => unit.ref);
+	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 outlineResponse = await requestOutlineInjections(options.pi, {
+		cwd: options.ctx.cwd,
+		batchId: options.toolCallId,
+		paths: outlinePaths,
+		signal: options.signal,
+		isLifecycleCurrent: () => options.generation === options.currentGeneration(),
+	});
+	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 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;
+		deferredKeys.add(key);
+		deferredFiles.push({ path, reason: file.reason.trim(), relevantWhen: file.relevantWhen.trim() });
+	}
+
+	const anchorIndex = findAnchorEntry(branch, options.toolCallId);
+	const retainedSet = new Set(retainedRefs);
+	const preAnchorUnits = [...catalog.values()].filter((unit) => unit.order < anchorIndex);
+	const prunedRowIds = [...new Set(preAnchorUnits.flatMap((unit) => (retainedSet.has(unit.ref) ? [] : unit.rowIds)))];
+	const details: WorkingMemoryCheckpointDetailsV1 = {
+		v: 1,
+		anchorToolCallId: options.toolCallId,
+		retainedRefs,
+		retainedLabels: retained.map((unit) => ({ ref: unit.ref, label: unit.label, preview: unit.preview })),
+		prunedRowIds,
+		outlinedFiles: outlineResponse.messages.map((message) => ({
+			path: message.details.path,
+			rowId: message.details.rowId,
+		})),
+		deferredFiles,
+		removedUnits: Math.max(0, preAnchorUnits.length - retained.length),
+		warnings,
+	};
+	const markdown = formatResult(options.params.continuation.trim(), deferredFiles, warnings);
+	return {
+		result: { content: [{ type: "text", text: truncateBoundedHead(markdown).content }], details },
+		outlines: outlineResponse.messages,
+	};
+}
+
+function formatResult(continuation: string, deferred: readonly DeferredFile[], warnings: readonly string[]): string {
+	const sections = [`## Continue\n\n${continuation}`];
+	if (deferred.length > 0) {
+		sections.push(
+			`## Deferred files\n\n${deferred
+				.map((file) => `- \`${escapeCode(file.path)}\` — ${file.reason} Reconsider when: ${file.relevantWhen}.`)
+				.join("\n")}`,
+		);
+	}
+	if (warnings.length > 0) sections.push(`## Warnings\n\n${warnings.map((warning) => `- ${warning}`).join("\n")}`);
+	return sections.join("\n\n");
+}
+
+function dedupePaths(paths: readonly string[], cwd: string): string[] {
+	const keys = new Set<string>();
+	const result: string[] = [];
+	for (const raw of paths) {
+		const path = normalizePath(raw);
+		const key = resolve(cwd, path);
+		if (keys.has(key)) continue;
+		keys.add(key);
+		result.push(path);
+	}
+	return result;
+}
+
+function findAnchorEntry(branch: readonly SessionEntry[], toolCallId: string): number {
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index];
+		if (
+			entry?.type === "message" &&
+			entry.message.role === "assistant" &&
+			entry.message.content.some(
+				(block) => block.type === "toolCall" && block.id === toolCallId && block.name === WORKING_MEMORY_TOOL,
+			)
+		) {
+			return index;
+		}
+	}
+	return -1;
+}
+
+function normalizePath(path: string): string {
+	return path.trim().replace(/^@/, "");
+}
+
+function escapeCode(path: string): string {
+	return path.replaceAll("`", "\\`");
+}
+
+function boundedWarning(warning: string): string {
+	return warning.length <= 500 ? warning : `${warning.slice(0, 499)}…`;
+}
+
+function assertCurrent(options: ExecuteWorkingMemoryOptions): void {
+	options.signal?.throwIfAborted();
+	if (options.generation !== options.currentGeneration()) {
+		throw new Error("Working-memory checkpoint crossed a session lifecycle boundary");
+	}
+}