@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/tools/tasks.ts

@@ -7,8 +7,9 @@ import {
 	type TaskBoardTask,
 	taskBoardCounts,
 } from "../domains/session/task-board.js";
+import type { UserTask, UserTasksStore } from "../domains/user-tasks/store.js";
+import { StringEnum } from "../engine/ai.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
-import { stringEnum } from "./string-enum.js";
 
 /**
  * The tasks tool: the session task board. The agent declares what it is
@@ -23,7 +24,7 @@ import { stringEnum } from "./string-enum.js";
  * track it across turns.
  */
 
-const TASKS_ACTIONS = ["plan", "add", "start", "done", "block", "drop", "list"] as const;
+const TASKS_ACTIONS = ["plan", "add", "pick", "start", "done", "block", "drop", "list"] as const;
 type TasksAction = (typeof TASKS_ACTIONS)[number];
 
 /** Plain-text status markers for model-facing output; the TUI owns glyphs. */
@@ -37,9 +38,20 @@ const STATUS_MARK: Record<TaskBoardTask["status"], string> = {
 
 export interface TasksToolDeps {
 	board: TaskBoardStore;
+	userTasks?: UserTasksStore;
+	getSessionId?: () => string | null;
 }
 
-function renderTaskBoardText(board: TaskBoardSnapshot): string {
+function waitingTrailer(tasks: ReadonlyArray<UserTask>): string[] {
+	return tasks
+		.filter((task) => task.status === "open" || task.status === "handed")
+		.map(
+			(task) =>
+				`operator tasks waiting: ${task.id} ${JSON.stringify(task.title)} — pick up with action="pick" id="${task.id}"`,
+		);
+}
+
+function renderTaskBoardText(board: TaskBoardSnapshot, userTasks: ReadonlyArray<UserTask> = []): string {
 	const counts = taskBoardCounts(board);
 	const lines: string[] = [`board "${board.title}" ${counts.completed}/${counts.total} done`];
 	for (const task of board.tasks) {
@@ -52,6 +64,7 @@ function renderTaskBoardText(board: TaskBoardSnapshot): string {
 	if (counts.open > 0 && counts.active === 0) {
 		lines.push(`next: start a task with action="start" before working it`);
 	}
+	lines.push(...waitingTrailer(userTasks));
 	return lines.join("\n");
 }
 
@@ -60,6 +73,7 @@ function boardDetails(action: TasksAction, board: TaskBoardSnapshot | null): Rec
 	const counts = taskBoardCounts(board);
 	return {
 		action,
+		boardId: board.boardId,
 		title: board.title,
 		counts,
 		tasks: board.tasks.map((task) => ({ ...task })),
@@ -87,6 +101,8 @@ function mutationFromArgs(action: TasksAction, args: Record<string, unknown>): T
 		}
 		case "add":
 			return { op: "add", tasks: taskTitlesArg(args) };
+		case "pick":
+			return { error: "pick is resolved from the durable operator task inbox" };
 		case "start":
 		case "done":
 		case "block":
@@ -105,18 +121,32 @@ function mutationFromArgs(action: TasksAction, args: Record<string, unknown>): T
 }
 
 export function createTasksTool(deps: TasksToolDeps): ToolSpec {
+	const reconcileUserTasks = (): ReadonlyArray<UserTask> => {
+		if (!deps.userTasks) return [];
+		const sessionId = deps.getSessionId?.();
+		if (!sessionId) return deps.userTasks.snapshot();
+		const links =
+			deps.board
+				.snapshot()
+				?.tasks.flatMap((task) =>
+					task.userTaskId ? [{ userTaskId: task.userTaskId, boardTaskId: task.id, status: task.status }] : [],
+				) ?? [];
+		return deps.userTasks.reconcile(links, sessionId);
+	};
+
 	return {
 		name: ToolNames.Tasks,
 		description:
 			"Session task board. plan declares a titled board (replaces any prior board); add appends tasks; " +
-			"start marks one task active (the current focus); done completes a started task and requires note as the " +
+			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
+			"done completes a started task and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
 			"Work that did not happen is blocked or dropped, never done.",
 		parameters: Type.Object({
-			action: stringEnum(TASKS_ACTIONS, "Board action."),
+			action: StringEnum(TASKS_ACTIONS, { description: "Board action." }),
 			title: Type.Optional(Type.String({ description: "Board title (plan)." })),
 			tasks: Type.Optional(Type.Array(Type.String(), { description: "Task titles (plan, add)." })),
-			id: Type.Optional(Type.String({ description: 'Task id like "t2" (start, done, block, drop).' })),
+			id: Type.Optional(Type.String({ description: 'Task id like "t2", or operator id "u2" for pick.' })),
 			note: Type.Optional(
 				Type.String({ description: "Evidence of completion (required for done) or the reason (block, drop)." }),
 			),
@@ -127,8 +157,11 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			const prepared = { ...args };
 			// Weak-model shapes: a numeric or bare-number id becomes "tN", and a
 			// JSON-string tasks array is parsed back into a real array.
-			if (typeof prepared.id === "number" && Number.isFinite(prepared.id)) prepared.id = `t${prepared.id}`;
-			if (typeof prepared.id === "string" && /^\d+$/.test(prepared.id.trim())) prepared.id = `t${prepared.id.trim()}`;
+			const idPrefix = prepared.action === "pick" ? "u" : "t";
+			if (typeof prepared.id === "number" && Number.isFinite(prepared.id)) prepared.id = `${idPrefix}${prepared.id}`;
+			if (typeof prepared.id === "string" && /^\d+$/.test(prepared.id.trim())) {
+				prepared.id = `${idPrefix}${prepared.id.trim()}`;
+			}
 			if (typeof prepared.tasks === "string" && prepared.tasks.trim().startsWith("[")) {
 				try {
 					const parsed = JSON.parse(prepared.tasks);
@@ -145,23 +178,87 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 				return { kind: "error", message: `tasks: action must be one of ${TASKS_ACTIONS.join(", ")}; got '${action}'` };
 			}
 			const typedAction = action as TasksAction;
+			let userTasks: ReadonlyArray<UserTask>;
+			try {
+				userTasks = reconcileUserTasks();
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				return { kind: "error", message: `tasks: could not reconcile the operator task inbox: ${message}` };
+			}
 			if (typedAction === "list") {
 				const board = deps.board.snapshot();
 				if (!board) {
+					const output = ['no task board yet; declare one with action="plan"', ...waitingTrailer(userTasks)].join("\n");
 					return {
 						kind: "ok",
-						output: 'no task board yet; declare one with action="plan"',
+						output,
 						details: boardDetails("list", null),
 					};
 				}
-				return { kind: "ok", output: renderTaskBoardText(board), details: boardDetails("list", board) };
+				return { kind: "ok", output: renderTaskBoardText(board, userTasks), details: boardDetails("list", board) };
 			}
+			if (typedAction === "pick") {
+				if (!deps.userTasks) return { kind: "error", message: "tasks: operator task inbox is unavailable" };
+				const sessionId = deps.getSessionId?.();
+				if (!sessionId) return { kind: "error", message: "tasks: pick requires an active session" };
+				const id = stringArg(args, "id");
+				if (!id || !/^u[1-9]\d*$/.test(id)) {
+					return { kind: "error", message: 'tasks: pick requires an operator task id (e.g. id="u3")' };
+				}
+				const userTask = userTasks.find((task) => task.id === id);
+				if (!userTask) return { kind: "error", message: `tasks: operator task ${id} was not found` };
+				if (userTask.status !== "open" && userTask.status !== "handed") {
+					return { kind: "error", message: `tasks: operator task ${id} is ${userTask.status}; it cannot be picked` };
+				}
+				const result = deps.board.apply({ op: "pick", title: userTask.title, userTaskId: userTask.id });
+				if (!result.ok) return { kind: "error", message: `tasks: ${result.message}` };
+				const picked = result.board.tasks.find((task) => task.userTaskId === userTask.id && task.status === "pending");
+				if (!picked) return { kind: "error", message: `tasks: durable pickup for ${id} did not produce a board row` };
+				try {
+					deps.userTasks.recordPicked(userTask.id, sessionId, picked.id);
+					userTasks = deps.userTasks.snapshot();
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return {
+						kind: "error",
+						message: `tasks: ${picked.id} durably picked up ${id}, but the operator inbox update failed: ${message}`,
+						details: boardDetails("pick", result.board),
+					};
+				}
+				return {
+					kind: "ok",
+					output: renderTaskBoardText(result.board, userTasks),
+					details: boardDetails("pick", result.board),
+				};
+			}
+			const before = deps.board.snapshot();
 			const mutation = mutationFromArgs(typedAction, args);
 			if ("error" in mutation) return { kind: "error", message: mutation.error };
+			const completedUserTask =
+				typedAction === "done" && mutation.op === "done"
+					? before?.tasks.find((task) => task.id === mutation.id && task.userTaskId)
+					: undefined;
+			const completionSessionId = completedUserTask?.userTaskId && deps.userTasks ? deps.getSessionId?.() : undefined;
+			if (completedUserTask?.userTaskId && deps.userTasks && !completionSessionId) {
+				return { kind: "error", message: "tasks: durable completion requires an active session" };
+			}
 			const result = deps.board.apply(mutation);
 			if (!result.ok) return { kind: "error", message: `tasks: ${result.message}` };
+			if (completedUserTask?.userTaskId && deps.userTasks && completionSessionId) {
+				try {
+					deps.userTasks.recordDone(completedUserTask.userTaskId, completionSessionId, completedUserTask.id);
+					userTasks = deps.userTasks.snapshot();
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					return {
+						kind: "error",
+						message: `tasks: ${completedUserTask.id} completed durably, but operator task ${completedUserTask.userTaskId} could not be updated: ${message}`,
+						details: boardDetails("done", result.board),
+					};
+				}
+			}
 			const noteLines = result.notes.map((note) => `note: ${note}`);
-			const output = [...noteLines, renderTaskBoardText(result.board)].join("\n");
+			const output = [...noteLines, renderTaskBoardText(result.board, userTasks)].join("\n");
 			return { kind: "ok", output, details: boardDetails(typedAction, result.board) };
 		},
 	};

package/src/tools/truncate.ts

@@ -1,38 +1,25 @@
-// Per-observation source cap. One tool result must stay proportional to the
-// question asked: ~16k chars ≈ 4k tokens, enough to read a typical source file
-// or doc section in one call while a local backend still prefills it quickly.
-// Truncated output always says how to continue (offset/limit or a narrower
-// query), so larger requests cost extra calls, not a blown context. The
-// per-turn observation budget (see read.ts) bounds how much these calls add up
-// to within a single turn.
+import {
+	formatSize,
+	GREP_MAX_LINE_LENGTH,
+	type TruncationOptions,
+	type TruncationResult,
+	truncateLine,
+	truncateHead as truncatePiHead,
+	truncateTail as truncatePiTail,
+} from "../engine/truncate.js";
+
+// Per-observation source cap. Pi defaults to 50 KiB; Clio deliberately keeps
+// one result proportional to its per-turn observation budget at 16 KiB. The
+// wrappers below retain only that product-level delta while Pi owns UTF-8-safe
+// head/tail truncation, line limits, grep-line clipping, and size formatting.
 export const DEFAULT_MAX_LINES = 2000;
 export const DEFAULT_MAX_BYTES = 16 * 1024;
-export const GREP_MAX_LINE_LENGTH = 500;
+export type { TruncationResult };
+export { formatSize, GREP_MAX_LINE_LENGTH, truncateLine };
 
-export interface TruncationResult {
-	content: string;
-	truncated: boolean;
-	truncatedBy: "lines" | "bytes" | null;
-	totalLines: number;
-	totalBytes: number;
-	outputLines: number;
-	outputBytes: number;
-	lastLinePartial: boolean;
-	firstLineExceedsLimit: boolean;
-	maxLines: number;
-	maxBytes: number;
-}
-
-export interface TruncationOptions {
-	maxLines?: number;
-	maxBytes?: number;
-}
-
-// Count lines without a trailing-newline phantom entry. `"a\nb\n".split("\n")`
-// yields `["a","b",""]` (3 entries) for a 2-line file; dropping the final empty
-// element restores an honest count so continuation notices ("N more lines") do
-// not over-report by one on newline-terminated files. Ported from pi's
-// truncate.ts:47.
+// Count lines without a trailing-newline phantom entry. Pi uses the same
+// counting rule internally but does not export it; Clio's read continuation
+// notices need the total before selecting a slice.
 export function splitLinesForCounting(content: string): string[] {
 	if (content.length === 0) return [];
 	const lines = content.split("\n");
@@ -40,163 +27,17 @@ export function splitLinesForCounting(content: string): string[] {
 	return lines;
 }
 
-export function formatSize(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
-export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
-	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
-	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-	const totalBytes = Buffer.byteLength(content, "utf8");
-	const lines = splitLinesForCounting(content);
-	const totalLines = lines.length;
-
-	if (totalLines <= maxLines && totalBytes <= maxBytes) {
-		return {
-			content,
-			truncated: false,
-			truncatedBy: null,
-			totalLines,
-			totalBytes,
-			outputLines: totalLines,
-			outputBytes: totalBytes,
-			lastLinePartial: false,
-			firstLineExceedsLimit: false,
-			maxLines,
-			maxBytes,
-		};
-	}
-
-	const firstLineBytes = Buffer.byteLength(lines[0] ?? "", "utf8");
-	if (firstLineBytes > maxBytes) {
-		return {
-			content: "",
-			truncated: true,
-			truncatedBy: "bytes",
-			totalLines,
-			totalBytes,
-			outputLines: 0,
-			outputBytes: 0,
-			lastLinePartial: false,
-			firstLineExceedsLimit: true,
-			maxLines,
-			maxBytes,
-		};
-	}
-
-	const out: string[] = [];
-	let outputBytes = 0;
-	let truncatedBy: "lines" | "bytes" = "lines";
-	for (let i = 0; i < lines.length && i < maxLines; i += 1) {
-		const line = lines[i] ?? "";
-		const lineBytes = Buffer.byteLength(line, "utf8") + (i > 0 ? 1 : 0);
-		if (outputBytes + lineBytes > maxBytes) {
-			truncatedBy = "bytes";
-			break;
-		}
-		out.push(line);
-		outputBytes += lineBytes;
-	}
-	if (out.length >= maxLines && outputBytes <= maxBytes) truncatedBy = "lines";
-	const output = out.join("\n");
+function withClioDefaults(options: TruncationOptions): Required<TruncationOptions> {
 	return {
-		content: output,
-		truncated: true,
-		truncatedBy,
-		totalLines,
-		totalBytes,
-		outputLines: out.length,
-		outputBytes: Buffer.byteLength(output, "utf8"),
-		lastLinePartial: false,
-		firstLineExceedsLimit: false,
-		maxLines,
-		maxBytes,
+		maxLines: options.maxLines ?? DEFAULT_MAX_LINES,
+		maxBytes: options.maxBytes ?? DEFAULT_MAX_BYTES,
 	};
 }
 
-// Keep the tail of a UTF-8 string within a byte budget, cutting at a valid
-// character boundary. Used when the last line alone exceeds the byte cap.
-function truncateStringToBytesFromEnd(str: string, maxBytes: number): string {
-	const buf = Buffer.from(str, "utf8");
-	if (buf.length <= maxBytes) return str;
-	let start = buf.length - maxBytes;
-	while (start < buf.length && ((buf[start] ?? 0) & 0xc0) === 0x80) start += 1;
-	return buf.subarray(start).toString("utf8");
+export function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {
+	return truncatePiHead(content, withClioDefaults(options));
 }
 
-// Keep the LAST N lines / bytes (whichever cap is hit first). Suitable for
-// shell/build/test output where the failing assertion, compiler error, and
-// exit summary live at the end. Ported from pi's truncate.ts:168, including the
-// partial-last-line edge case: when the final line alone exceeds maxBytes, the
-// end of that line is kept and lastLinePartial is set.
 export function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {
-	const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
-	const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
-	const totalBytes = Buffer.byteLength(content, "utf8");
-	const lines = splitLinesForCounting(content);
-	const totalLines = lines.length;
-
-	if (totalLines <= maxLines && totalBytes <= maxBytes) {
-		return {
-			content,
-			truncated: false,
-			truncatedBy: null,
-			totalLines,
-			totalBytes,
-			outputLines: totalLines,
-			outputBytes: totalBytes,
-			lastLinePartial: false,
-			firstLineExceedsLimit: false,
-			maxLines,
-			maxBytes,
-		};
-	}
-
-	const out: string[] = [];
-	let outputBytes = 0;
-	let truncatedBy: "lines" | "bytes" = "lines";
-	let lastLinePartial = false;
-	for (let i = lines.length - 1; i >= 0 && out.length < maxLines; i -= 1) {
-		const line = lines[i] ?? "";
-		const lineBytes = Buffer.byteLength(line, "utf8") + (out.length > 0 ? 1 : 0);
-		if (outputBytes + lineBytes > maxBytes) {
-			truncatedBy = "bytes";
-			// The final line alone overflows the budget: keep its tail so the
-			// last bytes (the exit summary) are still shown, flagged partial.
-			if (out.length === 0) {
-				const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
-				out.unshift(truncatedLine);
-				outputBytes = Buffer.byteLength(truncatedLine, "utf8");
-				lastLinePartial = true;
-			}
-			break;
-		}
-		out.unshift(line);
-		outputBytes += lineBytes;
-	}
-	if (out.length >= maxLines && outputBytes <= maxBytes) truncatedBy = "lines";
-	const output = out.join("\n");
-	return {
-		content: output,
-		truncated: true,
-		truncatedBy,
-		totalLines,
-		totalBytes,
-		outputLines: out.length,
-		outputBytes: Buffer.byteLength(output, "utf8"),
-		lastLinePartial,
-		firstLineExceedsLimit: false,
-		maxLines,
-		maxBytes,
-	};
-}
-
-export function truncateLine(
-	line: string,
-	maxChars: number = GREP_MAX_LINE_LENGTH,
-): { text: string; wasTruncated: boolean } {
-	if (line.length <= maxChars) return { text: line, wasTruncated: false };
-	return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
+	return truncatePiTail(content, withClioDefaults(options));
 }

package/src/tools/verify/frontend.ts

@@ -9,8 +9,10 @@ import { resolveReadPath } from "../path-utils.js";
 import type { ToolResult, ToolResultDetails } from "../registry.js";
 import { maxOutputArg, timeoutArg } from "../safe-exec.js";
 import { truncateUtf8 } from "../truncate-utf8.js";
+import { BROWSER_MODES } from "./surface.js";
+
+export { BROWSER_MODES } from "./surface.js";
 
-export const BROWSER_MODES = ["auto", "required", "off"] as const;
 type BrowserMode = (typeof BROWSER_MODES)[number];
 
 type CheckStatus = "pass" | "warn" | "fail" | "skip";

package/src/tools/verify/index.ts

@@ -1,10 +1,8 @@
-import { Type } from "typebox";
-import { ToolNames } from "../../core/tool-names.js";
 import { isVerificationScriptName } from "../../core/verification-scripts.js";
 import type { ToolResult, ToolSpec } from "../registry.js";
-import { stringEnum } from "../string-enum.js";
-import { BROWSER_MODES, runFrontendCheck } from "./frontend.js";
+import { runFrontendCheck } from "./frontend.js";
 import { listChecks, runScriptCheck, VERIFICATION_SCRIPT_FAMILY_HINT } from "./scripts.js";
+import { prepareVerifyArguments, verifyToolSurface } from "./surface.js";
 
 /**
  * The verify tool: one EXECUTE entry point for declared verification.
@@ -13,41 +11,8 @@ import { listChecks, runScriptCheck, VERIFICATION_SCRIPT_FAMILY_HINT } from "./s
  * path=<file>) validates an HTML/CSS/JS artifact without shell access.
  */
 
-/** Tolerate the weak-model shape of `args` sent as a JSON string. */
-function prepareVerifyArguments(args: Record<string, unknown>): Record<string, unknown> {
-	if (!args || typeof args !== "object" || Array.isArray(args)) return args;
-	const next: Record<string, unknown> = { ...args };
-	if (typeof next.args === "string") {
-		try {
-			const parsed = JSON.parse(next.args) as unknown;
-			if (Array.isArray(parsed)) next.args = parsed;
-		} catch {
-			// Leave the malformed string; runScriptCheck ignores non-arrays.
-		}
-	}
-	return next;
-}
-
 export const verifyTool: ToolSpec = {
-	name: ToolNames.Verify,
-	description:
-		'Run a declared verification check: no arguments lists checks, check=<package.json script> runs it, check="frontend" with path validates an HTML/CSS/JS artifact.',
-	parameters: Type.Object({
-		check: Type.Optional(
-			Type.String({
-				description: `Declared script name (${VERIFICATION_SCRIPT_FAMILY_HINT}) or "frontend". Omit to list available checks.`,
-			}),
-		),
-		path: Type.Optional(Type.String({ description: "check=frontend: artifact file under the workspace root." })),
-		args: Type.Optional(Type.Array(Type.String(), { description: "Extra arguments passed after --." })),
-		browser: Type.Optional(stringEnum(BROWSER_MODES, "check=frontend: headless browser mode (default auto).")),
-		cwd: Type.Optional(Type.String({ description: "Working directory." })),
-		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in ms (default 120000)." })),
-		max_output_bytes: Type.Optional(Type.Number({ description: "Output cap in bytes (default 600000)." })),
-	}),
-	baseActionClass: "execute",
-	executionMode: "sequential",
-	prepareArguments: prepareVerifyArguments,
+	...verifyToolSurface,
 	async run(rawArgs, options): Promise<ToolResult> {
 		const args = prepareVerifyArguments(rawArgs);
 		const check = typeof args.check === "string" ? args.check.trim() : "";

package/src/tools/verify/surface.ts

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { ToolNames } from "../../core/tool-names.js";
+import { VERIFICATION_SCRIPT_FAMILY_HINT } from "../../core/verification-scripts.js";
+import { StringEnum } from "../../engine/ai.js";
+import type { ToolSurface } from "../lazy-tool.js";
+
+export const BROWSER_MODES = ["auto", "required", "off"] as const;
+
+/** Tolerate the weak-model shape of `args` sent as a JSON string. */
+export function prepareVerifyArguments(args: Record<string, unknown>): Record<string, unknown> {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return args;
+	const next: Record<string, unknown> = { ...args };
+	if (typeof next.args === "string") {
+		try {
+			const parsed = JSON.parse(next.args) as unknown;
+			if (Array.isArray(parsed)) next.args = parsed;
+		} catch {
+			// Leave the malformed string; runScriptCheck ignores non-arrays.
+		}
+	}
+	return next;
+}
+
+export const verifyToolSurface = {
+	name: ToolNames.Verify,
+	description:
+		'Run a declared verification check: no arguments lists checks, check=<package.json script> runs it, check="frontend" with path validates an HTML/CSS/JS artifact.',
+	parameters: Type.Object({
+		check: Type.Optional(
+			Type.String({
+				description: `Declared script name (${VERIFICATION_SCRIPT_FAMILY_HINT}) or "frontend". Omit to list available checks.`,
+			}),
+		),
+		path: Type.Optional(Type.String({ description: "check=frontend: artifact file under the workspace root." })),
+		args: Type.Optional(Type.Array(Type.String(), { description: "Extra arguments passed after --." })),
+		browser: Type.Optional(
+			StringEnum(BROWSER_MODES, { description: "check=frontend: headless browser mode (default auto)." }),
+		),
+		cwd: Type.Optional(Type.String({ description: "Working directory." })),
+		timeout_ms: Type.Optional(Type.Number({ description: "Timeout in ms (default 120000)." })),
+		max_output_bytes: Type.Optional(Type.Number({ description: "Output cap in bytes (default 600000)." })),
+	}),
+	baseActionClass: "execute",
+	executionMode: "sequential",
+	prepareArguments: prepareVerifyArguments,
+} satisfies ToolSurface;

package/src/tools/web-fetch-surface.ts

@@ -0,0 +1,23 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { ToolSurface } from "./lazy-tool.js";
+
+export const webFetchToolSurface = {
+	name: ToolNames.WebFetch,
+	description: "Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors.",
+	parameters: Type.Object({
+		url: Type.String({ description: "Fully-qualified http(s) URL." }),
+		method: Type.Optional(Type.String({ description: "HTTP method (default GET)." })),
+		headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Request headers." })),
+		body: Type.Optional(Type.String({ description: "Request body (POST/PUT)." })),
+		timeout_ms: Type.Optional(Type.Number({ description: "Timeout ms (default 30000)." })),
+		max_bytes: Type.Optional(Type.Number({ description: "Max bytes returned (default 600000)." })),
+		format: Type.Optional(
+			Type.String({
+				description: "auto (default: HTML is cleaned to Markdown, other content passes through) or raw (no conversion).",
+			}),
+		),
+	}),
+	baseActionClass: "read",
+	executionMode: "parallel",
+} satisfies ToolSurface;

package/src/tools/web-fetch.ts

@@ -1,8 +1,6 @@
-import { Type } from "typebox";
-import { fetch } from "undici";
-import { ToolNames } from "../core/tool-names.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
 import { truncateUtf8 } from "./truncate-utf8.js";
+import { webFetchToolSurface } from "./web-fetch-surface.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_BYTES = 600_000;
@@ -627,23 +625,7 @@ function formatOutput(args: {
 }
 
 export const webFetchTool: ToolSpec = {
-	name: ToolNames.WebFetch,
-	description: "Fetch an http(s) URL; HTML is cleaned and converted to Markdown. Non-2xx responses are errors.",
-	parameters: Type.Object({
-		url: Type.String({ description: "Fully-qualified http(s) URL." }),
-		method: Type.Optional(Type.String({ description: "HTTP method (default GET)." })),
-		headers: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Request headers." })),
-		body: Type.Optional(Type.String({ description: "Request body (POST/PUT)." })),
-		timeout_ms: Type.Optional(Type.Number({ description: "Timeout ms (default 30000)." })),
-		max_bytes: Type.Optional(Type.Number({ description: "Max bytes returned (default 600000)." })),
-		format: Type.Optional(
-			Type.String({
-				description: "auto (default: HTML is cleaned to Markdown, other content passes through) or raw (no conversion).",
-			}),
-		),
-	}),
-	baseActionClass: "read",
-	executionMode: "parallel",
+	...webFetchToolSurface,
 	async run(args, options): Promise<ToolResult> {
 		const urlArg = typeof args.url === "string" ? args.url : null;
 		if (!urlArg) return { kind: "error", message: "web_fetch: missing url argument" };

package/src/tools/write.ts

@@ -2,6 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { Type } from "typebox";
 import { ToolNames } from "../core/tool-names.js";
+import { generateDiffString } from "./edit-diff.js";
 import { withFileMutationQueue } from "./file-mutation-queue.js";
 import { resolveToCwd } from "./path-utils.js";
 import type { ToolResult, ToolSpec } from "./registry.js";
@@ -25,16 +26,20 @@ export const writeTool: ToolSpec = {
 		const filePath = resolveToCwd(pathArg);
 		try {
 			let previousEndedWithNewline = false;
+			let previousContent = "";
 			await withFileMutationQueue(filePath, async () => {
 				try {
-					previousEndedWithNewline = readFileSync(filePath, "utf8").endsWith("\n");
+					previousContent = readFileSync(filePath, "utf8");
+					previousEndedWithNewline = previousContent.endsWith("\n");
 				} catch {
+					previousContent = "";
 					previousEndedWithNewline = false;
 				}
 				mkdirSync(dirname(filePath), { recursive: true });
 				writeFileSync(filePath, content, "utf8");
 			});
 			const bytes = Buffer.byteLength(content, "utf8");
+			const diff = generateDiffString(previousContent, content).diff;
 			let output = `wrote ${bytes}B to ${pathArg}`;
 			if (previousEndedWithNewline && !content.endsWith("\n")) {
 				output += `\nnote: ${pathArg} no longer ends with a newline; the previous content did`;
@@ -43,7 +48,7 @@ export const writeTool: ToolSpec = {
 			// before it falls back to the length of the returned text. A write's
 			// text is a confirmation sentence, so without this the ledger printed
 			// the sentence's length as the file size.
-			return { kind: "ok", output, details: { paths: [filePath], observation: { shownBytes: bytes } } };
+			return { kind: "ok", output, details: { diff, paths: [filePath], observation: { shownBytes: bytes } } };
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			return { kind: "error", message: `write: ${msg}` };