@copilotkit/runtime 1.9.2-next.9 → 1.9.3-next.0

package/src/lib/runtime/copilot-runtime.ts

@@ -20,13 +20,12 @@ import {
   CopilotKitApiDiscoveryError,
   randomId,
   CopilotKitError,
-  CopilotKitRemoteEndpointDiscoveryError,
   CopilotKitAgentDiscoveryError,
   CopilotKitMisuseError,
   CopilotKitErrorCode,
   CopilotKitLowLevelError,
-  CopilotTraceHandler,
-  CopilotTraceEvent,
+  CopilotErrorHandler,
+  CopilotErrorEvent,
   CopilotRequestContext,
   ensureStructuredError,
 } from "@copilotkit/shared";
@@ -66,7 +65,7 @@ import { ExtensionsInput } from "../../graphql/inputs/extensions.input";
 import { ExtensionsResponse } from "../../graphql/types/extensions-response.type";
 import { LoadAgentStateResponse } from "../../graphql/types/load-agent-state-response.type";
 import { Client as LangGraphClient } from "@langchain/langgraph-sdk";
-import { langchainMessagesToCopilotKit, isUserConfigurationError } from "./remote-lg-action";
+import { langchainMessagesToCopilotKit } from "./remote-lg-action";
 import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import {
   CopilotObservabilityConfig,
@@ -283,23 +282,23 @@ export interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []
   createMCPClient?: CreateMCPClientFunction;
 
   /**
-   * Optional trace handler for comprehensive debugging and observability.
+   * Optional error handler for comprehensive debugging and observability.
    *
-   * **Requires publicApiKey**: Tracing only works when requests include a valid publicApiKey.
+   * **Requires publicApiKey**: Error handling only works when requests include a valid publicApiKey.
    * This is a premium CopilotKit Cloud feature.
    *
-   * @param traceEvent - Structured trace event with rich debugging context
+   * @param errorEvent - Structured error event with rich debugging context
    *
    * @example
    * ```typescript
    * const runtime = new CopilotRuntime({
-   *   onTrace: (traceEvent) => {
-   *     debugDashboard.capture(traceEvent);
+   *   onError: (errorEvent) => {
+   *     debugDashboard.capture(errorEvent);
    *   }
    * });
    * ```
    */
-  onTrace?: CopilotTraceHandler;
+  onError?: CopilotErrorHandler;
 }
 
 export class CopilotRuntime<const T extends Parameter[] | [] = []> {
@@ -312,8 +311,8 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
   private delegateAgentProcessingToServiceAdapter: boolean;
   private observability?: CopilotObservabilityConfig;
   private availableAgents: Pick<AgentWithEndpoint, "name" | "id">[];
-  private onTrace?: CopilotTraceHandler;
-  private hasWarnedAboutTracing = false;
+  private onError?: CopilotErrorHandler;
+  private hasWarnedAboutError = false;
 
   // +++ MCP Properties +++
   private readonly mcpServersConfig?: MCPEndpointConfig[];
@@ -362,7 +361,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       params?.delegateAgentProcessingToServiceAdapter || false;
     this.observability = params?.observability_c;
     this.agents = params?.agents ?? {};
-    this.onTrace = params?.onTrace;
+    this.onError = params?.onError;
     // +++ MCP Initialization +++
     this.mcpServersConfig = params?.mcpServers;
     this.createMCPClientImpl = params?.createMCPClient;
@@ -440,9 +439,7 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
     }
 
     const instructions =
-      "You have access to the following tools provided by external Model Context Protocol (MCP) servers:\n" +
-      mcpToolInstructions +
-      "\nUse them when appropriate to fulfill the user's request.";
+      mcpToolInstructions + "\nUse them when appropriate to fulfill the user's request.";
 
     const systemMessageIndex = messages.findIndex((msg) => msg.textMessage?.role === "system");
 
@@ -489,16 +486,11 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
       publicApiKey,
     } = request;
 
-    const eventSource = new RuntimeEventSource();
-    // Track request start time for logging
-    const requestStartTime = Date.now();
-    // For storing streamed chunks if progressive logging is enabled
-    const streamedChunks: any[] = [];
-
-    // Trace request start
-    await this.trace(
-      "request",
-      {
+    const eventSource = new RuntimeEventSource({
+      errorHandler: async (error, context) => {
+        await this.error("error", context, error, publicApiKey);
+      },
+      errorContext: {
         threadId,
         runId,
         source: "runtime",
@@ -506,20 +498,18 @@ export class CopilotRuntime<const T extends Parameter[] | [] = []> {
           operation: "processRuntimeRequest",
           method: "POST",
           url: url,
-          startTime: requestStartTime,
+          startTime: Date.now(),
         },
         agent: agentSession ? { name: agentSession.agentName } : undefined,
-        messages: {
-          input: rawMessages,
-          messageCount: rawMessages.length,
-        },
         technical: {
           environment: process.env.NODE_ENV,
         },
       },
-      undefined,
-      publicApiKey,
-    );
+    });
+    // Track request start time for logging
+    const requestStartTime = Date.now();
+    // For storing streamed chunks if progressive logging is enabled
+    const streamedChunks: any[] = [];
 
     try {
       if (
@@ -755,8 +745,8 @@ please use an LLM adapter instead.`,
         );
       }
 
-      // Trace the error
-      await this.trace(
+      // Track the error
+      await this.error(
         "error",
         {
           threadId,
@@ -787,10 +777,8 @@ please use an LLM adapter instead.`,
   }
 
   async getAllAgents(graphqlContext: GraphQLContext): Promise<(AgentWithEndpoint | Agent)[]> {
-    const [agentsWithEndpoints, aguiAgents] = await Promise.all([
-      this.discoverAgentsFromEndpoints(graphqlContext),
-      this.discoverAgentsFromAgui(),
-    ]);
+    const agentsWithEndpoints = await this.discoverAgentsFromEndpoints(graphqlContext);
+    const aguiAgents = this.discoverAgentsFromAgui();
 
     this.availableAgents = [...agentsWithEndpoints, ...aguiAgents].map((a) => ({
       name: a.name,
@@ -885,39 +873,12 @@ please use an LLM adapter instead.`,
     return agents;
   }
 
-  async discoverAgentsFromAgui(): Promise<AgentWithEndpoint[]> {
-    const agents: Promise<AgentWithEndpoint[]> = Object.values(this.agents ?? []).reduce(
-      async (acc: Promise<Agent[]>, agent: LangGraphAgent) => {
-        const agents = await acc;
-
-        const client = agent.client;
-        let data: Array<{ assistant_id: string; graph_id: string }> | { detail: string } = [];
-        try {
-          data = await client.assistants.search();
-
-          if (data && "detail" in data && (data.detail as string).toLowerCase() === "not found") {
-            throw new CopilotKitAgentDiscoveryError({ availableAgents: this.availableAgents });
-          }
-        } catch (e) {
-          throw new CopilotKitMisuseError({
-            message: `
-              Failed to find or contact agent ${agent.graphId}.
-              Make sure the LangGraph API is running and the agent is defined in langgraph.json
-              
-              See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
-          });
-        }
-        const endpointAgents = data.map((entry) => ({
-          name: entry.graph_id,
-          id: entry.assistant_id,
-          description: "",
-        }));
-        return [...agents, ...endpointAgents];
-      },
-      Promise.resolve([]),
-    );
-
-    return agents;
+  discoverAgentsFromAgui(): Agent[] {
+    return Object.entries(this.agents ?? []).map(([key, agent]: [string, AbstractAgent]) => ({
+      name: (agent as any).agentName ?? key,
+      id: agent.agentId ?? key,
+      description: agent.description ?? "",
+    }));
   }
 
   async loadAgentState(
@@ -992,37 +953,43 @@ please use an LLM adapter instead.`,
       ? { authorization: `Bearer ${graphqlContext.properties.authorization}` }
       : null;
 
-    let client: LangGraphClient;
-    if ("endpoint" in agent && agent.endpoint.type === EndpointType.LangGraphPlatform) {
-      client = new LangGraphClient({
-        apiUrl: agent.endpoint.deploymentUrl,
-        apiKey: agent.endpoint.langsmithApiKey,
-        defaultHeaders: { ...propertyHeaders },
-      });
-    } else {
-      const aguiAgent = graphqlContext._copilotkit.runtime.agents[agent.name] as LangGraphAgent;
-      if (!aguiAgent) {
-        throw new Error(`Agent: ${agent.name} could not be resolved`);
-      }
-      // @ts-expect-error -- both clients are the same
-      client = aguiAgent.client;
-    }
     let state: any = {};
     try {
-      state = (await client.threads.getState(threadId)).values as any;
+      let client: LangGraphClient | null;
+      if ("endpoint" in agent && agent.endpoint.type === EndpointType.LangGraphPlatform) {
+        client = new LangGraphClient({
+          apiUrl: agent.endpoint.deploymentUrl,
+          apiKey: agent.endpoint.langsmithApiKey,
+          defaultHeaders: { ...propertyHeaders },
+        });
+      } else {
+        const aguiAgent = graphqlContext._copilotkit.runtime.agents[agent.name] as LangGraphAgent;
+        if (!aguiAgent) {
+          throw new Error(`Agent: ${agent.name} could not be resolved`);
+        }
+        // @ts-expect-error -- both clients are the same
+        client = aguiAgent.client ?? null;
+      }
+
+      state = client ? ((await client.threads.getState(threadId)).values as any) : {};
     } catch (error) {
       // All errors from agent state loading are user configuration issues
       const errorMessage = error instanceof Error ? error.message : String(error);
+      const errorStatus = error?.response?.status || error?.status;
 
-      // Log user configuration errors at debug level to reduce noise
-      console.debug(`Agent '${agentName}' configuration issue: ${errorMessage}`);
-
-      // Throw a configuration error - all agent state loading failures are user setup issues
-      throw new ResolvedCopilotKitError({
-        status: 400,
-        message: `Agent '${agentName}' failed to execute: ${errorMessage}`,
-        code: CopilotKitErrorCode.CONFIGURATION_ERROR,
-      });
+      if (errorStatus === 404) {
+        state = {};
+      } else {
+        // Log user configuration errors at debug level to reduce noise
+        console.debug(`Agent '${agentName}' configuration issue: ${errorMessage}`);
+
+        // Throw a configuration error - all agent state loading failures are user setup issues
+        throw new ResolvedCopilotKitError({
+          status: 400,
+          message: `Agent '${agentName}' failed to execute: ${errorMessage}`,
+          code: CopilotKitErrorCode.CONFIGURATION_ERROR,
+        });
+      }
     }
 
     if (Object.keys(state).length === 0) {
@@ -1069,8 +1036,8 @@ please use an LLM adapter instead.`,
     // for backwards compatibility, deal with the case when no threadId is provided
     const threadId = threadIdFromRequest ?? agentSession.threadId;
 
-    // Trace agent request start
-    await this.trace(
+    // Track agent request start
+    await this.error(
       "agent_state",
       {
         threadId,
@@ -1160,7 +1127,27 @@ please use an LLM adapter instead.`,
     });
 
     try {
-      const eventSource = new RuntimeEventSource();
+      const eventSource = new RuntimeEventSource({
+        errorHandler: async (error, context) => {
+          await this.error("error", context, error, publicApiKey);
+        },
+        errorContext: {
+          threadId,
+          source: "agent",
+          request: {
+            operation: "processAgentRequest",
+            method: "POST",
+            startTime: requestStartTime,
+          },
+          agent: {
+            name: agentName,
+            nodeName: nodeName,
+          },
+          technical: {
+            environment: process.env.NODE_ENV,
+          },
+        },
+      });
       const stream = await currentAgent.remoteAgentHandler({
         name: agentName,
         threadId,
@@ -1250,8 +1237,8 @@ please use an LLM adapter instead.`,
               this.convertStreamingErrorToStructured(error),
             );
 
-            // Trace streaming errors
-            await this.trace(
+            // Track streaming errors
+            await this.error(
               "error",
               {
                 threadId,
@@ -1360,8 +1347,8 @@ please use an LLM adapter instead.`,
         this.convertStreamingErrorToStructured(err),
       );
 
-      // Trace the agent error
-      await this.trace(
+      // Track the agent error
+      await this.error(
         "error",
         {
           threadId,
@@ -1420,6 +1407,7 @@ please use an LLM adapter instead.`,
       frontendUrl: url,
       agents: this.agents,
       metaEvents: request.metaEvents,
+      nodeName: request.agentSession?.nodeName,
     });
 
     const configuredActions =
@@ -1533,45 +1521,45 @@ please use an LLM adapter instead.`,
     });
   }
 
-  private async trace(
-    type: CopilotTraceEvent["type"],
+  private async error(
+    type: CopilotErrorEvent["type"],
     context: CopilotRequestContext,
     error?: any,
     publicApiKey?: string,
   ): Promise<void> {
-    if (!this.onTrace) return;
+    if (!this.onError) return;
 
     // Just check if publicApiKey is defined (regardless of validity)
     if (!publicApiKey) {
-      if (!this.hasWarnedAboutTracing) {
+      if (!this.hasWarnedAboutError) {
         console.warn(
-          "CopilotKit: onTrace handler provided but requires publicApiKey to be defined for tracing to work.",
+          "CopilotKit: onError handler provided but requires publicApiKey to be defined for error handling to work.",
         );
-        this.hasWarnedAboutTracing = true;
+        this.hasWarnedAboutError = true;
       }
       return;
     }
 
     try {
-      const traceEvent: CopilotTraceEvent = {
+      const errorEvent: CopilotErrorEvent = {
         type,
         timestamp: Date.now(),
         context,
         ...(error && { error }),
       };
 
-      await this.onTrace(traceEvent);
-    } catch (traceError) {
-      // Don't let trace errors break the main flow
-      console.error("Error in onTrace handler:", traceError);
+      await this.onError(errorEvent);
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
     }
   }
 
   /**
-   * Public method to trace GraphQL validation errors
-   * This allows the GraphQL resolver to send validation errors through the trace system
+   * Public method to handle GraphQL validation errors
+   * This allows the GraphQL resolver to send validation errors through the error system
    */
-  public async traceGraphQLError(
+  public async errorGraphQLError(
     error: { message: string; code: string; type: string },
     context: {
       operation: string;
@@ -1579,10 +1567,10 @@ please use an LLM adapter instead.`,
       guardrailsEnabled: boolean;
     },
   ): Promise<void> {
-    if (!this.onTrace) return;
+    if (!this.onError) return;
 
     try {
-      await this.onTrace({
+      await this.onError({
         type: "error",
         timestamp: Date.now(),
         context: {
@@ -1602,9 +1590,9 @@ please use an LLM adapter instead.`,
         },
         error,
       });
-    } catch (traceError) {
-      // Don't let trace errors break the main flow
-      console.error("Error in onTrace handler:", traceError);
+    } catch (errorHandlerError) {
+      // Don't let error handler errors break the main flow
+      console.error("Error in onError handler:", errorHandlerError);
     }
   }
 }

package/src/lib/runtime/mcp-tools-utils.ts

@@ -14,7 +14,7 @@ export interface MCPTool {
     };
   };
   /** The function to call to execute the tool on the MCP server. */
-  execute(options: { params: any }): Promise<any>;
+  execute(params: any): Promise<any>;
 }
 
 /**
@@ -51,7 +51,7 @@ export function extractParametersFromSchema(
       ? (toolOrSchema as MCPTool).schema
       : (toolOrSchema as MCPTool["schema"]);
 
-  const toolParameters = schema?.parameters || schema?.parameters?.jsonSchema;
+  const toolParameters = schema?.parameters?.jsonSchema || schema?.parameters;
   const properties = toolParameters?.properties;
   const requiredParams = new Set(toolParameters?.required || []);
 
@@ -62,15 +62,45 @@ export function extractParametersFromSchema(
   for (const paramName in properties) {
     if (Object.prototype.hasOwnProperty.call(properties, paramName)) {
       const paramDef = properties[paramName];
+
+      // Enhanced type extraction with support for complex types
+      let type = paramDef.type || "string";
+      let description = paramDef.description || "";
+
+      // Handle arrays with items
+      if (type === "array" && paramDef.items) {
+        const itemType = paramDef.items.type || "object";
+        if (itemType === "object" && paramDef.items.properties) {
+          // For arrays of objects, describe the structure
+          const itemProperties = Object.keys(paramDef.items.properties).join(", ");
+          description =
+            description +
+            (description ? " " : "") +
+            `Array of objects with properties: ${itemProperties}`;
+        } else {
+          // For arrays of primitives
+          type = `array<${itemType}>`;
+        }
+      }
+
+      // Handle enums
+      if (paramDef.enum && Array.isArray(paramDef.enum)) {
+        const enumValues = paramDef.enum.join(" | ");
+        description = description + (description ? " " : "") + `Allowed values: ${enumValues}`;
+      }
+
+      // Handle objects with properties
+      if (type === "object" && paramDef.properties) {
+        const objectProperties = Object.keys(paramDef.properties).join(", ");
+        description =
+          description + (description ? " " : "") + `Object with properties: ${objectProperties}`;
+      }
+
       parameters.push({
         name: paramName,
-        // Infer type, default to string. MCP schemas might have more complex types.
-        // This might need refinement based on common MCP schema practices.
-        type: paramDef.type || "string",
-        description: paramDef.description,
+        type: type,
+        description: description,
         required: requiredParams.has(paramName),
-        // Attributes might not directly map, handle if necessary
-        // attributes: paramDef.attributes || undefined,
       });
     }
   }
@@ -95,7 +125,7 @@ export function convertMCPToolsToActions(
 
     const handler = async (params: any): Promise<any> => {
       try {
-        const result = await tool.execute({ params });
+        const result = await tool.execute(params);
         // Ensure the result is a string or stringify it, as required by many LLMs.
         // This might need adjustment depending on how different LLMs handle tool results.
         return typeof result === "string" ? result : JSON.stringify(result);
@@ -148,16 +178,49 @@ export function generateMcpToolInstructions(toolsMap: Record<string, MCPTool>):
         if (tool.schema && typeof tool.schema === "object") {
           const schema = tool.schema as any;
 
-          // Extract parameters from JSON Schema
-          if (schema.properties) {
-            const requiredParams = schema.required || [];
+          // Extract parameters from JSON Schema - check both schema.parameters.properties and schema.properties
+          const toolParameters = schema.parameters?.jsonSchema || schema.parameters;
+          const properties = toolParameters?.properties || schema.properties;
+          const requiredParams = toolParameters?.required || schema.required || [];
 
-            // Build parameter documentation from properties
-            const paramsList = Object.entries(schema.properties).map(([paramName, propSchema]) => {
+          if (properties) {
+            // Build parameter documentation from properties with enhanced type information
+            const paramsList = Object.entries(properties).map(([paramName, propSchema]) => {
               const propDetails = propSchema as any;
               const requiredMark = requiredParams.includes(paramName) ? "*" : "";
-              const typeInfo = propDetails.type || "any";
-              const description = propDetails.description ? ` - ${propDetails.description}` : "";
+              let typeInfo = propDetails.type || "any";
+              let description = propDetails.description ? ` - ${propDetails.description}` : "";
+
+              // Enhanced type display for complex schemas
+              if (typeInfo === "array" && propDetails.items) {
+                const itemType = propDetails.items.type || "object";
+                if (itemType === "object" && propDetails.items.properties) {
+                  const itemProps = Object.keys(propDetails.items.properties).join(", ");
+                  typeInfo = `array<object>`;
+                  description =
+                    description +
+                    (description ? " " : " - ") +
+                    `Array of objects with properties: ${itemProps}`;
+                } else {
+                  typeInfo = `array<${itemType}>`;
+                }
+              }
+
+              // Handle enums
+              if (propDetails.enum && Array.isArray(propDetails.enum)) {
+                const enumValues = propDetails.enum.join(" | ");
+                description =
+                  description + (description ? " " : " - ") + `Allowed values: ${enumValues}`;
+              }
+
+              // Handle objects
+              if (typeInfo === "object" && propDetails.properties) {
+                const objectProps = Object.keys(propDetails.properties).join(", ");
+                description =
+                  description +
+                  (description ? " " : " - ") +
+                  `Object with properties: ${objectProps}`;
+              }
 
               return `    - ${paramName}${requiredMark} (${typeInfo})${description}`;
             });
@@ -183,6 +246,9 @@ ${toolsDoc}
 When using these tools:
 1. Only provide valid parameters according to their type requirements
 2. Required parameters are marked with *
-3. Format API calls correctly with the expected parameter structure
-4. Always check tool responses to determine your next action`;
+3. For array parameters, provide data in the correct array format
+4. For object parameters, include all required nested properties
+5. For enum parameters, use only the allowed values listed
+6. Format API calls correctly with the expected parameter structure
+7. Always check tool responses to determine your next action`;
 }

package/src/lib/runtime/remote-actions.ts

@@ -131,6 +131,7 @@ export async function setupRemoteActions({
   frontendUrl,
   agents,
   metaEvents,
+  nodeName,
 }: {
   remoteEndpointDefinitions: EndpointDefinition[];
   graphqlContext: GraphQLContext;
@@ -139,10 +140,13 @@ export async function setupRemoteActions({
   frontendUrl?: string;
   agents: Record<string, AbstractAgent>;
   metaEvents?: MetaEventInput[];
+  nodeName?: string;
 }): Promise<Action[]> {
   const logger = graphqlContext.logger.child({ component: "remote-actions.fetchRemoteActions" });
   logger.debug({ remoteEndpointDefinitions }, "Fetching from remote endpoints");
 
+  const threadMetadata = (graphqlContext.properties?.threadMetadata as Record<string, any>) || {};
+
   // Remove duplicates of remoteEndpointDefinitions.url
   const filtered = remoteEndpointDefinitions.filter((value, index, self) => {
     if (value.type === EndpointType.LangGraphPlatform) {
@@ -204,6 +208,8 @@ export async function setupRemoteActions({
         agentStates,
         agent: agent,
         metaEvents,
+        threadMetadata,
+        nodeName,
       }),
     );
   }