@xopcai/xopc 0.0.142 → 0.0.143

package/dist/src/connectors/policy.js

@@ -0,0 +1,48 @@
+//#region src/connectors/policy.ts
+const SCOPE_ORDER = {
+	read: 1,
+	write: 2,
+	admin: 3
+};
+function requiresConfirmation(policy, scope) {
+	if (policy === "always") return true;
+	if (policy === "writes") return scope === "write" || scope === "admin";
+	if (policy === "admin") return scope === "admin";
+	return false;
+}
+/** Evaluate every local policy layer before an external connector action is called. */
+function evaluateConnectorExecutionPolicy(input) {
+	const { installation, action } = input;
+	if (!installation.enabled) return {
+		decision: "denied",
+		reason: "Connector is disabled."
+	};
+	if (installation.allowedAgentIds.length > 0 && (!input.agentId || !installation.allowedAgentIds.includes(input.agentId))) return {
+		decision: "denied",
+		reason: "Agent is not allowed to use this connector."
+	};
+	if (installation.selectedConnectionIds.length > 0 && (!input.connectionId || !installation.selectedConnectionIds.includes(input.connectionId))) return {
+		decision: "denied",
+		reason: "Connection is not allowed by this connector policy."
+	};
+	if (SCOPE_ORDER[installation.maxScope] < SCOPE_ORDER[action.scope]) return {
+		decision: "denied",
+		reason: `Action requires ${action.scope} scope; connector allows ${installation.maxScope}.`
+	};
+	if (!action.curated && installation.maxScope !== "admin") return {
+		decision: "denied",
+		reason: "Unverified connector actions require admin scope."
+	};
+	if (!input.confirmed && requiresConfirmation(installation.confirmationPolicy, action.scope)) return {
+		decision: "confirmation_required",
+		reason: `Action requires ${action.scope} confirmation.`
+	};
+	return {
+		decision: "allowed",
+		reason: "Connector policy allows this action."
+	};
+}
+//#endregion
+export { evaluateConnectorExecutionPolicy };
+
+//# sourceMappingURL=policy.js.map

package/dist/src/connectors/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","names":[],"sources":["../../../src/connectors/policy.ts"],"sourcesContent":["import type {\n  ConnectorActionMetadata,\n  ConnectorExecutionDecision,\n  ConnectorInstallationPolicy,\n  ConnectorScope,\n} from './types.js';\n\nconst SCOPE_ORDER: Record<ConnectorScope, number> = {\n  read: 1,\n  write: 2,\n  admin: 3,\n};\n\nexport type ConnectorPolicyEvaluation = {\n  decision: ConnectorExecutionDecision;\n  reason: string;\n};\n\nfunction requiresConfirmation(\n  policy: ConnectorInstallationPolicy['confirmationPolicy'],\n  scope: ConnectorScope,\n): boolean {\n  if (policy === 'always') return true;\n  if (policy === 'writes') return scope === 'write' || scope === 'admin';\n  if (policy === 'admin') return scope === 'admin';\n  return false;\n}\n\n/** Evaluate every local policy layer before an external connector action is called. */\nexport function evaluateConnectorExecutionPolicy(input: {\n  installation: ConnectorInstallationPolicy;\n  action: Pick<ConnectorActionMetadata, 'scope' | 'curated'>;\n  agentId?: string;\n  connectionId?: string;\n  confirmed?: boolean;\n}): ConnectorPolicyEvaluation {\n  const { installation, action } = input;\n  if (!installation.enabled) {\n    return { decision: 'denied', reason: 'Connector is disabled.' };\n  }\n  if (\n    installation.allowedAgentIds.length > 0 &&\n    (!input.agentId || !installation.allowedAgentIds.includes(input.agentId))\n  ) {\n    return { decision: 'denied', reason: 'Agent is not allowed to use this connector.' };\n  }\n  if (\n    installation.selectedConnectionIds.length > 0 &&\n    (!input.connectionId || !installation.selectedConnectionIds.includes(input.connectionId))\n  ) {\n    return { decision: 'denied', reason: 'Connection is not allowed by this connector policy.' };\n  }\n  if (SCOPE_ORDER[installation.maxScope] < SCOPE_ORDER[action.scope]) {\n    return {\n      decision: 'denied',\n      reason: `Action requires ${action.scope} scope; connector allows ${installation.maxScope}.`,\n    };\n  }\n  if (!action.curated && installation.maxScope !== 'admin') {\n    return {\n      decision: 'denied',\n      reason: 'Unverified connector actions require admin scope.',\n    };\n  }\n  if (!input.confirmed && requiresConfirmation(installation.confirmationPolicy, action.scope)) {\n    return {\n      decision: 'confirmation_required',\n      reason: `Action requires ${action.scope} confirmation.`,\n    };\n  }\n  return { decision: 'allowed', reason: 'Connector policy allows this action.' };\n}\n"],"mappings":";AAOA,MAAM,cAA8C;CAClD,MAAM;CACN,OAAO;CACP,OAAO;CACR;AAOD,SAAS,qBACP,QACA,OACS;AACT,KAAI,WAAW,SAAU,QAAO;AAChC,KAAI,WAAW,SAAU,QAAO,UAAU,WAAW,UAAU;AAC/D,KAAI,WAAW,QAAS,QAAO,UAAU;AACzC,QAAO;;;AAIT,SAAgB,iCAAiC,OAMnB;CAC5B,MAAM,EAAE,cAAc,WAAW;AACjC,KAAI,CAAC,aAAa,QAChB,QAAO;EAAE,UAAU;EAAU,QAAQ;EAA0B;AAEjE,KACE,aAAa,gBAAgB,SAAS,MACrC,CAAC,MAAM,WAAW,CAAC,aAAa,gBAAgB,SAAS,MAAM,QAAQ,EAExE,QAAO;EAAE,UAAU;EAAU,QAAQ;EAA+C;AAEtF,KACE,aAAa,sBAAsB,SAAS,MAC3C,CAAC,MAAM,gBAAgB,CAAC,aAAa,sBAAsB,SAAS,MAAM,aAAa,EAExF,QAAO;EAAE,UAAU;EAAU,QAAQ;EAAuD;AAE9F,KAAI,YAAY,aAAa,YAAY,YAAY,OAAO,OAC1D,QAAO;EACL,UAAU;EACV,QAAQ,mBAAmB,OAAO,MAAM,2BAA2B,aAAa,SAAS;EAC1F;AAEH,KAAI,CAAC,OAAO,WAAW,aAAa,aAAa,QAC/C,QAAO;EACL,UAAU;EACV,QAAQ;EACT;AAEH,KAAI,CAAC,MAAM,aAAa,qBAAqB,aAAa,oBAAoB,OAAO,MAAM,CACzF,QAAO;EACL,UAAU;EACV,QAAQ,mBAAmB,OAAO,MAAM;EACzC;AAEH,QAAO;EAAE,UAAU;EAAW,QAAQ;EAAwC"}

package/dist/src/connectors/providers.js

@@ -1,5 +1,5 @@
-import { COMPOSIO_CONNECTORS } from "./composio.js";
 import { BUILTIN_CONNECTORS } from "./builtin-catalog.js";
+import { COMPOSIO_CONNECTORS } from "./composio.js";
 //#region src/connectors/providers.ts
 const builtinConnectorProvider = {
 	id: "builtin",

package/dist/src/connectors/runtime-adapter-registry.d.ts

@@ -0,0 +1,25 @@
+import type { CredentialResolver } from '../auth/credentials.js';
+import type { Config } from '../config/schema.js';
+import type { ConnectorDefinition, ConnectorInstallInput, ConnectorInstance, ConnectorRuntimeDefinition } from './types.js';
+export type ConnectorRuntimeInstallContext = {
+    config: Config;
+    definition: ConnectorDefinition;
+    input: ConnectorInstallInput;
+    resolver: CredentialResolver;
+};
+export type ConnectorRuntimeUninstallContext = {
+    config: Config;
+    definition: ConnectorDefinition;
+    instance: ConnectorInstance;
+};
+export type ConnectorRuntimeUpdateContext = ConnectorRuntimeInstallContext & {
+    instanceId: string;
+};
+export type ConnectorRuntimeAdapter = {
+    type: ConnectorRuntimeDefinition['type'];
+    install(context: ConnectorRuntimeInstallContext): Promise<ConnectorInstance>;
+    uninstall(context: ConnectorRuntimeUninstallContext): void;
+    update?(context: ConnectorRuntimeUpdateContext): ConnectorInstance;
+};
+export declare function registerConnectorRuntimeAdapter(adapter: ConnectorRuntimeAdapter): void;
+export declare function getConnectorRuntimeAdapter(type: ConnectorRuntimeDefinition['type']): ConnectorRuntimeAdapter;

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

@@ -0,0 +1,154 @@
+import { isXopcDatabaseOpen } from "../storage/sqlite/connection.js";
+import { deleteConnectorInstallation, getConnectorInstallation, upsertConnectorInstallation } from "../storage/sqlite/connector-repository.js";
+import "../storage/sqlite/index.js";
+import { assertComposioApiKeyConfigured } from "./composio-sessions.js";
+import { saveComposioApiKey } from "./composio.js";
+import { saveConnectorSecrets } from "./secret-store.js";
+import { isManagedConnectorServer, materializeConnectorMcpServer } from "./materialize.js";
+import { appendConnectorAuditRecord } from "./usage.js";
+import { listConnectorInstances } from "./instances.js";
+//#region src/connectors/runtime-adapter-registry.ts
+const adapters = /* @__PURE__ */ new Map();
+function registerConnectorRuntimeAdapter(adapter) {
+	if (adapters.has(adapter.type)) throw new Error(`Connector runtime adapter is already registered: ${adapter.type}`);
+	adapters.set(adapter.type, adapter);
+}
+function installedInstance(config, instanceId, connectorId) {
+	const instance = listConnectorInstances(config).find((candidate) => candidate.instanceId === instanceId);
+	if (!instance) throw new Error(`Connector "${connectorId}" was installed but could not be resolved.`);
+	return instance;
+}
+function installRecord(config, definition, extra = {}) {
+	const instanceId = definition.id;
+	config.connectors = config.connectors ?? {};
+	config.connectors.instances = {
+		...config.connectors.instances ?? {},
+		[instanceId]: {
+			xopcConnector: {
+				managed: true,
+				connectorId: definition.id,
+				version: definition.version,
+				enabled: true,
+				displayName: definition.displayName,
+				source: definition.source,
+				artifactSha256: definition.provenance?.sha256
+			},
+			runtime: definition.runtime,
+			...extra
+		}
+	};
+	return installedInstance(config, instanceId, definition.id);
+}
+function uninstallRecord(config, instanceId) {
+	if (!config.connectors?.instances?.[instanceId]) throw new Error(`Connector instance not found: ${instanceId}`);
+	const nextInstances = { ...config.connectors?.instances ?? {} };
+	delete nextInstances[instanceId];
+	config.connectors = {
+		...config.connectors ?? {},
+		instances: nextInstances
+	};
+}
+registerConnectorRuntimeAdapter({
+	type: "mcp",
+	async install({ config, definition, input, resolver }) {
+		if (definition.runtime.type !== "mcp") throw new Error(`Invalid MCP connector definition: ${definition.id}`);
+		const { serverId, server } = materializeConnectorMcpServer(definition, input);
+		const existingServer = config.mcp?.servers?.[serverId];
+		if (existingServer && !isManagedConnectorServer(existingServer)) throw new Error(`MCP server "${serverId}" already exists and is not managed by Connectors.`);
+		await saveConnectorSecrets(definition, input, resolver);
+		config.mcp = config.mcp ?? {};
+		config.mcp.servers = {
+			...config.mcp.servers ?? {},
+			[serverId]: server
+		};
+		const instance = installedInstance(config, serverId, definition.id);
+		appendConnectorAuditRecord(config, serverId, { action: "installed" });
+		return instance;
+	},
+	uninstall({ config, instance }) {
+		const server = config.mcp?.servers?.[instance.instanceId];
+		if (!server || !isManagedConnectorServer(server)) throw new Error(`MCP server "${instance.instanceId}" is not managed by Connectors.`);
+		appendConnectorAuditRecord(config, instance.instanceId, { action: "removed" });
+		const nextServers = { ...config.mcp?.servers ?? {} };
+		delete nextServers[instance.instanceId];
+		config.mcp = {
+			...config.mcp ?? {},
+			servers: nextServers
+		};
+	},
+	update({ config, definition, input, instanceId }) {
+		if (definition.runtime.type !== "mcp") throw new Error(`Invalid MCP connector definition: ${definition.id}`);
+		const existingServer = config.mcp?.servers?.[instanceId];
+		if (!existingServer || !isManagedConnectorServer(existingServer)) throw new Error(`MCP server "${instanceId}" is not managed by Connectors.`);
+		if ((definition.setup.secrets ?? []).length > 0) throw new Error("Connectors with secrets must be reinstalled to change configuration.");
+		const { serverId, server } = materializeConnectorMcpServer(definition, input);
+		if (serverId !== instanceId) throw new Error(`Connector config update cannot change server id from "${instanceId}" to "${serverId}".`);
+		config.mcp = config.mcp ?? {};
+		config.mcp.servers = {
+			...config.mcp.servers ?? {},
+			[serverId]: {
+				...server,
+				xopcConnector: {
+					...existingServer.xopcConnector,
+					...server.xopcConnector,
+					enabled: existingServer.xopcConnector.enabled,
+					lastConnectedAt: existingServer.xopcConnector.lastConnectedAt,
+					lastError: existingServer.xopcConnector.lastError
+				}
+			}
+		};
+		return installedInstance(config, serverId, definition.id);
+	}
+});
+registerConnectorRuntimeAdapter({
+	type: "composio",
+	async install({ config, definition, input, resolver }) {
+		if (definition.runtime.type !== "composio") throw new Error(`Invalid Composio connector definition: ${definition.id}`);
+		if (definition.runtime.role === "credential") await saveComposioApiKey(input, resolver);
+		if (definition.runtime.role === "toolkit") await assertComposioApiKeyConfigured(resolver);
+		const instance = installRecord(config, definition, definition.runtime.role === "toolkit" ? { scope: "read" } : {});
+		if (definition.runtime.role === "toolkit" && isXopcDatabaseOpen()) {
+			const installationId = `${definition.id}-local-owner`;
+			const existing = getConnectorInstallation(installationId);
+			upsertConnectorInstallation({
+				id: installationId,
+				connectorId: definition.id,
+				principalId: "local-owner",
+				enabled: true,
+				allowedAgentIds: existing?.allowedAgentIds ?? [],
+				maxScope: "read",
+				confirmationPolicy: existing?.confirmationPolicy ?? "writes",
+				selectedConnectionIds: existing?.selectedConnectionIds ?? [],
+				createdAt: existing?.createdAt
+			});
+		}
+		return instance;
+	},
+	uninstall({ config, definition, instance }) {
+		if (definition.runtime.type !== "composio") throw new Error(`Invalid Composio connector definition: ${definition.id}`);
+		uninstallRecord(config, instance.instanceId);
+		if (definition.runtime.role === "toolkit" && isXopcDatabaseOpen()) deleteConnectorInstallation(`${definition.id}-local-owner`);
+	}
+});
+for (const type of [
+	"channel",
+	"nativeTool",
+	"memorySource"
+]) registerConnectorRuntimeAdapter({
+	type,
+	async install({ config, definition }) {
+		return installRecord(config, definition);
+	},
+	uninstall({ config, instance }) {
+		uninstallRecord(config, instance.instanceId);
+	}
+});
+function getConnectorRuntimeAdapter(type) {
+	const adapter = adapters.get(type);
+	if (!adapter) throw new Error(`Unknown connector runtime adapter: ${type}`);
+	return adapter;
+}
+//#endregion
+export { getConnectorRuntimeAdapter, registerConnectorRuntimeAdapter };
+
+//# sourceMappingURL=runtime-adapter-registry.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-adapter-registry.js","names":[],"sources":["../../../src/connectors/runtime-adapter-registry.ts"],"sourcesContent":["import type { CredentialResolver } from '../auth/credentials.js';\nimport type { Config } from '../config/schema.js';\nimport {\n  deleteConnectorInstallation,\n  getConnectorInstallation,\n  isXopcDatabaseOpen,\n  upsertConnectorInstallation,\n} from '../storage/sqlite/index.js';\nimport { saveComposioApiKey } from './composio.js';\nimport { assertComposioApiKeyConfigured } from './composio-sessions.js';\nimport { listConnectorInstances } from './instances.js';\nimport { isManagedConnectorServer, materializeConnectorMcpServer } from './materialize.js';\nimport { saveConnectorSecrets } from './secret-store.js';\nimport { appendConnectorAuditRecord } from './usage.js';\nimport type {\n  ConnectorDefinition,\n  ConnectorInstallInput,\n  ConnectorInstance,\n  ConnectorRuntimeDefinition,\n} from './types.js';\n\nexport type ConnectorRuntimeInstallContext = {\n  config: Config;\n  definition: ConnectorDefinition;\n  input: ConnectorInstallInput;\n  resolver: CredentialResolver;\n};\n\nexport type ConnectorRuntimeUninstallContext = {\n  config: Config;\n  definition: ConnectorDefinition;\n  instance: ConnectorInstance;\n};\n\nexport type ConnectorRuntimeUpdateContext = ConnectorRuntimeInstallContext & { instanceId: string };\n\nexport type ConnectorRuntimeAdapter = {\n  type: ConnectorRuntimeDefinition['type'];\n  install(context: ConnectorRuntimeInstallContext): Promise<ConnectorInstance>;\n  uninstall(context: ConnectorRuntimeUninstallContext): void;\n  update?(context: ConnectorRuntimeUpdateContext): ConnectorInstance;\n};\n\nconst adapters = new Map<ConnectorRuntimeDefinition['type'], ConnectorRuntimeAdapter>();\n\nexport function registerConnectorRuntimeAdapter(adapter: ConnectorRuntimeAdapter): void {\n  if (adapters.has(adapter.type)) throw new Error(`Connector runtime adapter is already registered: ${adapter.type}`);\n  adapters.set(adapter.type, adapter);\n}\n\nfunction installedInstance(config: Config, instanceId: string, connectorId: string): ConnectorInstance {\n  const instance = listConnectorInstances(config).find((candidate) => candidate.instanceId === instanceId);\n  if (!instance) throw new Error(`Connector \"${connectorId}\" was installed but could not be resolved.`);\n  return instance;\n}\n\nfunction installRecord(config: Config, definition: ConnectorDefinition, extra: Record<string, unknown> = {}): ConnectorInstance {\n  const instanceId = definition.id;\n  config.connectors = config.connectors ?? {};\n  config.connectors.instances = {\n    ...(config.connectors.instances ?? {}),\n    [instanceId]: {\n      xopcConnector: {\n        managed: true,\n        connectorId: definition.id,\n        version: definition.version,\n        enabled: true,\n        displayName: definition.displayName,\n        source: definition.source,\n        artifactSha256: definition.provenance?.sha256,\n      },\n      runtime: definition.runtime,\n      ...extra,\n    },\n  };\n  return installedInstance(config, instanceId, definition.id);\n}\n\nfunction uninstallRecord(config: Config, instanceId: string): void {\n  const record = config.connectors?.instances?.[instanceId];\n  if (!record) throw new Error(`Connector instance not found: ${instanceId}`);\n  const nextInstances = { ...(config.connectors?.instances ?? {}) };\n  delete nextInstances[instanceId];\n  config.connectors = { ...(config.connectors ?? {}), instances: nextInstances };\n}\n\nregisterConnectorRuntimeAdapter({\n  type: 'mcp',\n  async install({ config, definition, input, resolver }) {\n    if (definition.runtime.type !== 'mcp') throw new Error(`Invalid MCP connector definition: ${definition.id}`);\n    const { serverId, server } = materializeConnectorMcpServer(definition, input);\n    const existingServer = config.mcp?.servers?.[serverId];\n    if (existingServer && !isManagedConnectorServer(existingServer)) {\n      throw new Error(`MCP server \"${serverId}\" already exists and is not managed by Connectors.`);\n    }\n    await saveConnectorSecrets(definition, input, resolver);\n    config.mcp = config.mcp ?? {};\n    config.mcp.servers = { ...(config.mcp.servers ?? {}), [serverId]: server };\n    const instance = installedInstance(config, serverId, definition.id);\n    appendConnectorAuditRecord(config, serverId, { action: 'installed' });\n    return instance;\n  },\n  uninstall({ config, instance }) {\n    const server = config.mcp?.servers?.[instance.instanceId];\n    if (!server || !isManagedConnectorServer(server)) {\n      throw new Error(`MCP server \"${instance.instanceId}\" is not managed by Connectors.`);\n    }\n    appendConnectorAuditRecord(config, instance.instanceId, { action: 'removed' });\n    const nextServers = { ...(config.mcp?.servers ?? {}) };\n    delete nextServers[instance.instanceId];\n    config.mcp = { ...(config.mcp ?? {}), servers: nextServers };\n  },\n  update({ config, definition, input, instanceId }) {\n    if (definition.runtime.type !== 'mcp') throw new Error(`Invalid MCP connector definition: ${definition.id}`);\n    const existingServer = config.mcp?.servers?.[instanceId];\n    if (!existingServer || !isManagedConnectorServer(existingServer)) {\n      throw new Error(`MCP server \"${instanceId}\" is not managed by Connectors.`);\n    }\n    if ((definition.setup.secrets ?? []).length > 0) {\n      throw new Error('Connectors with secrets must be reinstalled to change configuration.');\n    }\n    const { serverId, server } = materializeConnectorMcpServer(definition, input);\n    if (serverId !== instanceId) {\n      throw new Error(`Connector config update cannot change server id from \"${instanceId}\" to \"${serverId}\".`);\n    }\n    config.mcp = config.mcp ?? {};\n    config.mcp.servers = {\n      ...(config.mcp.servers ?? {}),\n      [serverId]: {\n        ...server,\n        xopcConnector: {\n          ...existingServer.xopcConnector,\n          ...(server.xopcConnector as Record<string, unknown>),\n          enabled: existingServer.xopcConnector.enabled,\n          lastConnectedAt: existingServer.xopcConnector.lastConnectedAt,\n          lastError: existingServer.xopcConnector.lastError,\n        },\n      },\n    };\n    return installedInstance(config, serverId, definition.id);\n  },\n});\n\nregisterConnectorRuntimeAdapter({\n  type: 'composio',\n  async install({ config, definition, input, resolver }) {\n    if (definition.runtime.type !== 'composio') throw new Error(`Invalid Composio connector definition: ${definition.id}`);\n    if (definition.runtime.role === 'credential') await saveComposioApiKey(input, resolver);\n    if (definition.runtime.role === 'toolkit') await assertComposioApiKeyConfigured(resolver);\n    const instance = installRecord(\n      config,\n      definition,\n      definition.runtime.role === 'toolkit' ? { scope: 'read' } : {},\n    );\n    if (definition.runtime.role === 'toolkit' && isXopcDatabaseOpen()) {\n      const installationId = `${definition.id}-local-owner`;\n      const existing = getConnectorInstallation(installationId);\n      upsertConnectorInstallation({\n        id: installationId,\n        connectorId: definition.id,\n        principalId: 'local-owner',\n        enabled: true,\n        allowedAgentIds: existing?.allowedAgentIds ?? [],\n        maxScope: 'read',\n        confirmationPolicy: existing?.confirmationPolicy ?? 'writes',\n        selectedConnectionIds: existing?.selectedConnectionIds ?? [],\n        createdAt: existing?.createdAt,\n      });\n    }\n    return instance;\n  },\n  uninstall({ config, definition, instance }) {\n    if (definition.runtime.type !== 'composio') throw new Error(`Invalid Composio connector definition: ${definition.id}`);\n    uninstallRecord(config, instance.instanceId);\n    if (definition.runtime.role === 'toolkit' && isXopcDatabaseOpen()) {\n      deleteConnectorInstallation(`${definition.id}-local-owner`);\n    }\n  },\n});\n\nfor (const type of ['channel', 'nativeTool', 'memorySource'] as const) {\n  registerConnectorRuntimeAdapter({\n    type,\n    async install({ config, definition }) {\n      return installRecord(config, definition);\n    },\n    uninstall({ config, instance }) {\n      uninstallRecord(config, instance.instanceId);\n    },\n  });\n}\n\nexport function getConnectorRuntimeAdapter(type: ConnectorRuntimeDefinition['type']): ConnectorRuntimeAdapter {\n  const adapter = adapters.get(type);\n  if (!adapter) throw new Error(`Unknown connector runtime adapter: ${type}`);\n  return adapter;\n}\n"],"mappings":"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"}

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

@@ -2,12 +2,38 @@ export type ConnectorKind = 'mcp' | 'cli' | 'http' | 'channel' | 'browser' | 'ex
 export type ConnectorCategory = 'code' | 'docs' | 'browser' | 'data' | 'automation' | 'custom';
 export type ConnectorCapability = 'tools' | 'resources' | 'prompts' | 'context' | 'channel' | 'events' | 'ui' | 'memory_source' | 'workflows' | 'auth.apiKey' | 'auth.oauth' | 'runtime.mcp.stdio' | 'runtime.mcp.sse' | 'runtime.mcp.streamableHttp';
 export type ConnectorAuthMode = 'none' | 'apiKey' | 'oauth';
+export type ConnectorAuthDefinition = {
+    mode: 'none';
+} | {
+    mode: 'apiKey';
+} | {
+    mode: 'oauth';
+    provider: string;
+};
+export type ConnectorScope = 'read' | 'write' | 'admin';
+export type ConnectorVerificationLevel = 'verified' | 'beta' | 'experimental';
+export type ConnectorBranding = {
+    logoUrl?: string;
+    source?: 'builtin' | 'composio-catalog' | 'registry' | 'extension' | 'custom';
+    backgroundColor?: string;
+    fetchedAt?: string;
+};
+export type ConnectorConfirmationPolicy = 'always' | 'writes' | 'admin' | 'never';
 export type ConnectorPermissions = {
     data?: string[];
     networkDomains?: string[];
     localExec?: boolean;
     filesystem?: string[];
 };
+export type ConnectorIntegrationStrategy = {
+    lane: 'native' | 'mcp' | 'composio';
+    workload: 'core' | 'high_frequency' | 'long_tail';
+    preferred: boolean;
+    alternative?: {
+        kind: 'channel' | 'connector';
+        id: string;
+    };
+};
 export type ConnectorSecretReference = {
     xopcSecretRef: {
         provider: string;
@@ -45,6 +71,7 @@ export type ConnectorRuntimeDefinition = {
 } | {
     type: 'composio';
     toolkit: string;
+    role: 'credential' | 'toolkit';
 } | {
     type: 'nativeTool';
     toolsetId: string;
@@ -62,20 +89,97 @@ export type ConnectorDefinition = {
     source: 'builtin' | 'extension' | 'custom' | 'registry' | 'store';
     capabilities: ConnectorCapability[];
     tags?: string[];
-    auth: {
-        mode: ConnectorAuthMode;
-    };
+    branding?: ConnectorBranding;
+    verificationLevel?: ConnectorVerificationLevel;
+    auth: ConnectorAuthDefinition;
     setup: {
         secrets?: ConnectorSecretField[];
         config?: ConnectorConfigField[];
     };
     runtime: ConnectorRuntimeDefinition;
     permissions?: ConnectorPermissions;
+    integrationStrategy?: ConnectorIntegrationStrategy;
     provenance?: {
         packageName: string;
         sha256: string;
     };
 };
+export type ConnectorInstallationPolicy = {
+    id: string;
+    connectorId: string;
+    principalId: string;
+    enabled: boolean;
+    allowedAgentIds: string[];
+    maxScope: ConnectorScope;
+    confirmationPolicy: ConnectorConfirmationPolicy;
+    selectedConnectionIds: string[];
+    createdAt: string;
+    updatedAt: string;
+};
+export type ConnectorConnectionStatus = 'pending' | 'active' | 'expired' | 'failed' | 'revoked' | 'disabled' | 'unknown';
+export type ConnectorConnection = {
+    id: string;
+    installationId?: string;
+    connectorId: string;
+    provider: string;
+    principalId: string;
+    providerConnectionId: string;
+    alias?: string;
+    identity: Record<string, unknown>;
+    status: ConnectorConnectionStatus;
+    isDefault: boolean;
+    connectedAt?: string;
+    expiresAt?: string;
+    lastError?: string;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+};
+export type ConnectorActionMetadata = {
+    connectorId: string;
+    actionId: string;
+    toolkit?: string;
+    scope: ConnectorScope;
+    curated: boolean;
+    inputSchema?: unknown;
+    schemaVersion?: string;
+    cachedAt: string;
+};
+export type ConnectorExecutionDecision = 'allowed' | 'denied' | 'confirmation_required';
+export type ConnectorExecutionAuditRecord = {
+    id: string;
+    installationId?: string;
+    connectionId?: string;
+    connectorId: string;
+    principalId: string;
+    agentId?: string;
+    sessionKey?: string;
+    actionId: string;
+    scope: ConnectorScope;
+    decision: ConnectorExecutionDecision;
+    resultStatus: 'success' | 'error' | 'not_executed';
+    durationMs?: number;
+    errorCode?: string;
+    createdAt: string;
+};
+export type ConnectorApprovalStatus = 'pending' | 'approved' | 'denied' | 'expired' | 'consumed';
+export type ConnectorApprovalRecord = {
+    id: string;
+    principalId: string;
+    connectorId: string;
+    connectionId?: string;
+    agentId?: string;
+    sessionKey?: string;
+    actionId: string;
+    scope: ConnectorScope;
+    argumentsHash: string;
+    argumentsPreview: Record<string, unknown>;
+    status: ConnectorApprovalStatus;
+    expiresAt: string;
+    createdAt: string;
+    decidedAt?: string;
+    consumedAt?: string;
+};
 export type ConnectorInstallInput = {
     secrets?: Record<string, unknown>;
     config?: Record<string, unknown>;
@@ -112,7 +216,12 @@ export type ConnectorInstance = {
         type: 'mcp';
         serverId: string;
     } | {
-        type: 'channel' | 'composio' | 'nativeTool' | 'memorySource';
+        type: 'composio';
+        id: string;
+        toolkit: string;
+        role: 'credential' | 'toolkit';
+    } | {
+        type: 'channel' | 'nativeTool' | 'memorySource';
         id: string;
     };
     usage: ConnectorUsageRecord;

package/dist/src/connectors/workflow-preflight.d.ts

@@ -0,0 +1,20 @@
+import type { Config } from '../config/schema.js';
+import type { WorkflowDefinition } from '../workflows/domain/definition.js';
+export type ConnectorPreflightIssueCode = 'not_installed' | 'disabled' | 'agent_not_allowed' | 'scope_too_narrow' | 'connection_missing' | 'reauthorization_required';
+export type ConnectorPreflightIssue = {
+    connectorId: string;
+    code: ConnectorPreflightIssueCode;
+    message: string;
+    recoveryPath: string;
+};
+export type ConnectorPreflightResult = {
+    ok: boolean;
+    issues: ConnectorPreflightIssue[];
+    optionalIssues: ConnectorPreflightIssue[];
+};
+export declare function preflightWorkflowConnectors(input: {
+    definition: WorkflowDefinition;
+    config: Config;
+    agentId: string;
+    principalId?: string;
+}): ConnectorPreflightResult;

package/dist/src/connectors/workflow-preflight.js

@@ -0,0 +1,70 @@
+import { getConnectorInstallation, listConnectorConnections } from "../storage/sqlite/connector-repository.js";
+import { getComposioToolkitScope } from "./composio.js";
+import { getConnectorDefinition } from "./catalog.js";
+import { listConnectorInstances } from "./instances.js";
+//#region src/connectors/workflow-preflight.ts
+const SCOPE_ORDER = {
+	read: 1,
+	write: 2,
+	admin: 3
+};
+function issue(requirement, code, message) {
+	return {
+		connectorId: requirement.connectorId,
+		code,
+		message,
+		recoveryPath: `/connectors?connector=${encodeURIComponent(requirement.connectorId)}`
+	};
+}
+function preflightWorkflowConnectors(input) {
+	const principalId = input.principalId ?? "local-owner";
+	const instances = listConnectorInstances(input.config);
+	const issues = [];
+	const optionalIssues = [];
+	const add = (requirement, value) => {
+		(requirement.optional ? optionalIssues : issues).push(value);
+	};
+	for (const requirement of input.definition.connectors ?? []) {
+		const instance = instances.find((candidate) => candidate.connectorId === requirement.connectorId);
+		if (!instance) {
+			add(requirement, issue(requirement, "not_installed", `${requirement.connectorId} is not installed.`));
+			continue;
+		}
+		if (!instance.enabled) {
+			add(requirement, issue(requirement, "disabled", `${requirement.connectorId} is disabled.`));
+			continue;
+		}
+		const definition = getConnectorDefinition(requirement.connectorId);
+		if (definition?.runtime.type !== "composio" || definition.runtime.role !== "toolkit") continue;
+		const toolkit = definition.runtime.toolkit;
+		const installation = getConnectorInstallation(`${requirement.connectorId}-${principalId}`);
+		if (installation?.allowedAgentIds.length && !installation.allowedAgentIds.includes(input.agentId)) {
+			add(requirement, issue(requirement, "agent_not_allowed", `${input.agentId} is not allowed to use ${requirement.connectorId}.`));
+			continue;
+		}
+		const allowedScope = installation?.maxScope ?? getComposioToolkitScope(input.config, toolkit);
+		const requiredScope = requirement.scope ?? "read";
+		if (SCOPE_ORDER[allowedScope] < SCOPE_ORDER[requiredScope]) {
+			add(requirement, issue(requirement, "scope_too_narrow", `${requirement.connectorId} requires ${requiredScope} scope but allows ${allowedScope}.`));
+			continue;
+		}
+		if (requirement.connectionRequired === false) continue;
+		const connections = listConnectorConnections({
+			principalId,
+			connectorId: requirement.connectorId
+		});
+		const selected = installation?.selectedConnectionIds.length ? connections.filter((connection) => installation.selectedConnectionIds.includes(connection.id)) : connections;
+		if (selected.some((connection) => connection.status === "active")) continue;
+		const needsAuthorization = selected.some((connection) => connection.status === "expired" || connection.status === "failed");
+		add(requirement, issue(requirement, needsAuthorization ? "reauthorization_required" : "connection_missing", needsAuthorization ? `${requirement.connectorId} needs to be reconnected.` : `${requirement.connectorId} has no active account connection.`));
+	}
+	return {
+		ok: issues.length === 0,
+		issues,
+		optionalIssues
+	};
+}
+//#endregion
+export { preflightWorkflowConnectors };
+
+//# sourceMappingURL=workflow-preflight.js.map

package/dist/src/connectors/workflow-preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-preflight.js","names":[],"sources":["../../../src/connectors/workflow-preflight.ts"],"sourcesContent":["import type { Config } from '../config/schema.js';\nimport { listConnectorConnections, getConnectorInstallation } from '../storage/sqlite/connector-repository.js';\nimport type { WorkflowConnectorRequirement, WorkflowDefinition } from '../workflows/domain/definition.js';\nimport { getComposioToolkitScope } from './composio.js';\nimport { getConnectorDefinition } from './catalog.js';\nimport { listConnectorInstances } from './instances.js';\nimport type { ConnectorScope } from './types.js';\n\nexport type ConnectorPreflightIssueCode =\n  | 'not_installed'\n  | 'disabled'\n  | 'agent_not_allowed'\n  | 'scope_too_narrow'\n  | 'connection_missing'\n  | 'reauthorization_required';\n\nexport type ConnectorPreflightIssue = {\n  connectorId: string;\n  code: ConnectorPreflightIssueCode;\n  message: string;\n  recoveryPath: string;\n};\n\nexport type ConnectorPreflightResult = {\n  ok: boolean;\n  issues: ConnectorPreflightIssue[];\n  optionalIssues: ConnectorPreflightIssue[];\n};\n\nconst SCOPE_ORDER: Record<ConnectorScope, number> = { read: 1, write: 2, admin: 3 };\n\nfunction issue(requirement: WorkflowConnectorRequirement, code: ConnectorPreflightIssueCode, message: string): ConnectorPreflightIssue {\n  return {\n    connectorId: requirement.connectorId,\n    code,\n    message,\n    recoveryPath: `/connectors?connector=${encodeURIComponent(requirement.connectorId)}`,\n  };\n}\n\nexport function preflightWorkflowConnectors(input: {\n  definition: WorkflowDefinition;\n  config: Config;\n  agentId: string;\n  principalId?: string;\n}): ConnectorPreflightResult {\n  const principalId = input.principalId ?? 'local-owner';\n  const instances = listConnectorInstances(input.config);\n  const issues: ConnectorPreflightIssue[] = [];\n  const optionalIssues: ConnectorPreflightIssue[] = [];\n  const add = (requirement: WorkflowConnectorRequirement, value: ConnectorPreflightIssue): void => {\n    (requirement.optional ? optionalIssues : issues).push(value);\n  };\n\n  for (const requirement of input.definition.connectors ?? []) {\n    const instance = instances.find((candidate) => candidate.connectorId === requirement.connectorId);\n    if (!instance) {\n      add(requirement, issue(requirement, 'not_installed', `${requirement.connectorId} is not installed.`));\n      continue;\n    }\n    if (!instance.enabled) {\n      add(requirement, issue(requirement, 'disabled', `${requirement.connectorId} is disabled.`));\n      continue;\n    }\n    const definition = getConnectorDefinition(requirement.connectorId);\n    if (definition?.runtime.type !== 'composio' || definition.runtime.role !== 'toolkit') continue;\n\n    const toolkit = definition.runtime.toolkit;\n    const installation = getConnectorInstallation(`${requirement.connectorId}-${principalId}`);\n    if (installation?.allowedAgentIds.length && !installation.allowedAgentIds.includes(input.agentId)) {\n      add(requirement, issue(requirement, 'agent_not_allowed', `${input.agentId} is not allowed to use ${requirement.connectorId}.`));\n      continue;\n    }\n    const allowedScope = installation?.maxScope ?? getComposioToolkitScope(input.config, toolkit);\n    const requiredScope = requirement.scope ?? 'read';\n    if (SCOPE_ORDER[allowedScope] < SCOPE_ORDER[requiredScope]) {\n      add(requirement, issue(requirement, 'scope_too_narrow', `${requirement.connectorId} requires ${requiredScope} scope but allows ${allowedScope}.`));\n      continue;\n    }\n    if (requirement.connectionRequired === false) continue;\n    const connections = listConnectorConnections({ principalId, connectorId: requirement.connectorId });\n    const selected = installation?.selectedConnectionIds.length\n      ? connections.filter((connection) => installation.selectedConnectionIds.includes(connection.id))\n      : connections;\n    if (selected.some((connection) => connection.status === 'active')) continue;\n    const needsAuthorization = selected.some((connection) => connection.status === 'expired' || connection.status === 'failed');\n    add(requirement, issue(\n      requirement,\n      needsAuthorization ? 'reauthorization_required' : 'connection_missing',\n      needsAuthorization\n        ? `${requirement.connectorId} needs to be reconnected.`\n        : `${requirement.connectorId} has no active account connection.`,\n    ));\n  }\n  return { ok: issues.length === 0, issues, optionalIssues };\n}\n"],"mappings":";;;;;AA6BA,MAAM,cAA8C;CAAE,MAAM;CAAG,OAAO;CAAG,OAAO;CAAG;AAEnF,SAAS,MAAM,aAA2C,MAAmC,SAA0C;AACrI,QAAO;EACL,aAAa,YAAY;EACzB;EACA;EACA,cAAc,yBAAyB,mBAAmB,YAAY,YAAY;EACnF;;AAGH,SAAgB,4BAA4B,OAKf;CAC3B,MAAM,cAAc,MAAM,eAAe;CACzC,MAAM,YAAY,uBAAuB,MAAM,OAAO;CACtD,MAAM,SAAoC,EAAE;CAC5C,MAAM,iBAA4C,EAAE;CACpD,MAAM,OAAO,aAA2C,UAAyC;AAC/F,GAAC,YAAY,WAAW,iBAAiB,QAAQ,KAAK,MAAM;;AAG9D,MAAK,MAAM,eAAe,MAAM,WAAW,cAAc,EAAE,EAAE;EAC3D,MAAM,WAAW,UAAU,MAAM,cAAc,UAAU,gBAAgB,YAAY,YAAY;AACjG,MAAI,CAAC,UAAU;AACb,OAAI,aAAa,MAAM,aAAa,iBAAiB,GAAG,YAAY,YAAY,oBAAoB,CAAC;AACrG;;AAEF,MAAI,CAAC,SAAS,SAAS;AACrB,OAAI,aAAa,MAAM,aAAa,YAAY,GAAG,YAAY,YAAY,eAAe,CAAC;AAC3F;;EAEF,MAAM,aAAa,uBAAuB,YAAY,YAAY;AAClE,MAAI,YAAY,QAAQ,SAAS,cAAc,WAAW,QAAQ,SAAS,UAAW;EAEtF,MAAM,UAAU,WAAW,QAAQ;EACnC,MAAM,eAAe,yBAAyB,GAAG,YAAY,YAAY,GAAG,cAAc;AAC1F,MAAI,cAAc,gBAAgB,UAAU,CAAC,aAAa,gBAAgB,SAAS,MAAM,QAAQ,EAAE;AACjG,OAAI,aAAa,MAAM,aAAa,qBAAqB,GAAG,MAAM,QAAQ,yBAAyB,YAAY,YAAY,GAAG,CAAC;AAC/H;;EAEF,MAAM,eAAe,cAAc,YAAY,wBAAwB,MAAM,QAAQ,QAAQ;EAC7F,MAAM,gBAAgB,YAAY,SAAS;AAC3C,MAAI,YAAY,gBAAgB,YAAY,gBAAgB;AAC1D,OAAI,aAAa,MAAM,aAAa,oBAAoB,GAAG,YAAY,YAAY,YAAY,cAAc,oBAAoB,aAAa,GAAG,CAAC;AAClJ;;AAEF,MAAI,YAAY,uBAAuB,MAAO;EAC9C,MAAM,cAAc,yBAAyB;GAAE;GAAa,aAAa,YAAY;GAAa,CAAC;EACnG,MAAM,WAAW,cAAc,sBAAsB,SACjD,YAAY,QAAQ,eAAe,aAAa,sBAAsB,SAAS,WAAW,GAAG,CAAC,GAC9F;AACJ,MAAI,SAAS,MAAM,eAAe,WAAW,WAAW,SAAS,CAAE;EACnE,MAAM,qBAAqB,SAAS,MAAM,eAAe,WAAW,WAAW,aAAa,WAAW,WAAW,SAAS;AAC3H,MAAI,aAAa,MACf,aACA,qBAAqB,6BAA6B,sBAClD,qBACI,GAAG,YAAY,YAAY,6BAC3B,GAAG,YAAY,YAAY,oCAChC,CAAC;;AAEJ,QAAO;EAAE,IAAI,OAAO,WAAW;EAAG;EAAQ;EAAgB"}

package/dist/src/extensions/install-transaction.d.ts

@@ -0,0 +1,16 @@
+export interface StagedExtensionInstall {
+    extensionId: string;
+    stagingRoot: string;
+    stagedExtensionDir: string;
+    targetDir: string;
+    backupDir?: string;
+    committed: boolean;
+}
+/** Extract, validate, install dependencies, and import-check an extension away from its live path. */
+export declare function stageExtensionStoreZip(buffer: Buffer, extensionsDir: string): Promise<StagedExtensionInstall>;
+/** Move a staged extension into its live path, preserving the previous version for rollback. */
+export declare function commitStagedExtensionInstall(state: StagedExtensionInstall, overwrite: boolean): void;
+/** Restore the previous live extension, or remove a newly committed install. */
+export declare function rollbackStagedExtensionInstall(state: StagedExtensionInstall): void;
+/** Delete the preserved previous version after every durable metadata write succeeds. */
+export declare function finalizeStagedExtensionInstall(state: StagedExtensionInstall): void;

package/dist/src/extensions/install-transaction.js

@@ -0,0 +1,76 @@
+import { installExtensionFromStoreZip } from "./install.js";
+import { join } from "node:path";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+//#region src/extensions/install-transaction.ts
+/** Extract, validate, install dependencies, and import-check an extension away from its live path. */
+async function stageExtensionStoreZip(buffer, extensionsDir) {
+	mkdirSync(extensionsDir, { recursive: true });
+	const stagingRoot = mkdtempSync(join(extensionsDir, ".xopc-install-"));
+	try {
+		const result = await installExtensionFromStoreZip(buffer, stagingRoot);
+		if (!result.ok || !result.extensionId || !result.targetDir) throw new Error(result.error ?? "Extension staging failed");
+		const manifestPath = join(result.targetDir, "xopc.extension.json");
+		const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+		if (!manifest.main) throw new Error("Extension manifest must declare main");
+		const mainUrl = pathToFileURL(join(result.targetDir, manifest.main));
+		mainUrl.searchParams.set("xopcInstallCheck", `${Date.now()}-${Math.random()}`);
+		await import(mainUrl.href);
+		return {
+			extensionId: result.extensionId,
+			stagingRoot,
+			stagedExtensionDir: result.targetDir,
+			targetDir: join(extensionsDir, result.extensionId),
+			committed: false
+		};
+	} catch (err) {
+		rmSync(stagingRoot, {
+			recursive: true,
+			force: true
+		});
+		throw err;
+	}
+}
+/** Move a staged extension into its live path, preserving the previous version for rollback. */
+function commitStagedExtensionInstall(state, overwrite) {
+	if (existsSync(state.targetDir)) {
+		if (!overwrite) throw new Error(`Extension already exists at ${state.targetDir}. Use overwrite to replace it.`);
+		state.backupDir = join(state.stagingRoot, "previous");
+		renameSync(state.targetDir, state.backupDir);
+	}
+	try {
+		renameSync(state.stagedExtensionDir, state.targetDir);
+		state.committed = true;
+	} catch (err) {
+		if (state.backupDir && existsSync(state.backupDir) && !existsSync(state.targetDir)) {
+			renameSync(state.backupDir, state.targetDir);
+			state.backupDir = void 0;
+		}
+		throw err;
+	}
+}
+/** Restore the previous live extension, or remove a newly committed install. */
+function rollbackStagedExtensionInstall(state) {
+	if (state.committed && existsSync(state.targetDir)) rmSync(state.targetDir, {
+		recursive: true,
+		force: true
+	});
+	if (state.backupDir && existsSync(state.backupDir)) renameSync(state.backupDir, state.targetDir);
+	state.committed = false;
+	rmSync(state.stagingRoot, {
+		recursive: true,
+		force: true
+	});
+}
+/** Delete the preserved previous version after every durable metadata write succeeds. */
+function finalizeStagedExtensionInstall(state) {
+	rmSync(state.stagingRoot, {
+		recursive: true,
+		force: true
+	});
+	state.backupDir = void 0;
+}
+//#endregion
+export { commitStagedExtensionInstall, finalizeStagedExtensionInstall, rollbackStagedExtensionInstall, stageExtensionStoreZip };
+
+//# sourceMappingURL=install-transaction.js.map

package/dist/src/extensions/install-transaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-transaction.js","names":[],"sources":["../../../src/extensions/install-transaction.ts"],"sourcesContent":["import {\n  existsSync,\n  mkdirSync,\n  mkdtempSync,\n  readFileSync,\n  renameSync,\n  rmSync,\n} from 'node:fs';\nimport { join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport { installExtensionFromStoreZip } from './install.js';\n\ninterface ExtensionManifestEntry {\n  id?: string;\n  main?: string;\n}\n\nexport interface StagedExtensionInstall {\n  extensionId: string;\n  stagingRoot: string;\n  stagedExtensionDir: string;\n  targetDir: string;\n  backupDir?: string;\n  committed: boolean;\n}\n\n/** Extract, validate, install dependencies, and import-check an extension away from its live path. */\nexport async function stageExtensionStoreZip(\n  buffer: Buffer,\n  extensionsDir: string,\n): Promise<StagedExtensionInstall> {\n  mkdirSync(extensionsDir, { recursive: true });\n  const stagingRoot = mkdtempSync(join(extensionsDir, '.xopc-install-'));\n\n  try {\n    const result = await installExtensionFromStoreZip(buffer, stagingRoot);\n    if (!result.ok || !result.extensionId || !result.targetDir) {\n      throw new Error(result.error ?? 'Extension staging failed');\n    }\n\n    const manifestPath = join(result.targetDir, 'xopc.extension.json');\n    const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as ExtensionManifestEntry;\n    if (!manifest.main) {\n      throw new Error('Extension manifest must declare main');\n    }\n\n    const mainUrl = pathToFileURL(join(result.targetDir, manifest.main));\n    mainUrl.searchParams.set('xopcInstallCheck', `${Date.now()}-${Math.random()}`);\n    await import(mainUrl.href);\n\n    return {\n      extensionId: result.extensionId,\n      stagingRoot,\n      stagedExtensionDir: result.targetDir,\n      targetDir: join(extensionsDir, result.extensionId),\n      committed: false,\n    };\n  } catch (err) {\n    rmSync(stagingRoot, { recursive: true, force: true });\n    throw err;\n  }\n}\n\n/** Move a staged extension into its live path, preserving the previous version for rollback. */\nexport function commitStagedExtensionInstall(\n  state: StagedExtensionInstall,\n  overwrite: boolean,\n): void {\n  if (existsSync(state.targetDir)) {\n    if (!overwrite) {\n      throw new Error(`Extension already exists at ${state.targetDir}. Use overwrite to replace it.`);\n    }\n    state.backupDir = join(state.stagingRoot, 'previous');\n    renameSync(state.targetDir, state.backupDir);\n  }\n\n  try {\n    renameSync(state.stagedExtensionDir, state.targetDir);\n    state.committed = true;\n  } catch (err) {\n    if (state.backupDir && existsSync(state.backupDir) && !existsSync(state.targetDir)) {\n      renameSync(state.backupDir, state.targetDir);\n      state.backupDir = undefined;\n    }\n    throw err;\n  }\n}\n\n/** Restore the previous live extension, or remove a newly committed install. */\nexport function rollbackStagedExtensionInstall(state: StagedExtensionInstall): void {\n  if (state.committed && existsSync(state.targetDir)) {\n    rmSync(state.targetDir, { recursive: true, force: true });\n  }\n  if (state.backupDir && existsSync(state.backupDir)) {\n    renameSync(state.backupDir, state.targetDir);\n  }\n  state.committed = false;\n  rmSync(state.stagingRoot, { recursive: true, force: true });\n}\n\n/** Delete the preserved previous version after every durable metadata write succeeds. */\nexport function finalizeStagedExtensionInstall(state: StagedExtensionInstall): void {\n  rmSync(state.stagingRoot, { recursive: true, force: true });\n  state.backupDir = undefined;\n}\n"],"mappings":";;;;;;AA4BA,eAAsB,uBACpB,QACA,eACiC;AACjC,WAAU,eAAe,EAAE,WAAW,MAAM,CAAC;CAC7C,MAAM,cAAc,YAAY,KAAK,eAAe,iBAAiB,CAAC;AAEtE,KAAI;EACF,MAAM,SAAS,MAAM,6BAA6B,QAAQ,YAAY;AACtE,MAAI,CAAC,OAAO,MAAM,CAAC,OAAO,eAAe,CAAC,OAAO,UAC/C,OAAM,IAAI,MAAM,OAAO,SAAS,2BAA2B;EAG7D,MAAM,eAAe,KAAK,OAAO,WAAW,sBAAsB;EAClE,MAAM,WAAW,KAAK,MAAM,aAAa,cAAc,OAAO,CAAC;AAC/D,MAAI,CAAC,SAAS,KACZ,OAAM,IAAI,MAAM,uCAAuC;EAGzD,MAAM,UAAU,cAAc,KAAK,OAAO,WAAW,SAAS,KAAK,CAAC;AACpE,UAAQ,aAAa,IAAI,oBAAoB,GAAG,KAAK,KAAK,CAAC,GAAG,KAAK,QAAQ,GAAG;AAC9E,QAAM,OAAO,QAAQ;AAErB,SAAO;GACL,aAAa,OAAO;GACpB;GACA,oBAAoB,OAAO;GAC3B,WAAW,KAAK,eAAe,OAAO,YAAY;GAClD,WAAW;GACZ;UACM,KAAK;AACZ,SAAO,aAAa;GAAE,WAAW;GAAM,OAAO;GAAM,CAAC;AACrD,QAAM;;;;AAKV,SAAgB,6BACd,OACA,WACM;AACN,KAAI,WAAW,MAAM,UAAU,EAAE;AAC/B,MAAI,CAAC,UACH,OAAM,IAAI,MAAM,+BAA+B,MAAM,UAAU,gCAAgC;AAEjG,QAAM,YAAY,KAAK,MAAM,aAAa,WAAW;AACrD,aAAW,MAAM,WAAW,MAAM,UAAU;;AAG9C,KAAI;AACF,aAAW,MAAM,oBAAoB,MAAM,UAAU;AACrD,QAAM,YAAY;UACX,KAAK;AACZ,MAAI,MAAM,aAAa,WAAW,MAAM,UAAU,IAAI,CAAC,WAAW,MAAM,UAAU,EAAE;AAClF,cAAW,MAAM,WAAW,MAAM,UAAU;AAC5C,SAAM,YAAY,KAAA;;AAEpB,QAAM;;;;AAKV,SAAgB,+BAA+B,OAAqC;AAClF,KAAI,MAAM,aAAa,WAAW,MAAM,UAAU,CAChD,QAAO,MAAM,WAAW;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC;AAE3D,KAAI,MAAM,aAAa,WAAW,MAAM,UAAU,CAChD,YAAW,MAAM,WAAW,MAAM,UAAU;AAE9C,OAAM,YAAY;AAClB,QAAO,MAAM,aAAa;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC;;;AAI7D,SAAgB,+BAA+B,OAAqC;AAClF,QAAO,MAAM,aAAa;EAAE,WAAW;EAAM,OAAO;EAAM,CAAC;AAC3D,OAAM,YAAY,KAAA"}