@copilotkit/core 1.77.0 → 1.77.2

package/dist/index.mjs

@@ -195,10 +195,17 @@ function ɵcreatePhoenixJoinOutcome$(channel) {
 *
 * 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 defer(() => {
-		const socket = new Socket(options.url, options.options);
+		const socket = new Socket(options.url, {
+			heartbeatIntervalMs: 15e3,
+			...options.options
+		});
 		const signals$ = ɵcreatePhoenixSocketSignals$(socket).pipe(shareReplay({
 			bufferSize: 1,
 			refCount: true
@@ -282,6 +289,11 @@ const STOP_RUN_EVENT = "stop_run";
 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?.__proxiedMCPRequest;
+	return 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");
@@ -389,10 +401,22 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	* 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 defer(() => this.requestJoinCredentials$("run", input)).pipe(switchMap((credentials) => {
 			if (credentials === null) return throwError(() => /* @__PURE__ */ new Error("REST run request returned no credentials"));
+			if ("kind" in credentials) return of({
+				type: EventType.RUN_STARTED,
+				threadId: credentials.threadId,
+				runId: credentials.runId
+			}, {
+				type: 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,
@@ -484,7 +508,18 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 					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 });
@@ -1267,6 +1302,21 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		}
 		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) {
+		const request = parameters.forwardedProps?.__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 === 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
@@ -3488,7 +3538,7 @@ var RunHandler = class {
 			this.processAgentResult({
 				runAgentResult,
 				agent,
-				toolExecutionMode: "human-in-the-loop",
+				toolExecutionMode: "restore",
 				signal: controller.signal
 			}).catch(async (error) => {
 				await this._internal.emitError({
@@ -3619,8 +3669,8 @@ var RunHandler = class {
 		const threadId = agent.threadId;
 		const executing = this._executingToolCalls.get(agent) ?? /* @__PURE__ */ new Set();
 		this._executingToolCalls.set(agent, executing);
-		if (toolExecutionMode === "human-in-the-loop" && agent.messages.some((message) => message.role === "assistant" && 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;
+		if (toolExecutionMode === "restore" && agent.messages.some((message) => message.role === "assistant" && 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 === "restore" ? [...agent.messages] : newMessages;
 		for (const message of messagesToProcess) if (message.role === "assistant") for (const toolCall of message.toolCalls || []) {
 			const tool = this.getTool({
 				toolName: toolCall.function.name,
@@ -3636,7 +3686,7 @@ var RunHandler = class {
 				return wildcardTool;
 			};
 			const executableTool = tool ?? getWildcardTool();
-			if (toolExecutionMode === "human-in-the-loop" && (executableTool?.type !== "human-in-the-loop" || !executableTool.handler)) continue;
+			if (toolExecutionMode === "restore" && (!executableTool?.handler || executableTool.type !== "human-in-the-loop" && executableTool.reconnectBehavior !== "resume-pending")) continue;
 			const executionKey = JSON.stringify([threadId, toolCall.id]);
 			if (signal?.aborted || agent.threadId !== threadId || executing.has(executionKey)) continue;
 			const existingResultIndex = newMessages.findIndex((m) => m.role === "tool" && m.toolCallId === toolCall.id);
@@ -3667,14 +3717,14 @@ var RunHandler = class {
 					if (signal?.aborted) abortInteraction();
 				}
 				const executionSignal = interactionController?.signal ?? 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 {
@@ -3708,7 +3758,7 @@ var RunHandler = class {
 	* Handles arg parsing, subscriber notifications, handler invocation, result stringification,
 	* and error handling.
 	*/
-	async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId, signal = this._runAbortController?.signal, discardOnAbort = false }) {
+	async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId, signal = this._runAbortController?.signal, discardOnAbort = false, isReplay = false }) {
 		let toolCallResult = "";
 		let toolCallText = "";
 		let errorMessage;
@@ -3744,7 +3794,8 @@ var RunHandler = class {
 			const result = await tool.handler(parsedArgs, {
 				toolCall,
 				agent,
-				signal
+				signal,
+				...isReplay ? { isReplay } : {}
 			});
 			({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 		} catch (error) {
@@ -3782,7 +3833,7 @@ var RunHandler = class {
 	/**
 	* 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?.agentId && tool.agentId !== agent.agentId) return false;
 		let handlerResult = {
@@ -3800,7 +3851,8 @@ var RunHandler = class {
 			toolType: "specific",
 			messageId: message.id,
 			signal,
-			discardOnAbort
+			discardOnAbort,
+			isReplay
 		});
 		{
 			const messageIndex = agent.messages.findIndex((m) => m.id === message.id);
@@ -3824,7 +3876,7 @@ var RunHandler = class {
 	* 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?.agentId && wildcardTool.agentId !== agent.agentId) return false;
 		let toolCallResult = "";
@@ -3865,7 +3917,8 @@ var RunHandler = class {
 				const result = await wildcardTool.handler(wildcardArgs, {
 					toolCall,
 					agent,
-					signal
+					signal,
+					...isReplay ? { isReplay } : {}
 				});
 				({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 			} catch (error) {
@@ -4588,6 +4641,16 @@ const MAX_BATCH_BYTES = 64 * 1024;
 const MAX_EVENT_BYTES = 16 * 1024;
 const byteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
 const reconnectDelay = 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;
 }
@@ -4600,12 +4663,23 @@ function isBatchAcknowledgement(value, eventCount) {
 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;
+	return (typeof reason === "string" && Object.hasOwn(JOIN_REFUSAL_CODES, reason) ? JOIN_REFUSAL_CODES[reason] : void 0) ?? 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;
 }
 /** Owns bounded, connected-only capture batches. Failed batches are never resent. */
 var TrajectoryConnection = class {
 	session;
+	warned = /* @__PURE__ */ new Set();
 	nextSeq = Math.floor(Date.now()) * 1e3;
 	constructor(core, onChange) {
 		this.core = core;
@@ -4648,9 +4722,12 @@ var TrajectoryConnection = class {
 					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);
@@ -4678,6 +4755,29 @@ var TrajectoryConnection = class {
 		if (session?.ready) session.collector?.emit(name, value);
 		else if (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 {
+			this.report(session, "INVALID_EVENT");
+		}
+	}
 	report(session, code) {
 		try {
 			session.config.onError?.({
@@ -4693,6 +4793,9 @@ var TrajectoryConnection = class {
 		if (this.session !== session) return;
 		this.session = void 0;
 		clearTimeout(session.retry);
+		session.runWatch?.unsubscribe();
+		for (const watch of session.agentWatches.values()) watch.unsubscribe();
+		session.agentWatches.clear();
 		session.collector?.stop();
 		session.ready = false;
 		if (session.queue.length > 0) this.report(session, "EVENTS_DROPPED");
@@ -4708,9 +4811,23 @@ var TrajectoryConnection = class {
 			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);
@@ -4739,6 +4856,7 @@ var TrajectoryConnection = class {
 		});
 		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);
@@ -4854,7 +4972,7 @@ var TrajectoryConnection = class {
 				} catch {
 					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"));
+			}).receive("error", (joinError) => this.fail(session, connection, joinErrorCode(joinError))).receive("timeout", () => this.fail(session, connection, "CONNECTION_TIMEOUT"));
 		} catch {
 			this.fail(session, connection, "CONNECTION_FAILED");
 		}