@copilotkit/runtime 1.9.2-next.8 → 1.9.2

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-action-constructors.ts

@@ -22,6 +22,9 @@ import { parseJson, tryMap } from "@copilotkit/shared";
 import { ActionInput } from "../../graphql/inputs/action.input";
 import { fetchWithRetry } from "./retry-utils";
 
+// Import the utility function from remote-lg-action
+import { isUserConfigurationError } from "./remote-lg-action";
+
 export function constructLGCRemoteAction({
   endpoint,
   graphqlContext,
@@ -93,11 +96,33 @@ export function constructLGCRemoteAction({
         writeJsonLineResponseToEventStream(response, eventSource.eventStream$);
         return eventSource.processLangGraphEvents();
       } catch (error) {
+        // Preserve structured CopilotKit errors with semantic information
+        if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
+          // Distinguish between user errors and system errors for logging
+          if (isUserConfigurationError(error)) {
+            logger.debug(
+              { url: endpoint.deploymentUrl, error: error.message, code: error.code },
+              "User configuration error in LangGraph Platform agent",
+            );
+          } else {
+            logger.error(
+              { url: endpoint.deploymentUrl, error: error.message, type: error.constructor.name },
+              "LangGraph Platform agent error",
+            );
+          }
+          throw error; // Re-throw the structured error to preserve semantic information
+        }
+
+        // For other errors, log and wrap them
         logger.error(
           { url: endpoint.deploymentUrl, status: 500, body: error.message },
           "Failed to execute LangGraph Platform agent",
         );
-        throw new Error("Failed to execute LangGraph Platform agent");
+        throw new CopilotKitLowLevelError({
+          error: error instanceof Error ? error : new Error(String(error)),
+          url: endpoint.deploymentUrl,
+          message: "Failed to execute LangGraph Platform agent",
+        });
       }
     },
   }));
@@ -180,7 +205,7 @@ export function constructRemoteActions({
         logger.debug({ actionName: action.name, result }, "Executed remote action");
         return result;
       } catch (error) {
-        if (error instanceof CopilotKitError) {
+        if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
           throw error;
         }
         throw new CopilotKitLowLevelError({ error, url: fetchUrl });
@@ -275,7 +300,7 @@ export function constructRemoteActions({
               throw new Error("Unsupported agent type");
             }
           } catch (error) {
-            if (error instanceof CopilotKitError) {
+            if (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) {
               throw error;
             }
             throw new CopilotKitLowLevelError({ error, url: fetchUrl });

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,
       }),
     );
   }

package/src/lib/runtime/remote-lg-action.ts

@@ -19,9 +19,28 @@ import { CustomEventNames, LangGraphEventTypes } from "../../agents/langgraph/ev
 import telemetry from "../telemetry-client";
 import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
 import { MetaEventName } from "../../graphql/types/meta-events.type";
-import { parseJson, CopilotKitMisuseError } from "@copilotkit/shared";
+import {
+  parseJson,
+  CopilotKitMisuseError,
+  CopilotKitLowLevelError,
+  CopilotKitError,
+} from "@copilotkit/shared";
 import { RemoveMessage } from "@langchain/core/messages";
 import { RETRY_CONFIG, isRetryableError, sleep, calculateDelay } from "./retry-utils";
+import { generateHelpfulErrorMessage } from "../streaming";
+
+// Utility to determine if an error is a user configuration issue vs system error
+export function isUserConfigurationError(error: any): boolean {
+  return (
+    (error instanceof CopilotKitError || error instanceof CopilotKitLowLevelError) &&
+    (error.code === "NETWORK_ERROR" ||
+      error.code === "AUTHENTICATION_ERROR" ||
+      error.statusCode === 401 ||
+      error.statusCode === 403 ||
+      error.message?.toLowerCase().includes("authentication") ||
+      error.message?.toLowerCase().includes("api key"))
+  );
+}
 
 type State = Record<string, any>;
 
@@ -128,6 +147,15 @@ export async function execute(args: ExecutionArgs): Promise<ReadableStream<Uint8
             See more: https://docs.copilotkit.ai/troubleshooting/common-issues`,
         });
       } else {
+        // Preserve already structured CopilotKit errors with semantic information
+        if (
+          lastError instanceof CopilotKitError ||
+          lastError instanceof CopilotKitLowLevelError ||
+          (lastError instanceof Error && lastError.name && lastError.name.includes("CopilotKit"))
+        ) {
+          throw lastError; // Re-throw to preserve semantic information and visibility settings
+        }
+
         throw new CopilotKitMisuseError({
           message: `
             The LangGraph client threw unhandled error ${lastError}.
@@ -341,7 +369,43 @@ async function streamEvents(controller: ReadableStreamDefaultController, args: E
       if (!["events", "values", "error", "updates"].includes(streamResponseChunk.event)) continue;
 
       if (streamResponseChunk.event === "error") {
-        throw new Error(`Error event thrown: ${streamResponseChunk.data.message}`);
+        const errorData = streamResponseChunk.data;
+
+        // Check if this is a structured error from our Python agent
+        if (errorData && typeof errorData === "object" && "error_details" in errorData) {
+          const errorDetails = (errorData as any).error_details;
+
+          // Create a structured error with preserved semantic information
+          const preservedError = new CopilotKitLowLevelError({
+            error: new Error(errorDetails.message),
+            url: "langgraph platform agent",
+            message: `${errorDetails.type}: ${errorDetails.message}`,
+          });
+
+          // Add additional error context
+          if (errorDetails.status_code) {
+            (preservedError as any).statusCode = errorDetails.status_code;
+          }
+          if (errorDetails.response_data) {
+            (preservedError as any).responseData = errorDetails.response_data;
+          }
+          (preservedError as any).agentName = errorDetails.agent_name;
+          (preservedError as any).originalErrorType = errorDetails.type;
+
+          throw preservedError;
+        }
+
+        // Fallback for generic error messages
+        const helpfulMessage = generateHelpfulErrorMessage(
+          new Error(errorData.message),
+          "LangGraph Platform agent",
+        );
+
+        throw new CopilotKitLowLevelError({
+          error: new Error(errorData.message),
+          url: "langgraph platform agent",
+          message: helpfulMessage,
+        });
       }
 
       // Force event type, as data is not properly defined on the LG side.
@@ -507,11 +571,29 @@ async function streamEvents(controller: ReadableStreamDefaultController, args: E
 
     return Promise.resolve();
   } catch (e) {
-    logger.error(e);
+    // Distinguish between user errors and system errors for logging
+    if (isUserConfigurationError(e)) {
+      // Log user errors at debug level to reduce noise
+      logger.debug({ error: e.message, code: e.code }, "User configuration error");
+    } else {
+      // Log actual system errors at error level
+      logger.error(e);
+    }
+
     telemetry.capture("oss.runtime.agent_execution_stream_errored", {
       ...streamInfo,
       error: e.message,
     });
+
+    // Re-throw CopilotKit errors so they can be handled properly at higher levels
+    if (
+      e instanceof CopilotKitError ||
+      e instanceof CopilotKitLowLevelError ||
+      (e instanceof Error && e.name && e.name.includes("CopilotKit"))
+    ) {
+      throw e;
+    }
+
     return Promise.resolve();
   }
 }

package/src/lib/streaming.ts

@@ -1,5 +1,11 @@
 import { ReplaySubject } from "rxjs";
-import { CopilotKitLowLevelError, CopilotKitError, CopilotKitErrorCode } from "@copilotkit/shared";
+import {
+  CopilotKitLowLevelError,
+  CopilotKitError,
+  CopilotKitErrorCode,
+  ensureStructuredError,
+} from "@copilotkit/shared";
+import { errorConfig, getFallbackMessage } from "./error-messages";
 
 export async function writeJsonLineResponseToEventStream<T>(
   response: ReadableStream<Uint8Array>,
@@ -52,10 +58,8 @@ export async function writeJsonLineResponseToEventStream<T>(
       }
     }
   } catch (error) {
-    console.error("Error in stream", error);
-
-    // Convert network termination errors to structured errors
-    const structuredError = convertStreamingErrorToStructured(error);
+    // Preserve already structured CopilotKit errors, only convert unstructured errors
+    const structuredError = ensureStructuredError(error, convertStreamingErrorToStructured);
     eventStream$.error(structuredError);
     return;
   }
@@ -63,50 +67,135 @@ export async function writeJsonLineResponseToEventStream<T>(
 }
 
 function convertStreamingErrorToStructured(error: any): CopilotKitError {
-  // Handle network termination errors
-  if (
-    error?.message?.includes("terminated") ||
-    error?.cause?.code === "UND_ERR_SOCKET" ||
-    error?.message?.includes("other side closed") ||
-    error?.code === "UND_ERR_SOCKET"
-  ) {
-    return new CopilotKitError({
-      message:
-        "Connection to agent was unexpectedly terminated. This is likely due to the agent service being down or experiencing issues. Please check your agent logs and try again.",
-      code: CopilotKitErrorCode.NETWORK_ERROR,
-    });
-  }
+  // Determine a more helpful error message based on context
+  let helpfulMessage = generateHelpfulErrorMessage(error);
 
-  // Handle other network-related errors
+  // For network-related errors, use CopilotKitLowLevelError to preserve the original error
   if (
     error?.message?.includes("fetch failed") ||
     error?.message?.includes("ECONNREFUSED") ||
     error?.message?.includes("ENOTFOUND") ||
-    error?.message?.includes("ETIMEDOUT")
+    error?.message?.includes("ETIMEDOUT") ||
+    error?.message?.includes("terminated") ||
+    error?.cause?.code === "UND_ERR_SOCKET" ||
+    error?.message?.includes("other side closed") ||
+    error?.code === "UND_ERR_SOCKET"
   ) {
     return new CopilotKitLowLevelError({
       error: error instanceof Error ? error : new Error(String(error)),
       url: "streaming connection",
-      message:
-        "Network error occurred during streaming. Please check your connection and try again.",
-    });
-  }
-
-  // Handle abort/cancellation errors (these are usually normal)
-  if (
-    error?.message?.includes("aborted") ||
-    error?.message?.includes("canceled") ||
-    error?.message?.includes("signal is aborted")
-  ) {
-    return new CopilotKitError({
-      message: "Request was cancelled",
-      code: CopilotKitErrorCode.UNKNOWN,
+      message: helpfulMessage,
     });
   }
 
-  // Default: convert unknown streaming errors
+  // For all other errors, preserve the raw error in a basic CopilotKitError
   return new CopilotKitError({
-    message: `Streaming error: ${error?.message || String(error)}`,
+    message: helpfulMessage,
     code: CopilotKitErrorCode.UNKNOWN,
   });
 }
+
+/**
+ * Generates a helpful error message based on error patterns and context
+ */
+export function generateHelpfulErrorMessage(error: any, context: string = "connection"): string {
+  const baseMessage = error?.message || String(error);
+
+  // Check for preserved error information from Python agent
+  const originalErrorType = error?.originalErrorType || error?.extensions?.originalErrorType;
+  const statusCode = error?.statusCode || error?.extensions?.statusCode;
+  const responseData = error?.responseData || error?.extensions?.responseData;
+
+  // First, try to match by original error type if available (more specific)
+  if (originalErrorType) {
+    const typeConfig = errorConfig.errorPatterns[originalErrorType];
+    if (typeConfig) {
+      return typeConfig.message.replace("{context}", context);
+    }
+  }
+
+  // Check for specific error patterns from configuration
+  for (const [pattern, config] of Object.entries(errorConfig.errorPatterns)) {
+    const shouldMatch =
+      baseMessage?.includes(pattern) ||
+      error?.cause?.code === pattern ||
+      error?.code === pattern ||
+      statusCode === parseInt(pattern) ||
+      (pattern === "other_side_closed" && baseMessage?.includes("other side closed")) ||
+      (pattern === "fetch_failed" && baseMessage?.includes("fetch failed")) ||
+      (responseData && JSON.stringify(responseData).includes(pattern));
+
+    if (shouldMatch) {
+      // Replace {context} placeholder with actual context
+      return config.message.replace("{context}", context);
+    }
+  }
+
+  // Try to match by category for fallback messages
+  if (isNetworkError(error)) {
+    return getFallbackMessage("network");
+  }
+
+  if (isConnectionError(error)) {
+    return getFallbackMessage("connection");
+  }
+
+  if (isAuthenticationError(error)) {
+    return getFallbackMessage("authentication");
+  }
+
+  // Default fallback
+  return getFallbackMessage("default");
+}
+
+/**
+ * Determines if an error is network-related
+ */
+function isNetworkError(error: any): boolean {
+  const networkPatterns = ["ECONNREFUSED", "ENOTFOUND", "ETIMEDOUT", "fetch_failed"];
+  return networkPatterns.some(
+    (pattern) =>
+      error?.message?.includes(pattern) ||
+      error?.cause?.code === pattern ||
+      error?.code === pattern,
+  );
+}
+
+/**
+ * Determines if an error is connection-related
+ */
+function isConnectionError(error: any): boolean {
+  const connectionPatterns = ["terminated", "UND_ERR_SOCKET", "other side closed"];
+  return connectionPatterns.some(
+    (pattern) =>
+      error?.message?.includes(pattern) ||
+      error?.cause?.code === pattern ||
+      error?.code === pattern,
+  );
+}
+
+/**
+ * Determines if an error is authentication-related
+ */
+function isAuthenticationError(error: any): boolean {
+  const authPatterns = [
+    "401",
+    "api key",
+    "unauthorized",
+    "authentication",
+    "AuthenticationError",
+    "PermissionDeniedError",
+  ];
+  const baseMessage = error?.message || String(error);
+  const originalErrorType = error?.originalErrorType || error?.extensions?.originalErrorType;
+  const statusCode = error?.statusCode || error?.extensions?.statusCode;
+
+  return authPatterns.some(
+    (pattern) =>
+      baseMessage?.toLowerCase().includes(pattern.toLowerCase()) ||
+      originalErrorType === pattern ||
+      statusCode === 401 ||
+      error?.status === 401 ||
+      error?.statusCode === 401,
+  );
+}