@copilotkit/core 1.66.3 → 1.67.0

package/dist/index.umd.js

@@ -1009,7 +1009,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#endregion
 //#region src/core/agent-registry.ts
-/**
+/** Maximum wait for optional Inspector metadata before degrading to absence. */
+	const INSPECTOR_METADATA_REQUEST_TIMEOUT_MS = 5e3;
+	/** Build case-insensitive JSON headers without mutating the Core snapshot. */
+	function withJsonContentType(headers) {
+		const requestHeaders = new Headers(headers);
+		if (!requestHeaders.has("content-type")) requestHeaders.set("content-type", "application/json");
+		return requestHeaders;
+	}
+	/**
 	* Manages agent registration, lifecycle, and runtime connectivity for CopilotKitCore.
 	* Handles both local development agents and remote runtime agents.
 	*/
@@ -1030,6 +1038,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			_defineProperty(this, "_intelligence", void 0);
 			_defineProperty(this, "_threadEndpoints", void 0);
 			_defineProperty(this, "_suggestions", void 0);
+			_defineProperty(this, "_inspectorMetadata", void 0);
+			_defineProperty(this, "_inspectorMetadataSupported", false);
+			_defineProperty(this, "inspectorMetadataRefreshReady", false);
+			_defineProperty(this, "inspectorMetadataConnectionGeneration", 0);
+			_defineProperty(this, "inspectorMetadataGeneration", 0);
+			_defineProperty(this, "inspectorMetadataHeadersGeneration", 0);
+			_defineProperty(this, "inspectorMetadataCredentialsGeneration", 0);
+			_defineProperty(this, "inspectorMetadataAbortController", void 0);
+			_defineProperty(this, "inspectorMetadataNotificationQueue", Promise.resolve());
 			_defineProperty(this, "_a2uiEnabled", false);
 			_defineProperty(this, "_a2uiAgents", void 0);
 			_defineProperty(this, "_openGenerativeUIEnabled", false);
@@ -1070,6 +1087,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		get suggestions() {
 			return this._suggestions;
 		}
+		get inspectorMetadata() {
+			return this._inspectorMetadata;
+		}
 		get a2uiEnabled() {
 			return this._a2uiEnabled;
 		}
@@ -1104,6 +1124,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		setRuntimeUrl(runtimeUrl, options) {
 			const normalizedRuntimeUrl = runtimeUrl ? runtimeUrl.replace(/\/$/, "") : void 0;
 			if (this._runtimeUrl === normalizedRuntimeUrl) return;
+			this.invalidateInspectorMetadataConnection();
 			this._runtimeUrl = normalizedRuntimeUrl;
 			if (options === null || options === void 0 ? void 0 : options.deferConnection) return;
 			this.updateRuntimeConnection();
@@ -1127,6 +1148,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 		setRuntimeTransport(runtimeTransport) {
 			if (this._requestedTransport === runtimeTransport) return;
+			this.invalidateInspectorMetadataConnection();
 			this._requestedTransport = runtimeTransport;
 			this._runtimeTransport = runtimeTransport;
 			this.updateRuntimeConnection();
@@ -1263,6 +1285,143 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				this.applyCredentialsToAgent(agent);
 			});
 		}
+		/** Refresh metadata after the Core header snapshot changes. */
+		handleHeadersChanged() {
+			this.inspectorMetadataHeadersGeneration += 1;
+			this.setInspectorMetadata(void 0);
+			this.refreshInspectorMetadata();
+		}
+		/** Refresh metadata after the Core credentials mode changes. */
+		handleCredentialsChanged() {
+			this.inspectorMetadataCredentialsGeneration += 1;
+			this.setInspectorMetadata(void 0);
+			this.refreshInspectorMetadata();
+		}
+		/**
+		* Fetch trusted inspector metadata independently from runtime discovery.
+		* Optional-route failures degrade to absent metadata and never affect the
+		* runtime connection state.
+		*/
+		async refreshInspectorMetadata() {
+			var _this$inspectorMetada;
+			const generation = ++this.inspectorMetadataGeneration;
+			(_this$inspectorMetada = this.inspectorMetadataAbortController) === null || _this$inspectorMetada === void 0 || _this$inspectorMetada.abort();
+			this.inspectorMetadataAbortController = void 0;
+			if (!this._inspectorMetadataSupported || !this.inspectorMetadataRefreshReady || !this.runtimeUrl || this._runtimeConnectionStatus !== CopilotKitCoreRuntimeConnectionStatus.Connected) {
+				this.setInspectorMetadata(void 0);
+				return;
+			}
+			const runtimeUrl = this.runtimeUrl;
+			const requestedTransport = this._requestedTransport;
+			const resolvedTransport = this._runtimeTransport;
+			const headersGeneration = this.inspectorMetadataHeadersGeneration;
+			const credentialsGeneration = this.inspectorMetadataCredentialsGeneration;
+			const friends = this.core;
+			const headers = { ...friends.headers };
+			const credentials = friends.credentials;
+			const abortController = new AbortController();
+			this.inspectorMetadataAbortController = abortController;
+			let timedOut = false;
+			let timeoutId;
+			let rejectForAbort;
+			const aborted = new Promise((_resolve, reject) => {
+				rejectForAbort = reject;
+			});
+			const handleAbort = () => {
+				rejectForAbort === null || rejectForAbort === void 0 || rejectForAbort(/* @__PURE__ */ new Error("Inspector metadata request aborted"));
+			};
+			abortController.signal.addEventListener("abort", handleAbort, { once: true });
+			const timeout = new Promise((_resolve, reject) => {
+				timeoutId = setTimeout(() => {
+					timedOut = true;
+					reject(/* @__PURE__ */ new Error("Inspector metadata request timed out"));
+					abortController.abort();
+				}, INSPECTOR_METADATA_REQUEST_TIMEOUT_MS);
+			});
+			let nextMetadata;
+			try {
+				const request = (async () => {
+					const response = resolvedTransport === "single" ? await this.fetchInspectorMetadataSingle({
+						runtimeUrl,
+						headers,
+						credentials,
+						signal: abortController.signal
+					}) : await this.fetchInspectorMetadataRest({
+						runtimeUrl,
+						headers,
+						credentials,
+						signal: abortController.signal
+					});
+					if (response.status === 204 || !response.ok) return;
+					return (0, _copilotkit_shared.parseInspectorMetadataV1)(await response.json());
+				})();
+				nextMetadata = await Promise.race([
+					request,
+					aborted,
+					timeout
+				]);
+			} catch (_unused) {
+				nextMetadata = void 0;
+			} finally {
+				if (timeoutId !== void 0) clearTimeout(timeoutId);
+				abortController.signal.removeEventListener("abort", handleAbort);
+			}
+			if (!this.isInspectorMetadataRequestCurrent({
+				generation,
+				runtimeUrl,
+				requestedTransport,
+				resolvedTransport,
+				headersGeneration,
+				credentialsGeneration,
+				signal: abortController.signal,
+				allowAbortedSignal: timedOut
+			})) return;
+			this.inspectorMetadataAbortController = void 0;
+			this.setInspectorMetadata(nextMetadata);
+		}
+		async fetchInspectorMetadataRest({ runtimeUrl, headers, credentials, signal }) {
+			return fetch(`${runtimeUrl}/inspector-metadata`, {
+				method: "GET",
+				headers,
+				...credentials ? { credentials } : {},
+				signal
+			});
+		}
+		async fetchInspectorMetadataSingle({ runtimeUrl, headers, credentials, signal }) {
+			return fetch(runtimeUrl, {
+				method: "POST",
+				headers: withJsonContentType(headers),
+				body: JSON.stringify({ method: "inspector/metadata" }),
+				...credentials ? { credentials } : {},
+				signal
+			});
+		}
+		isInspectorMetadataRequestCurrent({ generation, runtimeUrl, requestedTransport, resolvedTransport, headersGeneration, credentialsGeneration, signal, allowAbortedSignal = false }) {
+			return (allowAbortedSignal || !signal.aborted) && generation === this.inspectorMetadataGeneration && runtimeUrl === this.runtimeUrl && requestedTransport === this._requestedTransport && resolvedTransport === this._runtimeTransport && headersGeneration === this.inspectorMetadataHeadersGeneration && credentialsGeneration === this.inspectorMetadataCredentialsGeneration && this._inspectorMetadataSupported && this.inspectorMetadataRefreshReady && this._runtimeConnectionStatus === CopilotKitCoreRuntimeConnectionStatus.Connected;
+		}
+		invalidateInspectorMetadataConnection() {
+			var _this$inspectorMetada2;
+			this._inspectorMetadataSupported = false;
+			this.inspectorMetadataRefreshReady = false;
+			this.inspectorMetadataConnectionGeneration += 1;
+			this.inspectorMetadataGeneration += 1;
+			(_this$inspectorMetada2 = this.inspectorMetadataAbortController) === null || _this$inspectorMetada2 === void 0 || _this$inspectorMetada2.abort();
+			this.inspectorMetadataAbortController = void 0;
+			this.setInspectorMetadata(void 0);
+		}
+		/**
+		* Publish one state transition without making refreshes wait on subscribers.
+		* Each queued callback closes over its readonly snapshot so reentrant changes
+		* cannot replace the value that an older publication is still delivering.
+		*/
+		setInspectorMetadata(inspectorMetadata) {
+			if (JSON.stringify(this._inspectorMetadata) === JSON.stringify(inspectorMetadata)) return;
+			this._inspectorMetadata = inspectorMetadata;
+			const snapshot = inspectorMetadata;
+			this.inspectorMetadataNotificationQueue = this.inspectorMetadataNotificationQueue.then(() => this.notifyInspectorMetadataChanged(snapshot)).catch((error) => {
+				console.error("Subscriber onInspectorMetadataChanged queue error:", error);
+			});
+		}
 		/**
 		* Update runtime connection and fetch remote agents
 		*/
@@ -1285,6 +1444,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 		async performRuntimeConnection() {
 			if (!this.runtimeUrl) {
+				this.invalidateInspectorMetadataConnection();
 				this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Disconnected;
 				this._runtimeVersion = void 0;
 				this._audioFileTranscriptionEnabled = false;
@@ -1301,11 +1461,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				await this.notifyAgentsChanged();
 				return;
 			}
+			const inspectorMetadataConnectionGeneration = this.inspectorMetadataConnectionGeneration;
 			this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Connecting;
 			await this.notifyRuntimeStatusChanged(CopilotKitCoreRuntimeConnectionStatus.Connecting);
 			try {
 				var _runtimeInfoResponse$2, _runtimeInfoResponse$3, _ref, _a2uiInfo$enabled, _runtimeInfoResponse$4, _runtimeInfoResponse$5;
-				const runtimeInfoResponse = await this.fetchRuntimeInfo();
+				if (inspectorMetadataConnectionGeneration !== this.inspectorMetadataConnectionGeneration) return;
+				const { runtimeInfo: runtimeInfoResponse, resolvedTransport } = await this.fetchRuntimeInfo();
+				if (inspectorMetadataConnectionGeneration !== this.inspectorMetadataConnectionGeneration) return;
+				this._runtimeTransport = resolvedTransport;
 				const { version, ...runtimeInfo } = runtimeInfoResponse;
 				const credentials = this.core.credentials;
 				const rawDebug = this.core.debug;
@@ -1342,6 +1506,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				this._intelligence = runtimeInfoResponse.intelligence;
 				this._threadEndpoints = runtimeInfoResponse.threadEndpoints;
 				this._suggestions = runtimeInfoResponse.suggestions;
+				this._inspectorMetadataSupported = runtimeInfoResponse.inspectorMetadata === true;
+				this.inspectorMetadataRefreshReady = false;
+				if (!this._inspectorMetadataSupported) this.setInspectorMetadata(void 0);
 				const a2uiInfo = runtimeInfoResponse.a2ui;
 				this._a2uiEnabled = (_ref = (_a2uiInfo$enabled = a2uiInfo === null || a2uiInfo === void 0 ? void 0 : a2uiInfo.enabled) !== null && _a2uiInfo$enabled !== void 0 ? _a2uiInfo$enabled : runtimeInfoResponse.a2uiEnabled) !== null && _ref !== void 0 ? _ref : false;
 				this._a2uiAgents = (a2uiInfo === null || a2uiInfo === void 0 ? void 0 : a2uiInfo.enabled) ? a2uiInfo.agents : void 0;
@@ -1350,7 +1517,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				this._telemetryDisabled = (_runtimeInfoResponse$5 = runtimeInfoResponse.telemetryDisabled) !== null && _runtimeInfoResponse$5 !== void 0 ? _runtimeInfoResponse$5 : false;
 				await this.notifyRuntimeStatusChanged(CopilotKitCoreRuntimeConnectionStatus.Connected);
 				await this.notifyAgentsChanged();
+				if (inspectorMetadataConnectionGeneration !== this.inspectorMetadataConnectionGeneration || this._runtimeConnectionStatus !== CopilotKitCoreRuntimeConnectionStatus.Connected) return;
+				this.inspectorMetadataRefreshReady = true;
+				if (this._inspectorMetadataSupported) this.refreshInspectorMetadata();
 			} catch (error) {
+				if (inspectorMetadataConnectionGeneration !== this.inspectorMetadataConnectionGeneration) return;
+				this.invalidateInspectorMetadataConnection();
 				this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Error;
 				this._runtimeVersion = void 0;
 				this._audioFileTranscriptionEnabled = false;
@@ -1376,24 +1548,31 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			}
 		}
 		async fetchRuntimeInfo() {
-			if (!this.runtimeUrl) throw new Error("Runtime URL is not set");
+			const runtimeUrl = this.runtimeUrl;
+			if (!runtimeUrl) throw new Error("Runtime URL is not set");
 			const baseHeaders = this.core.headers;
 			const credentials = this.core.credentials;
 			const headers = { ...baseHeaders };
-			if (this._runtimeTransport === "single") return this.fetchRuntimeInfoSingle(headers, credentials);
-			if (this._runtimeTransport === "auto") return this.fetchRuntimeInfoAutoDetect(headers, credentials);
-			const response = await fetch(`${this.runtimeUrl}/info`, {
+			const runtimeTransport = this._runtimeTransport;
+			if (runtimeTransport === "single") return {
+				runtimeInfo: await this.fetchRuntimeInfoSingle(runtimeUrl, headers, credentials),
+				resolvedTransport: "single"
+			};
+			if (runtimeTransport === "auto") return this.fetchRuntimeInfoAutoDetect(runtimeUrl, headers, credentials);
+			const response = await fetch(`${runtimeUrl}/info`, {
 				headers,
 				...credentials ? { credentials } : {}
 			});
 			if (!response.ok) throw new Error(`Runtime info request failed with status ${response.status}`);
-			return await response.json();
+			return {
+				runtimeInfo: await response.json(),
+				resolvedTransport: "rest"
+			};
 		}
-		async fetchRuntimeInfoSingle(headers, credentials) {
-			if (!headers["Content-Type"]) headers["Content-Type"] = "application/json";
-			const response = await fetch(this.runtimeUrl, {
+		async fetchRuntimeInfoSingle(runtimeUrl, headers, credentials) {
+			const response = await fetch(runtimeUrl, {
 				method: "POST",
-				headers,
+				headers: withJsonContentType(headers),
 				body: JSON.stringify({ method: "info" }),
 				...credentials ? { credentials } : {}
 			});
@@ -1402,22 +1581,24 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 		/**
 		* Auto-detect transport by trying REST first, then falling back to single-endpoint.
-		* Updates `_runtimeTransport` to the detected value so subsequent requests use it directly.
+		* The caller commits the detected transport only after confirming this
+		* connection attempt is still current.
 		*/
-		async fetchRuntimeInfoAutoDetect(headers, credentials) {
+		async fetchRuntimeInfoAutoDetect(runtimeUrl, headers, credentials) {
 			try {
-				const response = await fetch(`${this.runtimeUrl}/info`, {
+				const response = await fetch(`${runtimeUrl}/info`, {
 					headers: { ...headers },
 					...credentials ? { credentials } : {}
 				});
-				if (response.status >= 200 && response.status < 300) {
-					this._runtimeTransport = "rest";
-					return await response.json();
-				}
-			} catch (_unused) {}
-			const result = await this.fetchRuntimeInfoSingle({ ...headers }, credentials);
-			this._runtimeTransport = "single";
-			return result;
+				if (response.status >= 200 && response.status < 300) return {
+					runtimeInfo: await response.json(),
+					resolvedTransport: "rest"
+				};
+			} catch (_unused2) {}
+			return {
+				runtimeInfo: await this.fetchRuntimeInfoSingle(runtimeUrl, { ...headers }, credentials),
+				resolvedTransport: "single"
+			};
 		}
 		/**
 		* Assign agent IDs to a record of agents
@@ -1459,6 +1640,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				});
 			}, "Subscriber onAgentsChanged error:");
 		}
+		async notifyInspectorMetadataChanged(inspectorMetadata) {
+			await this.core.notifySubscribers((subscriber) => {
+				var _subscriber$onInspect;
+				return (_subscriber$onInspect = subscriber.onInspectorMetadataChanged) === null || _subscriber$onInspect === void 0 ? void 0 : _subscriber$onInspect.call(subscriber, {
+					copilotkit: this.core,
+					inspectorMetadata
+				});
+			}, "Subscriber onInspectorMetadataChanged error:");
+		}
 	};
 
 //#endregion
@@ -4302,6 +4492,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		get suggestions() {
 			return this.agentRegistry.suggestions;
 		}
+		/** Trusted, optional metadata advertised by the connected runtime. */
+		get inspectorMetadata() {
+			return this.agentRegistry.inspectorMetadata;
+		}
+		/** Refresh trusted inspector metadata without reconnecting runtime agents. */
+		async refreshInspectorMetadata() {
+			await this.agentRegistry.refreshInspectorMetadata();
+		}
 		get a2uiEnabled() {
 			return this.agentRegistry.a2uiEnabled;
 		}
@@ -4357,6 +4555,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			this._headers = normalizeHeaders(headers);
 			if (this._memoryStore) this.syncMemoryContext();
 			this.agentRegistry.applyHeadersToAgents(this.agentRegistry.agents);
+			this.agentRegistry.handleHeadersChanged();
 			this.notifySubscribers((subscriber) => {
 				var _subscriber$onHeaders;
 				return (_subscriber$onHeaders = subscriber.onHeadersChanged) === null || _subscriber$onHeaders === void 0 ? void 0 : _subscriber$onHeaders.call(subscriber, {
@@ -4368,6 +4567,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		setCredentials(credentials) {
 			this._credentials = credentials;
 			this.agentRegistry.applyCredentialsToAgents(this.agentRegistry.agents);
+			this.agentRegistry.handleCredentialsChanged();
 		}
 		setProperties(properties) {
 			this._properties = properties;