@copilotkit/core 1.78.0 → 1.79.1-canary.1792034358

package/dist/index.umd.js

@@ -23,7 +23,17 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#endregion
 //#region src/utils/connect-replay.ts
-/**
+	const connectRunErrorPhases = /* @__PURE__ */ new WeakMap();
+	/**
+	* The phase in which a connection received `event`, as recorded when it
+	* arrived. Events that did not come through a connection with replay
+	* boundaries report `unknown`.
+	*/
+	function ɵgetConnectRunErrorPhase(event) {
+		var _connectRunErrorPhase;
+		return (_connectRunErrorPhase = connectRunErrorPhases.get(event)) !== null && _connectRunErrorPhase !== void 0 ? _connectRunErrorPhase : "unknown";
+	}
+	/**
 	* Runs an agent's `connect()` stream through the AbstractAgent apply pipeline
 	* with the `verifyEvents` step omitted.
 	*
@@ -78,6 +88,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			let result;
 			const previousMessageIds = new Set(agent.messages.map((m) => m.id));
 			let isReplaying = true;
+			let reportsReplayPhase = false;
 			const liveErrors = /* @__PURE__ */ new WeakSet();
 			const subscribers = [
 				{
@@ -125,15 +136,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			};
 			const lifecycle = {
 				onReplayStarted: () => {
+					reportsReplayPhase = true;
 					isReplaying = true;
 					agent.isRunning = true;
 				},
 				onReplayFinished: () => {
+					reportsReplayPhase = true;
 					isReplaying = false;
 				}
 			};
 			const source$ = (0, rxjs.defer)(() => new _ag_ui_client.CompatibilityBoundary().run(input, { run: () => connect ? connect(input, lifecycle) : self.connect(input) })).pipe((0, rxjs_operators.tap)((event) => {
-				if (!isReplaying && event.type === _ag_ui_client.EventType.RUN_ERROR) liveErrors.add(event);
+				if (event.type !== _ag_ui_client.EventType.RUN_ERROR) return;
+				if (!isReplaying) liveErrors.add(event);
+				if (reportsReplayPhase) connectRunErrorPhases.set(event, isReplaying ? "replay" : "live");
 			}), (0, _ag_ui_client.transformChunks)(self.debugLogger), (0, rxjs_operators.takeUntil)(activeRunDetach$));
 			const applied$ = self.apply(input, source$, subscribers);
 			await (0, rxjs.lastValueFrom)(self.processApplyEvents(input, applied$, subscribers).pipe((0, rxjs_operators.catchError)((error) => {
@@ -342,6 +357,20 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 	};
 	/**
+	* The gateway could not replay a live run's events, so the client cannot
+	* verify the run it is following. The run itself may still be going on the
+	* server; reconnecting to the thread shows its real state.
+	*/
+	var IntelligenceReplayFailedError = class extends Error {
+		constructor(threadId, runId) {
+			super("The run's events could not be replayed. Reconnect to the thread to check the run's status.");
+			this.threadId = threadId;
+			this.runId = runId;
+			_defineProperty(this, "code", "INTELLIGENCE_REPLAY_FAILED");
+			this.name = "IntelligenceReplayFailedError";
+		}
+	};
+	/**
 	* Type guard for {@link RunCompletionAware}. Returns true when `agent` exposes
 	* an `activeRunCompletionPromise` property, so callers can await an in-flight
 	* run without an `as unknown as` cast. Returns false for agents that don't
@@ -672,6 +701,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				};
 				const replayFailed$ = channel$.pipe((0, rxjs_operators.switchMap)(({ channel }) => this.observeChannelEvent$(channel, REPLAY_FAILED_EVENT)), (0, rxjs_operators.tap)(() => {
 					controlCursor.replayFailed = true;
+					if (options.streamMode === "run") throw new IntelligenceReplayFailedError(credentials.threadId, credentials.runId);
 				}));
 				const replayComplete$ = this.observeControlEvent$(input.threadId, channel$, REPLAY_COMPLETE_EVENT, controlCursor).pipe((0, rxjs_operators.tap)(() => {
 					var _options$lifecycle2, _options$lifecycle2$o;
@@ -1158,7 +1188,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					...this.headers,
 					"Content-Type": "application/json"
 				});
-				fetch(this.singleEndpointUrl, {
+				this.fetch(this.singleEndpointUrl, {
 					method: "POST",
 					headers,
 					body: JSON.stringify({
@@ -1169,7 +1199,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 						},
 						...runId === void 0 ? {} : { body: { runId } }
 					}),
-					...this.credentials ? { credentials: this.credentials } : {}
+					...this.credentials ? { credentials: this.credentials } : {},
+					ɵruntimeRequest: { nonCritical: true }
 				}).catch((error) => {
 					console.error("ProxiedCopilotRuntimeAgent: stop request failed", error);
 				});
@@ -1180,14 +1211,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			const origin = typeof window !== "undefined" && window.location ? window.location.origin : "http://localhost";
 			const base = new URL(this.runtimeUrl, origin);
 			const stopUrl = new URL(stopPath, base);
-			fetch(stopUrl.toString(), {
+			this.fetch(stopUrl.toString(), {
 				method: "POST",
 				headers: {
 					"Content-Type": "application/json",
 					...this.headers
 				},
 				...runId === void 0 ? {} : { body: JSON.stringify({ runId }) },
-				...this.credentials ? { credentials: this.credentials } : {}
+				...this.credentials ? { credentials: this.credentials } : {},
+				ɵruntimeRequest: { nonCritical: true }
 			}).catch((error) => {
 				console.error("ProxiedCopilotRuntimeAgent: stop request failed", error);
 			});
@@ -1663,6 +1695,185 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		};
 	}
 
+//#endregion
+//#region src/core/header-source.ts
+	var CopilotKitHeaderResolutionError = class extends Error {
+		constructor(cause) {
+			super("[CopilotKit] Failed to resolve request headers", { cause });
+			_defineProperty(this, "name", "CopilotKitHeaderResolutionError");
+		}
+	};
+	function isHeaderResolutionError(error) {
+		let current = error;
+		for (let depth = 0; depth < 5 && current; depth++) {
+			if (current instanceof CopilotKitHeaderResolutionError) return true;
+			current = current.cause;
+		}
+		return false;
+	}
+	function isPromiseLike(value) {
+		return typeof value === "object" && value !== null && typeof value.then === "function";
+	}
+	/**
+	* Normalize a header map to a `Record<string, string>` with no `null` or
+	* `undefined` values. Dropping an entry is how a header is cleared.
+	*/
+	function normalizeHeaders(headers) {
+		return Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] != null));
+	}
+	/** Same keys, same values (order-independent). */
+	function shallowEqualRecord(a, b) {
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys.length !== bKeys.length) return false;
+		return aKeys.every((key) => a[key] === b[key]);
+	}
+	function isHeaderRecordInput(value) {
+		return typeof value === "object" && value !== null && !Array.isArray(value);
+	}
+	/**
+	* Owns the headers source for one core. Resolution is synchronous for a
+	* record or a sync builder, so those callers never pay an extra await.
+	*/
+	var HeaderSourceResolver = class {
+		constructor(onFailure) {
+			this.onFailure = onFailure;
+			_defineProperty(this, "source", {});
+			_defineProperty(this, "sourceGeneration", 0);
+			_defineProperty(this, "snapshot", {});
+			_defineProperty(this, "inFlight", void 0);
+		}
+		/** The last resolved headers. Not necessarily current for a builder. */
+		get headers() {
+			return this.snapshot;
+		}
+		/** Bumped on every accepted `setSource`, never by a new token. */
+		get generation() {
+			return this.sourceGeneration;
+		}
+		/**
+		* Returns false when a builder with the same identity is set again, or
+		* when a record replaces another record with equal normalized values (a
+		* caller re-passing an equivalent literal on every re-render must not
+		* bump the generation). A record replacing a builder, a builder replacing
+		* a record, and a new builder function all still count as a change.
+		*/
+		setSource(source) {
+			if (typeof source === "function" && source === this.source) return false;
+			const nextSnapshot = typeof source === "function" ? {} : normalizeHeaders(source);
+			if (typeof source !== "function" && typeof this.source !== "function" && shallowEqualRecord(nextSnapshot, this.snapshot)) return false;
+			this.source = source;
+			this.sourceGeneration += 1;
+			this.inFlight = void 0;
+			this.snapshot = nextSnapshot;
+			return true;
+		}
+		resolve() {
+			var _this$inFlight;
+			const source = this.source;
+			if (typeof source !== "function") return this.snapshot;
+			const generation = this.sourceGeneration;
+			if (((_this$inFlight = this.inFlight) === null || _this$inFlight === void 0 ? void 0 : _this$inFlight.generation) === generation) return this.inFlight.promise;
+			let value;
+			try {
+				value = source();
+			} catch (error) {
+				throw this.fail(error);
+			}
+			if (!isPromiseLike(value)) return this.accept(value, generation);
+			const promise = Promise.resolve(value).then((resolved) => this.accept(resolved, generation), (error) => {
+				throw this.fail(error);
+			}).finally(() => {
+				var _this$inFlight2;
+				if (((_this$inFlight2 = this.inFlight) === null || _this$inFlight2 === void 0 ? void 0 : _this$inFlight2.promise) === promise) this.inFlight = void 0;
+			});
+			this.inFlight = {
+				generation,
+				promise
+			};
+			return promise;
+		}
+		accept(value, generation) {
+			if (!isHeaderRecordInput(value)) throw this.fail(/* @__PURE__ */ new TypeError("headers builder must return an object of header values"));
+			const normalized = normalizeHeaders(value);
+			if (generation === this.sourceGeneration) {
+				if (!shallowEqualRecord(normalized, this.snapshot)) this.snapshot = normalized;
+				return this.snapshot;
+			}
+			return normalized;
+		}
+		fail(cause) {
+			if (cause instanceof CopilotKitHeaderResolutionError) return cause;
+			const error = new CopilotKitHeaderResolutionError(cause);
+			this.onFailure(error);
+			return error;
+		}
+	};
+	const PROTOCOL_HEADERS = new Set(["content-type", "accept"]);
+	/**
+	* Put fresh core headers on top of a request's headers, keeping the input's
+	* shape. Core beats an agent's own headers (#5635). A site's Content-Type and
+	* Accept are never overridden, matching every site's existing spread order.
+	*/
+	function ɵoverlayCoreHeaders(existing, core) {
+		if (existing instanceof Headers) {
+			const headers = new Headers(existing);
+			for (const [key, value] of Object.entries(core)) {
+				if (PROTOCOL_HEADERS.has(key.toLowerCase()) && headers.has(key)) continue;
+				headers.set(key, value);
+			}
+			return headers;
+		}
+		const base = Array.isArray(existing) ? Object.fromEntries(existing) : { ...existing };
+		const keyByLower = new Map(Object.keys(base).map((k) => [k.toLowerCase(), k]));
+		for (const [key, value] of Object.entries(core)) {
+			const existingKey = keyByLower.get(key.toLowerCase());
+			if (existingKey !== void 0) {
+				if (PROTOCOL_HEADERS.has(key.toLowerCase())) continue;
+				delete base[existingKey];
+			}
+			base[key] = value;
+		}
+		return base;
+	}
+	/** Reject with the signal's AbortError if it aborts before `value` settles. */
+	async function abortable(value, signal) {
+		if (!signal || !isPromiseLike(value)) return value;
+		if (signal.aborted) throw abortError(signal);
+		return new Promise((resolve, reject) => {
+			const onAbort = () => reject(abortError(signal));
+			signal.addEventListener("abort", onAbort, { once: true });
+			Promise.resolve(value).then((v) => {
+				signal.removeEventListener("abort", onAbort);
+				resolve(v);
+			}, (e) => {
+				signal.removeEventListener("abort", onAbort);
+				reject(e);
+			});
+		});
+	}
+	function abortError(signal) {
+		return signal.reason instanceof Error ? signal.reason : new DOMException("The operation was aborted.", "AbortError");
+	}
+	/**
+	* Add default headers (e.g. the public API key) to a source, only where the
+	* source left the key unset or empty. The single shared replacement for the
+	* React, Vue and Angular providers' own merges.
+	*/
+	function ɵwithHeaderDefaults(source, defaults) {
+		if (Object.keys(defaults).length === 0) return source;
+		const fill = (headers) => {
+			const out = { ...headers };
+			for (const [key, value] of Object.entries(defaults)) if (!out[key]) out[key] = value;
+			return out;
+		};
+		if (typeof source !== "function") return fill(source);
+		return (() => {
+			const value = source();
+			return isPromiseLike(value) ? Promise.resolve(value).then((resolved) => isHeaderRecordInput(resolved) ? fill(resolved) : resolved) : isHeaderRecordInput(value) ? fill(value) : value;
+		});
+	}
+
 //#endregion
 //#region src/core/agent-registry.ts
 /** Maximum wait for optional Inspector metadata before degrading to absence. */
@@ -1988,29 +2199,85 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			console.warn(`Agent ${id} not found`);
 		}
 		/**
-		* Apply current core headers to an agent, merged ON TOP of the agent's own
-		* construction-time headers (the per-agent baseline in `agentOwnHeaders`).
-		* Core wins on a key conflict. Non-`HttpAgent` agents are left untouched
-		* because only `HttpAgent` carries a `headers` field. See #5635.
+		* Shared core-and-own-header merge for a single agent. Captures the
+		* agent's construction-time headers once (the per-agent baseline in
+		* `agentOwnHeaders`), then either keeps only that baseline — a
+		* `ProxiedCopilotRuntimeAgent`, whose core headers are added by
+		* `ɵruntimeFetch` when each request is actually sent instead, so a key the
+		* builder stops returning can never ride along from a stale copy baked
+		* onto the agent (see #1937) — or merges `coreHeaders` on top of it (any
+		* other `HttpAgent`; core wins on a key conflict, see #5635).
 		*/
-		applyHeadersToAgent(agent) {
-			if (ɵisHttpAgent(agent)) {
-				if (!this.agentOwnHeaders.has(agent)) this.agentOwnHeaders.set(agent, { ...agent.headers });
-				agent.headers = {
-					...this.agentOwnHeaders.get(agent),
-					...this.core.headers
-				};
+		applyHeaderRecordToAgent(agent, coreHeaders) {
+			if (!this.agentOwnHeaders.has(agent)) this.agentOwnHeaders.set(agent, { ...agent.headers });
+			const own = this.agentOwnHeaders.get(agent);
+			if (agent instanceof ProxiedCopilotRuntimeAgent) {
+				agent.headers = { ...own };
+				this.applyRuntimeFetchToAgent(agent);
+				return;
 			}
+			agent.headers = {
+				...own,
+				...coreHeaders
+			};
+		}
+		/**
+		* Apply the last resolved header snapshot to an agent, merged ON TOP of
+		* the agent's own construction-time headers. Non-`HttpAgent` agents are
+		* left untouched because only `HttpAgent` carries a `headers` field. See
+		* #5635.
+		*
+		* Never invokes the headers builder — safe to call from anywhere (dev-only
+		* registration helpers, a React effect that re-runs on every render)
+		* without risking a synchronous throw or an unhandled async rejection from
+		* a user-supplied builder. Use `prepareAgentHeadersForRun` (friends-only)
+		* on the run/connect path, where a builder failure can be awaited and
+		* reported once.
+		*/
+		applyHeadersToAgent(agent) {
+			if (!ɵisHttpAgent(agent)) return;
+			const friends = this.core;
+			this.applyHeaderRecordToAgent(agent, friends.headers);
 		}
 		/**
-		* Apply current headers to all agents
+		* Apply the last resolved header snapshot to every agent, without
+		* triggering a builder call per agent. Used by `initialize` and
+		* `setHeaders`; a run re-applies with fresh headers anyway (see
+		* `prepareAgentHeadersForRun`).
 		*/
 		applyHeadersToAgents(agents) {
+			const friends = this.core;
 			Object.values(agents).forEach((agent) => {
-				this.applyHeadersToAgent(agent);
+				if (ɵisHttpAgent(agent)) this.applyHeaderRecordToAgent(agent, friends.headers);
 			});
 		}
 		/**
+		* Resolve headers fresh and apply them to `agent` right before a run or
+		* connect actually sends (#1937) — the resolving counterpart to
+		* `applyHeadersToAgent`. Friends-only: only the run handler should call
+		* this, since resolving can invoke a user-supplied builder that throws
+		* synchronously or returns a rejecting promise. Resolution is synchronous
+		* for a record or a sync builder; this returns a promise only when an
+		* async builder must be awaited first, and callers that need the write to
+		* have landed before continuing must await a returned promise.
+		*
+		* A `ProxiedCopilotRuntimeAgent` never invokes the builder here: its core
+		* headers are added by `ɵruntimeFetch` at send time instead, so only its
+		* own headers are (re)applied.
+		*/
+		prepareAgentHeadersForRun(agent) {
+			if (!ɵisHttpAgent(agent)) return;
+			if (agent instanceof ProxiedCopilotRuntimeAgent) {
+				this.applyHeaderRecordToAgent(agent, {});
+				return;
+			}
+			const resolved = this.core.resolveHeaders();
+			if (isPromiseLike(resolved)) return Promise.resolve(resolved).then((headers) => {
+				this.applyHeaderRecordToAgent(agent, headers);
+			});
+			this.applyHeaderRecordToAgent(agent, resolved);
+		}
+		/**
 		* Apply current credentials to an agent
 		*/
 		applyCredentialsToAgent(agent) {
@@ -2072,6 +2339,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		}
 		createRuntimeFetch() {
 			if (!this.runtimeFetch) this.runtimeFetch = (async (input, init) => {
+				var _init$headers;
+				const friends = this.core;
+				const coreHeaders = await abortable(friends.resolveHeaders(), init === null || init === void 0 ? void 0 : init.signal);
+				const requestHeaders = ɵoverlayCoreHeaders((_init$headers = init === null || init === void 0 ? void 0 : init.headers) !== null && _init$headers !== void 0 ? _init$headers : input instanceof Request ? input.headers : void 0, coreHeaders);
+				init = {
+					...init,
+					headers: requestHeaders
+				};
 				const meta = () => runtimeRequestMeta(init);
 				const watchdog = this.armRuntimeRequestWatchdog(meta());
 				try {
@@ -2143,7 +2418,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			const headersGeneration = this.inspectorMetadataHeadersGeneration;
 			const credentialsGeneration = this.inspectorMetadataCredentialsGeneration;
 			const friends = this.core;
-			const headers = { ...friends.headers };
+			let headers;
+			try {
+				const resolved = friends.resolveHeaders();
+				headers = { ...isPromiseLike(resolved) ? await resolved : resolved };
+			} catch (_unused) {
+				if (generation === this.inspectorMetadataGeneration) this.setInspectorMetadata(void 0);
+				return;
+			}
+			if (generation !== this.inspectorMetadataGeneration) return;
 			const credentials = friends.credentials;
 			const abortController = new AbortController();
 			this.inspectorMetadataAbortController = abortController;
@@ -2186,7 +2469,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					aborted,
 					timeout
 				]);
-			} catch (_unused) {
+			} catch (_unused2) {
 				nextMetadata = void 0;
 			} finally {
 				if (timeoutId !== void 0) clearTimeout(timeoutId);
@@ -2305,6 +2588,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		async markRuntimeUnreachable(error) {
 			this.setRuntimeConnectionStatus(CopilotKitCoreRuntimeConnectionStatus.Error);
 			await this.notifyRuntimeStatusChanged(CopilotKitCoreRuntimeConnectionStatus.Error);
+			if (isHeaderResolutionError(error)) {
+				_copilotkit_shared.logger.warn(`Could not resolve request headers for the identification request (${this._runtimeUrl}/info). Check the headers builder passed to CopilotKit.`);
+				return;
+			}
 			const runtimeStatus = isRuntimeInfoRequestError(error) ? error.runtimeInfoStatus : void 0;
 			_copilotkit_shared.logger.warn(runtimeStatus === void 0 ? `Runtime did not answer the identification request (${this._runtimeUrl}/info): ${error.message}. The runtime appears to be unreachable.` : `Runtime answered the identification request with status ${runtimeStatus} (${this._runtimeUrl}/info): ${error.message}. The runtime is reachable but refused the request — check credentials and authorisation before addresses and ports.`);
 			await this.core.emitError({
@@ -2570,9 +2857,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			}
 		}
 		async fetchRuntimeInfo(runtimeUrl, runtimeTransport, signal) {
-			const baseHeaders = this.core.headers;
-			const credentials = this.core.credentials;
-			const headers = { ...baseHeaders };
+			const friends = this.core;
+			const credentials = friends.credentials;
+			const resolved = friends.resolveHeaders();
+			const headers = { ...isPromiseLike(resolved) ? await abortable(resolved, signal) : resolved };
 			if (runtimeTransport === "single") return {
 				runtimeInfo: await this.fetchRuntimeInfoSingle(this.singleEndpointUrlFor(runtimeUrl), headers, credentials, signal),
 				resolvedTransport: "single"
@@ -2625,7 +2913,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					runtimeInfo: await response.json(),
 					resolvedTransport: "rest"
 				};
-			} catch (_unused2) {}
+			} catch (_unused3) {}
 			return {
 				runtimeInfo: await this.fetchRuntimeInfoSingle(this.singleEndpointUrlFor(runtimeUrl), { ...headers }, credentials, signal),
 				resolvedTransport: "single"
@@ -2875,18 +3163,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				const seededState = JSON.parse(JSON.stringify((_suggestionsConsumerA = suggestionsConsumerAgent.state) !== null && _suggestionsConsumerA !== void 0 ? _suggestionsConsumerA : {}));
 				const useStateless = this.core.suggestions === true && this.core.runtimeTransport !== "single";
 				let suggestionAgent;
+				let statelessAgent;
 				if (useStateless) {
 					const suggestUrl = `${this.core.runtimeUrl}/agent/${encodeURIComponent(resolvedProviderAgentId)}/suggest`;
 					const credentials = this.core.credentials;
-					suggestionAgent = new _ag_ui_client.HttpAgent({
+					statelessAgent = new _ag_ui_client.HttpAgent({
 						agentId: resolvedProviderAgentId,
 						url: suggestUrl,
-						headers: { ...this.core.headers },
 						...credentials ? { fetch: (url, requestInit) => fetch(url, {
 							...requestInit,
 							credentials
 						}) } : {}
 					});
+					suggestionAgent = statelessAgent;
 				} else {
 					suggestionAgent = suggestionsProviderAgent.clone();
 					if (suggestionAgent instanceof ProxiedCopilotRuntimeAgent) suggestionAgent.messageFilter = void 0;
@@ -2899,6 +3188,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					suggestionAgent.abortRun();
 				} };
 				this._runningSuggestions[consumerAgentId] = [...(_this$_runningSuggest3 = this._runningSuggestions[consumerAgentId]) !== null && _this$_runningSuggest3 !== void 0 ? _this$_runningSuggest3 : [], runHandle];
+				if (statelessAgent) statelessAgent.headers = { ...await this.core.resolveHeaders() };
+				else await this.core.prepareAgentHeadersForRun(suggestionAgent);
+				if (aborted) return;
 				suggestionAgent.addMessage({
 					id: suggestionId,
 					role: "user",
@@ -3594,7 +3886,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 						if (typeof cursorAware.clearReconnectCursor === "function") cursorAware.clearReconnectCursor(incomingThreadId);
 					}
 				}
-				this._internal.applyHeadersToAgent(agent);
+				const headersApplied = this._internal.prepareAgentHeadersForRun(agent);
+				if (headersApplied) await headersApplied;
 				await this._internal.notifySubscribers((subscriber) => {
 					var _subscriber$onAgentRu;
 					return (_subscriber$onAgentRu = subscriber.onAgentRunStarted) === null || _subscriber$onAgentRu === void 0 ? void 0 : _subscriber$onAgentRu.call(subscriber, {
@@ -3610,7 +3903,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					forwardedProps: this._internal.properties,
 					tools: this.buildFrontendTools(agent.agentId),
 					context: this._internal.getContextForAgent(agent.agentId)
-				}, this.createAgentErrorSubscriber(agent));
+				}, this.createAgentErrorSubscriber(agent, "connect"));
 				if (this._connectionGenerations.get(agent) !== connection || ((_agent$threadId4 = agent.threadId) !== null && _agent$threadId4 !== void 0 ? _agent$threadId4 : null) !== incomingThreadId) return runAgentResult;
 				const controller = new AbortController();
 				const replay = (_this$_interactionAbo = this._interactionAbortControllers.get(agent)) !== null && _this$_interactionAbo !== void 0 ? _this$_interactionAbo : {
@@ -3661,7 +3954,16 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		*/
 		async runAgent({ agent, forwardedProps, resume, runId }, continuationHandoff) {
 			if (agent.agentId) this._internal.suggestionEngine.clearSuggestions(agent.agentId);
-			this._internal.applyHeadersToAgent(agent);
+			try {
+				const headersApplied = this._internal.prepareAgentHeadersForRun(agent);
+				if (headersApplied) await headersApplied;
+			} catch (_unused) {
+				continuationHandoff === null || continuationHandoff === void 0 || continuationHandoff.cancel();
+				return {
+					result: void 0,
+					newMessages: []
+				};
+			}
 			if (agent.detachActiveRun) try {
 				await agent.detachActiveRun();
 			} catch (error) {
@@ -3695,7 +3997,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			this._runDepth++;
 			try {
 				let logicalRunId = resumedRunId !== null && resumedRunId !== void 0 ? resumedRunId : runId;
-				const agentSubscriber = this.createAgentErrorSubscriber(agent);
+				const agentSubscriber = this.createAgentErrorSubscriber(agent, "run");
 				let started = false;
 				const onRunStartedEvent = agentSubscriber.onRunStartedEvent;
 				const onRunInitialized = agentSubscriber.onRunInitialized;
@@ -4229,7 +4531,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		/**
 		* Create an agent error subscriber
 		*/
-		createAgentErrorSubscriber(agent) {
+		createAgentErrorSubscriber(agent, stream) {
 			const emitAgentError = async (error, code, extraContext = {}) => {
 				const context = { ...extraContext };
 				if (agent.agentId) context.agentId = agent.agentId;
@@ -4253,7 +4555,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					await emitAgentError(rawError, CopilotKitCoreErrorCode.AGENT_RUN_ERROR_EVENT, {
 						source: "onRunErrorEvent",
 						event,
-						runtimeErrorCode: event === null || event === void 0 ? void 0 : event.code
+						runtimeErrorCode: event === null || event === void 0 ? void 0 : event.code,
+						phase: stream === "run" ? "live" : ɵgetConnectRunErrorPhase(event)
 					});
 				}
 			};
@@ -4911,6 +5214,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		stop() {
 			const session = this.session;
 			if (!session) return;
+			const collector = session.collector;
+			session.collector = void 0;
+			collector === null || collector === void 0 || collector.stop();
 			if (session.ready && session.connection) this.flush(session, session.connection);
 			this.end(session, {
 				status: "error",
@@ -5013,6 +5319,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			} finally {
 				if (socket) {
 					socket.off(connection.socketRefs);
+					socket.connect = () => void 0;
 					socket.disconnect();
 				}
 			}
@@ -5020,12 +5327,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		fail(session, connection, code, retryable = true) {
 			var _session$collector3;
 			if (!this.current(session, connection)) return;
-			(_session$collector3 = session.collector) === null || _session$collector3 === void 0 || _session$collector3.stop();
-			session.collector = void 0;
 			if (session.ready && session.started) session.promise = new Promise((resolve) => {
 				session.resolve = resolve;
 			});
 			session.ready = false;
+			(_session$collector3 = session.collector) === null || _session$collector3 === void 0 || _session$collector3.stop();
+			session.collector = void 0;
 			this.discardQueue(session);
 			session.linkedThreads.clear();
 			for (const pending of connection.pending) pending.finish("PERSISTENCE_UNKNOWN");
@@ -5070,12 +5377,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					if (!this.current(session, connection)) return;
 				}
 				const rest = transport === "rest";
+				const resolved = this.core.resolveHeaders();
+				const coreHeaders = isPromiseLike(resolved) ? await abortable(resolved, connection.abort.signal) : resolved;
+				if (!this.current(session, connection)) return;
 				const response = await fetch(rest ? `${runtimeUrl}/trajectory/${encodeURIComponent(session.trajectoryId)}/connect` : (_this$core$ɵruntimeE = this.core.ɵruntimeEndpointUrl) !== null && _this$core$ɵruntimeE !== void 0 ? _this$core$ɵruntimeE : runtimeUrl, {
 					method: "POST",
 					redirect: "error",
 					signal: connection.abort.signal,
 					headers: {
-						...this.core.headers,
+						...coreHeaders,
 						"Content-Type": "application/json"
 					},
 					credentials: this.core.credentials,
@@ -5187,7 +5497,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			return ((_connection$socket = connection.socket) === null || _connection$socket === void 0 ? void 0 : _connection$socket.isConnected()) === true && ((_connection$channel = connection.channel) === null || _connection$channel === void 0 ? void 0 : _connection$channel.state) === "joined";
 		}
 		send(session, connection, event) {
-			if (!this.current(session, connection) || !session.ready) return;
+			if (!this.current(session, connection)) return;
+			if (!session.ready) {
+				this.addDropped(session, 1, false);
+				return;
+			}
 			if (!this.connected(connection)) {
 				this.addDropped(session, 1);
 				this.fail(session, connection, "CONNECTION_LOST");
@@ -5358,7 +5672,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				});
 			}
 			if (config.sink === void 0) {
-				if (options.learningContainerIds !== void 0) console.warn("[CopilotKit] learningContainerIds is supported only with a custom sink. Authenticated Trajectory capture does not assign Learning Containers; remove learningContainerIds from the capture options.");
+				if (options.learningContainerIds !== void 0) console.warn("[CopilotKit] learningContainerIds is supported only with a custom sink. Authenticated Trajectory capture ignores it; assign Learning Spaces on the server with getTrajectoryLearningContainerIds on CopilotKitIntelligence, and remove learningContainerIds from the capture options.");
 				this.stopLegacy();
 				return this.connection.start(options.trajectoryId, config);
 			}
@@ -6686,6 +7000,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		CopilotKitCoreErrorCode["AGENT_CONNECT_FAILED"] = "agent_connect_failed";
 		CopilotKitCoreErrorCode["AGENT_RUN_FAILED"] = "agent_run_failed";
 		CopilotKitCoreErrorCode["AGENT_RUN_FAILED_EVENT"] = "agent_run_failed_event";
+		/**
+		* An agent emitted RUN_ERROR. `context.phase` (`RunErrorPhase`) is
+		* `"replay"` when the error belongs to stored thread history replayed on
+		* connect, `"live"` when the run is happening now, and `"unknown"` when the
+		* transport cannot tell. Show a live-failure notice only for `"live"`.
+		*/
 		CopilotKitCoreErrorCode["AGENT_RUN_ERROR_EVENT"] = "agent_run_error_event";
 		CopilotKitCoreErrorCode["TOOL_ARGUMENT_PARSE_FAILED"] = "tool_argument_parse_failed";
 		CopilotKitCoreErrorCode["TOOL_HANDLER_FAILED"] = "tool_handler_failed";
@@ -6714,6 +7034,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		CopilotKitCoreErrorCode["TRANSCRIPTION_AUTH_FAILED"] = "transcription_auth_failed";
 		CopilotKitCoreErrorCode["TRANSCRIPTION_NETWORK_ERROR"] = "transcription_network_error";
 		CopilotKitCoreErrorCode["SUBSCRIBER_CALLBACK_FAILED"] = "subscriber_callback_failed";
+		/**
+		* The `headers` builder threw, rejected, or returned something other than
+		* an object. The request was not sent. `error.cause` is the builder's error.
+		*/
+		CopilotKitCoreErrorCode["HEADER_RESOLUTION_FAILED"] = "header_resolution_failed";
 		return CopilotKitCoreErrorCode;
 	}({});
 	/**
@@ -6736,18 +7061,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		CopilotKitCoreRuntimeConnectionStatus["Error"] = "error";
 		return CopilotKitCoreRuntimeConnectionStatus;
 	}({});
-	/**
-	* Normalize a header map to the internal invariant: a `Record<string, string>`
-	* with no `null`/`undefined` values. Entries whose value is `null`/`undefined`
-	* are dropped (this is how a header is cleared). Shared by the constructor and
-	* `setHeaders` so both write paths into `_headers` enforce the same invariant.
-	*/
-	function normalizeHeaders(headers) {
-		return Object.fromEntries(Object.entries(headers).filter((entry) => entry[1] != null));
-	}
 	var CopilotKitCore = class {
 		constructor({ runtimeUrl, runtimeTransport = "auto", deferInitialConnection = false, headers = {}, credentials, messageFilter, properties = {}, agents__unsafe_dev_only = {}, tools = [], suggestionsConfig = [], debug, learning }) {
-			_defineProperty(this, "_headers", void 0);
+			_defineProperty(this, "headerSource", void 0);
 			_defineProperty(this, "_credentials", void 0);
 			_defineProperty(this, "_messageFilter", void 0);
 			_defineProperty(this, "_properties", void 0);
@@ -6765,7 +7081,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			_defineProperty(this, "learningConfiguredListeners", /* @__PURE__ */ new Set());
 			_defineProperty(this, "_memoryStore", void 0);
 			_defineProperty(this, "previousAgentIds", /* @__PURE__ */ new Set());
-			this._headers = normalizeHeaders(headers);
+			this.headerSource = new HeaderSourceResolver((error) => {
+				this.emitError({
+					error,
+					code: CopilotKitCoreErrorCode.HEADER_RESOLUTION_FAILED,
+					context: { source: "headers" }
+				});
+			});
+			this.headerSource.setSource(headers);
 			this._credentials = credentials;
 			this._messageFilter = messageFilter;
 			this._properties = properties;
@@ -6823,6 +7146,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* Internal method used by delegate classes to emit errors
 		*/
 		async emitError({ error, code, context = {} }) {
+			if (code !== CopilotKitCoreErrorCode.HEADER_RESOLUTION_FAILED && isHeaderResolutionError(error)) return;
 			await this.notifySubscribers((subscriber) => {
 				var _subscriber$onError;
 				return (_subscriber$onError = subscriber.onError) === null || _subscriber$onError === void 0 ? void 0 : _subscriber$onError.call(subscriber, {
@@ -6885,8 +7209,24 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		get runtimeVersion() {
 			return this.agentRegistry.runtimeVersion;
 		}
+		/**
+		* The last resolved headers. With a builder this is the value from the most
+		* recent request, not necessarily current; call `resolveHeaders()` for that.
+		*/
 		get headers() {
-			return this._headers;
+			return this.headerSource.headers;
+		}
+		/**
+		* Resolve the current headers. Synchronous for a record or a sync builder,
+		* a promise for an async builder. Concurrent calls share one builder call.
+		* The returned object is shared; copy it before modifying.
+		*/
+		resolveHeaders() {
+			return this.headerSource.resolve();
+		}
+		/** Changes only on `setHeaders` or a new source, never on a new token. */
+		get ɵheadersGeneration() {
+			return this.headerSource.generation;
 		}
 		get credentials() {
 			return this._credentials;
@@ -7027,9 +7367,17 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* with, set it at the provider/core level instead of on the agent, or update
 		* it on the agent directly. The clear-on-logout pattern above is for
 		* core-level headers.
+		*
+		* Pass a function to have headers evaluated when each request is sent
+		* (sync or async). Setting the same function again is a no-op. A new token
+		* from the builder doesn't notify `onHeadersChanged`. On a user switch,
+		* call `setHeaders` with a NEW function (or a record), or remount.
+		*
+		* Passing a record equal (by value) to the currently applied record is
+		* also a no-op — safe to call on every render with a fresh object literal.
 		*/
 		setHeaders(headers) {
-			this._headers = normalizeHeaders(headers);
+			if (!this.headerSource.setSource(headers)) return;
 			if (this._memoryStore) this.syncMemoryContext();
 			this.agentRegistry.applyHeadersToAgents(this.agentRegistry.agents);
 			this.agentRegistry.handleHeadersChanged();
@@ -7185,8 +7533,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			return this.learningBridge.registerOpenThread(params);
 		}
 		/**
-		* Re-apply the current headers to a single agent (delegated to
-		* AgentRegistry). Core headers are merged on top of the agent's own
+		* Re-apply the last resolved header snapshot to a single agent (delegated
+		* to AgentRegistry). Core headers are merged on top of the agent's own
 		* construction-time headers rather than replacing them, so headers
 		* configured directly on an `HttpAgent` (e.g. an `Authorization` for a
 		* self-hosted backend) survive header updates instead of being silently
@@ -7197,11 +7545,31 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* afterwards is `setHeaders` (which re-applies to every agent), not mutating
 		* `agent.headers` directly — a direct mutation is overwritten on the next
 		* re-apply.
+		*
+		* A `ProxiedCopilotRuntimeAgent` keeps only its own construction-time
+		* headers here — core headers are added by `ɵruntimeFetch` when each
+		* request is sent (see #1937), so `agent.headers` never carries a stale
+		* copy of a core header the builder has since stopped returning.
+		*
+		* Never invokes the headers builder (unlike the run/connect path's
+		* internal `prepareAgentHeadersForRun`): safe to call from a dev-only
+		* registration helper or a React effect that re-runs on every render
+		* without risking a synchronous throw or an unhandled async rejection from
+		* a user-supplied builder.
 		*/
 		applyHeadersToAgent(agent) {
 			this.agentRegistry.applyHeadersToAgent(agent);
 		}
 		/**
+		* Resolve headers fresh and apply them to `agent` right before a run or
+		* connect actually sends (#1937). Friends-only (delegated to
+		* AgentRegistry) — the run handler is the sole caller, since resolving can
+		* invoke a user-supplied builder that throws or rejects.
+		*/
+		prepareAgentHeadersForRun(agent) {
+			return this.agentRegistry.prepareAgentHeadersForRun(agent);
+		}
+		/**
 		* Context management (delegated to ContextStore).
 		* Pass `agentIds` to restrict the entry to runs of specific agents;
 		* omit it for context every agent should receive.
@@ -7261,17 +7629,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		/**
 		* Pushes the current runtime wiring into the memory store. When the runtime
 		* is connected and both the intelligence WebSocket URL and runtime URL are
-		* available, the store receives a context (runtime URL, WebSocket URL, and a
-		* copy of the current headers); otherwise its context is cleared. No-op when
-		* the store has not been created yet.
+		* available, the store receives a context (runtime URL, WebSocket URL);
+		* otherwise its context is cleared. No-op when the store has not been
+		* created yet.
+		*
+		* Headers are deliberately NOT part of this context: the store's `fetch` is
+		* `ɵruntimeFetch` (see `ensureMemoryStore`), which already resolves and
+		* overlays the current core headers at send time (#1937) — a header
+		* snapshot copied here would go stale between context syncs.
 		*/
 		syncMemoryContext() {
 			var _this$intelligence;
 			if (!this._memoryStore) return;
 			if (this.runtimeConnectionStatus === CopilotKitCoreRuntimeConnectionStatus.Connected && ((_this$intelligence = this.intelligence) === null || _this$intelligence === void 0 ? void 0 : _this$intelligence.wsUrl) && this.runtimeUrl) this._memoryStore.setContext({
 				runtimeUrl: this.runtimeUrl,
-				wsUrl: this.intelligence.wsUrl,
-				headers: { ...this.headers }
+				wsUrl: this.intelligence.wsUrl
 			});
 			else this._memoryStore.setContext(null);
 		}
@@ -8755,8 +9127,10 @@ exports.ContextStore = ContextStore;
 exports.CopilotKitCore = CopilotKitCore;
 exports.CopilotKitCoreErrorCode = CopilotKitCoreErrorCode;
 exports.CopilotKitCoreRuntimeConnectionStatus = CopilotKitCoreRuntimeConnectionStatus;
+exports.CopilotKitHeaderResolutionError = CopilotKitHeaderResolutionError;
 exports.INSPECTOR_THREAD_BRIDGE_PLUGIN_ID = INSPECTOR_THREAD_BRIDGE_PLUGIN_ID;
 exports.IntelligenceAgent = IntelligenceAgent;
+exports.IntelligenceReplayFailedError = IntelligenceReplayFailedError;
 exports.MEMORY_ERROR_REGISTRY = MEMORY_ERROR_REGISTRY;
 exports.MemoryError = MemoryError;
 exports.ProxiedCopilotRuntimeAgent = ProxiedCopilotRuntimeAgent;
@@ -8828,5 +9202,6 @@ exports.ɵselectThreads = ɵselectThreads;
 exports.ɵselectThreadsError = ɵselectThreadsError;
 exports.ɵselectThreadsIsLoading = ɵselectThreadsIsLoading;
 exports.ɵthreadAdapterEvents = ɵthreadAdapterEvents;
+exports.ɵwithHeaderDefaults = ɵwithHeaderDefaults;
 });
 //# sourceMappingURL=index.umd.js.map