@copilotkit/core 1.66.4 → 1.67.0

package/README.md

@@ -0,0 +1,61 @@
+# @copilotkit/core
+
+`@copilotkit/core` is the framework-neutral client for CopilotKit runtimes. It
+manages runtime agents, frontend tools, shared context, suggestions, thread
+stores, and subscriptions.
+
+## Trusted Inspector metadata
+
+When the connected runtime reports `inspectorMetadata: true` in its runtime-info
+response, Core loads the optional `InspectorMetadataV1` value in the background.
+The runtime connection and agent notifications finish first, so a slow or
+unavailable metadata route cannot delay the app.
+
+Core exposes the object returned by Shared normalization unchanged through the
+getter and subscriber event. Older runtimes may omit
+`usage.expiringSoonCount`; that absence remains valid V1 usage. A value of `0`
+means known zero and stays different from absence. Shared omits a malformed
+expiry leaf without removing valid `used`, `limit`, or sibling modules. Core
+does not calculate or rebuild expiry and does not require a V2 schema.
+
+Read the latest value with `inspectorMetadata`, refresh it without reconnecting,
+or subscribe to changes:
+
+```ts
+import { CopilotKitCore } from "@copilotkit/core";
+
+const copilotkit = new CopilotKitCore({
+  runtimeUrl: "/api/copilotkit",
+  headers: { Authorization: "Bearer app-session" },
+  credentials: "include",
+});
+
+const subscription = copilotkit.subscribe({
+  onInspectorMetadataChanged: ({ inspectorMetadata }) => {
+    console.log(inspectorMetadata);
+  },
+});
+
+await copilotkit.refreshInspectorMetadata();
+console.log(copilotkit.inspectorMetadata);
+
+subscription.unsubscribe();
+```
+
+Core sends the current headers and fetch credentials to the Copilot Runtime. A
+call to `setHeaders()` or `setCredentials()` clears the prior value before it
+starts a new metadata refresh, so trusted context cannot cross an auth-context
+change. Changing the runtime URL or transport, losing the capability, or
+disconnecting also clears the value.
+
+Each refresh cancels the prior request and has a five-second deadline. Core also
+checks the runtime URL, requested and resolved transport, headers, credentials,
+connection, and capability before publishing a response. A stale success or
+failure cannot replace metadata from a newer connection. Route, timeout, parse,
+and subscriber failures stay isolated from the runtime connection.
+
+See the
+[`CopilotKitCore` reference](https://docs.copilotkit.ai/reference/core/classes/CopilotKitCore)
+and
+[`CopilotKitCoreSubscriber` reference](https://docs.copilotkit.ai/reference/core/types/CopilotKitCoreSubscriber)
+for the full API.

package/dist/index.cjs

@@ -895,6 +895,14 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 
 //#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.
@@ -914,6 +922,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;
@@ -966,6 +983,9 @@ var AgentRegistry = class {
 	get suggestions() {
 		return this._suggestions;
 	}
+	get inspectorMetadata() {
+		return this._inspectorMetadata;
+	}
 	get a2uiEnabled() {
 		return this._a2uiEnabled;
 	}
@@ -1000,6 +1020,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();
@@ -1023,6 +1044,7 @@ var AgentRegistry = class {
 	}
 	setRuntimeTransport(runtimeTransport) {
 		if (this._requestedTransport === runtimeTransport) return;
+		this.invalidateInspectorMetadataConnection();
 		this._requestedTransport = runtimeTransport;
 		this._runtimeTransport = runtimeTransport;
 		this.updateRuntimeConnection();
@@ -1159,6 +1181,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 (0, _copilotkit_shared.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
 	*/
@@ -1179,6 +1336,7 @@ var AgentRegistry = class {
 	}
 	async performRuntimeConnection() {
 		if (!this.runtimeUrl) {
+			this.invalidateInspectorMetadataConnection();
 			this._runtimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus.Disconnected;
 			this._runtimeVersion = void 0;
 			this._audioFileTranscriptionEnabled = false;
@@ -1195,10 +1353,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;
@@ -1234,6 +1396,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;
@@ -1242,7 +1407,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;
@@ -1268,24 +1438,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 } : {}
 		});
@@ -1294,22 +1471,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
@@ -1345,6 +1524,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
@@ -4160,6 +4345,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;
 	}
@@ -4215,6 +4408,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
@@ -4223,6 +4417,7 @@ var CopilotKitCore = class {
 	setCredentials(credentials) {
 		this._credentials = credentials;
 		this.agentRegistry.applyCredentialsToAgents(this.agentRegistry.agents);
+		this.agentRegistry.handleCredentialsChanged();
 	}
 	setProperties(properties) {
 		this._properties = properties;