@copilotkitnext/core 1.54.0-next.5 → 1.54.0-next.7

package/dist/index.mjs

@@ -748,6 +748,13 @@ var RunHandler = class {
 		this.core = core;
 	}
 	/**
+	* Typed access to CopilotKitCore's internal ("friend") methods.
+	* Centralises the single unavoidable cast so call-sites stay clean.
+	*/
+	get _internal() {
+		return this.core;
+	}
+	/**
 	* Get all tools as a readonly array
 	*/
 	get tools() {
@@ -805,9 +812,9 @@ var RunHandler = class {
 			await agent.detachActiveRun();
 			agent.setMessages([]);
 			agent.setState({});
-			if (agent instanceof HttpAgent) agent.headers = { ...this.core.headers };
+			if (agent instanceof HttpAgent) agent.headers = { ...this._internal.headers };
 			const runAgentResult = await agent.connectAgent({
-				forwardedProps: this.core.properties,
+				forwardedProps: this._internal.properties,
 				tools: this.buildFrontendTools(agent.agentId)
 			}, this.createAgentErrorSubscriber(agent));
 			return this.processAgentResult({
@@ -818,7 +825,7 @@ var RunHandler = class {
 			const connectError = error instanceof Error ? error : new Error(String(error));
 			const context = {};
 			if (agent.agentId) context.agentId = agent.agentId;
-			await this.core.emitError({
+			await this._internal.emitError({
 				error: connectError,
 				code: CopilotKitCoreErrorCode.AGENT_CONNECT_FAILED,
 				context
@@ -830,16 +837,16 @@ var RunHandler = class {
 	* Run an agent
 	*/
 	async runAgent({ agent, forwardedProps }) {
-		if (agent.agentId) this.core.suggestionEngine.clearSuggestions(agent.agentId);
-		if (agent instanceof HttpAgent) agent.headers = { ...this.core.headers };
+		if (agent.agentId) this._internal.suggestionEngine.clearSuggestions(agent.agentId);
+		if (agent instanceof HttpAgent) agent.headers = { ...this._internal.headers };
 		try {
 			const runAgentResult = await agent.runAgent({
 				forwardedProps: {
-					...this.core.properties,
+					...this._internal.properties,
 					...forwardedProps
 				},
 				tools: this.buildFrontendTools(agent.agentId),
-				context: Object.values(this.core.context)
+				context: Object.values(this._internal.context)
 			}, this.createAgentErrorSubscriber(agent));
 			return this.processAgentResult({
 				runAgentResult,
@@ -849,7 +856,7 @@ var RunHandler = class {
 			const runError = error instanceof Error ? error : new Error(String(error));
 			const context = {};
 			if (agent.agentId) context.agentId = agent.agentId;
-			await this.core.emitError({
+			await this._internal.emitError({
 				error: runError,
 				code: CopilotKitCoreErrorCode.AGENT_RUN_FAILED,
 				context
@@ -883,78 +890,107 @@ var RunHandler = class {
 				}
 			}
 		}
-		if (needsFollowUp) return await this.runAgent({ agent });
-		this.core.suggestionEngine.reloadSuggestions(agentId);
+		if (needsFollowUp) {
+			await this._internal.waitForPendingFrameworkUpdates();
+			return await this.runAgent({ agent });
+		}
+		this._internal.suggestionEngine.reloadSuggestions(agentId);
 		return runAgentResult;
 	}
 	/**
-	* Execute a specific tool
+	* Shared handler execution logic used by executeSpecificTool, executeWildcardTool, and runTool.
+	* Handles arg parsing, subscriber notifications, handler invocation, result stringification,
+	* and error handling.
 	*/
-	async executeSpecificTool(tool, toolCall, message, agent, agentId) {
-		if (tool?.agentId && tool.agentId !== agent.agentId) return false;
+	async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId }) {
 		let toolCallResult = "";
 		let errorMessage;
-		if (tool?.handler) {
-			let parsedArgs;
-			try {
-				parsedArgs = ensureObjectArgs(JSON.parse(toolCall.function.arguments), toolCall.function.name);
-			} catch (error) {
-				const parseError = error instanceof Error ? error : new Error(String(error));
-				errorMessage = parseError.message;
-				await this.core.emitError({
-					error: parseError,
-					code: CopilotKitCoreErrorCode.TOOL_ARGUMENT_PARSE_FAILED,
-					context: {
-						agentId,
-						toolCallId: toolCall.id,
-						toolName: toolCall.function.name,
-						rawArguments: toolCall.function.arguments,
-						toolType: "specific",
-						messageId: message.id
-					}
-				});
-			}
-			await this.core.notifySubscribers((subscriber) => subscriber.onToolExecutionStart?.({
-				copilotkit: this.core,
-				toolCallId: toolCall.id,
-				agentId,
-				toolName: toolCall.function.name,
-				args: parsedArgs
-			}), "Subscriber onToolExecutionStart error:");
-			if (!errorMessage) try {
-				const result = await tool.handler(parsedArgs, {
-					toolCall,
-					agent
-				});
-				if (result === void 0 || result === null) toolCallResult = "";
-				else if (typeof result === "string") toolCallResult = result;
-				else toolCallResult = JSON.stringify(result);
-			} catch (error) {
-				const handlerError = error instanceof Error ? error : new Error(String(error));
-				errorMessage = handlerError.message;
-				await this.core.emitError({
-					error: handlerError,
-					code: CopilotKitCoreErrorCode.TOOL_HANDLER_FAILED,
-					context: {
-						agentId,
-						toolCallId: toolCall.id,
-						toolName: toolCall.function.name,
-						parsedArgs,
-						toolType: "specific",
-						messageId: message.id
-					}
-				});
-			}
-			if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
-			await this.core.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
-				copilotkit: this.core,
-				toolCallId: toolCall.id,
-				agentId,
-				toolName: toolCall.function.name,
-				result: errorMessage ? "" : toolCallResult,
-				error: errorMessage
-			}), "Subscriber onToolExecutionEnd error:");
+		let isArgumentError = false;
+		let parsedArgs;
+		try {
+			parsedArgs = ensureObjectArgs(typeof handlerArgs === "string" ? JSON.parse(handlerArgs) : handlerArgs, toolCall.function.name);
+		} catch (error) {
+			const parseError = error instanceof Error ? error : new Error(String(error));
+			errorMessage = parseError.message;
+			isArgumentError = true;
+			await this._internal.emitError({
+				error: parseError,
+				code: CopilotKitCoreErrorCode.TOOL_ARGUMENT_PARSE_FAILED,
+				context: {
+					agentId,
+					toolCallId: toolCall.id,
+					toolName: toolCall.function.name,
+					rawArguments: handlerArgs,
+					toolType,
+					...messageId ? { messageId } : {}
+				}
+			});
+		}
+		await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionStart?.({
+			copilotkit: this.core,
+			toolCallId: toolCall.id,
+			agentId,
+			toolName: toolCall.function.name,
+			args: parsedArgs
+		}), "Subscriber onToolExecutionStart error:");
+		if (!errorMessage) try {
+			const result = await tool.handler(parsedArgs, {
+				toolCall,
+				agent
+			});
+			if (result === void 0 || result === null) toolCallResult = "";
+			else if (typeof result === "string") toolCallResult = result;
+			else toolCallResult = JSON.stringify(result);
+		} catch (error) {
+			const handlerError = error instanceof Error ? error : new Error(String(error));
+			errorMessage = handlerError.message;
+			await this._internal.emitError({
+				error: handlerError,
+				code: CopilotKitCoreErrorCode.TOOL_HANDLER_FAILED,
+				context: {
+					agentId,
+					toolCallId: toolCall.id,
+					toolName: toolCall.function.name,
+					parsedArgs,
+					toolType,
+					...messageId ? { messageId } : {}
+				}
+			});
 		}
+		if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
+		await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
+			copilotkit: this.core,
+			toolCallId: toolCall.id,
+			agentId,
+			toolName: toolCall.function.name,
+			result: errorMessage ? "" : toolCallResult,
+			error: errorMessage
+		}), "Subscriber onToolExecutionEnd error:");
+		return {
+			result: toolCallResult,
+			error: errorMessage,
+			isArgumentError
+		};
+	}
+	/**
+	* Execute a specific tool
+	*/
+	async executeSpecificTool(tool, toolCall, message, agent, agentId) {
+		if (tool?.agentId && tool.agentId !== agent.agentId) return false;
+		let handlerResult = {
+			result: "",
+			error: void 0,
+			isArgumentError: false
+		};
+		if (tool?.handler) handlerResult = await this.executeToolHandler({
+			tool,
+			toolCall,
+			agent,
+			agentId,
+			handlerArgs: toolCall.function.arguments,
+			toolType: "specific",
+			messageId: message.id
+		});
 		{
 			const messageIndex = agent.messages.findIndex((m) => m.id === message.id);
 			if (messageIndex === -1) return false;
@@ -962,15 +998,18 @@ var RunHandler = class {
 				id: randomUUID(),
 				role: "tool",
 				toolCallId: toolCall.id,
-				content: toolCallResult
+				content: handlerResult.result
 			};
 			agent.messages.splice(messageIndex + 1, 0, toolMessage);
-			if (!errorMessage && tool?.followUp !== false) return true;
+			if (!handlerResult.error && tool?.followUp !== false) return true;
 		}
 		return false;
 	}
 	/**
-	* Execute a wildcard tool
+	* Execute a wildcard tool.
+	* Wildcard tools receive args wrapped as `{toolName, args}`, which differs from
+	* specific tools, so this method keeps its own arg-wrapping logic rather than
+	* delegating to `executeToolHandler`.
 	*/
 	async executeWildcardTool(wildcardTool, toolCall, message, agent, agentId) {
 		if (wildcardTool?.agentId && wildcardTool.agentId !== agent.agentId) return false;
@@ -983,7 +1022,7 @@ var RunHandler = class {
 			} catch (error) {
 				const parseError = error instanceof Error ? error : new Error(String(error));
 				errorMessage = parseError.message;
-				await this.core.emitError({
+				await this._internal.emitError({
 					error: parseError,
 					code: CopilotKitCoreErrorCode.TOOL_ARGUMENT_PARSE_FAILED,
 					context: {
@@ -1000,7 +1039,7 @@ var RunHandler = class {
 				toolName: toolCall.function.name,
 				args: parsedArgs
 			};
-			await this.core.notifySubscribers((subscriber) => subscriber.onToolExecutionStart?.({
+			await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionStart?.({
 				copilotkit: this.core,
 				toolCallId: toolCall.id,
 				agentId,
@@ -1018,7 +1057,7 @@ var RunHandler = class {
 			} catch (error) {
 				const handlerError = error instanceof Error ? error : new Error(String(error));
 				errorMessage = handlerError.message;
-				await this.core.emitError({
+				await this._internal.emitError({
 					error: handlerError,
 					code: CopilotKitCoreErrorCode.TOOL_HANDLER_FAILED,
 					context: {
@@ -1032,7 +1071,7 @@ var RunHandler = class {
 				});
 			}
 			if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
-			await this.core.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
+			await this._internal.notifySubscribers((subscriber) => subscriber.onToolExecutionEnd?.({
 				copilotkit: this.core,
 				toolCallId: toolCall.id,
 				agentId,
@@ -1056,6 +1095,95 @@ var RunHandler = class {
 		return false;
 	}
 	/**
+	* Programmatically execute a registered frontend tool without going through an LLM turn.
+	* The handler runs, render components show up in the UI, and both the tool call and
+	* result messages are added to `agent.messages`.
+	*/
+	async runTool(params) {
+		const { name, agentId, parameters = {}, followUp = false } = params;
+		const tool = this.getTool({
+			toolName: name,
+			agentId
+		});
+		if (!tool) {
+			const error = /* @__PURE__ */ new Error(`Tool not found: ${name}`);
+			await this._internal.emitError({
+				error,
+				code: CopilotKitCoreErrorCode.TOOL_NOT_FOUND,
+				context: {
+					toolName: name,
+					agentId
+				}
+			});
+			throw error;
+		}
+		const resolvedAgentId = agentId ?? "default";
+		const agent = this._internal.getAgent(resolvedAgentId);
+		if (!agent) {
+			const error = /* @__PURE__ */ new Error(`Agent not found: ${resolvedAgentId}`);
+			await this._internal.emitError({
+				error,
+				code: CopilotKitCoreErrorCode.AGENT_NOT_FOUND,
+				context: { agentId: resolvedAgentId }
+			});
+			throw error;
+		}
+		const toolCallId = randomUUID();
+		const assistantMessage = {
+			id: randomUUID(),
+			role: "assistant",
+			content: "",
+			toolCalls: [{
+				id: toolCallId,
+				type: "function",
+				function: {
+					name,
+					arguments: JSON.stringify(parameters)
+				}
+			}]
+		};
+		agent.messages.push(assistantMessage);
+		let handlerResult = {
+			result: "",
+			error: void 0,
+			isArgumentError: false
+		};
+		if (tool.handler) handlerResult = await this.executeToolHandler({
+			tool,
+			toolCall: assistantMessage.toolCalls[0],
+			agent,
+			agentId: resolvedAgentId,
+			handlerArgs: parameters,
+			toolType: "runTool"
+		});
+		const toolResultMessage = {
+			id: randomUUID(),
+			role: "tool",
+			toolCallId,
+			content: handlerResult.result
+		};
+		const assistantIndex = agent.messages.findIndex((m) => m.id === assistantMessage.id);
+		if (assistantIndex !== -1) agent.messages.splice(assistantIndex + 1, 0, toolResultMessage);
+		else agent.messages.push(toolResultMessage);
+		if (!handlerResult.error && followUp !== false) {
+			if (typeof followUp === "string" && followUp !== "generate") {
+				const userMessage = {
+					id: randomUUID(),
+					role: "user",
+					content: followUp
+				};
+				agent.messages.push(userMessage);
+			}
+			await this._internal.waitForPendingFrameworkUpdates();
+			await this.runAgent({ agent });
+		}
+		return {
+			toolCallId,
+			result: handlerResult.result,
+			error: handlerResult.error
+		};
+	}
+	/**
 	* Build frontend tools for an agent
 	*/
 	buildFrontendTools(agentId) {
@@ -1072,7 +1200,7 @@ var RunHandler = class {
 		const emitAgentError = async (error, code, extraContext = {}) => {
 			const context = { ...extraContext };
 			if (agent.agentId) context.agentId = agent.agentId;
-			await this.core.emitError({
+			await this._internal.emitError({
 				error,
 				code,
 				context
@@ -1318,6 +1446,8 @@ let CopilotKitCoreErrorCode = /* @__PURE__ */ function(CopilotKitCoreErrorCode)
 	CopilotKitCoreErrorCode["AGENT_RUN_ERROR_EVENT"] = "agent_run_error_event";
 	CopilotKitCoreErrorCode["TOOL_ARGUMENT_PARSE_FAILED"] = "tool_argument_parse_failed";
 	CopilotKitCoreErrorCode["TOOL_HANDLER_FAILED"] = "tool_handler_failed";
+	CopilotKitCoreErrorCode["TOOL_NOT_FOUND"] = "tool_not_found";
+	CopilotKitCoreErrorCode["AGENT_NOT_FOUND"] = "agent_not_found";
 	CopilotKitCoreErrorCode["TRANSCRIPTION_FAILED"] = "transcription_failed";
 	CopilotKitCoreErrorCode["TRANSCRIPTION_SERVICE_NOT_CONFIGURED"] = "transcription_service_not_configured";
 	CopilotKitCoreErrorCode["TRANSCRIPTION_INVALID_AUDIO"] = "transcription_invalid_audio";
@@ -1533,6 +1663,14 @@ var CopilotKitCore = class {
 		return this.runHandler.runAgent(params);
 	}
 	/**
+	* Programmatically execute a registered frontend tool without going through an LLM turn.
+	* The handler runs, render components show up in the UI, and both the tool call and
+	* result messages are added to `agent.messages`.
+	*/
+	async runTool(params) {
+		return this.runHandler.runTool(params);
+	}
+	/**
 	* State management (delegated to StateManager)
 	*/
 	getStateByRun(agentId, threadId, runId) {
@@ -1550,6 +1688,24 @@ var CopilotKitCore = class {
 	buildFrontendTools(agentId) {
 		return this.runHandler.buildFrontendTools(agentId);
 	}
+	/**
+	* Called before each follow-up agent run (after tool execution).
+	*
+	* When a frontend tool handler calls framework state setters (e.g. React's
+	* setState), those updates are batched and deferred — they do not take effect
+	* until the framework's scheduler runs (React uses MessageChannel).
+	* useAgentContext registers context via useLayoutEffect, which runs
+	* synchronously after React commits that deferred batch.
+	*
+	* Without yielding here, the follow-up runAgent reads the context store
+	* synchronously while the deferred updates are still pending, producing stale
+	* context for the next agent turn.
+	*
+	* Override in framework-specific subclasses to yield to the framework
+	* scheduler before the follow-up run. The base implementation is a no-op
+	* because non-React environments have no deferred state to flush.
+	*/
+	async waitForPendingFrameworkUpdates() {}
 };
 
 //#endregion