@copilotkitnext/core 1.54.0-next.4 → 1.54.0-next.6

package/dist/index.umd.js

@@ -823,6 +823,13 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			_defineProperty(this, "_tools", []);
 		}
 		/**
+		* 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() {
@@ -880,9 +887,9 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				await agent.detachActiveRun();
 				agent.setMessages([]);
 				agent.setState({});
-				if (agent instanceof _ag_ui_client.HttpAgent) agent.headers = { ...this.core.headers };
+				if (agent instanceof _ag_ui_client.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({
@@ -893,7 +900,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				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
@@ -905,16 +912,16 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		* Run an agent
 		*/
 		async runAgent({ agent, forwardedProps }) {
-			if (agent.agentId) this.core.suggestionEngine.clearSuggestions(agent.agentId);
-			if (agent instanceof _ag_ui_client.HttpAgent) agent.headers = { ...this.core.headers };
+			if (agent.agentId) this._internal.suggestionEngine.clearSuggestions(agent.agentId);
+			if (agent instanceof _ag_ui_client.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,
@@ -924,7 +931,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				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
@@ -959,83 +966,109 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				}
 			}
 			if (needsFollowUp) return await this.runAgent({ agent });
-			this.core.suggestionEngine.reloadSuggestions(agentId);
+			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 === null || tool === void 0 ? void 0 : tool.agentId) && tool.agentId !== agent.agentId) return false;
+		async executeToolHandler({ tool, toolCall, agent, agentId, handlerArgs, toolType, messageId }) {
 			let toolCallResult = "";
 			let errorMessage;
-			if (tool === null || tool === void 0 ? void 0 : 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) => {
-					var _subscriber$onToolExe;
-					return (_subscriber$onToolExe = subscriber.onToolExecutionStart) === null || _subscriber$onToolExe === void 0 ? void 0 : _subscriber$onToolExe.call(subscriber, {
-						copilotkit: this.core,
-						toolCallId: toolCall.id,
+			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,
-						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) => {
-					var _subscriber$onToolExe2;
-					return (_subscriber$onToolExe2 = subscriber.onToolExecutionEnd) === null || _subscriber$onToolExe2 === void 0 ? void 0 : _subscriber$onToolExe2.call(subscriber, {
-						copilotkit: this.core,
 						toolCallId: toolCall.id,
+						toolName: toolCall.function.name,
+						rawArguments: handlerArgs,
+						toolType,
+						...messageId ? { messageId } : {}
+					}
+				});
+			}
+			await this._internal.notifySubscribers((subscriber) => {
+				var _subscriber$onToolExe;
+				return (_subscriber$onToolExe = subscriber.onToolExecutionStart) === null || _subscriber$onToolExe === void 0 ? void 0 : _subscriber$onToolExe.call(subscriber, {
+					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,
-						result: errorMessage ? "" : toolCallResult,
-						error: errorMessage
-					});
-				}, "Subscriber onToolExecutionEnd error:");
+						parsedArgs,
+						toolType,
+						...messageId ? { messageId } : {}
+					}
+				});
 			}
+			if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
+			await this._internal.notifySubscribers((subscriber) => {
+				var _subscriber$onToolExe2;
+				return (_subscriber$onToolExe2 = subscriber.onToolExecutionEnd) === null || _subscriber$onToolExe2 === void 0 ? void 0 : _subscriber$onToolExe2.call(subscriber, {
+					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 === null || tool === void 0 ? void 0 : tool.agentId) && tool.agentId !== agent.agentId) return false;
+			let handlerResult = {
+				result: "",
+				error: void 0,
+				isArgumentError: false
+			};
+			if (tool === null || tool === void 0 ? void 0 : 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;
@@ -1043,15 +1076,18 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					id: (0, _copilotkitnext_shared.randomUUID)(),
 					role: "tool",
 					toolCallId: toolCall.id,
-					content: toolCallResult
+					content: handlerResult.result
 				};
 				agent.messages.splice(messageIndex + 1, 0, toolMessage);
-				if (!errorMessage && (tool === null || tool === void 0 ? void 0 : tool.followUp) !== false) return true;
+				if (!handlerResult.error && (tool === null || tool === void 0 ? void 0 : 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 === null || wildcardTool === void 0 ? void 0 : wildcardTool.agentId) && wildcardTool.agentId !== agent.agentId) return false;
@@ -1064,7 +1100,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				} 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: {
@@ -1081,7 +1117,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					toolName: toolCall.function.name,
 					args: parsedArgs
 				};
-				await this.core.notifySubscribers((subscriber) => {
+				await this._internal.notifySubscribers((subscriber) => {
 					var _subscriber$onToolExe3;
 					return (_subscriber$onToolExe3 = subscriber.onToolExecutionStart) === null || _subscriber$onToolExe3 === void 0 ? void 0 : _subscriber$onToolExe3.call(subscriber, {
 						copilotkit: this.core,
@@ -1102,7 +1138,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 				} 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: {
@@ -1116,7 +1152,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 					});
 				}
 				if (errorMessage) toolCallResult = `Error: ${errorMessage}`;
-				await this.core.notifySubscribers((subscriber) => {
+				await this._internal.notifySubscribers((subscriber) => {
 					var _subscriber$onToolExe4;
 					return (_subscriber$onToolExe4 = subscriber.onToolExecutionEnd) === null || _subscriber$onToolExe4 === void 0 ? void 0 : _subscriber$onToolExe4.call(subscriber, {
 						copilotkit: this.core,
@@ -1143,6 +1179,94 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			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 !== null && agentId !== void 0 ? 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 = (0, _copilotkitnext_shared.randomUUID)();
+			const assistantMessage = {
+				id: (0, _copilotkitnext_shared.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: (0, _copilotkitnext_shared.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: (0, _copilotkitnext_shared.randomUUID)(),
+						role: "user",
+						content: followUp
+					};
+					agent.messages.push(userMessage);
+				}
+				await this.runAgent({ agent });
+			}
+			return {
+				toolCallId,
+				result: handlerResult.result,
+				error: handlerResult.error
+			};
+		}
+		/**
 		* Build frontend tools for an agent
 		*/
 		buildFrontendTools(agentId) {
@@ -1162,7 +1286,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			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
@@ -1414,6 +1538,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 		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";
@@ -1638,6 +1764,14 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 			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) {