@copilotkit/core 1.66.4 → 1.67.1

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { Throttler } from "@tanstack/pacer";
 import { AbstractAgent, EventType, HttpAgent, buildResumeArray, isInterruptExpired, randomUUID, runHttpRequest, structuredClone_, transformChunks, transformHttpEventStream } from "@ag-ui/client";
-import { RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, logger, partialJSONParse, phoenixExponentialBackoff, randomUUID as randomUUID$1, resolveDebugConfig, schemaToJsonSchema } from "@copilotkit/shared";
+import { RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, logger, parseInspectorMetadataV1, partialJSONParse, phoenixExponentialBackoff, randomUUID as randomUUID$1, resolveDebugConfig, schemaToJsonSchema } from "@copilotkit/shared";
 import { BehaviorSubject, EMPTY, NEVER, Notification, Observable, Subject, Subscription, asapScheduler, combineLatest, concat, defer, dematerialize, firstValueFrom, from, lastValueFrom, merge, observeOn, of, switchMap, throwError } from "rxjs";
 import { catchError, concatWith, delay, distinctUntilChanged, endWith, filter, finalize, ignoreElements, map, mergeMap, observeOn as observeOn$1, scan, share, shareReplay, switchMap as switchMap$1, take, takeUntil, tap, timeout, withLatestFrom } from "rxjs/operators";
 import { Socket } from "phoenix";
@@ -894,6 +894,14 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 
 //#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.
@@ -913,6 +921,15 @@ var AgentRegistry = class {
 	_intelligence;
 	_threadEndpoints;
 	_suggestions;
+	_inspectorMetadata;
+	_inspectorMetadataSupported = false;
+	inspectorMetadataRefreshReady = false;
+	inspectorMetadataConnectionGeneration = 0;
+	inspectorMetadataGeneration = 0;
+	inspectorMetadataHeadersGeneration = 0;
+	inspectorMetadataCredentialsGeneration = 0;
+	inspectorMetadataAbortController;
+	inspectorMetadataNotificationQueue = Promise.resolve();
 	_a2uiEnabled = false;
 	_a2uiAgents;
 	_openGenerativeUIEnabled = false;
@@ -965,6 +982,9 @@ var AgentRegistry = class {
 	get suggestions() {
 		return this._suggestions;
 	}
+	get inspectorMetadata() {
+		return this._inspectorMetadata;
+	}
 	get a2uiEnabled() {
 		return this._a2uiEnabled;
 	}
@@ -999,6 +1019,7 @@ var AgentRegistry = class {
 	setRuntimeUrl(runtimeUrl, options) {
 		const normalizedRuntimeUrl = runtimeUrl ? runtimeUrl.replace(/\/$/, "") : void 0;
 		if (this._runtimeUrl === normalizedRuntimeUrl) return;
+		this.invalidateInspectorMetadataConnection();
 		this._runtimeUrl = normalizedRuntimeUrl;
 		if (options?.deferConnection) return;
 		this.updateRuntimeConnection();
@@ -1022,6 +1043,7 @@ var AgentRegistry = class {
 	}
 	setRuntimeTransport(runtimeTransport) {
 		if (this._requestedTransport === runtimeTransport) return;
+		this.invalidateInspectorMetadataConnection();
 		this._requestedTransport = runtimeTransport;
 		this._runtimeTransport = runtimeTransport;
 		this.updateRuntimeConnection();
@@ -1158,6 +1180,141 @@ var AgentRegistry = class {
 			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() {
+		const generation = ++this.inspectorMetadataGeneration;
+		this.inspectorMetadataAbortController?.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?.(/* @__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 parseInspectorMetadataV1(await response.json());
+			})();
+			nextMetadata = await Promise.race([
+				request,
+				aborted,
+				timeout
+			]);
+		} catch {
+			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() {
+		this._inspectorMetadataSupported = false;
+		this.inspectorMetadataRefreshReady = false;
+		this.inspectorMetadataConnectionGeneration += 1;
+		this.inspectorMetadataGeneration += 1;
+		this.inspectorMetadataAbortController?.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
 	*/
@@ -1178,6 +1335,7 @@ var AgentRegistry = class {
 	}
 	async performRuntimeConnection() {
 		if (!this.runtimeUrl) {
+			this.invalidateInspectorMetadataConnection();
 			this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Disconnected;
 			this._runtimeVersion = void 0;
 			this._audioFileTranscriptionEnabled = false;
@@ -1194,10 +1352,14 @@ var AgentRegistry = class {
 			await this.notifyAgentsChanged();
 			return;
 		}
+		const inspectorMetadataConnectionGeneration = this.inspectorMetadataConnectionGeneration;
 		this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Connecting;
 		await this.notifyRuntimeStatusChanged(CopilotKitCoreRuntimeConnectionStatus.Connecting);
 		try {
-			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;
@@ -1233,6 +1395,9 @@ var AgentRegistry = class {
 			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 = a2uiInfo?.enabled ?? runtimeInfoResponse.a2uiEnabled ?? false;
 			this._a2uiAgents = a2uiInfo?.enabled ? a2uiInfo.agents : void 0;
@@ -1241,7 +1406,12 @@ var AgentRegistry = class {
 			this._telemetryDisabled = runtimeInfoResponse.telemetryDisabled ?? 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;
@@ -1267,24 +1437,31 @@ var AgentRegistry = class {
 		}
 	}
 	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 } : {}
 		});
@@ -1293,22 +1470,24 @@ var AgentRegistry = class {
 	}
 	/**
 	* 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();
-			}
+			if (response.status >= 200 && response.status < 300) return {
+				runtimeInfo: await response.json(),
+				resolvedTransport: "rest"
+			};
 		} catch {}
-		const result = await this.fetchRuntimeInfoSingle({ ...headers }, credentials);
-		this._runtimeTransport = "single";
-		return result;
+		return {
+			runtimeInfo: await this.fetchRuntimeInfoSingle(runtimeUrl, { ...headers }, credentials),
+			resolvedTransport: "single"
+		};
 	}
 	/**
 	* Assign agent IDs to a record of agents
@@ -1344,6 +1523,12 @@ var AgentRegistry = class {
 			agents: this._agents
 		}), "Subscriber onAgentsChanged error:");
 	}
+	async notifyInspectorMetadataChanged(inspectorMetadata) {
+		await this.core.notifySubscribers((subscriber) => subscriber.onInspectorMetadataChanged?.({
+			copilotkit: this.core,
+			inspectorMetadata
+		}), "Subscriber onInspectorMetadataChanged error:");
+	}
 };
 
 //#endregion
@@ -4159,6 +4344,14 @@ var CopilotKitCore = class {
 	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;
 	}
@@ -4214,6 +4407,7 @@ var CopilotKitCore = class {
 		this._headers = normalizeHeaders(headers);
 		if (this._memoryStore) this.syncMemoryContext();
 		this.agentRegistry.applyHeadersToAgents(this.agentRegistry.agents);
+		this.agentRegistry.handleHeadersChanged();
 		this.notifySubscribers((subscriber) => subscriber.onHeadersChanged?.({
 			copilotkit: this,
 			headers: this.headers
@@ -4222,6 +4416,7 @@ var CopilotKitCore = class {
 	setCredentials(credentials) {
 		this._credentials = credentials;
 		this.agentRegistry.applyCredentialsToAgents(this.agentRegistry.agents);
+		this.agentRegistry.handleCredentialsChanged();
 	}
 	setProperties(properties) {
 		this._properties = properties;