@copilotkit/core 1.75.2 → 1.77.0

package/dist/index.cjs

@@ -6,7 +6,25 @@ let rxjs = require("rxjs");
 let rxjs_operators = require("rxjs/operators");
 let phoenix = require("phoenix");
 let zod_to_json_schema = require("zod-to-json-schema");
+let _copilotkit_learning = require("@copilotkit/learning");
 
+//#region src/utils/http-agent.ts
+/**
+* Whether an agent is an `HttpAgent`, including one built from another copy of
+* `@ag-ui/client` (an app that pins its own 0.x version next to CopilotKit's
+* 1.0, for example). `instanceof` is false across package copies, which made
+* CopilotKit silently skip headers and abort wiring for those agents. The
+* fallback checks the public fields CopilotKit uses, which every published
+* `HttpAgent` has.
+*/
+function ɵisHttpAgent(agent) {
+	if (agent instanceof _ag_ui_client.HttpAgent) return true;
+	if (typeof agent !== "object" || agent === null) return false;
+	const candidate = agent;
+	return typeof candidate.url === "string" && typeof candidate.headers === "object" && candidate.headers !== null && candidate.abortController instanceof AbortController && typeof candidate.runAgent === "function";
+}
+
+//#endregion
 //#region src/utils/connect-replay.ts
 /**
 * Runs an agent's `connect()` stream through the AbstractAgent apply pipeline
@@ -23,18 +41,27 @@ let zod_to_json_schema = require("zod-to-json-schema");
 *   Cannot send event type 'RUN_STARTED': The run has already errored with
 *   'RUN_ERROR'. No further events can be sent.
 *
-* `transformChunks` is still applied — message reassembly is needed either way.
+* The AG-UI 1.0 compatibility boundary still runs first, so stored 0.x history
+* is translated (THINKING_* events, `binary` parts, legacy nulls) exactly as in
+* the base pipeline. `enforceEvents` is omitted too: a replay is stored
+* history, and one event that the 1.0 schema rejects (the Intelligence gateway
+* replays RUN_STARTED without `runId`, for example) must not stop the whole
+* thread from hydrating. That keeps the leniency this path had before 1.0.
 *
 * Connection-local replay hooks track the phase before applying events. An
 * explicitly live RUN_ERROR clears busy without closing the connection;
 * historical errors remain data. Connections without hooks retain the existing
-* completion behavior. Subscriber, detach, and result contracts are preserved.
+* completion behavior.
+*
+* Apart from the above, this mirrors the base `AbstractAgent.connectAgent`
+* implementation, so callers keep the same subscriber notifications, detach
+* semantics, and `{ result, newMessages }` return shape.
 *
 * TODO: Remove this in favour of the base implementation once AG-UI's
 * AbstractAgent supports opting out of `verifyEvents` for transports whose
 * connection life-cycle isn't a single run AND preserves the connection-local
 * replay lifecycle and running-state behavior below. Skipping verification alone
-* is insufficient. As of `@ag-ui/client@0.0.57`
+* is insufficient. As of `@ag-ui/client@1.0.1`
 * `connectAgent(parameters?, subscriber?)` takes no such option.
 *
 * @param agent - The agent whose `connect()` stream should be consumed.
@@ -43,6 +70,9 @@ let zod_to_json_schema = require("zod-to-json-schema");
 */
 async function ɵconnectWithoutEventVerification(agent, parameters, subscriber, connect) {
 	const self = agent;
+	let finalizeRun = () => {
+		agent.isRunning = false;
+	};
 	try {
 		agent.isRunning = true;
 		agent.agentId = agent.agentId ?? (0, _ag_ui_client.randomUUID)();
@@ -66,12 +96,35 @@ async function ɵconnectWithoutEventVerification(agent, parameters, subscriber,
 			...agent.subscribers,
 			subscriber ?? {}
 		];
-		await self.onInitialize(input, subscribers);
-		self.activeRunDetach$ = new rxjs.Subject();
+		const activeRunDetach$ = new rxjs.Subject();
+		self.activeRunDetach$ = activeRunDetach$;
 		let resolveCompletion;
 		self.activeRunCompletionPromise = new Promise((resolve) => {
 			resolveCompletion = resolve;
 		});
+		let detached = false;
+		let finalized = false;
+		const detachSubscription = activeRunDetach$.subscribe(() => {
+			detached = true;
+		});
+		finalizeRun = () => {
+			if (finalized) return;
+			finalized = true;
+			detachSubscription.unsubscribe();
+			if (self.activeRunDetach$ === activeRunDetach$) {
+				agent.isRunning = false;
+				self.activeRunCompletionPromise = void 0;
+				self.activeRunDetach$ = void 0;
+				self.onFinalize(input, subscribers);
+			}
+			resolveCompletion?.();
+			resolveCompletion = void 0;
+		};
+		await self.onInitialize(input, subscribers);
+		if (detached) return {
+			result: void 0,
+			newMessages: []
+		};
 		const lifecycle = {
 			onReplayStarted: () => {
 				isReplaying = true;
@@ -81,29 +134,23 @@ async function ɵconnectWithoutEventVerification(agent, parameters, subscriber,
 				isReplaying = false;
 			}
 		};
-		const source$ = (0, rxjs.defer)(() => connect ? connect(input, lifecycle) : self.connect(input)).pipe((0, rxjs_operators.tap)((event) => {
+		const source$ = (0, rxjs.defer)(() => new _ag_ui_client.CompatibilityBoundary().run(input, { run: () => connect ? connect(input, lifecycle) : self.connect(input) })).pipe((0, rxjs_operators.tap)((event) => {
 			if (!isReplaying && event.type === _ag_ui_client.EventType.RUN_ERROR) liveErrors.add(event);
-		}), (0, _ag_ui_client.transformChunks)(self.debugLogger), (0, rxjs_operators.takeUntil)(self.activeRunDetach$));
+		}), (0, _ag_ui_client.transformChunks)(self.debugLogger), (0, rxjs_operators.takeUntil)(activeRunDetach$));
 		const applied$ = self.apply(input, source$, subscribers);
 		await (0, rxjs.lastValueFrom)(self.processApplyEvents(input, applied$, subscribers).pipe((0, rxjs_operators.catchError)((error) => {
+			if (self.activeRunDetach$ !== activeRunDetach$) return rxjs.EMPTY;
 			agent.isRunning = false;
 			if (error instanceof _ag_ui_client.AGUIConnectNotImplementedError) return rxjs.EMPTY;
 			return self.onError(input, error, subscribers);
-		}), (0, rxjs_operators.finalize)(() => {
-			agent.isRunning = false;
-			self.onFinalize(input, subscribers);
-			resolveCompletion?.();
-			resolveCompletion = void 0;
-			self.activeRunCompletionPromise = void 0;
-			self.activeRunDetach$ = void 0;
-		})), { defaultValue: void 0 });
+		}), (0, rxjs_operators.finalize)(() => finalizeRun())), { defaultValue: void 0 });
 		const newMessages = (0, _ag_ui_client.structuredClone_)(agent.messages).filter((m) => !previousMessageIds.has(m.id));
 		return {
 			result,
 			newMessages
 		};
 	} finally {
-		agent.isRunning = false;
+		finalizeRun();
 	}
 }
 
@@ -586,7 +633,7 @@ var IntelligenceAgent = class IntelligenceAgent extends _ag_ui_client.AbstractAg
 	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);
-		}), (0, rxjs_operators.mergeMap)((payload) => this.createThreadNotifications(payload, {
+		}), (0, rxjs_operators.map)((payload) => options.streamMode === "run" ? (0, _copilotkit_shared.stripIntelligenceRoutingFields)(payload) : payload), (0, rxjs_operators.mergeMap)((payload) => this.createThreadNotifications(payload, {
 			completeOnRunError: options.completeOnRunError,
 			completeOnRunFinished: options.streamMode === "run",
 			errorOnRunError: options.streamMode === "run"
@@ -840,6 +887,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 	_capabilities;
 	delegate;
 	runtimeInfoPromise;
+	connectionAttempt;
 	_messageFilter;
 	/**
 	* The HTTP `run` this agent started and has not yet seen finish, as the
@@ -902,13 +950,12 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		this.runtimeMode = runtimeMode;
 		this.intelligence = intelligence;
 		if (unchanged) return;
+		this.connectionAttempt = void 0;
 		this.runtimeInfoPromise = void 0;
 		const staleDelegate = this.delegate;
 		this.delegate = void 0;
-		if (staleDelegate) {
-			staleDelegate.abortRun();
-			this.detachActiveRun();
-		}
+		if (staleDelegate) staleDelegate.abortRun();
+		this.detachActiveRun();
 	}
 	/**
 	* The agent id used for outbound runtime requests — `runtimeAgentId` when
@@ -999,8 +1046,11 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		return this._capabilities ?? {};
 	}
 	async detachActiveRun() {
-		if (this.delegate) await this.delegate.detachActiveRun();
-		await super.detachActiveRun();
+		this.connectionAttempt = void 0;
+		this.isRunning = false;
+		const delegateDetach = this.delegate?.detachActiveRun();
+		const proxyDetach = super.detachActiveRun();
+		await Promise.all([delegateDetach, proxyDetach]);
 	}
 	abortRun() {
 		if (this.delegate) {
@@ -1054,41 +1104,74 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		});
 	}
 	async connectAgent(parameters, subscriber) {
+		const detached = this.detachActiveRun();
+		const connection = {};
+		const threadId = this.threadId;
+		this.connectionAttempt = connection;
+		const isCurrentConnection = () => this.connectionAttempt === connection && this.threadId === threadId;
+		await detached;
+		if (!isCurrentConnection()) return {
+			result: void 0,
+			newMessages: []
+		};
+		await this.ensureRuntimeConfiguration();
+		if (!isCurrentConnection()) return {
+			result: void 0,
+			newMessages: []
+		};
 		if (this.runtimeMode !== _copilotkit_shared.RUNTIME_MODE_INTELLIGENCE) return ɵconnectWithoutEventVerification(this, parameters, subscriber, (input, lifecycle) => this.connect(input, lifecycle));
-		if (this.delegate) await this.delegate.detachActiveRun();
 		await this.resolveDelegate();
+		if (!isCurrentConnection()) return {
+			result: void 0,
+			newMessages: []
+		};
 		const delegate = this.delegate;
 		const bridgeSub = delegate.subscribe({
 			onMessagesChanged: () => {
+				if (!isCurrentConnection()) return;
 				this.setMessages([...delegate.messages]);
 			},
 			onStateChanged: () => {
+				if (!isCurrentConnection()) return;
 				this.setState({ ...delegate.state });
 			},
 			onRunInitialized: () => {
+				if (!isCurrentConnection()) return;
 				this.isRunning = true;
 			},
 			onRunFinalized: () => {
+				if (!isCurrentConnection()) return;
+				this.pendingInterrupts = (0, _ag_ui_client.structuredClone_)(delegate.pendingInterrupts);
 				this.isRunning = false;
 			},
 			onRunFailed: () => {
+				if (!isCurrentConnection()) return;
 				this.isRunning = false;
 			},
 			onRunErrorEvent: () => {
+				if (!isCurrentConnection()) return;
 				this.isRunning = delegate.isRunning;
 			},
 			onRunStartedEvent: () => {
+				if (!isCurrentConnection()) return;
 				this.isRunning = delegate.isRunning;
 			}
 		});
-		const forwardedSubs = this.subscribers.map((s) => delegate.subscribe(s));
+		const forwardedSubs = [...this.subscribers, ...subscriber ? [subscriber] : []].map((subscriber) => delegate.subscribe(new Proxy(subscriber, { get(target, property, receiver) {
+			const callback = Reflect.get(target, property, receiver);
+			if (typeof callback !== "function") return callback;
+			return (...args) => isCurrentConnection() ? Reflect.apply(callback, target, args) : void 0;
+		} })));
 		try {
-			const result = await delegate.connectAgent(parameters, subscriber);
-			this.setMessages([...delegate.messages]);
-			this.setState({ ...delegate.state });
+			const result = await delegate.connectAgent(parameters);
+			if (isCurrentConnection()) {
+				this.setMessages([...delegate.messages]);
+				this.setState({ ...delegate.state });
+				this.pendingInterrupts = (0, _ag_ui_client.structuredClone_)(delegate.pendingInterrupts);
+			}
 			return result;
 		} finally {
-			this.isRunning = false;
+			if (isCurrentConnection()) this.isRunning = false;
 			bridgeSub.unsubscribe();
 			for (const sub of forwardedSubs) sub.unsubscribe();
 		}
@@ -1110,14 +1193,31 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		const input = this.#applyMessageFilter(unfiltered);
 		this.activeRun = void 0;
 		const routedId = this.routedAgentId();
+		let httpEvents;
 		if (this.transport === "single") {
 			if (!this.singleEndpointUrl) throw new Error("Single endpoint transport requires a runtimeUrl");
 			const requestInit = this.createSingleRouteRequestInit(input, "agent/connect", { agentId: routedId });
-			return withAbortErrorHandling((0, _ag_ui_client.transformHttpEventStream)((0, _ag_ui_client.runHttpRequest)(() => this.fetch(this.singleEndpointUrl, requestInit))));
+			httpEvents = (0, _ag_ui_client.runHttpRequest)(() => this.fetch(this.singleEndpointUrl, requestInit));
+		} else {
+			const connectUrl = `${this.runtimeUrl}/agent/${routedId}/connect`;
+			const connectRequestInit = this.requestInit(input);
+			httpEvents = (0, _ag_ui_client.runHttpRequest)(() => this.fetch(connectUrl, connectRequestInit));
 		}
-		const connectUrl = `${this.runtimeUrl}/agent/${routedId}/connect`;
-		const connectRequestInit = this.requestInit(input);
-		return withAbortErrorHandling((0, _ag_ui_client.transformHttpEventStream)((0, _ag_ui_client.runHttpRequest)(() => this.fetch(connectUrl, connectRequestInit))));
+		return withAbortErrorHandling((0, rxjs.defer)(() => {
+			let replayStarted = false;
+			const emptyHistory = [{
+				type: _ag_ui_client.EventType.MESSAGES_SNAPSHOT,
+				messages: []
+			}, {
+				type: _ag_ui_client.EventType.STATE_SNAPSHOT,
+				snapshot: {}
+			}];
+			return (0, _ag_ui_client.transformHttpEventStream)(httpEvents).pipe((0, rxjs_operators.concatMap)((event) => {
+				if (replayStarted) return (0, rxjs.of)(event);
+				replayStarted = true;
+				return (0, rxjs.from)([...emptyHistory, event]);
+			}), (0, rxjs_operators.concatWith)((0, rxjs.defer)(() => replayStarted ? rxjs.EMPTY : (0, rxjs.from)(emptyHistory))));
+		}));
 	}
 	#runViaDelegate(input) {
 		return (0, rxjs.defer)(() => (0, rxjs.from)(this.resolveDelegate())).pipe((0, rxjs_operators.switchMap)((delegate) => withAbortErrorHandling(delegate.run(input))));
@@ -1160,6 +1260,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		cloned.threadId = this.threadId;
 		cloned.setState(this.state);
 		cloned.setMessages(this.messages);
+		cloned.pendingInterrupts = (0, _ag_ui_client.structuredClone_)(this.pendingInterrupts);
 		if (this.delegate) {
 			const clonedDelegate = this.delegate.clone();
 			cloned.delegate = clonedDelegate;
@@ -1197,6 +1298,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		if (this.runtimeMode === _copilotkit_shared.RUNTIME_MODE_INTELLIGENCE || this.runtimeMode !== "pending" && this.transport !== "auto") return;
 		if (!this.runtimeUrl) throw new Error("Runtime URL is not set");
 		const runtimeInfoPromise = this.runtimeInfoPromise ?? this.fetchRuntimeInfo().then((runtimeInfo) => {
+			if (this.runtimeInfoPromise !== runtimeInfoPromise) return;
 			this.runtimeMode = runtimeInfo.mode ?? _copilotkit_shared.RUNTIME_MODE_SSE;
 			this.intelligence = runtimeInfo.intelligence;
 		});
@@ -1301,6 +1403,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends _ag_ui
 		delegate.debugLogger = this.debugLogger;
 		delegate.setMessages(this.messages);
 		delegate.setState(this.state);
+		delegate.pendingInterrupts = (0, _ag_ui_client.structuredClone_)(this.pendingInterrupts);
 		if (hasHeaders(delegate)) delegate.headers = { ...this.headers };
 		if (hasCredentials(delegate)) delegate.credentials = this.credentials;
 	}
@@ -1736,7 +1839,7 @@ var AgentRegistry = class {
 	* because only `HttpAgent` carries a `headers` field. See #5635.
 	*/
 	applyHeadersToAgent(agent) {
-		if (agent instanceof _ag_ui_client.HttpAgent) {
+		if (ɵisHttpAgent(agent)) {
 			if (!this.agentOwnHeaders.has(agent)) this.agentOwnHeaders.set(agent, { ...agent.headers });
 			agent.headers = {
 				...this.agentOwnHeaders.get(agent),
@@ -1805,6 +1908,10 @@ var AgentRegistry = class {
 			this.applyMessageFilterToAgent(agent);
 		});
 	}
+	/** Preserve the exact configured URL when posting to a single endpoint. */
+	get runtimeEndpointUrl() {
+		return this._runtimeEndpointUrl;
+	}
 	createRuntimeFetch() {
 		if (!this.runtimeFetch) this.runtimeFetch = (async (input, init) => {
 			const meta = () => runtimeRequestMeta(init);
@@ -2829,6 +2936,68 @@ function normalizeToolResultContent(content) {
 function isForwardedToClientPlaceholder(content) {
 	return normalizeToolResultContent(content) === FORWARDED_TO_CLIENT;
 }
+const MEDIA_PART_TYPES = new Set([
+	"image",
+	"audio",
+	"video",
+	"document"
+]);
+function isOptionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function isPartSource(value) {
+	if (!value || typeof value !== "object") return false;
+	const source = value;
+	if (typeof source.value !== "string") return false;
+	switch (source.type) {
+		case "data": return typeof source.mimeType === "string";
+		case "url": return isOptionalString(source.mimeType);
+		case "file": return isOptionalString(source.provider) && isOptionalString(source.mimeType);
+		default: return false;
+	}
+}
+/**
+* Mirrors `ContentPartSchema` from `@ag-ui/core/schemas`. The runtime parses
+* the request with that schema, and one invalid part there fails the whole run.
+* Core does not import the schema because the UMD build has no global for it.
+* A test checks this function against the schema.
+*/
+function isContentPart(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const part = value;
+	if (!isOptionalString(part.id) || part.metadata === null) return false;
+	if (part.type === "text") return typeof part.text === "string";
+	return typeof part.type === "string" && MEDIA_PART_TYPES.has(part.type) && isPartSource(part.source);
+}
+/**
+* Converts what a frontend tool handler returned into tool message content.
+* A non-empty array of AG-UI content parts passes through unchanged, so an
+* image reaches the model as media. Everything else becomes a string, as before.
+*
+* `text` is the string form, for surfaces typed as `result: string`
+* (`runTool`, `onToolExecutionEnd`). For content parts it is the JSON text they
+* received before. It is computed here, so a part that cannot be serialized
+* throws inside the caller's handler error boundary.
+*/
+function toToolResultContent(result) {
+	if (result === void 0 || result === null) return {
+		content: "",
+		text: ""
+	};
+	if (typeof result === "string") return {
+		content: result,
+		text: result
+	};
+	const text = JSON.stringify(result);
+	if (Array.isArray(result) && result.length > 0 && result.every(isContentPart)) return {
+		content: result,
+		text
+	};
+	return {
+		content: text,
+		text
+	};
+}
 
 //#endregion
 //#region src/core/tool-schema.ts
@@ -3087,6 +3256,7 @@ var RunHandler = class {
 	* inspector and intermittent "Message not found" toasts.
 	*/
 	_lastConnectedThreadIdsByAgent = /* @__PURE__ */ new Map();
+	_lastActiveThreadIdsByAgent = /* @__PURE__ */ new Map();
 	_anonymousAgentIds = /* @__PURE__ */ new WeakMap();
 	_nextAnonymousAgentId = 0;
 	/** Prevent reconnects from starting an interaction already executing locally. */
@@ -3264,7 +3434,8 @@ var RunHandler = class {
 	* Connect an agent (establish initial connection)
 	*/
 	async connectAgent({ agent }) {
-		this._connectionGenerations.set(agent, {});
+		const connection = {};
+		this._connectionGenerations.set(agent, connection);
 		const incomingThreadId = agent.threadId ?? null;
 		const previousReplay = this._interactionAbortControllers.get(agent);
 		if (previousReplay && previousReplay.threadId !== incomingThreadId) {
@@ -3274,12 +3445,19 @@ var RunHandler = class {
 		}
 		try {
 			const restoreKey = this.getConnectRestoreKey(agent);
-			const isFreshRestore = incomingThreadId !== (this._lastConnectedThreadIdsByAgent.get(restoreKey) ?? null);
-			this._lastConnectedThreadIdsByAgent.set(restoreKey, incomingThreadId);
+			const previousThreadId = this._lastActiveThreadIdsByAgent.get(restoreKey);
+			const isFreshRestore = incomingThreadId !== (previousThreadId ?? this._lastConnectedThreadIdsByAgent.get(restoreKey) ?? null);
 			await agent.detachActiveRun();
+			if (this._connectionGenerations.get(agent) !== connection || (agent.threadId ?? null) !== incomingThreadId) return {
+				result: void 0,
+				newMessages: []
+			};
+			this._lastConnectedThreadIdsByAgent.set(restoreKey, incomingThreadId);
+			this._lastActiveThreadIdsByAgent.set(restoreKey, incomingThreadId);
 			if (isFreshRestore) {
 				agent.setMessages([]);
 				agent.setState({});
+				if (previousThreadId !== void 0 && previousThreadId !== incomingThreadId) agent.pendingInterrupts = [];
 				const cursorAware = agent;
 				if (incomingThreadId) {
 					if (typeof cursorAware.clearReplayCursor === "function") cursorAware.clearReplayCursor(incomingThreadId);
@@ -3291,12 +3469,16 @@ var RunHandler = class {
 				copilotkit: this.core,
 				agent
 			}), "Subscriber onAgentRunStarted error:");
+			if (this._connectionGenerations.get(agent) !== connection || (agent.threadId ?? null) !== incomingThreadId) return {
+				result: void 0,
+				newMessages: []
+			};
 			const runAgentResult = await agent.connectAgent({
 				forwardedProps: this._internal.properties,
 				tools: this.buildFrontendTools(agent.agentId),
 				context: this._internal.getContextForAgent(agent.agentId)
 			}, this.createAgentErrorSubscriber(agent));
-			if ((agent.threadId ?? null) !== incomingThreadId) return runAgentResult;
+			if (this._connectionGenerations.get(agent) !== connection || (agent.threadId ?? null) !== incomingThreadId) return runAgentResult;
 			const controller = new AbortController();
 			const replay = this._interactionAbortControllers.get(agent) ?? {
 				threadId: incomingThreadId,
@@ -3353,6 +3535,12 @@ var RunHandler = class {
 			continuationHandoff?.cancel();
 			throw error;
 		}
+		const resumedRunId = this._internal.stateManager.getContinuationRunId(agent, {
+			threadId: agent.threadId,
+			resume,
+			forwardedProps
+		});
+		const logicalHandoff = continuationHandoff ?? (resumedRunId ? this._internal.stateManager.markNextRunAsContinuation(agent, resumedRunId) : void 0);
 		const isTopLevel = this._runDepth === 0;
 		let originalAbortRun;
 		if (isTopLevel) {
@@ -3370,18 +3558,19 @@ var RunHandler = class {
 		}
 		this._runDepth++;
 		try {
-			let logicalRunId = runId;
+			let logicalRunId = resumedRunId ?? runId;
 			const agentSubscriber = this.createAgentErrorSubscriber(agent);
 			let started = false;
 			const onRunStartedEvent = agentSubscriber.onRunStartedEvent;
 			const onRunInitialized = agentSubscriber.onRunInitialized;
 			agentSubscriber.onRunInitialized = async (params) => {
-				continuationHandoff?.bind(params.input);
+				this._lastActiveThreadIdsByAgent.set(this.getConnectRestoreKey(agent), params.input.threadId);
+				logicalHandoff?.bind(params.input);
 				return onRunInitialized?.(params);
 			};
 			agentSubscriber.onRunStartedEvent = async (params) => {
 				started = true;
-				if (!continuationHandoff) logicalRunId = params.input.runId;
+				if (!logicalHandoff) logicalRunId = params.input.runId;
 				return onRunStartedEvent?.(params);
 			};
 			const pinRunIdOnWire = runId !== void 0 && !continuationHandoff;
@@ -3396,14 +3585,14 @@ var RunHandler = class {
 				context: this._internal.getContextForAgent(agent.agentId)
 			};
 			const runAgentResult = await agent.runAgent(agentRunInput, agentSubscriber);
-			if (!started) continuationHandoff?.cancel();
+			if (!started) logicalHandoff?.cancel();
 			return await this.processAgentResult({
 				runAgentResult,
 				agent,
 				runId: logicalRunId
 			});
 		} catch (error) {
-			continuationHandoff?.cancel();
+			logicalHandoff?.cancel();
 			const runError = error instanceof Error ? error : new Error(String(error));
 			const context = {};
 			if (agent.agentId) context.agentId = agent.agentId;
@@ -3522,6 +3711,7 @@ var RunHandler = class {
 	*/
 	async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId, signal = this._runAbortController?.signal, discardOnAbort = false }) {
 		let toolCallResult = "";
+		let toolCallText = "";
 		let errorMessage;
 		let isArgumentError = false;
 		let parsedArgs;
@@ -3557,9 +3747,7 @@ var RunHandler = class {
 				agent,
 				signal
 			});
-			if (result === void 0 || result === null) toolCallResult = "";
-			else if (typeof result === "string") toolCallResult = result;
-			else toolCallResult = JSON.stringify(result);
+			({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 		} catch (error) {
 			const handlerError = error instanceof Error ? error : new Error(String(error));
 			errorMessage = handlerError.message;
@@ -3576,17 +3764,18 @@ var RunHandler = class {
 				}
 			});
 		}
-		if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
+		if (errorMessage) toolCallResult = toolCallText = `Error: ${errorMessage}`;
 		await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
 			copilotkit: this.core,
 			toolCallId: toolCall.id,
 			agentId,
 			toolName: toolCall.function.name,
-			result: errorMessage ? "" : toolCallResult,
+			result: errorMessage ? "" : toolCallText,
 			error: errorMessage
 		}), "Subscriber onToolExecutionEnd error:");
 		return {
-			result: toolCallResult,
+			content: toolCallResult,
+			result: toolCallText,
 			error: errorMessage,
 			isArgumentError
 		};
@@ -3598,6 +3787,7 @@ var RunHandler = class {
 		const threadId = agent.threadId;
 		if (tool?.agentId && tool.agentId !== agent.agentId) return false;
 		let handlerResult = {
+			content: "",
 			result: "",
 			error: void 0,
 			isArgumentError: false
@@ -3622,7 +3812,7 @@ var RunHandler = class {
 				id: (0, _copilotkit_shared.randomUUID)(),
 				role: "tool",
 				toolCallId: toolCall.id,
-				content: handlerResult.result
+				content: handlerResult.content
 			};
 			agent.messages.splice(insertAt, 0, toolMessage);
 			if (!handlerResult.error && tool?.followUp !== false) return true;
@@ -3639,6 +3829,7 @@ var RunHandler = class {
 		const threadId = agent.threadId;
 		if (wildcardTool?.agentId && wildcardTool.agentId !== agent.agentId) return false;
 		let toolCallResult = "";
+		let toolCallText = "";
 		let errorMessage;
 		if (wildcardTool?.handler) {
 			let parsedArgs;
@@ -3677,9 +3868,7 @@ var RunHandler = class {
 					agent,
 					signal
 				});
-				if (result === void 0 || result === null) toolCallResult = "";
-				else if (typeof result === "string") toolCallResult = result;
-				else toolCallResult = JSON.stringify(result);
+				({content: toolCallResult, text: toolCallText} = toToolResultContent(result));
 			} catch (error) {
 				const handlerError = error instanceof Error ? error : new Error(String(error));
 				errorMessage = handlerError.message;
@@ -3696,13 +3885,13 @@ var RunHandler = class {
 					}
 				});
 			}
-			if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
+			if (errorMessage) toolCallResult = toolCallText = `Error: ${errorMessage}`;
 			await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
 				copilotkit: this.core,
 				toolCallId: toolCall.id,
 				agentId,
 				toolName: toolCall.function.name,
-				result: errorMessage ? "" : toolCallResult,
+				result: errorMessage ? "" : toolCallText,
 				error: errorMessage
 			}), "Subscriber onToolExecutionEnd error:");
 		}
@@ -3773,6 +3962,7 @@ var RunHandler = class {
 		};
 		agent.messages.push(assistantMessage);
 		let handlerResult = {
+			content: "",
 			result: "",
 			error: void 0,
 			isArgumentError: false
@@ -3789,7 +3979,7 @@ var RunHandler = class {
 			id: (0, _copilotkit_shared.randomUUID)(),
 			role: "tool",
 			toolCallId,
-			content: handlerResult.result
+			content: handlerResult.content
 		};
 		const assistantIndex = agent.messages.findIndex((m) => m.id === assistantMessage.id);
 		if (assistantIndex !== -1) agent.messages.splice(assistantIndex + 1, 0, toolResultMessage);
@@ -3945,6 +4135,15 @@ var StateManager = class {
 	activeRun = /* @__PURE__ */ new Map();
 	agentSubscriptions = /* @__PURE__ */ new Map();
 	pendingContinuations = /* @__PURE__ */ new WeakMap();
+	interruptedRuns = /* @__PURE__ */ new WeakMap();
+	/** Find the interrupted logical run without consuming its pending answers. */
+	getContinuationRunId(agent, input) {
+		const pending = this.interruptedRuns.get(agent)?.get(input.threadId);
+		if (!pending) return void 0;
+		if (pending.interruptIds === null) return input.resume === void 0 && isContinuation(input) ? pending.runId : void 0;
+		const submitted = new Set(input.resume?.map((entry) => entry.interruptId));
+		return submitted.size > 0 && submitted.size === input.resume?.length && submitted.size === pending.interruptIds.length && pending.interruptIds.every((id) => submitted.has(id)) ? pending.runId : void 0;
+	}
 	constructor(core) {
 		this.core = core;
 	}
@@ -3988,6 +4187,7 @@ var StateManager = class {
 		}
 		let revoked = false;
 		let subRunId;
+		let legacyInterrupted = false;
 		let runFinished = false;
 		const pendingResults = /* @__PURE__ */ new WeakMap();
 		const reconcilePendingResults = (historyMessages, input) => {
@@ -4053,21 +4253,43 @@ var StateManager = class {
 				if (revoked) return;
 				const internalContinuation = [...this.pendingContinuations.get(agent) ?? []].find((pending) => pending.expectedInput === input);
 				internalContinuation?.cancel();
+				const startedInput = event.input ?? {
+					...input,
+					threadId: event.threadId
+				};
+				const resumedRunId = this.getContinuationRunId(agent, startedInput);
+				this.interruptedRuns.get(agent)?.delete(startedInput.threadId);
+				legacyInterrupted = false;
 				if (internalContinuation) subRunId = internalContinuation.expectedRunId ?? event.runId ?? input.runId;
+				else if (resumedRunId) subRunId = resumedRunId;
 				else if (runFinished && input.runId === subRunId && !isContinuation(input) && (event.runId == null || event.runId === subRunId)) subRunId = (0, _ag_ui_client.randomUUID)();
 				else subRunId = event.runId || input.runId;
 				runFinished = false;
 				this.handleRunStarted(agent, effectiveInput(input), state);
 			},
-			onRunFinishedEvent: ({ input, state, messages }) => {
+			onRunFinishedEvent: ({ event, input, state, messages }) => {
 				if (revoked) return;
 				runFinished = true;
 				const effective = effectiveInput(input);
+				let interrupted = this.interruptedRuns.get(agent);
+				if (event.outcome?.type === "interrupt" || legacyInterrupted) {
+					if (!interrupted) {
+						interrupted = /* @__PURE__ */ new Map();
+						this.interruptedRuns.set(agent, interrupted);
+					}
+					interrupted.set(event.threadId, {
+						runId: effective.runId,
+						interruptIds: event.outcome?.type === "interrupt" ? event.outcome.interrupts.map((interrupt) => interrupt.id) : null
+					});
+				} else interrupted?.delete(event.threadId);
 				const mutation = reconcilePendingResults(messages, input);
 				clearPendingResults(input);
 				this.handleRunFinished(agent, effective, state);
 				return mutation;
 			},
+			onCustomEvent: ({ event }) => {
+				if (!revoked && event.name === "on_interrupt") legacyInterrupted = true;
+			},
 			onRunErrorEvent: ({ input, state, messages }) => {
 				if (revoked) return;
 				runFinished = true;
@@ -4124,6 +4346,7 @@ var StateManager = class {
 			unsubscribe: () => {
 				revoked = true;
 				this.pendingContinuations.delete(agent);
+				this.interruptedRuns.delete(agent);
 				unsubscribe();
 			}
 		});
@@ -4284,6 +4507,8 @@ var StateManager = class {
 	* Clear all state for an agent
 	*/
 	clearAgentState(agentId) {
+		const agent = this.agentSubscriptions.get(agentId)?.agent;
+		if (agent) this.interruptedRuns.delete(agent);
 		this.stateByRun.delete(agentId);
 		this.messageToRun.delete(agentId);
 		this.rawEventByMessage.delete(agentId);
@@ -4292,6 +4517,8 @@ var StateManager = class {
 	* Clear all state for a thread
 	*/
 	clearThreadState(agentId, threadId) {
+		const agent = this.agentSubscriptions.get(agentId)?.agent;
+		if (agent) this.interruptedRuns.get(agent)?.delete(threadId);
 		this.stateByRun.get(agentId)?.delete(threadId);
 		this.messageToRun.get(agentId)?.delete(threadId);
 		this.rawEventByMessage.get(agentId)?.delete(threadId);
@@ -4353,6 +4580,720 @@ var ThreadStoreRegistry = class {
 	}
 };
 
+//#endregion
+//#region src/core/trajectory-connection.ts
+const TIMEOUT_MS = 1e4;
+const BATCH_INTERVAL_MS = 2e3;
+const MAX_BATCH_EVENTS = 50;
+const MAX_BATCH_BYTES = 64 * 1024;
+const MAX_EVENT_BYTES = 16 * 1024;
+const byteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+const reconnectDelay = (0, _copilotkit_shared.phoenixExponentialBackoff)(1e3, 1e4);
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function isNonNegativeInteger(value) {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function isBatchAcknowledgement(value, eventCount) {
+	return isObject(value) && isNonNegativeInteger(value.accepted) && isNonNegativeInteger(value.rejected) && value.accepted + value.rejected === eventCount && (value.highestSeq === null || isNonNegativeInteger(value.highestSeq)) && (value.accepted === 0 || value.highestSeq !== null);
+}
+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;
+}
+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;
+	nextSeq = Math.floor(Date.now()) * 1e3;
+	constructor(core, onChange) {
+		this.core = core;
+		this.onChange = onChange;
+	}
+	get trajectoryId() {
+		return this.session?.ready ? this.session.trajectoryId : null;
+	}
+	start(trajectoryId, config) {
+		if (this.session && (trajectoryId === void 0 || trajectoryId === this.session.trajectoryId)) return this.session.promise;
+		this.stop();
+		const id = trajectoryId ?? crypto.randomUUID();
+		let resolveStart;
+		const promise = new Promise((resolve) => {
+			resolveStart = resolve;
+		});
+		const session = {
+			trajectoryId: id,
+			config,
+			promise,
+			resolve: resolveStart,
+			retries: 0,
+			queue: [],
+			dropped: 0,
+			ready: false,
+			started: false,
+			offline: typeof navigator !== "undefined" && navigator.onLine === false,
+			onOffline: () => {
+				if (this.session !== session) return;
+				session.offline = true;
+				if (session.connection) this.fail(session, session.connection, "CONNECTION_LOST");
+				clearTimeout(session.retry);
+				session.retry = void 0;
+			},
+			onOnline: () => {
+				if (this.session !== session) return;
+				session.offline = false;
+				if (!session.connection) {
+					clearTimeout(session.retry);
+					session.retry = void 0;
+					this.connect(session);
+				}
+			}
+		};
+		this.session = session;
+		if (typeof window !== "undefined" && typeof window.addEventListener === "function") {
+			window.addEventListener("offline", session.onOffline);
+			window.addEventListener("online", session.onOnline);
+		}
+		if (session.offline) {
+			this.report(session, "CONNECTION_LOST");
+			this.end(session, {
+				status: "error",
+				code: "CONNECTION_LOST"
+			});
+		} else this.connect(session);
+		return promise;
+	}
+	stop() {
+		const session = this.session;
+		if (!session) return;
+		if (session.ready && session.connection) this.flush(session, session.connection);
+		this.end(session, {
+			status: "error",
+			code: "CANCELLED"
+		});
+	}
+	emit(name, value) {
+		const session = this.session;
+		if (session?.ready) session.collector?.emit(name, value);
+		else if (session?.started) this.addDropped(session, 1, false);
+	}
+	report(session, code) {
+		try {
+			session.config.onError?.({
+				code,
+				message: `Trajectory capture: ${code}.`
+			});
+		} catch {}
+	}
+	current(session, connection) {
+		return this.session === session && session.connection === connection;
+	}
+	end(session, result) {
+		if (this.session !== session) return;
+		this.session = void 0;
+		clearTimeout(session.retry);
+		session.collector?.stop();
+		session.ready = false;
+		if (session.queue.length > 0) this.report(session, "EVENTS_DROPPED");
+		this.discardQueue(session);
+		if (session.connection) {
+			for (const pending of session.connection.pending) {
+				pending.finish("PERSISTENCE_UNKNOWN");
+				this.report(session, "PERSISTENCE_UNKNOWN");
+			}
+			this.cleanup(session, session.connection);
+		}
+		if (typeof window !== "undefined" && typeof window.removeEventListener === "function") {
+			window.removeEventListener("offline", session.onOffline);
+			window.removeEventListener("online", session.onOnline);
+		}
+		session.resolve(result);
+		this.onChange();
+	}
+	cleanup(session, connection) {
+		session.connection = void 0;
+		clearTimeout(connection.timer);
+		connection.abort.abort();
+		for (const pending of connection.pending) clearTimeout(pending.timer);
+		connection.pending.clear();
+		const { socket, channel } = connection;
+		try {
+			if (channel) {
+				for (const [event, ref] of connection.channelRefs) channel.off(event, ref);
+				channel.leave();
+			}
+		} finally {
+			if (socket) {
+				socket.off(connection.socketRefs);
+				socket.disconnect();
+			}
+		}
+	}
+	fail(session, connection, code, retryable = true) {
+		if (!this.current(session, connection)) return;
+		session.collector?.stop();
+		session.collector = void 0;
+		if (session.ready && session.started) session.promise = new Promise((resolve) => {
+			session.resolve = resolve;
+		});
+		session.ready = false;
+		this.discardQueue(session);
+		for (const pending of connection.pending) pending.finish("PERSISTENCE_UNKNOWN");
+		if (!this.current(session, connection)) return;
+		this.cleanup(session, connection);
+		this.onChange();
+		this.report(session, code);
+		if (this.session !== session) return;
+		if (!session.started || !retryable) {
+			this.end(session, {
+				status: "error",
+				code
+			});
+			return;
+		}
+		if (session.offline || this.session !== session) return;
+		session.retry = setTimeout(() => {
+			session.retry = void 0;
+			if (this.session === session && !session.offline) this.connect(session);
+		}, reconnectDelay(++session.retries));
+	}
+	async connect(session) {
+		if (this.session !== session || session.offline || session.connection) return;
+		const connection = {
+			abort: new AbortController(),
+			socketRefs: [],
+			channelRefs: [],
+			pending: /* @__PURE__ */ new Set()
+		};
+		session.connection = connection;
+		connection.timer = setTimeout(() => this.fail(session, connection, "CONNECTION_TIMEOUT"), TIMEOUT_MS);
+		try {
+			const runtimeUrl = this.core.runtimeUrl;
+			if (!runtimeUrl) {
+				this.fail(session, connection, "RUNTIME_REQUIRED", false);
+				return;
+			}
+			let transport = this.core.runtimeTransport;
+			if (transport === "auto") {
+				transport = await this.detectedTransport(connection.abort.signal);
+				if (!this.current(session, connection)) return;
+			}
+			const rest = transport === "rest";
+			const response = await fetch(rest ? `${runtimeUrl}/trajectory/${encodeURIComponent(session.trajectoryId)}/connect` : this.core.ɵruntimeEndpointUrl ?? runtimeUrl, {
+				method: "POST",
+				redirect: "error",
+				signal: connection.abort.signal,
+				headers: {
+					...this.core.headers,
+					"Content-Type": "application/json"
+				},
+				credentials: this.core.credentials,
+				body: JSON.stringify(rest ? {} : {
+					method: "trajectory/connect",
+					params: { trajectoryId: session.trajectoryId },
+					body: {}
+				})
+			});
+			if (!this.current(session, connection)) return;
+			const payload = await response.json().catch(() => void 0);
+			if (!this.current(session, connection)) return;
+			if (!response.ok) {
+				this.fail(session, connection, errorCode(payload, "CONNECTION_FAILED"), response.status >= 500 || response.status === 408 || response.status === 429);
+				return;
+			}
+			if (!isGrant(payload)) {
+				this.fail(session, connection, "INVALID_GRANT", false);
+				return;
+			}
+			const socket = new phoenix.Socket(payload.realtime.clientUrl, {
+				params: { join_token: payload.joinToken },
+				timeout: TIMEOUT_MS
+			});
+			connection.socket = socket;
+			const lost = () => this.fail(session, connection, "CONNECTION_LOST");
+			connection.socketRefs.push(socket.onError(lost), socket.onClose(lost));
+			const channel = socket.channel(payload.realtime.topic, {});
+			connection.channel = channel;
+			connection.channelRefs.push(["phx_error", channel.onError(lost)], ["phx_close", channel.onClose(lost)]);
+			socket.connect();
+			if (!this.current(session, connection)) return;
+			channel.join(TIMEOUT_MS).receive("ok", () => {
+				if (!this.current(session, connection)) return;
+				try {
+					clearTimeout(connection.timer);
+					session.ready = true;
+					session.retries = 0;
+					session.collector = (0, _copilotkit_learning.createTrajectoryCollector)({
+						...session.config,
+						ignoreUrls: [
+							...session.config.ignoreUrls ?? [],
+							...this.core.runtimeUrl ? [this.core.runtimeUrl] : [],
+							...this.core.ɵruntimeEndpointUrl ? [this.core.ɵruntimeEndpointUrl] : [],
+							"https://telemetry.copilotkit.ai/",
+							"https://cdn.copilotkit.ai/"
+						],
+						onError: (error) => {
+							if (error.code === "CAPTURE_FAILED") this.fail(session, connection, error.code, false);
+							else {
+								if (error.code === "INVALID_EVENT" || error.code === "EVENT_TOO_LARGE") this.addDropped(session, 1);
+								session.config.onError?.(error);
+							}
+						},
+						send: (event) => this.send(session, connection, event)
+					});
+					session.collector.start();
+					if (!this.current(session, connection)) return;
+					if (session.dropped > 0) this.scheduleFlush(session, connection);
+					session.started = true;
+					session.resolve({
+						status: "started",
+						trajectoryId: session.trajectoryId
+					});
+					this.onChange();
+				} 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"));
+		} catch {
+			this.fail(session, connection, "CONNECTION_FAILED");
+		}
+	}
+	/** Resolves once auto-detection picks a transport, or with "auto" when the attempt is aborted. */
+	detectedTransport(signal) {
+		return new Promise((resolve) => {
+			const finish = () => {
+				subscription.unsubscribe();
+				signal.removeEventListener("abort", finish);
+				resolve(this.core.runtimeTransport);
+			};
+			const subscription = this.core.subscribe({ onRuntimeConnectionStatusChanged: () => {
+				if (this.core.runtimeTransport !== "auto") finish();
+			} });
+			signal.addEventListener("abort", finish, { once: true });
+		});
+	}
+	addDropped(session, count, schedule = true) {
+		session.dropped = Math.min(Number.MAX_SAFE_INTEGER, session.dropped + count);
+		if (schedule && count > 0 && session.ready && session.connection) this.scheduleFlush(session, session.connection);
+	}
+	scheduleFlush(session, connection) {
+		if (session.flushTimer !== void 0 || !this.current(session, connection)) return;
+		session.flushTimer = setTimeout(() => {
+			session.flushTimer = void 0;
+			this.flush(session, connection);
+		}, BATCH_INTERVAL_MS);
+	}
+	discardQueue(session) {
+		clearTimeout(session.flushTimer);
+		session.flushTimer = void 0;
+		this.addDropped(session, session.queue.length, false);
+		session.queue = [];
+	}
+	connected(connection) {
+		return connection.socket?.isConnected() === true && connection.channel?.state === "joined";
+	}
+	send(session, connection, event) {
+		if (!this.current(session, connection) || !session.ready) return;
+		if (!this.connected(connection)) {
+			this.addDropped(session, 1);
+			this.fail(session, connection, "CONNECTION_LOST");
+			return;
+		}
+		if (!Number.isSafeInteger(this.nextSeq)) {
+			this.addDropped(session, 1);
+			this.report(session, "SEQUENCE_EXHAUSTED");
+			return;
+		}
+		const original = event.value;
+		const fields = isObject(original) && !Array.isArray(original) && !Object.hasOwn(original, "seq") ? original : { data: original };
+		const wire = {
+			...event,
+			value: {
+				...fields,
+				seq: this.nextSeq++
+			}
+		};
+		if (byteLength(wire) > MAX_EVENT_BYTES) {
+			this.addDropped(session, 1);
+			this.report(session, "EVENT_TOO_LARGE");
+			return;
+		}
+		const fits = () => session.queue.length < MAX_BATCH_EVENTS && byteLength({
+			events: [...session.queue, wire],
+			dropped: Number.MAX_SAFE_INTEGER
+		}) <= MAX_BATCH_BYTES;
+		if (!fits()) this.flush(session, connection);
+		if (!this.current(session, connection) || !session.ready) return;
+		if (!fits()) {
+			this.addDropped(session, 1);
+			this.report(session, "EVENTS_DROPPED");
+			return;
+		}
+		session.queue.push(wire);
+		if (session.queue.length === MAX_BATCH_EVENTS) this.flush(session, connection);
+		else this.scheduleFlush(session, connection);
+	}
+	flush(session, connection) {
+		if (!this.current(session, connection) || !session.ready || session.queue.length === 0 && session.dropped === 0) return;
+		if (!this.connected(connection)) {
+			this.fail(session, connection, "CONNECTION_LOST");
+			return;
+		}
+		if (connection.pending.size > 0) return;
+		clearTimeout(session.flushTimer);
+		session.flushTimer = void 0;
+		const batch = {
+			events: session.queue,
+			dropped: session.dropped
+		};
+		session.queue = [];
+		session.dropped = 0;
+		let finished = false;
+		const pending = {
+			timer: setTimeout(() => pending.finish("PERSISTENCE_UNKNOWN"), TIMEOUT_MS),
+			finish: (code, knownRollback = false, flushNext = true) => {
+				if (finished) return;
+				finished = true;
+				clearTimeout(pending.timer);
+				connection.pending.delete(pending);
+				if (knownRollback) this.addDropped(session, batch.events.length + batch.dropped, false);
+				if (code && this.current(session, connection)) this.report(session, code);
+				if (flushNext && this.current(session, connection) && session.ready && (session.queue.length > 0 || !knownRollback && session.dropped > 0)) this.flush(session, connection);
+			}
+		};
+		connection.pending.add(pending);
+		try {
+			connection.channel.push("events", batch, TIMEOUT_MS).receive("ok", (payload) => {
+				pending.finish(!isBatchAcknowledgement(payload, batch.events.length) ? "PERSISTENCE_UNKNOWN" : payload.rejected > 0 ? "EVENTS_REJECTED" : void 0);
+			}).receive("error", (payload) => {
+				if (!this.current(session, connection)) return;
+				const reason = isObject(payload) ? payload.reason : void 0;
+				if (reason === "unauthorized" || reason === "trajectory_mismatch") {
+					pending.finish(void 0, true, false);
+					this.fail(session, connection, reason.toUpperCase(), false);
+					return;
+				}
+				const rollback = typeof reason === "string" && [
+					"invalid_batch",
+					"batch_too_large",
+					"batch_too_many_events",
+					"trajectory_over_share",
+					"trajectory_outbox_full",
+					"unsupported_event"
+				].includes(reason);
+				pending.finish(rollback ? reason.toUpperCase() : "PERSISTENCE_UNKNOWN", rollback);
+			}).receive("timeout", () => pending.finish("PERSISTENCE_UNKNOWN"));
+		} catch {
+			pending.finish("PERSISTENCE_UNKNOWN");
+		}
+	}
+};
+
+//#endregion
+//#region src/core/learning-bridge.ts
+const COPILOTKIT_OWN_URLS = ["https://telemetry.copilotkit.ai/", "https://cdn.copilotkit.ai/"];
+/**
+* Wires `@copilotkit/learning` into Core. Default capture uses Runtime and Phoenix;
+* explicit legacy sinks also use agent events and open-Thread attribution.
+*/
+var LearningBridge = class {
+	collector = null;
+	agents = /* @__PURE__ */ new Map();
+	openThreads = /* @__PURE__ */ new Set();
+	toolCalls = /* @__PURE__ */ new Map();
+	executingTools = /* @__PURE__ */ new Map();
+	lastRunIds = /* @__PURE__ */ new WeakMap();
+	lastLinkedThreadId = null;
+	coreSubscription = null;
+	seq = 0;
+	activeConfig;
+	connection;
+	constructor(core, config, onChange = () => {}) {
+		this.core = core;
+		this.config = config;
+		this.connection = new TrajectoryConnection(core, onChange);
+		this.setConfig(config);
+	}
+	setConfig(config) {
+		this.config = config;
+		if (config === void 0) this.stop();
+	}
+	get isConfigured() {
+		return this.config !== void 0;
+	}
+	get isLegacyCaptureActive() {
+		return this.collector !== null && this.collector.trajectoryId !== null;
+	}
+	startTracking() {
+		if (this.coreSubscription !== null || !this.isLegacyCaptureActive) return;
+		this.coreSubscription = this.core.subscribe({
+			onAgentsChanged: ({ agents }) => {
+				for (const agent of Object.values(agents)) this.track(agent);
+			},
+			onAgentRunStarted: ({ agent }) => this.track(agent),
+			onToolExecutionStart: ({ toolCallId, agentId, toolName }) => {
+				if (!this.isLegacyCaptureActive) return;
+				this.executingTools.set(toolCallId, Date.now());
+				this.emitToolCall("executing", toolCallId, agentId, toolName, {});
+			},
+			onToolExecutionEnd: ({ toolCallId, agentId, toolName, error }) => {
+				if (!this.isLegacyCaptureActive) return;
+				const startedAt = this.executingTools.get(toolCallId);
+				this.executingTools.delete(toolCallId);
+				this.emitToolCall("completed", toolCallId, agentId, toolName, {
+					durationMs: startedAt === void 0 ? void 0 : Date.now() - startedAt,
+					outcome: error === void 0 ? "ok" : "error"
+				});
+				this.toolCalls.delete(toolCallId);
+			}
+		});
+		for (const agent of Object.values(this.core.agents)) this.track(agent);
+	}
+	get trajectoryId() {
+		return this.connection.trajectoryId ?? this.collector?.trajectoryId ?? null;
+	}
+	start(options = {}) {
+		const config = this.config;
+		if (config === void 0) {
+			console.warn("[CopilotKit] startTrajectory() needs the `learning` option on CopilotKitCore (or the CopilotKitProvider `learning` prop).");
+			return Promise.resolve({
+				status: "error",
+				code: "LEARNING_DISABLED"
+			});
+		}
+		if (config.sink === void 0) {
+			if (options.learningContainerIds !== void 0) console.warn("[CopilotKit] learningContainerIds is supported only with a custom sink. Authenticated Trajectory capture does not assign Learning Containers; remove learningContainerIds from the capture options.");
+			this.stopLegacy();
+			return this.connection.start(options.trajectoryId, config);
+		}
+		this.connection.stop();
+		const trajectoryId = options.trajectoryId ?? this.collector?.trajectoryId ?? crypto.randomUUID();
+		if (this.collector === null) {
+			this.activeConfig = config;
+			const runtimeUrl = this.core.runtimeUrl;
+			this.collector = (0, _copilotkit_learning.createCollector)({
+				...config,
+				beforeSend: (event) => {
+					const sequenced = {
+						...event,
+						value: {
+							...event.value,
+							seq: ++this.seq
+						}
+					};
+					return config.beforeSend === void 0 ? sequenced : config.beforeSend(sequenced);
+				},
+				ignoreUrls: [
+					...config.ignoreUrls ?? [],
+					...COPILOTKIT_OWN_URLS,
+					...runtimeUrl === void 0 ? [] : [runtimeUrl]
+				],
+				enrich: (target) => this.enrich(target)
+			});
+		}
+		const wasActive = this.collector.trajectoryId !== null;
+		this.collector.start({
+			...options,
+			trajectoryId
+		});
+		if (wasActive) return Promise.resolve(this.collector.trajectoryId === trajectoryId ? {
+			status: "started",
+			trajectoryId
+		} : {
+			status: "error",
+			code: "TRAJECTORY_ACTIVE"
+		});
+		this.startTracking();
+		this.lastLinkedThreadId = null;
+		for (const threadId of this.distinctOpenThreadIds()) this.emitThreadLinked(threadId, "start");
+		return Promise.resolve({
+			status: "started",
+			trajectoryId
+		});
+	}
+	stop() {
+		this.connection.stop();
+		this.stopLegacy();
+	}
+	stopLegacy() {
+		this.collector?.stop();
+		this.collector = null;
+		this.activeConfig = void 0;
+		this.coreSubscription?.unsubscribe();
+		this.coreSubscription = null;
+		for (const subscription of this.agents.values()) subscription.unsubscribe();
+		this.agents.clear();
+		this.toolCalls.clear();
+		this.executingTools.clear();
+	}
+	/** A developer event. Only an explicit legacy sink adds open-Thread context. */
+	emit(name, value) {
+		this.connection.emit(name, value);
+		if (value !== null && typeof value === "object" && !Array.isArray(value)) this.collector?.emit(name, {
+			...this.openThreadContext(),
+			...value
+		});
+	}
+	registerOpenThread(params) {
+		const entry = { ...params };
+		const isNew = !this.distinctOpenThreadIds().includes(entry.threadId);
+		this.openThreads.add(entry);
+		if (isNew) this.emitThreadLinked(entry.threadId, "open");
+		return {
+			update: (threadId) => {
+				if (threadId === entry.threadId) return;
+				entry.threadId = threadId;
+				if (![...this.openThreads].filter((other) => other !== entry).some((other) => other.threadId === threadId)) this.emitThreadLinked(threadId, "switch");
+			},
+			unregister: () => {
+				this.openThreads.delete(entry);
+			}
+		};
+	}
+	distinctOpenThreadIds() {
+		return [...new Set([...this.openThreads].map((open) => open.threadId))];
+	}
+	emitThreadLinked(threadId, reason) {
+		if (!(this.collector !== null && this.collector.trajectoryId !== null) || threadId === this.lastLinkedThreadId) return;
+		this.lastLinkedThreadId = threadId;
+		const owner = [...this.openThreads].find((open) => open.threadId === threadId);
+		const agent = this.findAgentForThread(threadId);
+		this.collector?.ɵemit("thread.linked", {
+			threadId,
+			agentId: owner?.agentId ?? agent?.agentId ?? null,
+			hasMessages: (agent?.messages.length ?? 0) > 0,
+			reason
+		});
+	}
+	findAgentForThread(threadId) {
+		return [...this.agents.keys()].find((agent) => agent.threadId === threadId);
+	}
+	track(agent) {
+		const agentId = agent.agentId;
+		if (!this.isLegacyCaptureActive || this.agents.has(agent) || agentId === void 0) return;
+		this.agents.set(agent, agent.subscribe(this.agentSubscriber(agent, agentId)));
+	}
+	agentSubscriber(agent, agentId) {
+		const runIdFor = () => this.lastRunIds.get(agent);
+		return {
+			onRunStartedEvent: ({ event }) => {
+				this.lastRunIds.set(agent, event.runId);
+				this.emitRun("started", agent, event.threadId, event.runId);
+			},
+			onRunFinishedEvent: ({ event }) => {
+				this.emitRun("finished", agent, event.threadId, event.runId);
+			},
+			onRunErrorEvent: () => {
+				this.emitRun("error", agent, agent.threadId, runIdFor() ?? null);
+			},
+			onToolCallStartEvent: ({ event }) => {
+				if (!this.isLegacyCaptureActive) return;
+				const origin = {
+					agentId,
+					threadId: agent.threadId,
+					messageId: event.parentMessageId,
+					runId: runIdFor()
+				};
+				this.toolCalls.set(event.toolCallId, origin);
+				this.emitToolCall("started", event.toolCallId, origin.agentId, event.toolCallName, {});
+			},
+			onToolCallResultEvent: ({ event }) => {
+				if (!this.executingTools.has(event.toolCallId)) this.toolCalls.delete(event.toolCallId);
+			},
+			onNewMessage: ({ message }) => this.emitMessage(agent, message)
+		};
+	}
+	emitRun(phase, agent, threadId, runId) {
+		this.collector?.ɵemit("agent.run", {
+			phase,
+			runId,
+			threadId,
+			agentId: agent.agentId
+		});
+	}
+	emitMessage(agent, message) {
+		const content = typeof message.content === "string" ? message.content : "";
+		const includeText = this.activeConfig?.capture?.agentText !== false && typeof message.content === "string";
+		this.collector?.ɵemit("agent.message", {
+			messageId: message.id,
+			runId: this.runIdForMessage(agent, message.id),
+			threadId: agent.threadId,
+			agentId: agent.agentId,
+			role: message.role,
+			textLength: content.length,
+			...includeText ? { text: content } : {}
+		});
+	}
+	emitToolCall(phase, toolCallId, agentId, toolName, extra) {
+		const origin = this.toolCalls.get(toolCallId);
+		this.collector?.ɵemit("tool.call", {
+			phase,
+			toolCallId,
+			toolName,
+			agentId,
+			threadId: origin?.threadId ?? null,
+			messageId: origin?.messageId,
+			runId: origin?.runId,
+			...extra
+		});
+	}
+	runIdForMessage(agent, messageId) {
+		const agentId = agent.agentId;
+		if (agentId === void 0) return null;
+		return this.core.getRunIdForMessage(agentId, agent.threadId, messageId) ?? this.lastRunIds.get(agent) ?? null;
+	}
+	findMessage(messageId) {
+		for (const agent of this.agents.keys()) {
+			const message = agent.messages.find((candidate) => candidate.id === messageId);
+			if (message !== void 0) return {
+				agent,
+				message
+			};
+		}
+		return null;
+	}
+	toolStatus(agent, toolCallId) {
+		if (this.executingTools.has(toolCallId)) return "executing";
+		return agent.messages.some((message) => message.role === "tool" && message.toolCallId === toolCallId) ? "complete" : "inProgress";
+	}
+	/** Adds agent context to a click: exact message first, then the single open Thread. */
+	enrich(target) {
+		const messageId = target.closest("[data-message-id]")?.getAttribute("data-message-id") ?? null;
+		const toolCallId = target.closest("[data-tool-call-id]")?.getAttribute("data-tool-call-id") ?? null;
+		const found = messageId === null ? null : this.findMessage(messageId);
+		if (found !== null) {
+			const { agent, message } = found;
+			const toolCall = toolCallId !== null && message.role === "assistant" ? message.toolCalls?.find((call) => call.id === toolCallId) : void 0;
+			return {
+				threadId: agent.threadId,
+				agentId: agent.agentId,
+				messageId: message.id,
+				runId: this.runIdForMessage(agent, message.id),
+				...toolCall === void 0 ? {} : {
+					toolCallId: toolCall.id,
+					toolName: toolCall.function.name,
+					toolStatus: this.toolStatus(agent, toolCall.id)
+				}
+			};
+		}
+		return this.openThreadContext();
+	}
+	/** The single open Thread, or `null` with the candidates when several are open. */
+	openThreadContext() {
+		const openIds = this.distinctOpenThreadIds();
+		if (openIds.length > 1) return {
+			threadId: null,
+			threadAmbiguity: {
+				reason: "multiple-open",
+				candidates: openIds
+			}
+		};
+		return { threadId: openIds[0] ?? null };
+	}
+};
+
 //#endregion
 //#region src/utils/micro-redux.ts
 const INTERNAL_ACTION_TYPES = {
@@ -5505,6 +6446,9 @@ var CopilotKitCore = class {
 	runHandler;
 	stateManager;
 	threadStoreRegistry;
+	learningBridge;
+	notifiedTrajectoryId = null;
+	learningConfiguredListeners = /* @__PURE__ */ new Set();
 	/**
 	* The single core-owned memory store, created lazily on first
 	* `getMemoryStore()` and kept user-scoped for the lifetime of the core.
@@ -5519,7 +6463,7 @@ var CopilotKitCore = class {
 	* store that was registered prior to that initial notification.
 	*/
 	previousAgentIds = /* @__PURE__ */ new Set();
-	constructor({ runtimeUrl, runtimeTransport = "auto", deferInitialConnection = false, headers = {}, credentials, messageFilter, properties = {}, agents__unsafe_dev_only = {}, tools = [], suggestionsConfig = [], debug }) {
+	constructor({ runtimeUrl, runtimeTransport = "auto", deferInitialConnection = false, headers = {}, credentials, messageFilter, properties = {}, agents__unsafe_dev_only = {}, tools = [], suggestionsConfig = [], debug, learning }) {
 		this._headers = normalizeHeaders(headers);
 		this._credentials = credentials;
 		this._messageFilter = messageFilter;
@@ -5535,6 +6479,7 @@ var CopilotKitCore = class {
 		this.runHandler.initialize(tools);
 		this.suggestionEngine.initialize(suggestionsConfig);
 		this.stateManager.initialize();
+		this.learningBridge = new LearningBridge(this, learning, () => this.notifyTrajectoryChanged());
 		this.agentRegistry.setRuntimeTransport(runtimeTransport);
 		this.agentRegistry.setRuntimeUrl(runtimeUrl, { deferConnection: deferInitialConnection });
 		this.previousAgentIds = new Set(Object.keys(agents__unsafe_dev_only));
@@ -5686,6 +6631,10 @@ var CopilotKitCore = class {
 	get runtimeConnectionStatus() {
 		return this.agentRegistry.runtimeConnectionStatus;
 	}
+	/** @internal The verbatim single-endpoint URL, including any trailing slash. */
+	get ɵruntimeEndpointUrl() {
+		return this.agentRegistry.runtimeEndpointUrl;
+	}
 	get ɵruntimeFetch() {
 		return this.agentRegistry.createRuntimeFetch();
 	}
@@ -5845,6 +6794,83 @@ var CopilotKitCore = class {
 	getAgent(id) {
 		return this.agentRegistry.getAgent(id);
 	}
+	/** Updates settings for the next capture. Removing the config stops capture. */
+	setLearningConfig(config) {
+		const wasConfigured = this.ɵlearningConfigured;
+		this.learningBridge.setConfig(config);
+		this.notifyTrajectoryChanged();
+		if (this.ɵlearningConfigured === wasConfigured) return;
+		for (const listener of this.learningConfiguredListeners) try {
+			listener();
+		} catch (error) {
+			console.error("Learning configured listener error:", error);
+		}
+	}
+	/**
+	* @internal Whether a `learning` config is set. Unlike {@link trajectoryId},
+	* it does not change with capture start, connection failures or reconnects.
+	*/
+	get ɵlearningConfigured() {
+		return this.learningBridge.isConfigured;
+	}
+	/** @internal Calls `listener` when {@link ɵlearningConfigured} changes. */
+	ɵsubscribeToLearningConfigured(listener) {
+		this.learningConfiguredListeners.add(listener);
+		return () => {
+			this.learningConfiguredListeners.delete(listener);
+		};
+	}
+	/** The active capture's Trajectory ID, or null while capture is stopped. */
+	get trajectoryId() {
+		return this.learningBridge.trajectoryId;
+	}
+	notifyTrajectoryChanged() {
+		const trajectoryId = this.trajectoryId;
+		if (trajectoryId === this.notifiedTrajectoryId) return;
+		this.notifiedTrajectoryId = trajectoryId;
+		this.notifySubscribers((subscriber) => subscriber.onTrajectoryChanged?.({
+			copilotkit: this,
+			trajectoryId
+		}), "Subscriber onTrajectoryChanged error:");
+	}
+	/**
+	* Starts one Trajectory after Runtime authorization and the Gateway join.
+	* Omit the ID to create one. Repeated starts await the active connection;
+	* a different ID stops the previous capture. Explicit sinks retain the
+	* prototype's synchronous capture and require a stop before changing IDs.
+	*
+	* @example copilotkit.startTrajectory({ trajectoryId: crypto.randomUUID() })
+	*/
+	startTrajectory(options = {}) {
+		const result = this.learningBridge.start(options);
+		this.notifyTrajectoryChanged();
+		return result;
+	}
+	/** Cancels pending work and stops capture, attempting one final batch without waiting for its ACK. */
+	stopTrajectory() {
+		this.learningBridge.stop();
+		this.notifyTrajectoryChanged();
+	}
+	/**
+	* Records an outcome that clicks cannot show, such as a saved report or an
+	* approved deal. The wire adds `value.seq`; arrays, primitives, and objects
+	* already containing `seq` are preserved under `value.data`. Explicit legacy
+	* sinks retain object-only events with open-Thread enrichment.
+	* No-op while no Trajectory runs. Events emitted during connection recovery
+	* count as dropped. Built-in names such as `click` are rejected.
+	*
+	* @example copilotkit.emitTrajectoryEvent("deal.approved", { dealId: "deal-1" })
+	*/
+	emitTrajectoryEvent(name, value = {}) {
+		this.learningBridge.emit(name, value);
+	}
+	/**
+	* Tells Core that a view shows this Thread, so captured interactions can link to it.
+	* Framework bindings call this; call it yourself only without a CopilotKit provider.
+	*/
+	registerOpenThread(params) {
+		return this.learningBridge.registerOpenThread(params);
+	}
 	/**
 	* Re-apply the current headers to a single agent (delegated to
 	* AgentRegistry). Core headers are merged on top of the agent's own
@@ -7407,6 +8433,7 @@ exports.ɵcreateMemoryStore = createMemoryStore;
 exports.ɵcreateThreadSelectors = ɵcreateThreadSelectors;
 exports.ɵcreateThreadStore = createThreadStore;
 exports.ɵisCopilotKitFeature = ɵisCopilotKitFeature;
+exports.ɵisHttpAgent = ɵisHttpAgent;
 exports.ɵisRetryableMemoryStatus = isRetryableStatus;
 exports.ɵjoinPhoenixChannel$ = ɵjoinPhoenixChannel$;
 exports.ɵmapMemoryMetadataEvent = ɵmapMemoryMetadataEvent;