@copilotkit/core 1.77.1 → 1.78.0

package/dist/index.mjs

@@ -4641,6 +4641,16 @@ const MAX_BATCH_BYTES = 64 * 1024;
 const MAX_EVENT_BYTES = 16 * 1024;
 const byteLength = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
 const reconnectDelay = phoenixExponentialBackoff(1e3, 1e4);
+const SETUP_HINTS = {
+	RUNTIME_REQUIRED: "Set runtimeUrl: capture connects through the CopilotKit runtime.",
+	INTELLIGENCE_RUNTIME_REQUIRED: "Configure the CopilotRuntime with `intelligence` to accept capture.",
+	CONNECTION_FAILED: "Check that the CopilotRuntime is configured with `intelligence` and valid Intelligence credentials, and check the runtime logs.",
+	IDENTITY_REQUIRED: "The runtime could not identify the user. Configure `identifyUser` on the CopilotRuntime and send the app's session with runtime requests.",
+	TRAJECTORIES_NOT_ENABLED: "Trajectories are not enabled for this Intelligence project.",
+	TRAJECTORIES_UNAVAILABLE: "This Intelligence deployment does not serve Trajectory capture.",
+	TRAJECTORIES_ENTITLEMENT_UNAVAILABLE: "Intelligence could not confirm that Trajectories are enabled for this project; try again later.",
+	MARKETPLACE_LICENSE_REQUIRED: "Trajectory capture requires a CopilotKit license for this project."
+};
 function isObject(value) {
 	return typeof value === "object" && value !== null;
 }
@@ -4653,12 +4663,23 @@ function isBatchAcknowledgement(value, eventCount) {
 function isGrant(value) {
 	return isObject(value) && typeof value.joinToken === "string" && value.joinToken.length > 0 && isObject(value.realtime) && typeof value.realtime.clientUrl === "string" && value.realtime.clientUrl.length > 0 && typeof value.realtime.topic === "string" && value.realtime.topic.length > 0;
 }
+const JOIN_REFUSAL_CODES = {
+	trajectories_unavailable: "TRAJECTORIES_UNAVAILABLE",
+	trajectories_not_enabled: "TRAJECTORIES_NOT_ENABLED",
+	entitlement_unavailable: "TRAJECTORIES_ENTITLEMENT_UNAVAILABLE",
+	marketplace_license_required: "MARKETPLACE_LICENSE_REQUIRED"
+};
+function joinErrorCode(value) {
+	const reason = isObject(value) ? value.reason : void 0;
+	return (typeof reason === "string" && Object.hasOwn(JOIN_REFUSAL_CODES, reason) ? JOIN_REFUSAL_CODES[reason] : void 0) ?? errorCode(value, "JOIN_FAILED");
+}
 function errorCode(value, fallback) {
 	return isObject(value) && typeof value.code === "string" && /^[A-Z][A-Z0-9_]{0,63}$/.test(value.code) ? value.code : fallback;
 }
 /** Owns bounded, connected-only capture batches. Failed batches are never resent. */
 var TrajectoryConnection = class {
 	session;
+	warned = /* @__PURE__ */ new Set();
 	nextSeq = Math.floor(Date.now()) * 1e3;
 	constructor(core, onChange) {
 		this.core = core;
@@ -4790,9 +4811,23 @@ var TrajectoryConnection = class {
 			window.removeEventListener("offline", session.onOffline);
 			window.removeEventListener("online", session.onOnline);
 		}
+		if (result.status === "error" && result.code !== "CANCELLED") this.warnEnded(session, result.code);
 		session.resolve(result);
 		this.onChange();
 	}
+	/**
+	* Without an app handler, a capture that ends on its own would otherwise fail
+	* silently. Each outcome warns once per Core, so StrictMode replays and
+	* repeated starts against the same misconfigured Runtime stay quiet.
+	*/
+	warnEnded(session, code) {
+		if (session.config.onError !== void 0) return;
+		const summary = session.started ? `Trajectory capture stopped (${code}).` : `Trajectory capture did not start (${code}).`;
+		if (this.warned.has(summary)) return;
+		this.warned.add(summary);
+		const hint = SETUP_HINTS[code];
+		console.warn(`[CopilotKit] ${summary}${hint === void 0 ? "" : ` ${hint}`} Set learning.onError to handle capture errors in the app.`);
+	}
 	cleanup(session, connection) {
 		session.connection = void 0;
 		clearTimeout(connection.timer);
@@ -4937,7 +4972,7 @@ var TrajectoryConnection = class {
 				} catch {
 					this.fail(session, connection, "CAPTURE_FAILED", false);
 				}
-			}).receive("error", (joinError) => this.fail(session, connection, errorCode(joinError, "JOIN_FAILED"))).receive("timeout", () => this.fail(session, connection, "CONNECTION_TIMEOUT"));
+			}).receive("error", (joinError) => this.fail(session, connection, joinErrorCode(joinError))).receive("timeout", () => this.fail(session, connection, "CONNECTION_TIMEOUT"));
 		} catch {
 			this.fail(session, connection, "CONNECTION_FAILED");
 		}