@xopcai/xopc 0.0.223 → 0.0.225

package/dist/src/config/schema.d.ts

@@ -1430,6 +1430,10 @@ export declare const TuiConfigSchema: z.ZodDefault<z.ZodObject<{
     defaultAgent: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>>;
 export type TuiConfig = z.infer<typeof TuiConfigSchema>;
+export declare const McpOAuthConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"oauth">;
+    clientId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -1452,6 +1456,10 @@ export declare const McpServerSchema: z.ZodObject<{
             fieldKey: z.ZodString;
         }, z.core.$strip>;
     }, z.core.$strip>]>>>;
+    auth: z.ZodOptional<z.ZodObject<{
+        type: z.ZodLiteral<"oauth">;
+        clientId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
     connectionTimeoutMs: z.ZodOptional<z.ZodNumber>;
     requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$catchall<z.ZodUnknown>>;
@@ -1478,12 +1486,17 @@ export declare const McpConfigSchema: z.ZodOptional<z.ZodObject<{
                 fieldKey: z.ZodString;
             }, z.core.$strip>;
         }, z.core.$strip>]>>>;
+        auth: z.ZodOptional<z.ZodObject<{
+            type: z.ZodLiteral<"oauth">;
+            clientId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
         connectionTimeoutMs: z.ZodOptional<z.ZodNumber>;
         requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$catchall<z.ZodUnknown>>>>;
     sessionIdleTtlMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>>;
 export type McpServerConfig = z.infer<typeof McpServerSchema>;
+export type McpOAuthConfig = z.infer<typeof McpOAuthConfigSchema>;
 export type McpConfig = z.infer<typeof McpConfigSchema>;
 export declare const ConnectorsConfigSchema: z.ZodOptional<z.ZodObject<{
     instances: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
@@ -2331,6 +2344,10 @@ export declare const ConfigSchema: z.ZodDefault<z.ZodObject<{
                     fieldKey: z.ZodString;
                 }, z.core.$strip>;
             }, z.core.$strip>]>>>;
+            auth: z.ZodOptional<z.ZodObject<{
+                type: z.ZodLiteral<"oauth">;
+                clientId: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
             connectionTimeoutMs: z.ZodOptional<z.ZodNumber>;
             requestTimeoutMs: z.ZodOptional<z.ZodNumber>;
         }, z.core.$catchall<z.ZodUnknown>>>>;

package/dist/src/config/schema.js

@@ -64,7 +64,7 @@ function parseModelRef(ref) {
 		model: trimmed.slice(idx + 1).trim()
 	};
 }
-var AgentModelRefSchema, AgentImageGenerationModelSchema, AgentTypedModelRoleSchema, AgentTypedModelRolesSchema, AgentModelsSchema, AgentsConfigSchema, BrowserCloudConfigSchema, BrowserExtensionConfigSchema, BrowserCloakConfigSchema, BrowserConfigSchema, BindingMatchSchema, BindingRuleSchema, BindingsConfigSchema, SessionDmScopeSchema, SessionStorageConfigSchema, SessionResetModeSchema, SessionResetConfigSchema, SessionResetByTypeSchema, SessionScopeSchema, SessionConfigSchema, ChannelsConfigSchema, SearchProviderEntrySchema, WebSearchConfigSchema, WebsiteBlocklistSchema, WebToolsConfigSchema, ToolsConfigSchema, RuntimePreferenceSchema, RuntimeProvisionSchema, LanguageRuntimeSchema, DEFAULT_RUNTIME_TOOLS_CONFIG, RuntimeToolsConfigSchema, GatewayAuthRateLimitSchema, GatewaySecuritySchema, GatewayTrustedProxySchema, GatewayAuthSchema, GatewayTailscaleConsentSchema, GatewayTailscaleSchema, GatewayRemoteSchema, GatewayTlsSchema, GatewayModeSchema, HeartbeatConfigSchema, GatewayChannelConnectDeferModeSchema, TunnelConsentSchema, TunnelConfigSchema, WorkspaceImportConfigSchema, WorkspaceConfigSchema, GatewayBindModeSchema, GatewayWebchatConfigSchema, GatewayConfigSchema, ModelsDevConfigSchema, ModelCatalogConfigSchema, SttProviderConfigCatchallSchema, STTProviderConfigSchema, STTFallbackConfigSchema, MediaUnderstandingCapabilitiesSchema, MediaUnderstandingModelSchema, STTConfigSchema, TtsProviderConfigCatchallSchema, TTSProviderConfigSchema, TTSFallbackConfigSchema, TTSModelOverridesConfigSchema, TTSEdgeConfigSchema, TTSSummarizationConfigSchema, TTSConfigSchema, VoiceRefinementConfigSchema, VoiceConfigSchema, MessagesConfigSchema, ToolsMediaAudioConfigSchema, ToolsMediaConfigSchema, ProviderAzureConfigSchema, ProviderRequestOverridesSchema, ProviderAuthConfigSchema, ProvidersConfigSchema, ExtensionSecurityConfigSchema, ExtensionSlotsConfigSchema, ExtensionsConfigSchema, UpdateAutoConfigSchema, UpdateConfigSchema, CommandsConfigSchema, TuiConfigSchema, McpHttpUrlSchema, ConnectorSecretReferenceSchema, McpConfigScalarSchema, McpServerSchema, McpConfigSchema, ConnectorsConfigSchema, ExperimentalConfigSchema, ConfigSchema;
+var AgentModelRefSchema, AgentImageGenerationModelSchema, AgentTypedModelRoleSchema, AgentTypedModelRolesSchema, AgentModelsSchema, AgentsConfigSchema, BrowserCloudConfigSchema, BrowserExtensionConfigSchema, BrowserCloakConfigSchema, BrowserConfigSchema, BindingMatchSchema, BindingRuleSchema, BindingsConfigSchema, SessionDmScopeSchema, SessionStorageConfigSchema, SessionResetModeSchema, SessionResetConfigSchema, SessionResetByTypeSchema, SessionScopeSchema, SessionConfigSchema, ChannelsConfigSchema, SearchProviderEntrySchema, WebSearchConfigSchema, WebsiteBlocklistSchema, WebToolsConfigSchema, ToolsConfigSchema, RuntimePreferenceSchema, RuntimeProvisionSchema, LanguageRuntimeSchema, DEFAULT_RUNTIME_TOOLS_CONFIG, RuntimeToolsConfigSchema, GatewayAuthRateLimitSchema, GatewaySecuritySchema, GatewayTrustedProxySchema, GatewayAuthSchema, GatewayTailscaleConsentSchema, GatewayTailscaleSchema, GatewayRemoteSchema, GatewayTlsSchema, GatewayModeSchema, HeartbeatConfigSchema, GatewayChannelConnectDeferModeSchema, TunnelConsentSchema, TunnelConfigSchema, WorkspaceImportConfigSchema, WorkspaceConfigSchema, GatewayBindModeSchema, GatewayWebchatConfigSchema, GatewayConfigSchema, ModelsDevConfigSchema, ModelCatalogConfigSchema, SttProviderConfigCatchallSchema, STTProviderConfigSchema, STTFallbackConfigSchema, MediaUnderstandingCapabilitiesSchema, MediaUnderstandingModelSchema, STTConfigSchema, TtsProviderConfigCatchallSchema, TTSProviderConfigSchema, TTSFallbackConfigSchema, TTSModelOverridesConfigSchema, TTSEdgeConfigSchema, TTSSummarizationConfigSchema, TTSConfigSchema, VoiceRefinementConfigSchema, VoiceConfigSchema, MessagesConfigSchema, ToolsMediaAudioConfigSchema, ToolsMediaConfigSchema, ProviderAzureConfigSchema, ProviderRequestOverridesSchema, ProviderAuthConfigSchema, ProvidersConfigSchema, ExtensionSecurityConfigSchema, ExtensionSlotsConfigSchema, ExtensionsConfigSchema, UpdateAutoConfigSchema, UpdateConfigSchema, CommandsConfigSchema, TuiConfigSchema, McpHttpUrlSchema, ConnectorSecretReferenceSchema, McpConfigScalarSchema, McpOAuthConfigSchema, McpServerSchema, McpConfigSchema, ConnectorsConfigSchema, ExperimentalConfigSchema, ConfigSchema;
 var init_schema = __esmMin((() => {
 	init_schema$1();
 	init_preset_chain();
@@ -970,6 +970,11 @@ defaultAgent: z.string().min(1).optional() }).strict().default({});
 		z.boolean(),
 		ConnectorSecretReferenceSchema
 	]);
+	McpOAuthConfigSchema = z.object({
+		type: z.literal("oauth"),
+		/** Optional public client id for authorization servers without dynamic registration. */
+		clientId: z.string().min(1).optional()
+	}).strict();
 	McpServerSchema = z.object({
 		command: z.string().optional(),
 		args: z.array(z.string()).optional(),
@@ -979,6 +984,7 @@ defaultAgent: z.string().min(1).optional() }).strict().default({});
 		url: McpHttpUrlSchema.optional(),
 		transport: z.enum(["sse", "streamable-http"]).optional(),
 		headers: z.record(z.string(), McpConfigScalarSchema).optional(),
+		auth: McpOAuthConfigSchema.optional(),
 		connectionTimeoutMs: z.number().finite().positive().optional(),
 		requestTimeoutMs: z.number().finite().positive().optional()
 	}).catchall(z.unknown()).superRefine((value, ctx) => {
@@ -988,6 +994,24 @@ defaultAgent: z.string().min(1).optional() }).strict().default({});
 			code: "custom",
 			message: "MCP server cannot define both command and url"
 		});
+		if (value.auth && !hasUrl) ctx.addIssue({
+			code: "custom",
+			path: ["auth"],
+			message: "MCP OAuth requires an HTTP server URL"
+		});
+		if (value.auth && value.transport === "sse") ctx.addIssue({
+			code: "custom",
+			path: ["auth"],
+			message: "MCP OAuth currently supports streamable HTTP only"
+		});
+		if (value.auth && value.headers) {
+			const authorizationHeader = Object.keys(value.headers).find((key) => key.toLowerCase() === "authorization");
+			if (authorizationHeader) ctx.addIssue({
+				code: "custom",
+				path: ["headers", authorizationHeader],
+				message: "MCP OAuth cannot be combined with a static Authorization header"
+			});
+		}
 	});
 	McpConfigSchema = z.object({
 		servers: z.record(z.string(), McpServerSchema).optional(),
@@ -1148,4 +1172,4 @@ workDiscoveryOnboarding: z.boolean().default(true) }).strict().default({ workDis
 }));
 //#endregion
 init_schema();
-export { AgentImageGenerationModelSchema, AgentModelRefSchema, AgentModelsSchema, AgentTypedModelRoleSchema, AgentsConfigSchema, BindingMatchSchema, BindingRuleSchema, BindingsConfigSchema, BrowserConfigSchema, ChannelsConfigSchema, CommandsConfigSchema, ConfigSchema, ConnectorsConfigSchema, ExperimentalConfigSchema, ExtensionSecurityConfigSchema, ExtensionSlotsConfigSchema, ExtensionsConfigSchema, GatewayAuthRateLimitSchema, GatewayAuthSchema, GatewayBindModeSchema, GatewayChannelConnectDeferModeSchema, GatewayConfigSchema, GatewayModeSchema, GatewayRemoteSchema, GatewaySecuritySchema, GatewayTailscaleConsentSchema, GatewayTailscaleSchema, GatewayTlsSchema, GatewayTrustedProxySchema, GatewayWebchatConfigSchema, HeartbeatConfigSchema, McpConfigSchema, McpServerSchema, MediaUnderstandingCapabilitiesSchema, MediaUnderstandingModelSchema, MessagesConfigSchema, ModelCatalogConfigSchema, ModelsDevConfigSchema, ProviderAuthConfigSchema, ProviderAzureConfigSchema, ProviderRequestOverridesSchema, ProvidersConfigSchema, RuntimeToolsConfigSchema, STTConfigSchema, STTFallbackConfigSchema, STTProviderConfigSchema, SearchProviderEntrySchema, SessionConfigSchema, SessionDmScopeSchema, SessionResetByTypeSchema, SessionResetConfigSchema, SessionResetModeSchema, SessionScopeSchema, SessionStorageConfigSchema, TTSConfigSchema, TTSEdgeConfigSchema, TTSFallbackConfigSchema, TTSModelOverridesConfigSchema, TTSProviderConfigSchema, TTSSummarizationConfigSchema, TelegramAccountConfigSchema, TelegramConfigSchema, TelegramGroupConfigSchema, TelegramTopicConfigSchema, ToolsConfigSchema, ToolsMediaAudioConfigSchema, ToolsMediaConfigSchema, TuiConfigSchema, TunnelConfigSchema, TunnelConsentSchema, UpdateAutoConfigSchema, UpdateConfigSchema, VoiceConfigSchema, VoiceRefinementConfigSchema, WebSearchConfigSchema, WebToolsConfigSchema, WebsiteBlocklistSchema, WeixinAccountConfigSchema, WeixinConfigSchema, WorkspaceConfigSchema, WorkspaceImportConfigSchema, getAgentDefaultImageGenerationModelConfig, getAgentDefaultImageModelConfig, getAgentDefaultModelRef, init_schema, parseModelRef };
+export { AgentImageGenerationModelSchema, AgentModelRefSchema, AgentModelsSchema, AgentTypedModelRoleSchema, AgentsConfigSchema, BindingMatchSchema, BindingRuleSchema, BindingsConfigSchema, BrowserConfigSchema, ChannelsConfigSchema, CommandsConfigSchema, ConfigSchema, ConnectorsConfigSchema, ExperimentalConfigSchema, ExtensionSecurityConfigSchema, ExtensionSlotsConfigSchema, ExtensionsConfigSchema, GatewayAuthRateLimitSchema, GatewayAuthSchema, GatewayBindModeSchema, GatewayChannelConnectDeferModeSchema, GatewayConfigSchema, GatewayModeSchema, GatewayRemoteSchema, GatewaySecuritySchema, GatewayTailscaleConsentSchema, GatewayTailscaleSchema, GatewayTlsSchema, GatewayTrustedProxySchema, GatewayWebchatConfigSchema, HeartbeatConfigSchema, McpConfigSchema, McpOAuthConfigSchema, McpServerSchema, MediaUnderstandingCapabilitiesSchema, MediaUnderstandingModelSchema, MessagesConfigSchema, ModelCatalogConfigSchema, ModelsDevConfigSchema, ProviderAuthConfigSchema, ProviderAzureConfigSchema, ProviderRequestOverridesSchema, ProvidersConfigSchema, RuntimeToolsConfigSchema, STTConfigSchema, STTFallbackConfigSchema, STTProviderConfigSchema, SearchProviderEntrySchema, SessionConfigSchema, SessionDmScopeSchema, SessionResetByTypeSchema, SessionResetConfigSchema, SessionResetModeSchema, SessionScopeSchema, SessionStorageConfigSchema, TTSConfigSchema, TTSEdgeConfigSchema, TTSFallbackConfigSchema, TTSModelOverridesConfigSchema, TTSProviderConfigSchema, TTSSummarizationConfigSchema, TelegramAccountConfigSchema, TelegramConfigSchema, TelegramGroupConfigSchema, TelegramTopicConfigSchema, ToolsConfigSchema, ToolsMediaAudioConfigSchema, ToolsMediaConfigSchema, TuiConfigSchema, TunnelConfigSchema, TunnelConsentSchema, UpdateAutoConfigSchema, UpdateConfigSchema, VoiceConfigSchema, VoiceRefinementConfigSchema, WebSearchConfigSchema, WebToolsConfigSchema, WebsiteBlocklistSchema, WeixinAccountConfigSchema, WeixinConfigSchema, WorkspaceConfigSchema, WorkspaceImportConfigSchema, getAgentDefaultImageGenerationModelConfig, getAgentDefaultImageModelConfig, getAgentDefaultModelRef, init_schema, parseModelRef };

package/dist/src/connectors/auth-provider-registry.d.ts

@@ -7,4 +7,4 @@ export type ConnectorAuthStartResult = {
     authorizationUrl?: string;
     connectionId?: string;
 };
-export declare function startConnectorAuthorization(definition: ConnectorDefinition, config?: Config): Promise<ConnectorAuthStartResult>;
+export declare function startConnectorAuthorization(definition: ConnectorDefinition, config?: Config, instanceId?: string): Promise<ConnectorAuthStartResult>;

package/dist/src/connectors/auth-provider-registry.js

@@ -1,8 +1,29 @@
 import { startComposioAuthorize } from "./composio.js";
+import { isManagedConnectorServer } from "./materialize.js";
 import { getConnectorInstance } from "./instances.js";
+import { getMcpOAuthManager } from "../agent/mcp/oauth/mcp-oauth-manager.js";
 //#region src/connectors/auth-provider-registry.ts
-async function startConnectorAuthorization(definition, config) {
-	if (definition.auth.mode !== "oauth" || definition.auth.provider !== "composio" || definition.runtime.type !== "composio" || definition.runtime.role !== "toolkit") throw new Error(`Connector "${definition.id}" does not support Composio authorization.`);
+async function startConnectorAuthorization(definition, config, instanceId) {
+	if (definition.auth.mode !== "oauth") throw new Error(`Connector "${definition.id}" does not use OAuth.`);
+	if (definition.runtime.type === "mcp") {
+		if (!config) throw new Error("Connector configuration is required for MCP authorization.");
+		const serverId = instanceId ?? definition.runtime.serverId;
+		const server = config.mcp?.servers?.[serverId];
+		if (!server) throw new Error(`Connector MCP server not found: ${serverId}`);
+		if (!isManagedConnectorServer(server) || server.xopcConnector.connectorId !== definition.id) throw new Error(`MCP server "${serverId}" is not managed by connector "${definition.id}".`);
+		const status = await getMcpOAuthManager().start({
+			serverId,
+			rawServer: server,
+			cfg: config
+		});
+		return {
+			connectorId: definition.id,
+			provider: "mcp",
+			status: status.status,
+			authorizationUrl: status.session?.authorizationUrl
+		};
+	}
+	if (definition.auth.provider !== "composio" || definition.runtime.type !== "composio" || definition.runtime.role !== "toolkit") throw new Error(`Connector "${definition.id}" does not support OAuth authorization.`);
 	const configuredAuthConfigId = config ? getConnectorInstance(config, definition.id)?.config?.authConfigId : void 0;
 	const authConfigId = typeof configuredAuthConfigId === "string" && configuredAuthConfigId.trim() ? configuredAuthConfigId.trim() : void 0;
 	const authorization = await startComposioAuthorize(definition.id, definition.runtime.toolkit, void 0, authConfigId);

package/dist/src/connectors/install.js

@@ -1,7 +1,7 @@
 import { CredentialResolver, init_credentials } from "../auth/credentials.js";
 import { assertPreferredConnectorStrategy } from "./integration-strategy.js";
 import { getConnectorDefinition } from "./catalog.js";
-import { getConnectorInstance } from "./instances.js";
+import { getConnectorInstance, getInstalledConnectorDefinition } from "./instances.js";
 import { getConnectorRuntimeAdapter } from "./runtime-adapter-registry.js";
 //#region src/connectors/install.ts
 init_credentials();
@@ -22,7 +22,7 @@ async function installConnector(config, connectorId, input, resolver = new Crede
 function updateConnectorConfig(config, instanceId, input) {
 	const instance = getConnectorInstance(config, instanceId);
 	if (!instance) throw new Error(`Connector instance not found: ${instanceId}`);
-	const definition = getConnectorDefinition(instance.connectorId);
+	const definition = getInstalledConnectorDefinition(config, instanceId);
 	if (!definition) throw new Error(`Unknown connector: ${instance.connectorId}`);
 	const adapter = getConnectorRuntimeAdapter(definition.runtime.type);
 	if (!adapter.update) throw new Error(`Connector type "${definition.runtime.type}" does not support config updates.`);
@@ -40,7 +40,7 @@ function uninstallConnector(config, instanceId) {
 		if (config.mcp?.servers?.[instanceId] || config.connectors?.instances?.[instanceId]) throw new Error(`Connector instance "${instanceId}" is not managed by Connectors.`);
 		throw new Error(`Connector instance not found: ${instanceId}`);
 	}
-	const definition = getConnectorDefinition(instance.connectorId);
+	const definition = getInstalledConnectorDefinition(config, instanceId);
 	if (!definition) throw new Error(`Unknown connector: ${instance.connectorId}`);
 	getConnectorRuntimeAdapter(definition.runtime.type).uninstall({
 		config,

package/dist/src/connectors/instances.d.ts

@@ -1,4 +1,5 @@
 import type { Config } from '../config/schema.js';
-import type { ConnectorInstance } from './types.js';
+import type { ConnectorDefinition, ConnectorInstance } from './types.js';
 export declare function listConnectorInstances(config: Config): ConnectorInstance[];
 export declare function getConnectorInstance(config: Config, instanceId: string): ConnectorInstance | undefined;
+export declare function getInstalledConnectorDefinition(config: Config, instanceId: string): ConnectorDefinition | undefined;

package/dist/src/connectors/instances.js

@@ -1,5 +1,5 @@
 import { getConnectorDefinition } from "./catalog.js";
-import { isManagedConnectorServer } from "./materialize.js";
+import { connectorDefinitionFromManagedMarker, isManagedConnectorServer } from "./materialize.js";
 import { getConnectorAuditFromMarker, getConnectorUsageFromMarker } from "./usage.js";
 //#region src/connectors/instances.ts
 function readMarkerConfig(marker) {
@@ -9,7 +9,7 @@ function readMarkerConfig(marker) {
 }
 function secretStatusForServer(server) {
 	const marker = server.xopcConnector;
-	const definition = marker?.connectorId ? getConnectorDefinition(marker.connectorId) : void 0;
+	const definition = connectorDefinitionFromManagedMarker(marker) ?? (marker?.connectorId ? getConnectorDefinition(marker.connectorId) : void 0);
 	const env = server.env && typeof server.env === "object" && !Array.isArray(server.env) ? server.env : {};
 	const status = {};
 	for (const secret of definition?.setup.secrets ?? []) {
@@ -24,7 +24,7 @@ function connectorInstanceFromRecord(instanceId, record) {
 	const markerRecord = marker;
 	if (markerRecord.managed !== true || typeof markerRecord.connectorId !== "string") return [];
 	const connectorId = markerRecord.connectorId;
-	const definition = getConnectorDefinition(connectorId);
+	const definition = connectorDefinitionFromManagedMarker(markerRecord) ?? getConnectorDefinition(connectorId);
 	const runtime = record.runtime && typeof record.runtime === "object" && !Array.isArray(record.runtime) ? record.runtime : {};
 	const runtimeType = runtime.type;
 	if (runtimeType !== "composio" && runtimeType !== "channel" && runtimeType !== "nativeTool" && runtimeType !== "memorySource") return [];
@@ -66,7 +66,7 @@ function listConnectorInstances(config) {
 	const mcpInstances = Object.entries(servers).flatMap(([serverId, server]) => {
 		if (!isManagedConnectorServer(server)) return [];
 		const connectorId = server.xopcConnector.connectorId;
-		const definition = getConnectorDefinition(connectorId);
+		const definition = connectorDefinitionFromManagedMarker(server.xopcConnector) ?? getConnectorDefinition(connectorId);
 		const enabled = server.xopcConnector.enabled !== false;
 		const usage = getConnectorUsageFromMarker(server.xopcConnector);
 		const lastHealthStatus = usage.lastHealthStatus;
@@ -99,5 +99,15 @@ function listConnectorInstances(config) {
 function getConnectorInstance(config, instanceId) {
 	return listConnectorInstances(config).find((instance) => instance.instanceId === instanceId);
 }
+function getInstalledConnectorDefinition(config, instanceId) {
+	const server = config.mcp?.servers?.[instanceId];
+	if (server && isManagedConnectorServer(server)) return connectorDefinitionFromManagedMarker(server.xopcConnector) ?? getConnectorDefinition(server.xopcConnector.connectorId);
+	const record = config.connectors?.instances?.[instanceId];
+	if (record && typeof record === "object" && !Array.isArray(record)) {
+		const marker = record.xopcConnector;
+		const connectorId = marker && typeof marker === "object" && !Array.isArray(marker) ? marker.connectorId : void 0;
+		return connectorDefinitionFromManagedMarker(marker) ?? (typeof connectorId === "string" ? getConnectorDefinition(connectorId) : void 0);
+	}
+}
 //#endregion
-export { getConnectorInstance, listConnectorInstances };
+export { getConnectorInstance, getInstalledConnectorDefinition, listConnectorInstances };

package/dist/src/connectors/materialize.d.ts

@@ -4,6 +4,7 @@ export declare function materializeConnectorMcpServer(definition: ConnectorDefin
     serverId: string;
     server: Record<string, unknown>;
 };
+export declare function connectorDefinitionFromManagedMarker(marker: unknown): ConnectorDefinition | undefined;
 export declare function isManagedConnectorServer(server: unknown): server is Record<string, unknown> & {
     xopcConnector: ManagedConnectorMarker;
 };

package/dist/src/connectors/materialize.js

@@ -56,6 +56,7 @@ function materializeConnectorMcpServer(definition, input) {
 		displayName: definition.displayName,
 		source: definition.source,
 		artifactSha256: definition.provenance?.sha256,
+		definition,
 		...input.config && Object.keys(input.config).length > 0 ? { config: input.config } : {}
 	};
 	const server = {
@@ -69,10 +70,17 @@ function materializeConnectorMcpServer(definition, input) {
 		server
 	};
 }
+function connectorDefinitionFromManagedMarker(marker) {
+	if (!marker || typeof marker !== "object" || Array.isArray(marker)) return void 0;
+	const definition = marker.definition;
+	if (!definition || typeof definition !== "object" || Array.isArray(definition)) return void 0;
+	const record = definition;
+	return typeof record.id === "string" && typeof record.version === "string" && record.runtime ? record : void 0;
+}
 function isManagedConnectorServer(server) {
 	if (!server || typeof server !== "object" || Array.isArray(server)) return false;
 	const marker = server.xopcConnector;
 	return Boolean(marker && typeof marker === "object" && !Array.isArray(marker) && marker.managed === true && typeof marker.connectorId === "string");
 }
 //#endregion
-export { assertValidConnectorServerId, isManagedConnectorServer, materializeConnectorMcpServer };
+export { assertValidConnectorServerId, connectorDefinitionFromManagedMarker, isManagedConnectorServer, materializeConnectorMcpServer };

package/dist/src/connectors/runtime-adapter-registry.js

@@ -32,6 +32,7 @@ function installRecord(config, definition, extra = {}, markerExtra = {}) {
 				displayName: definition.displayName,
 				source: definition.source,
 				artifactSha256: definition.provenance?.sha256,
+				definition,
 				...markerExtra
 			},
 			runtime: definition.runtime,

package/dist/src/connectors/types.d.ts

@@ -8,7 +8,8 @@ export type ConnectorAuthDefinition = {
     mode: 'apiKey';
 } | {
     mode: 'oauth';
-    provider: string;
+    provider?: string;
+    clientId?: string;
 };
 export type ConnectorScope = 'read' | 'write' | 'admin';
 export type ConnectorVerificationLevel = 'verified' | 'beta' | 'experimental';
@@ -289,4 +290,6 @@ export type ManagedConnectorMarker = {
     config?: Record<string, unknown>;
     source?: ConnectorDefinition['source'];
     artifactSha256?: string;
+    /** Immutable install-time snapshot used for update, health, and uninstall after restart. */
+    definition?: ConnectorDefinition;
 };

package/dist/src/extensions/connector-dependencies.d.ts

@@ -0,0 +1,10 @@
+import type { Config } from '../config/schema.js';
+export type ExtensionConnectorDiagnostic = {
+    extensionId: string;
+    connectorId: string;
+    message: string;
+};
+export declare function inspectExtensionConnectorDependencies(params: {
+    cfg?: Config;
+    roots?: string[];
+}): ExtensionConnectorDiagnostic[];

package/dist/src/extensions/connector-dependencies.js

@@ -0,0 +1,65 @@
+import { init_paths, resolveBundledExtensionsDir, resolveExtensionsDir } from "../config/paths.js";
+import { isRecord } from "../utils/is-record.js";
+import { join } from "node:path";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+//#region src/extensions/connector-dependencies.ts
+init_paths();
+function isExtensionEnabled(extensionId, cfg) {
+	const disabled = cfg?.extensions?.disabled;
+	if (Array.isArray(disabled) && disabled.includes(extensionId)) return false;
+	const enabled = cfg?.extensions?.enabled;
+	return !Array.isArray(enabled) || enabled.length === 0 || enabled.includes(extensionId);
+}
+function enabledConnectorIds(cfg) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const server of Object.values(cfg?.mcp?.servers ?? {})) {
+		if (!isRecord(server) || !isRecord(server.xopcConnector)) continue;
+		if (server.xopcConnector.managed === true && server.xopcConnector.enabled !== false && typeof server.xopcConnector.connectorId === "string") ids.add(server.xopcConnector.connectorId);
+	}
+	for (const instance of Object.values(cfg?.connectors?.instances ?? {})) {
+		if (!isRecord(instance) || !isRecord(instance.xopcConnector)) continue;
+		if (instance.xopcConnector.managed === true && instance.xopcConnector.enabled !== false && typeof instance.xopcConnector.connectorId === "string") ids.add(instance.xopcConnector.connectorId);
+	}
+	return ids;
+}
+function scanRoot(params) {
+	if (!existsSync(params.root)) return;
+	for (const entry of readdirSync(params.root, { withFileTypes: true })) {
+		if (!entry.isDirectory() || params.seenExtensions.has(entry.name) || !isExtensionEnabled(entry.name, params.cfg)) continue;
+		const manifestPath = join(params.root, entry.name, "xopc.extension.json");
+		if (!existsSync(manifestPath)) continue;
+		params.seenExtensions.add(entry.name);
+		let manifest;
+		try {
+			manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+		} catch {
+			continue;
+		}
+		if (!isRecord(manifest) || !Array.isArray(manifest.connectorDependencies)) continue;
+		const dependencies = [...new Set(manifest.connectorDependencies.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean))];
+		for (const connectorId of dependencies) {
+			if (params.installed.has(connectorId)) continue;
+			params.diagnostics.push({
+				extensionId: entry.name,
+				connectorId,
+				message: `Extension "${entry.name}" requires enabled Connector "${connectorId}". Install and connect it from the Connector Store.`
+			});
+		}
+	}
+}
+function inspectExtensionConnectorDependencies(params) {
+	const diagnostics = [];
+	const installed = enabledConnectorIds(params.cfg);
+	const seenExtensions = /* @__PURE__ */ new Set();
+	const roots = params.roots ?? [resolveExtensionsDir(), resolveBundledExtensionsDir()].filter((root) => Boolean(root));
+	for (const root of roots) scanRoot({
+		root,
+		cfg: params.cfg,
+		installed,
+		seenExtensions,
+		diagnostics
+	});
+	return diagnostics;
+}
+//#endregion
+export { inspectExtensionConnectorDependencies };

package/dist/src/extensions/install.js

@@ -172,6 +172,24 @@ function isSafeZipPath(name) {
 	for (const p of normalized.split("/")) if (p === "..") return false;
 	return true;
 }
+function findEmbeddedMcpConfig(root) {
+	for (const entry of readdirSync(root, { withFileTypes: true })) {
+		if (entry.isSymbolicLink()) continue;
+		const path = join(root, entry.name);
+		if (entry.isFile() && entry.name.toLowerCase() === ".mcp.json") return path;
+		if (entry.isDirectory()) {
+			const nested = findEmbeddedMcpConfig(path);
+			if (nested) return nested;
+		}
+	}
+}
+function validateConnectorDependencies(value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) return "Extension connectorDependencies must be an array of unique Connector ids";
+	const dependencies = value;
+	const validId = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
+	if (dependencies.some((id) => !validId.test(id)) || new Set(dependencies).size !== dependencies.length) return "Extension connectorDependencies must be an array of unique Connector ids";
+}
 function isIgnorableZipEntry(name) {
 	const n = name.replace(/\\/g, "/");
 	if (n.startsWith("__MACOSX/")) return true;
@@ -448,6 +466,15 @@ async function installFromDirectory(sourceDir, extensionsDir) {
 		ok: false,
 		error: "Extension must include xopc.extension.json"
 	};
+	if (findEmbeddedMcpConfig(sourceDir)) return {
+		ok: false,
+		error: "Extensions must declare connectorDependencies instead of embedding .mcp.json"
+	};
+	const connectorDependencyError = validateConnectorDependencies(manifest.connectorDependencies);
+	if (connectorDependencyError) return {
+		ok: false,
+		error: connectorDependencyError
+	};
 	if (!manifest.engines?.xopc) return {
 		ok: false,
 		error: "Extension manifest must declare engines.xopc"

package/dist/src/extensions/normalize-manifest.js

@@ -130,6 +130,7 @@ function normalizeExtensionManifest(raw) {
 		main: typeof raw.main === "string" ? raw.main : void 0,
 		configSchema: isRecord(raw.configSchema) ? raw.configSchema : void 0,
 		dependencies: isRecord(raw.dependencies) ? raw.dependencies : void 0,
+		connectorDependencies: Array.isArray(raw.connectorDependencies) ? [...new Set(raw.connectorDependencies.filter((value) => typeof value === "string").map((value) => value.trim()).filter(Boolean))] : void 0,
 		enabledByDefault: typeof raw.enabledByDefault === "boolean" ? raw.enabledByDefault : void 0,
 		providers: Array.isArray(raw.providers) ? raw.providers.filter((x) => typeof x === "string") : void 0,
 		speechProviders: Array.isArray(raw.speechProviders) ? raw.speechProviders.filter((x) => typeof x === "string") : void 0,

package/dist/src/extensions/types/manifest.d.ts

@@ -20,6 +20,8 @@ export interface ExtensionManifest {
     main?: string;
     configSchema?: Record<string, unknown>;
     dependencies?: Record<string, string>;
+    /** Connector ids that must already be installed and enabled. Extensions never embed MCP server configuration. */
+    connectorDependencies?: string[];
     enabledByDefault?: boolean;
     providers?: string[];
     /** Speech/TTS provider ids implemented by this extension. */

package/dist/src/gateway/heartbeat/service.js

@@ -1,9 +1,9 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
 import { shouldSilence, stripHeartbeatToken } from "../../heartbeat/tokens.js";
+import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { isWithinActiveHours } from "../../heartbeat/active-hours.js";
 import { isHeartbeatContentEmpty } from "../../heartbeat/content-check.js";
-import { appendCronEventLines } from "../../heartbeat/event-prompt.js";
 import { createHeartbeatWake } from "../../heartbeat/wake.js";
 import { resolveHeartbeatMdPath } from "../workspace-heartbeat-path.js";
 import { readFile } from "fs/promises";

package/dist/src/gateway/hono/routes/capabilities.js

@@ -1,4 +1,5 @@
 import { getStoreConnectorInstallPlan, installStoreConnector, listStoreConnectors } from "../../../capabilities/store-connector.js";
+import { ConfigPersistenceError, persistConfigMutation } from "../../../config/config-mutation.js";
 //#region src/gateway/hono/routes/capabilities.ts
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
@@ -50,14 +51,13 @@ function registerCapabilityRoutes(authenticated, deps) {
 	authenticated.post("/api/capabilities/connectors/:name/install", strictRateLimitMiddleware, async (c) => {
 		const body = await c.req.json().catch(() => ({}));
 		const input = body && typeof body === "object" && !Array.isArray(body) ? body : {};
+		const config = service.currentConfig;
 		try {
-			const config = service.currentConfig;
-			const { instance, plan } = await installStoreConnector(config, c.req.param("name"), input, optionalVersion(body));
-			const saved = await service.saveConfig(config);
-			if (!saved.saved) return c.json({
-				ok: false,
-				error: saved.error ?? "Failed to save connector configuration."
-			}, 500);
+			const { instance, plan } = await persistConfigMutation({
+				config,
+				mutate: () => installStoreConnector(config, c.req.param("name"), input, optionalVersion(body)),
+				save: () => service.saveConfig(config)
+			});
 			return c.json({
 				ok: true,
 				payload: {
@@ -69,7 +69,7 @@ function registerCapabilityRoutes(authenticated, deps) {
 			return c.json({
 				ok: false,
 				error: errorMessage(error)
-			}, 400);
+			}, error instanceof ConfigPersistenceError ? 500 : 400);
 		}
 	});
 }