@oh-my-pi/pi-coding-agent 17.0.1 → 17.0.3

package/src/tools/bash.ts

@@ -177,6 +177,8 @@ export interface BashToolDetails {
 	wallTimeMs?: number;
 	/** Exit code of a command that ran to completion but failed (non-zero). */
 	exitCode?: number;
+	/** True when the command was killed by its timeout deadline (not a failure). */
+	timedOut?: boolean;
 	terminalId?: string;
 	async?: {
 		state: "running" | "completed" | "failed";
@@ -208,10 +210,6 @@ function normalizeResultOutput(result: BashResult | BashInteractiveResult): stri
 	return result.output || "";
 }
 
-function isInteractiveResult(result: BashResult | BashInteractiveResult): result is BashInteractiveResult {
-	return "timedOut" in result;
-}
-
 function normalizeBashEnv(env: Record<string, string> | undefined): Record<string, string> | undefined {
 	if (!env || Object.keys(env).length === 0) return undefined;
 	const normalized: Record<string, string> = {};
@@ -439,12 +437,15 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 	}
 
 	/**
-	 * Throw for outcomes that are *not* a completed command: user/timeout
-	 * aborts and a missing exit status. The foreground and bridge callers plus
-	 * the async job manager rely on these throwing so cancellations surface as
-	 * aborts and jobs are recorded as failed. A definite non-zero exit is a
-	 * completed command that failed; #buildCompletedResult surfaces it as an
-	 * error *result* (carrying execution details) rather than a throw.
+	 * Throw for outcomes that are *not* a completed command: user aborts and a
+	 * missing exit status. Timeouts are handled separately by
+	 * #buildCompletedResult, which returns a non-throwing error result with
+	 * details.timedOut=true so the renderer can show a warning border. The
+	 * foreground and bridge callers plus the async job manager rely on these
+	 * throwing so cancellations surface as aborts and jobs are recorded as
+	 * failed. A definite non-zero exit is a completed command that failed;
+	 * #buildCompletedResult surfaces it as an error *result* (carrying
+	 * execution details) rather than a throw.
 	 */
 	#throwIfUnfinished(
 		result: BashResult | BashInteractiveResult,
@@ -452,13 +453,14 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		outputText: string,
 	): void {
 		if (result.cancelled) {
-			// executeBash output already carries a `[Command cancelled]` notice from
-			// the sink; PTY/bridge interactive output does not, so annotate it here.
+			// Local executor output already carries a leading `[Command cancelled]`
+			// notice from the sink; PTY/bridge output does not, so annotate only
+			// the latter.
 			const out = normalizeResultOutput(result);
-			const annotated = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out;
+			const annotated = out.startsWith("[Command cancelled]") ? out : out ? `${out}\n\n[Command aborted]` : out;
 			throw new ToolError(annotated || "Command aborted");
 		}
-		if (isInteractiveResult(result) && result.timedOut) {
+		if (result.timedOut === true) {
 			const out = normalizeResultOutput(result);
 			const message =
 				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
@@ -496,8 +498,12 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) outputLines.push("", formatExitCodeNotice(exitCode));
 		const outputText = outputLines.join("\n");
 
-		// Aborts / timeouts / missing-status still propagate as thrown errors.
-		this.#throwIfUnfinished(result, timeoutSec, outputText);
+		// Timeouts are not failures — the command ran its course. Return an error
+		// result (isError=true for the model) but flag timedOut so the renderer
+		// uses a warning border instead of error red. Both interactive and
+		// non-interactive results carry an explicit `timedOut` field from the
+		// executor/PTY layer.
+		const isTimeout = result.timedOut === true;
 
 		const details: BashToolDetails = {};
 		if (timeoutSec === undefined) {
@@ -517,6 +523,29 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 		if (failedExit) {
 			details.exitCode = exitCode;
 		}
+
+		if (isTimeout) {
+			details.timedOut = true;
+			const message =
+				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
+			// executeBash has already emitted this leading sink notice. PTY output
+			// has not, so provide the LLM-facing annotation exactly once.
+			if (!normalizeResultOutput(result).startsWith(`[${message}]\n`)) {
+				outputLines.push("", `[${message}]`);
+			}
+			const timeoutOutputText = await enforceInlineByteCap(outputLines.join("\n"), {
+				saveArtifact: full => saveBashOriginalArtifact(this.session, full),
+			});
+			return toolResult(details)
+				.text(timeoutOutputText)
+				.truncationFromSummary(result, { direction: "tail" })
+				.error()
+				.done();
+		}
+
+		// Non-timeout cancellations and missing exit status still propagate as thrown errors.
+		this.#throwIfUnfinished(result, timeoutSec, outputText);
+
 		// Final defense at the tool-result boundary: no bash path (client bridge,
 		// head-retention spill, minimizer miss) may emit more than
 		// ~DEFAULT_MAX_BYTES inline. No-op for already-bounded output.
@@ -992,12 +1021,8 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 								outputLines: current.output.length > 0 ? current.output.split("\n").length : 0,
 								outputBytes: current.output.length,
 							};
-							return this.#buildCompletedResult(timedOutResult, timeoutSec, {
-								requestedTimeoutSec,
-								notices: pendingNotices,
-								terminalId: handle.terminalId,
-								wallTimeMs: performance.now() - bridgeWallTimeStart,
-							});
+							this.#throwIfUnfinished(timedOutResult, timeoutSec, this.#formatResultOutput(timedOutResult));
+							throw new ToolError("Command timed out");
 						}
 
 						if (raced.kind === "exit") {
@@ -1102,20 +1127,27 @@ export class BashTool implements AgentTool<typeof bashSchemaBase | typeof bashSc
 				});
 		const wallTimeMs = performance.now() - wallTimeStart;
 		if (result.cancelled) {
-			const out = normalizeResultOutput(result);
-			// PTY output carries no cancel/timeout notice of its own; annotate so
-			// the model can tell an abort from a plain failure.
-			const message = isInteractiveResult(result) && out ? `${out}\n\n[Command aborted]` : out || "Command aborted";
-			if (signal?.aborted) {
-				throw new ToolAbortError(message);
+			// A cancelled result is either a timeout (the command's deadline fired)
+			// or a user/system abort. Timeouts are handled by #buildCompletedResult
+			// which returns a non-throwing error result with details.timedOut=true
+			// so the renderer can show a warning border instead of error red.
+			// Both interactive and non-interactive results carry an explicit
+			// `timedOut` field from the executor/PTY layer.
+			const isTimeout = result.timedOut === true;
+			if (!isTimeout) {
+				const out = normalizeResultOutput(result);
+				// The local executor already prepends `[Command cancelled]`; PTY
+				// output does not, so preserve one cancellation notice in either case.
+				const message = out.startsWith("[Command cancelled]")
+					? out
+					: out
+						? `${out}\n\n[Command aborted]`
+						: "Command aborted";
+				if (signal?.aborted) {
+					throw new ToolAbortError(message);
+				}
+				throw new ToolError(message);
 			}
-			throw new ToolError(message);
-		}
-		if (isInteractiveResult(result) && result.timedOut) {
-			const out = normalizeResultOutput(result);
-			const message =
-				timeoutSec === undefined ? "Command timed out" : `Command timed out after ${timeoutSec} seconds`;
-			throw new ToolError(out ? `${out}\n\n[${message}]` : message);
 		}
 		return this.#buildCompletedResult(result, timeoutSec, {
 			requestedTimeoutSec,
@@ -1253,6 +1285,8 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 			const isError = result.isError === true;
 			const isPartial = options.isPartial === true;
 			const success = !isPartial && !isError;
+			const details = result.details;
+			const isTimeout = details?.timedOut === true;
 			const header =
 				config.showHeader === false
 					? undefined
@@ -1263,12 +1297,11 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 										title: config.resolveTitle(args, options),
 									}
 								: {
-										icon: isPartial ? "pending" : "error",
+										icon: isPartial ? "pending" : isTimeout ? "warning" : "error",
 										title: config.resolveTitle(args, options),
 									},
 							uiTheme,
 						);
-			const details = result.details;
 			const outputBlock = new CachedOutputBlock();
 
 			// Per-instance cache for the expensive inner lines computation. Mirrors
@@ -1408,7 +1441,7 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					const framed = outputBlock.render(
 						{
 							header,
-							state: isPartial ? "pending" : isError ? "error" : "success",
+							state: isPartial ? "pending" : isError ? (isTimeout ? "warning" : "error") : "success",
 							sections: [
 								{
 									// Viewport-sized tail window in every state — streaming and final

package/src/tools/essential-tools.ts

@@ -0,0 +1,45 @@
+/**
+ * Canonical set of built-in tools that must stay top-level.
+ *
+ * These are the coding essentials the model always needs directly in its
+ * callable schema. `read`/`write` are additionally the `xd://` transport
+ * (`read xd://` lists devices, `write xd://<tool>` executes them), so demoting
+ * them under xdev makes every mounted device unreachable.
+ *
+ * Adapter boundaries (extension `registerTool`, SDK custom tools, RPC host
+ * tools) default an omitted `loadMode` to `"discoverable"`. A UI-only
+ * re-register of a built-in — e.g. wrapping `read`/`write`/`bash`/`edit`/`glob`
+ * to customize rendering — would then silently demote it to `discoverable` and,
+ * with `tools.xdev` on, unmount it from the top-level schema (issue #5764).
+ * {@link defaultLoadModeForToolName} pins these names to `"essential"` when the
+ * definition omits `loadMode`, so re-registering a built-in never demotes it.
+ */
+import type { ToolLoadMode } from "@oh-my-pi/pi-agent-core";
+
+/**
+ * Built-in tool names whose classes declare `loadMode = "essential"`. Kept in
+ * sync with the tool classes by `essential-tools.test.ts` (drift guard).
+ */
+export const ESSENTIAL_BUILTIN_TOOL_NAMES: Record<string, true> = {
+	read: true,
+	write: true,
+	bash: true,
+	edit: true,
+	glob: true,
+	eval: true,
+	task: true,
+	hub: true,
+	learn: true,
+	manage_skill: true,
+};
+
+/**
+ * Resolve a tool's presentation mode at an adapter boundary. An explicit
+ * `declared` mode always wins. When omitted, known essential built-in names
+ * default to `"essential"` (so a re-register never demotes them); everything
+ * else defaults to `"discoverable"`.
+ */
+export function defaultLoadModeForToolName(name: string, declared?: ToolLoadMode): ToolLoadMode {
+	if (declared) return declared;
+	return name in ESSENTIAL_BUILTIN_TOOL_NAMES ? "essential" : "discoverable";
+}

package/src/tools/fetch.ts

@@ -7,7 +7,6 @@ import type { FetchImpl, ImageContent, TextContent } from "@oh-my-pi/pi-ai";
 import { htmlToMarkdown } from "@oh-my-pi/pi-natives";
 import { type Component, Text } from "@oh-my-pi/pi-tui";
 import { $which, ptree, truncate } from "@oh-my-pi/pi-utils";
-import { LRUCache } from "lru-cache/raw";
 import type { Settings } from "../config/settings";
 import { readEditableNotebookText } from "../edit/notebook";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types";
@@ -19,6 +18,7 @@ import { renderStatusLine, urlHyperlink } from "../tui";
 import { CachedOutputBlock, markFramedBlockComponent } from "../tui/output-block";
 import { webpExclusionForModel } from "../utils/image-loading";
 import { formatDimensionNote, resizeImage } from "../utils/image-resize";
+import { CONVERTIBLE_EXTENSIONS } from "../utils/markit";
 import { ensureTool } from "../utils/tools-manager";
 import { type ArchiveFormat, listArchiveRoot, sniffArchiveFormat } from "../utils/zip";
 import { extractWithParallel, findParallelApiKey, getParallelExtractContent } from "../web/parallel";
@@ -39,21 +39,17 @@ import { clampTimeout } from "./tool-timeouts";
 // =============================================================================
 
 const FETCH_DEFAULT_MAX_LINES = 300;
-// Convertible document types handled by markit.
+// MIME types markit can convert — one per registered converter (pdf, docx,
+// pptx, xlsx, epub). Legacy `application/msword`, `application/vnd.ms-*`, and
+// `application/rtf` are intentionally absent: markit has no converter for them.
 const CONVERTIBLE_MIMES = new Set([
 	"application/pdf",
-	"application/msword",
-	"application/vnd.ms-powerpoint",
-	"application/vnd.ms-excel",
 	"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
 	"application/vnd.openxmlformats-officedocument.presentationml.presentation",
 	"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-	"application/rtf",
 	"application/epub+zip",
 ]);
 
-const CONVERTIBLE_EXTENSIONS = new Set([".pdf", ".doc", ".docx", ".ppt", ".pptx", ".xls", ".xlsx", ".rtf", ".epub"]);
-
 const NOTEBOOK_MIMES = new Set(["application/x-ipynb+json"]);
 const NOTEBOOK_EXTENSIONS = new Set([".ipynb"]);
 
@@ -1553,24 +1549,15 @@ export interface ReadUrlToolDetails {
 	meta?: OutputMeta;
 }
 
-interface ReadUrlCacheEntry {
+interface ReadUrlEntry {
 	artifactId?: string;
 	artifactPath?: string;
-	contentPath?: string;
 	details: ReadUrlToolDetails;
 	image?: FetchImagePayload;
 	output: string;
 	content: string;
 }
 
-const READ_URL_CACHE_MAX_ENTRIES = 100;
-const readUrlCache = new LRUCache<string, ReadUrlCacheEntry>({ max: READ_URL_CACHE_MAX_ENTRIES });
-
-function getReadUrlCacheKey(session: ToolSession, requestedUrl: string, raw: boolean): string {
-	const scope = session.getSessionFile() ?? session.cwd;
-	return `${scope}::${raw ? "raw" : "rendered"}::${normalizeUrl(requestedUrl)}`;
-}
-
 async function findArtifactPath(session: ToolSession, artifactId: string): Promise<string | null> {
 	const artifactsDir = session.getArtifactsDir?.();
 	if (!artifactsDir) return null;
@@ -1584,25 +1571,6 @@ async function findArtifactPath(session: ToolSession, artifactId: string): Promi
 	}
 }
 
-async function readArtifactOutput(session: ToolSession, artifactId: string): Promise<string | null> {
-	const artifactPath = await findArtifactPath(session, artifactId);
-	return artifactPath ? await Bun.file(artifactPath).text() : null;
-}
-
-async function materializeReadUrlCacheEntry(
-	session: ToolSession,
-	entry: ReadUrlCacheEntry,
-): Promise<ReadUrlCacheEntry | null> {
-	if (entry.artifactId) {
-		const artifactOutput = await readArtifactOutput(session, entry.artifactId);
-		if (artifactOutput !== null) {
-			return { ...entry, output: artifactOutput };
-		}
-	}
-
-	return entry.output.length > 0 ? entry : null;
-}
-
 async function persistReadUrlArtifact(
 	session: ToolSession,
 	output: string,
@@ -1613,7 +1581,7 @@ async function persistReadUrlArtifact(
 	return artifact;
 }
 
-async function ensureReadUrlCacheArtifact(session: ToolSession, entry: ReadUrlCacheEntry): Promise<ReadUrlCacheEntry> {
+async function ensureReadUrlArtifact(session: ToolSession, entry: ReadUrlEntry): Promise<ReadUrlEntry> {
 	if (entry.artifactId && entry.artifactPath) return entry;
 	if (entry.artifactId) {
 		const artifactPath = await findArtifactPath(session, entry.artifactId);
@@ -1632,19 +1600,7 @@ function readUrlContentExtension(finalUrl: string): string {
 	}
 }
 
-async function ensureReadUrlContentFile(
-	session: ToolSession,
-	entry: ReadUrlCacheEntry,
-	raw: boolean,
-): Promise<ReadUrlCacheEntry> {
-	if (entry.contentPath) {
-		try {
-			await Bun.file(entry.contentPath).stat();
-			return entry;
-		} catch {
-			// Recreate below when the cached scratch file was removed.
-		}
-	}
+async function materializeReadUrlContent(session: ToolSession, entry: ReadUrlEntry, raw: boolean): Promise<string> {
 	const root = session.getArtifactsDir?.();
 	if (!root) {
 		throw new ToolError("Cannot search URL output because this session cannot materialize read artifacts.");
@@ -1654,20 +1610,16 @@ async function ensureReadUrlContentFile(
 	const hash = Bun.hash(`${raw ? "raw" : "rendered"}:${entry.details.finalUrl}`).toString(36);
 	const contentPath = path.join(dir, `${hash}${readUrlContentExtension(entry.details.finalUrl)}`);
 	await Bun.write(contentPath, entry.content);
-	return { ...entry, contentPath };
-}
-
-function cacheReadUrlEntry(session: ToolSession, requestedUrl: string, raw: boolean, entry: ReadUrlCacheEntry): void {
-	readUrlCache.set(getReadUrlCacheKey(session, requestedUrl, raw), entry);
-	readUrlCache.set(getReadUrlCacheKey(session, entry.details.finalUrl, raw), entry);
+	return contentPath;
 }
 
-async function buildReadUrlCacheEntry(
+/** Fetch and render a URL for a read or search operation. */
+export async function fetchReadUrl(
 	session: ToolSession,
 	params: { path: string; raw?: boolean },
 	signal?: AbortSignal,
 	options?: { ensureArtifact?: boolean },
-): Promise<ReadUrlCacheEntry> {
+): Promise<ReadUrlEntry> {
 	const { path: url, raw = false } = params;
 
 	const effectiveTimeout = clampTimeout("fetch", 30);
@@ -1708,30 +1660,6 @@ async function buildReadUrlCacheEntry(
 	};
 }
 
-export async function loadReadUrlCacheEntry(
-	session: ToolSession,
-	params: { path: string; raw?: boolean },
-	signal?: AbortSignal,
-	options?: { ensureArtifact?: boolean; preferCached?: boolean },
-): Promise<ReadUrlCacheEntry> {
-	const raw = params.raw ?? false;
-	const cached = readUrlCache.get(getReadUrlCacheKey(session, params.path, raw));
-	if (options?.preferCached && cached) {
-		const prepared = options.ensureArtifact ? await ensureReadUrlCacheArtifact(session, cached) : cached;
-		const materialized = await materializeReadUrlCacheEntry(session, prepared);
-		if (materialized) {
-			cacheReadUrlEntry(session, params.path, raw, materialized);
-			return materialized;
-		}
-	}
-
-	const fresh = await buildReadUrlCacheEntry(session, params, signal, {
-		ensureArtifact: options?.ensureArtifact,
-	});
-	cacheReadUrlEntry(session, params.path, raw, fresh);
-	return fresh;
-}
-
 /** Materialize rendered URL body text to a local file for tools that require filesystem paths. */
 export async function materializeReadUrlToFile(
 	session: ToolSession,
@@ -1741,13 +1669,9 @@ export async function materializeReadUrlToFile(
 	if (!session.settings.get("fetch.enabled")) {
 		throw new ToolError("URL reads are disabled by settings.");
 	}
-	const cacheEntry = await loadReadUrlCacheEntry(session, params, signal, { preferCached: true });
-	const materialized = await ensureReadUrlContentFile(session, cacheEntry, params.raw ?? false);
-	cacheReadUrlEntry(session, params.path, params.raw ?? false, materialized);
-	if (!materialized.contentPath) {
-		throw new ToolError("Cannot search URL output because this session cannot materialize read artifacts.");
-	}
-	return { path: materialized.contentPath, details: materialized.details };
+	const entry = await fetchReadUrl(session, params, signal);
+	const contentPath = await materializeReadUrlContent(session, entry, params.raw ?? false);
+	return { path: contentPath, details: entry.details };
 }
 
 function buildUrlReadOutput(result: FetchRenderResult, content: string): string {
@@ -1768,36 +1692,35 @@ export async function executeReadUrl(
 	params: { path: string; raw?: boolean },
 	signal?: AbortSignal,
 ): Promise<AgentToolResult<ReadUrlToolDetails>> {
-	let cacheEntry = await loadReadUrlCacheEntry(session, params, signal, { preferCached: true });
-	const truncation = truncateHead(cacheEntry.output, {
+	let entry = await fetchReadUrl(session, params, signal);
+	const truncation = truncateHead(entry.output, {
 		maxBytes: DEFAULT_MAX_BYTES,
 		maxLines: FETCH_DEFAULT_MAX_LINES,
 	});
 	const needsArtifact = truncation.truncated;
-	if (needsArtifact && !cacheEntry.artifactId) {
-		cacheEntry = await ensureReadUrlCacheArtifact(session, cacheEntry);
-		cacheReadUrlEntry(session, params.path, params.raw ?? false, cacheEntry);
+	if (needsArtifact && !entry.artifactId) {
+		entry = await ensureReadUrlArtifact(session, entry);
 	}
-	const output = needsArtifact ? truncation.content : cacheEntry.output;
+	const output = needsArtifact ? truncation.content : entry.output;
 	const details: ReadUrlToolDetails = {
-		...cacheEntry.details,
-		truncated: Boolean(cacheEntry.details.truncated || needsArtifact),
+		...entry.details,
+		truncated: Boolean(entry.details.truncated || needsArtifact),
 	};
 
 	const contentBlocks: Array<TextContent | ImageContent> = [{ type: "text", text: output }];
-	if (cacheEntry.image) {
-		contentBlocks.push({ type: "image", data: cacheEntry.image.data, mimeType: cacheEntry.image.mimeType });
+	if (entry.image) {
+		contentBlocks.push({ type: "image", data: entry.image.data, mimeType: entry.image.mimeType });
 	}
 
 	const resultBuilder = toolResult(details).content(contentBlocks).sourceUrl(details.finalUrl);
 	if (needsArtifact) {
-		resultBuilder.truncation(truncation, { direction: "head", artifactId: cacheEntry.artifactId });
-	} else if (cacheEntry.details.truncated) {
-		const outputLines = cacheEntry.output.split("\n").length;
-		const outputBytes = Buffer.byteLength(cacheEntry.output, "utf-8");
+		resultBuilder.truncation(truncation, { direction: "head", artifactId: entry.artifactId });
+	} else if (entry.details.truncated) {
+		const outputLines = entry.output.split("\n").length;
+		const outputBytes = Buffer.byteLength(entry.output, "utf-8");
 		const totalBytes = Math.max(outputBytes + 1, MAX_OUTPUT_CHARS + 1);
 		const totalLines = outputLines + 1;
-		resultBuilder.truncationFromText(cacheEntry.output, {
+		resultBuilder.truncationFromText(entry.output, {
 			direction: "tail",
 			totalLines,
 			totalBytes,