@copilotkit/core 1.76.0 → 1.77.0

package/dist/index.cjs

@@ -6,6 +6,7 @@ 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
 /**
@@ -1907,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);
@@ -2931,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
@@ -3644,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;
@@ -3679,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;
@@ -3698,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
 		};
@@ -3720,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
@@ -3744,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;
@@ -3761,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;
@@ -3799,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;
@@ -3818,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:");
 		}
@@ -3895,6 +3962,7 @@ var RunHandler = class {
 		};
 		agent.messages.push(assistantMessage);
 		let handlerResult = {
+			content: "",
 			result: "",
 			error: void 0,
 			isArgumentError: false
@@ -3911,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);
@@ -4512,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 = {
@@ -5664,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.
@@ -5678,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;
@@ -5694,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));
@@ -5845,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();
 	}
@@ -6004,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