@xopcai/xopc 0.0.388 → 0.0.390

package/dist/src/agent/external-tools/gateway-tools.js

@@ -7,11 +7,11 @@ import { getSessionMetadata } from "../../storage/sqlite/session-read-repository
 import { init_session_repository } from "../../storage/sqlite/session-repository.js";
 import { connectorPrincipalForSession } from "../../connectors/principal.js";
 import { listConnectorInstances } from "../../connectors/instances.js";
-import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
-import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { parseExternalToolRef } from "./refs.js";
 import { setXopcToolMetadata } from "../embedded/tool-metadata.js";
+import { getStoreConnectorInstallPlan, parseStoreConnectorCandidateRef, searchStoreConnectorInstallCandidates } from "../../capabilities/store-connector.js";
 import { assertPersonalRequestAccountAccess } from "../../personal-agent/request-access.js";
+import { connectionCandidates, resolveConnectionCandidate } from "../../connectors/connection-candidates.js";
 import { ExternalToolService } from "./service.js";
 import { EXTERNAL_TOOL_SOURCES } from "./types.js";
 import { bindExternalToolRegistry } from "./tool-registry.js";

package/dist/src/agent/image/generation/openai-images-provider.js

@@ -1,5 +1,6 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { imageFileExtensionForMimeType } from "./image-assets.js";
 import { pickTimeoutMsOrFallback } from "../../../media-shared/http/deadline.js";
 import { privateNetworkPolicyToSsrfGuardOptions } from "../../../media-shared/http/private-network.js";
 import { resolveProviderHttpRequestConfig } from "../../../media-shared/http/resolve-provider-http-request-config.js";
@@ -8,7 +9,6 @@ import "../../../media-shared/http/index.js";
 import { ImageProviderError, validateImageRequest } from "../../../../packages/image-providers/src/validation.js";
 import { decodeBase64, imageFromBytes } from "../../../../packages/image-providers/src/http.js";
 import "../../../../packages/image-providers/src/index.js";
-import { imageFileExtensionForMimeType } from "./image-assets.js";
 //#region src/agent/image/generation/openai-images-provider.ts
 /** Strict implementation of the OpenAI Images REST protocol. */
 init_logger();

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

@@ -1,15 +1,17 @@
 import { createLogger } from "../../../utils/logger/index.js";
 import { init_logger } from "../../../utils/logger.js";
+import { assertProviderUsage, init_model_usage } from "../../../providers/model-usage.js";
 import { PROVIDER_ENV_MAP, init_env_keys } from "../../../providers/env-keys.js";
-import { ImageProviderError } from "../../../../packages/image-providers/src/validation.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();
 init_logger();
 const log = createLogger("ImageGen");
@@ -59,30 +61,26 @@ async function generateImage(params, deps = {}) {
 		try {
 			if (!provider.models.includes(candidate.model)) throw new ImageProviderError(`Unsupported image model: ${candidate.model}`, 400);
 			const modelCapabilities = provider.modelCapabilities?.[candidate.model];
+			const capabilityProvider = modelCapabilities ? {
+				...provider,
+				capabilities: modelCapabilities
+			} : provider;
+			const candidateParams = normalizeImageGeometry(params, capabilityProvider.capabilities, Boolean(params.inputImages?.length));
 			validateImageGenerationRequest({
-				provider: modelCapabilities ? {
-					...provider,
-					capabilities: modelCapabilities
-				} : provider,
-				size: params.size,
-				count: params.count,
-				aspectRatio: params.aspectRatio,
-				resolution: params.resolution,
-				quality: params.quality,
-				outputFormat: params.outputFormat,
-				background: params.background,
-				inputImages: params.inputImages
+				provider: capabilityProvider,
+				...candidateParams
 			});
 			const request = buildProviderRequest({
 				provider,
 				candidate,
-				params
+				params: candidateParams
 			});
 			log.debug({
 				provider: candidate.provider,
 				model: candidate.model,
 				phase: "provider_invoked"
 			}, `image-generation provider invoked: ${candidate.provider}/${candidate.model}`);
+			assertProviderUsage(candidate.provider, request.cfg?.providers?.[candidate.provider]?.baseUrl);
 			const result = await provider.generateImage(request);
 			if (!result.images?.length) throw new Error("Image generation provider returned no images.");
 			return {

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/image/load-image-media.js

@@ -1,5 +1,5 @@
-import { decodeDataUrl } from "./image-helpers.js";
 import { checkFileSafety } from "../prompt/safety.js";
+import { decodeDataUrl } from "./image-helpers.js";
 import { homedir } from "node:os";
 import path from "node:path";
 import { promises } from "node:fs";

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

@@ -1,11 +1,14 @@
+import { assertProviderUsage, init_model_usage, isProviderUsageScopeError } from "../../../providers/model-usage.js";
 import { init_schema, parseModelRef } from "../../../config/schema.js";
 import { getImageUnderstandingProvider } from "./provider-registry.js";
 import "./pi-ai-provider.js";
 //#region src/agent/image/understanding/runtime.ts
+init_model_usage();
 init_schema();
 async function describeImages(params) {
 	const parsed = parseModelRef(params.modelRef);
 	if (!parsed) throw new Error(`Invalid model reference: ${params.modelRef}`);
+	assertProviderUsage(parsed.provider);
 	const provider = getImageUnderstandingProvider(parsed.provider);
 	if (!provider) throw new Error(`No image understanding provider registered for: ${parsed.provider}. Ensure the provider module is imported.`);
 	return provider.describeImages(parsed.model, {
@@ -40,6 +43,7 @@ async function describeImagesWithFallback(params) {
 			continue;
 		}
 		try {
+			assertProviderUsage(parsed.provider);
 			return {
 				...await provider.describeImages(parsed.model, {
 					images: params.images,
@@ -51,6 +55,7 @@ async function describeImagesWithFallback(params) {
 				attempts
 			};
 		} catch (err) {
+			if (isProviderUsageScopeError(err)) throw err;
 			lastError = err;
 			attempts.push({
 				provider: parsed.provider,

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

@@ -1,14 +1,14 @@
 import { stripRuntimeUserMessageEnvelope } from "../../../packages/gateway-contract/src/user-message-display.js";
 import { init_src } from "../../../packages/gateway-contract/src/index.js";
+import { extractProfileAgentId } from "../../config/agent-profile.js";
+import { readAgentMessageContent } from "../memory/agent-message-access.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";
 import { expandAtFileMentionsInPlainText } from "../context/expand-at-file-mentions.js";
-import { readAgentMessageContent } from "../memory/agent-message-access.js";
 import { resolveImageHandlingStrategy } from "../image/vision-detection.js";
 import { resolveInboundImageContentParts } from "../image/inbound-image-handling.js";
 //#region src/agent/inbound/attachment-pipeline.ts

package/dist/src/agent/inbound/inbound-loop.d.ts

@@ -1,18 +1,3 @@
-/**
- * InboundLoop — owns the bus-driven inbound pipeline.
- *
- * Replaces the previous `AgentService.start()` while-loop, `handleInboundMessage`,
- * and `handleSystemMessage` methods. Everything that "a message arrives, run the
- * agent turn, publish the reply" needs is concentrated here; the parent
- * `AgentService` now just constructs the loop with collaborators and forwards
- * start/stop to it.
- *
- * The constructor takes a fairly wide config because handling a single inbound
- * message touches almost every subsystem (router, command handler, lifecycle
- * manager, agent orchestrator, outbound coordinator, session state, etc.). All
- * dependencies are injected so this class is unit-testable and the inbound
- * pipeline can evolve without touching `AgentService`.
- */
 import type { MessageBus } from '../../infra/bus/index.js';
 import type { Config } from '../../config/schema.js';
 import type { ChannelManager } from '../../channels/manager.js';
@@ -74,5 +59,6 @@ export declare class InboundLoop {
     /** Cooperatively stop the loop; the current message (if any) is allowed to finish. */
     stop(): void;
     private handleInboundMessage;
+    private handleInboundMessageScoped;
     private handleSystemMessage;
 }

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

@@ -1,12 +1,14 @@
 import { runWithLogContext, updateAsyncLogContext } from "../../utils/logger/context.js";
 import { init_logger } from "../../utils/logger.js";
-import { MessageBusShutdownError } from "../../infra/bus/queue.js";
-import "../../infra/bus/index.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 { runEmbeddedTurnForSession } from "../embedded/run-for-session.js";
 import { inboundMessageLogRequestId } from "../service-inbound-utils.js";
 //#region src/agent/inbound/inbound-loop.ts
+init_model_usage();
 init_logger();
 /** Initial back-off when bus consume fails. Doubles each consecutive failure. */
 const INBOUND_CONSUME_BASE_BACKOFF_MS = 1e3;
@@ -75,6 +77,9 @@ var InboundLoop = class {
 		this.running = false;
 	}
 	async handleInboundMessage(msg) {
+		return withModelUsageOrigin(msg.channel === "system" ? "background" : "interactive", () => this.handleInboundMessageScoped(msg));
+	}
+	async handleInboundMessageScoped(msg) {
 		await runWithLogContext({ requestId: inboundMessageLogRequestId(msg) }, async () => {
 			const { context, isCommand, command, commandArgs } = await this.cfg.messageRouter.routeMessage(msg);
 			const sessionContext = {

package/dist/src/agent/index.js

@@ -1,14 +1,14 @@
-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 { extractToolCallsFromAssistant, extractToolResultId, sanitizeToolCallId, sanitizeToolCallIdsForCloudCodeAssist } from "./transcript/tool-call-id.js";
+import { makeMissingToolResult, repairToolUseResultPairing, sanitizeToolCallInputs, sanitizeToolUseResultPairing, stripToolResultDetails } from "./transcript/session-transcript-repair.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

@@ -0,0 +1,50 @@
+import { type Config } from '../../config/schema.js';
+import { type McpConnectionProbe } from './connection-setup.js';
+export declare function mcpConfigRevision(value: unknown): string;
+export declare class McpDraftError extends Error {
+    readonly status: 400 | 404 | 409 | 429 | 500;
+    constructor(status: 400 | 404 | 409 | 429 | 500, message: string);
+}
+export type McpDraftInput = {
+    serverId: string;
+    sourceServerId?: string;
+    expectedServer?: unknown;
+    server: unknown;
+};
+/** Unsaved configuration and OAuth state belong to one principal and never enter the live registry. */
+export declare class McpConnectionDrafts {
+    private readonly options;
+    private readonly completed;
+    private readonly drafts;
+    constructor(options: {
+        readConfig: () => Config;
+        saveConfig: (config: Config, expectedConfig?: Config) => Promise<{
+            saved: boolean;
+            error?: string;
+            persisted?: boolean;
+            conflict?: boolean;
+        }>;
+    });
+    create(owner: string, input: McpDraftInput): Promise<{
+        id: `${string}-${string}-${string}-${string}-${string}`;
+        serverId: string;
+        expiresAt: number;
+    }>;
+    probe(owner: string, id: string): Promise<McpConnectionProbe>;
+    authorize(owner: string, id: string): import("./connection-setup.js").McpAuthorization;
+    authorization(owner: string, id: string): import("./connection-setup.js").McpAuthorization;
+    redirect(owner: string, id: string, url: string): void;
+    cancelAuthorization(owner: string, id: string): void;
+    tools(owner: string, id: string): Promise<import("./tool-catalog.js").McpCatalogTool[]>;
+    /** Caller serializes this with other Gateway config writes. Only this entry is merged into the latest config. */
+    commit(owner: string, id: string, enable?: boolean): Promise<{
+        reloadRequired?: boolean;
+        serverId: string;
+    }>;
+    remove(owner: string, id: string): void;
+    close(): void;
+    private get;
+    private assertIdle;
+    private assertAvailable;
+    private dispose;
+}

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

@@ -0,0 +1,278 @@
+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 { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "./connection-setup.js";
+import { createHash, randomUUID } from "node:crypto";
+//#region src/agent/mcp/connection-drafts.ts
+init_schema();
+const TTL_MS = 10 * 6e4;
+function canonical(value) {
+	if (Array.isArray(value)) return value.map(canonical);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).filter(([, child]) => child !== void 0).sort(([a], [b]) => a.localeCompare(b)).map(([key, child]) => [key, canonical(child)]));
+	return value;
+}
+function mcpConfigRevision(value) {
+	return createHash("sha256").update(JSON.stringify(canonical(value)) ?? "null").digest("hex");
+}
+var McpDraftError = class extends Error {
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** Unsaved configuration and OAuth state belong to one principal and never enter the live registry. */
+var McpConnectionDrafts = class {
+	completed = /* @__PURE__ */ new Map();
+	drafts = /* @__PURE__ */ new Map();
+	constructor(options) {
+		this.options = options;
+	}
+	async create(owner, input) {
+		const current = this.options.readConfig();
+		if (!/^[a-zA-Z0-9_-]+$/.test(input.serverId) || input.sourceServerId && input.sourceServerId !== input.serverId) throw new McpDraftError(400, "Invalid or changed MCP server ID.");
+		const source = Object.hasOwn(current.mcp?.servers ?? {}, input.serverId) ? current.mcp?.servers?.[input.serverId] : void 0;
+		if (input.sourceServerId && (!source || isManagedConnectorServer(source))) throw new McpDraftError(409, "The original custom server no longer exists.");
+		if (input.sourceServerId && mcpConfigRevision(source) !== mcpConfigRevision(input.expectedServer)) throw new McpDraftError(409, "The original configuration changed. Reload before testing.");
+		this.assertAvailable(current, input.serverId, input.sourceServerId);
+		const parsed = McpServerSchema.safeParse(input.server);
+		if (!parsed.success) throw new McpDraftError(400, "Invalid MCP configuration.");
+		const revision = mcpConfigRevision(source);
+		const server = structuredClone(parsed.data);
+		for (const internal of [
+			"xopcConnector",
+			"xopcPlugin",
+			"xopcOAuthCredentialId",
+			"xopcConnectionCheck"
+		]) delete server[internal];
+		const workspace = getWorkspacePath(current) || process.cwd();
+		const config = structuredClone(current);
+		config.mcp = { servers: { [input.serverId]: {
+			...server,
+			enabled: true
+		} } };
+		const credentials = await createNativeMcpCredentials(true);
+		if (this.drafts.size >= 100 || [...this.drafts.values()].filter((draft) => draft.owner === owner).length >= 8) throw new McpDraftError(429, "Too many unsaved MCP connection tests.");
+		const id = randomUUID();
+		const timer = setTimeout(() => {
+			const draft = this.drafts.get(id);
+			if (draft && !draft.committing) this.dispose(draft);
+		}, TTL_MS);
+		timer.unref();
+		const draft = {
+			id,
+			owner,
+			serverId: input.serverId,
+			sourceServerId: input.sourceServerId,
+			revision,
+			workspace,
+			server,
+			config,
+			credentials,
+			controller: new AbortController(),
+			timer,
+			expiresAt: Date.now() + TTL_MS,
+			running: false,
+			committing: false
+		};
+		this.drafts.set(id, draft);
+		return {
+			id,
+			serverId: draft.serverId,
+			expiresAt: draft.expiresAt
+		};
+	}
+	async probe(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		draft.authorizationId = void 0;
+		draft.running = true;
+		draft.probe = void 0;
+		draft.checkedAt = void 0;
+		try {
+			const result = await probeMcpConnection(draft.config, draft.workspace, draft.serverId, {
+				credentials: draft.credentials,
+				signal: draft.controller.signal
+			});
+			this.get(owner, id);
+			draft.probe = result;
+			if (result.state === "connected") draft.checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+			return result;
+		} finally {
+			draft.running = false;
+		}
+	}
+	authorize(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, owner);
+		draft.probe = void 0;
+		const attempt = startMcpAuthorization(draft.config, draft.workspace, draft.serverId, owner, {
+			credentials: draft.credentials,
+			authorizationScope: draft.id
+		});
+		draft.authorizationId = attempt.id;
+		return attempt;
+	}
+	authorization(owner, id) {
+		const draft = this.get(owner, id);
+		const result = draft.authorizationId && getMcpAuthorization(draft.authorizationId, owner, draft.config);
+		if (!result) throw new McpDraftError(404, "Draft authorization not found.");
+		if (result.state === "connected" && draft.probe?.state !== "connected") {
+			draft.probe = {
+				state: "connected",
+				toolCount: result.toolCount
+			};
+			draft.checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+		}
+		return result;
+	}
+	redirect(owner, id, url) {
+		const draft = this.get(owner, id);
+		if (!draft.authorizationId || !submitMcpRedirect(draft.authorizationId, owner, url, draft.config)) throw new McpDraftError(400, "The callback address does not match this draft authorization.");
+	}
+	cancelAuthorization(owner, id) {
+		const draft = this.get(owner, id);
+		if (draft.committing) throw new McpDraftError(409, "This draft is being saved.");
+		if (draft.running) throw new McpDraftError(409, "A connection test is still running.");
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, owner);
+		draft.authorizationId = void 0;
+		draft.probe = void 0;
+	}
+	async tools(owner, id) {
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.probe?.state !== "connected") throw new McpDraftError(409, "Test the connection first.");
+		draft.running = true;
+		try {
+			const tools = await discoverMcpTools(draft.config, draft.workspace, draft.serverId, {
+				credentials: draft.credentials,
+				signal: draft.controller.signal
+			});
+			this.get(owner, id);
+			return tools;
+		} finally {
+			draft.running = false;
+		}
+	}
+	/** Caller serializes this with other Gateway config writes. Only this entry is merged into the latest config. */
+	async commit(owner, id, enable = false) {
+		const completed = this.completed.get(id);
+		if (completed?.owner === owner) {
+			if (completed.enable !== enable) throw new McpDraftError(409, "This test has already been committed with different settings.");
+			return {
+				serverId: completed.serverId,
+				...completed.reloadRequired ? { reloadRequired: true } : {}
+			};
+		}
+		const draft = this.get(owner, id);
+		this.assertIdle(draft);
+		if (draft.authorizationId) this.authorization(owner, id);
+		if (draft.probe?.state !== "connected") throw new McpDraftError(409, "A successful connection test is required before saving.");
+		const current = this.options.readConfig();
+		if (mcpConfigRevision(current.mcp?.servers?.[draft.serverId]) !== draft.revision || (getWorkspacePath(current) || process.cwd()) !== draft.workspace) throw new McpDraftError(409, "Configuration changed after the test. Reload and test again.");
+		this.assertAvailable(current, draft.serverId, draft.sourceServerId);
+		draft.committing = true;
+		let alias;
+		let durable;
+		let published = false;
+		try {
+			const server = structuredClone(draft.server);
+			if (enable) server.enabled = true;
+			if (server.url) {
+				const state = await draft.credentials.forServer(draft.serverId, server.url).load();
+				const candidateAlias = `mcp_draft_${randomUUID().replaceAll("-", "")}`;
+				durable = await createNativeMcpCredentials();
+				await durable.forServer(candidateAlias, server.url).save(state?.tokens ? {
+					...state,
+					codeVerifier: void 0,
+					oauthState: void 0
+				} : { serverUrl: server.url });
+				alias = candidateAlias;
+				server.xopcOAuthCredentialId = alias;
+			}
+			server.xopcConnectionCheck = {
+				checkedAt: draft.checkedAt,
+				toolCount: draft.probe.toolCount ?? 0,
+				revision: mcpConfigRevision(server)
+			};
+			const latest = this.options.readConfig();
+			if (mcpConfigRevision(latest.mcp?.servers?.[draft.serverId]) !== draft.revision || (getWorkspacePath(latest) || process.cwd()) !== draft.workspace) throw new McpDraftError(409, "Configuration changed while preparing the save. Test again.");
+			this.assertAvailable(latest, draft.serverId, draft.sourceServerId);
+			const next = structuredClone(latest);
+			next.mcp = {
+				...next.mcp,
+				servers: {
+					...next.mcp?.servers,
+					[draft.serverId]: server
+				}
+			};
+			const result = await this.options.saveConfig(next, structuredClone(latest));
+			published = result.persisted === true || alias !== void 0 && this.options.readConfig().mcp?.servers?.[draft.serverId]?.xopcOAuthCredentialId === alias;
+			if (result.conflict) throw new McpDraftError(409, "Configuration changed before writing. Reload and test again.");
+			if (!result.saved && !result.persisted) throw new McpDraftError(500, "Could not save MCP configuration. Retry or reload the current configuration.");
+			const reloadRequired = !result.saved;
+			published = true;
+			const timer = setTimeout(() => this.completed.delete(id), TTL_MS);
+			timer.unref();
+			this.completed.set(id, {
+				owner,
+				enable,
+				serverId: draft.serverId,
+				reloadRequired,
+				timer
+			});
+			this.dispose(draft);
+			return {
+				serverId: draft.serverId,
+				...reloadRequired ? { reloadRequired: true } : {}
+			};
+		} finally {
+			draft.committing = false;
+			if (alias && this.options.readConfig().mcp?.servers?.[draft.serverId]?.xopcOAuthCredentialId === alias) published = true;
+			if (!published && alias && durable && draft.server.url) durable.remove(alias, draft.server.url);
+			if (this.drafts.has(id) && draft.expiresAt <= Date.now()) this.dispose(draft);
+		}
+	}
+	remove(owner, id) {
+		const draft = this.drafts.get(id);
+		if (!draft || draft.owner !== owner) return;
+		if (draft.committing) throw new McpDraftError(409, "This draft is being saved.");
+		this.dispose(draft);
+	}
+	close() {
+		for (const draft of this.drafts.values()) this.dispose(draft);
+		for (const item of this.completed.values()) clearTimeout(item.timer);
+		this.completed.clear();
+	}
+	get(owner, id) {
+		const draft = this.drafts.get(id);
+		if (!draft || draft.owner !== owner) throw new McpDraftError(404, "MCP draft not found or expired.");
+		if (draft.expiresAt <= Date.now() && !draft.committing) {
+			this.dispose(draft);
+			throw new McpDraftError(404, "MCP draft expired.");
+		}
+		return draft;
+	}
+	assertIdle(draft) {
+		const auth = draft.authorizationId && getMcpAuthorization(draft.authorizationId, draft.owner, draft.config);
+		if (draft.running || draft.committing || auth && (auth.state === "starting" || auth.state === "authorizing")) throw new McpDraftError(409, "Another draft operation is still running.");
+	}
+	assertAvailable(config, id, sourceId) {
+		const all = loadMergedMcpConfig({
+			cfg: config,
+			workspaceDir: getWorkspacePath(config) || process.cwd()
+		}).config.mcpServers;
+		if (Object.keys(all).some((other) => other !== sourceId && other.replaceAll("-", "_") === id.replaceAll("-", "_"))) throw new McpDraftError(409, "The MCP server ID is already in use.");
+	}
+	dispose(draft) {
+		this.drafts.delete(draft.id);
+		clearTimeout(draft.timer);
+		draft.controller.abort();
+		if (draft.authorizationId) cancelMcpAuthorization(draft.authorizationId, draft.owner);
+	}
+};
+//#endregion
+export { McpConnectionDrafts, McpDraftError, mcpConfigRevision };

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

@@ -0,0 +1,3 @@
+export type McpConnectionErrorCode = 'command_missing' | 'connection_refused' | 'host_not_found' | 'timeout' | 'access_denied' | 'network' | 'tls' | 'invalid_response' | 'not_found' | 'rate_limited' | 'configuration' | 'unknown';
+/** Return a safe category without exposing addresses, headers, or credential-bearing errors. */
+export declare function classifyMcpConnectionError(error: unknown): McpConnectionErrorCode;

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

@@ -0,0 +1,32 @@
+//#region src/agent/mcp/connection-errors.ts
+/** Return a safe category without exposing addresses, headers, or credential-bearing errors. */
+function classifyMcpConnectionError(error) {
+	const messages = [];
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (current && !seen.has(current) && seen.size < 8) {
+		seen.add(current);
+		if (typeof current !== "object") {
+			messages.push(String(current));
+			break;
+		}
+		const detail = current;
+		messages.push(String(detail.message ?? ""), String(detail.code ?? ""));
+		current = detail.cause;
+	}
+	const message = messages.join(" ");
+	if (/ENOENT|command not found|executable.{0,30}not found/i.test(message)) return "command_missing";
+	if (/ECONNREFUSED|connection refused/i.test(message)) return "connection_refused";
+	if (/ENOTFOUND|EAI_AGAIN|could not resolve/i.test(message)) return "host_not_found";
+	if (/timeout|timed out|ETIMEDOUT/i.test(message)) return "timeout";
+	if (/CERT_|CERTIFICATE|ERR_TLS|UNABLE_TO_VERIFY|DEPTH_ZERO|self.signed|unable to verify/i.test(message)) return "tls";
+	if (/\b429\b|too many requests|rate.limit/i.test(message)) return "rate_limited";
+	if (/\b(?:401|403)\b|unauthorized|forbidden|permission denied|invalid_token/i.test(message)) return "access_denied";
+	if (/\b404\b|\b405\b|method not allowed/i.test(message)) return "not_found";
+	if (/ECONNRESET|EHOSTUNREACH|ENETUNREACH|fetch failed|network error|socket.*closed/i.test(message)) return "network";
+	if (/content.type|text\/html|invalid json|unexpected token|protocol version|not a valid JSON/i.test(message)) return "invalid_response";
+	if (/not configured|invalid configuration|is disabled/i.test(message)) return "configuration";
+	return "unknown";
+}
+//#endregion
+export { classifyMcpConnectionError };

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

@@ -1,10 +1,13 @@
 import type { Config } from '../../config/schema.js';
+import { type McpConnectionErrorCode } from './connection-errors.js';
+import { type McpSessionOptions } from './tool-catalog.js';
 export type McpConnectionProbe = {
     state: 'connected' | 'oauth_required' | 'token_required' | 'error';
     toolCount?: number;
     error?: string;
+    errorCode?: McpConnectionErrorCode;
 };
-export declare function probeMcpConnection(config: Config, workspace: string, serverId: string): Promise<McpConnectionProbe>;
+export declare function probeMcpConnection(config: Config, workspace: string, serverId: string, options?: McpSessionOptions): Promise<McpConnectionProbe>;
 export type McpAuthorization = {
     id: string;
     serverId: string;
@@ -15,7 +18,9 @@ export type McpAuthorization = {
     error?: string;
 };
 /** A UI bridge to native pi's login command; no host-owned OAuth client or token store. */
-export declare function startMcpAuthorization(config: Config, workspace: string, serverId: string, owner: string): McpAuthorization;
+export declare function startMcpAuthorization(config: Config, workspace: string, serverId: string, owner: string, options?: McpSessionOptions & {
+    authorizationScope?: string;
+}): McpAuthorization;
 export declare function getMcpAuthorization(id: string, owner: string, config: Config): McpAuthorization | undefined;
 export declare function cancelMcpAuthorization(id: string, owner: string): boolean;
 export declare function submitMcpRedirect(id: string, owner: string, redirectUrl: string, config: Config): boolean;