@copilotkit/core 1.56.2 → 1.56.3

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";
@@ -137,7 +138,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 +176,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 +219,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,7 +238,7 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	*/
 	run(input) {
 		this.threadId = input.threadId;
-		this.runId = input.runId;
+		this.canonicalRunId = input.runId;
 		return defer(() => this.requestJoinCredentials$("run", input)).pipe(switchMap((credentials) => this.observeThread$(input, credentials, {
 			completeOnRunError: false,
 			streamMode: "run"
@@ -245,16 +250,14 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	*/
 	connect(input) {
 		this.threadId = input.threadId;
-		this.runId = input.runId;
+		this.canonicalRunId = 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",
@@ -277,7 +280,7 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 			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);
@@ -413,7 +416,6 @@ 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());
 	}
 	observeChannelEvent$(channel, eventName) {
@@ -463,23 +465,6 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 		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;
@@ -2308,8 +2293,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 +2373,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 +2419,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 +2563,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 +3240,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 +3284,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,