@copilotkit/core 1.77.0 → 1.77.2

package/dist/index.umd.js

@@ -194,10 +194,17 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	*
 	* The socket is constructed and connected on subscription, and disconnected on
 	* teardown. Each subscription creates an isolated socket instance.
+	*
+	* Heartbeats default to every 15s: Phoenix's own 30s default matches common
+	* reverse-proxy WebSocket idle timeouts (e.g. Azure Application Gateway), which
+	* would drop the socket during a quiet run. Callers may override it.
 	*/
 	function ɵphoenixSocket$(options) {
 		return (0, rxjs.defer)(() => {
-			const socket = new phoenix.Socket(options.url, options.options);
+			const socket = new phoenix.Socket(options.url, {
+				heartbeatIntervalMs: 15e3,
+				...options.options
+			});
 			const signals$ = ɵcreatePhoenixSocketSignals$(socket).pipe((0, rxjs_operators.shareReplay)({
 				bufferSize: 1,
 				refCount: true
@@ -323,6 +330,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	const CONNECT_STREAM_IDLE_REPLAY_FALLBACK_MS = 100;
 	const CONNECT_IDLE_WARNING_MS = 3e4;
 	const MAX_UNOPENED_CREDENTIAL_REFRESHES = 2;
+	function isMcpResourceRead(input) {
+		const forwardedProps = input.forwardedProps;
+		const request = forwardedProps === null || forwardedProps === void 0 ? void 0 : forwardedProps.__proxiedMCPRequest;
+		return (forwardedProps === null || forwardedProps === void 0 ? void 0 : forwardedProps.__copilotkitMcpResourceReadOnly) === true && typeof request === "object" && request !== null && request.method === "resources/read";
+	}
 	var AgentThreadLockedError = class extends Error {
 		constructor(threadId) {
 			super(threadId ? `Thread ${threadId} is locked` : "Thread is locked");
@@ -430,10 +442,22 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* server-pushed AG-UI events to the Observable subscriber.
 		*/
 		run(input) {
-			this.threadId = input.threadId;
-			this.canonicalRunId = input.runId;
+			if (!isMcpResourceRead(input)) {
+				this.threadId = input.threadId;
+				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"));
+				if ("kind" in credentials) return (0, rxjs.of)({
+					type: _ag_ui_client.EventType.RUN_STARTED,
+					threadId: credentials.threadId,
+					runId: credentials.runId
+				}, {
+					type: _ag_ui_client.EventType.RUN_FINISHED,
+					threadId: credentials.threadId,
+					runId: credentials.runId,
+					result: credentials.result
+				});
 				const canonicalInput = this.applyCanonicalRunIdentity(input, credentials, { fallbackToInputRunId: true });
 				return this.observeThread$(canonicalInput, credentials, {
 					completeOnRunError: false,
@@ -527,7 +551,18 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 						const text = await response.text().catch(() => "");
 						throw new Error(text || response.statusText || String(response.status));
 					}
-					return this.normalizeJoinCredentials(await response.json(), input);
+					const payload = await response.json();
+					if (mode === "run" && isMcpResourceRead(input) && typeof payload === "object" && payload !== null && payload.kind === "mcp-resource-read") {
+						const resource = payload;
+						if (typeof resource.threadId !== "string" || !resource.threadId || typeof resource.runId !== "string" || !resource.runId) throw new Error("invalid MCP resource response identity");
+						return {
+							kind: "mcp-resource-read",
+							threadId: resource.threadId,
+							runId: resource.runId,
+							result: resource.result
+						};
+					}
+					return this.normalizeJoinCredentials(payload, 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 });
@@ -1268,6 +1303,22 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			}
 			return cloned;
 		}
+		/** Run presentation-only MCP reads on a separate client agent so their
+		* lifecycle cannot replace an in-flight approval's detach/completion state. */
+		async ɵrunMcpResourceRead(parameters) {
+			var _parameters$forwarded;
+			const request = (_parameters$forwarded = parameters.forwardedProps) === null || _parameters$forwarded === void 0 ? void 0 : _parameters$forwarded.__proxiedMCPRequest;
+			if (typeof request !== "object" || request === null || request.method !== "resources/read") throw new Error("Only MCP resources/read can use the read-only path");
+			await this.ensureRuntimeConfiguration();
+			const resourceParameters = {
+				...parameters,
+				forwardedProps: {
+					...parameters.forwardedProps,
+					__copilotkitMcpResourceReadOnly: true
+				}
+			};
+			return this.runtimeMode === _copilotkit_shared.RUNTIME_MODE_INTELLIGENCE ? this.clone().runAgent(resourceParameters) : this.runAgent(resourceParameters);
+		}
 		/**
 		* Drop the delegate's cached `lastSeenEventId` for this thread so
 		* the next connect requests a full historical replay from the
@@ -3571,7 +3622,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				this.processAgentResult({
 					runAgentResult,
 					agent,
-					toolExecutionMode: "human-in-the-loop",
+					toolExecutionMode: "restore",
 					signal: controller.signal
 				}).catch(async (error) => {
 					await this._internal.emitError({
@@ -3709,11 +3760,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			const threadId = agent.threadId;
 			const executing = (_this$_executingToolC = this._executingToolCalls.get(agent)) !== null && _this$_executingToolC !== void 0 ? _this$_executingToolC : /* @__PURE__ */ new Set();
 			this._executingToolCalls.set(agent, executing);
-			if (toolExecutionMode === "human-in-the-loop" && agent.messages.some((message) => {
+			if (toolExecutionMode === "restore" && agent.messages.some((message) => {
 				var _message$toolCalls;
 				return message.role === "assistant" && ((_message$toolCalls = message.toolCalls) === null || _message$toolCalls === void 0 ? void 0 : _message$toolCalls.some((call) => executing.has(JSON.stringify([threadId, call.id])) && !agent.messages.some((result) => result.role === "tool" && result.toolCallId === call.id && !this.isFrontendPlaceholderResult(result))));
 			})) return runAgentResult;
-			const messagesToProcess = toolExecutionMode === "human-in-the-loop" ? [...agent.messages] : newMessages;
+			const messagesToProcess = toolExecutionMode === "restore" ? [...agent.messages] : newMessages;
 			for (const message of messagesToProcess) if (message.role === "assistant") for (const toolCall of message.toolCalls || []) {
 				var _agent$messages$find;
 				const tool = this.getTool({
@@ -3730,7 +3781,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					return wildcardTool;
 				};
 				const executableTool = tool !== null && tool !== void 0 ? tool : getWildcardTool();
-				if (toolExecutionMode === "human-in-the-loop" && ((executableTool === null || executableTool === void 0 ? void 0 : executableTool.type) !== "human-in-the-loop" || !executableTool.handler)) continue;
+				if (toolExecutionMode === "restore" && (!(executableTool === null || executableTool === void 0 ? void 0 : executableTool.handler) || executableTool.type !== "human-in-the-loop" && executableTool.reconnectBehavior !== "resume-pending")) continue;
 				const executionKey = JSON.stringify([threadId, toolCall.id]);
 				if ((signal === null || signal === void 0 ? void 0 : signal.aborted) || agent.threadId !== threadId || executing.has(executionKey)) continue;
 				const existingResultIndex = newMessages.findIndex((m) => m.role === "tool" && m.toolCallId === toolCall.id);
@@ -3762,14 +3813,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 						if (signal === null || signal === void 0 ? void 0 : signal.aborted) abortInteraction();
 					}
 					const executionSignal = (_interactionControlle = interactionController === null || interactionController === void 0 ? void 0 : interactionController.signal) !== null && _interactionControlle !== void 0 ? _interactionControlle : signal;
-					const discardOnAbort = toolExecutionMode === "human-in-the-loop" || !!interactionController;
+					const discardOnAbort = toolExecutionMode === "restore" || !!interactionController;
 					try {
 						if (tool) {
-							if (await this.executeSpecificTool(tool, toolCall, message, agent, agentId, executionSignal, discardOnAbort)) needsFollowUp = true;
+							if (await this.executeSpecificTool(tool, toolCall, message, agent, agentId, executionSignal, discardOnAbort, toolExecutionMode === "restore")) needsFollowUp = true;
 						} else {
 							const fallbackTool = getWildcardTool();
 							if (fallbackTool) {
-								if (await this.executeWildcardTool(fallbackTool, toolCall, message, agent, agentId, executionSignal, discardOnAbort)) needsFollowUp = true;
+								if (await this.executeWildcardTool(fallbackTool, toolCall, message, agent, agentId, executionSignal, discardOnAbort, toolExecutionMode === "restore")) needsFollowUp = true;
 							}
 						}
 					} finally {
@@ -3806,7 +3857,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId, signal = (() => {
 			var _this$_runAbortContro3;
 			return (_this$_runAbortContro3 = this._runAbortController) === null || _this$_runAbortContro3 === void 0 ? void 0 : _this$_runAbortContro3.signal;
-		})(), discardOnAbort = false }) {
+		})(), discardOnAbort = false, isReplay = false }) {
 			let toolCallResult = "";
 			let toolCallText = "";
 			let errorMessage;
@@ -3845,7 +3896,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				const result = await tool.handler(parsedArgs, {
 					toolCall,
 					agent,
-					signal
+					signal,
+					...isReplay ? { isReplay } : {}
 				});
 				({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 			} catch (error) {
@@ -3886,7 +3938,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		/**
 		* Execute a specific tool
 		*/
-		async executeSpecificTool(tool, toolCall, message, agent, agentId, signal, discardOnAbort = false) {
+		async executeSpecificTool(tool, toolCall, message, agent, agentId, signal, discardOnAbort = false, isReplay = false) {
 			const threadId = agent.threadId;
 			if ((tool === null || tool === void 0 ? void 0 : tool.agentId) && tool.agentId !== agent.agentId) return false;
 			let handlerResult = {
@@ -3904,7 +3956,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				toolType: "specific",
 				messageId: message.id,
 				signal,
-				discardOnAbort
+				discardOnAbort,
+				isReplay
 			});
 			{
 				var _agent$messages$inser;
@@ -3929,7 +3982,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* specific tools, so this method keeps its own arg-wrapping logic rather than
 		* delegating to `executeToolHandler`.
 		*/
-		async executeWildcardTool(wildcardTool, toolCall, message, agent, agentId, signal, discardOnAbort = false) {
+		async executeWildcardTool(wildcardTool, toolCall, message, agent, agentId, signal, discardOnAbort = false, isReplay = false) {
 			const threadId = agent.threadId;
 			if ((wildcardTool === null || wildcardTool === void 0 ? void 0 : wildcardTool.agentId) && wildcardTool.agentId !== agent.agentId) return false;
 			let toolCallResult = "";
@@ -3973,7 +4026,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					const result = await wildcardTool.handler(wildcardArgs, {
 						toolCall,
 						agent,
-						signal
+						signal,
+						...isReplay ? { isReplay } : {}
 					});
 					({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 				} catch (error) {
@@ -4752,6 +4806,16 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	const MAX_EVENT_BYTES = 16 * 1024;
 	const byteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
 	const reconnectDelay = (0, _copilotkit_shared.phoenixExponentialBackoff)(1e3, 1e4);
+	const SETUP_HINTS = {
+		RUNTIME_REQUIRED: "Set runtimeUrl: capture connects through the CopilotKit runtime.",
+		INTELLIGENCE_RUNTIME_REQUIRED: "Configure the CopilotRuntime with `intelligence` to accept capture.",
+		CONNECTION_FAILED: "Check that the CopilotRuntime is configured with `intelligence` and valid Intelligence credentials, and check the runtime logs.",
+		IDENTITY_REQUIRED: "The runtime could not identify the user. Configure `identifyUser` on the CopilotRuntime and send the app's session with runtime requests.",
+		TRAJECTORIES_NOT_ENABLED: "Trajectories are not enabled for this Intelligence project.",
+		TRAJECTORIES_UNAVAILABLE: "This Intelligence deployment does not serve Trajectory capture.",
+		TRAJECTORIES_ENTITLEMENT_UNAVAILABLE: "Intelligence could not confirm that Trajectories are enabled for this project; try again later.",
+		MARKETPLACE_LICENSE_REQUIRED: "Trajectory capture requires a CopilotKit license for this project."
+	};
 	function isObject(value) {
 		return typeof value === "object" && value !== null;
 	}
@@ -4764,6 +4828,17 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	function isGrant(value) {
 		return isObject(value) && typeof value.joinToken === "string" && value.joinToken.length > 0 && isObject(value.realtime) && typeof value.realtime.clientUrl === "string" && value.realtime.clientUrl.length > 0 && typeof value.realtime.topic === "string" && value.realtime.topic.length > 0;
 	}
+	const JOIN_REFUSAL_CODES = {
+		trajectories_unavailable: "TRAJECTORIES_UNAVAILABLE",
+		trajectories_not_enabled: "TRAJECTORIES_NOT_ENABLED",
+		entitlement_unavailable: "TRAJECTORIES_ENTITLEMENT_UNAVAILABLE",
+		marketplace_license_required: "MARKETPLACE_LICENSE_REQUIRED"
+	};
+	function joinErrorCode(value) {
+		const reason = isObject(value) ? value.reason : void 0;
+		const code = typeof reason === "string" && Object.hasOwn(JOIN_REFUSAL_CODES, reason) ? JOIN_REFUSAL_CODES[reason] : void 0;
+		return code !== null && code !== void 0 ? code : errorCode(value, "JOIN_FAILED");
+	}
 	function errorCode(value, fallback) {
 		return isObject(value) && typeof value.code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(value.code) ? value.code : fallback;
 	}
@@ -4773,6 +4848,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			this.core = core;
 			this.onChange = onChange;
 			_defineProperty(this, "session", void 0);
+			_defineProperty(this, "warned", /* @__PURE__ */ new Set());
 			_defineProperty(this, "nextSeq", Math.floor(Date.now()) * 1e3);
 		}
 		get trajectoryId() {
@@ -4813,9 +4889,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 						session.retry = void 0;
 						this.connect(session);
 					}
-				}
+				},
+				linkedThreads: /* @__PURE__ */ new Set(),
+				agentWatches: /* @__PURE__ */ new Map()
 			};
 			this.session = session;
+			session.runWatch = this.core.subscribe({ onAgentRunStarted: ({ agent }) => this.watchAgent(session, agent) });
 			if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
 				window.addEventListener("offline", session.onOffline);
 				window.addEventListener("online", session.onOnline);
@@ -4844,6 +4923,29 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			if (session === null || session === void 0 ? void 0 : session.ready) (_session$collector = session.collector) === null || _session$collector === void 0 || _session$collector.emit(name, value);
 			else if (session === null || session === void 0 ? void 0 : session.started) this.addDropped(session, 1, false);
 		}
+		watchAgent(session, agent) {
+			if (this.session !== session || session.agentWatches.has(agent)) return;
+			session.agentWatches.set(agent, agent.subscribe({ onRunStartedEvent: ({ event }) => this.linkThread(session, event) }));
+		}
+		/** Sends one `thread.linked` per Thread. A link that cannot be sent waits for the next run. */
+		linkThread(session, { threadId }) {
+			const connection = session.connection;
+			if (!session.ready || !connection || !threadId || session.linkedThreads.has(threadId)) return;
+			session.linkedThreads.add(threadId);
+			const event = {
+				type: "CUSTOM",
+				name: "thread.linked",
+				timestamp: Date.now(),
+				value: { threadId }
+			};
+			try {
+				const { beforeSend } = session.config;
+				const kept = beforeSend === void 0 ? event : beforeSend(event);
+				if (kept !== null) this.send(session, connection, kept);
+			} catch (_unused) {
+				this.report(session, "INVALID_EVENT");
+			}
+		}
 		report(session, code) {
 			try {
 				var _session$config$onErr, _session$config;
@@ -4851,16 +4953,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					code,
 					message: `Trajectory capture: ${code}.`
 				});
-			} catch (_unused) {}
+			} catch (_unused2) {}
 		}
 		current(session, connection) {
 			return this.session === session && session.connection === connection;
 		}
 		end(session, result) {
-			var _session$collector2;
+			var _session$runWatch, _session$collector2;
 			if (this.session !== session) return;
 			this.session = void 0;
 			clearTimeout(session.retry);
+			(_session$runWatch = session.runWatch) === null || _session$runWatch === void 0 || _session$runWatch.unsubscribe();
+			for (const watch of session.agentWatches.values()) watch.unsubscribe();
+			session.agentWatches.clear();
 			(_session$collector2 = session.collector) === null || _session$collector2 === void 0 || _session$collector2.stop();
 			session.ready = false;
 			if (session.queue.length > 0) this.report(session, "EVENTS_DROPPED");
@@ -4876,9 +4981,23 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				window.removeEventListener("offline", session.onOffline);
 				window.removeEventListener("online", session.onOnline);
 			}
+			if (result.status === "error" && result.code !== "CANCELLED") this.warnEnded(session, result.code);
 			session.resolve(result);
 			this.onChange();
 		}
+		/**
+		* Without an app handler, a capture that ends on its own would otherwise fail
+		* silently. Each outcome warns once per Core, so StrictMode replays and
+		* repeated starts against the same misconfigured Runtime stay quiet.
+		*/
+		warnEnded(session, code) {
+			if (session.config.onError !== void 0) return;
+			const summary = session.started ? `Trajectory capture stopped (${code}).` : `Trajectory capture did not start (${code}).`;
+			if (this.warned.has(summary)) return;
+			this.warned.add(summary);
+			const hint = SETUP_HINTS[code];
+			console.warn(`[CopilotKit] ${summary}${hint === void 0 ? "" : ` ${hint}`} Set learning.onError to handle capture errors in the app.`);
+		}
 		cleanup(session, connection) {
 			session.connection = void 0;
 			clearTimeout(connection.timer);
@@ -4908,6 +5027,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			});
 			session.ready = false;
 			this.discardQueue(session);
+			session.linkedThreads.clear();
 			for (const pending of connection.pending) pending.finish("PERSISTENCE_UNKNOWN");
 			if (!this.current(session, connection)) return;
 			this.cleanup(session, connection);
@@ -5023,11 +5143,11 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 							trajectoryId: session.trajectoryId
 						});
 						this.onChange();
-					} catch (_unused2) {
+					} catch (_unused3) {
 						this.fail(session, connection, "CAPTURE_FAILED", false);
 					}
-				}).receive("error", (joinError) => this.fail(session, connection, errorCode(joinError, "JOIN_FAILED"))).receive("timeout", () => this.fail(session, connection, "CONNECTION_TIMEOUT"));
-			} catch (_unused3) {
+				}).receive("error", (joinError) => this.fail(session, connection, joinErrorCode(joinError))).receive("timeout", () => this.fail(session, connection, "CONNECTION_TIMEOUT"));
+			} catch (_unused4) {
 				this.fail(session, connection, "CONNECTION_FAILED");
 			}
 		}
@@ -5157,7 +5277,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					].includes(reason);
 					pending.finish(rollback ? reason.toUpperCase() : "PERSISTENCE_UNKNOWN", rollback);
 				}).receive("timeout", () => pending.finish("PERSISTENCE_UNKNOWN"));
-			} catch (_unused4) {
+			} catch (_unused5) {
 				pending.finish("PERSISTENCE_UNKNOWN");
 			}
 		}