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

package/src/tools/gemini-image.ts

@@ -1,7 +1,7 @@
 import * as os from "node:os";
 import * as path from "node:path";
 import { getAntigravityHeaders, getEnvApiKey, StringEnum } from "@oh-my-pi/pi-ai";
-import { $env, ptree, readSseJson, Snowflake, untilAborted } from "@oh-my-pi/pi-utils";
+import { $env, isEnoent, ptree, readSseJson, Snowflake, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import type { ModelRegistry } from "../config/model-registry";
 import { renderPromptTemplate } from "../config/prompt-templates";
@@ -428,21 +428,22 @@ async function findImageApiKey(modelRegistry?: ModelRegistry): Promise<ImageApiK
 
 async function loadImageFromPath(imagePath: string, cwd: string): Promise<InlineImageData> {
 	const resolved = resolveReadPath(imagePath, cwd);
-	const file = Bun.file(resolved);
-	if (!(await file.exists())) {
-		throw new Error(`Image file not found: ${imagePath}`);
-	}
-	if (file.size > MAX_IMAGE_SIZE) {
-		throw new Error(`Image file too large: ${imagePath}`);
-	}
+	try {
+		const buffer = await Bun.file(resolved).bytes();
+		if (buffer.length > MAX_IMAGE_SIZE) {
+			throw new Error(`Image file too large: ${imagePath}`);
+		}
 
-	const mimeType = await detectSupportedImageMimeTypeFromFile(resolved);
-	if (!mimeType) {
-		throw new Error(`Unsupported image type: ${imagePath}`);
-	}
+		const mimeType = await detectSupportedImageMimeTypeFromFile(resolved);
+		if (!mimeType) {
+			throw new Error(`Unsupported image type: ${imagePath}`);
+		}
 
-	const buffer = await file.bytes();
-	return { data: buffer.toBase64(), mimeType };
+		return { data: buffer.toBase64(), mimeType };
+	} catch (err) {
+		if (isEnoent(err)) throw new Error(`Image file not found: ${imagePath}`);
+		throw err;
+	}
 }
 
 async function resolveInputImage(input: ImageInput, cwd: string): Promise<InlineImageData> {

package/src/tools/grep.ts

@@ -11,15 +11,15 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
 import { computeLineHash } from "../patch/hashline";
 import grepDescription from "../prompts/tools/grep.md" with { type: "text" };
+import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead } from "../session/streaming-output";
 import { Ellipsis, Hasher, type RenderCache, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";
-import type { OutputMeta } from "./output-meta";
+import { formatFullOutputReference, type OutputMeta } from "./output-meta";
 import { resolveToCwd } from "./path-utils";
 import { formatCount, formatEmptyMessage, formatErrorMessage, PREVIEW_LIMITS } from "./render-utils";
 import { ToolError } from "./tool-errors";
 import { toolResult } from "./tool-result";
-import { DEFAULT_MAX_COLUMN, type TruncationResult, truncateHead } from "./truncate";
 
 const grepSchema = Type.Object({
 	pattern: Type.String({ description: "Regex pattern to search for" }),
@@ -452,7 +452,7 @@ export const grepToolRenderer = {
 		if (limits?.resultLimit) truncationReasons.push(`limit ${limits.resultLimit.reached} results`);
 		if (truncation) truncationReasons.push(truncation.truncatedBy === "lines" ? "line limit" : "size limit");
 		if (limits?.columnTruncated) truncationReasons.push(`line length ${limits.columnTruncated.maxColumn}`);
-		if (truncation?.artifactId) truncationReasons.push(`full output: artifact://${truncation.artifactId}`);
+		if (truncation?.artifactId) truncationReasons.push(formatFullOutputReference(truncation.artifactId));
 
 		const extraLines =
 			truncationReasons.length > 0 ? [uiTheme.fg("warning", `truncated: ${truncationReasons.join(", ")}`)] : [];

package/src/tools/index.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
 import { $env, logger } from "@oh-my-pi/pi-utils";
+import type { AsyncJobManager } from "../async";
 import type { PromptTemplate } from "../config/prompt-templates";
 import type { Settings } from "../config/settings";
 import type { Skill } from "../extensibility/skills";
@@ -9,7 +10,6 @@ import { checkPythonKernelAvailability } from "../ipy/kernel";
 import { LspTool } from "../lsp";
 import { EditTool } from "../patch";
 import type { PlanModeState } from "../plan-mode/state";
-import type { ArtifactManager } from "../session/artifacts";
 import { TaskTool } from "../task";
 import type { AgentOutputManager } from "../task/output-manager";
 import type { EventBus } from "../utils/event-bus";
@@ -18,12 +18,14 @@ import { AskTool } from "./ask";
 import { BashTool } from "./bash";
 import { BrowserTool } from "./browser";
 import { CalculatorTool } from "./calculator";
+import { CancelJobTool } from "./cancel-job";
 import { ExitPlanModeTool } from "./exit-plan-mode";
 import { FetchTool } from "./fetch";
 import { FindTool } from "./find";
 import { GrepTool } from "./grep";
 import { NotebookTool } from "./notebook";
 import { wrapToolWithMetaNotice } from "./output-meta";
+import { PollJobsTool } from "./poll-jobs";
 import { PythonTool } from "./python";
 import { ReadTool } from "./read";
 import { reportFindingTool } from "./review";
@@ -48,49 +50,27 @@ export {
 	warmupLspServers,
 } from "../lsp";
 export { EditTool, type EditToolDetails } from "../patch";
+export * from "../session/streaming-output";
 export { BUNDLED_AGENTS, TaskTool } from "../task";
-export {
-	companySearchTools,
-	exaSearchTools,
-	getSearchTools,
-	type SearchProvider,
-	type SearchResponse,
-	SearchTool,
-	type SearchToolsOptions,
-	setPreferredSearchProvider,
-	webSearchCodeContextTool,
-	webSearchCompanyTool,
-	webSearchCrawlTool,
-	webSearchCustomTool,
-	webSearchDeepTool,
-	webSearchLinkedinTool,
-} from "../web/search";
+export * from "../web/search";
 export { AskTool, type AskToolDetails } from "./ask";
 export { BashTool, type BashToolDetails, type BashToolInput, type BashToolOptions } from "./bash";
 export { BrowserTool, type BrowserToolDetails } from "./browser";
 export { CalculatorTool, type CalculatorToolDetails } from "./calculator";
+export { CancelJobTool, type CancelJobToolDetails } from "./cancel-job";
 export { type ExitPlanModeDetails, ExitPlanModeTool } from "./exit-plan-mode";
 export { FetchTool, type FetchToolDetails } from "./fetch";
 export { type FindOperations, FindTool, type FindToolDetails, type FindToolInput, type FindToolOptions } from "./find";
 export { setPreferredImageProvider } from "./gemini-image";
 export { GrepTool, type GrepToolDetails, type GrepToolInput } from "./grep";
 export { NotebookTool, type NotebookToolDetails } from "./notebook";
+export { PollJobsTool, type PollJobsToolDetails } from "./poll-jobs";
 export { PythonTool, type PythonToolDetails, type PythonToolOptions } from "./python";
 export { ReadTool, type ReadToolDetails, type ReadToolInput } from "./read";
 export { reportFindingTool, type SubmitReviewDetails } from "./review";
 export { loadSshTool, type SSHToolDetails, SshTool } from "./ssh";
 export { SubmitResultTool } from "./submit-result";
 export { type TodoItem, TodoWriteTool, type TodoWriteToolDetails } from "./todo-write";
-export {
-	DEFAULT_MAX_BYTES,
-	DEFAULT_MAX_LINES,
-	formatSize,
-	type TruncationOptions,
-	type TruncationResult,
-	truncateHead,
-	truncateLine,
-	truncateTail,
-} from "./truncate";
 export { WriteTool, type WriteToolDetails, type WriteToolInput } from "./write";
 
 /** Tool type (AgentTool from pi-ai) */
@@ -132,10 +112,10 @@ export interface ToolSession {
 	getSessionFile: () => string | null;
 	/** Get session ID */
 	getSessionId?: () => string | null;
-	/** Cached artifact manager (allocated per ToolSession) */
-	artifactManager?: ArtifactManager;
 	/** Get artifacts directory for artifact:// URLs and $ARTIFACTS env var */
 	getArtifactsDir?: () => string | null;
+	/** Allocate a new artifact path and ID for session-scoped truncated output. */
+	allocateOutputArtifact?: (toolType: string) => Promise<{ id?: string; path?: string }>;
 	/** Get session spawns */
 	getSessionSpawns: () => string | null;
 	/** Get resolved model string if explicitly set for this session */
@@ -152,6 +132,8 @@ export interface ToolSession {
 	internalRouter?: InternalUrlRouter;
 	/** Agent output manager for unique agent:// IDs across task invocations */
 	agentOutputManager?: AgentOutputManager;
+	/** Async background job manager for bash/task async execution */
+	asyncJobManager?: AsyncJobManager;
 	/** Settings instance for passing to subagents */
 	settings: Settings;
 	/** Plan mode state (if active) */
@@ -176,6 +158,8 @@ export const BUILTIN_TOOLS: Record<string, ToolFactory> = {
 	read: s => new ReadTool(s),
 	browser: s => new BrowserTool(s),
 	task: TaskTool.create,
+	cancel_job: CancelJobTool.createIf,
+	poll_jobs: PollJobsTool.createIf,
 	todo_write: s => new TodoWriteTool(s),
 	fetch: s => new FetchTool(s),
 	web_search: s => new SearchTool(s),

package/src/tools/json-tree.ts

@@ -12,6 +12,17 @@ export const JSON_TREE_MAX_LINES_EXPANDED = 200;
 export const JSON_TREE_SCALAR_LEN_COLLAPSED = 60;
 export const JSON_TREE_SCALAR_LEN_EXPANDED = 2000;
 
+/** Keys injected by the harness that should not be displayed to users */
+const HIDDEN_ARG_KEYS = new Set(["agent__intent"]);
+
+/** Strip harness-internal keys from tool args for display */
+export function stripInternalArgs(args: Record<string, unknown>): Record<string, unknown> {
+	const result: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(args)) {
+		if (!HIDDEN_ARG_KEYS.has(key)) result[key] = value;
+	}
+	return result;
+}
 /**
  * Format a scalar value for inline display.
  */
@@ -37,7 +48,7 @@ export function formatScalar(value: unknown, maxLen: number): string {
  * Format args inline for collapsed view.
  */
 export function formatArgsInline(args: Record<string, unknown>, maxWidth: number): string {
-	const entries = Object.entries(args);
+	const entries = Object.entries(args).filter(([k]) => !HIDDEN_ARG_KEYS.has(k));
 	if (entries.length === 0) return "";
 
 	// Single arg: show key=value

package/src/tools/jtd-to-json-schema.ts

@@ -8,52 +8,16 @@
  * @see https://datatracker.ietf.org/doc/html/rfc8927
  */
 
-type JTDPrimitive =
-	| "boolean"
-	| "string"
-	| "timestamp"
-	| "float32"
-	| "float64"
-	| "int8"
-	| "uint8"
-	| "int16"
-	| "uint16"
-	| "int32"
-	| "uint32";
-
-interface JTDType {
-	type: JTDPrimitive;
-}
-
-interface JTDEnum {
-	enum: string[];
-}
-
-interface JTDElements {
-	elements: JTDSchema;
-}
-
-interface JTDValues {
-	values: JTDSchema;
-}
-
-interface JTDProperties {
-	properties?: Record<string, JTDSchema>;
-	optionalProperties?: Record<string, JTDSchema>;
-}
-
-interface JTDDiscriminator {
-	discriminator: string;
-	mapping: Record<string, JTDProperties>;
-}
-
-interface JTDRef {
-	ref: string;
-}
-
-interface JTDEmpty {}
-
-type JTDSchema = JTDType | JTDEnum | JTDElements | JTDValues | JTDProperties | JTDDiscriminator | JTDRef | JTDEmpty;
+import type { JTDPrimitive } from "./jtd-utils.js";
+import {
+	isJTDDiscriminator,
+	isJTDElements,
+	isJTDEnum,
+	isJTDProperties,
+	isJTDRef,
+	isJTDType,
+	isJTDValues,
+} from "./jtd-utils.js";
 
 const primitiveMap: Record<JTDPrimitive, string> = {
 	boolean: "boolean",
@@ -69,34 +33,6 @@ const primitiveMap: Record<JTDPrimitive, string> = {
 	uint32: "integer",
 };
 
-function isJTDType(schema: unknown): schema is JTDType {
-	return typeof schema === "object" && schema !== null && "type" in schema;
-}
-
-function isJTDEnum(schema: unknown): schema is JTDEnum {
-	return typeof schema === "object" && schema !== null && "enum" in schema;
-}
-
-function isJTDElements(schema: unknown): schema is JTDElements {
-	return typeof schema === "object" && schema !== null && "elements" in schema;
-}
-
-function isJTDValues(schema: unknown): schema is JTDValues {
-	return typeof schema === "object" && schema !== null && "values" in schema;
-}
-
-function isJTDProperties(schema: unknown): schema is JTDProperties {
-	return typeof schema === "object" && schema !== null && ("properties" in schema || "optionalProperties" in schema);
-}
-
-function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
-	return typeof schema === "object" && schema !== null && "discriminator" in schema;
-}
-
-function isJTDRef(schema: unknown): schema is JTDRef {
-	return typeof schema === "object" && schema !== null && "ref" in schema;
-}
-
 function convertSchema(schema: unknown): unknown {
 	if (schema === null || typeof schema !== "object") {
 		return {};

package/src/tools/jtd-to-typescript.ts

@@ -5,50 +5,16 @@
  * helping models understand expected output structure.
  */
 
-type JTDPrimitive =
-	| "boolean"
-	| "string"
-	| "timestamp"
-	| "float32"
-	| "float64"
-	| "int8"
-	| "uint8"
-	| "int16"
-	| "uint16"
-	| "int32"
-	| "uint32";
-
-interface JTDType {
-	type: JTDPrimitive;
-}
-
-interface JTDEnum {
-	enum: string[];
-}
-
-interface JTDElements {
-	elements: JTDSchema;
-}
-
-interface JTDValues {
-	values: JTDSchema;
-}
-
-interface JTDProperties {
-	properties?: Record<string, JTDSchema>;
-	optionalProperties?: Record<string, JTDSchema>;
-}
-
-interface JTDDiscriminator {
-	discriminator: string;
-	mapping: Record<string, JTDProperties>;
-}
-
-interface JTDRef {
-	ref: string;
-}
-
-type JTDSchema = JTDType | JTDEnum | JTDElements | JTDValues | JTDProperties | JTDDiscriminator | JTDRef | object;
+import type { JTDPrimitive } from "./jtd-utils.js";
+import {
+	isJTDDiscriminator,
+	isJTDElements,
+	isJTDEnum,
+	isJTDProperties,
+	isJTDRef,
+	isJTDType,
+	isJTDValues,
+} from "./jtd-utils.js";
 
 const primitiveMap: Record<JTDPrimitive, string> = {
 	boolean: "boolean",
@@ -64,34 +30,6 @@ const primitiveMap: Record<JTDPrimitive, string> = {
 	uint32: "number",
 };
 
-function isJTDType(schema: unknown): schema is JTDType {
-	return typeof schema === "object" && schema !== null && "type" in schema;
-}
-
-function isJTDEnum(schema: unknown): schema is JTDEnum {
-	return typeof schema === "object" && schema !== null && "enum" in schema && Array.isArray((schema as JTDEnum).enum);
-}
-
-function isJTDElements(schema: unknown): schema is JTDElements {
-	return typeof schema === "object" && schema !== null && "elements" in schema;
-}
-
-function isJTDValues(schema: unknown): schema is JTDValues {
-	return typeof schema === "object" && schema !== null && "values" in schema;
-}
-
-function isJTDProperties(schema: unknown): schema is JTDProperties {
-	return typeof schema === "object" && schema !== null && ("properties" in schema || "optionalProperties" in schema);
-}
-
-function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
-	return typeof schema === "object" && schema !== null && "discriminator" in schema && "mapping" in schema;
-}
-
-function isJTDRef(schema: unknown): schema is JTDRef {
-	return typeof schema === "object" && schema !== null && "ref" in schema;
-}
-
 function convertToTypeScript(schema: unknown, inline = false): string {
 	if (schema === null || schema === undefined || (typeof schema === "object" && Object.keys(schema).length === 0)) {
 		return "unknown";

package/src/tools/jtd-utils.ts

@@ -0,0 +1,102 @@
+/**
+ * JSON Type Definition (JTD) utility types and guards.
+ *
+ * Shared type definitions and type guard functions for JTD schema validation.
+ *
+ * @see https://jsontypedef.com/
+ * @see https://datatracker.ietf.org/doc/html/rfc8927
+ */
+
+export type JTDPrimitive =
+	| "boolean"
+	| "string"
+	| "timestamp"
+	| "float32"
+	| "float64"
+	| "int8"
+	| "uint8"
+	| "int16"
+	| "uint16"
+	| "int32"
+	| "uint32";
+
+export interface JTDType {
+	type: JTDPrimitive;
+}
+
+export interface JTDEnum {
+	enum: string[];
+}
+
+export interface JTDElements {
+	elements: JTDSchema;
+}
+
+export interface JTDValues {
+	values: JTDSchema;
+}
+
+export interface JTDProperties {
+	properties?: Record<string, JTDSchema>;
+	optionalProperties?: Record<string, JTDSchema>;
+}
+
+export interface JTDDiscriminator {
+	discriminator: string;
+	mapping: Record<string, JTDProperties>;
+}
+
+export interface JTDRef {
+	ref: string;
+}
+
+export interface JTDEmpty {}
+
+export type JTDSchema =
+	| JTDType
+	| JTDEnum
+	| JTDElements
+	| JTDValues
+	| JTDProperties
+	| JTDDiscriminator
+	| JTDRef
+	| JTDEmpty;
+
+// Type guards
+
+export function isJTDType(schema: unknown): schema is JTDType {
+	return typeof schema === "object" && schema !== null && "type" in schema;
+}
+
+export function isJTDEnum(schema: unknown): schema is JTDEnum {
+	return typeof schema === "object" && schema !== null && "enum" in schema && Array.isArray(schema.enum);
+}
+
+export function isJTDElements(schema: unknown): schema is JTDElements {
+	return typeof schema === "object" && schema !== null && "elements" in schema;
+}
+
+export function isJTDValues(schema: unknown): schema is JTDValues {
+	return typeof schema === "object" && schema !== null && "values" in schema;
+}
+
+export function isJTDProperties(schema: unknown): schema is JTDProperties {
+	return typeof schema === "object" && schema !== null && ("properties" in schema || "optionalProperties" in schema);
+}
+
+export function isJTDDiscriminator(schema: unknown): schema is JTDDiscriminator {
+	return (
+		typeof schema === "object" &&
+		schema !== null &&
+		"discriminator" in schema &&
+		"mapping" in schema &&
+		typeof schema.discriminator === "string" &&
+		typeof schema.mapping === "object" &&
+		schema.mapping !== null &&
+		!Array.isArray(schema.mapping)
+	);
+}
+
+export function isJTDRef(schema: unknown): schema is JTDRef {
+	return typeof schema === "object" && schema !== null && "ref" in schema;
+}

package/src/tools/notebook.ts

@@ -2,7 +2,7 @@ import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallb
 import { StringEnum } from "@oh-my-pi/pi-ai";
 import type { Component } from "@oh-my-pi/pi-tui";
 import { Text } from "@oh-my-pi/pi-tui";
-import { untilAborted } from "@oh-my-pi/pi-utils";
+import { isEnoent, untilAborted } from "@oh-my-pi/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import type { Theme } from "../modes/theme/theme";
@@ -80,17 +80,12 @@ export class NotebookTool implements AgentTool<typeof notebookSchema, NotebookTo
 		const absolutePath = resolveToCwd(notebook_path, this.session.cwd);
 
 		return untilAborted(signal, async () => {
-			// Check if file exists
-			const file = Bun.file(absolutePath);
-			if (!(await file.exists())) {
-				throw new Error(`Notebook not found: ${notebook_path}`);
-			}
-
 			// Read and parse notebook
 			let notebook: Notebook;
 			try {
-				notebook = await file.json();
-			} catch {
+				notebook = await Bun.file(absolutePath).json();
+			} catch (err) {
+				if (isEnoent(err)) throw new Error(`Notebook not found: ${notebook_path}`);
 				throw new Error(`Invalid JSON in notebook: ${notebook_path}`);
 			}
 

package/src/tools/output-meta.ts

@@ -12,10 +12,10 @@ import type {
 	AgentToolUpdateCallback,
 } 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 { Theme } from "../modes/theme/theme";
+import type { OutputSummary, TruncationResult } from "../session/streaming-output";
+import { formatBytes, wrapBrackets } from "./render-utils";
 import { renderError } from "./tool-errors";
-import type { TruncationResult } from "./truncate";
-import { formatSize } from "./truncate";
 
 /**
  * Truncation metadata for the output notice.
@@ -313,6 +313,44 @@ export function outputMeta(): OutputMetaBuilder {
 // Notice formatting
 // =============================================================================
 
+export function formatFullOutputReference(artifactId: string): string {
+	return `Full output: artifact://${artifactId}`;
+}
+
+export function formatTruncationMetaNotice(truncation: TruncationMeta): string {
+	const range = truncation.shownRange;
+	let notice: string;
+
+	if (range && range.end >= range.start) {
+		notice = `Showing lines ${range.start}-${range.end} of ${truncation.totalLines}`;
+	} else {
+		notice = `Showing ${truncation.outputLines} of ${truncation.totalLines} lines`;
+	}
+
+	if (truncation.truncatedBy === "bytes") {
+		const maxBytes = truncation.maxBytes ?? truncation.outputBytes;
+		notice += ` (${formatBytes(maxBytes)} limit)`;
+	}
+
+	if (truncation.nextOffset != null) {
+		notice += `. Use offset=${truncation.nextOffset} to continue`;
+	}
+
+	if (truncation.artifactId != null) {
+		notice += `. ${formatFullOutputReference(truncation.artifactId)}`;
+	}
+
+	return notice;
+}
+
+/**
+ * Format styled artifact reference with warning color and brackets.
+ * For TUI rendering of truncation warnings.
+ */
+export function formatStyledArtifactReference(artifactId: string, theme: Theme): string {
+	return theme.fg("warning", formatFullOutputReference(artifactId));
+}
+
 /**
  * Format notices from OutputMeta for LLM consumption.
  * Returns empty string if no notices needed.
@@ -324,29 +362,7 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
 
 	// Truncation notice
 	if (meta.truncation) {
-		const t = meta.truncation;
-		const range = t.shownRange;
-		let notice: string;
-
-		if (range && range.end >= range.start) {
-			notice = `Showing lines ${range.start}-${range.end} of ${t.totalLines}`;
-		} else {
-			notice = `Showing ${t.outputLines} of ${t.totalLines} lines`;
-		}
-
-		if (t.truncatedBy === "bytes") {
-			const maxBytes = t.maxBytes ?? t.outputBytes;
-			notice += ` (${formatSize(maxBytes)} limit)`;
-		}
-
-		if (t.nextOffset != null) {
-			notice += `. Use offset=${t.nextOffset} to continue`;
-		}
-		if (t.artifactId != null) {
-			notice += `. Full: artifact://${t.artifactId}`;
-		}
-
-		parts.push(notice);
+		parts.push(formatTruncationMetaNotice(meta.truncation));
 	}
 
 	// Limit notices
@@ -377,6 +393,16 @@ export function formatOutputNotice(meta: OutputMeta | undefined): string {
 	return notice + diagnosticsNotice;
 }
 
+/**
+ * Format a styled truncation warning message.
+ * Returns null if no truncation metadata present.
+ */
+export function formatStyledTruncationWarning(meta: OutputMeta | undefined, theme: Theme): string | null {
+	if (!meta?.truncation) return null;
+	const message = formatTruncationMetaNotice(meta.truncation);
+	return theme.fg("warning", wrapBrackets(message, theme));
+}
+
 // =============================================================================
 // Tool wrapper
 // =============================================================================

package/src/tools/path-utils.ts

@@ -58,15 +58,21 @@ function normalizeAtPrefix(filePath: string): string {
 	return filePath;
 }
 
-export function expandPath(filePath: string): string {
-	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
-	if (normalized === "~") {
-		return os.homedir();
+export function expandTilde(filePath: string, home?: string): string {
+	const h = home ?? os.homedir();
+	if (filePath === "~") return h;
+	if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+		return h + filePath.slice(1);
 	}
-	if (normalized.startsWith("~/")) {
-		return os.homedir() + normalized.slice(1);
+	if (filePath.startsWith("~")) {
+		return path.join(h, filePath.slice(1));
 	}
-	return normalized;
+	return filePath;
+}
+
+export function expandPath(filePath: string): string {
+	const normalized = normalizeUnicodeSpaces(normalizeAtPrefix(filePath));
+	return expandTilde(normalized);
 }
 
 /**