@copilotkit/core 1.56.2 → 1.56.4-canary.1777529757

package/dist/index.mjs

@@ -1,3 +1,4 @@
+import { Throttler } from "@tanstack/pacer";
 import { AbstractAgent, EventType, HttpAgent, randomUUID, runHttpRequest, structuredClone_, transformChunks, transformHttpEventStream } from "@ag-ui/client";
 import { RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, logger, partialJSONParse, phoenixExponentialBackoff, randomUUID as randomUUID$1, resolveDebugConfig, schemaToJsonSchema } from "@copilotkit/shared";
 import { BehaviorSubject, EMPTY, NEVER, Notification, Observable, Subject, Subscription, asapScheduler, concat, defer, dematerialize, firstValueFrom, from, lastValueFrom, merge, of, switchMap, throwError } from "rxjs";
@@ -126,6 +127,8 @@ function ɵobservePhoenixSocketHealth$(socketSignals$, maxConsecutiveErrors) {
 //#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) {
@@ -137,7 +140,7 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	config;
 	socket = null;
 	activeChannel = null;
-	runId = null;
+	canonicalRunId = null;
 	sharedState;
 	constructor(config, sharedState = { lastSeenEventIds: /* @__PURE__ */ new Map() }) {
 		super();
@@ -175,7 +178,11 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 		try {
 			this.isRunning = true;
 			this.agentId = this.agentId ?? randomUUID();
-			const input = this.prepareRunAgentInput(parameters);
+			const effectiveParameters = 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 = [
@@ -214,14 +221,14 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 		}
 	}
 	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();
@@ -233,11 +240,15 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	*/
 	run(input) {
 		this.threadId = input.threadId;
-		this.runId = input.runId;
-		return defer(() => this.requestJoinCredentials$("run", input)).pipe(switchMap((credentials) => this.observeThread$(input, credentials, {
-			completeOnRunError: false,
-			streamMode: "run"
-		})));
+		this.canonicalRunId = input.runId;
+		return defer(() => this.requestJoinCredentials$("run", input)).pipe(switchMap((credentials) => {
+			if (credentials === null) return 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
@@ -245,21 +256,15 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	*/
 	connect(input) {
 		this.threadId = input.threadId;
-		this.runId = input.runId;
-		return defer(() => this.requestConnectPlan$(input)).pipe(switchMap((plan) => {
-			if (plan === null) return EMPTY;
-			if (plan.mode === "bootstrap") {
-				this.setLastSeenEventId(input.threadId, plan.latestEventId);
-				for (const event of plan.events) this.updateRunIdFromEvent(event);
-				return from(plan.events);
-			}
-			this.setLastSeenEventId(input.threadId, plan.joinFromEventId);
-			for (const event of plan.events) this.updateRunIdFromEvent(event);
-			return concat(from(plan.events), this.observeThread$(input, { joinToken: plan.joinToken }, {
-				completeOnRunError: true,
-				streamMode: "connect",
-				replayCursor: plan.joinFromEventId
-			}));
+		this.canonicalRunId = null;
+		this.clearReconnectCursor(input.threadId);
+		return defer(() => this.requestJoinCredentials$("connect", input)).pipe(switchMap((credentials) => {
+			if (credentials === null) return EMPTY;
+			const canonicalInput = this.applyCanonicalRunIdentity(input, credentials, { fallbackToInputRunId: false });
+			return this.observeThread$(canonicalInput, credentials, {
+				completeOnRunError: false,
+				streamMode: "connect"
+			});
 		}));
 	}
 	/**
@@ -276,8 +281,7 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 			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);
@@ -298,80 +302,56 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 						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 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?.mode === "bootstrap") return {
-			mode: "bootstrap",
-			latestEventId: typeof envelope.latestEventId === "string" ? envelope.latestEventId : null,
-			events: Array.isArray(envelope.events) ? envelope.events : []
+		const realtime = envelope?.realtime && typeof envelope.realtime === "object" ? envelope.realtime : null;
+		if (typeof envelope?.joinToken !== "string" || !envelope.joinToken) throw new Error("missing joinToken");
+		if (typeof 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?.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(catchError((error) => {
+			if (!this.isSocketReconnectExhaustedError(error)) return throwError(() => error);
+			return this.requestJoinCredentials$("connect", input).pipe(switchMap((refreshedCredentials) => refreshedCredentials === null ? EMPTY : this.observeThread$(this.applyCanonicalRunIdentity(input, refreshedCredentials, { fallbackToInputRunId: options.streamMode === "run" }), refreshedCredentials, {
+				...options,
+				channelMode: "connect",
+				replayCursor: this.getReconnectCursor(input)
+			})));
+		}));
+	}
+	observeThreadSession$(input, credentials, options) {
 		return defer(() => {
 			let ownSocket = null;
 			let ownChannel = null;
 			const socket$ = ɵphoenixSocket$({
-				url: this.config.url,
+				url: credentials.realtime.clientUrl,
 				options: {
 					params: {
 						...this.config.socketParams,
@@ -387,10 +367,10 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 				bufferSize: 1,
 				refCount: true
 			}));
-			const { topic, params } = this.createThreadChannelDescriptor(input, options.streamMode, options.replayCursor);
+			const params = this.createThreadChannelParams(input, options.channelMode ?? options.streamMode, options.replayCursor);
 			const channel$ = ɵphoenixChannel$({
 				socket$,
-				topic,
+				topic: credentials.realtime.topic,
 				params
 			}).pipe(tap(({ channel }) => {
 				ownChannel = channel;
@@ -400,8 +380,14 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 				refCount: true
 			}));
 			const threadEvents$ = this.observeThreadEvents$(input.threadId, channel$, options).pipe(share());
-			const threadCompleted$ = threadEvents$.pipe(ignoreElements(), endWith(null), take(1));
-			return merge(this.joinThreadChannel$(channel$), this.observeSocketHealth$(socket$).pipe(takeUntil(threadCompleted$)), threadEvents$).pipe(finalize(() => this.cleanupOwned(ownChannel, ownSocket)));
+			const replayComplete$ = this.observeControlEvent$(input.threadId, channel$, REPLAY_COMPLETE_EVENT).pipe(ignoreElements(), share());
+			const streamIdle$ = this.observeControlEvent$(input.threadId, channel$, STREAM_IDLE_EVENT).pipe(shareReplay({
+				bufferSize: 1,
+				refCount: true
+			}));
+			const streamIdleCompletion$ = options.streamMode === "connect" ? streamIdle$.pipe(take(1)) : EMPTY;
+			const terminal$ = merge(threadEvents$.pipe(ignoreElements(), endWith(null), take(1)), streamIdleCompletion$);
+			return merge(this.joinThreadChannel$(channel$), this.observeSocketHealth$(socket$).pipe(takeUntil(terminal$)), threadEvents$.pipe(takeUntil(streamIdleCompletion$)), replayComplete$.pipe(takeUntil(terminal$)), streamIdleCompletion$.pipe(ignoreElements())).pipe(finalize(() => this.cleanupOwned(ownChannel, ownSocket)));
 		});
 	}
 	joinThreadChannel$(channel$) {
@@ -413,17 +399,23 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	observeThreadEvents$(threadId, channel$, options) {
 		return channel$.pipe(switchMap$1(({ channel }) => this.observeChannelEvent$(channel, CLIENT_AG_UI_EVENT)), tap((payload) => {
 			this.updateLastSeenEventId(threadId, payload);
-			this.updateRunIdFromEvent(payload);
-		}), mergeMap((payload) => from(this.createThreadNotifications(payload, options.completeOnRunError))), dematerialize());
+		}), mergeMap((payload) => this.createThreadNotifications(payload, {
+			completeOnRunError: options.completeOnRunError,
+			completeOnRunFinished: options.streamMode === "run",
+			errorOnRunError: options.streamMode === "run"
+		})), dematerialize());
+	}
+	observeControlEvent$(threadId, channel$, eventName) {
+		return channel$.pipe(switchMap$1(({ channel }) => this.observeChannelEvent$(channel, eventName)), tap((payload) => this.updateLastSeenEventIdFromControl(threadId, payload)));
 	}
 	observeChannelEvent$(channel, eventName) {
 		return ɵobservePhoenixEvent$(channel, eventName);
 	}
-	createThreadNotifications(payload, completeOnRunError) {
-		if (payload.type === EventType.RUN_FINISHED) return [Notification.createNext(payload), Notification.createComplete()];
+	createThreadNotifications(payload, options) {
+		if (payload.type === EventType.RUN_FINISHED) return options.completeOnRunFinished ? [Notification.createNext(payload), Notification.createComplete()] : [Notification.createNext(payload)];
 		if (payload.type === EventType.RUN_ERROR) {
 			const errorMessage = payload.message ?? "Run error";
-			return completeOnRunError ? [Notification.createNext(payload), Notification.createComplete()] : [Notification.createNext(payload), Notification.createError(new Error(errorMessage))];
+			return options.completeOnRunError ? [Notification.createNext(payload), Notification.createComplete()] : options.errorOnRunError ? [Notification.createNext(payload), Notification.createError(new Error(errorMessage))] : [Notification.createNext(payload)];
 		}
 		return [Notification.createNext(payload)];
 	}
@@ -432,60 +424,58 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 		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) {
 		return this.sharedState.lastSeenEventIds.get(threadId) ?? 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) {
-		const record = payload;
-		const eventRunId = 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) {
+		this.threadId = credentials.threadId;
+		const runId = 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
@@ -1234,6 +1224,19 @@ var SuggestionEngine = class {
 		this.notifySuggestionsChanged(agentId, []);
 	}
 	/**
+	* Clear suggestions at the start of a run, but immediately restore static
+	* suggestions that have `available: "always"` so they remain visible
+	* throughout the run.
+	*/
+	clearSuggestionsForRun(agentId) {
+		this.clearSuggestions(agentId);
+		for (const config of Object.values(this._suggestionsConfig)) {
+			if (config.consumerAgentId !== void 0 && config.consumerAgentId !== "*" && config.consumerAgentId !== agentId) continue;
+			if (config.available !== "always") continue;
+			if (isStaticSuggestionsConfig(config)) this.addStaticSuggestions(randomUUID$1(), config, agentId);
+		}
+	}
+	/**
 	* Get current suggestions for an agent
 	*/
 	getSuggestions(agentId) {
@@ -1586,7 +1589,7 @@ var RunHandler = class {
 	* Run an agent
 	*/
 	async runAgent({ agent, forwardedProps }) {
-		if (agent.agentId) this._internal.suggestionEngine.clearSuggestions(agent.agentId);
+		if (agent.agentId) this._internal.suggestionEngine.clearSuggestionsForRun(agent.agentId);
 		if (agent instanceof HttpAgent) agent.headers = { ...this._internal.headers };
 		if (agent.detachActiveRun) await agent.detachActiveRun();
 		this._internal.subscribeAgentToStateManager(agent);
@@ -2308,8 +2311,21 @@ let CopilotKitCoreErrorCode = /* @__PURE__ */ function(CopilotKitCoreErrorCode)
 	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";
@@ -2375,6 +2391,16 @@ var CopilotKitCore = class {
 		}), "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() {
@@ -2411,17 +2437,30 @@ var CopilotKitCore = class {
 		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;
@@ -2542,6 +2581,137 @@ var CopilotKitCore = class {
 		} };
 	}
 	/**
+	* 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) {
+		const resolved = options?.throttleMs ?? this._defaultThrottleMs ?? 0;
+		let effectiveMs = 0;
+		if (!Number.isFinite(resolved) || resolved < 0) {
+			const source = 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 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) {
@@ -3088,15 +3258,18 @@ const threadDomainEvents = createActionGroup("Thread Domain", {
 	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) => {
+		const leftKey = left.lastRunAt ?? left.updatedAt ?? left.createdAt;
+		return (right.lastRunAt ?? right.updatedAt ?? 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,
@@ -3129,7 +3302,7 @@ const threadReducer = createReducer(initialThreadState, on(threadAdapterEvents.c
 	if (sessionId !== state.sessionId) return state;
 	return {
 		...state,
-		threads: sortThreadsByUpdatedAt(threads),
+		threads: sortThreadsByRecency(threads),
 		isLoading: false,
 		error: null,
 		metadataJoinCode: joinCode,