@copilotkit/core 1.57.0 → 1.57.1-canary.1778272612

package/dist/index.mjs

@@ -254,10 +254,22 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	* Reconnect to an existing thread by fetching websocket credentials and
 	* joining the realtime thread channel.
 	*/
+	/**
+	* Reconnect to an existing thread by fetching websocket credentials
+	* and joining the realtime thread channel.
+	*
+	* Note: this method does NOT clear the replay cursor. Whether to
+	* request a full historical replay vs. resume from
+	* `lastSeenEventId` is a decision the caller (typically
+	* `RunHandler.connectAgent`) makes by calling
+	* {@link clearReconnectCursor} ahead of time on a fresh thread
+	* restore. Same-thread churn re-connects preserve the cursor so the
+	* gateway only streams events past it instead of replaying the
+	* entire history every time the chat re-opens a socket.
+	*/
 	connect(input) {
 		this.threadId = input.threadId;
 		this.canonicalRunId = null;
-		this.clearReconnectCursor(input.threadId);
 		return defer(() => this.requestJoinCredentials$("connect", input)).pipe(switchMap((credentials) => {
 			if (credentials === null) return EMPTY;
 			const canonicalInput = this.applyCanonicalRunIdentity(input, credentials, { fallbackToInputRunId: false });
@@ -439,6 +451,14 @@ var IntelligenceAgent = class IntelligenceAgent extends AbstractAgent {
 	getReconnectCursor(input) {
 		return this.getLastSeenEventId(input.threadId);
 	}
+	/**
+	* Drop the cached `lastSeenEventId` cursor for `threadId` so the
+	* next connect to that topic asks the gateway for a full historical
+	* replay (rather than resuming). Public because
+	* `RunHandler.connectAgent` calls it on a detected thread switch
+	* to rebuild local state from scratch, and skips it on same-thread
+	* churn so the gateway can resume.
+	*/
 	clearReconnectCursor(threadId) {
 		this.sharedState.lastSeenEventIds.delete(threadId);
 	}
@@ -501,6 +521,7 @@ function withAbortErrorHandling(observable) {
 var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAgent {
 	runtimeUrl;
 	credentials;
+	runtimeAgentId;
 	transport;
 	singleEndpointUrl;
 	runtimeMode;
@@ -511,7 +532,8 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 	constructor(config) {
 		const normalizedRuntimeUrl = config.runtimeUrl ? config.runtimeUrl.replace(/\/$/, "") : void 0;
 		const transport = config.transport ?? "auto";
-		const runUrl = transport === "single" ? normalizedRuntimeUrl ?? config.runtimeUrl ?? "" : `${normalizedRuntimeUrl ?? config.runtimeUrl}/agent/${encodeURIComponent(config.agentId ?? "")}/run`;
+		const routedId = config.runtimeAgentId ?? config.agentId ?? "";
+		const runUrl = transport === "single" ? normalizedRuntimeUrl ?? config.runtimeUrl ?? "" : `${normalizedRuntimeUrl ?? config.runtimeUrl}/agent/${encodeURIComponent(routedId)}/run`;
 		if (!runUrl) throw new Error("ProxiedCopilotRuntimeAgent requires a runtimeUrl when transport is set to 'single'.");
 		super({
 			...config,
@@ -519,6 +541,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		});
 		this.runtimeUrl = normalizedRuntimeUrl ?? config.runtimeUrl;
 		this.credentials = config.credentials;
+		this.runtimeAgentId = config.runtimeAgentId;
 		this.transport = transport;
 		this.runtimeMode = config.runtimeMode ?? RUNTIME_MODE_SSE;
 		this.intelligence = config.intelligence;
@@ -526,6 +549,21 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		if (config.debug) this.debug = config.debug;
 		if (this.transport === "single") this.singleEndpointUrl = this.runtimeUrl;
 	}
+	/**
+	* The agent id used for outbound runtime requests — `runtimeAgentId` when
+	* set (manually-registered proxy), otherwise `agentId` (registry id
+	* matches runtime id). Subscriber bookkeeping keeps using `agentId`
+	* directly.
+	*
+	* Throws when both are unset: a proxy reaching an HTTP path with no
+	* routable id is a bug, and a missing id would otherwise produce a
+	* malformed `/agent//run` or `/agent/undefined/connect` URL silently.
+	*/
+	routedAgentId() {
+		const id = this.runtimeAgentId ?? this.agentId;
+		if (!id) throw new Error("ProxiedCopilotRuntimeAgent: cannot make a runtime request without an agentId or runtimeAgentId.");
+		return id;
+	}
 	get capabilities() {
 		return this._capabilities;
 	}
@@ -545,6 +583,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		}
 		if (!this.agentId || !this.threadId) return;
 		if (typeof fetch === "undefined") return;
+		const routedId = this.routedAgentId();
 		if (this.transport === "single") {
 			if (!this.singleEndpointUrl) return;
 			const headers = new Headers({
@@ -557,7 +596,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 				body: JSON.stringify({
 					method: "agent/stop",
 					params: {
-						agentId: this.agentId,
+						agentId: routedId,
 						threadId: this.threadId
 					}
 				}),
@@ -568,7 +607,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 			return;
 		}
 		if (!this.runtimeUrl) return;
-		const stopPath = `${this.runtimeUrl}/agent/${encodeURIComponent(this.agentId)}/stop/${encodeURIComponent(this.threadId)}`;
+		const stopPath = `${this.runtimeUrl}/agent/${encodeURIComponent(routedId)}/stop/${encodeURIComponent(this.threadId)}`;
 		const origin = typeof window !== "undefined" && window.location ? window.location.origin : "http://localhost";
 		const base = new URL(this.runtimeUrl, origin);
 		const stopUrl = new URL(stopPath, base);
@@ -632,12 +671,13 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		return defer(() => from(this.resolveDelegate())).pipe(switchMap$1((delegate) => withAbortErrorHandling(delegate.connect(input))));
 	}
 	#connectViaHttp(input) {
+		const routedId = this.routedAgentId();
 		if (this.transport === "single") {
 			if (!this.singleEndpointUrl) throw new Error("Single endpoint transport requires a runtimeUrl");
-			const requestInit = this.createSingleRouteRequestInit(input, "agent/connect", { agentId: this.agentId });
+			const requestInit = this.createSingleRouteRequestInit(input, "agent/connect", { agentId: routedId });
 			return withAbortErrorHandling(transformHttpEventStream(runHttpRequest(this.singleEndpointUrl, requestInit)));
 		}
-		return withAbortErrorHandling(transformHttpEventStream(runHttpRequest(`${this.runtimeUrl}/agent/${this.agentId}/connect`, this.requestInit(input))));
+		return withAbortErrorHandling(transformHttpEventStream(runHttpRequest(`${this.runtimeUrl}/agent/${routedId}/connect`, this.requestInit(input))));
 	}
 	#runViaDelegate(input) {
 		return defer(() => from(this.resolveDelegate())).pipe(switchMap$1((delegate) => withAbortErrorHandling(delegate.run(input))));
@@ -645,7 +685,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 	#runViaHttp(input) {
 		if (this.transport === "single") {
 			if (!this.singleEndpointUrl) throw new Error("Single endpoint transport requires a runtimeUrl");
-			const requestInit = this.createSingleRouteRequestInit(input, "agent/run", { agentId: this.agentId });
+			const requestInit = this.createSingleRouteRequestInit(input, "agent/run", { agentId: this.routedAgentId() });
 			return withAbortErrorHandling(transformHttpEventStream(runHttpRequest(this.singleEndpointUrl, requestInit)));
 		}
 		return withAbortErrorHandling(super.run(input));
@@ -654,6 +694,7 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		const cloned = new ProxiedCopilotRuntimeAgent({
 			runtimeUrl: this.runtimeUrl,
 			agentId: this.agentId,
+			runtimeAgentId: this.runtimeAgentId,
 			description: this.description,
 			headers: { ...this.headers },
 			credentials: this.credentials,
@@ -672,6 +713,22 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		}
 		return cloned;
 	}
+	/**
+	* Drop the delegate's cached `lastSeenEventId` for this thread so
+	* the next connect requests a full historical replay from the
+	* gateway. Used by `RunHandler.connectAgent` on a detected thread
+	* switch (the chat moved between threads, so its local
+	* messages/state are about to be cleared and need rebuilding from
+	* the gateway). Skipped on same-thread churn re-connects so the
+	* gateway can resume from the cursor instead.
+	*
+	* No-op for non-Intelligence runtime modes — the HTTP transport
+	* doesn't replay.
+	*/
+	clearReplayCursor(threadId) {
+		if (this.runtimeMode !== RUNTIME_MODE_INTELLIGENCE) return;
+		this.delegate?.clearReconnectCursor?.(threadId);
+	}
 	async resolveDelegate() {
 		await this.ensureRuntimeMode();
 		if (!this.delegate) {
@@ -762,17 +819,18 @@ var ProxiedCopilotRuntimeAgent = class ProxiedCopilotRuntimeAgent extends HttpAg
 		};
 	}
 	createIntelligenceDelegate() {
-		if (!this.runtimeUrl || !this.agentId || !this.intelligence?.wsUrl) throw new Error("Intelligence mode requires runtimeUrl, agentId, and intelligence websocket metadata");
+		const routedId = this.routedAgentId();
+		if (!this.runtimeUrl || !routedId || !this.intelligence?.wsUrl) throw new Error("Intelligence mode requires runtimeUrl, agentId, and intelligence websocket metadata");
 		return new IntelligenceAgent({
 			url: this.intelligence.wsUrl,
 			runtimeUrl: this.runtimeUrl,
-			agentId: this.agentId,
+			agentId: routedId,
 			headers: { ...this.headers },
 			credentials: this.credentials
 		});
 	}
 	syncDelegate(delegate) {
-		delegate.agentId = this.agentId;
+		delegate.agentId = this.routedAgentId();
 		delegate.description = this.description;
 		delegate.threadId = this.threadId;
 		delegate.setMessages(this.messages);
@@ -906,6 +964,52 @@ var AgentRegistry = class {
 		this.notifyAgentsChanged();
 	}
 	/**
+	* Register a proxied agent that routes outbound runtime requests to an
+	* existing runtime agent (`runtimeAgentId`) while exposing a distinct local
+	* registry id (`agentId`). Throws if `agentId` is already taken by either a
+	* local or runtime-discovered agent.
+	*
+	* Use this to mount multiple frontend agents against a single runtime
+	* agent (e.g. a chat-1 / chat-2 pair both proxying to "default") without
+	* implicit per-thread cloning. The returned `unregister` removes the proxy
+	* from the registry and emits `onAgentsChanged`.
+	*/
+	registerProxiedAgent({ agentId, runtimeAgentId }) {
+		if (Object.prototype.hasOwnProperty.call(this._agents, agentId)) throw new Error(`CopilotKitCore.registerProxiedAgent: agentId "${agentId}" is already registered. Pick a different agentId, or unregister the existing agent first.`);
+		const friends = this.core;
+		const debug = friends.debug;
+		const agent = new ProxiedCopilotRuntimeAgent({
+			runtimeUrl: this._runtimeUrl,
+			agentId,
+			runtimeAgentId,
+			transport: this._runtimeTransport,
+			credentials: friends.credentials,
+			runtimeMode: this._runtimeUrl ? this._runtimeConnectionStatus === CopilotKitCoreRuntimeConnectionStatus.Connected ? this._runtimeMode : "pending" : RUNTIME_MODE_SSE,
+			intelligence: this._intelligence,
+			debug: debug ? resolveDebugConfig(debug) : void 0
+		});
+		this.applyHeadersToAgent(agent);
+		this.localAgents[agentId] = agent;
+		this._agents = {
+			...this.localAgents,
+			...this.remoteAgents
+		};
+		this.notifyAgentsChanged();
+		return {
+			agent,
+			unregister: () => {
+				if (this.localAgents[agentId] === agent) {
+					delete this.localAgents[agentId];
+					this._agents = {
+						...this.localAgents,
+						...this.remoteAgents
+					};
+					this.notifyAgentsChanged();
+				}
+			}
+		};
+	}
+	/**
 	* Get an agent by ID
 	*/
 	getAgent(id) {
@@ -1185,16 +1289,10 @@ var SuggestionEngine = class {
 	/**
 	* Reload suggestions for a specific agent
 	* This triggers generation of new suggestions based on current configs
-	*
-	* @param agentId - The consumer agent ID
-	* @param consumerAgent - Optional: the specific agent instance whose messages should be used
-	*   for availability filtering and context. When running with per-thread clones, the thread
-	*   clone holds the conversation messages; passing it here ensures dynamic suggestions fire
-	*   after the first message even though the registry agent has an empty message list.
 	*/
-	reloadSuggestions(agentId, consumerAgent) {
+	reloadSuggestions(agentId) {
 		this.clearSuggestions(agentId);
-		const agent = consumerAgent ?? this.core.getAgent(agentId);
+		const agent = this.core.getAgent(agentId);
 		const messageCount = agent?.messages?.length ?? 0;
 		let hasAnySuggestions = false;
 		for (const config of Object.values(this._suggestionsConfig)) {
@@ -1207,7 +1305,7 @@ var SuggestionEngine = class {
 					hasAnySuggestions = true;
 					this.notifySuggestionsStartedLoading(agentId);
 				}
-				this.generateSuggestions(suggestionId, config, agentId, agent);
+				this.generateSuggestions(suggestionId, config, agentId);
 			} else if (isStaticSuggestionsConfig(config)) this.addStaticSuggestions(suggestionId, config, agentId);
 		}
 	}
@@ -1235,12 +1333,12 @@ var SuggestionEngine = class {
 	/**
 	* Generate suggestions using a provider agent
 	*/
-	async generateSuggestions(suggestionId, config, consumerAgentId, consumerAgent) {
+	async generateSuggestions(suggestionId, config, consumerAgentId) {
 		let agent = void 0;
 		try {
 			const suggestionsProviderAgent = this.core.getAgent(config.providerAgentId ?? "default");
 			if (!suggestionsProviderAgent) throw new Error(`Suggestions provider agent not found: ${config.providerAgentId}`);
-			const suggestionsConsumerAgent = consumerAgent ?? this.core.getAgent(consumerAgentId);
+			const suggestionsConsumerAgent = this.core.getAgent(consumerAgentId);
 			if (!suggestionsConsumerAgent) throw new Error(`Suggestions consumer agent not found: ${consumerAgentId}`);
 			agent = suggestionsProviderAgent.clone();
 			agent.threadId = suggestionId;
@@ -1468,6 +1566,23 @@ var RunHandler = class {
 	* `processAgentResult`.
 	*/
 	_runDepth = 0;
+	/**
+	* Tracks the threadId of the most recent `connectAgent` call so we
+	* can distinguish a fresh thread restore (different threadId than
+	* last time — chat is rebuilding state from scratch, must clear
+	* messages/state and ask the gateway for a full replay) from a
+	* same-thread churn re-connect (effect-dep churn or transient
+	* disconnect — local messages/state are still meaningful, must
+	* preserve them and let the gateway resume from
+	* `lastSeenEventId`).
+	*
+	* Tyler's bug fired because every `connectAgent` was treated as a
+	* fresh restore, which forced the gateway to replay the full
+	* thread history on every churn re-connect and amplified the
+	* downstream churn into duplicate `cpki_event_id` rows in the
+	* inspector and intermittent "Message not found" toasts.
+	*/
+	_lastConnectedThreadId = null;
 	constructor(core) {
 		this.core = core;
 	}
@@ -1541,14 +1656,17 @@ var RunHandler = class {
 	*/
 	async connectAgent({ agent }) {
 		try {
+			const incomingThreadId = agent.threadId ?? null;
+			const isFreshRestore = incomingThreadId !== this._lastConnectedThreadId;
+			this._lastConnectedThreadId = incomingThreadId;
 			await agent.detachActiveRun();
-			agent.setMessages([]);
-			agent.setState({});
+			if (isFreshRestore) {
+				agent.setMessages([]);
+				agent.setState({});
+				const proxied = agent;
+				if (incomingThreadId && typeof proxied.clearReplayCursor === "function") proxied.clearReplayCursor(incomingThreadId);
+			}
 			if (agent instanceof HttpAgent) agent.headers = { ...this._internal.headers };
-			await this._internal.notifySubscribers((subscriber) => subscriber.onAgentRunStarted?.({
-				copilotkit: this.core,
-				agent
-			}), "Subscriber onAgentRunStarted error:");
 			const runAgentResult = await agent.connectAgent({
 				forwardedProps: this._internal.properties,
 				tools: this.buildFrontendTools(agent.agentId),
@@ -1579,11 +1697,6 @@ var RunHandler = class {
 		if (agent.agentId) this._internal.suggestionEngine.clearSuggestions(agent.agentId);
 		if (agent instanceof HttpAgent) agent.headers = { ...this._internal.headers };
 		if (agent.detachActiveRun) await agent.detachActiveRun();
-		this._internal.subscribeAgentToStateManager(agent);
-		await this._internal.notifySubscribers((subscriber) => subscriber.onAgentRunStarted?.({
-			copilotkit: this.core,
-			agent
-		}), "Subscriber onAgentRunStarted error:");
 		const isTopLevel = this._runDepth === 0;
 		let originalAbortRun;
 		if (isTopLevel) {
@@ -1654,7 +1767,7 @@ var RunHandler = class {
 			await this._internal.waitForPendingFrameworkUpdates();
 			return await this.runAgent({ agent });
 		}
-		this._internal.suggestionEngine.reloadSuggestions(agentId, agent);
+		this._internal.suggestionEngine.reloadSuggestions(agentId);
 		return runAgentResult;
 	}
 	/**
@@ -2066,21 +2179,14 @@ var StateManager = class {
 	initialize() {}
 	/**
 	* Subscribe to an agent's events to track state and messages.
-	*
-	* Registry agents (subscribed via `onAgentsChanged`) use the bare `agentId`
-	* key so that `unsubscribeFromAgent(agentId)` can remove them when they
-	* are replaced. Per-thread clones (subscribed via `subscribeAgentToStateManager`)
-	* pass `{ isClone: true }` to use a composite `agentId:threadId` key, keeping
-	* their subscription independent of the registry agent's.
 	*/
-	subscribeToAgent(agent, { isClone = false } = {}) {
+	subscribeToAgent(agent) {
 		if (!agent.agentId) return;
 		const agentId = agent.agentId;
-		const subscriptionKey = isClone && agent.threadId ? `${agentId}:${agent.threadId}` : agentId;
-		const existingUnsubscribe = this.agentSubscriptions.get(subscriptionKey);
+		const existingUnsubscribe = this.agentSubscriptions.get(agentId);
 		if (existingUnsubscribe) {
 			existingUnsubscribe();
-			this.agentSubscriptions.delete(subscriptionKey);
+			this.agentSubscriptions.delete(agentId);
 		}
 		let revoked = false;
 		let subRunId;
@@ -2124,16 +2230,13 @@ var StateManager = class {
 				this.handleNewMessage(agent, message, input ? effectiveInput(input) : void 0);
 			}
 		});
-		this.agentSubscriptions.set(subscriptionKey, () => {
+		this.agentSubscriptions.set(agentId, () => {
 			revoked = true;
 			unsubscribe();
 		});
 	}
 	/**
-	* Unsubscribe a registry agent's subscription (bare `agentId` key).
-	* Per-thread clone subscriptions use composite `agentId:threadId` keys and
-	* are replaced (not removed) by subsequent subscribeToAgent(agent, { isClone: true })
-	* calls for the same (agentId, threadId) pair.
+	* Unsubscribe an agent's subscription.
 	*/
 	unsubscribeFromAgent(agentId) {
 		const unsubscribe = this.agentSubscriptions.get(agentId);
@@ -2418,7 +2521,16 @@ var CopilotKitCore = class {
 				if (agent.agentId) this.stateManager.subscribeToAgent(agent);
 			});
 			const currentAgentIds = new Set(Object.keys(agents));
-			for (const agentId of Object.keys(this.threadStoreRegistry.getAll())) if (this.previousAgentIds.has(agentId) && !currentAgentIds.has(agentId)) this.threadStoreRegistry.unregister(agentId);
+			for (const agentId of Object.keys(this.threadStoreRegistry.getAll())) if (this.previousAgentIds.has(agentId) && !currentAgentIds.has(agentId)) try {
+				this.threadStoreRegistry.unregister(agentId);
+			} catch (err) {
+				console.error(`CopilotKitCore.onAgentsChanged: threadStoreRegistry.unregister failed for "${agentId}":`, err);
+			}
+			for (const agentId of this.previousAgentIds) if (!currentAgentIds.has(agentId)) try {
+				this.stateManager.unsubscribeFromAgent(agentId);
+			} catch (err) {
+				console.error(`CopilotKitCore.onAgentsChanged: stateManager.unsubscribeFromAgent failed for "${agentId}":`, err);
+			}
 			this.previousAgentIds = currentAgentIds;
 		} });
 	}
@@ -2581,6 +2693,28 @@ var CopilotKitCore = class {
 	removeAgent__unsafe_dev_only(id) {
 		this.agentRegistry.removeAgent__unsafe_dev_only(id);
 	}
+	/**
+	* Register a proxied agent against an existing runtime agent. The proxy is
+	* exposed under `agentId` (local registry id) and routes outbound runtime
+	* requests to `runtimeAgentId`. Throws if `agentId` is already taken.
+	*
+	* Returns the minted proxy and an `unregister` handle for cleanup.
+	*
+	* Use this to mount multiple frontend agents against a single runtime
+	* agent (e.g. one per chat window) without implicit per-thread cloning.
+	*
+	* @example
+	* const { agent, unregister } = copilotkit.registerProxiedAgent({
+	*   agentId: "chat-1",
+	*   runtimeAgentId: "default",
+	* });
+	* // ... <CopilotChat agentId="chat-1" />
+	* // on cleanup:
+	* unregister();
+	*/
+	registerProxiedAgent(params) {
+		return this.agentRegistry.registerProxiedAgent(params);
+	}
 	getAgent(id) {
 		return this.agentRegistry.getAgent(id);
 	}
@@ -2814,9 +2948,6 @@ var CopilotKitCore = class {
 	getRunIdsForThread(agentId, threadId) {
 		return this.stateManager.getRunIdsForThread(agentId, threadId);
 	}
-	subscribeAgentToStateManager(agent) {
-		this.stateManager.subscribeToAgent(agent, { isClone: true });
-	}
 	/**
 	* Internal method used by RunHandler to build frontend tools
 	*/