@oh-my-pi/pi-coding-agent 12.18.3 → 12.19.2

package/src/tools/render-utils.ts

@@ -6,6 +6,7 @@
  */
 import * as os from "node:os";
 import { type Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
+import { pluralize } from "@oh-my-pi/pi-utils";
 import type { Theme } from "../modes/theme/theme";
 
 export { Ellipsis, replaceTabs, truncateToWidth } from "@oh-my-pi/pi-tui";
@@ -81,60 +82,7 @@ export function getDomain(url: string): string {
 // Formatting Utilities
 // =============================================================================
 
-/**
- * Format byte count for display (e.g., "1.5KB", "2.3MB").
- */
-export function formatBytes(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`;
-}
-
-/**
- * Format token count for display (e.g., "1.5k", "25k").
- */
-export function formatTokens(tokens: number): string {
-	if (tokens >= 1000) {
-		return `${(tokens / 1000).toFixed(1)}k`;
-	}
-	return String(tokens);
-}
-
-/**
- * Format duration for display (e.g., "500ms", "2.5s", "1.2m").
- */
-export function formatDuration(ms: number): string {
-	if (ms < 1000) return `${ms}ms`;
-	if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-	return `${(ms / 60000).toFixed(1)}m`;
-}
-
-/**
- * Format count with pluralized label (e.g., "3 files", "1 error").
- */
-export function formatCount(label: string, count: number): string {
-	const safeCount = Number.isFinite(count) ? count : 0;
-	return `${safeCount} ${pluralize(label, safeCount)}`;
-}
-
-/**
- * Format age from seconds to human-readable string.
- */
-export function formatAge(ageSeconds: number | null | undefined): string {
-	if (!ageSeconds) return "";
-	const mins = Math.floor(ageSeconds / 60);
-	const hours = Math.floor(mins / 60);
-	const days = Math.floor(hours / 24);
-	const weeks = Math.floor(days / 7);
-	const months = Math.floor(days / 30);
-
-	if (months > 0) return `${months}mo ago`;
-	if (weeks > 0) return `${weeks}w ago`;
-	if (days > 0) return `${days}d ago`;
-	if (hours > 0) return `${hours}h ago`;
-	if (mins > 0) return `${mins}m ago`;
-	return "just now";
-}
+export { formatAge, formatBytes, formatCount, formatDuration, pluralize } from "@oh-my-pi/pi-utils";
 
 // =============================================================================
 // Theme Helper Utilities
@@ -199,14 +147,6 @@ export function formatMeta(meta: string[], theme: Theme): string {
 	return meta.length > 0 ? ` ${theme.fg("muted", meta.join(theme.sep.dot))}` : "";
 }
 
-export function formatScope(scopePath: string | undefined, theme: Theme): string {
-	return scopePath ? ` ${theme.fg("muted", `in ${scopePath}`)}` : "";
-}
-
-export function formatTruncationSuffix(truncated: boolean, theme: Theme): string {
-	return truncated ? theme.fg("warning", " (truncated)") : "";
-}
-
 export function formatErrorMessage(message: string | undefined, theme: Theme): string {
 	const clean = (message ?? "").replace(/^Error:\s*/, "").trim();
 	return `${theme.styledSymbol("status.error", "error")} ${theme.fg("error", `Error: ${clean || "Unknown error"}`)}`;
@@ -217,7 +157,7 @@ export function formatEmptyMessage(message: string, theme: Theme): string {
 }
 
 // =============================================================================
-// Tool UI Kit
+// Tool UI Helpers
 // =============================================================================
 
 export type ToolUIStatus = "success" | "error" | "warning" | "info" | "pending" | "running" | "aborted";
@@ -227,99 +167,15 @@ export interface ToolUITitleOptions {
 	bold?: boolean;
 }
 
+export function formatTitle(label: string, theme: Theme, options?: ToolUITitleOptions): string {
+	const content = options?.bold === false ? label : theme.bold(label);
+	return theme.fg("toolTitle", content);
+}
+
 // =============================================================================
 // Diagnostic Formatting
 // =============================================================================
 
-export class ToolUIKit {
-	constructor(public theme: Theme) {}
-
-	title(label: string, options?: ToolUITitleOptions): string {
-		const content = options?.bold === false ? label : this.theme.bold(label);
-		return this.theme.fg("toolTitle", content);
-	}
-
-	meta(meta: string[]): string {
-		return formatMeta(meta, this.theme);
-	}
-
-	count(label: string, count: number): string {
-		return formatCount(label, count);
-	}
-
-	moreItems(remaining: number, itemType: string): string {
-		return formatMoreItems(remaining, itemType);
-	}
-
-	expandHint(expanded: boolean, hasMore: boolean): string {
-		return formatExpandHint(this.theme, expanded, hasMore);
-	}
-
-	scope(scopePath?: string): string {
-		return formatScope(scopePath, this.theme);
-	}
-
-	truncationSuffix(truncated: boolean): string {
-		return formatTruncationSuffix(truncated, this.theme);
-	}
-
-	errorMessage(message: string | undefined): string {
-		return formatErrorMessage(message, this.theme);
-	}
-
-	emptyMessage(message: string): string {
-		return formatEmptyMessage(message, this.theme);
-	}
-
-	badge(label: string, color: ToolUIColor): string {
-		return formatBadge(label, color, this.theme);
-	}
-
-	statusIcon(status: ToolUIStatus, spinnerFrame?: number): string {
-		return formatStatusIcon(status, this.theme, spinnerFrame);
-	}
-
-	wrapBrackets(text: string): string {
-		return wrapBrackets(text, this.theme);
-	}
-
-	truncate(text: string, maxLen: number): string {
-		return truncateToWidth(text, maxLen);
-	}
-
-	previewLines(text: string, maxLines: number, maxLineLen: number): string[] {
-		return getPreviewLines(text, maxLines, maxLineLen);
-	}
-
-	formatBytes(bytes: number): string {
-		return formatBytes(bytes);
-	}
-
-	formatTokens(tokens: number): string {
-		return formatTokens(tokens);
-	}
-
-	formatDuration(ms: number): string {
-		return formatDuration(ms);
-	}
-
-	formatAge(ageSeconds: number | null | undefined): string {
-		return formatAge(ageSeconds);
-	}
-
-	formatDiagnostics(
-		diag: { errored: boolean; summary: string; messages: string[] },
-		expanded: boolean,
-		getLangIcon: (filePath: string) => string,
-	): string {
-		return formatDiagnostics(diag, expanded, this.theme, getLangIcon);
-	}
-
-	formatDiffStats(added: number, removed: number, hunks: number): string {
-		return formatDiffStats(added, removed, hunks, this.theme);
-	}
-}
-
 interface ParsedDiagnostic {
 	filePath: string;
 	line: number;
@@ -671,10 +527,3 @@ export function shortenPath(filePath: string, homeDir?: string): string {
 export function wrapBrackets(text: string, theme: Theme): string {
 	return `${theme.format.bracketLeft}${text}${theme.format.bracketRight}`;
 }
-
-function pluralize(label: string, count: number): string {
-	if (count === 1) return label;
-	if (/(?:ch|sh|s|x|z)$/i.test(label)) return `${label}es`;
-	if (/[^aeiou]y$/i.test(label)) return `${label.slice(0, -1)}ies`;
-	return `${label}s`;
-}

package/src/tools/ssh.ts

@@ -9,18 +9,16 @@ import { loadCapability } from "../discovery";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import sshDescriptionBase from "../prompts/tools/ssh.md" with { type: "text" };
+import { DEFAULT_MAX_BYTES, TailBuffer } from "../session/streaming-output";
 import type { SSHHostInfo } from "../ssh/connection-manager";
 import { ensureHostInfo, getHostInfoForHost } from "../ssh/connection-manager";
 import { executeSSH } from "../ssh/ssh-executor";
 import { renderStatusLine } from "../tui";
 import { CachedOutputBlock } from "../tui/output-block";
 import type { ToolSession } from ".";
-import type { OutputMeta } from "./output-meta";
-import { allocateOutputArtifact, createTailBuffer } from "./output-utils";
-import { formatBytes, wrapBrackets } from "./render-utils";
+import { formatStyledTruncationWarning, type OutputMeta } from "./output-meta";
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
-import { DEFAULT_MAX_BYTES } from "./truncate";
 
 const sshSchema = Type.Object({
 	host: Type.String({ description: "Host name from managed SSH config or discovered ssh.json files" }),
@@ -159,8 +157,8 @@ export class SshTool implements AgentTool<typeof sshSchema, SSHToolDetails> {
 		const timeoutSec = Math.max(1, Math.min(3600, rawTimeout));
 		const timeoutMs = timeoutSec * 1000;
 
-		const tailBuffer = createTailBuffer(DEFAULT_MAX_BYTES);
-		const { artifactPath, artifactId } = await allocateOutputArtifact(this.session, "ssh");
+		const tailBuffer = new TailBuffer(DEFAULT_MAX_BYTES);
+		const { path: artifactPath, id: artifactId } = (await this.session.allocateOutputArtifact?.("ssh")) ?? {};
 
 		const result = await executeSSH(hostConfig, remoteCommand, {
 			timeout: timeoutMs,
@@ -253,7 +251,6 @@ export const sshToolRenderer = {
 			uiTheme,
 		);
 		const textContent = result.content?.find(c => c.type === "text")?.text ?? "";
-		const truncation = details?.meta?.truncation;
 		const outputBlock = new CachedOutputBlock();
 
 		return {
@@ -292,19 +289,9 @@ export const sshToolRenderer = {
 					}
 				}
 
-				if (truncation) {
-					const warnings: string[] = [];
-					if (truncation.artifactId) {
-						warnings.push(`Full output: artifact://${truncation.artifactId}`);
-					}
-					if (truncation.truncatedBy === "lines") {
-						warnings.push(`Truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines`);
-					} else {
-						warnings.push(
-							`Truncated: ${truncation.outputLines} lines shown (${formatBytes(truncation.outputBytes)} limit)`,
-						);
-					}
-					outputLines.push(uiTheme.fg("warning", wrapBrackets(warnings.join(". "), uiTheme)));
+				if (details?.meta?.truncation) {
+					const warning = formatStyledTruncationWarning(details.meta, uiTheme);
+					if (warning) outputLines.push(warning);
 				}
 
 				return outputBlock.render(

package/src/tools/submit-result.ts

@@ -89,7 +89,7 @@ export class SubmitResultTool implements AgentTool<TObject, SubmitResultDetails>
 					...(normalizedSchema as object),
 					description: `Structured output matching the schema:\n${schemaHint}`,
 				})
-			: Type.Any({ description: "Structured JSON output (no schema specified)" });
+			: Type.Object({}, { additionalProperties: true, description: "Structured JSON output (no schema specified)" });
 
 		this.parameters = Type.Object({
 			data: Type.Optional(dataSchema),

package/src/tools/tool-errors.ts

@@ -24,36 +24,6 @@ export class ToolError extends Error {
 	}
 }
 
-/**
- * Error entry for MultiError.
- */
-export interface ErrorEntry {
-	message: string;
-	context?: string;
-}
-
-/**
- * Error with multiple entries (e.g., multiple validation failures, batch errors).
- */
-export class MultiError extends ToolError {
-	constructor(readonly errors: ErrorEntry[]) {
-		super(errors.map(e => e.message).join("; "));
-		this.name = "MultiError";
-	}
-
-	render(): string {
-		if (this.errors.length === 1) {
-			const e = this.errors[0];
-			return e.context ? `${e.context}: ${e.message}` : e.message;
-		}
-		return this.errors.map(e => (e.context ? `${e.context}: ${e.message}` : e.message)).join("\n");
-	}
-
-	static from(errors: Array<string | ErrorEntry>): MultiError {
-		return new MultiError(errors.map(e => (typeof e === "string" ? { message: e } : e)));
-	}
-}
-
 /**
  * Error thrown when a tool operation is aborted (e.g., via AbortSignal).
  */

package/src/tools/tool-result.ts

@@ -1,9 +1,8 @@
 import type { AgentToolResult } from "@oh-my-pi/pi-agent-core";
 import type { ImageContent, TextContent } from "@oh-my-pi/pi-ai";
-import type { OutputSummary } from "../session/streaming-output";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
 import type { OutputMeta, TruncationOptions, TruncationSummaryOptions, TruncationTextOptions } from "./output-meta";
 import { outputMeta } from "./output-meta";
-import type { TruncationResult } from "./truncate";
 
 type ToolContent = Array<TextContent | ImageContent>;
 

package/src/tools/write.ts

@@ -24,9 +24,9 @@ import {
 	formatExpandHint,
 	formatMoreItems,
 	formatStatusIcon,
+	formatTitle,
 	replaceTabs,
 	shortenPath,
-	ToolUIKit,
 } from "./render-utils";
 
 const writeSchema = Type.Object({
@@ -151,7 +151,7 @@ function formatMetadataLine(lineCount: number | null, language: string | undefin
 	return uiTheme.fg("dim", `${icon}`);
 }
 
-function formatStreamingContent(content: string, uiTheme: Theme, ui: ToolUIKit): string {
+function formatStreamingContent(content: string, uiTheme: Theme): string {
 	if (!content) return "";
 	const lines = content.split("\n");
 	const displayLines = lines.slice(-WRITE_STREAMING_PREVIEW_LINES);
@@ -162,13 +162,13 @@ function formatStreamingContent(content: string, uiTheme: Theme, ui: ToolUIKit):
 		text += uiTheme.fg("dim", `… (${hidden} earlier lines)\n`);
 	}
 	for (const line of displayLines) {
-		text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+		text += `${uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(line), 80))}\n`;
 	}
 	text += uiTheme.fg("dim", `… (streaming)`);
 	return text;
 }
 
-function renderContentPreview(content: string, expanded: boolean, uiTheme: Theme, ui: ToolUIKit): string {
+function renderContentPreview(content: string, expanded: boolean, uiTheme: Theme): string {
 	if (!content) return "";
 	const lines = content.split("\n");
 	const maxLines = expanded ? lines.length : Math.min(lines.length, WRITE_PREVIEW_LINES);
@@ -177,7 +177,7 @@ function renderContentPreview(content: string, expanded: boolean, uiTheme: Theme
 
 	let text = "\n\n";
 	for (const line of displayLines) {
-		text += `${uiTheme.fg("toolOutput", ui.truncate(replaceTabs(line), 80))}\n`;
+		text += `${uiTheme.fg("toolOutput", truncateToWidth(replaceTabs(line), 80))}\n`;
 	}
 	if (!expanded && hidden > 0) {
 		const hint = formatExpandHint(uiTheme, expanded, hidden > 0);
@@ -189,7 +189,6 @@ function renderContentPreview(content: string, expanded: boolean, uiTheme: Theme
 
 export const writeToolRenderer = {
 	renderCall(args: WriteRenderArgs, options: RenderResultOptions, uiTheme: Theme): Component {
-		const ui = new ToolUIKit(uiTheme);
 		const rawPath = args.file_path || args.path || "";
 		const filePath = shortenPath(rawPath);
 		const lang = getLanguageFromPath(rawPath) ?? "text";
@@ -198,14 +197,14 @@ export const writeToolRenderer = {
 		const spinner =
 			options?.spinnerFrame !== undefined ? formatStatusIcon("running", uiTheme, options.spinnerFrame) : "";
 
-		let text = `${ui.title("Write")} ${spinner ? `${spinner} ` : ""}${langIcon} ${pathDisplay}`;
+		let text = `${formatTitle("Write", uiTheme)} ${spinner ? `${spinner} ` : ""}${langIcon} ${pathDisplay}`;
 
 		if (!args.content) {
 			return new Text(text, 0, 0);
 		}
 
 		// Show streaming preview of content (tail)
-		text += formatStreamingContent(args.content, uiTheme, ui);
+		text += formatStreamingContent(args.content, uiTheme);
 
 		return new Text(text, 0, 0);
 	},
@@ -216,7 +215,6 @@ export const writeToolRenderer = {
 		uiTheme: Theme,
 		args?: WriteRenderArgs,
 	): Component {
-		const ui = new ToolUIKit(uiTheme);
 		const rawPath = args?.file_path || args?.path || "";
 		const filePath = shortenPath(rawPath);
 		const fileContent = args?.content || "";
@@ -247,7 +245,7 @@ export const writeToolRenderer = {
 
 				let text = header;
 				text += `\n${metadataLine}`;
-				text += renderContentPreview(fileContent, expanded, uiTheme, ui);
+				text += renderContentPreview(fileContent, expanded, uiTheme);
 
 				if (diagnostics) {
 					const diagText = formatDiagnostics(diagnostics, expanded, uiTheme, fp =>

package/src/tui/code-cell.ts

@@ -2,10 +2,15 @@
  * Render a code cell with optional output section.
  */
 import { highlightCode, type Theme } from "../modes/theme/theme";
-import { formatDuration, formatExpandHint, formatMoreItems, replaceTabs } from "../tools/render-utils";
+import {
+	formatDuration,
+	formatExpandHint,
+	formatMoreItems,
+	formatStatusIcon,
+	replaceTabs,
+} from "../tools/render-utils";
 import { renderOutputBlock } from "./output-block";
 import type { State } from "./types";
-import { getStateIcon } from "./utils";
 
 export interface CodeCellOptions {
 	code: string;
@@ -35,7 +40,7 @@ function formatHeader(options: CodeCellOptions, theme: Theme): { title: string;
 	const { index, total, title, status, spinnerFrame, duration } = options;
 	const parts: string[] = [];
 	if (status) {
-		const icon = getStateIcon(
+		const icon = formatStatusIcon(
 			status === "complete"
 				? "success"
 				: status === "error"

package/src/tui/status-line.ts

@@ -2,11 +2,11 @@
  * Standardized status header rendering for tool output.
  */
 import type { Theme, ThemeColor } from "../modes/theme/theme";
-import type { IconType } from "./types";
-import { getStateIcon } from "./utils";
+import type { ToolUIStatus } from "../tools/render-utils";
+import { formatStatusIcon } from "../tools/render-utils";
 
 export interface StatusLineOptions {
-	icon?: IconType;
+	icon?: ToolUIStatus;
 	spinnerFrame?: number;
 	title: string;
 	titleColor?: ThemeColor;
@@ -16,7 +16,7 @@ export interface StatusLineOptions {
 }
 
 export function renderStatusLine(options: StatusLineOptions, theme: Theme): string {
-	const icon = options.icon ? getStateIcon(options.icon, theme, options.spinnerFrame) : "";
+	const icon = options.icon ? formatStatusIcon(options.icon, theme, options.spinnerFrame) : "";
 	const titleColor = options.titleColor ?? "accent";
 	const title = theme.fg(titleColor, options.title);
 	let line = icon ? `${icon} ${title}` : title;

package/src/tui/types.ts

@@ -4,7 +4,6 @@
 import type { Theme } from "../modes/theme/theme";
 
 export type State = "pending" | "running" | "success" | "error" | "warning";
-export type IconType = "success" | "error" | "running" | "pending" | "warning" | "info";
 
 export interface TreeContext {
 	index: number;

package/src/tui/utils.ts

@@ -3,7 +3,7 @@
  */
 import { padding, visibleWidth } from "@oh-my-pi/pi-tui";
 import type { Theme, ThemeBg } from "../modes/theme/theme";
-import type { IconType, State } from "./types";
+import type { State } from "./types";
 
 export { Ellipsis, truncateToWidth } from "@oh-my-pi/pi-tui";
 
@@ -101,16 +101,3 @@ export function getStateBgColor(state: State): ThemeBg {
 	if (state === "error") return "toolErrorBg";
 	return "toolPendingBg";
 }
-
-export function getStateIcon(icon: IconType, theme: Theme, spinnerFrame?: number): string {
-	if (icon === "success") return theme.styledSymbol("status.success", "success");
-	if (icon === "error") return theme.styledSymbol("status.error", "error");
-	if (icon === "warning") return theme.styledSymbol("status.warning", "warning");
-	if (icon === "info") return theme.styledSymbol("status.info", "accent");
-	if (icon === "pending") return theme.styledSymbol("status.pending", "accent");
-	if (spinnerFrame !== undefined) {
-		const frames = theme.spinnerFrames;
-		return frames[spinnerFrame % frames.length];
-	}
-	return theme.styledSymbol("status.running", "accent");
-}

package/src/utils/command-args.ts

@@ -0,0 +1,76 @@
+export function parseCommandArgs(argsString: string): string[] {
+	const args: string[] = [];
+	let current = "";
+	let inQuote: string | null = null;
+
+	for (let i = 0; i < argsString.length; i++) {
+		const char = argsString[i];
+
+		if (inQuote) {
+			if (char === inQuote) {
+				inQuote = null;
+			} else {
+				current += char;
+			}
+		} else if (char === '"' || char === "'") {
+			inQuote = char;
+		} else if (char === " " || char === "\t") {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else {
+			current += char;
+		}
+	}
+
+	if (current) {
+		args.push(current);
+	}
+
+	return args;
+}
+
+/**
+ * Substitute argument placeholders in template content
+ * Supports $1, $2, ... for positional args, $@ and $ARGUMENTS for all args
+ *
+ * Note: Replacement happens on the template string only. Argument values
+ * containing patterns like $1, $@, or $ARGUMENTS are NOT recursively substituted.
+ */
+export function substituteArgs(content: string, args: string[]): string {
+	let result = content;
+
+	// Replace $1, $2, etc. with positional args FIRST (before wildcards)
+	// This prevents wildcard replacement values containing $<digit> patterns from being re-substituted
+	result = result.replace(/\$(\d+)/g, (_, num) => {
+		const index = parseInt(num, 10) - 1;
+		return args[index] ?? "";
+	});
+
+	result = result.replace(/\$@\[(\d+)(?::(\d*)?)?\]/g, (_, startRaw: string, lengthRaw?: string) => {
+		const start = Number.parseInt(startRaw, 10);
+		if (!Number.isFinite(start) || start < 1) return "";
+		const startIndex = start - 1;
+		if (startIndex >= args.length) return "";
+
+		if (lengthRaw === undefined || lengthRaw === "") {
+			return args.slice(startIndex).join(" ");
+		}
+
+		const length = Number.parseInt(lengthRaw, 10);
+		if (!Number.isFinite(length) || length <= 0) return "";
+		return args.slice(startIndex, startIndex + length).join(" ");
+	});
+
+	// Pre-compute all args joined (optimization)
+	const allArgs = args.join(" ");
+
+	// Replace $ARGUMENTS with all args joined (new syntax, aligns with Claude, Codex, OpenCode)
+	result = result.replaceAll("$ARGUMENTS", allArgs);
+
+	// Replace $@ with all args joined (existing syntax)
+	result = result.replaceAll("$@", allArgs);
+
+	return result;
+}

package/src/utils/file-mentions.ts

@@ -11,9 +11,14 @@ import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
 import { glob } from "@oh-my-pi/pi-natives";
 import { formatHashLines } from "../patch/hashline";
 import type { FileMentionMessage } from "../session/messages";
+import {
+	DEFAULT_MAX_BYTES,
+	formatHeadTruncationNotice,
+	truncateHead,
+	truncateHeadBytes,
+} from "../session/streaming-output";
 import { resolveReadPath } from "../tools/path-utils";
-import { formatAge } from "../tools/render-utils";
-import { DEFAULT_MAX_BYTES, formatSize, truncateHead, truncateStringToBytesFromStart } from "../tools/truncate";
+import { formatAge, formatBytes } from "../tools/render-utils";
 import { fuzzyMatch } from "./fuzzy";
 import { formatDimensionNote, resizeImage } from "./image-resize";
 import { detectSupportedImageMimeTypeFromFile } from "./mime";
@@ -162,15 +167,15 @@ function buildTextOutput(textContent: string): { output: string; lineCount: numb
 	if (truncation.firstLineExceedsLimit) {
 		const firstLine = allLines[0] ?? "";
 		const firstLineBytes = Buffer.byteLength(firstLine, "utf-8");
-		const snippet = truncateStringToBytesFromStart(firstLine, DEFAULT_MAX_BYTES);
+		const snippet = truncateHeadBytes(firstLine, DEFAULT_MAX_BYTES);
 		let outputText = snippet.text;
 
 		if (outputText.length > 0) {
-			outputText += `\n\n[Line 1 is ${formatSize(firstLineBytes)}, exceeds ${formatSize(
+			outputText += `\n\n[Line 1 is ${formatBytes(firstLineBytes)}, exceeds ${formatBytes(
 				DEFAULT_MAX_BYTES,
-			)} limit. Showing first ${formatSize(snippet.bytes)} of the line.]`;
+			)} limit. Showing first ${formatBytes(snippet.bytes)} of the line.]`;
 		} else {
-			outputText = `[Line 1 is ${formatSize(firstLineBytes)}, exceeds ${formatSize(
+			outputText = `[Line 1 is ${formatBytes(firstLineBytes)}, exceeds ${formatBytes(
 				DEFAULT_MAX_BYTES,
 			)} limit. Unable to display a valid UTF-8 snippet.]`;
 		}
@@ -181,16 +186,7 @@ function buildTextOutput(textContent: string): { output: string; lineCount: numb
 	let outputText = truncation.content;
 
 	if (truncation.truncated) {
-		const endLineDisplay = truncation.outputLines;
-		const nextOffset = endLineDisplay + 1;
-
-		if (truncation.truncatedBy === "lines") {
-			outputText += `\n\n[Showing lines 1-${endLineDisplay} of ${totalFileLines}. Use offset=${nextOffset} to continue]`;
-		} else {
-			outputText += `\n\n[Showing lines 1-${endLineDisplay} of ${totalFileLines} (${formatSize(
-				DEFAULT_MAX_BYTES,
-			)} limit). Use offset=${nextOffset} to continue]`;
-		}
+		outputText += formatHeadTruncationNotice(truncation, { startLine: 1, totalFileLines });
 	}
 
 	return { output: outputText, lineCount: totalFileLines };
@@ -247,7 +243,7 @@ async function buildDirectoryListing(absolutePath: string): Promise<{ output: st
 		notices.push(`${DEFAULT_DIR_LIMIT} entries limit reached. Use limit=${DEFAULT_DIR_LIMIT * 2} for more`);
 	}
 	if (truncation.truncated) {
-		notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+		notices.push(`${formatBytes(DEFAULT_MAX_BYTES)} limit reached`);
 	}
 	if (notices.length > 0) {
 		output += `\n\n[${notices.join(". ")}]`;
@@ -313,7 +309,7 @@ export async function generateFileMentionMessages(
 				if (stat.size > MAX_AUTO_READ_IMAGE_BYTES) {
 					files.push({
 						path: resolvedPath,
-						content: `(skipped auto-read: too large, ${formatSize(stat.size)})`,
+						content: `(skipped auto-read: too large, ${formatBytes(stat.size)})`,
 						byteSize: stat.size,
 						skippedReason: "tooLarge",
 					});
@@ -349,7 +345,7 @@ export async function generateFileMentionMessages(
 			if (stat.size > MAX_AUTO_READ_TEXT_BYTES) {
 				files.push({
 					path: resolvedPath,
-					content: `(skipped auto-read: too large, ${formatSize(stat.size)})`,
+					content: `(skipped auto-read: too large, ${formatBytes(stat.size)})`,
 					byteSize: stat.size,
 					skippedReason: "tooLarge",
 				});