@xopcai/xopc 0.0.427 → 0.0.428

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

@@ -11,9 +11,11 @@ import { isManagedConnectorServer } from "../../connectors/materialize.js";
 import { classifyMcpConnectionError } from "./connection-errors.js";
 import { McpConnectionDrafts, McpDraftError, mcpConfigRevision } from "./connection-drafts.js";
 import { weixinSetupScope } from "./weixin-setup-scope.js";
+import { localExecutionSchema, secretFieldsSchema } from "./setup-plan.js";
+import { McpDiscovery, createMcpResearch } from "./discovery.js";
 import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
-import { setTimeout } from "node:timers/promises";
+import { setTimeout as setTimeout$1 } from "node:timers/promises";
 //#region src/agent/mcp/conversation-setup.ts
 init_credentials();
 init_session_repository();
@@ -24,9 +26,26 @@ const log = createLogger("McpConversationSetup");
 const targetSchema = z.object({
 	serverId: z.string().regex(/^[a-zA-Z0-9_-]{1,64}$/),
 	displayName: z.string().min(1).max(100).optional(),
-	url: z.string().url().max(2048),
+	url: z.string().url().max(2048).optional(),
 	purpose: z.string().min(1).max(1e3),
-	expectedRevision: z.string().optional()
+	authentication: z.enum([
+		"auto",
+		"bearer",
+		"header",
+		"none"
+	]).optional(),
+	expectedRevision: z.string().optional(),
+	planId: z.string().uuid().optional(),
+	expectedPlanVersion: z.number().int().positive().optional(),
+	transport: z.enum([
+		"streamable-http",
+		"sse",
+		"stdio"
+	]).optional(),
+	secretFields: secretFieldsSchema.optional(),
+	execution: localExecutionSchema.optional(),
+	helpUrl: z.string().url().optional(),
+	objective: z.enum(["connect_only", "complete_task"]).optional()
 }).strict();
 const setupSchema = z.object({
 	setupId: identity,
@@ -49,12 +68,15 @@ var McpConversationSetup = class {
 	busy = /* @__PURE__ */ new Set();
 	authorizations = /* @__PURE__ */ new Set();
 	disposed = false;
+	retryTimers = /* @__PURE__ */ new Map();
+	discovery;
 	constructor(options) {
 		this.options = options;
 		this.drafts = new McpConnectionDrafts({
 			readConfig: options.readConfig,
 			saveConfig: options.saveConfig
 		});
+		this.discovery = new McpDiscovery(options.research ?? createMcpResearch(options.readConfig));
 	}
 	notify(goal) {
 		try {
@@ -87,8 +109,18 @@ var McpConversationSetup = class {
 		if (!goal || conversationId && goal.conversationId !== conversationId) throw new McpDraftError(404, "MCP setup not found.");
 		return goal;
 	}
+	canProvideToken(goal) {
+		const url = new URL(goal.url);
+		return (goal.phase === "auth_unknown" || goal.phase === "blocked" && goal.errorCode === "access_denied") && !goal.tokenProvider && !goal.secretProviders && (url.protocol === "https:" || [
+			"127.0.0.1",
+			"localhost",
+			"[::1]"
+		].includes(url.hostname));
+	}
 	view(goal) {
 		const expired = goal.expiresAt < Date.now() && goal.phase !== "ready";
+		const interactionPath = goal.channel ? `${goal.channel.origin}/#/mcp-setup/${goal.id}` : `/mcp-setup/${goal.id}`;
+		const interactionLink = `[Complete connection](${interactionPath})`;
 		return {
 			setupId: goal.id,
 			serverId: goal.serverId,
@@ -97,18 +129,33 @@ var McpConversationSetup = class {
 			phase: goal.phase,
 			expired,
 			reloadRequired: goal.reloadRequired === true,
+			canProvideToken: this.canProvideToken(goal),
+			secretFields: goal.secretFields,
+			helpUrl: goal.helpUrl,
+			objective: goal.objective,
+			planApproval: goal.reviewRequired ? {
+				sources: goal.sources ?? [],
+				execution: goal.execution,
+				endpoint: goal.transport === "stdio" ? goal.execution?.command : goal.url,
+				purpose: goal.purpose
+			} : void 0,
+			diagnosis: goal.diagnosis,
+			nextRetryAt: goal.nextRetryAt,
+			attempts: goal.attempts ?? 0,
 			errorCode: goal.errorCode,
 			conversationId: goal.conversationId,
 			expiresAt: goal.expiresAt,
-			interactionPath: goal.channel ? `${goal.channel.origin}/#/mcp-setup/${goal.id}` : `/mcp-setup/${goal.id}`,
+			interactionPath,
 			returnChannel: goal.channel ? "weixin" : void 0,
 			managementPath: goal.channel ? `${goal.channel.origin}/#/capabilities/connectors?tab=connected` : "/capabilities/connectors?tab=connected",
 			continuationQueued: goal.resumed === true,
 			replyDelivery: goal.reply?.status,
-			instruction: goal.phase === "cancelled" ? "This setup is cancelled. Do not continue or revive it. Cancellation does not undo configuration already saved." : expired ? "This request expired. Start a new objective instead of reusing authorization." : goal.phase === "approval_required" ? "Send the exact trusted interactionPath to the user. The paired Weixin user has requested this service; an authenticated Gateway owner must approve this exact request on that page before any probe, credential submission or configuration change. Never ask for keys, callback URLs or a continue reply in chat. The result returns to this original Weixin conversation automatically." : goal.phase === "blocked" ? "The connection check failed. Report the safe error code and the remaining blocker. Do not repeatedly retry without resolving the cause." : goal.reloadRequired ? "Configuration is saved but runtime reload failed. Report the partial result and require a Gateway restart; do not claim the tools are active or tested." : goal.phase === "ready" ? "Configuration is saved. The host continues the original objective in a fresh turn so native MCP tools can load. Stop this turn; do not repeat installation or invent a successful read." : goal.phase === "planned" ? "Continue automatic steps with advance and the returned version." : "Link the trusted interactionPath for authorization or Token input, then stop this turn. The host resumes automatically; never ask for credentials, callback URLs or a continue reply in chat."
+			instruction: goal.phase === "cancelled" ? "This setup is cancelled. Do not continue or revive it. Cancellation does not undo configuration already saved." : expired ? "This request expired. Start a new objective instead of reusing authorization." : goal.phase === "approval_required" ? goal.channel ? "Send the exact trusted interactionPath to the user. The paired Weixin user has requested this service; an authenticated Gateway owner must approve this exact request on that page before any probe, credential submission or configuration change. Never ask for keys, callback URLs or a continue reply in chat. The result returns to this original Weixin conversation automatically." : `Copy ${interactionLink} verbatim. The owner must review this exact publisher source or local execution plan before any probe, credential submission or execution. Do not ask for secrets or an additional continue reply in chat.` : this.canProvideToken(goal) ? `The service refused access. Copy this Markdown link verbatim for secure first-time Token input: ${interactionLink} . Never rewrite its destination as xopc://workspace or add an origin. A refusal alone does not prove a missing Token; service or account permissions may also block access. Do not request secrets in chat or repeatedly retry.` : goal.phase === "blocked" ? "The connection check failed. Report the safe error code and the remaining blocker. Do not repeatedly retry without resolving the cause." : goal.reloadRequired ? "Configuration is saved but runtime reload failed. Report the partial result and require a Gateway restart; do not claim the tools are active or tested." : goal.phase === "ready" ? "Configuration is saved. The host queues the original objective once in a fresh turn. If this is that continuation, discover native tools by the exact server namespace and finish the original objective; otherwise stop and let the queued continuation run. Do not repeat installation or invent a successful read." : goal.phase === "planned" ? "Continue automatic steps with advance and the returned version." : `Copy this Markdown link verbatim for authorization or Token input: ${interactionLink} . Never rewrite its destination as xopc://workspace or add an origin. Then stop this turn. The host resumes automatically; never ask for credentials, callback URLs or a continue reply in chat.`
 		};
 	}
 	cancelGoal(goal) {
+		clearTimeout(this.retryTimers.get(goal.id));
+		this.retryTimers.delete(goal.id);
 		goal.phase = "cancelled";
 		this.save(goal);
 		const draftId = this.draftIds.get(goal.id);
@@ -118,6 +165,10 @@ var McpConversationSetup = class {
 		this.draftIds.delete(goal.id);
 		return this.view(goal);
 	}
+	async cancelConversation(conversationId) {
+		this.discovery.cancelConversation(conversationId);
+		for (const goal of this.goals.values().filter((g) => g.conversationId === conversationId && g.phase !== "cancelled")) this.cancelGoal(goal);
+	}
 	revokeWeixinRequests(accountId, peerId) {
 		for (const goal of this.goals.values()) if (goal.channel?.accountId === accountId && goal.channel.peerId.toLowerCase() === peerId.toLowerCase() && goal.phase !== "cancelled") this.cancelGoal(goal);
 	}
@@ -153,11 +204,27 @@ var McpConversationSetup = class {
 		const channel = context.canRequestWeixinSetup ? weixinSetupScope(context.conversationId, this.options.readConfig()) : void 0;
 		if (!localOwner && !channel) throw new McpDraftError(404, "A paired, account-isolated Weixin direct conversation and a secure Gateway public URL are required. Shared/merged routing is not eligible.");
 		if (channel && ![
+			"discover",
+			"propose",
+			"select",
+			"repair",
 			"start",
 			"get",
 			"cancel",
 			"advance"
 		].includes(command)) throw new McpDraftError(409, "Weixin configuration requires approval for a specific new connection on the secure page.");
+		if ([
+			"discover",
+			"propose",
+			"select"
+		].includes(command)) {
+			if (!context.canConfigure && !channel) throw new McpDraftError(409, "An active owner turn is required.");
+			if (dryRun) return {
+				dryRun: true,
+				instruction: "Discovery and candidate state were not changed."
+			};
+			return this.discovery.command(command, input, context);
+		}
 		if (command === "inspect") {
 			z.object({}).strict().parse(input);
 			return this.inspect();
@@ -167,15 +234,65 @@ var McpConversationSetup = class {
 			return this.view(this.get(args.setupId, context.conversationId));
 		}
 		if (!context.canConfigure && !channel) throw new McpDraftError(409, "An active owner App or local CLI turn is required for MCP configuration.");
+		if (command === "repair") {
+			const args = setupSchema.extend({
+				planId: z.string().uuid(),
+				expectedPlanVersion: z.number().int().positive()
+			}).strict().parse(input);
+			const goal = this.get(args.setupId, context.conversationId);
+			this.current(goal);
+			if (goal.version !== args.expectedVersion || goal.expiresAt < Date.now() || goal.phase !== "blocked" || goal.diagnosis?.recovery?.kind !== "verify_documented_endpoint") throw new McpDraftError(409, "This objective does not permit endpoint repair.");
+			const selected = this.discovery.selected(args.planId, args.expectedPlanVersion, context);
+			if (selected.purpose !== goal.purpose || selected.plan.url === goal.url && (selected.plan.transport ?? "streamable-http") === (goal.transport ?? "streamable-http")) throw new McpDraftError(409, "Repair needs the original objective and a documented different endpoint or transport.");
+			if (dryRun) return {
+				dryRun: true,
+				instruction: "The original objective and all existing credentials remain unchanged."
+			};
+			const revision = mcpConfigRevision(configuredServer(this.options.readConfig(), goal.serverId));
+			if (revision !== goal.expectedRevision) throw new McpDraftError(409, "The saved connection changed. Inspect before repairing.");
+			this.cancelGoal(goal);
+			return this.command("start", {
+				planId: args.planId,
+				expectedPlanVersion: args.expectedPlanVersion,
+				serverId: goal.serverId,
+				purpose: goal.purpose,
+				...!channel ? { expectedRevision: revision } : {}
+			}, context);
+		}
 		if (command === "start") {
 			if (getActiveConnectionWait(context.conversationId)) throw new McpDraftError(409, "Another connection objective is waiting. Finish or cancel it before starting a separate MCP setup.");
-			const args = targetSchema.parse(input), url = new URL(args.url);
+			const args = targetSchema.parse(input);
+			let selected;
+			if (args.planId) {
+				if (!args.expectedPlanVersion || args.url || args.execution || args.authentication || args.secretFields || args.transport || args.helpUrl || args.objective) throw new McpDraftError(400, "Use the selected plan without overriding its configuration.");
+				selected = this.discovery.selected(args.planId, args.expectedPlanVersion, context);
+				Object.assign(args, selected.plan);
+				args.purpose = selected.purpose;
+			}
+			const stdio = args.transport === "stdio";
+			for (const reference of [args.helpUrl, args.execution?.sourceUrl].filter((v) => Boolean(v))) {
+				const parsed = new URL(reference);
+				if (!["https:", "http:"].includes(parsed.protocol) || parsed.username || parsed.password || [...parsed.searchParams.keys()].some((key) => /token|secret|password|api.?key|authorization/i.test(key))) throw new McpDraftError(400, "Use a public integration guide without embedded credentials.");
+			}
+			if (stdio ? !args.execution || args.url : !args.url || args.execution) throw new McpDraftError(400, "Provide one HTTP URL or stdio execution plan.");
+			const url = new URL(stdio ? `stdio://localhost/${args.serverId}` : args.url);
 			if ([
 				"__proto__",
 				"constructor",
 				"prototype"
 			].includes(args.serverId.toLowerCase())) throw new McpDraftError(400, "Use a non-reserved server name.");
-			if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || [...url.searchParams.keys()].some((key) => /token|secret|password|api.?key|authorization/i.test(key))) throw new McpDraftError(400, "Use an HTTP MCP address without embedded credentials. Enter secrets only in the secure page.");
+			if (!stdio && (!["http:", "https:"].includes(url.protocol) || url.username || url.password || [...url.searchParams.keys()].some((key) => /token|secret|password|api.?key|authorization/i.test(key)))) throw new McpDraftError(400, "Use an HTTP MCP address without embedded credentials. Enter secrets only in the secure page.");
+			if (args.secretFields?.some((field) => field.location !== (stdio ? "env" : "header"))) throw new McpDraftError(400, "Credential fields do not match the selected transport.");
+			if (args.authentication === "bearer" && args.secretFields?.length) {
+				if (args.secretFields.length !== 1 || args.secretFields[0].location !== "header" || args.secretFields[0].name.toLowerCase() !== "authorization") throw new McpDraftError(400, "Bearer authentication uses one Authorization credential field.");
+				args.secretFields[0].prefix = "Bearer ";
+			}
+			if (args.authentication === "header" && !args.secretFields?.length) throw new McpDraftError(400, "Describe the documented header fields.");
+			if (!stdio && (args.authentication === "bearer" || args.secretFields?.length) && url.protocol !== "https:" && ![
+				"127.0.0.1",
+				"localhost",
+				"[::1]"
+			].includes(url.hostname)) throw new McpDraftError(400, "Token authentication requires HTTPS or a loopback server.");
 			const session = getSessionMetadata(context.conversationId);
 			if (!session?.transcriptId || session.agentId !== context.agentId) throw new McpDraftError(409, "Conversation identity changed.");
 			if (channel) {
@@ -196,14 +313,23 @@ var McpConversationSetup = class {
 			if (dryRun) return {
 				dryRun: true,
 				serverId: args.serverId,
-				authentication: "probe_required"
+				authentication: args.authentication === "bearer" ? "token_required" : "probe_required"
 			};
-			const existing = this.goals.values().find((goal) => goal.conversationId === context.conversationId && goal.transcriptId === session.transcriptId && goal.serverId === args.serverId && goal.url === url.href && goal.purpose === args.purpose && goal.displayName === args.displayName && goal.phase !== "cancelled" && goal.phase !== "ready" && goal.expiresAt > Date.now());
+			const existing = this.goals.values().find((goal) => goal.conversationId === context.conversationId && goal.transcriptId === session.transcriptId && JSON.stringify([
+				goal.transport ?? "streamable-http",
+				goal.execution,
+				goal.secretFields,
+				goal.helpUrl,
+				goal.objective
+			]) === JSON.stringify([
+				args.transport ?? "streamable-http",
+				args.execution,
+				args.secretFields,
+				args.helpUrl,
+				args.objective
+			]) && JSON.stringify(goal.sources) === JSON.stringify(selected?.sources) && goal.serverId === args.serverId && goal.url === url.href && goal.purpose === args.purpose && goal.displayName === args.displayName && (goal.authentication ?? "auto") === (args.authentication ?? "auto") && goal.phase !== "cancelled" && goal.phase !== "ready" && goal.expiresAt > Date.now());
 			if (existing) return this.view(existing);
-			for (const previous of this.goals.values().filter((item) => item.conversationId === context.conversationId && (item.phase !== "ready" || !item.resumed) && item.phase !== "cancelled")) {
-				previous.phase = "cancelled";
-				this.save(previous);
-			}
+			for (const previous of this.goals.values().filter((item) => item.conversationId === context.conversationId && (item.phase !== "ready" || !item.resumed) && item.phase !== "cancelled")) this.cancelGoal(previous);
 			const goal = {
 				id: randomUUID(),
 				conversationId: context.conversationId,
@@ -213,9 +339,18 @@ var McpConversationSetup = class {
 				displayName: args.displayName,
 				url: url.href,
 				purpose: args.purpose,
+				authentication: args.authentication,
+				transport: args.transport,
+				execution: args.execution,
+				secretFields: args.secretFields,
+				helpUrl: args.helpUrl,
+				objective: args.objective,
+				reviewRequired: stdio || Boolean(selected),
+				publicOnly: Boolean(selected && !stdio),
+				sources: selected?.sources,
 				expectedRevision: mcpConfigRevision(server),
 				version: 1,
-				phase: channel ? "approval_required" : "planned",
+				phase: channel || stdio || selected ? "approval_required" : "planned",
 				...channel ? { channel } : {},
 				expiresAt: Date.now() + 15 * 6e4
 			};
@@ -233,10 +368,7 @@ var McpConversationSetup = class {
 			return this.options.withConfigLock(async () => {
 				const config = this.options.readConfig(), server = configuredServer(config, args.serverId);
 				if (!server || isManagedConnectorServer(server) || server.xopcPlugin || mcpConfigRevision(server) !== args.expectedRevision) throw new McpDraftError(409, "The custom server changed or belongs to another owner. Inspect again.");
-				for (const goal of this.goals.values().filter((item) => item.serverId === args.serverId && item.phase !== "ready" && item.phase !== "cancelled")) {
-					goal.phase = "cancelled";
-					this.save(goal);
-				}
+				for (const goal of this.goals.values().filter((item) => item.serverId === args.serverId && item.phase !== "ready" && item.phase !== "cancelled")) this.cancelGoal(goal);
 				const next = structuredClone(config);
 				if (command === "remove") delete next.mcp.servers[args.serverId];
 				else next.mcp.servers[args.serverId].enabled = args.enabled;
@@ -271,6 +403,10 @@ var McpConversationSetup = class {
 			return this.view(goal);
 		}
 		if (goal.expiresAt < Date.now()) throw new McpDraftError(409, "Setup expired. Start a new goal; do not reuse an old authorization.");
+		if (goal.nextRetryAt && Date.now() < goal.nextRetryAt) {
+			this.scheduleRetry(goal);
+			return this.view(goal);
+		}
 		if (this.busy.has(goal.id)) return {
 			...this.view(goal),
 			inProgress: true
@@ -288,6 +424,22 @@ var McpConversationSetup = class {
 			if (mcpConfigRevision(published) !== goal.expectedRevision) throw new McpDraftError(409, "Server changed. Start again from the current configuration.");
 			let draftId = this.draftIds.get(goal.id);
 			if (!draftId) {
+				const fields = goal.secretFields?.length ? goal.secretFields : [{
+					id: "token",
+					name: "Authorization",
+					location: "header",
+					prefix: "Bearer ",
+					label: "Token"
+				}];
+				const secretConfig = {};
+				for (const field of fields) {
+					const provider = goal.secretProviders?.[field.id] ?? (field.id === "token" ? goal.tokenProvider : void 0);
+					if (provider) (secretConfig[field.location === "env" ? "env" : "headers"] ??= {})[field.name] = { xopcSecretRef: {
+						provider,
+						fieldKey: field.id,
+						prefix: field.prefix
+					} };
+				}
 				const draft = await this.drafts.create("local-owner", {
 					serverId: goal.serverId,
 					...published ? {
@@ -295,16 +447,20 @@ var McpConversationSetup = class {
 						expectedServer: published
 					} : {},
 					server: {
-						url: goal.url,
+						...goal.transport === "stdio" ? {
+							...goal.execution,
+							sourceUrl: void 0,
+							type: "stdio",
+							xopcManagedStdio: true
+						} : {
+							url: goal.url,
+							type: goal.transport ?? "streamable-http"
+						},
 						displayName: goal.displayName,
-						type: "streamable-http",
 						enabled: true,
 						xopcSetupId: goal.id,
-						...goal.tokenProvider ? { headers: { Authorization: { xopcSecretRef: {
-							provider: goal.tokenProvider,
-							fieldKey: "token",
-							prefix: "Bearer "
-						} } } } : {}
+						xopcPublicOnly: goal.publicOnly,
+						...secretConfig
 					}
 				});
 				this.current(goal);
@@ -315,6 +471,12 @@ var McpConversationSetup = class {
 					this.save(goal);
 				}
 			}
+			if (goal.authentication === "bearer" && !goal.secretFields?.length && !goal.tokenProvider && !goal.secretProviders?.token || goal.secretFields?.some((field) => !goal.secretProviders?.[field.id])) {
+				goal.phase = "token_required";
+				goal.errorCode = void 0;
+				this.save(goal);
+				return this.view(goal);
+			}
 			if (goal.phase === "authorizing") {
 				const auth = this.drafts.authorization("local-owner", draftId);
 				if (auth.state === "error" || auth.state === "cancelled") {
@@ -325,12 +487,46 @@ var McpConversationSetup = class {
 				}
 				if (auth.state !== "connected") return this.view(goal);
 			} else {
-				const probe = await this.drafts.probe("local-owner", draftId);
+				if ((goal.attempts ?? 0) >= 3) {
+					goal.phase = "blocked";
+					goal.nextRetryAt = void 0;
+					goal.diagnosis = {
+						...goal.diagnosis,
+						recovery: {
+							kind: "report_blocker",
+							reason: "retry_budget_exhausted"
+						}
+					};
+					this.save(goal);
+					return this.view(goal);
+				}
+				goal.attempts = (goal.attempts ?? 0) + 1;
+				goal.nextRetryAt = void 0;
+				this.save(goal);
+				const probe = await this.drafts.probe("local-owner", draftId, { beforeRequest: (request) => {
+					this.current(goal);
+					const key = `${request?.method ?? "GET"}:${request?.stage ?? "metadata"}`;
+					goal.requestCounts ??= {};
+					if ((goal.requestCounts[key] ?? 0) >= 3) throw new Error("MCP retry budget exhausted for this protocol stage");
+					goal.requestCounts[key] = (goal.requestCounts[key] ?? 0) + 1;
+					this.goals.set(goal.id, goal);
+				} });
 				this.current(goal);
+				goal.diagnosis = {
+					auth: probe.auth,
+					observation: probe.observation,
+					recovery: probe.recovery
+				};
 				if (probe.state !== "connected") {
 					goal.phase = probe.state === "error" ? "blocked" : probe.state;
-					goal.errorCode = probe.state === "token_required" && goal.tokenProvider ? "credential_rejected" : probe.errorCode;
+					goal.errorCode = probe.state === "token_required" && (goal.tokenProvider || goal.secretProviders) ? "credential_rejected" : probe.errorCode;
+					if ((probe.recovery?.kind === "wait" || [
+						"network",
+						"timeout",
+						"connection_refused"
+					].includes(probe.errorCode ?? "")) && (goal.attempts ?? 0) < 3) goal.nextRetryAt = probe.recovery?.retryAt ?? Date.now() + (goal.attempts === 1 ? 2e3 : 5e3);
 					this.save(goal);
+					this.scheduleRetry(goal);
 					return this.view(goal);
 				}
 			}
@@ -369,6 +565,21 @@ var McpConversationSetup = class {
 			this.busy.delete(goal.id);
 		}
 	}
+	scheduleRetry(goal) {
+		if (this.retryTimers.has(goal.id) || !goal.nextRetryAt || goal.nextRetryAt >= goal.expiresAt || this.disposed) return;
+		const version = goal.version;
+		const timer = setTimeout(() => {
+			this.retryTimers.delete(goal.id);
+			if (this.disposed) return;
+			try {
+				const current = this.goals.get(goal.id);
+				if (!current || current.version !== version) return;
+				this.advance(current).catch(() => {});
+			} catch {}
+		}, Math.max(1, goal.nextRetryAt - Date.now()));
+		timer.unref();
+		this.retryTimers.set(goal.id, timer);
+	}
 	/** Owner-only UI; secret values and OAuth URLs never pass through the model API. */
 	async interact(id, action, value, expectedVersion, ownerPrincipalId = "local-owner") {
 		const goal = this.get(id);
@@ -398,16 +609,16 @@ var McpConversationSetup = class {
 			}
 			return {
 				...this.view(goal),
-				endpointOrigin: new URL(goal.url).origin,
+				endpointOrigin: goal.transport === "stdio" ? "Gateway local process" : new URL(goal.url).origin,
 				approval: goal.channel ? {
 					...goal.channel,
 					endpoint: goal.url,
 					purpose: goal.purpose
 				} : void 0,
-				canReplaceToken: Boolean(goal.tokenProvider),
+				canReplaceToken: Boolean(goal.tokenProvider || goal.secretProviders),
 				authorizationUrl,
 				authState,
-				requiresRecheck: !draftId && goal.phase !== "ready" && goal.phase !== "cancelled"
+				requiresRecheck: !draftId && goal.phase !== "ready" && goal.phase !== "cancelled" && goal.phase !== "approval_required"
 			};
 		}
 		this.current(goal);
@@ -421,7 +632,7 @@ var McpConversationSetup = class {
 		}
 		if (goal.expiresAt < Date.now() || goal.phase === "ready") throw new McpDraftError(409, "This setup no longer accepts input.");
 		if (action === "approve") {
-			if (!goal.channel || goal.phase !== "approval_required" || !ownerPrincipalId) throw new McpDraftError(409, "This request cannot be approved.");
+			if (!(goal.channel || goal.reviewRequired) || goal.phase !== "approval_required" || !ownerPrincipalId) throw new McpDraftError(409, "This request cannot be approved.");
 			goal.approvedBy = ownerPrincipalId;
 			goal.phase = "planned";
 			this.save(goal);
@@ -429,21 +640,35 @@ var McpConversationSetup = class {
 		}
 		if (goal.phase === "approval_required") throw new McpDraftError(409, "Approve the exact Weixin request before continuing.");
 		if (action === "token") {
-			if (!(goal.phase === "token_required" || goal.phase === "blocked" && goal.tokenProvider) || !value?.trim() || value.length > 16384) throw new McpDraftError(400, "A token is required for this setup.");
+			if (!(goal.phase === "token_required" || goal.phase === "blocked" && (goal.tokenProvider || goal.secretProviders) || this.canProvideToken(goal))) throw new McpDraftError(400, "A token is required for this setup.");
+			if (goal.nextRetryAt && Date.now() < goal.nextRetryAt) throw new McpDraftError(409, "The service cooldown has not expired. Wait before submitting credentials.");
+			const fields = goal.secretFields?.length ? goal.secretFields : [{
+				id: "token",
+				name: "Authorization",
+				location: "header",
+				prefix: "Bearer ",
+				label: "Token"
+			}];
+			const values = typeof value === "string" && fields.length === 1 ? { [fields[0].id]: value } : value;
+			if (!values || typeof values !== "object" || Object.keys(values).length !== fields.length || fields.some((field) => !Object.hasOwn(values, field.id) || typeof values[field.id] !== "string" || !values[field.id].trim() || values[field.id].length > 16384 || /[\r\n\0]/.test(values[field.id]))) throw new McpDraftError(400, "Provide every requested secret field without control characters.");
 			if (this.busy.has(id)) throw new McpDraftError(409, "A check is in progress.");
 			const url = new URL(goal.url);
-			if (url.protocol !== "https:" && ![
+			if (goal.transport !== "stdio" && url.protocol !== "https:" && ![
 				"127.0.0.1",
 				"localhost",
 				"[::1]"
 			].includes(url.hostname)) throw new McpDraftError(400, "Token authentication requires HTTPS or a loopback server.");
 			this.busy.add(id);
 			this.save(goal);
-			const provider = connectorSecretProviderId(`mcp-setup-${id}-${goal.version}`, "token");
+			const providers = {};
 			const credentials = new CredentialResolver();
 			try {
-				await credentials.saveApiKey(provider, value.trim());
-				this.current(goal);
+				for (const field of fields) {
+					const provider = connectorSecretProviderId(`mcp-setup-${id}-${goal.version}`, field.id);
+					providers[field.id] = provider;
+					await credentials.saveApiKey(provider, values[field.id].trim());
+					this.current(goal);
+				}
 				const old = this.draftIds.get(id);
 				if (old) try {
 					this.drafts.remove("local-owner", old);
@@ -451,12 +676,16 @@ var McpConversationSetup = class {
 					if (!(error instanceof McpDraftError) || error.status !== 404) throw error;
 				}
 				this.draftIds.delete(id);
-				goal.tokenProvider = provider;
+				goal.secretProviders = providers;
+				goal.tokenProvider = providers.token;
 				goal.phase = "planned";
 				goal.errorCode = void 0;
+				goal.attempts = 0;
+				goal.requestCounts = {};
+				goal.nextRetryAt = void 0;
 				this.save(goal);
 			} catch (error) {
-				await credentials.deleteProfile(`${provider}:default`);
+				await Promise.all(Object.values(providers).map((provider) => credentials.deleteProfile(`${provider}:default`)));
 				throw error;
 			} finally {
 				this.busy.delete(id);
@@ -483,7 +712,7 @@ var McpConversationSetup = class {
 		this.authorizations.add(id);
 		(async () => {
 			for (;;) {
-				await setTimeout(250, void 0, { ref: false });
+				await setTimeout$1(250, void 0, { ref: false });
 				if (this.disposed) return;
 				const goal = this.goals.get(id);
 				if (!goal || goal.phase !== "authorizing" || goal.expiresAt < Date.now()) return;
@@ -513,6 +742,8 @@ var McpConversationSetup = class {
 	}
 	dispose() {
 		this.disposed = true;
+		for (const timer of this.retryTimers.values()) clearTimeout(timer);
+		this.retryTimers.clear();
 		for (const draftId of this.draftIds.values()) try {
 			this.drafts.remove("local-owner", draftId);
 		} catch {}
@@ -602,6 +833,10 @@ var McpConversationSetup = class {
 		}
 	}
 	async resumePending(runtimeReloaded = false) {
+		for (const goal of this.goals.values().filter((item) => item.phase === "blocked" && item.nextRetryAt)) try {
+			this.current(goal);
+			this.scheduleRetry(goal);
+		} catch {}
 		for (const goal of this.goals.values().filter((item) => item.phase === "ready" && item.reply && item.reply.status !== "delivered")) try {
 			await this.deliverReply(goal);
 		} catch {}

package/dist/src/agent/mcp/discovery.d.ts

@@ -0,0 +1,102 @@
+import type { Config } from '../../config/schema.js';
+import { type ConnectionPlan } from './setup-plan.js';
+type Context = {
+    conversationId: string;
+    agentId: string;
+    authorizeResearch?: (tool: 'web_search' | 'web_fetch', args: Record<string, unknown>) => Promise<boolean>;
+    signal?: AbortSignal;
+};
+type Document = {
+    id: string;
+    url: string;
+    hash: string;
+    text: string;
+};
+export interface McpResearch {
+    search(query: string, signal?: AbortSignal): Promise<Array<{
+        url: string;
+        title: string;
+    }>>;
+    read(url: string, signal?: AbortSignal): Promise<{
+        url: string;
+        text: string;
+    }>;
+}
+export declare function createMcpResearch(config: () => Config): McpResearch;
+/** Search results are evidence to inspect, never configuration authority. */
+export declare class McpDiscovery {
+    private readonly research;
+    private readonly records;
+    constructor(research: McpResearch);
+    private current;
+    private authorized;
+    command(command: string, input: Record<string, unknown>, context: Context): Promise<{
+        discoveryId: string;
+        version: number;
+        documents: Document[];
+        failures: {
+            url: string;
+            reason: string;
+        }[];
+        instruction: string;
+        candidates?: undefined;
+        planId?: undefined;
+        expectedPlanVersion?: undefined;
+    } | {
+        discoveryId: string;
+        version: number;
+        candidates: {
+            ownership: string;
+            displayName: string;
+            transport: "stdio" | "streamable-http" | "sse";
+            authentication: "header" | "none" | "auto" | "bearer";
+            secretFields: {
+                id: string;
+                label: string;
+                location: "header" | "env";
+                name: string;
+                prefix: "" | "Bearer ";
+            }[];
+            objective: "connect_only" | "complete_task";
+            url?: string;
+            helpUrl?: string;
+            execution?: {
+                command: string;
+                args: string[];
+                sourceUrl: string;
+                cwd?: string;
+            };
+            candidateId: string;
+        }[];
+        instruction: string;
+        documents?: undefined;
+        failures?: undefined;
+        planId?: undefined;
+        expectedPlanVersion?: undefined;
+    } | {
+        planId: string;
+        expectedPlanVersion: number;
+        instruction: string;
+        discoveryId?: undefined;
+        version?: undefined;
+        documents?: undefined;
+        failures?: undefined;
+        candidates?: undefined;
+    }>;
+    selected(id: string, version: number, context: Context): {
+        trusted: boolean;
+        sources: {
+            url: string;
+            hash: string;
+        }[];
+        purpose: string;
+        id: string;
+        plan: ConnectionPlan;
+        evidence: Array<{
+            documentId: string;
+            quote: string;
+        }>;
+    };
+    cancelConversation(conversationId: string): void;
+}
+export {};