@copilotkit/core 1.56.2 → 1.56.4

package/dist/index.umd.js

@@ -1,8 +1,8 @@
 (function(global, factory) {
-  typeof exports === 'object' && typeof module !== 'undefined' ?  factory(exports, require('@ag-ui/client'), require('@copilotkit/shared'), require('rxjs'), require('rxjs/operators'), require('phoenix'), require('zod-to-json-schema'), require('rxjs/fetch')) :
-  typeof define === 'function' && define.amd ? define(['exports', '@ag-ui/client', '@copilotkit/shared', 'rxjs', 'rxjs/operators', 'phoenix', 'zod-to-json-schema', 'rxjs/fetch'], factory) :
-  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory((global.CopilotKitCore = {}), global.AgUIClient,global.CopilotKitShared,global.rxjs,global.rxjs.operators,global.phoenix,global.zodToJsonSchema,global.rxjs_fetch));
-})(this, function(exports, _ag_ui_client, _copilotkit_shared, rxjs, rxjs_operators, phoenix, zod_to_json_schema, rxjs_fetch) {
+  typeof exports === 'object' && typeof module !== 'undefined' ?  factory(exports, require('@tanstack/pacer'), require('@ag-ui/client'), require('@copilotkit/shared'), require('rxjs'), require('rxjs/operators'), require('phoenix'), require('zod-to-json-schema'), require('rxjs/fetch')) :
+  typeof define === 'function' && define.amd ? define(['exports', '@tanstack/pacer', '@ag-ui/client', '@copilotkit/shared', 'rxjs', 'rxjs/operators', 'phoenix', 'zod-to-json-schema', 'rxjs/fetch'], factory) :
+  (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory((global.CopilotKitCore = {}), global._tanstack_pacer,global.AgUIClient,global.CopilotKitShared,global.rxjs,global.rxjs.operators,global.phoenix,global.zodToJsonSchema,global.rxjs_fetch));
+})(this, function(exports, _tanstack_pacer, _ag_ui_client, _copilotkit_shared, rxjs, rxjs_operators, phoenix, zod_to_json_schema, rxjs_fetch) {
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/utils/phoenix-observable.ts
@@ -167,6 +167,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 //#endregion
 //#region src/intelligence-agent.ts
 	const CLIENT_AG_UI_EVENT = "ag_ui_event";
+	const REPLAY_COMPLETE_EVENT = "replay_complete";
+	const STREAM_IDLE_EVENT = "stream_idle";
 	const STOP_RUN_EVENT = "stop_run";
 	var AgentThreadLockedError = class extends Error {
 		constructor(threadId) {
@@ -180,7 +182,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			_defineProperty(this, "config", void 0);
 			_defineProperty(this, "socket", null);
 			_defineProperty(this, "activeChannel", null);
-			_defineProperty(this, "runId", null);
+			_defineProperty(this, "canonicalRunId", null);
 			_defineProperty(this, "sharedState", void 0);
 			this.config = config;
 			this.sharedState = sharedState;
@@ -217,7 +219,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				var _this$agentId;
 				this.isRunning = true;
 				this.agentId = (_this$agentId = this.agentId) !== null && _this$agentId !== void 0 ? _this$agentId : (0, _ag_ui_client.randomUUID)();
-				const input = this.prepareRunAgentInput(parameters);
+				const effectiveParameters = (parameters === null || parameters === void 0 ? void 0 : parameters.runId) || !this.canonicalRunId ? parameters : {
+					...parameters,
+					runId: this.canonicalRunId
+				};
+				const input = this.prepareRunAgentInput(effectiveParameters);
 				let result;
 				const previousMessageIds = new Set(this.messages.map((m) => m.id));
 				const subscribers = [
@@ -256,14 +262,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			}
 		}
 		abortRun() {
-			if (this.activeChannel && this.runId) {
+			if (this.activeChannel && this.canonicalRunId) {
 				const fallback = setTimeout(() => clear(), 5e3);
 				const clear = () => {
 					clearTimeout(fallback);
 					this.detachActiveRun();
 					this.cleanup();
 				};
-				this.activeChannel.push(STOP_RUN_EVENT, { run_id: this.runId }).receive("ok", clear).receive("error", clear).receive("timeout", clear);
+				this.activeChannel.push(STOP_RUN_EVENT, { run_id: this.canonicalRunId }).receive("ok", clear).receive("error", clear).receive("timeout", clear);
 			} else {
 				this.detachActiveRun();
 				this.cleanup();
@@ -275,11 +281,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		*/
 		run(input) {
 			this.threadId = input.threadId;
-			this.runId = input.runId;
-			return (0, rxjs.defer)(() => this.requestJoinCredentials$("run", input)).pipe((0, rxjs.switchMap)((credentials) => this.observeThread$(input, credentials, {
-				completeOnRunError: false,
-				streamMode: "run"
-			})));
+			this.canonicalRunId = input.runId;
+			return (0, rxjs.defer)(() => this.requestJoinCredentials$("run", input)).pipe((0, rxjs.switchMap)((credentials) => {
+				if (credentials === null) return (0, rxjs.throwError)(() => /* @__PURE__ */ new Error("REST run request returned no credentials"));
+				const canonicalInput = this.applyCanonicalRunIdentity(input, credentials, { fallbackToInputRunId: true });
+				return this.observeThread$(canonicalInput, credentials, {
+					completeOnRunError: false,
+					streamMode: "run"
+				});
+			}));
 		}
 		/**
 		* Reconnect to an existing thread by fetching websocket credentials and
@@ -287,21 +297,15 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		*/
 		connect(input) {
 			this.threadId = input.threadId;
-			this.runId = input.runId;
-			return (0, rxjs.defer)(() => this.requestConnectPlan$(input)).pipe((0, rxjs.switchMap)((plan) => {
-				if (plan === null) return rxjs.EMPTY;
-				if (plan.mode === "bootstrap") {
-					this.setLastSeenEventId(input.threadId, plan.latestEventId);
-					for (const event of plan.events) this.updateRunIdFromEvent(event);
-					return (0, rxjs.from)(plan.events);
-				}
-				this.setLastSeenEventId(input.threadId, plan.joinFromEventId);
-				for (const event of plan.events) this.updateRunIdFromEvent(event);
-				return (0, rxjs.concat)((0, rxjs.from)(plan.events), this.observeThread$(input, { joinToken: plan.joinToken }, {
-					completeOnRunError: true,
-					streamMode: "connect",
-					replayCursor: plan.joinFromEventId
-				}));
+			this.canonicalRunId = null;
+			this.clearReconnectCursor(input.threadId);
+			return (0, rxjs.defer)(() => this.requestJoinCredentials$("connect", input)).pipe((0, rxjs.switchMap)((credentials) => {
+				if (credentials === null) return rxjs.EMPTY;
+				const canonicalInput = this.applyCanonicalRunIdentity(input, credentials, { fallbackToInputRunId: false });
+				return this.observeThread$(canonicalInput, credentials, {
+					completeOnRunError: false,
+					streamMode: "connect"
+				});
 			}));
 		}
 		/**
@@ -318,8 +322,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				ownSocket.disconnect();
 				if (this.socket === ownSocket) this.socket = null;
 			}
-			if (this.threadId) this.sharedState.lastSeenEventIds.delete(this.threadId);
-			this.runId = null;
+			this.canonicalRunId = null;
 		}
 		cleanup() {
 			this.cleanupOwned(this.activeChannel, this.socket);
@@ -340,80 +343,57 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 							tools: input.tools,
 							context: input.context,
 							state: input.state,
-							forwardedProps: input.forwardedProps
+							forwardedProps: input.forwardedProps,
+							...mode === "connect" ? { lastSeenEventId: this.getReconnectCursor(input) } : {}
 						}),
 						...this.config.credentials ? { credentials: this.config.credentials } : {}
 					});
-					if (response.status === 409) throw new AgentThreadLockedError(input.threadId);
+					if (response.status === 204 && mode === "connect") return null;
+					if (response.status === 409 && mode === "run") throw new AgentThreadLockedError(input.threadId);
 					if (!response.ok) {
 						const text = await response.text().catch(() => "");
 						throw new Error(text || response.statusText || String(response.status));
 					}
-					const payload = await response.json();
-					if (!payload.joinToken) throw new Error("missing joinToken");
-					return { joinToken: payload.joinToken };
+					return this.normalizeJoinCredentials(await response.json(), input);
 				} catch (error) {
 					if (error instanceof AgentThreadLockedError) throw error;
 					throw new Error(`REST ${mode} request failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
 				}
 			});
 		}
-		requestConnectPlan$(input) {
-			return (0, rxjs.defer)(async () => {
-				try {
-					const response = await fetch(this.buildRuntimeUrl("connect"), {
-						method: "POST",
-						headers: {
-							"Content-Type": "application/json",
-							...this.config.headers
-						},
-						body: JSON.stringify({
-							threadId: input.threadId,
-							runId: input.runId,
-							messages: input.messages,
-							tools: input.tools,
-							context: input.context,
-							state: input.state,
-							forwardedProps: input.forwardedProps,
-							lastSeenEventId: this.getReconnectCursor(input)
-						}),
-						...this.config.credentials ? { credentials: this.config.credentials } : {}
-					});
-					if (response.status === 204) return null;
-					if (!response.ok) {
-						const text = await response.text().catch(() => "");
-						throw new Error(text || response.statusText || String(response.status));
-					}
-					return this.normalizeConnectPlan(await response.json());
-				} catch (error) {
-					throw new Error(`REST connect request failed: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
-				}
-			});
-		}
-		normalizeConnectPlan(payload) {
+		normalizeJoinCredentials(payload, input) {
 			const envelope = payload && typeof payload === "object" ? payload : null;
-			if ((envelope === null || envelope === void 0 ? void 0 : envelope.mode) === "bootstrap") return {
-				mode: "bootstrap",
-				latestEventId: typeof envelope.latestEventId === "string" ? envelope.latestEventId : null,
-				events: Array.isArray(envelope.events) ? envelope.events : []
+			const realtime = (envelope === null || envelope === void 0 ? void 0 : envelope.realtime) && typeof envelope.realtime === "object" ? envelope.realtime : null;
+			if (typeof (envelope === null || envelope === void 0 ? void 0 : envelope.joinToken) !== "string" || !envelope.joinToken) throw new Error("missing joinToken");
+			if (typeof (realtime === null || realtime === void 0 ? void 0 : realtime.clientUrl) !== "string" || !realtime.clientUrl) throw new Error("missing realtime.clientUrl");
+			if (typeof realtime.topic !== "string" || !realtime.topic) throw new Error("missing realtime.topic");
+			return {
+				threadId: typeof envelope.threadId === "string" && envelope.threadId ? envelope.threadId : input.threadId,
+				runId: typeof envelope.runId === "string" && envelope.runId ? envelope.runId : null,
+				joinToken: envelope.joinToken,
+				realtime: {
+					clientUrl: realtime.clientUrl,
+					topic: realtime.topic
+				}
 			};
-			if ((envelope === null || envelope === void 0 ? void 0 : envelope.mode) === "live") {
-				if (typeof envelope.joinToken !== "string" || envelope.joinToken.length === 0) throw new Error("missing joinToken");
-				return {
-					mode: "live",
-					joinToken: envelope.joinToken,
-					joinFromEventId: typeof envelope.joinFromEventId === "string" ? envelope.joinFromEventId : null,
-					events: Array.isArray(envelope.events) ? envelope.events : []
-				};
-			}
-			throw new Error("invalid connect plan");
 		}
 		observeThread$(input, credentials, options) {
+			return this.observeThreadSession$(input, credentials, options).pipe((0, rxjs_operators.catchError)((error) => {
+				if (!this.isSocketReconnectExhaustedError(error)) return (0, rxjs.throwError)(() => error);
+				return this.requestJoinCredentials$("connect", input).pipe((0, rxjs.switchMap)((refreshedCredentials) => refreshedCredentials === null ? rxjs.EMPTY : this.observeThread$(this.applyCanonicalRunIdentity(input, refreshedCredentials, { fallbackToInputRunId: options.streamMode === "run" }), refreshedCredentials, {
+					...options,
+					channelMode: "connect",
+					replayCursor: this.getReconnectCursor(input)
+				})));
+			}));
+		}
+		observeThreadSession$(input, credentials, options) {
 			return (0, rxjs.defer)(() => {
+				var _options$channelMode;
 				let ownSocket = null;
 				let ownChannel = null;
 				const socket$ = ɵphoenixSocket$({
-					url: this.config.url,
+					url: credentials.realtime.clientUrl,
 					options: {
 						params: {
 							...this.config.socketParams,
@@ -429,10 +409,10 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					bufferSize: 1,
 					refCount: true
 				}));
-				const { topic, params } = this.createThreadChannelDescriptor(input, options.streamMode, options.replayCursor);
+				const params = this.createThreadChannelParams(input, (_options$channelMode = options.channelMode) !== null && _options$channelMode !== void 0 ? _options$channelMode : options.streamMode, options.replayCursor);
 				const channel$ = ɵphoenixChannel$({
 					socket$,
-					topic,
+					topic: credentials.realtime.topic,
 					params
 				}).pipe((0, rxjs_operators.tap)(({ channel }) => {
 					ownChannel = channel;
@@ -442,8 +422,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					refCount: true
 				}));
 				const threadEvents$ = this.observeThreadEvents$(input.threadId, channel$, options).pipe((0, rxjs_operators.share)());
-				const threadCompleted$ = threadEvents$.pipe((0, rxjs_operators.ignoreElements)(), (0, rxjs_operators.endWith)(null), (0, rxjs_operators.take)(1));
-				return (0, rxjs.merge)(this.joinThreadChannel$(channel$), this.observeSocketHealth$(socket$).pipe((0, rxjs_operators.takeUntil)(threadCompleted$)), threadEvents$).pipe((0, rxjs_operators.finalize)(() => this.cleanupOwned(ownChannel, ownSocket)));
+				const replayComplete$ = this.observeControlEvent$(input.threadId, channel$, REPLAY_COMPLETE_EVENT).pipe((0, rxjs_operators.ignoreElements)(), (0, rxjs_operators.share)());
+				const streamIdle$ = this.observeControlEvent$(input.threadId, channel$, STREAM_IDLE_EVENT).pipe((0, rxjs_operators.shareReplay)({
+					bufferSize: 1,
+					refCount: true
+				}));
+				const streamIdleCompletion$ = options.streamMode === "connect" ? streamIdle$.pipe((0, rxjs_operators.take)(1)) : rxjs.EMPTY;
+				const terminal$ = (0, rxjs.merge)(threadEvents$.pipe((0, rxjs_operators.ignoreElements)(), (0, rxjs_operators.endWith)(null), (0, rxjs_operators.take)(1)), streamIdleCompletion$);
+				return (0, rxjs.merge)(this.joinThreadChannel$(channel$), this.observeSocketHealth$(socket$).pipe((0, rxjs_operators.takeUntil)(terminal$)), threadEvents$.pipe((0, rxjs_operators.takeUntil)(streamIdleCompletion$)), replayComplete$.pipe((0, rxjs_operators.takeUntil)(terminal$)), streamIdleCompletion$.pipe((0, rxjs_operators.ignoreElements)())).pipe((0, rxjs_operators.finalize)(() => this.cleanupOwned(ownChannel, ownSocket)));
 			});
 		}
 		joinThreadChannel$(channel$) {
@@ -455,18 +441,24 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		observeThreadEvents$(threadId, channel$, options) {
 			return channel$.pipe((0, rxjs_operators.switchMap)(({ channel }) => this.observeChannelEvent$(channel, CLIENT_AG_UI_EVENT)), (0, rxjs_operators.tap)((payload) => {
 				this.updateLastSeenEventId(threadId, payload);
-				this.updateRunIdFromEvent(payload);
-			}), (0, rxjs_operators.mergeMap)((payload) => (0, rxjs.from)(this.createThreadNotifications(payload, options.completeOnRunError))), (0, rxjs.dematerialize)());
+			}), (0, rxjs_operators.mergeMap)((payload) => this.createThreadNotifications(payload, {
+				completeOnRunError: options.completeOnRunError,
+				completeOnRunFinished: options.streamMode === "run",
+				errorOnRunError: options.streamMode === "run"
+			})), (0, rxjs.dematerialize)());
+		}
+		observeControlEvent$(threadId, channel$, eventName) {
+			return channel$.pipe((0, rxjs_operators.switchMap)(({ channel }) => this.observeChannelEvent$(channel, eventName)), (0, rxjs_operators.tap)((payload) => this.updateLastSeenEventIdFromControl(threadId, payload)));
 		}
 		observeChannelEvent$(channel, eventName) {
 			return ɵobservePhoenixEvent$(channel, eventName);
 		}
-		createThreadNotifications(payload, completeOnRunError) {
-			if (payload.type === _ag_ui_client.EventType.RUN_FINISHED) return [rxjs.Notification.createNext(payload), rxjs.Notification.createComplete()];
+		createThreadNotifications(payload, options) {
+			if (payload.type === _ag_ui_client.EventType.RUN_FINISHED) return options.completeOnRunFinished ? [rxjs.Notification.createNext(payload), rxjs.Notification.createComplete()] : [rxjs.Notification.createNext(payload)];
 			if (payload.type === _ag_ui_client.EventType.RUN_ERROR) {
 				var _message;
 				const errorMessage = (_message = payload.message) !== null && _message !== void 0 ? _message : "Run error";
-				return completeOnRunError ? [rxjs.Notification.createNext(payload), rxjs.Notification.createComplete()] : [rxjs.Notification.createNext(payload), rxjs.Notification.createError(new Error(errorMessage))];
+				return options.completeOnRunError ? [rxjs.Notification.createNext(payload), rxjs.Notification.createComplete()] : options.errorOnRunError ? [rxjs.Notification.createNext(payload), rxjs.Notification.createError(new Error(errorMessage))] : [rxjs.Notification.createNext(payload)];
 			}
 			return [rxjs.Notification.createNext(payload)];
 		}
@@ -475,62 +467,60 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			const origin = typeof window !== "undefined" && window.location ? window.location.origin : "http://localhost";
 			return new URL(path, new URL(this.config.runtimeUrl, origin)).toString();
 		}
-		createThreadChannelDescriptor(input, streamMode, replayCursor) {
-			const params = streamMode === "run" ? {
+		createThreadChannelParams(input, streamMode, replayCursor) {
+			return streamMode === "run" ? {
 				stream_mode: "run",
 				run_id: input.runId
 			} : {
 				stream_mode: "connect",
 				last_seen_event_id: replayCursor === void 0 ? this.getReconnectCursor(input) : replayCursor
 			};
-			return {
-				topic: `thread:${input.threadId}`,
-				params
-			};
 		}
 		getLastSeenEventId(threadId) {
 			var _this$sharedState$las;
 			return (_this$sharedState$las = this.sharedState.lastSeenEventIds.get(threadId)) !== null && _this$sharedState$las !== void 0 ? _this$sharedState$las : null;
 		}
 		getReconnectCursor(input) {
-			return this.hasLocalThreadMessages(input) ? this.getLastSeenEventId(input.threadId) : null;
+			return this.getLastSeenEventId(input.threadId);
 		}
-		hasLocalThreadMessages(input) {
-			return Array.isArray(input.messages) && input.messages.length > 0;
+		clearReconnectCursor(threadId) {
+			this.sharedState.lastSeenEventIds.delete(threadId);
 		}
 		updateLastSeenEventId(threadId, payload) {
 			const eventId = this.readEventId(payload);
 			if (!eventId) return;
 			this.sharedState.lastSeenEventIds.set(threadId, eventId);
 		}
-		setLastSeenEventId(threadId, eventId) {
+		updateLastSeenEventIdFromControl(threadId, payload) {
+			const eventId = this.readControlEventId(payload);
 			if (!eventId) return;
 			this.sharedState.lastSeenEventIds.set(threadId, eventId);
 		}
-		/**
-		* Keep `this.runId` in sync with the backend's actual run ID.
-		*
-		* During a `connect` (resume) flow the client generates a fresh `runId`
-		* via `prepareRunAgentInput`, but the backend is running under its own
-		* run ID.  If the client later sends `STOP_RUN_EVENT` with the wrong
-		* `runId`, the gateway's runner channel will not match it and the agent
-		* keeps running.  Extracting the run ID from live events fixes this.
-		*
-		* The runner normalises events to `run_id` (snake_case) before pushing
-		* to the gateway, so we check both `runId` and `run_id`.
-		*/
-		updateRunIdFromEvent(payload) {
-			var _record$runId;
-			const record = payload;
-			const eventRunId = (_record$runId = record.runId) !== null && _record$runId !== void 0 ? _record$runId : record.run_id;
-			if (typeof eventRunId === "string" && eventRunId.length > 0) this.runId = eventRunId;
-		}
 		readEventId(payload) {
 			const metadata = payload.metadata;
 			if (!metadata || typeof metadata !== "object") return null;
 			const runnerEventId = metadata.cpki_event_id;
 			return typeof runnerEventId === "string" ? runnerEventId : null;
 		}
+		readControlEventId(payload) {
+			if (!payload || typeof payload !== "object") return null;
+			const latestEventId = payload.latestEventId;
+			return typeof latestEventId === "string" ? latestEventId : null;
+		}
+		applyCanonicalRunIdentity(input, credentials, options) {
+			var _credentials$runId;
+			this.threadId = credentials.threadId;
+			const runId = (_credentials$runId = credentials.runId) !== null && _credentials$runId !== void 0 ? _credentials$runId : options.fallbackToInputRunId ? input.runId : null;
+			this.canonicalRunId = runId;
+			return {
+				...input,
+				threadId: credentials.threadId,
+				...runId === null ? {} : { runId }
+			};
+		}
+		isSocketReconnectExhaustedError(error) {
+			return error instanceof Error && error.message.includes("WebSocket connection failed after");
+		}
 	};
 
 //#endregion
@@ -2473,8 +2463,21 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		CopilotKitCoreErrorCode["TRANSCRIPTION_RATE_LIMITED"] = "transcription_rate_limited";
 		CopilotKitCoreErrorCode["TRANSCRIPTION_AUTH_FAILED"] = "transcription_auth_failed";
 		CopilotKitCoreErrorCode["TRANSCRIPTION_NETWORK_ERROR"] = "transcription_network_error";
+		CopilotKitCoreErrorCode["SUBSCRIBER_CALLBACK_FAILED"] = "subscriber_callback_failed";
 		return CopilotKitCoreErrorCode;
 	}({});
+	/**
+	* Runtime allowlist derived from {@link SUBSCRIBE_TO_AGENT_KEYS}. Hoisted
+	* to module scope so the Set is allocated once, not per-subscription.
+	*/
+	const ALLOWED_KEYS = new Set([
+		"onMessagesChanged",
+		"onStateChanged",
+		"onRunInitialized",
+		"onRunFinalized",
+		"onRunFailed",
+		"onRunErrorEvent"
+	]);
 	let CopilotKitCoreRuntimeConnectionStatus = /* @__PURE__ */ function(CopilotKitCoreRuntimeConnectionStatus) {
 		CopilotKitCoreRuntimeConnectionStatus["Disconnected"] = "disconnected";
 		CopilotKitCoreRuntimeConnectionStatus["Connected"] = "connected";
@@ -2543,6 +2546,16 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			}, "Subscriber onError error:");
 		}
 		/**
+		* Log a message to the console and emit an error to subscribers.
+		* Catches failures from `emitError` itself to prevent unhandled rejections.
+		*/
+		logAndEmitError(message, params, logLevel = "error") {
+			console[logLevel](message, params.error);
+			this.emitError(params).catch((emitErr) => {
+				console.error(message + " — emitError itself failed:", emitErr);
+			});
+		}
+		/**
 		* Snapshot accessors
 		*/
 		get context() {
@@ -2579,17 +2592,30 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			return this._properties;
 		}
 		/**
-		* Default throttle interval (ms) applied by framework hooks (e.g.
-		* `useAgent()`) when the hook/component does not specify an explicit
-		* `throttleMs`. An explicit `0` passed as `throttleMs` to `useAgent()`
-		* or `<CopilotChat>` overrides this default and disables throttling.
+		* Default throttle interval (ms) used by `subscribeToAgentWithOptions()`
+		* when the caller does not specify an explicit `throttleMs`.
+		* `undefined` means no default is configured; `0` means no throttling.
 		*/
 		get defaultThrottleMs() {
 			return this._defaultThrottleMs;
 		}
+		/**
+		* Set the default throttle interval (ms) for `subscribeToAgentWithOptions()`.
+		*
+		* Accepts a non-negative finite number or `undefined` (to clear the
+		* default). Invalid values (NaN, Infinity, negative) are logged as
+		* errors and ignored — the previous valid value is preserved.
+		*/
 		setDefaultThrottleMs(value) {
 			if (value !== void 0 && (!Number.isFinite(value) || value < 0)) {
-				this._defaultThrottleMs = void 0;
+				this.logAndEmitError(`CopilotKitCore.setDefaultThrottleMs: value must be a non-negative finite number or undefined, got ${value}. Keeping current value (${this._defaultThrottleMs}).`, {
+					error: /* @__PURE__ */ new Error(`setDefaultThrottleMs: invalid value (${value}), keeping current value (${this._defaultThrottleMs})`),
+					code: CopilotKitCoreErrorCode.SUBSCRIBER_CALLBACK_FAILED,
+					context: {
+						value,
+						currentValue: this._defaultThrottleMs
+					}
+				});
 				return;
 			}
 			this._defaultThrottleMs = value;
@@ -2716,6 +2742,138 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			} };
 		}
 		/**
+		* Subscribe to an agent's notification and lifecycle events with
+		* optional configuration (e.g. throttling).
+		*
+		* Wraps every callback with error protection (`safeCall`) and applies
+		* the options before delegating to `agent.subscribe()`.
+		*
+		* See {@link SubscribeToAgentSubscriber} for the accepted callback subset
+		* and the rationale for excluding AG-UI event handlers.
+		*/
+		subscribeToAgentWithOptions(agent, subscriber, options) {
+			var _ref, _options$throttleMs;
+			const resolved = (_ref = (_options$throttleMs = options === null || options === void 0 ? void 0 : options.throttleMs) !== null && _options$throttleMs !== void 0 ? _options$throttleMs : this._defaultThrottleMs) !== null && _ref !== void 0 ? _ref : 0;
+			let effectiveMs = 0;
+			if (!Number.isFinite(resolved) || resolved < 0) {
+				const source = (options === null || options === void 0 ? void 0 : options.throttleMs) !== void 0 ? "throttleMs" : "defaultThrottleMs";
+				this.logAndEmitError(`CopilotKitCore.subscribeToAgentWithOptions: ${source} must be a non-negative finite number, got ${resolved}. Falling back to unthrottled.`, {
+					error: /* @__PURE__ */ new Error(`subscribeToAgentWithOptions: invalid ${source} (${resolved}), falling back to unthrottled`),
+					code: CopilotKitCoreErrorCode.SUBSCRIBER_CALLBACK_FAILED,
+					context: {
+						agentId: agent.agentId,
+						source,
+						value: resolved
+					}
+				});
+			} else effectiveMs = resolved;
+			const agentLabel = agent.agentId || "(unknown agent)";
+			const safeCall = (label, fn, ...args) => {
+				const reportError = (err, verb) => {
+					this.logAndEmitError(`CopilotKitCore.subscribeToAgentWithOptions[${agentLabel}]: ${label} callback ${verb}:`, {
+						error: err instanceof Error ? err : new Error(String(err)),
+						code: CopilotKitCoreErrorCode.SUBSCRIBER_CALLBACK_FAILED,
+						context: {
+							agentId: agent.agentId,
+							callback: label
+						}
+					});
+				};
+				try {
+					const result = fn(...args);
+					if (result instanceof Promise) return result.catch((err) => {
+						reportError(err, "rejected");
+					});
+					return result;
+				} catch (err) {
+					reportError(err, "threw");
+				}
+			};
+			const guardAll = (sub) => {
+				const guarded = {};
+				if (sub.onMessagesChanged) {
+					const fn = sub.onMessagesChanged;
+					guarded.onMessagesChanged = (params) => safeCall("onMessagesChanged", fn, params);
+				}
+				if (sub.onStateChanged) {
+					const fn = sub.onStateChanged;
+					guarded.onStateChanged = (params) => safeCall("onStateChanged", fn, params);
+				}
+				if (sub.onRunInitialized) {
+					const fn = sub.onRunInitialized;
+					guarded.onRunInitialized = (params) => safeCall("onRunInitialized", fn, params);
+				}
+				if (sub.onRunFinalized) {
+					const fn = sub.onRunFinalized;
+					guarded.onRunFinalized = (params) => safeCall("onRunFinalized", fn, params);
+				}
+				if (sub.onRunFailed) {
+					const fn = sub.onRunFailed;
+					guarded.onRunFailed = (params) => safeCall("onRunFailed", fn, params);
+				}
+				if (sub.onRunErrorEvent) {
+					const fn = sub.onRunErrorEvent;
+					guarded.onRunErrorEvent = (params) => safeCall("onRunErrorEvent", fn, params);
+				}
+				return guarded;
+			};
+			for (const key of Object.keys(subscriber)) if (typeof subscriber[key] === "function" && !ALLOWED_KEYS.has(key)) {
+				const message = `CopilotKitCore.subscribeToAgentWithOptions[${agentLabel}]: callback "${key}" is not supported and was dropped. Supported callbacks: ${Array.from(ALLOWED_KEYS).join(", ")}. Use agent.subscribe() directly for event handlers and per-item notifications.`;
+				this.logAndEmitError(message, {
+					error: new Error(message),
+					code: CopilotKitCoreErrorCode.SUBSCRIBER_CALLBACK_FAILED,
+					context: {
+						agentId: agent.agentId,
+						droppedCallback: key
+					}
+				}, "warn");
+			}
+			if (effectiveMs <= 0) {
+				const subscription = agent.subscribe(guardAll(subscriber));
+				return { unsubscribe: () => subscription.unsubscribe() };
+			}
+			let active = true;
+			let latestMessagesParams = null;
+			let latestStateParams = null;
+			const flushPending = () => {
+				if (active && subscriber.onMessagesChanged && latestMessagesParams) {
+					const params = latestMessagesParams;
+					latestMessagesParams = null;
+					safeCall("onMessagesChanged", subscriber.onMessagesChanged, params);
+				}
+				if (active && subscriber.onStateChanged && latestStateParams) {
+					const params = latestStateParams;
+					latestStateParams = null;
+					safeCall("onStateChanged", subscriber.onStateChanged, params);
+				}
+			};
+			const throttler = new _tanstack_pacer.Throttler(flushPending, {
+				wait: effectiveMs,
+				leading: true,
+				trailing: true
+			});
+			const lifecycleOnly = {};
+			if (subscriber.onRunInitialized) lifecycleOnly.onRunInitialized = subscriber.onRunInitialized;
+			if (subscriber.onRunFinalized) lifecycleOnly.onRunFinalized = subscriber.onRunFinalized;
+			if (subscriber.onRunFailed) lifecycleOnly.onRunFailed = subscriber.onRunFailed;
+			if (subscriber.onRunErrorEvent) lifecycleOnly.onRunErrorEvent = subscriber.onRunErrorEvent;
+			const wrappedSubscriber = guardAll(lifecycleOnly);
+			if (subscriber.onMessagesChanged) wrappedSubscriber.onMessagesChanged = (params) => {
+				latestMessagesParams = params;
+				throttler.maybeExecute();
+			};
+			if (subscriber.onStateChanged) wrappedSubscriber.onStateChanged = (params) => {
+				latestStateParams = params;
+				throttler.maybeExecute();
+			};
+			const subscription = agent.subscribe(wrappedSubscriber);
+			return { unsubscribe: () => {
+				active = false;
+				throttler.cancel();
+				subscription.unsubscribe();
+			} };
+		}
+		/**
 		* Agent connectivity (delegated to RunHandler)
 		*/
 		async connectAgent(params) {
@@ -3264,15 +3422,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		threadUpserted: props(),
 		threadDeleted: props()
 	});
-	function sortThreadsByUpdatedAt(threads) {
-		return [...threads].sort((left, right) => right.updatedAt.localeCompare(left.updatedAt));
+	function sortThreadsByRecency(threads) {
+		return [...threads].sort((left, right) => {
+			var _ref, _left$lastRunAt, _ref2, _right$lastRunAt;
+			const leftKey = (_ref = (_left$lastRunAt = left.lastRunAt) !== null && _left$lastRunAt !== void 0 ? _left$lastRunAt : left.updatedAt) !== null && _ref !== void 0 ? _ref : left.createdAt;
+			return ((_ref2 = (_right$lastRunAt = right.lastRunAt) !== null && _right$lastRunAt !== void 0 ? _right$lastRunAt : right.updatedAt) !== null && _ref2 !== void 0 ? _ref2 : right.createdAt).localeCompare(leftKey);
+		});
 	}
 	function upsertThread(threads, thread) {
 		const existingIndex = threads.findIndex((item) => item.id === thread.id);
-		if (existingIndex === -1) return sortThreadsByUpdatedAt([...threads, thread]);
+		if (existingIndex === -1) return sortThreadsByRecency([...threads, thread]);
 		const next = [...threads];
 		next[existingIndex] = thread;
-		return sortThreadsByUpdatedAt(next);
+		return sortThreadsByRecency(next);
 	}
 	const threadReducer = createReducer(initialThreadState, on(threadAdapterEvents.contextChanged, (state, { context }) => ({
 		...state,
@@ -3305,7 +3467,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		if (sessionId !== state.sessionId) return state;
 		return {
 			...state,
-			threads: sortThreadsByUpdatedAt(threads),
+			threads: sortThreadsByRecency(threads),
 			isLoading: false,
 			error: null,
 			metadataJoinCode: joinCode,