@xopcai/xopc 0.0.427 → 0.0.430

package/dist/src/agent/image/generation/runtime.js

@@ -4,12 +4,12 @@ import { assertProviderUsage, init_model_usage } from "../../../providers/model-
 import { PROVIDER_ENV_MAP, init_env_keys } from "../../../providers/env-keys.js";
 import { ImageProviderError, normalizeImageGeometry } from "../../../../packages/image-providers/src/validation.js";
 import "../../../../packages/image-providers/src/index.js";
+import { getImageGenerationProvider, listImageGenerationProviders, listImageGenerationProvidersSummary as listImageGenerationProvidersSummary$1 } from "./provider-registry.js";
 import { describeFailoverError, isFailoverError } from "../../failover-error.js";
 import { buildNoCapabilityModelConfiguredMessage, recordCapabilityCandidateFailure, resolveCapabilityModelCandidates, throwCapabilityGenerationFailure } from "../../media-generation/runtime-shared.js";
 import "../../media-generation/index.js";
 import { parseImageGenerationModelRef } from "./model-ref.js";
 import { validateImageGenerationRequest } from "./validation.js";
-import { getImageGenerationProvider, listImageGenerationProviders, listImageGenerationProvidersSummary as listImageGenerationProvidersSummary$1 } from "./provider-registry.js";
 //#region src/agent/image/generation/runtime.ts
 init_model_usage();
 init_env_keys();

package/dist/src/agent/image/index.js

@@ -1,9 +1,9 @@
+import { getImageGenerationProvider, listImageGenerationProviders } from "./generation/provider-registry.js";
 import { getImageUnderstandingProvider, listImageUnderstandingProviders, registerImageUnderstandingProvider } from "./understanding/provider-registry.js";
 import { resolveImageModelConfigForTool } from "./tool-model-config.js";
 import { describeImages, describeImagesWithFallback } from "./understanding/runtime.js";
 import { modelSupportsVision, resolveImageHandlingStrategy } from "./vision-detection.js";
 import { runWithImageModelFallback } from "./image-model-fallback.js";
 import { loadImageForToolInput } from "./load-image-media.js";
-import { getImageGenerationProvider, listImageGenerationProviders } from "./generation/provider-registry.js";
 import { generateImage, listImageGenerationProvidersSummary } from "./generation/runtime.js";
 export { describeImages, describeImagesWithFallback, generateImage, getImageGenerationProvider, getImageUnderstandingProvider, listImageGenerationProviders, listImageGenerationProvidersSummary, listImageUnderstandingProviders, loadImageForToolInput, modelSupportsVision, registerImageUnderstandingProvider, resolveImageHandlingStrategy, resolveImageModelConfigForTool, runWithImageModelFallback };

package/dist/src/agent/inbound/attachment-pipeline.js

@@ -1,10 +1,10 @@
 import { stripRuntimeUserMessageEnvelope } from "../../../packages/gateway-contract/src/user-message-display.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
 import { readAgentMessageContent } from "../memory/agent-message-access.js";
-import { extractProfileAgentId } from "../../config/agent-profile.js";
-import { isPersonalConversation } from "../../personal-agent/repository.js";
 import { mimeTypeFromMediaPath } from "../../media/store.js";
 import { readMediaReference } from "../../media/media-reference.js";
+import { isPersonalConversation } from "../../personal-agent/repository.js";
+import { extractProfileAgentId } from "../../config/agent-profile.js";
 import { MODEL_IMAGE_MAX_BYTES, MODEL_IMAGE_SOURCE_MAX_BYTES, prepareImageForModel } from "../image/prepare-image-for-model.js";
 import { isImageInboundAttachment } from "../../channels/attachments/attachment-classifiers.js";
 import "../../channels/attachments/inbound-persist.js";

package/dist/src/agent/inbound/inbound-loop.js

@@ -1,10 +1,10 @@
 import { runWithLogContext, updateAsyncLogContext } from "../../utils/logger/context.js";
 import { init_logger } from "../../utils/logger.js";
 import { init_model_usage, withModelUsageOrigin } from "../../providers/model-usage.js";
-import { shouldSkipResetOverlapCommand } from "../../session/reset-triggers.js";
-import { initSessionTurn } from "../../session/init-session-turn.js";
 import { MessageBusShutdownError } from "../../infra/bus/queue.js";
 import "../../infra/bus/index.js";
+import { shouldSkipResetOverlapCommand } from "../../session/reset-triggers.js";
+import { initSessionTurn } from "../../session/init-session-turn.js";
 import { runEmbeddedTurnForSession } from "../embedded/run-for-session.js";
 import { inboundMessageLogRequestId } from "../service-inbound-utils.js";
 //#region src/agent/inbound/inbound-loop.ts

package/dist/src/agent/independent-execution.js

@@ -1,8 +1,8 @@
 import { withoutCloudCreditBudget } from "../providers/xopc-cloud-credit-budget.js";
 import { withoutEmbeddedExecutionSession } from "./embedded/execution-context.js";
-import { withoutDelegationScope } from "./orchestration/delegation-scope.js";
-import { withoutDataToolPermissions } from "./tools/dataBatch.js";
 import { withoutSearchCache } from "./tools/search/cache.js";
+import { withoutDataToolPermissions } from "./tools/dataBatch.js";
+import { withoutDelegationScope } from "./orchestration/delegation-scope.js";
 //#region src/agent/independent-execution.ts
 /** Discard caller-owned execution scopes before resolving the target Agent. */
 function runInIndependentAgentExecution(run) {

package/dist/src/agent/index.js

@@ -1,14 +1,14 @@
-import { resolveTranscriptPolicy } from "./transcript/transcript-policy.js";
-import { dropThinkingBlocks } from "./transcript/thinking.js";
 import { extractToolCallsFromAssistant, extractToolResultId, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist } from "./transcript/tool-call-id.js";
 import { makeMissingToolResult, repairToolUseResultPairing, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolResultDetails } from "./transcript/session-transcript-repair.js";
+import { resolveTranscriptPolicy } from "./transcript/transcript-policy.js";
+import { dropThinkingBlocks } from "./transcript/thinking.js";
 import { applySessionTranscriptHygiene, applySessionTranscriptHygieneForPersistence, applySessionTranscriptHygieneWithPolicy, resolvePolicyForModel, tryApplySessionTranscriptHygiene, tryApplySessionTranscriptHygieneForPersistence } from "./transcript/transcript-hygiene.js";
+import { AgentService } from "./service.js";
 import { createResponseMessage, createSignalMessage, createTaskMessage, isValidIPCMessage } from "./ipc/types.js";
 import { AgentInbox } from "./ipc/inbox.js";
 import { AgentBus } from "./ipc/bus.js";
 import { AgentSocketClient, AgentSocketServer, isSocketAvailable } from "./ipc/socket.js";
 import "./ipc/index.js";
-import { AgentService } from "./service.js";
 import { stripToolMessages } from "./transcript/strip-tool-messages.js";
 import "./transcript/index.js";
 export { AgentBus, AgentInbox, AgentService, AgentSocketClient, AgentSocketServer, applySessionTranscriptHygiene, applySessionTranscriptHygieneForPersistence, applySessionTranscriptHygieneWithPolicy, createResponseMessage, createSignalMessage, createTaskMessage, dropThinkingBlocks, extractToolCallsFromAssistant, extractToolResultId, isSocketAvailable, isValidIPCMessage, makeMissingToolResult, repairToolUseResultPairing, resolvePolicyForModel, resolveTranscriptPolicy, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolMessages, stripToolResultDetails, tryApplySessionTranscriptHygiene, tryApplySessionTranscriptHygieneForPersistence };

package/dist/src/agent/mcp/connection-drafts.d.ts

@@ -1,5 +1,6 @@
 import { type Config } from '../../config/schema.js';
 import { type McpConnectionProbe } from './connection-setup.js';
+import type { McpTransportDiagnostics } from './transport.js';
 export declare function mcpConfigRevision(value: unknown): string;
 export declare class McpDraftError extends Error {
     readonly status: 400 | 404 | 409 | 429 | 500;
@@ -30,7 +31,7 @@ export declare class McpConnectionDrafts {
         serverId: string;
         expiresAt: number;
     }>;
-    probe(owner: string, id: string): Promise<McpConnectionProbe>;
+    probe(owner: string, id: string, diagnostics?: McpTransportDiagnostics): Promise<McpConnectionProbe>;
     authorize(owner: string, id: string, options?: {
         callbackRelayUrl?: string;
     }): import("./connection-setup.js").McpAuthorization;

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

@@ -1,9 +1,9 @@
 import { McpServerSchema, init_schema } from "../../config/schema.js";
-import { getWorkspacePath } from "../../config/workspace-path-helpers.js";
 import { isManagedConnectorServer } from "../../connectors/materialize.js";
 import { createNativeMcpCredentials } from "./credential-store.js";
 import { loadMergedMcpConfig } from "./config.js";
 import { discoverMcpTools } from "./tool-catalog.js";
+import { getWorkspacePath } from "../../config/workspace-path-helpers.js";
 import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "./connection-setup.js";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/agent/mcp/connection-drafts.ts
@@ -84,7 +84,7 @@ var McpConnectionDrafts = class {
 			expiresAt: draft.expiresAt
 		};
 	}
-	async probe(owner, id) {
+	async probe(owner, id, diagnostics) {
 		const draft = this.get(owner, id);
 		this.assertIdle(draft);
 		draft.authorizationId = void 0;
@@ -94,7 +94,8 @@ var McpConnectionDrafts = class {
 		try {
 			const result = await probeMcpConnection(draft.config, draft.workspace, draft.serverId, {
 				credentials: draft.credentials,
-				signal: draft.controller.signal
+				signal: draft.controller.signal,
+				diagnostics
 			});
 			this.get(owner, id);
 			draft.probe = result;

package/dist/src/agent/mcp/connection-setup.d.ts

@@ -1,11 +1,25 @@
 import type { Config } from '../../config/schema.js';
 import { type McpConnectionErrorCode } from './connection-errors.js';
 import { type McpSessionOptions } from './tool-catalog.js';
+import { type McpObservation } from './transport.js';
+export type McpMetadataState = 'valid' | 'absent' | 'unreachable' | 'invalid' | 'not_checked';
+export type McpRecovery = {
+    kind: 'choose_auth' | 'enter_secret' | 'authorize' | 'verify_documented_endpoint' | 'report_blocker' | 'wait';
+    retryAt?: number;
+    reason?: string;
+};
 export type McpConnectionProbe = {
-    state: 'connected' | 'oauth_required' | 'token_required' | 'error';
+    state: 'connected' | 'oauth_required' | 'token_required' | 'auth_unknown' | 'error';
     toolCount?: number;
     error?: string;
     errorCode?: McpConnectionErrorCode;
+    auth?: {
+        method: 'oauth' | 'unknown' | 'credential';
+        metadata: McpMetadataState;
+        credential: 'missing' | 'present' | 'rejected' | 'unknown';
+    };
+    observation?: Omit<McpObservation, 'challenge'>;
+    recovery?: McpRecovery;
 };
 export declare function probeMcpConnection(config: Config, workspace: string, serverId: string, options?: McpSessionOptions): Promise<McpConnectionProbe>;
 export type McpAuthorization = {

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 { resolveMcpSetupConfig } from "./effective-server.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 { Agent } from "undici";
+import { lookup } from "node:dns";
 //#region src/agent/mcp/connection-setup.ts
 init_logger();
 const log = createLogger("McpConnectionSetup");
@@ -14,138 +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)) 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");
+	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;
+	}
+	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);
-		}
-		if (server?.url && hasCredentials && /\b(?:401|403)\b|unauthorized|forbidden/i.test(String(error))) return { state: "token_required" };
-		if (server?.url && !server.auth && classifyMcpConnectionError(error) === "unknown" && Object.keys(server.headers ?? {}).some((name) => name.toLowerCase() === "authorization")) try {
-			const entry = (await prepareNativeMcpConfig(config, workspace)).servers.find((candidate) => candidate.name === serverId);
-			if (entry && "url" in entry.config) {
-				const response = await fetch(httpUrl(entry.config.url), {
-					method: "POST",
-					redirect: "error",
-					signal: options?.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(1e4)]) : AbortSignal.timeout(1e4),
-					headers: {
-						Accept: "application/json, text/event-stream",
-						"Content-Type": "application/json",
-						...entry.config.headers
+		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"
 					},
-					body: JSON.stringify({
-						jsonrpc: "2.0",
-						id: 1,
-						method: "initialize",
-						params: {
-							protocolVersion: "2025-03-26",
-							capabilities: {},
-							clientInfo: {
-								name: "xopc",
-								version: "1"
-							}
-						}
-					})
-				});
-				await response.body?.cancel();
-				if (response.status === 401 || response.status === 403) return { state: "token_required" };
+					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"
+					}
+				};
 			}
-		} catch {
-			options?.signal?.throwIfAborted();
 		}
-		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 };