@copilotkitnext/core 0.0.7 → 0.0.9-alpha.0

package/dist/index.mjs

@@ -1,8 +1,12 @@
 // src/core.ts
 import {
-  randomUUID
+  DEFAULT_AGENT_ID,
+  randomUUID,
+  logger
 } from "@copilotkitnext/shared";
-import { logger } from "@copilotkitnext/shared";
+import {
+  HttpAgent as HttpAgent2
+} from "@ag-ui/client";
 
 // src/agent.ts
 import {
@@ -10,8 +14,7 @@ import {
   runHttpRequest,
   transformHttpEventStream
 } from "@ag-ui/client";
-var CopilotKitHttpAgent = class extends HttpAgent {
-  isCopilotKitAgent = true;
+var ProxiedCopilotRuntimeAgent = class extends HttpAgent {
   runtimeUrl;
   constructor(config) {
     super({
@@ -20,144 +23,387 @@ var CopilotKitHttpAgent = class extends HttpAgent {
     });
     this.runtimeUrl = config.runtimeUrl;
   }
-  run(input) {
-    const url = input.forwardedProps.__copilotkitConnect === true ? `${this.runtimeUrl}/agent/${this.agentId}/connect` : this.url;
-    const httpEvents = runHttpRequest(url, this.requestInit(input));
+  connect(input) {
+    const httpEvents = runHttpRequest(
+      `${this.runtimeUrl}/agent/${this.agentId}/connect`,
+      this.requestInit(input)
+    );
     return transformHttpEventStream(httpEvents);
   }
 };
 
 // src/core.ts
+import { zodToJsonSchema } from "zod-to-json-schema";
+var CopilotKitCoreErrorCode = /* @__PURE__ */ ((CopilotKitCoreErrorCode2) => {
+  CopilotKitCoreErrorCode2["RUNTIME_INFO_FETCH_FAILED"] = "runtime_info_fetch_failed";
+  CopilotKitCoreErrorCode2["AGENT_CONNECT_FAILED"] = "agent_connect_failed";
+  CopilotKitCoreErrorCode2["AGENT_RUN_FAILED"] = "agent_run_failed";
+  CopilotKitCoreErrorCode2["AGENT_RUN_FAILED_EVENT"] = "agent_run_failed_event";
+  CopilotKitCoreErrorCode2["AGENT_RUN_ERROR_EVENT"] = "agent_run_error_event";
+  CopilotKitCoreErrorCode2["TOOL_ARGUMENT_PARSE_FAILED"] = "tool_argument_parse_failed";
+  CopilotKitCoreErrorCode2["TOOL_HANDLER_FAILED"] = "tool_handler_failed";
+  return CopilotKitCoreErrorCode2;
+})(CopilotKitCoreErrorCode || {});
+var CopilotKitCoreRuntimeConnectionStatus = /* @__PURE__ */ ((CopilotKitCoreRuntimeConnectionStatus2) => {
+  CopilotKitCoreRuntimeConnectionStatus2["Disconnected"] = "disconnected";
+  CopilotKitCoreRuntimeConnectionStatus2["Connected"] = "connected";
+  CopilotKitCoreRuntimeConnectionStatus2["Connecting"] = "connecting";
+  CopilotKitCoreRuntimeConnectionStatus2["Error"] = "error";
+  return CopilotKitCoreRuntimeConnectionStatus2;
+})(CopilotKitCoreRuntimeConnectionStatus || {});
 var CopilotKitCore = class {
-  runtimeUrl;
-  didLoadRuntime = false;
-  context = {};
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tools = {};
-  agents = {};
   headers;
   properties;
-  version;
+  _context = {};
+  _agents = {};
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  _tools = [];
   localAgents = {};
   remoteAgents = {};
   subscribers = /* @__PURE__ */ new Set();
+  _runtimeUrl;
+  _runtimeVersion;
+  _runtimeConnectionStatus = "disconnected" /* Disconnected */;
   constructor({
     runtimeUrl,
     headers = {},
     properties = {},
     agents = {},
-    tools = {}
+    tools = []
   }) {
     this.headers = headers;
     this.properties = properties;
-    this.localAgents = agents;
-    this.agents = this.localAgents;
-    this.tools = tools;
+    this.localAgents = this.assignAgentIds(agents);
+    this._agents = this.localAgents;
+    this._tools = tools;
     this.setRuntimeUrl(runtimeUrl);
   }
-  async getRuntimeInfo() {
-    const response = await fetch(`${this.runtimeUrl}/info`, {
-      headers: this.headers
+  assignAgentIds(agents) {
+    Object.entries(agents).forEach(([id, agent]) => {
+      if (agent && !agent.agentId) {
+        agent.agentId = id;
+      }
     });
-    const {
-      version,
-      ...runtimeInfo
-    } = await response.json();
-    const agents = Object.fromEntries(
-      Object.entries(runtimeInfo.agents).map(([id, { description }]) => {
-        const agent = new CopilotKitHttpAgent({
-          runtimeUrl: this.runtimeUrl,
-          agentId: id,
-          description
-        });
-        return [id, agent];
+    return agents;
+  }
+  async notifySubscribers(handler, errorMessage) {
+    await Promise.all(
+      Array.from(this.subscribers).map(async (subscriber) => {
+        try {
+          await handler(subscriber);
+        } catch (error) {
+          logger.error(errorMessage, error);
+        }
       })
     );
-    return { agents, version };
-  }
-  async fetchRemoteAgents() {
-    if (this.runtimeUrl) {
-      this.getRuntimeInfo().then(({ agents, version }) => {
-        this.remoteAgents = agents;
-        this.agents = { ...this.localAgents, ...this.remoteAgents };
-        this.didLoadRuntime = true;
-        this.version = version;
-        this.subscribers.forEach(async (subscriber) => {
-          try {
-            await subscriber.onRuntimeLoaded?.({ copilotkit: this });
-          } catch (error) {
-            logger.error(
-              "Error in CopilotKitCore subscriber (onRuntimeLoaded):",
-              error
-            );
-          }
-        });
-      }).catch((error) => {
-        this.subscribers.forEach(async (subscriber) => {
-          try {
-            await subscriber.onRuntimeLoadError?.({ copilotkit: this });
-          } catch (error2) {
-            logger.error(
-              "Error in CopilotKitCore subscriber (onRuntimeLoadError):",
-              error2
-            );
-          }
-        });
-        logger.warn(`Failed to load runtime info: ${error.message}`);
+  }
+  async emitError({
+    error,
+    code,
+    context = {}
+  }) {
+    await this.notifySubscribers(
+      (subscriber) => subscriber.onError?.({
+        copilotkit: this,
+        error,
+        code,
+        context
+      }),
+      "Subscriber onError error:"
+    );
+  }
+  resolveAgentId(agent, providedAgentId) {
+    if (providedAgentId) {
+      return providedAgentId;
+    }
+    if (agent.agentId) {
+      return agent.agentId;
+    }
+    const found = Object.entries(this._agents).find(([, storedAgent]) => {
+      return storedAgent === agent;
+    });
+    if (found) {
+      agent.agentId = found[0];
+      return found[0];
+    }
+    agent.agentId = DEFAULT_AGENT_ID;
+    return DEFAULT_AGENT_ID;
+  }
+  /**
+   * Snapshot accessors
+   */
+  get context() {
+    return this._context;
+  }
+  get agents() {
+    return this._agents;
+  }
+  get tools() {
+    return this._tools;
+  }
+  get runtimeUrl() {
+    return this._runtimeUrl;
+  }
+  setRuntimeUrl(runtimeUrl) {
+    const normalizedRuntimeUrl = runtimeUrl ? runtimeUrl.replace(/\/$/, "") : void 0;
+    if (this._runtimeUrl === normalizedRuntimeUrl) {
+      return;
+    }
+    this._runtimeUrl = normalizedRuntimeUrl;
+    void this.updateRuntimeConnection();
+  }
+  get runtimeVersion() {
+    return this._runtimeVersion;
+  }
+  get runtimeConnectionStatus() {
+    return this._runtimeConnectionStatus;
+  }
+  /**
+   * Runtime connection
+   */
+  async updateRuntimeConnection() {
+    if (!this.runtimeUrl) {
+      this._runtimeConnectionStatus = "disconnected" /* Disconnected */;
+      this._runtimeVersion = void 0;
+      this.remoteAgents = {};
+      this._agents = this.localAgents;
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onRuntimeConnectionStatusChanged?.({
+          copilotkit: this,
+          status: "disconnected" /* Disconnected */
+        }),
+        "Error in CopilotKitCore subscriber (onRuntimeConnectionStatusChanged):"
+      );
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onAgentsChanged?.({
+          copilotkit: this,
+          agents: this._agents
+        }),
+        "Subscriber onAgentsChanged error:"
+      );
+      return;
+    }
+    this._runtimeConnectionStatus = "connecting" /* Connecting */;
+    await this.notifySubscribers(
+      (subscriber) => subscriber.onRuntimeConnectionStatusChanged?.({
+        copilotkit: this,
+        status: "connecting" /* Connecting */
+      }),
+      "Error in CopilotKitCore subscriber (onRuntimeConnectionStatusChanged):"
+    );
+    try {
+      const response = await fetch(`${this.runtimeUrl}/info`, {
+        headers: this.headers
+      });
+      const {
+        version,
+        ...runtimeInfo
+      } = await response.json();
+      const agents = Object.fromEntries(
+        Object.entries(runtimeInfo.agents).map(([id, { description }]) => {
+          const agent = new ProxiedCopilotRuntimeAgent({
+            runtimeUrl: this.runtimeUrl,
+            agentId: id,
+            description
+          });
+          return [id, agent];
+        })
+      );
+      this.remoteAgents = agents;
+      this._agents = { ...this.localAgents, ...this.remoteAgents };
+      this._runtimeConnectionStatus = "connected" /* Connected */;
+      this._runtimeVersion = version;
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onRuntimeConnectionStatusChanged?.({
+          copilotkit: this,
+          status: "connected" /* Connected */
+        }),
+        "Error in CopilotKitCore subscriber (onRuntimeConnectionStatusChanged):"
+      );
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onAgentsChanged?.({
+          copilotkit: this,
+          agents: this._agents
+        }),
+        "Subscriber onAgentsChanged error:"
+      );
+    } catch (error) {
+      this._runtimeConnectionStatus = "error" /* Error */;
+      this._runtimeVersion = void 0;
+      this.remoteAgents = {};
+      this._agents = this.localAgents;
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onRuntimeConnectionStatusChanged?.({
+          copilotkit: this,
+          status: "error" /* Error */
+        }),
+        "Error in CopilotKitCore subscriber (onRuntimeConnectionStatusChanged):"
+      );
+      await this.notifySubscribers(
+        (subscriber) => subscriber.onAgentsChanged?.({
+          copilotkit: this,
+          agents: this._agents
+        }),
+        "Subscriber onAgentsChanged error:"
+      );
+      const message = error instanceof Error ? error.message : JSON.stringify(error);
+      logger.warn(
+        `Failed to load runtime info (${this.runtimeUrl}/info): ${message}`
+      );
+      const runtimeError = error instanceof Error ? error : new Error(String(error));
+      await this.emitError({
+        error: runtimeError,
+        code: "runtime_info_fetch_failed" /* RUNTIME_INFO_FETCH_FAILED */,
+        context: {
+          runtimeUrl: this.runtimeUrl
+        }
       });
     }
   }
+  /**
+   * Configuration updates
+   */
+  setHeaders(headers) {
+    this.headers = headers;
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onHeadersChanged?.({
+        copilotkit: this,
+        headers: this.headers
+      }),
+      "Subscriber onHeadersChanged error:"
+    );
+  }
+  setProperties(properties) {
+    this.properties = properties;
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onPropertiesChanged?.({
+        copilotkit: this,
+        properties: this.properties
+      }),
+      "Subscriber onPropertiesChanged error:"
+    );
+  }
   setAgents(agents) {
-    this.localAgents = agents;
-    this.agents = { ...this.localAgents, ...this.remoteAgents };
+    this.localAgents = this.assignAgentIds(agents);
+    this._agents = { ...this.localAgents, ...this.remoteAgents };
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onAgentsChanged?.({
+        copilotkit: this,
+        agents: this._agents
+      }),
+      "Subscriber onAgentsChanged error:"
+    );
   }
   addAgent({ id, agent }) {
     this.localAgents[id] = agent;
-    this.agents = { ...this.localAgents, ...this.remoteAgents };
+    if (!agent.agentId) {
+      agent.agentId = id;
+    }
+    this._agents = { ...this.localAgents, ...this.remoteAgents };
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onAgentsChanged?.({
+        copilotkit: this,
+        agents: this._agents
+      }),
+      "Subscriber onAgentsChanged error:"
+    );
   }
   removeAgent(id) {
     delete this.localAgents[id];
-    this.agents = { ...this.localAgents, ...this.remoteAgents };
+    this._agents = { ...this.localAgents, ...this.remoteAgents };
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onAgentsChanged?.({
+        copilotkit: this,
+        agents: this._agents
+      }),
+      "Subscriber onAgentsChanged error:"
+    );
   }
   getAgent(id) {
-    if (id in this.agents) {
-      return this.agents[id];
+    if (id in this._agents) {
+      return this._agents[id];
+    }
+    if (this.runtimeUrl !== void 0 && (this.runtimeConnectionStatus === "disconnected" /* Disconnected */ || this.runtimeConnectionStatus === "connecting" /* Connecting */)) {
+      return void 0;
     } else {
-      if (!this.didLoadRuntime) {
-        return void 0;
-      } else {
-        throw new Error(`Agent ${id} not found`);
-      }
+      console.warn(`Agent ${id} not found`);
+      return void 0;
     }
   }
+  /**
+   * Context management
+   */
   addContext({ description, value }) {
     const id = randomUUID();
-    this.context[id] = { description, value };
+    this._context[id] = { description, value };
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onContextChanged?.({
+        copilotkit: this,
+        context: this._context
+      }),
+      "Subscriber onContextChanged error:"
+    );
     return id;
   }
   removeContext(id) {
-    delete this.context[id];
-  }
-  setRuntimeUrl(runtimeUrl) {
-    this.runtimeUrl = runtimeUrl ? runtimeUrl.replace(/\/$/, "") : void 0;
-    this.fetchRemoteAgents();
+    delete this._context[id];
+    void this.notifySubscribers(
+      (subscriber) => subscriber.onContextChanged?.({
+        copilotkit: this,
+        context: this._context
+      }),
+      "Subscriber onContextChanged error:"
+    );
   }
+  /**
+   * Tool management
+   */
   addTool(tool) {
-    if (tool.name in this.tools) {
-      logger.warn(`Tool already exists: '${tool.name}', skipping.`);
+    const existingToolIndex = this._tools.findIndex(
+      (t) => t.name === tool.name && t.agentId === tool.agentId
+    );
+    if (existingToolIndex !== -1) {
+      logger.warn(
+        `Tool already exists: '${tool.name}' for agent '${tool.agentId || "global"}', skipping.`
+      );
       return;
     }
-    this.tools[tool.name] = tool;
+    this._tools.push(tool);
   }
-  removeTool(id) {
-    delete this.tools[id];
+  removeTool(id, agentId) {
+    this._tools = this._tools.filter((tool) => {
+      if (agentId !== void 0) {
+        return !(tool.name === id && tool.agentId === agentId);
+      }
+      return !(tool.name === id && !tool.agentId);
+    });
   }
-  setHeaders(headers) {
-    this.headers = headers;
+  /**
+   * Get a tool by name and optionally by agentId.
+   * If agentId is provided, it will first look for an agent-specific tool,
+   * then fall back to a global tool with the same name.
+   */
+  getTool(params) {
+    const { toolName, agentId } = params;
+    if (agentId) {
+      const agentTool = this._tools.find(
+        (tool) => tool.name === toolName && tool.agentId === agentId
+      );
+      if (agentTool) {
+        return agentTool;
+      }
+    }
+    return this._tools.find((tool) => tool.name === toolName && !tool.agentId);
   }
-  setProperties(properties) {
-    this.properties = properties;
+  /**
+   * Set all tools at once. Replaces existing tools.
+   */
+  setTools(tools) {
+    this._tools = [...tools];
   }
+  /**
+   * Subscription lifecycle
+   */
   subscribe(subscriber) {
     this.subscribers.add(subscriber);
     return () => {
@@ -167,19 +413,83 @@ var CopilotKitCore = class {
   unsubscribe(subscriber) {
     this.subscribers.delete(subscriber);
   }
-  // TODO: AG-UI needs to expose the runAgent result type
+  /**
+   * Agent connectivity
+   */
+  async connectAgent({
+    agent,
+    agentId
+  }) {
+    try {
+      if (agent instanceof HttpAgent2) {
+        agent.headers = { ...this.headers };
+      }
+      const runAgentResult = await agent.connectAgent(
+        {
+          forwardedProps: this.properties,
+          tools: this.buildFrontendTools(agentId)
+        },
+        this.createAgentErrorSubscriber(agent, agentId)
+      );
+      return this.processAgentResult({ runAgentResult, agent, agentId });
+    } catch (error) {
+      const connectError = error instanceof Error ? error : new Error(String(error));
+      const context = {};
+      if (agentId ?? agent.agentId) {
+        context.agentId = agentId ?? agent.agentId;
+      }
+      await this.emitError({
+        error: connectError,
+        code: "agent_connect_failed" /* AGENT_CONNECT_FAILED */,
+        context
+      });
+      throw error;
+    }
+  }
   async runAgent({
     agent,
     withMessages,
     agentId
   }) {
+    if (agent instanceof HttpAgent2) {
+      agent.headers = { ...this.headers };
+    }
     if (withMessages) {
       agent.addMessages(withMessages);
     }
-    const runAgentResult = await agent.runAgent({
-      forwardedProps: this.properties
-    });
+    try {
+      const runAgentResult = await agent.runAgent(
+        {
+          forwardedProps: this.properties,
+          tools: this.buildFrontendTools(agentId)
+        },
+        this.createAgentErrorSubscriber(agent, agentId)
+      );
+      return this.processAgentResult({ runAgentResult, agent, agentId });
+    } catch (error) {
+      const runError = error instanceof Error ? error : new Error(String(error));
+      const context = {};
+      if (agentId ?? agent.agentId) {
+        context.agentId = agentId ?? agent.agentId;
+      }
+      if (withMessages) {
+        context.messageCount = withMessages.length;
+      }
+      await this.emitError({
+        error: runError,
+        code: "agent_run_failed" /* AGENT_RUN_FAILED */,
+        context
+      });
+      throw error;
+    }
+  }
+  async processAgentResult({
+    runAgentResult,
+    agent,
+    agentId
+  }) {
     const { newMessages } = runAgentResult;
+    const effectiveAgentId = this.resolveAgentId(agent, agentId);
     let needsFollowUp = false;
     for (const message of newMessages) {
       if (message.role === "assistant") {
@@ -187,76 +497,214 @@ var CopilotKitCore = class {
           if (newMessages.findIndex(
             (m) => m.role === "tool" && m.toolCallId === toolCall.id
           ) === -1) {
-            if (toolCall.function.name in this.tools) {
-              const tool = this.tools[toolCall.function.name];
+            const tool = this.getTool({
+              toolName: toolCall.function.name,
+              agentId
+            });
+            if (tool) {
               if (tool?.agentId && tool.agentId !== agentId) {
                 continue;
               }
               let toolCallResult = "";
+              let errorMessage;
+              let isArgumentError = false;
               if (tool?.handler) {
-                const args = JSON.parse(toolCall.function.arguments);
+                let parsedArgs;
                 try {
-                  const result = await tool.handler(args);
-                  if (result === void 0 || result === null) {
-                    toolCallResult = "";
-                  } else if (typeof result === "string") {
-                    toolCallResult = result;
-                  } else {
-                    toolCallResult = JSON.stringify(result);
-                  }
+                  parsedArgs = JSON.parse(toolCall.function.arguments);
                 } catch (error) {
-                  toolCallResult = `Error: ${error instanceof Error ? error.message : String(error)}`;
+                  const parseError = error instanceof Error ? error : new Error(String(error));
+                  errorMessage = parseError.message;
+                  isArgumentError = true;
+                  await this.emitError({
+                    error: parseError,
+                    code: "tool_argument_parse_failed" /* TOOL_ARGUMENT_PARSE_FAILED */,
+                    context: {
+                      agentId: effectiveAgentId,
+                      toolCallId: toolCall.id,
+                      toolName: toolCall.function.name,
+                      rawArguments: toolCall.function.arguments,
+                      toolType: "specific",
+                      messageId: message.id
+                    }
+                  });
+                }
+                await this.notifySubscribers(
+                  (subscriber) => subscriber.onToolExecutionStart?.({
+                    copilotkit: this,
+                    toolCallId: toolCall.id,
+                    agentId: effectiveAgentId,
+                    toolName: toolCall.function.name,
+                    args: parsedArgs
+                  }),
+                  "Subscriber onToolExecutionStart error:"
+                );
+                if (!errorMessage) {
+                  try {
+                    const result = await tool.handler(parsedArgs);
+                    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.emitError({
+                      error: handlerError,
+                      code: "tool_handler_failed" /* TOOL_HANDLER_FAILED */,
+                      context: {
+                        agentId: effectiveAgentId,
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.function.name,
+                        parsedArgs,
+                        toolType: "specific",
+                        messageId: message.id
+                      }
+                    });
+                  }
+                }
+                if (errorMessage) {
+                  toolCallResult = `Error: ${errorMessage}`;
+                }
+                await this.notifySubscribers(
+                  (subscriber) => subscriber.onToolExecutionEnd?.({
+                    copilotkit: this,
+                    toolCallId: toolCall.id,
+                    agentId: effectiveAgentId,
+                    toolName: toolCall.function.name,
+                    result: errorMessage ? "" : toolCallResult,
+                    error: errorMessage
+                  }),
+                  "Subscriber onToolExecutionEnd error:"
+                );
+                if (isArgumentError) {
+                  throw new Error(errorMessage ?? "Tool execution failed");
                 }
               }
-              const messageIndex = agent.messages.findIndex(
-                (m) => m.id === message.id
-              );
-              const toolMessage = {
-                id: randomUUID(),
-                role: "tool",
-                toolCallId: toolCall.id,
-                content: toolCallResult
-              };
-              agent.messages.splice(messageIndex + 1, 0, toolMessage);
-              if (tool?.followUp !== false) {
-                needsFollowUp = true;
-              }
-            } else if ("*" in this.tools) {
-              const wildcardTool = this.tools["*"];
-              if (wildcardTool?.agentId && wildcardTool.agentId !== agentId) {
-                continue;
-              }
-              let toolCallResult = "";
-              if (wildcardTool?.handler) {
-                const wildcardArgs = {
-                  toolName: toolCall.function.name,
-                  args: JSON.parse(toolCall.function.arguments)
+              if (!errorMessage || !isArgumentError) {
+                const messageIndex = agent.messages.findIndex(
+                  (m) => m.id === message.id
+                );
+                const toolMessage = {
+                  id: randomUUID(),
+                  role: "tool",
+                  toolCallId: toolCall.id,
+                  content: toolCallResult
                 };
-                try {
-                  const result = await wildcardTool.handler(wildcardArgs);
-                  if (result === void 0 || result === null) {
-                    toolCallResult = "";
-                  } else if (typeof result === "string") {
-                    toolCallResult = result;
-                  } else {
-                    toolCallResult = JSON.stringify(result);
-                  }
-                } catch (error) {
-                  toolCallResult = `Error: ${error instanceof Error ? error.message : String(error)}`;
+                agent.messages.splice(messageIndex + 1, 0, toolMessage);
+                if (!errorMessage && tool?.followUp !== false) {
+                  needsFollowUp = true;
                 }
               }
-              const messageIndex = agent.messages.findIndex(
-                (m) => m.id === message.id
-              );
-              const toolMessage = {
-                id: randomUUID(),
-                role: "tool",
-                toolCallId: toolCall.id,
-                content: toolCallResult
-              };
-              agent.messages.splice(messageIndex + 1, 0, toolMessage);
-              if (wildcardTool?.followUp !== false) {
-                needsFollowUp = true;
+            } else {
+              const wildcardTool = this.getTool({ toolName: "*", agentId });
+              if (wildcardTool) {
+                if (wildcardTool?.agentId && wildcardTool.agentId !== agentId) {
+                  continue;
+                }
+                let toolCallResult = "";
+                let errorMessage;
+                let isArgumentError = false;
+                if (wildcardTool?.handler) {
+                  let parsedArgs;
+                  try {
+                    parsedArgs = JSON.parse(toolCall.function.arguments);
+                  } catch (error) {
+                    const parseError = error instanceof Error ? error : new Error(String(error));
+                    errorMessage = parseError.message;
+                    isArgumentError = true;
+                    await this.emitError({
+                      error: parseError,
+                      code: "tool_argument_parse_failed" /* TOOL_ARGUMENT_PARSE_FAILED */,
+                      context: {
+                        agentId: effectiveAgentId,
+                        toolCallId: toolCall.id,
+                        toolName: toolCall.function.name,
+                        rawArguments: toolCall.function.arguments,
+                        toolType: "wildcard",
+                        messageId: message.id
+                      }
+                    });
+                  }
+                  const wildcardArgs = {
+                    toolName: toolCall.function.name,
+                    args: parsedArgs
+                  };
+                  await this.notifySubscribers(
+                    (subscriber) => subscriber.onToolExecutionStart?.({
+                      copilotkit: this,
+                      toolCallId: toolCall.id,
+                      agentId: effectiveAgentId,
+                      toolName: toolCall.function.name,
+                      args: wildcardArgs
+                    }),
+                    "Subscriber onToolExecutionStart error:"
+                  );
+                  if (!errorMessage) {
+                    try {
+                      const result = await wildcardTool.handler(
+                        wildcardArgs
+                      );
+                      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.emitError({
+                        error: handlerError,
+                        code: "tool_handler_failed" /* TOOL_HANDLER_FAILED */,
+                        context: {
+                          agentId: effectiveAgentId,
+                          toolCallId: toolCall.id,
+                          toolName: toolCall.function.name,
+                          parsedArgs: wildcardArgs,
+                          toolType: "wildcard",
+                          messageId: message.id
+                        }
+                      });
+                    }
+                  }
+                  if (errorMessage) {
+                    toolCallResult = `Error: ${errorMessage}`;
+                  }
+                  await this.notifySubscribers(
+                    (subscriber) => subscriber.onToolExecutionEnd?.({
+                      copilotkit: this,
+                      toolCallId: toolCall.id,
+                      agentId: effectiveAgentId,
+                      toolName: toolCall.function.name,
+                      result: errorMessage ? "" : toolCallResult,
+                      error: errorMessage
+                    }),
+                    "Subscriber onToolExecutionEnd error:"
+                  );
+                  if (isArgumentError) {
+                    throw new Error(errorMessage ?? "Tool execution failed");
+                  }
+                }
+                if (!errorMessage || !isArgumentError) {
+                  const messageIndex = agent.messages.findIndex(
+                    (m) => m.id === message.id
+                  );
+                  const toolMessage = {
+                    id: randomUUID(),
+                    role: "tool",
+                    toolCallId: toolCall.id,
+                    content: toolCallResult
+                  };
+                  agent.messages.splice(messageIndex + 1, 0, toolMessage);
+                  if (!errorMessage && wildcardTool?.followUp !== false) {
+                    needsFollowUp = true;
+                  }
+                }
               }
             }
           }
@@ -268,7 +716,82 @@ var CopilotKitCore = class {
     }
     return runAgentResult;
   }
+  buildFrontendTools(agentId) {
+    return this._tools.filter((tool) => !tool.agentId || tool.agentId === agentId).map((tool) => ({
+      name: tool.name,
+      description: tool.description ?? "",
+      parameters: createToolSchema(tool)
+    }));
+  }
+  createAgentErrorSubscriber(agent, agentId) {
+    const emitAgentError = async (error, code, extraContext = {}) => {
+      const context = { ...extraContext };
+      if (agentId ?? agent.agentId) {
+        context.agentId = agentId ?? agent.agentId;
+      }
+      await this.emitError({
+        error,
+        code,
+        context
+      });
+    };
+    return {
+      onRunFailed: async ({ error }) => {
+        await emitAgentError(
+          error,
+          "agent_run_failed_event" /* AGENT_RUN_FAILED_EVENT */,
+          {
+            source: "onRunFailed"
+          }
+        );
+      },
+      onRunErrorEvent: async ({ event }) => {
+        const eventError = event?.rawEvent instanceof Error ? event.rawEvent : event?.rawEvent?.error instanceof Error ? event.rawEvent.error : void 0;
+        const errorMessage = typeof event?.rawEvent?.error === "string" ? event.rawEvent.error : event?.message ?? "Agent run error";
+        const rawError = eventError ?? new Error(errorMessage);
+        if (event?.code && !rawError.code) {
+          rawError.code = event.code;
+        }
+        await emitAgentError(
+          rawError,
+          "agent_run_error_event" /* AGENT_RUN_ERROR_EVENT */,
+          {
+            source: "onRunErrorEvent",
+            event,
+            runtimeErrorCode: event?.code
+          }
+        );
+      }
+    };
+  }
 };
+var EMPTY_TOOL_SCHEMA = {
+  type: "object",
+  properties: {},
+  additionalProperties: false
+};
+function createToolSchema(tool) {
+  if (!tool.parameters) {
+    return EMPTY_TOOL_SCHEMA;
+  }
+  const rawSchema = zodToJsonSchema(tool.parameters, {
+    $refStrategy: "none"
+  });
+  if (!rawSchema || typeof rawSchema !== "object") {
+    return { ...EMPTY_TOOL_SCHEMA };
+  }
+  const { $schema, ...schema } = rawSchema;
+  if (typeof schema.type !== "string") {
+    schema.type = "object";
+  }
+  if (typeof schema.properties !== "object" || schema.properties === null) {
+    schema.properties = {};
+  }
+  if (schema.additionalProperties === void 0) {
+    schema.additionalProperties = false;
+  }
+  return schema;
+}
 
 // src/types.ts
 var ToolCallStatus = /* @__PURE__ */ ((ToolCallStatus2) => {
@@ -495,7 +1018,9 @@ ${indent}${fence}`;
 }
 export {
   CopilotKitCore,
-  CopilotKitHttpAgent,
+  CopilotKitCoreErrorCode,
+  CopilotKitCoreRuntimeConnectionStatus,
+  ProxiedCopilotRuntimeAgent,
   ToolCallStatus,
   completePartialMarkdown
 };