@copilotkit/runtime 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

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

@@ -0,0 +1,254 @@
+import { Action, Parameter } from "@copilotkit/shared";
+
+/**
+ * Represents a tool provided by an MCP server.
+ */
+export interface MCPTool {
+  description?: string;
+  /** Schema defining parameters, mirroring the MCP structure. */
+  schema?: {
+    parameters?: {
+      properties?: Record<string, any>;
+      required?: string[];
+      jsonSchema?: Record<string, any>;
+    };
+  };
+  /** The function to call to execute the tool on the MCP server. */
+  execute(params: any): Promise<any>;
+}
+
+/**
+ * Defines the contract for *any* MCP client implementation the user might provide.
+ */
+export interface MCPClient {
+  /** A method that returns a map of tool names to MCPTool objects available from the connected MCP server. */
+  tools(): Promise<Record<string, MCPTool>>;
+  /** An optional method for cleanup if the underlying client requires explicit disconnection. */
+  close?(): Promise<void>;
+}
+
+/**
+ * Configuration for connecting to an MCP endpoint.
+ */
+export interface MCPEndpointConfig {
+  endpoint: string;
+  apiKey?: string;
+}
+
+/**
+ * Extracts CopilotKit-compatible parameters from an MCP tool schema.
+ * @param toolOrSchema The schema object from an MCPTool or the full MCPTool object.
+ * @returns An array of Parameter objects.
+ */
+export function extractParametersFromSchema(
+  toolOrSchema?: MCPTool | MCPTool["schema"],
+): Parameter[] {
+  const parameters: Parameter[] = [];
+
+  // Handle either full tool object or just schema
+  const schema =
+    "schema" in (toolOrSchema || {})
+      ? (toolOrSchema as MCPTool).schema
+      : (toolOrSchema as MCPTool["schema"]);
+
+  const toolParameters = schema?.parameters?.jsonSchema || schema?.parameters;
+  const properties = toolParameters?.properties;
+  const requiredParams = new Set(toolParameters?.required || []);
+
+  if (!properties) {
+    return parameters;
+  }
+
+  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,
+        type: type,
+        description: description,
+        required: requiredParams.has(paramName),
+      });
+    }
+  }
+
+  return parameters;
+}
+
+/**
+ * Converts a map of MCPTools into an array of CopilotKit Actions.
+ * @param mcpTools A record mapping tool names to MCPTool objects.
+ * @param mcpEndpoint The endpoint URL from which these tools were fetched.
+ * @returns An array of Action<any> objects.
+ */
+export function convertMCPToolsToActions(
+  mcpTools: Record<string, MCPTool>,
+  mcpEndpoint: string,
+): Action<any>[] {
+  const actions: Action<any>[] = [];
+
+  for (const [toolName, tool] of Object.entries(mcpTools)) {
+    const parameters = extractParametersFromSchema(tool);
+
+    const handler = async (params: any): Promise<any> => {
+      try {
+        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);
+      } catch (error) {
+        console.error(
+          `Error executing MCP tool '${toolName}' from endpoint ${mcpEndpoint}:`,
+          error,
+        );
+        // Re-throw or format the error for the LLM
+        throw new Error(
+          `Execution failed for MCP tool '${toolName}': ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    };
+
+    actions.push({
+      name: toolName,
+      description: tool.description || `MCP tool: ${toolName} (from ${mcpEndpoint})`,
+      parameters: parameters,
+      handler: handler,
+      // Add metadata for easier identification/debugging
+      _isMCPTool: true,
+      _mcpEndpoint: mcpEndpoint,
+    } as Action<any> & { _isMCPTool: boolean; _mcpEndpoint: string }); // Type assertion for metadata
+  }
+
+  return actions;
+}
+
+/**
+ * Generate better instructions for using MCP tools
+ * This is used to enhance the system prompt with tool documentation
+ */
+export function generateMcpToolInstructions(toolsMap: Record<string, MCPTool>): string {
+  if (!toolsMap || Object.keys(toolsMap).length === 0) {
+    return "";
+  }
+
+  const toolEntries = Object.entries(toolsMap);
+
+  // Generate documentation for each tool
+  const toolsDoc = toolEntries
+    .map(([name, tool]) => {
+      // Extract schema information if available
+      let paramsDoc = "    No parameters required";
+
+      try {
+        if (tool.schema && typeof tool.schema === "object") {
+          const schema = tool.schema as any;
+
+          // 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 || [];
+
+          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) ? "*" : "";
+              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}`;
+            });
+
+            if (paramsList.length > 0) {
+              paramsDoc = paramsList.join("\n");
+            }
+          }
+        }
+      } catch (e) {
+        console.error(`Error parsing schema for tool ${name}:`, e);
+      }
+
+      return `- ${name}: ${tool.description || ""}
+${paramsDoc}`;
+    })
+    .join("\n\n");
+
+  return `You have access to the following external tools provided by Model Context Protocol (MCP) servers:
+
+${toolsDoc}
+
+When using these tools:
+1. Only provide valid parameters according to their type requirements
+2. Required parameters are marked with *
+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/retry-utils.ts

@@ -0,0 +1,96 @@
+import { Logger } from "pino";
+
+// Retry configuration for network requests
+export const RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelayMs: 1000,
+  maxDelayMs: 5000,
+  // HTTP status codes that should be retried
+  retryableStatusCodes: [502, 503, 504, 408, 429],
+  // Network error patterns that should be retried
+  retryableErrorMessages: [
+    "fetch failed",
+    "network error",
+    "connection timeout",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "ENOTFOUND",
+    "ECONNRESET",
+  ],
+};
+
+// Helper function to check if an error/response is retryable
+export function isRetryableError(error: any, response?: Response): boolean {
+  // Check HTTP response status
+  if (response && RETRY_CONFIG.retryableStatusCodes.includes(response.status)) {
+    return true;
+  }
+
+  // Check error codes (for connection errors like ECONNREFUSED)
+  const errorCode = error?.cause?.code || error?.code;
+  if (errorCode && RETRY_CONFIG.retryableErrorMessages.includes(errorCode)) {
+    return true;
+  }
+
+  // Check error messages
+  const errorMessage = error?.message?.toLowerCase() || "";
+  return RETRY_CONFIG.retryableErrorMessages.some((msg) => errorMessage.includes(msg));
+}
+
+// Helper function to sleep for a given duration
+export function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// Calculate exponential backoff delay
+export function calculateDelay(attempt: number): number {
+  const delay = RETRY_CONFIG.baseDelayMs * Math.pow(2, attempt);
+  return Math.min(delay, RETRY_CONFIG.maxDelayMs);
+}
+
+// Retry wrapper for fetch requests
+export async function fetchWithRetry(
+  url: string,
+  options: RequestInit,
+  logger?: Logger,
+): Promise<Response> {
+  let lastError: any;
+
+  for (let attempt = 0; attempt <= RETRY_CONFIG.maxRetries; attempt++) {
+    try {
+      const response = await fetch(url, options);
+
+      // If response is retryable, treat as error and retry
+      if (isRetryableError(null, response) && attempt < RETRY_CONFIG.maxRetries) {
+        const delay = calculateDelay(attempt);
+        logger?.warn(
+          `Request to ${url} failed with status ${response.status}. ` +
+            `Retrying attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} in ${delay}ms.`,
+        );
+        await sleep(delay);
+        continue;
+      }
+
+      return response; // Success or non-retryable error
+    } catch (error) {
+      lastError = error;
+
+      // Check if this is a retryable network error
+      if (isRetryableError(error) && attempt < RETRY_CONFIG.maxRetries) {
+        const delay = calculateDelay(attempt);
+        logger?.warn(
+          `Request to ${url} failed with network error. ` +
+            `Retrying attempt ${attempt + 1}/${RETRY_CONFIG.maxRetries + 1} in ${delay}ms. Error: ${error?.message || String(error)}`,
+        );
+        await sleep(delay);
+        continue;
+      }
+
+      // Not retryable or max retries exceeded
+      break;
+    }
+  }
+
+  // Re-throw the last error after retries exhausted
+  throw lastError;
+}

package/src/lib/runtime/telemetry-agent-runner.ts

@@ -0,0 +1,139 @@
+/**
+ * TelemetryAgentRunner - A wrapper around AgentRunner that adds telemetry
+ * for agent execution streams.
+ *
+ * This captures the following telemetry events:
+ * - oss.runtime.agent_execution_stream_started - when an agent execution starts
+ * - oss.runtime.agent_execution_stream_ended - when an agent execution completes
+ * - oss.runtime.agent_execution_stream_errored - when an agent execution fails
+ */
+
+import { type AgentRunner, InMemoryAgentRunner } from "@copilotkitnext/runtime";
+import { createHash } from "node:crypto";
+import { tap, catchError, finalize } from "rxjs";
+import telemetry from "../telemetry-client";
+import type { AgentExecutionResponseInfo } from "@copilotkit/shared/src/telemetry/events";
+
+/**
+ * Configuration options for TelemetryAgentRunner
+ */
+export interface TelemetryAgentRunnerConfig {
+  /**
+   * The underlying runner to delegate to
+   * If not provided, defaults to InMemoryAgentRunner
+   */
+  runner?: AgentRunner;
+
+  /**
+   * Optional LangSmith API key (will be hashed for telemetry)
+   */
+  langsmithApiKey?: string;
+}
+
+/**
+ * An AgentRunner wrapper that adds telemetry tracking for agent executions.
+ *
+ * Usage:
+ * ```ts
+ * const runtime = new CopilotRuntime({
+ *   runner: new TelemetryAgentRunner(),
+ *   // or with custom runner:
+ *   runner: new TelemetryAgentRunner({ runner: customRunner }),
+ * });
+ * ```
+ */
+export class TelemetryAgentRunner implements AgentRunner {
+  private readonly _runner: AgentRunner;
+  private readonly hashedLgcKey: string | undefined;
+
+  constructor(config?: TelemetryAgentRunnerConfig) {
+    this._runner = config?.runner ?? new InMemoryAgentRunner();
+    this.hashedLgcKey = config?.langsmithApiKey
+      ? createHash("sha256").update(config.langsmithApiKey).digest("hex")
+      : undefined;
+  }
+
+  /**
+   * Runs an agent with telemetry tracking.
+   * Wraps the underlying runner's Observable stream with telemetry events.
+   */
+  run(...args: Parameters<AgentRunner["run"]>): ReturnType<AgentRunner["run"]> {
+    const streamInfo: AgentExecutionResponseInfo = {
+      hashedLgcKey: this.hashedLgcKey,
+    };
+    let streamErrored = false;
+
+    // Capture stream started event
+    telemetry.capture("oss.runtime.agent_execution_stream_started", {
+      hashedLgcKey: this.hashedLgcKey,
+    });
+
+    // Delegate to the underlying runner and wrap with telemetry
+    return this._runner.run(...args).pipe(
+      // Extract metadata from events if available
+      tap((event) => {
+        // Try to extract provider/model info from raw events
+        const rawEvent = (
+          event as {
+            rawEvent?: { metadata?: Record<string, unknown>; data?: Record<string, unknown> };
+          }
+        ).rawEvent;
+        if (rawEvent?.data) {
+          const data = rawEvent.data as { output?: { model?: string } };
+          if (data?.output?.model) {
+            streamInfo.model = data.output.model;
+            streamInfo.provider = data.output.model;
+          }
+        }
+        if (rawEvent?.metadata) {
+          const metadata = rawEvent.metadata as {
+            langgraph_host?: string;
+            langgraph_version?: string;
+          };
+          if (metadata?.langgraph_host) {
+            streamInfo.langGraphHost = metadata.langgraph_host;
+          }
+          if (metadata?.langgraph_version) {
+            streamInfo.langGraphVersion = metadata.langgraph_version;
+          }
+        }
+      }),
+      catchError((error) => {
+        // Capture stream error event
+        streamErrored = true;
+        telemetry.capture("oss.runtime.agent_execution_stream_errored", {
+          ...streamInfo,
+          error: error instanceof Error ? error.message : String(error),
+        });
+        throw error;
+      }),
+      finalize(() => {
+        // Capture stream ended event (only if not errored)
+        if (!streamErrored) {
+          telemetry.capture("oss.runtime.agent_execution_stream_ended", streamInfo);
+        }
+      }),
+    );
+  }
+
+  /**
+   * Delegates to the underlying runner's connect method
+   */
+  connect(...args: Parameters<AgentRunner["connect"]>): ReturnType<AgentRunner["connect"]> {
+    return this._runner.connect(...args);
+  }
+
+  /**
+   * Delegates to the underlying runner's isRunning method
+   */
+  isRunning(...args: Parameters<AgentRunner["isRunning"]>): ReturnType<AgentRunner["isRunning"]> {
+    return this._runner.isRunning(...args);
+  }
+
+  /**
+   * Delegates to the underlying runner's stop method
+   */
+  stop(...args: Parameters<AgentRunner["stop"]>): ReturnType<AgentRunner["stop"]> {
+    return this._runner.stop(...args);
+  }
+}

package/src/lib/runtime/types.ts

@@ -0,0 +1,49 @@
+import { GraphQLContext } from "../integrations";
+import { ActionInput } from "../../graphql/inputs/action.input";
+import { Message } from "../../graphql/types/converted";
+import { MetaEventInput } from "../../graphql/inputs/meta-event.input";
+
+export interface BaseEndpointDefinition<TActionType extends EndpointType> {
+  type?: TActionType;
+}
+
+export interface CopilotKitEndpoint extends BaseEndpointDefinition<EndpointType.CopilotKit> {
+  url: string;
+  onBeforeRequest?: ({ ctx }: { ctx: GraphQLContext }) => {
+    headers?: Record<string, string> | undefined;
+  };
+}
+
+export interface LangGraphPlatformAgent {
+  name: string;
+  description: string;
+  assistantId?: string;
+}
+
+export interface LangGraphPlatformEndpoint
+  extends BaseEndpointDefinition<EndpointType.LangGraphPlatform> {
+  deploymentUrl: string;
+  langsmithApiKey?: string | null;
+  agents: LangGraphPlatformAgent[];
+}
+
+export type RemoteActionInfoResponse = {
+  actions: any[];
+  agents: any[];
+};
+
+export type RemoteAgentHandlerParams = {
+  name: string;
+  actionInputsWithoutAgents: ActionInput[];
+  threadId?: string;
+  nodeName?: string;
+  additionalMessages?: Message[];
+  metaEvents?: MetaEventInput[];
+};
+
+export type EndpointDefinition = CopilotKitEndpoint | LangGraphPlatformEndpoint;
+
+export enum EndpointType {
+  CopilotKit = "copilotKit",
+  LangGraphPlatform = "langgraph-platform",
+}

package/src/lib/runtime/utils.ts

@@ -0,0 +1,87 @@
+import { GraphQLContext } from "../integrations";
+import { Logger } from "pino";
+import { CopilotKitEndpoint, RemoteActionInfoResponse } from "./types";
+import {
+  Action,
+  CopilotKitError,
+  CopilotKitLowLevelError,
+  ResolvedCopilotKitError,
+} from "@copilotkit/shared";
+
+async function fetchRemoteInfo({
+  url,
+  onBeforeRequest,
+  graphqlContext,
+  logger,
+  frontendUrl,
+}: {
+  url: string;
+  onBeforeRequest?: CopilotKitEndpoint["onBeforeRequest"];
+  graphqlContext: GraphQLContext;
+  logger: Logger;
+  frontendUrl?: string;
+}): Promise<RemoteActionInfoResponse> {
+  logger.debug({ url }, "Fetching actions from url");
+  const headers = createHeaders(onBeforeRequest, graphqlContext);
+
+  const fetchUrl = `${url}/info`;
+  try {
+    const response = await fetch(fetchUrl, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ properties: graphqlContext.properties, frontendUrl }),
+    });
+
+    if (!response.ok) {
+      logger.error(
+        { url, status: response.status, body: await response.text() },
+        "Failed to fetch actions from url",
+      );
+      throw new ResolvedCopilotKitError({
+        status: response.status,
+        url: fetchUrl,
+        isRemoteEndpoint: true,
+      });
+    }
+
+    const json = await response.json();
+    logger.debug({ json }, "Fetched actions from url");
+    return json;
+  } catch (error) {
+    if (error instanceof CopilotKitError) {
+      throw error;
+    }
+    throw new CopilotKitLowLevelError({ error, url: fetchUrl });
+  }
+}
+
+// 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"))
+  );
+}
+
+export function createHeaders(
+  onBeforeRequest: CopilotKitEndpoint["onBeforeRequest"],
+  graphqlContext: GraphQLContext,
+) {
+  const headers = {
+    "Content-Type": "application/json",
+  };
+
+  if (onBeforeRequest) {
+    const { headers: additionalHeaders } = onBeforeRequest({ ctx: graphqlContext });
+    if (additionalHeaders) {
+      Object.assign(headers, additionalHeaders);
+    }
+  }
+
+  return headers;
+}