@copilotkit/core 1.77.2 → 1.79.0

package/dist/index.cjs

@@ -1104,7 +1104,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 				...this.headers,
 				"Content-Type": "application/json"
 			});
-			fetch(this.singleEndpointUrl, {
+			this.fetch(this.singleEndpointUrl, {
 				method: "POST",
 				headers,
 				body: JSON.stringify({
@@ -1115,7 +1115,8 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 					},
 					...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);
 			});
@@ -1126,14 +1127,15 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		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);
 		});
@@ -1549,6 +1551,183 @@ async function createSingleRouteResourceRequest(input, init, runtimeUrl) {
 	};
 }
 
+//#endregion
+//#region src/core/header-source.ts
+var CopilotKitHeaderResolutionError = class extends Error {
+	name = "CopilotKitHeaderResolutionError";
+	constructor(cause) {
+		super("[CopilotKit] Failed to resolve request headers", { cause });
+	}
+};
+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 {
+	source = {};
+	sourceGeneration = 0;
+	snapshot = {};
+	inFlight;
+	constructor(onFailure) {
+		this.onFailure = onFailure;
+	}
+	/** 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() {
+		const source = this.source;
+		if (typeof source !== "function") return this.snapshot;
+		const generation = this.sourceGeneration;
+		if (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(() => {
+			if (this.inFlight?.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. */
@@ -1883,29 +2062,85 @@ var AgentRegistry = class {
 		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).
+	*/
+	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)) {
-			if (!this.agentOwnHeaders.has(agent)) this.agentOwnHeaders.set(agent, { ...agent.headers });
-			agent.headers = {
-				...this.agentOwnHeaders.get(agent),
-				...this.core.headers
-			};
-		}
+		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) {
@@ -1964,6 +2199,13 @@ var AgentRegistry = class {
 	}
 	createRuntimeFetch() {
 		if (!this.runtimeFetch) this.runtimeFetch = (async (input, init) => {
+			const friends = this.core;
+			const coreHeaders = await abortable(friends.resolveHeaders(), init?.signal);
+			const requestHeaders = ɵoverlayCoreHeaders(init?.headers ?? (input instanceof Request ? input.headers : void 0), coreHeaders);
+			init = {
+				...init,
+				headers: requestHeaders
+			};
 			const meta = () => runtimeRequestMeta(init);
 			const watchdog = this.armRuntimeRequestWatchdog(meta());
 			try {
@@ -2033,7 +2275,15 @@ var AgentRegistry = class {
 		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 {
+			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;
@@ -2194,6 +2444,10 @@ var AgentRegistry = class {
 	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({
@@ -2454,9 +2708,10 @@ var AgentRegistry = class {
 		}
 	}
 	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"
@@ -2744,18 +2999,19 @@ var SuggestionEngine = class {
 			const seededState = JSON.parse(JSON.stringify(suggestionsConsumerAgent.state ?? {}));
 			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;
@@ -2768,6 +3024,9 @@ var SuggestionEngine = class {
 				suggestionAgent.abortRun();
 			} };
 			this._runningSuggestions[consumerAgentId] = [...this._runningSuggestions[consumerAgentId] ?? [], runHandle];
+			if (statelessAgent) statelessAgent.headers = { ...await this.core.resolveHeaders() };
+			else await this.core.prepareAgentHeadersForRun(suggestionAgent);
+			if (aborted) return;
 			suggestionAgent.addMessage({
 				id: suggestionId,
 				role: "user",
@@ -3514,7 +3773,8 @@ var RunHandler = class {
 					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) => subscriber.onAgentRunStarted?.({
 				copilotkit: this.core,
 				agent
@@ -3578,7 +3838,16 @@ var RunHandler = class {
 	*/
 	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 {
+			continuationHandoff?.cancel();
+			return {
+				result: void 0,
+				newMessages: []
+			};
+		}
 		if (agent.detachActiveRun) try {
 			await agent.detachActiveRun();
 		} catch (error) {
@@ -4745,6 +5014,9 @@ var TrajectoryConnection = class {
 	stop() {
 		const session = this.session;
 		if (!session) return;
+		const collector = session.collector;
+		session.collector = void 0;
+		collector?.stop();
 		if (session.ready && session.connection) this.flush(session, session.connection);
 		this.end(session, {
 			status: "error",
@@ -4844,18 +5116,19 @@ var TrajectoryConnection = class {
 		} finally {
 			if (socket) {
 				socket.off(connection.socketRefs);
+				socket.connect = () => void 0;
 				socket.disconnect();
 			}
 		}
 	}
 	fail(session, connection, code, retryable = true) {
 		if (!this.current(session, connection)) return;
-		session.collector?.stop();
-		session.collector = void 0;
 		if (session.ready && session.started) session.promise = new Promise((resolve) => {
 			session.resolve = resolve;
 		});
 		session.ready = false;
+		session.collector?.stop();
+		session.collector = void 0;
 		this.discardQueue(session);
 		session.linkedThreads.clear();
 		for (const pending of connection.pending) pending.finish("PERSISTENCE_UNKNOWN");
@@ -4899,12 +5172,15 @@ var TrajectoryConnection = class {
 				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.ɵruntimeEndpointUrl ?? runtimeUrl, {
 				method: "POST",
 				redirect: "error",
 				signal: connection.abort.signal,
 				headers: {
-					...this.core.headers,
+					...coreHeaders,
 					"Content-Type": "application/json"
 				},
 				credentials: this.core.credentials,
@@ -5013,7 +5289,11 @@ var TrajectoryConnection = class {
 		return connection.socket?.isConnected() === true && 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");
@@ -6519,6 +6799,11 @@ let CopilotKitCoreErrorCode = /* @__PURE__ */ function(CopilotKitCoreErrorCode)
 	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;
 }({});
 /**
@@ -6541,17 +6826,8 @@ let CopilotKitCoreRuntimeConnectionStatus = /* @__PURE__ */ function(CopilotKitC
 	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 {
-	_headers;
+	headerSource;
 	_credentials;
 	_messageFilter;
 	_properties;
@@ -6582,7 +6858,14 @@ var CopilotKitCore = class {
 	*/
 	previousAgentIds = /* @__PURE__ */ new Set();
 	constructor({ runtimeUrl, runtimeTransport = "auto", deferInitialConnection = false, headers = {}, credentials, messageFilter, properties = {}, agents__unsafe_dev_only = {}, tools = [], suggestionsConfig = [], debug, learning }) {
-		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;
@@ -6640,6 +6923,7 @@ var CopilotKitCore = class {
 	* 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) => subscriber.onError?.({
 			copilotkit: this,
 			error,
@@ -6699,8 +6983,24 @@ var CopilotKitCore = class {
 	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;
@@ -6841,9 +7141,17 @@ var CopilotKitCore = class {
 	* 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();
@@ -6990,8 +7298,8 @@ var CopilotKitCore = class {
 		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
@@ -7002,11 +7310,31 @@ var CopilotKitCore = class {
 	* 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.
@@ -7066,16 +7394,20 @@ var CopilotKitCore = class {
 	/**
 	* 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() {
 		if (!this._memoryStore) return;
 		if (this.runtimeConnectionStatus === CopilotKitCoreRuntimeConnectionStatus.Connected && 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);
 	}
@@ -8506,6 +8838,7 @@ 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.MEMORY_ERROR_REGISTRY = MEMORY_ERROR_REGISTRY;
@@ -8579,4 +8912,5 @@ exports.ɵselectThreads = ɵselectThreads;
 exports.ɵselectThreadsError = ɵselectThreadsError;
 exports.ɵselectThreadsIsLoading = ɵselectThreadsIsLoading;
 exports.ɵthreadAdapterEvents = ɵthreadAdapterEvents;
+exports.ɵwithHeaderDefaults = ɵwithHeaderDefaults;
 //# sourceMappingURL=index.cjs.map