@oh-my-pi/pi-coding-agent 15.4.3 → 15.5.0

package/src/lsp/edits.ts

@@ -127,39 +127,92 @@ export async function applyTextEdits(filePath: string, edits: TextEdit[]): Promi
 export async function applyWorkspaceEdit(edit: WorkspaceEdit, cwd: string): Promise<string[]> {
 	const applied: string[] = [];
 
-	// Coalesce all text edits per URI before applying so a single file's edits
-	// are applied in one pass against a single snapshot — multiple TextDocumentEdits
-	// for the same URI would otherwise read stale positions on subsequent writes.
-	const textEditsByUri = flattenWorkspaceTextEdits(edit);
-	for (const [uri, textEdits] of textEditsByUri) {
-		const filePath = uriToFile(uri);
-		await applyTextEdits(filePath, textEdits);
-		applied.push(`Applied ${textEdits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
-	}
-
-	// Resource operations (create/rename/delete) preserve their original order.
 	if (edit.documentChanges) {
+		// Walk documentChanges in original order. Accumulate text edits per-URI and
+		// flush them before any resource op that touches the same URI (or, for folder
+		// rename/delete, any descendant URI) so that renames, creates, and deletes
+		// always see the correct prior file state.
+		const pending = new Map<string, TextEdit[]>();
+
+		const flushUri = async (uri: string) => {
+			const edits = pending.get(uri);
+			if (!edits) return;
+			pending.delete(uri);
+			const filePath = uriToFile(uri);
+			await applyTextEdits(filePath, edits);
+			applied.push(`Applied ${edits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
+		};
+
+		// Flush the exact URI plus every pending descendant (for folder-level
+		// resource ops where the queued edits target child files of the target).
+		const flushSubtree = async (uri: string) => {
+			const prefix = uri.endsWith("/") ? uri : `${uri}/`;
+			const matches: string[] = [];
+			for (const candidate of pending.keys()) {
+				if (candidate === uri || candidate.startsWith(prefix)) matches.push(candidate);
+			}
+			for (const target of matches) {
+				await flushUri(target);
+			}
+		};
+
 		for (const change of edit.documentChanges) {
-			if (!("kind" in change) || !change.kind) continue;
-			if (change.kind === "create") {
-				const createOp = change as CreateFile;
-				const filePath = uriToFile(createOp.uri);
-				await Bun.write(filePath, "");
-				applied.push(`Created ${formatPathRelativeToCwd(filePath, cwd)}`);
-			} else if (change.kind === "rename") {
-				const renameOp = change as RenameFile;
-				const oldPath = uriToFile(renameOp.oldUri);
-				const newPath = uriToFile(renameOp.newUri);
-				await fs.mkdir(path.dirname(newPath), { recursive: true });
-				await fs.rename(oldPath, newPath);
-				applied.push(`Renamed ${formatPathRelativeToCwd(oldPath, cwd)} → ${formatPathRelativeToCwd(newPath, cwd)}`);
-			} else if (change.kind === "delete") {
-				const deleteOp = change as DeleteFile;
-				const filePath = uriToFile(deleteOp.uri);
-				await fs.rm(filePath, { recursive: true });
-				applied.push(`Deleted ${formatPathRelativeToCwd(filePath, cwd)}`);
+			if ("textDocument" in change && change.textDocument && "edits" in change && change.edits) {
+				const tdc = change as TextDocumentEdit;
+				const uri = tdc.textDocument.uri;
+				const textEdits = tdc.edits.filter((e): e is TextEdit => "range" in e && "newText" in e);
+				if (textEdits.length > 0) {
+					const prev = pending.get(uri);
+					if (prev) prev.push(...textEdits);
+					else pending.set(uri, [...textEdits]);
+				}
+			} else if ("kind" in change && change.kind) {
+				if (change.kind === "create") {
+					const createOp = change as CreateFile;
+					await flushUri(createOp.uri);
+					const filePath = uriToFile(createOp.uri);
+					await Bun.write(filePath, "");
+					applied.push(`Created ${formatPathRelativeToCwd(filePath, cwd)}`);
+				} else if (change.kind === "rename") {
+					const renameOp = change as RenameFile;
+					// Per LSP §3.16.2 documentChanges are applied in declared order.
+					// Flush both the source subtree (so prior edits land before the move)
+					// AND the destination subtree (so prior edits land on whatever exists
+					// at newUri before the rename overwrites/replaces it — relevant under
+					// `options.overwrite` and `options.ignoreIfExists`).
+					await flushSubtree(renameOp.oldUri);
+					await flushSubtree(renameOp.newUri);
+					const oldPath = uriToFile(renameOp.oldUri);
+					const newPath = uriToFile(renameOp.newUri);
+					await fs.mkdir(path.dirname(newPath), { recursive: true });
+					await fs.rename(oldPath, newPath);
+					applied.push(
+						`Renamed ${formatPathRelativeToCwd(oldPath, cwd)} → ${formatPathRelativeToCwd(newPath, cwd)}`,
+					);
+				} else if (change.kind === "delete") {
+					const deleteOp = change as DeleteFile;
+					await flushSubtree(deleteOp.uri);
+					const filePath = uriToFile(deleteOp.uri);
+					await fs.rm(filePath, { recursive: true });
+					applied.push(`Deleted ${formatPathRelativeToCwd(filePath, cwd)}`);
+				}
 			}
 		}
+
+		// Flush text edits not followed by a resource op.
+		for (const [uri] of pending) {
+			await flushUri(uri);
+		}
+	} else if (edit.changes) {
+		// Legacy changes-map path: apply all text edits in one pass.
+		const changes = edit.changes;
+		for (const uri in changes) {
+			const textEdits = changes[uri];
+			if (textEdits.length === 0) continue;
+			const filePath = uriToFile(uri);
+			await applyTextEdits(filePath, textEdits);
+			applied.push(`Applied ${textEdits.length} edit(s) to ${formatPathRelativeToCwd(filePath, cwd)}`);
+		}
 	}
 
 	return applied;

package/src/lsp/index.ts

@@ -1,11 +1,18 @@
 import * as fs from "node:fs";
 import path from "node:path";
-import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback } from "@oh-my-pi/pi-agent-core";
+import type {
+	AgentTool,
+	AgentToolContext,
+	AgentToolResult,
+	AgentToolUpdateCallback,
+	ToolApprovalDecision,
+} from "@oh-my-pi/pi-agent-core";
 import { logger, once, prompt, untilAborted } from "@oh-my-pi/pi-utils";
 import type { BunFile } from "bun";
 import { type Theme, theme } from "../modes/theme/theme";
 import lspDescription from "../prompts/tools/lsp.md" with { type: "text" };
 import type { ToolSession } from "../tools";
+import { truncateForPrompt } from "../tools/approval";
 import { formatPathRelativeToCwd, resolveToCwd } from "../tools/path-utils";
 import { ToolAbortError, ToolError, throwIfAborted } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
@@ -79,6 +86,23 @@ import {
 export type { LspServerStatus } from "./client";
 export type { LspToolDetails } from "./types";
 
+/**
+ * LSP actions that do not mutate the workspace or language-server state.
+ * Anything not in this set (rename, code_actions with apply, rename_file,
+ * reload, raw request, etc.) is classified as write-tier.
+ */
+export const LSP_READONLY_ACTIONS: ReadonlySet<string> = new Set([
+	"diagnostics",
+	"definition",
+	"type_definition",
+	"implementation",
+	"references",
+	"hover",
+	"symbols",
+	"status",
+	"capabilities",
+]);
+
 export interface LspStartupServerInfo {
 	name: string;
 	status: "connecting" | "ready" | "error";
@@ -1174,6 +1198,19 @@ export function createLspWritethrough(cwd: string, options?: WritethroughOptions
  */
 export class LspTool implements AgentTool<typeof lspSchema, LspToolDetails, Theme> {
 	readonly name = "lsp";
+	readonly approval = (args: unknown): ToolApprovalDecision => {
+		const rawAction = (args as Partial<LspParams>).action;
+		const action = typeof rawAction === "string" ? rawAction.toLowerCase() : "";
+		return LSP_READONLY_ACTIONS.has(action) ? "read" : "write";
+	};
+	readonly formatApprovalDetails = (args: unknown): string[] => {
+		const params = args as Partial<LspParams>;
+		const lines = [`Action: ${typeof params.action === "string" ? params.action : "(missing)"}`];
+		if (typeof params.file === "string" && params.file.length > 0) {
+			lines.push(`File: ${truncateForPrompt(params.file)}`);
+		}
+		return lines;
+	};
 	readonly label = "LSP";
 	readonly loadMode = "discoverable";
 	readonly summary = "Query LSP (language server) for diagnostics, hover info, and references";

package/src/lsp/utils.ts

@@ -581,7 +581,7 @@ function firstNonWhitespaceColumn(lineText: string): number {
 	return match ? (match.index ?? 0) : 0;
 }
 
-const BARE_IDENTIFIER_RE = /^[A-Za-z_][\w]*$/;
+const BARE_IDENTIFIER_RE = /^[$A-Za-z_][\w$]*$/;
 const IDENTIFIER_CHAR_RE = /[A-Za-z0-9_$]/;
 
 function findSymbolMatchIndexes(lineText: string, symbol: string, caseInsensitive = false): number[] {

package/src/main.ts

@@ -529,6 +529,7 @@ async function buildSessionOptions(
 ): Promise<{ options: CreateAgentSessionOptions }> {
 	const options: CreateAgentSessionOptions = {
 		cwd: parsed.cwd ?? getProjectDir(),
+		autoApprove: parsed.autoApprove ?? false,
 	};
 
 	// Auto-discover SYSTEM.md if no CLI system prompt provided
@@ -769,6 +770,11 @@ export async function runRootCommand(
 
 	const cwd = getProjectDir();
 	const settingsInstance = deps.settings ?? (await logger.time("settings:init", Settings.init, { cwd }));
+	if (parsedArgs.approvalMode) {
+		// Runtime override (not persisted): every settings.get("tools.approvalMode") downstream
+		// sees this value. The wrapper still honours --auto-approve / --yolo on top of it.
+		settingsInstance.override("tools.approvalMode", parsedArgs.approvalMode);
+	}
 	if (parsedArgs.mode === "rpc" || parsedArgs.mode === "rpc-ui" || parsedArgs.mode === "acp") {
 		applyRpcDefaultSettingOverrides(settingsInstance);
 	}

package/src/mcp/client.ts

@@ -6,6 +6,7 @@
 import * as path from "node:path";
 import * as url from "node:url";
 import { getProjectDir, logger, withTimeout } from "@oh-my-pi/pi-utils";
+import { describeMCPTimeout, isMCPTimeoutEnabled, resolveMCPTimeoutMs } from "./timeout";
 import { createHttpTransport } from "./transports/http";
 import { createStdioTransport } from "./transports/stdio";
 import type {
@@ -39,9 +40,6 @@ import type {
 /** MCP protocol version we support */
 const PROTOCOL_VERSION = "2025-03-26";
 
-/** Default connection timeout in ms */
-const CONNECTION_TIMEOUT_MS = 30_000;
-
 /** Client info sent during initialization */
 const CLIENT_INFO = {
 	name: "omp-coding-agent",
@@ -128,7 +126,8 @@ async function initializeConnection(
 
 /**
  * Connect to an MCP server.
- * Has a 30 second timeout to prevent blocking startup.
+ * Has a 30 second timeout by default to prevent blocking startup.
+ * Set OMP_MCP_TIMEOUT_MS=0 to disable MCP client-side timeouts.
  */
 export async function connectToServer(
 	name: string,
@@ -139,7 +138,7 @@ export async function connectToServer(
 		onRequest?: (method: string, params: unknown) => Promise<unknown>;
 	},
 ): Promise<MCPServerConnection> {
-	const timeoutMs = config.timeout ?? CONNECTION_TIMEOUT_MS;
+	const timeoutMs = resolveMCPTimeoutMs(config.timeout);
 	let transport: MCPTransport | undefined;
 
 	const connect = async (): Promise<MCPServerConnection> => {
@@ -180,10 +179,13 @@ export async function connectToServer(
 	};
 
 	try {
+		if (!isMCPTimeoutEnabled(timeoutMs)) {
+			return await connect();
+		}
 		return await withTimeout(
 			connect(),
 			timeoutMs,
-			`Connection to MCP server "${name}" timed out after ${timeoutMs}ms`,
+			`Connection to MCP server "${name}" timed out after ${describeMCPTimeout(timeoutMs)}`,
 			options?.signal,
 		);
 	} catch (error) {

package/src/mcp/oauth-discovery.ts

@@ -17,22 +17,23 @@ export interface AuthDetectionResult {
 	authType?: "oauth" | "apikey" | "unknown";
 	oauth?: OAuthEndpoints;
 	authServerUrl?: string;
+	resourceMetadataUrl?: string;
 	message?: string;
 }
 
-function parseMcpAuthServerUrl(errorMessage: string): string | undefined {
+function parseMcpAuthServerUrl(errorMessage: string, serverUrl?: string): string | undefined {
 	const match = errorMessage.match(/Mcp-Auth-Server:\s*([^;\]\s]+)/i);
 	if (!match?.[1]) return undefined;
 
 	try {
-		return new URL(match[1]).toString();
+		return new URL(match[1], serverUrl).toString();
 	} catch {
 		return undefined;
 	}
 }
 
-export function extractMcpAuthServerUrl(error: Error): string | undefined {
-	return parseMcpAuthServerUrl(error.message);
+export function extractMcpAuthServerUrl(error: Error, serverUrl?: string): string | undefined {
+	return parseMcpAuthServerUrl(error.message, serverUrl);
 }
 
 /**
@@ -189,12 +190,15 @@ export function extractOAuthEndpoints(error: Error): OAuthEndpoints | null {
  * Analyze an error to determine authentication requirements.
  * Returns structured info about what auth is needed.
  */
-export function analyzeAuthError(error: Error): AuthDetectionResult {
+export function analyzeAuthError(error: Error, serverUrl?: string): AuthDetectionResult {
 	if (!detectAuthError(error)) {
 		return { requiresAuth: false };
 	}
 
-	const authServerUrl = extractMcpAuthServerUrl(error);
+	const authServerUrl = extractMcpAuthServerUrl(error, serverUrl);
+	// Extract resource_metadata URL from challenge entries in error message
+	const resourceMetaMatch = error.message.match(/resource_metadata\s*=\s*"([^"]+)"/i);
+	const resourceMetadataUrl = resourceMetaMatch?.[1];
 
 	// Try to extract OAuth endpoints
 	const oauth = extractOAuthEndpoints(error);
@@ -205,6 +209,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 			authType: "oauth",
 			oauth,
 			authServerUrl,
+			resourceMetadataUrl,
 			message: "Server requires OAuth authentication. Launching authorization flow...",
 		};
 	}
@@ -221,6 +226,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 			requiresAuth: true,
 			authType: "apikey",
 			authServerUrl,
+			resourceMetadataUrl,
 			message: "Server requires API key authentication.",
 		};
 	}
@@ -230,6 +236,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 		requiresAuth: true,
 		authType: "unknown",
 		authServerUrl,
+		resourceMetadataUrl,
 		message: "Server requires authentication but type could not be determined.",
 	};
 }
@@ -241,6 +248,7 @@ export function analyzeAuthError(error: Error): AuthDetectionResult {
 export async function discoverOAuthEndpoints(
 	serverUrl: string,
 	authServerUrl?: string,
+	resourceMetadataUrl?: string,
 ): Promise<OAuthEndpoints | null> {
 	const wellKnownPaths = [
 		"/.well-known/oauth-authorization-server",
@@ -250,9 +258,44 @@ export async function discoverOAuthEndpoints(
 		"/.mcp/auth",
 		"/authorize", // Some MCP servers expose OAuth config here
 	];
-	const urlsToQuery = [authServerUrl, serverUrl].filter((value): value is string => Boolean(value));
+	const urlsToQuery: string[] = [];
 	const visitedAuthServers = new Set<string>();
 
+	// Step 1: If a resource_metadata URL was provided, fetch it to discover auth servers.
+	// This follows the RFC 9728 chain: resource_metadata → authorization_servers.
+	if (resourceMetadataUrl && !visitedAuthServers.has(resourceMetadataUrl)) {
+		visitedAuthServers.add(resourceMetadataUrl);
+		try {
+			const metaResp = await fetch(resourceMetadataUrl, {
+				method: "GET",
+				headers: { Accept: "application/json" },
+				redirect: "follow",
+			});
+			if (metaResp.ok) {
+				const meta = (await metaResp.json()) as Record<string, unknown>;
+				const authServers = Array.isArray(meta.authorization_servers)
+					? meta.authorization_servers.filter((entry): entry is string => typeof entry === "string")
+					: [];
+				for (const s of authServers) {
+					if (!visitedAuthServers.has(s)) {
+						urlsToQuery.push(s);
+						visitedAuthServers.add(s);
+					}
+				}
+			}
+		} catch {
+			// Ignore errors, continue to try explicit URLs
+		}
+	}
+
+	// Step 2: Add explicit authServerUrl and serverUrl (deduped against visited)
+	for (const url of [authServerUrl, serverUrl].filter((v): v is string => Boolean(v))) {
+		if (!visitedAuthServers.has(url)) {
+			urlsToQuery.push(url);
+			visitedAuthServers.add(url);
+		}
+	}
+
 	const findEndpoints = (metadata: Record<string, unknown>): OAuthEndpoints | null => {
 		if (metadata.authorization_endpoint && metadata.token_endpoint) {
 			const scopesSupported = Array.isArray(metadata.scopes_supported)
@@ -311,39 +354,84 @@ export async function discoverOAuthEndpoints(
 	};
 
 	for (const baseUrl of urlsToQuery) {
-		visitedAuthServers.add(baseUrl);
 		for (const path of wellKnownPaths) {
-			try {
-				const url = new URL(path, baseUrl);
-				const response = await fetch(url.toString(), {
-					method: "GET",
-					headers: { Accept: "application/json" },
-				});
-
-				if (response.ok) {
-					const metadata = (await response.json()) as Record<string, unknown>;
-					const endpoints = findEndpoints(metadata);
-					if (endpoints) return endpoints;
-
-					if (path === "/.well-known/oauth-protected-resource") {
-						const authServers = Array.isArray(metadata.authorization_servers)
-							? metadata.authorization_servers.filter((entry): entry is string => typeof entry === "string")
-							: [];
-
-						for (const discoveredAuthServer of authServers) {
-							if (visitedAuthServers.has(discoveredAuthServer)) {
-								continue;
+			// Try each well-known path at both the absolute origin and relative
+			const urlsToTry = buildWellKnownUrls(path, baseUrl);
+			for (const url of urlsToTry) {
+				try {
+					const response = await fetch(url.toString(), {
+						method: "GET",
+						headers: { Accept: "application/json" },
+						redirect: "follow",
+					});
+
+					if (response.ok) {
+						const metadata = (await response.json()) as Record<string, unknown>;
+						const endpoints = findEndpoints(metadata);
+						if (endpoints) return endpoints;
+
+						if (path === "/.well-known/oauth-protected-resource") {
+							const authServers = Array.isArray(metadata.authorization_servers)
+								? metadata.authorization_servers.filter((entry): entry is string => typeof entry === "string")
+								: [];
+
+							for (const discoveredAuthServer of authServers) {
+								if (visitedAuthServers.has(discoveredAuthServer)) {
+									continue;
+								}
+								const discovered = await discoverOAuthEndpoints(serverUrl, discoveredAuthServer);
+								if (discovered) return discovered;
 							}
-							const discovered = await discoverOAuthEndpoints(serverUrl, discoveredAuthServer);
-							if (discovered) return discovered;
 						}
 					}
+				} catch {
+					// Ignore errors, try next path
 				}
-			} catch {
-				// Ignore errors, try next path
 			}
 		}
 	}
 
 	return null;
 }
+
+function buildWellKnownUrls(wellKnownPath: string, baseUrl: string): URL[] {
+	let parsed: URL;
+	try {
+		parsed = new URL(baseUrl);
+	} catch {
+		return [];
+	}
+
+	const absUrl = new URL(wellKnownPath, parsed);
+	if (!wellKnownPath.startsWith("/")) return [absUrl];
+
+	const normalizedPath = parsed.pathname.replace(/\/$/, "");
+	const lastSlash = normalizedPath.lastIndexOf("/");
+	// Bare origin (no path beyond "/") — only the origin-root candidate applies.
+	if (lastSlash < 0) return [absUrl];
+
+	// Path-prefixed well-known (common for gateways with sub-path routing).
+	// Multi-segment paths drop the trailing segment (typically the MCP endpoint);
+	// single-segment paths (lastSlash === 0) are themselves the gateway prefix.
+	const prefixPath = lastSlash === 0 ? normalizedPath : normalizedPath.slice(0, lastSlash);
+	const relUrl = new URL(wellKnownPath.slice(1), `${parsed.origin}${prefixPath}/`);
+
+	const candidates: URL[] = [absUrl];
+	const seen = new Set<string>([absUrl.href]);
+	const push = (u: URL): void => {
+		if (!seen.has(u.href)) {
+			candidates.push(u);
+			seen.add(u.href);
+		}
+	};
+	push(relUrl);
+
+	// RFC 8414 §3.1 path-ful issuer form: /.well-known/<suffix>/<issuer-path>.
+	// Only meaningful for well-known metadata documents.
+	if (wellKnownPath.startsWith("/.well-known/")) {
+		const pathfulUrl = new URL(`${wellKnownPath}${normalizedPath}`, parsed.origin);
+		push(pathfulUrl);
+	}
+
+	return candidates;
+}

package/src/mcp/oauth-flow.ts

@@ -324,23 +324,51 @@ export class MCPOAuthFlow extends OAuthCallbackFlow {
 	}
 
 	async #resolveRegistrationEndpoint(): Promise<string | null> {
+		const authorizationUrl = new URL(this.config.authorizationUrl);
+
+		// origin-root well-known; most servers serve metadata here.
+		const rootUrl = new URL("/.well-known/oauth-authorization-server", authorizationUrl.origin).toString();
+		const endpoint = await this.#tryWellKnownForRegistration(rootUrl);
+		if (endpoint) return endpoint;
+
+		// path-prefixed well-known for gateways (e.g. https://gateway.example.com/my-service/).
+		const normalizedPath = authorizationUrl.pathname.replace(/\/$/, "");
+		const lastSlash = normalizedPath.lastIndexOf("/");
+		// Bare-origin authorization URL — nothing further to try.
+		if (lastSlash < 0) return null;
+
+		// Single-segment paths are the gateway prefix itself; multi-segment paths
+		// drop the trailing segment (typically a service endpoint).
+		const prefixPath = lastSlash === 0 ? normalizedPath : normalizedPath.slice(0, lastSlash);
+		const prefixedUrl = new URL(
+			".well-known/oauth-authorization-server",
+			`${authorizationUrl.origin}${prefixPath}/`,
+		).toString();
+		const prefixedEndpoint = await this.#tryWellKnownForRegistration(prefixedUrl);
+		if (prefixedEndpoint) return prefixedEndpoint;
+
+		// RFC 8414 §3.1 path-ful issuer form: /.well-known/oauth-authorization-server/<path>.
+		const pathfulUrl = new URL(
+			`/.well-known/oauth-authorization-server${normalizedPath}`,
+			authorizationUrl.origin,
+		).toString();
+		return await this.#tryWellKnownForRegistration(pathfulUrl);
+	}
+
+	async #tryWellKnownForRegistration(wellKnownUrl: string): Promise<string | null> {
 		try {
-			const authorizationEndpoint = new URL(this.config.authorizationUrl);
-			const metadataUrl = new URL("/.well-known/oauth-authorization-server", authorizationEndpoint.origin);
-			const response = await fetch(metadataUrl.toString(), {
+			const response = await fetch(wellKnownUrl, {
 				method: "GET",
 				headers: { Accept: "application/json" },
 			});
-
 			if (!response.ok) return null;
 			const metadata = (await response.json()) as { registration_endpoint?: string };
 			if (metadata.registration_endpoint && metadata.registration_endpoint.trim() !== "") {
 				return metadata.registration_endpoint;
 			}
 		} catch {
-			// Ignore metadata discovery failures.
+			// Ignore fetch/parse failures.
 		}
-
 		return null;
 	}
 

package/src/mcp/timeout.ts

@@ -0,0 +1,59 @@
+import { logger } from "@oh-my-pi/pi-utils";
+
+const DEFAULT_MCP_TIMEOUT_MS = 30_000;
+const MCP_TIMEOUT_ENV = "OMP_MCP_TIMEOUT_MS";
+
+let neverAbortController: AbortController | undefined;
+
+export function resolveMCPTimeoutMs(configTimeout?: number): number {
+	const raw = Bun.env[MCP_TIMEOUT_ENV]?.trim();
+	if (raw) {
+		const value = Number(raw);
+		if (Number.isFinite(value) && value >= 0) return value;
+		logger.warn("Ignoring invalid OMP_MCP_TIMEOUT_MS env value; expected a non-negative number", {
+			value: raw,
+		});
+	}
+	return configTimeout ?? DEFAULT_MCP_TIMEOUT_MS;
+}
+
+export function isMCPTimeoutEnabled(timeoutMs: number): boolean {
+	return timeoutMs > 0;
+}
+
+export function describeMCPTimeout(timeoutMs: number): string {
+	return isMCPTimeoutEnabled(timeoutMs) ? `${timeoutMs}ms` : "disabled";
+}
+
+export function getNeverAbortSignal(): AbortSignal {
+	neverAbortController ??= new AbortController();
+	return neverAbortController.signal;
+}
+
+export function createMCPTimeout(
+	timeoutMs: number,
+	signal?: AbortSignal,
+): {
+	signal?: AbortSignal;
+	clear: () => void;
+	isTimeoutAbort: (error: unknown) => boolean;
+} {
+	if (!isMCPTimeoutEnabled(timeoutMs)) {
+		return {
+			signal,
+			clear: () => {},
+			isTimeoutAbort: () => false,
+		};
+	}
+
+	const abortController = new AbortController();
+	const timeoutId = setTimeout(() => abortController.abort(), timeoutMs);
+	const operationSignal = signal ? AbortSignal.any([signal, abortController.signal]) : abortController.signal;
+
+	return {
+		signal: operationSignal,
+		clear: () => clearTimeout(timeoutId),
+		isTimeoutAbort: error =>
+			error instanceof Error && error.name === "AbortError" && abortController.signal.aborted && !signal?.aborted,
+	};
+}