@copilotkit/core 1.56.1 → 1.56.2-canary.pin-to-send

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
@@ -180,7 +180,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 +217,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 +260,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,7 +279,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		*/
 		run(input) {
 			this.threadId = input.threadId;
-			this.runId = input.runId;
+			this.canonicalRunId = input.runId;
 			return (0, rxjs.defer)(() => this.requestJoinCredentials$("run", input)).pipe((0, rxjs.switchMap)((credentials) => this.observeThread$(input, credentials, {
 				completeOnRunError: false,
 				streamMode: "run"
@@ -287,16 +291,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		*/
 		connect(input) {
 			this.threadId = input.threadId;
-			this.runId = input.runId;
+			this.canonicalRunId = 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",
@@ -319,7 +321,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				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);
@@ -455,7 +457,6 @@ 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)());
 		}
 		observeChannelEvent$(channel, eventName) {
@@ -507,24 +508,6 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			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;
@@ -2473,8 +2456,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 +2539,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 +2585,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 +2735,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 +3415,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 +3460,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,