@oh-my-pi/pi-coding-agent 15.10.2 → 15.10.3

package/src/cli/gallery-fixtures/fs.ts

@@ -1,6 +1,7 @@
 // biome-ignore-all lint/suspicious/noTemplateCurlyInString: sample source-code strings (read fixtures) intentionally contain literal ${...}.
 // Gallery fixtures for the filesystem tools (read, write, find).
-import type { GalleryFixture } from "./types";
+import { ReadToolGroupComponent } from "../../modes/components/read-tool-group";
+import type { GalleryFixture, GalleryFixtureState, GalleryResult } from "./types";
 
 const readSnippet = [
 	"export const findToolRenderer = {",
@@ -36,6 +37,64 @@ const writtenContent = [
 	"",
 ].join("\n");
 
+const groupedReadTargets = [
+	"packages/coding-agent/test/streaming-preview-height.test.ts:301-409",
+	"packages/coding-agent/test/tool-live-region-scrollback.test.ts:143-310",
+	"packages/tui/test/streaming-scrollback-defer.test.ts:89-464",
+];
+
+const groupedReadDelimitedPath = groupedReadTargets.join(",");
+const groupedReadRepeatedFile = "packages/coding-agent/src/task/render.ts";
+const groupedReadRepeatedRanges = `${groupedReadRepeatedFile}:507-605,1070-1194,1210-1240,1270-1274`;
+
+function textResult(text: string, details?: unknown, isError?: boolean): GalleryResult {
+	return { content: [{ type: "text", text }], details, isError };
+}
+
+function addGroupedReadArgs(component: ReadToolGroupComponent): void {
+	component.updateArgs({ path: groupedReadDelimitedPath }, "read-delimited");
+	component.updateArgs({ path: groupedReadRepeatedRanges }, "read-ranges");
+}
+
+function renderReadGroupFixtureState(state: GalleryFixtureState, width: number, expanded: boolean): string[] {
+	const component = new ReadToolGroupComponent();
+	component.setExpanded(expanded);
+
+	if (state === "streaming") {
+		component.updateArgs(
+			{
+				path: [
+					"packages/coding-agent/test/streaming-preview-height.test.ts:301-409",
+					"packages/coding-agent/test/tool-live-region-scrollback.test.ts:143-",
+				].join(","),
+			},
+			"read-delimited",
+		);
+		return component.render(width);
+	}
+
+	addGroupedReadArgs(component);
+	if (state === "progress") return component.render(width);
+
+	component.updateResult(
+		textResult("Read three focused test ranges.", { displayReadTargets: groupedReadTargets }),
+		false,
+		"read-delimited",
+	);
+
+	if (state === "error") {
+		component.updateResult(
+			textResult("Error: selector 1270-1274 is outside the file", undefined, true),
+			false,
+			"read-ranges",
+		);
+		return component.render(width);
+	}
+
+	component.updateResult(textResult("Read four render.ts ranges."), false, "read-ranges");
+	return component.render(width);
+}
+
 export const fsFixtures: Record<string, GalleryFixture> = {
 	read: {
 		label: "Read",
@@ -81,6 +140,14 @@ export const fsFixtures: Record<string, GalleryFixture> = {
 		},
 	},
 
+	read_group: {
+		label: "Read Groups",
+		args: {},
+		result: textResult("Rendered grouped read calls."),
+		errorResult: textResult("Rendered grouped read errors.", undefined, true),
+		renderState: renderReadGroupFixtureState,
+	},
+
 	write: {
 		label: "Write",
 		// Streaming: path known, content still arriving (only the imports so far).

package/src/cli/gallery-fixtures/types.ts

@@ -11,14 +11,21 @@ export interface GalleryResult {
 	isError?: boolean;
 }
 
+export type GalleryFixtureState = "streaming" | "progress" | "success" | "error";
+
 export interface GalleryFixture {
 	/** Display label for the tool header (defaults to the tool name). */
 	label?: string;
 	/** Edit mode for edit-like tools so the streaming preview dispatches correctly. */
 	editMode?: EditMode;
+	/**
+	 * Custom gallery-only renderer for fixtures that are not one ToolExecutionComponent
+	 * (for example the read-group transcript component).
+	 */
+	renderState?: (state: GalleryFixtureState, width: number, expanded: boolean) => string[] | Promise<string[]>;
 	/**
 	 * Set for tools whose real `AgentTool` attaches `renderCall`/`renderResult`
-	 * directly on the instance (e.g. `lsp`, `task`). The harness then attaches
+	 * directly on the instance (e.g. `task`). The harness then attaches
 	 * the registry renderer onto the fake tool so the component routes through
 	 * the custom-tool branch — the same path production takes — instead of the
 	 * built-in registry branch. The two branches can diverge, so exercising the

package/src/commit/agentic/agent.ts

@@ -170,6 +170,7 @@ export async function runCommitAgentSession(input: CommitAgentInput): Promise<Co
 			await session.prompt(reminder, {
 				attribution: "agent",
 				expandPromptTemplates: false,
+				synthetic: true,
 			});
 		}
 

package/src/edit/hashline/diff.ts

@@ -12,6 +12,7 @@
 import {
 	type ApplyResult,
 	applyEdits,
+	type Cursor,
 	computeFileHash,
 	type Edit,
 	Patch as HashlinePatch,
@@ -131,6 +132,86 @@ function applyPreviewEdits(args: {
 	throw createMismatchError(section, absolutePath, normalized, snapshots, expected);
 }
 
+/**
+ * Map an insert cursor to the 1-indexed line where its payload lands, used to
+ * number the `+` rows of a streaming preview. Deliberately approximate: it
+ * ignores line shifts introduced by sibling ops, because the args-complete
+ * pass renumbers everything through the real unified diff.
+ */
+function insertCursorLine(cursor: Cursor, fileLineCount: number): number {
+	switch (cursor.kind) {
+		case "bof":
+			return 1;
+		case "eof":
+			return fileLineCount + 1;
+		case "before_anchor":
+			return cursor.anchor.line;
+		case "after_anchor":
+			return cursor.anchor.line + 1;
+	}
+}
+
+/**
+ * Build a streaming diff preview by emitting, per op in patch order, the
+ * removed file lines followed by the op's `+` payload rows — never a whole-file
+ * Myers re-diff. {@link generateDiffString} re-aligns the in-flight payload
+ * against the removed block on every streamed chunk (it greedily matches shared
+ * `}`/blank/`return` rows), so additions jump between hunks and the tail window
+ * the renderer pins stutters tick to tick. Natural order keeps the removed
+ * block fixed and grows the payload monotonically at the bottom so the streamed
+ * cursor stays put. Mirrors the apply_patch streaming strategy; the
+ * args-complete pass still produces the real unified diff.
+ */
+function buildStreamingSectionDiff(
+	section: PatchSection,
+	normalized: string,
+): { diff: string; firstChangedLine: number | undefined } | { error: string } {
+	const { edits } = parsePatchStreaming(section.diff);
+	const resolved = resolveBlockEdits(edits, normalized, section.path, nativeBlockResolver, { onUnresolved: "drop" });
+	if (resolved.length === 0) return { error: `No changes would be made to ${section.path}.` };
+
+	const fileLines = normalized.split("\n");
+	const rows: string[] = [];
+	let firstChangedLine: number | undefined;
+
+	// Every edit emitted from one op header carries that header's patch line
+	// number and the edits sit contiguously (a replace lays down its replacement
+	// inserts then its range deletes; block ops expand to the same shape). Group
+	// on that boundary so each op stays intact and ordered.
+	for (let i = 0; i < resolved.length; ) {
+		const opLine = resolved[i].lineNum;
+		const deletes: number[] = [];
+		const inserts: string[] = [];
+		let insertBase: number | undefined;
+		while (i < resolved.length && resolved[i].lineNum === opLine) {
+			const edit = resolved[i];
+			if (edit.kind === "delete") deletes.push(edit.anchor.line);
+			else if (edit.kind === "insert") {
+				insertBase ??= insertCursorLine(edit.cursor, fileLines.length);
+				inserts.push(edit.text);
+			}
+			i++;
+		}
+		// Removed lines first (a fixed block), payload second (grows at the
+		// bottom = the streamed cursor).
+		deletes.sort((a, b) => a - b);
+		for (const line of deletes) {
+			firstChangedLine ??= line;
+			const content = line >= 1 && line <= fileLines.length ? fileLines[line - 1] : "";
+			rows.push(`-${line}|${content}`);
+		}
+		let newLine = insertBase ?? deletes[0] ?? 1;
+		for (const text of inserts) {
+			firstChangedLine ??= newLine;
+			rows.push(`+${newLine}|${text}`);
+			newLine++;
+		}
+	}
+
+	if (rows.length === 0) return { error: `No changes would be made to ${section.path}.` };
+	return { diff: rows.join("\n"), firstChangedLine };
+}
+
 export async function computeHashlineSectionDiff(
 	section: PatchSection,
 	cwd: string,
@@ -142,6 +223,11 @@ export async function computeHashlineSectionDiff(
 		const rawContent = await readSectionText(absolutePath, section.path);
 		const { text: content } = stripBom(rawContent);
 		const normalized = normalizeToLF(content);
+		// Streaming favors a stable, monotonic preview over an exact unified
+		// diff: feed the in-flight ops through the natural-order builder so the
+		// streamed cursor stays pinned to the bottom. The args-complete pass
+		// (`streaming` unset) falls through to the real Myers diff below.
+		if (options.streaming) return buildStreamingSectionDiff(section, normalized);
 		const result = applyPreviewEdits({ section, absolutePath, normalized, snapshots, options });
 		if (normalized === result.text) return { error: `No changes would be made to ${section.path}.` };
 		return generateDiffString(normalized, result.text);

package/src/edit/hashline/execute.ts

@@ -11,6 +11,7 @@
  * round-trip once.
  */
 import {
+	type BlockResolution,
 	buildCompactDiffPreview,
 	MismatchError as HashlineMismatchError,
 	Patch,
@@ -76,6 +77,14 @@ interface RenderedSection {
 	perFileResult: EditToolPerFileResult;
 }
 
+function formatBlockResolution(resolution: BlockResolution): string {
+	const op = resolution.isDelete ? "delete block" : "replace block";
+	const lines = resolution.end - resolution.start + 1;
+	const span =
+		resolution.start === resolution.end ? `line ${resolution.start}` : `lines ${resolution.start}-${resolution.end}`;
+	return `${op} ${resolution.anchorLine} → resolved ${span} (${lines} line${lines === 1 ? "" : "s"})`;
+}
+
 function renderSection(result: PatchSectionResult, diagnostics: FileDiagnosticsResult | undefined): RenderedSection {
 	if (result.op === "noop") {
 		const toolResult: AgentToolResult<EditToolDetails, typeof hashlineEditParamsSchema> = {
@@ -96,10 +105,14 @@ function renderSection(result: PatchSectionResult, diagnostics: FileDiagnosticsR
 
 	const warningsBlock = result.warnings.length > 0 ? `\n\nWarnings:\n${result.warnings.join("\n")}` : "";
 	const previewBlock = preview.preview ? `\n${preview.preview}` : "";
+	const blockBlock =
+		result.blockResolutions && result.blockResolutions.length > 0
+			? `\n${result.blockResolutions.map(formatBlockResolution).join("\n")}`
+			: "";
 	const firstChangedLine = result.firstChangedLine ?? diff.firstChangedLine;
 	return {
 		toolResult: {
-			content: [{ type: "text", text: `${result.header}${previewBlock}${warningsBlock}` }],
+			content: [{ type: "text", text: `${result.header}${blockBlock}${previewBlock}${warningsBlock}` }],
 			details: {
 				diff: diff.diff,
 				firstChangedLine,

package/src/edit/index.ts

@@ -14,7 +14,7 @@ import { getDiagnosticsLedger } from "../lsp/diagnostics-ledger";
 import applyPatchDescription from "../prompts/tools/apply-patch.md" with { type: "text" };
 import patchDescription from "../prompts/tools/patch.md" with { type: "text" };
 import replaceDescription from "../prompts/tools/replace.md" with { type: "text" };
-import type { ToolSession } from "../tools";
+import type { DeferredDiagnosticsEntry, ToolSession } from "../tools";
 import { truncateForPrompt } from "../tools/approval";
 import { isInternalUrlPath } from "../tools/path-utils";
 import { type EditMode, normalizeEditMode, resolveEditMode } from "../utils/edit-mode";
@@ -297,7 +297,6 @@ export class EditTool implements AgentTool<TInput> {
 	readonly name = "edit";
 	readonly label = "Edit";
 	readonly loadMode = "essential";
-	readonly nonAbortable = true;
 	readonly concurrency = "exclusive";
 	readonly strict = true;
 
@@ -307,6 +306,10 @@ export class EditTool implements AgentTool<TInput> {
 	readonly #editMode?: EditMode;
 	readonly #dedupDiagnostics: boolean;
 	readonly #pendingDeferredFetches = new Map<string, AbortController>();
+	/** Fallback per-path mutation counter used only when the session does not expose
+	 *  a shared one. Prefer `session.bumpFileMutationVersion` so write (and any other
+	 *  tool) mutating the same file also invalidates pending late-diagnostics. */
+	readonly #editVersionByPath = new Map<string, number>();
 
 	constructor(private readonly session: ToolSession) {
 		const {
@@ -503,10 +506,11 @@ export class EditTool implements AgentTool<TInput> {
 		}
 
 		const deferredController = new AbortController();
+		const editVersion = this.#bumpFileVersion(path);
 		return {
 			onDeferredDiagnostics: (lateDiagnostics: FileDiagnosticsResult) => {
 				this.#pendingDeferredFetches.delete(path);
-				this.#injectLateDiagnostics(path, lateDiagnostics);
+				this.#injectLateDiagnostics(path, lateDiagnostics, editVersion);
 			},
 			signal: deferredController.signal,
 			finalize: (diagnostics: FileDiagnosticsResult | undefined) => {
@@ -519,24 +523,34 @@ export class EditTool implements AgentTool<TInput> {
 		};
 	}
 
-	#injectLateDiagnostics(path: string, diagnostics: FileDiagnosticsResult): void {
+	#injectLateDiagnostics(path: string, diagnostics: FileDiagnosticsResult, editVersion: number): void {
 		const effective = this.#dedupDiagnostics
 			? getDiagnosticsLedger(this.session).reduce(path, diagnostics)
 			: diagnostics;
 		if (this.#dedupDiagnostics && effective.messages.length === 0) return;
 
-		const summary = effective.summary ?? "";
-		const lines = effective.messages ?? [];
-		const body = [`Late LSP diagnostics for ${path} (arrived after the edit tool returned):`, summary, ...lines]
-			.filter(Boolean)
-			.join("\n");
-
-		this.session.queueDeferredMessage?.({
-			role: "custom",
-			customType: "lsp-late-diagnostic",
-			content: body,
-			display: false,
-			timestamp: Date.now(),
-		});
+		const entry: DeferredDiagnosticsEntry = {
+			path,
+			summary: effective.summary ?? "",
+			messages: effective.messages ?? [],
+			errored: effective.errored,
+			// Drop at flush time if a later edit to the same file superseded this fetch.
+			isStale: () => this.#fileVersion(path) !== editVersion,
+		};
+		this.session.queueDeferredDiagnostics?.(entry);
+	}
+
+	/** Bump the file's mutation counter (session-global when available). */
+	#bumpFileVersion(path: string): number {
+		if (this.session.bumpFileMutationVersion) return this.session.bumpFileMutationVersion(path);
+		const next = (this.#editVersionByPath.get(path) ?? 0) + 1;
+		this.#editVersionByPath.set(path, next);
+		return next;
+	}
+
+	/** Read the file's current mutation counter (session-global when available). */
+	#fileVersion(path: string): number {
+		if (this.session.getFileMutationVersion) return this.session.getFileMutationVersion(path);
+		return this.#editVersionByPath.get(path) ?? 0;
 	}
 }

package/src/edit/renderer.ts

@@ -4,7 +4,7 @@
 
 import { HL_FILE_PREFIX, HL_FILE_SUFFIX } from "@oh-my-pi/hashline";
 import type { Component } from "@oh-my-pi/pi-tui";
-import { visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
+import { sliceWithWidth, visibleWidth, wrapTextWithAnsi } from "@oh-my-pi/pi-tui";
 import { sanitizeText } from "@oh-my-pi/pi-utils";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { FileDiagnosticsResult } from "../lsp";
@@ -13,7 +13,6 @@ import { getLanguageFromPath, type Theme } from "../modes/theme/theme";
 import type { OutputMeta } from "../tools/output-meta";
 import {
 	formatDiagnostics,
-	formatDiffStats,
 	formatExpandHint,
 	formatStatusIcon,
 	getDiffStats,
@@ -182,42 +181,118 @@ function getOperationTitle(op: Operation | undefined): string {
 	return op === "create" ? "Create" : op === "delete" ? "Delete" : "Edit";
 }
 
+interface EditPathDisplayOptions {
+	rename?: string;
+	firstChangedLine?: number;
+	linkPath?: string;
+	renameLinkPath?: string;
+	maxPathWidth?: number;
+}
+
+function truncateEditTitlePath(displayPath: string, maxWidth: number | undefined): string {
+	if (maxWidth === undefined) return displayPath;
+	const width = visibleWidth(displayPath);
+	const safeMaxWidth = Math.max(0, Math.floor(maxWidth));
+	if (width <= safeMaxWidth) return displayPath;
+
+	const contentWidth = safeMaxWidth - 1;
+	if (contentWidth <= 0) return "…";
+
+	const headWidth = Math.floor(contentWidth / 2);
+	const tailWidth = contentWidth - headWidth;
+	const head = sliceWithWidth(displayPath, 0, headWidth, true).text;
+	const tail = sliceWithWidth(displayPath, Math.max(0, width - tailWidth), tailWidth, true).text;
+	return `${head}…${tail}`;
+}
+
+function formatEditTitlePath(pathValue: string, maxWidth?: number): string {
+	return truncateEditTitlePath(replaceTabs(shortenPath(pathValue), pathValue), maxWidth);
+}
+
 function formatEditPathDisplay(
 	rawPath: string,
 	uiTheme: Theme,
-	options?: { rename?: string; firstChangedLine?: number; linkPath?: string; renameLinkPath?: string },
-): string {
+	options?: EditPathDisplayOptions,
+): { text: string; pathWidth: number } {
 	// `rawPath`/`rename` are shown (cwd-relative) but the OSC 8 link targets the
-	// absolute path when known — a relative `rawPath` would yield a `file:///rel`
-	// URI that resolves against filesystem root instead of cwd.
+	// absolute path when known — a relative `rawPath` would otherwise yield a
+	// `file:///rel` URI that resolves against filesystem root instead of cwd.
 	const linkTarget = options?.linkPath || rawPath;
+	const lineLink = options?.firstChangedLine ? { line: options.firstChangedLine } : undefined;
+	const primaryDisplay = rawPath ? formatEditTitlePath(rawPath, options?.maxPathWidth) : "…";
 	let pathDisplay = rawPath
-		? fileHyperlink(linkTarget, uiTheme.fg("accent", shortenPath(rawPath)))
-		: uiTheme.fg("toolOutput", "…");
-
-	if (options?.firstChangedLine) {
-		pathDisplay += uiTheme.fg("warning", `:${options.firstChangedLine}`);
-	}
+		? fileHyperlink(linkTarget, uiTheme.fg("accent", primaryDisplay), lineLink)
+		: uiTheme.fg("toolOutput", primaryDisplay);
+	let pathWidth = visibleWidth(primaryDisplay);
 
 	if (options?.rename) {
 		const renameTarget = options.renameLinkPath || options.rename;
-		pathDisplay += ` ${uiTheme.fg("dim", "→")} ${fileHyperlink(renameTarget, uiTheme.fg("accent", shortenPath(options.rename)))}`;
+		const renameDisplay = formatEditTitlePath(options.rename, options.maxPathWidth);
+		pathDisplay += ` ${uiTheme.fg("dim", "→")} ${fileHyperlink(renameTarget, uiTheme.fg("accent", renameDisplay))}`;
+		pathWidth += visibleWidth(renameDisplay);
 	}
 
-	return pathDisplay;
+	return { text: pathDisplay, pathWidth };
 }
 
 function formatEditDescription(
 	rawPath: string,
 	uiTheme: Theme,
-	options?: { rename?: string; firstChangedLine?: number; linkPath?: string; renameLinkPath?: string },
-): { language: string; description: string } {
+	options?: EditPathDisplayOptions,
+): { language: string; description: string; pathWidth: number } {
 	const language = getLanguageFromPath(rawPath) ?? "text";
 	const icon = uiTheme.fg("muted", uiTheme.getLangIcon(language));
+	const pathDisplay = formatEditPathDisplay(rawPath, uiTheme, options);
 	return {
 		language,
-		description: `${icon} ${formatEditPathDisplay(rawPath, uiTheme, options)}`,
+		description: `${icon} ${pathDisplay.text}`,
+		pathWidth: pathDisplay.pathWidth,
+	};
+}
+
+function editHeaderLabelBudget(width: number, uiTheme: Theme): number {
+	const leftGlyphs = `${uiTheme.boxSharp.topLeft}${uiTheme.boxSharp.horizontal.repeat(3)}`;
+	return Math.max(0, width - visibleWidth(leftGlyphs) - visibleWidth(uiTheme.boxSharp.topRight) - 2);
+}
+
+function renderEditHeader(
+	width: number,
+	uiTheme: Theme,
+	options: {
+		icon: "pending" | "success" | "error";
+		spinnerFrame?: number;
+		op?: Operation;
+		rawPath: string;
+		rename?: string;
+		firstChangedLine?: number;
+		linkPath?: string;
+		statsSuffix?: string;
+		extraSuffix?: string;
+	},
+): string {
+	const title = getOperationTitle(options.op);
+	const descriptionOptions: EditPathDisplayOptions = {
+		rename: options.rename,
+		firstChangedLine: options.firstChangedLine,
+		linkPath: options.linkPath,
 	};
+	const formatted = formatEditDescription(options.rawPath, uiTheme, descriptionOptions);
+	const suffix = `${options.statsSuffix ?? ""}${options.extraSuffix ?? ""}`;
+	const buildHeader = (description: string): string =>
+		renderStatusLine({ icon: options.icon, spinnerFrame: options.spinnerFrame, title, description }, uiTheme) +
+		suffix;
+
+	const header = buildHeader(formatted.description);
+	const overflow = visibleWidth(header) - editHeaderLabelBudget(width, uiTheme);
+	if (overflow <= 0 || formatted.pathWidth <= 1) return header;
+
+	const pathCount = Math.max(1, (options.rawPath ? 1 : 0) + (options.rename ? 1 : 0));
+	const fittedPathWidth = Math.max(1, Math.floor((formatted.pathWidth - overflow) / pathCount));
+	const fitted = formatEditDescription(options.rawPath, uiTheme, {
+		...descriptionOptions,
+		maxPathWidth: fittedPathWidth,
+	});
+	return buildHeader(fitted.description);
 }
 
 function renderPlainTextPreview(text: string, uiTheme: Theme, filePath?: string): string {
@@ -379,10 +454,13 @@ function getApplyPatchRenderSummary(
 }
 
 function formatDiffStatsSuffix(diff: string, uiTheme: Theme): string {
-	const { added, removed, hunks } = getDiffStats(diff);
-	const stats = formatDiffStats(added, removed, hunks, uiTheme);
-	if (!stats) return "";
-	return ` ${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${stats}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
+	const { added, removed } = getDiffStats(diff);
+	if (added === 0 && removed === 0) return "";
+	const stats = [
+		added > 0 ? uiTheme.fg("toolDiffAdded", `+${added}`) : undefined,
+		removed > 0 ? uiTheme.fg("toolDiffRemoved", `-${removed}`) : undefined,
+	].filter(value => value !== undefined);
+	return ` ${uiTheme.fg("dim", uiTheme.format.bracketLeft)}${stats.join(uiTheme.fg("dim", "/"))}${uiTheme.fg("dim", uiTheme.format.bracketRight)}`;
 }
 
 function renderDiffSection(
@@ -462,17 +540,19 @@ export const editToolRenderer = {
 			"";
 		const rename = editArgs.rename || firstEdit?.rename || firstEdit?.move || firstApplyPatchEntry?.rename;
 		const op = editArgs.op || firstEdit?.op || firstApplyPatchEntry?.op;
-		const { description } = formatEditDescription(rawPath, uiTheme, { rename });
 		let fileCount = hashlineInputSummary?.entries.length ?? applyPatchSummary?.entries.length ?? 0;
 		if (Array.isArray(editArgs.edits)) {
 			fileCount = countEditFiles(editArgs.edits);
 		}
 		return framedBlock(uiTheme, width => {
-			let header = renderStatusLine(
-				{ icon: "pending", spinnerFrame: options?.spinnerFrame, title: getOperationTitle(op), description },
-				uiTheme,
-			);
-			if (fileCount > 1) header += uiTheme.fg("dim", ` (+${fileCount - 1} more)`);
+			const header = renderEditHeader(width, uiTheme, {
+				icon: "pending",
+				spinnerFrame: options?.spinnerFrame,
+				op,
+				rawPath,
+				rename,
+				extraSuffix: fileCount > 1 ? uiTheme.fg("dim", ` (+${fileCount - 1} more)`) : undefined,
+			});
 			let body = getCallPreview(editArgs, rawPath, uiTheme, renderContext, options.expanded);
 			if (applyPatchSummary?.error) {
 				body += `\n${uiTheme.fg("error", truncateToWidth(replaceTabs(applyPatchSummary.error, rawPath), Math.max(1, width - 2)))}`;
@@ -546,15 +626,20 @@ function renderSingleFileResult(
 			(editDiffPreview && "firstChangedLine" in editDiffPreview ? editDiffPreview.firstChangedLine : undefined) ||
 			(details && !isError ? details.firstChangedLine : undefined);
 		const linkPath = details && "path" in details ? details.path : undefined;
-		const { description } = formatEditDescription(rawPath, uiTheme, { rename, firstChangedLine, linkPath });
 
 		// Change stats ride inline on the header bar next to the path.
 		const previewDiff = editDiffPreview && !("error" in editDiffPreview) ? editDiffPreview.diff : undefined;
 		const headerDiff = isError ? undefined : details?.diff || previewDiff;
 		const statsSuffix = headerDiff ? formatDiffStatsSuffix(headerDiff, uiTheme) : "";
-		const header =
-			renderStatusLine({ icon: isError ? "error" : "success", title: getOperationTitle(op), description }, uiTheme) +
-			statsSuffix;
+		const header = renderEditHeader(width, uiTheme, {
+			icon: isError ? "error" : "success",
+			op,
+			rawPath,
+			rename,
+			firstChangedLine,
+			linkPath,
+			statsSuffix,
+		});
 
 		let body = "";
 		if (isError) {

package/src/eval/js/shared/prelude.txt

@@ -1,17 +1,33 @@
 if (!globalThis.__omp_js_prelude_loaded__) {
 	globalThis.__omp_js_prelude_loaded__ = true;
 
-	const toOptions = value => (value && typeof value === "object" && !Array.isArray(value) ? value : {});
+	const isPlainObject = value => value !== null && typeof value === "object" && !Array.isArray(value);
+	const optionsArg = (name, value, rest, example) => {
+		if (rest.length > 0) {
+			throw new TypeError(
+				`${name}() takes options as a single trailing object literal, not positional arguments (got ${rest.length + 1} extra args). Pass them as ${name}(..., ${example}).`,
+			);
+		}
+		if (value === undefined || value === null) return {};
+		if (!isPlainObject(value)) {
+			const kind = Array.isArray(value) ? "an array" : typeof value;
+			throw new TypeError(
+				`${name}() options must be a trailing object literal like ${example}, not ${kind}. JS helpers never take positional options.`,
+			);
+		}
+		return value;
+	};
 	const callHelper = (name, ...args) => globalThis.__omp_helpers__[name](...args);
 
-	const read = (path, opts = {}) => callHelper("read", path, toOptions(opts));
+	const read = (path, opts, ...rest) => callHelper("read", path, optionsArg("read", opts, rest, "{ offset, limit }"));
 	const write = async (path, data) => callHelper("writeFile", path, data);
 	const append = (path, content) => callHelper("append", path, content);
-	const sort = (text, opts = {}) => callHelper("sortText", text, toOptions(opts));
-	const uniq = (text, opts = {}) => callHelper("uniqText", text, toOptions(opts));
-	const counter = (items, opts = {}) => callHelper("counter", items, toOptions(opts));
+	const sort = (text, opts, ...rest) => callHelper("sortText", text, optionsArg("sort", opts, rest, "{ reverse, unique }"));
+	const uniq = (text, opts, ...rest) => callHelper("uniqText", text, optionsArg("uniq", opts, rest, "{ count }"));
+	const counter = (items, opts, ...rest) =>
+		callHelper("counter", items, optionsArg("counter", opts, rest, "{ limit, reverse }"));
 	const diff = (a, b) => callHelper("diff", a, b);
-	const tree = (path = ".", opts = {}) => callHelper("tree", path, toOptions(opts));
+	const tree = (path = ".", opts, ...rest) => callHelper("tree", path, optionsArg("tree", opts, rest, "{ maxDepth, showHidden }"));
 	const env = (key, value) => callHelper("env", key, value);
 
 	const tool = new Proxy(
@@ -41,15 +57,15 @@ if (!globalThis.__omp_js_prelude_loaded__) {
 
 	const hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
 
-	const llm = async (prompt, opts = {}) => {
-		const o = toOptions(opts);
+	const llm = async (prompt, opts, ...rest) => {
+		const o = optionsArg("llm", opts, rest, "{ model, system, schema }");
 		const res = await globalThis.__omp_call_tool__("__llm__", { prompt, ...o });
 		const text = res && typeof res === "object" ? res.text : res;
 		return hasOwn(o, "schema") ? JSON.parse(text) : text;
 	};
 
-	const agent = async (prompt, opts = {}) => {
-		const o = toOptions(opts);
+	const agent = async (prompt, opts, ...rest) => {
+		const o = optionsArg("agent", opts, rest, "{ agentType, model, context, label, schema }");
 		const res = await globalThis.__omp_call_tool__("__agent__", { prompt, ...o });
 		const text = res && typeof res === "object" ? res.text : res;
 		return hasOwn(o, "schema") ? JSON.parse(text) : text;