@xopcai/xopc 0.0.426 → 0.0.428

package/dist/src/agent/mcp/connection-setup.js

@@ -1,11 +1,15 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { checkUrlSafety } from "../tools/url-safety.js";
 import { isManagedConnectorServer } from "../../connectors/materialize.js";
-import { prepareNativeMcpConfig } from "./native-mcp.js";
 import { resolveMcpSetupConfig } from "./effective-server.js";
-import { classifyMcpConnectionError } from "./connection-errors.js";
+import { prepareNativeMcpConfig } from "./native-mcp.js";
+import { retryAfter } from "./transport.js";
 import { McpAuthenticationRequiredError, discoverMcpTools, signInNativeMcp } from "./tool-catalog.js";
+import { classifyMcpConnectionError } from "./connection-errors.js";
 import { createHash, randomUUID } from "node:crypto";
+import { lookup } from "node:dns";
+import { Agent } from "undici";
 //#region src/agent/mcp/connection-setup.ts
 init_logger();
 const log = createLogger("McpConnectionSetup");
@@ -14,106 +18,247 @@ function httpUrl(value) {
 	if (!["http:", "https:"].includes(url.protocol) || url.username || url.password) throw new Error("Use an HTTP or HTTPS MCP address without embedded credentials.");
 	return url;
 }
-async function metadata(url, signal) {
+async function metadata(url, endpoint, signal, publicOnly = false) {
+	const sameOrigin = endpoint.origin === url.origin && !publicOnly;
+	if (!sameOrigin && !checkUrlSafety(url.href).safe) return { state: "invalid" };
+	const dispatcher = new Agent({ connect: { lookup(host, options, callback) {
+		lookup(host, { all: true }, (error, addresses) => {
+			if (error) {
+				callback(error, "", 4);
+				return;
+			}
+			if (!sameOrigin && addresses.some((a) => !checkUrlSafety(`http://${a.family === 6 ? `[${a.address}]` : a.address}`).safe)) {
+				callback(/* @__PURE__ */ new Error("Non-public authorization metadata destination"), "", 4);
+				return;
+			}
+			if (options.all) callback(null, addresses);
+			else if (addresses[0]) callback(null, addresses[0].address, addresses[0].family);
+			else callback(/* @__PURE__ */ new Error("No metadata address"), "", 4);
+		});
+	} } });
 	try {
 		const response = await fetch(url, {
 			signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(5e3)]) : AbortSignal.timeout(5e3),
 			redirect: "error",
-			headers: { Accept: "application/json" }
+			headers: { Accept: "application/json" },
+			dispatcher
 		});
-		if (!response.ok) return;
-		const result = await response.json();
-		if (result && typeof result === "object" && !Array.isArray(result)) return result;
-	} catch {
+		if (!response.ok) {
+			await response.body?.cancel();
+			return {
+				retryAt: response.status === 429 || response.status === 503 ? retryAfter(response.headers.get("Retry-After")) ?? Date.now() + 2e3 : void 0,
+				state: response.status === 404 || response.status === 410 ? "absent" : response.status >= 500 || response.status === 429 ? "unreachable" : "invalid"
+			};
+		}
+		const reader = response.body?.getReader();
+		if (!reader) return { state: "invalid" };
+		const decoder = new TextDecoder();
+		let text = "", bytes = 0;
+		try {
+			for (;;) {
+				const chunk = await reader.read();
+				if (chunk.done) break;
+				bytes += chunk.value.byteLength;
+				if (bytes > 1e5) return { state: "invalid" };
+				text += decoder.decode(chunk.value, { stream: true });
+			}
+			text += decoder.decode();
+		} finally {
+			await reader.cancel().catch(() => {});
+			reader.releaseLock();
+		}
+		const data = JSON.parse(text);
+		return data && typeof data === "object" && !Array.isArray(data) ? {
+			state: "valid",
+			data
+		} : { state: "invalid" };
+	} catch (error) {
 		signal?.throwIfAborted();
+		return { state: error instanceof SyntaxError ? "invalid" : "unreachable" };
+	} finally {
+		await dispatcher.close();
 	}
 }
-/** A 401 alone is not evidence that a service supports OAuth. */
-async function advertisesOAuth(config, workspace, serverId, signal) {
-	signal?.throwIfAborted();
-	const loaded = await prepareNativeMcpConfig(config, workspace);
-	signal?.throwIfAborted();
-	const entry = loaded.servers.find((server) => server.name === serverId);
-	if (!entry || !("url" in entry.config)) return false;
+async function authentication(config, workspace, serverId, challenge, options) {
+	const entry = (await prepareNativeMcpConfig(config, workspace)).servers.find((s) => s.name === serverId);
+	if (!entry || !("url" in entry.config)) return {
+		method: "unknown",
+		metadata: "not_checked"
+	};
 	const url = httpUrl(entry.config.url);
-	if (Object.keys(entry.config.headers ?? {}).some((name) => name.toLowerCase() === "authorization")) return false;
-	const response = await fetch(url, {
-		method: "POST",
-		signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(1e4)]) : AbortSignal.timeout(1e4),
-		redirect: "error",
-		headers: {
-			Accept: "application/json, text/event-stream",
-			"Content-Type": "application/json",
-			...entry.config.headers
-		},
-		body: JSON.stringify({
-			jsonrpc: "2.0",
-			id: 1,
-			method: "initialize",
-			params: {
-				protocolVersion: "2025-03-26",
-				capabilities: {},
-				clientInfo: {
-					name: "xopc",
-					version: "1"
-				}
-			}
-		})
-	});
-	const challenge = response.headers.get("WWW-Authenticate") ?? "";
-	await response.body?.cancel();
-	const resourceMetadata = /resource_metadata\s*=\s*"([^"\s]+)"/i.exec(challenge)?.[1];
+	const publicOnly = config.mcp?.servers?.[serverId]?.xopcPublicOnly === true;
+	const allowedIssuer = (value) => {
+		try {
+			if (typeof value !== "string") return false;
+			const issuer = httpUrl(value);
+			return issuer.protocol === "https:" && checkUrlSafety(issuer.href).safe || !publicOnly && issuer.origin === url.origin && [
+				"localhost",
+				"127.0.0.1",
+				"[::1]"
+			].includes(issuer.hostname);
+		} catch {
+			return false;
+		}
+	};
+	challenge ??= "";
+	const reference = /resource_metadata\s*=\s*"([^"\s]+)"/i.exec(challenge)?.[1];
 	const candidates = [
-		...resourceMetadata ? [httpUrl(resourceMetadata)] : [],
+		...reference ? [httpUrl(reference)] : [],
 		new URL(`/.well-known/oauth-protected-resource${url.pathname === "/" ? "" : url.pathname}`, url),
 		new URL("/.well-known/oauth-protected-resource", url)
 	];
-	for (const candidate of candidates) {
-		signal?.throwIfAborted();
-		const data = await metadata(candidate, signal);
-		if (data && typeof data.resource === "string" && data.resource === url.href && Array.isArray(data.authorization_servers) && data.authorization_servers.some((value) => {
-			try {
-				return typeof value === "string" && Boolean(httpUrl(value));
-			} catch {
-				return false;
-			}
-		})) return true;
+	let state = "absent";
+	for (const candidate of [...new Map(candidates.map((c) => [c.href, c])).values()]) {
+		options?.signal?.throwIfAborted();
+		options?.diagnostics?.beforeRequest?.({
+			method: "GET",
+			stage: "authorization_metadata"
+		});
+		const result = await metadata(candidate, url, options?.signal, publicOnly);
+		if (result.retryAt) return {
+			method: "unknown",
+			metadata: result.state,
+			retryAt: result.retryAt
+		};
+		if (result.state !== "absent") state = result.state;
+		const data = result.data;
+		if (data && typeof data.resource === "string" && data.resource === url.href && Array.isArray(data.authorization_servers) && data.authorization_servers.some(allowedIssuer)) return {
+			method: "oauth",
+			metadata: "valid"
+		};
+		if (data) state = "invalid";
+	}
+	if (/\bBearer\b/i.test(challenge)) {
+		options?.diagnostics?.beforeRequest?.({
+			method: "GET",
+			stage: "authorization_metadata"
+		});
+		const result = await metadata(new URL("/.well-known/oauth-authorization-server", url), url, options?.signal, publicOnly);
+		if (result.retryAt) return {
+			method: "unknown",
+			metadata: result.state,
+			retryAt: result.retryAt
+		};
+		const data = result.data;
+		if (data && data.issuer === url.origin && allowedIssuer(data.issuer) && typeof data.authorization_endpoint === "string" && typeof data.token_endpoint === "string" && allowedIssuer(data.authorization_endpoint) && allowedIssuer(data.token_endpoint)) return {
+			method: "oauth",
+			metadata: "valid"
+		};
+		if (result.state !== "absent") state = result.data ? "invalid" : result.state;
 	}
-	if (!/\bBearer\b/i.test(challenge)) return false;
-	const authorizationServer = await metadata(new URL("/.well-known/oauth-authorization-server", url), signal);
-	return Boolean(authorizationServer && authorizationServer.issuer === url.origin && typeof authorizationServer.authorization_endpoint === "string" && typeof authorizationServer.token_endpoint === "string");
+	return {
+		method: "unknown",
+		metadata: state
+	};
 }
 async function probeMcpConnection(config, workspace, serverId, options) {
 	config = resolveMcpSetupConfig(config, serverId);
+	const observations = [];
+	let cooldown = 0, requests = 0;
 	try {
 		return {
 			state: "connected",
-			toolCount: (await discoverMcpTools(config, workspace, serverId, options)).length
+			toolCount: (await discoverMcpTools(config, workspace, serverId, {
+				...options,
+				diagnostics: {
+					...options?.diagnostics,
+					probe: true,
+					beforeRequest: (request) => {
+						options?.signal?.throwIfAborted();
+						if (Date.now() < cooldown || requests >= 16) throw new Error("MCP probe request budget or cooldown reached");
+						options?.diagnostics?.beforeRequest?.(request);
+						requests++;
+					},
+					observe: (value) => {
+						observations.push(value);
+						if (value.status === 429 || value.status === 503) cooldown = value.retryAt ?? Date.now() + 2e3;
+						options?.diagnostics?.observe?.(value);
+					}
+				}
+			})).length
 		};
 	} catch (error) {
-		const failed = (cause) => {
-			const errorCode = classifyMcpConnectionError(cause);
-			log.warn({
-				serverId,
-				errorCode
-			}, `MCP connection check failed: ${errorCode}`);
-			return {
-				state: "error",
-				error: cause instanceof Error ? cause.message : String(cause),
-				errorCode
-			};
-		};
 		const server = config.mcp?.servers?.[serverId];
-		const rejectedCredential = /\b401\b|unauthorized|invalid_token/i.test(String(error));
-		const hasCredentials = server?.auth || Object.keys(server?.headers ?? {}).some((name) => name.toLowerCase() === "authorization");
-		if (error instanceof McpAuthenticationRequiredError || server?.url && rejectedCredential && !hasCredentials) try {
-			options?.signal?.throwIfAborted();
-			return { state: await advertisesOAuth(config, workspace, serverId, options?.signal) ? "oauth_required" : "token_required" };
-		} catch (cause) {
-			return failed(cause);
+		const failed = observations.filter((o) => o.status >= 400 && !(o.method === "GET" && o.status === 405 && server?.type !== "sse")).at(-1);
+		const last = failed ?? observations.at(-1);
+		const observation = last ? (({ challenge: _challenge, ...safe }) => safe)(last) : void 0;
+		const category = failed ? classifyMcpConnectionError(`HTTP ${failed.status}`) : classifyMcpConnectionError(error);
+		const hasCredentials = Boolean(server?.auth || Object.keys(server?.headers ?? {}).some((n) => n.toLowerCase() === "authorization") || JSON.stringify(server?.headers ?? {}).includes("xopcSecretRef"));
+		const denied = error instanceof McpAuthenticationRequiredError || category === "access_denied";
+		if (server?.url && denied) {
+			if (hasCredentials) {
+				const rejected = failed?.status === 401 || /\b401\b|invalid_token|unauthorized/i.test(String(error)) || /invalid_token/i.test(failed?.challenge ?? "");
+				return {
+					state: rejected ? "token_required" : "error",
+					errorCode: rejected ? void 0 : "access_denied",
+					observation,
+					auth: {
+						method: "credential",
+						metadata: "not_checked",
+						credential: rejected ? "rejected" : "unknown"
+					},
+					recovery: {
+						kind: "enter_secret",
+						reason: rejected ? "credential_rejected" : "credential_or_permission_refused"
+					}
+				};
+			}
+			try {
+				const auth = await authentication(config, workspace, serverId, last ? last.challenge ?? "" : void 0, options);
+				return {
+					state: auth.method === "oauth" ? "oauth_required" : "auth_unknown",
+					auth: {
+						method: auth.method,
+						metadata: auth.metadata,
+						credential: "missing"
+					},
+					observation,
+					recovery: {
+						kind: auth.retryAt ? "wait" : auth.method === "oauth" ? "authorize" : "choose_auth",
+						...auth.retryAt ? { retryAt: auth.retryAt } : {},
+						reason: auth.metadata
+					}
+				};
+			} catch {
+				options?.signal?.throwIfAborted();
+				return {
+					state: "auth_unknown",
+					auth: {
+						method: "unknown",
+						metadata: "unreachable",
+						credential: "missing"
+					},
+					observation,
+					recovery: {
+						kind: "choose_auth",
+						reason: "metadata_unreachable"
+					}
+				};
+			}
 		}
-		if (server?.url && hasCredentials && /\b(?:401|403)\b|unauthorized|forbidden/i.test(String(error))) return { state: "token_required" };
-		return failed(error);
+		if (category === "rate_limited" || failed?.status === 503) return {
+			state: "error",
+			errorCode: category === "rate_limited" ? category : "network",
+			observation,
+			recovery: {
+				kind: "wait",
+				retryAt: cooldown || Date.now() + 2e3
+			}
+		};
+		const errorCode = /html/i.test(observation?.contentType ?? "") ? "invalid_response" : category;
+		log.warn({
+			serverId,
+			errorCode
+		}, `MCP connection check failed: ${errorCode}`);
+		return {
+			state: "error",
+			errorCode,
+			observation,
+			recovery: {
+				kind: ["not_found", "invalid_response"].includes(errorCode) ? "verify_documented_endpoint" : "report_blocker",
+				reason: errorCode
+			}
+		};
 	}
 }
 const attempts = /* @__PURE__ */ new Map();

package/dist/src/agent/mcp/continuation-guard.d.ts

@@ -0,0 +1,3 @@
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+/** Connecting alone does not authorize reading private MCP resources or invoking business tools. */
+export declare function createMcpSetupContinuationGuard(conversationId: string, discoveryAvailable?: boolean): ExtensionFactory;

package/dist/src/agent/mcp/continuation-guard.js

@@ -0,0 +1,54 @@
+import { findSessionInputByRunId, init_session_input_repository } from "../../storage/sqlite/session-input-repository.js";
+import { getSessionMetadata, init_session_read_repository } from "../../storage/sqlite/session-read-repository.js";
+import { DurableState } from "../../storage/sqlite/durable-state.js";
+import { getEmbeddedExecutionRunId } from "../embedded/execution-context.js";
+//#region src/agent/mcp/continuation-guard.ts
+init_session_input_repository();
+init_session_read_repository();
+/** Connecting alone does not authorize reading private MCP resources or invoking business tools. */
+function createMcpSetupContinuationGuard(conversationId, discoveryAvailable = false) {
+	return (pi) => {
+		if (discoveryAvailable) pi.on("tool_result", (event) => {
+			if (event.isError) return;
+			const content = event.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+			const empty = event.toolName === "codemode" && /searchTools\s*\(/.test(JSON.stringify(event.input)) && /Output:\s*\[\]\s*$/.test(content) || event.toolName === "tool_search" && /no (?:matching |relevant )?tools|0 tools/i.test(content);
+			const runId = getEmbeddedExecutionRunId();
+			const input = runId ? findSessionInputByRunId(conversationId, runId) : void 0;
+			const goal = input?.clientMessageId.startsWith("mcp-setup:") ? new DurableState("mcp.conversation-setup").get(input.clientMessageId.slice(10)) : void 0;
+			if (empty && goal?.phase === "ready") return { content: [...event.content, {
+				type: "text",
+				text: `This is a saved connection continuation. Search tools using the exact namespace mcp__${goal.serverId.replace(/-/g, "_")}, then finish the original objective. Do not restart setup.`
+			}] };
+			if (empty) return { content: [...event.content, {
+				type: "text",
+				text: "No registered tool matches this search. This is not evidence that the requested service cannot be connected. If the user clearly asked to connect a named service, call the available mcp_setup discover {serviceName,purpose} and read tool_manual topic mcp before reporting a blocker or asking for an MCP URL. Do not substitute a different saved service."
+			}] };
+		});
+		pi.on("tool_call", (event) => {
+			if (!event.toolName.startsWith("mcp__") && !["read_mcp_resource", "read_resource"].includes(event.toolName)) return;
+			const runId = getEmbeddedExecutionRunId();
+			if (!runId) return;
+			const input = findSessionInputByRunId(conversationId, runId);
+			if (!input?.clientMessageId.startsWith("mcp-setup:")) return;
+			const goal = new DurableState("mcp.conversation-setup").get(input.clientMessageId.slice(10));
+			if (!goal || goal.phase !== "ready" || goal.transcriptId !== getSessionMetadata(conversationId)?.transcriptId) return {
+				block: true,
+				reason: "MCP setup authorization changed. Return to the current conversation."
+			};
+			if (goal.objective === "connect_only") return {
+				block: true,
+				reason: "The user requested connection only. Describe discovered capabilities without reading private data or invoking business tools."
+			};
+			if (["read_mcp_resource", "read_resource"].includes(event.toolName) && event.input.server !== goal.serverId) return {
+				block: true,
+				reason: "This continuation may read resources only from the newly connected MCP server."
+			};
+			if (event.toolName.startsWith("mcp__") && !event.toolName.startsWith(`mcp__${goal.serverId.replace(/-/g, "_")}__`)) return {
+				block: true,
+				reason: `This continuation may use only the newly connected MCP server ${goal.serverId}. Discover that server's actual tools.`
+			};
+		});
+	};
+}
+//#endregion
+export { createMcpSetupContinuationGuard };

package/dist/src/agent/mcp/continuation-input.d.ts

@@ -0,0 +1,4 @@
+/** Only host-created MCP setup inputs may become hidden continuation context. */
+export declare function getMcpSetupResumeInput(conversationId: string, runId: string): {
+    content: string;
+};

package/dist/src/agent/mcp/continuation-input.js

@@ -0,0 +1,13 @@
+import { init_connection, isXopcDatabaseOpen } from "../../storage/sqlite/connection.js";
+import { findSessionInputByRunId, init_session_input_repository } from "../../storage/sqlite/session-input-repository.js";
+//#region src/agent/mcp/continuation-input.ts
+init_connection();
+init_session_input_repository();
+/** Only host-created MCP setup inputs may become hidden continuation context. */
+function getMcpSetupResumeInput(conversationId, runId) {
+	if (!isXopcDatabaseOpen()) return void 0;
+	const input = findSessionInputByRunId(conversationId, runId);
+	return input?.origin.type === "system" && input.origin.source === "internal" && input.clientMessageId.startsWith("mcp-setup:") ? { content: input.content } : void 0;
+}
+//#endregion
+export { getMcpSetupResumeInput };