@copilotkit/runtime 1.57.3 → 1.58.0-canary.thread-id-propagation

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

@@ -1,313 +0,0 @@
-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 — preserve as structured data for Zod conversion
-      let enumValues: string[] | undefined;
-      if (paramDef.enum && Array.isArray(paramDef.enum)) {
-        enumValues = paramDef.enum.map(String);
-        const enumDisplay = enumValues.join(" | ");
-        description =
-          description +
-          (description ? " " : "") +
-          `Allowed values: ${enumDisplay}`;
-      }
-
-      // Handle objects with properties — recurse to preserve nested structure
-      let attributes: Parameter[] | undefined;
-      if (type === "object" && paramDef.properties) {
-        const objectProperties = Object.keys(paramDef.properties).join(", ");
-        description =
-          description +
-          (description ? " " : "") +
-          `Object with properties: ${objectProperties}`;
-        // Recursively extract nested parameters
-        attributes = extractParametersFromSchema({
-          parameters: {
-            properties: paramDef.properties,
-            required: paramDef.required || [],
-          },
-        });
-      }
-
-      // Handle object arrays — recurse into item schema
-      if (type === "array" && paramDef.items?.type === "object" && paramDef.items?.properties) {
-        attributes = extractParametersFromSchema({
-          parameters: {
-            properties: paramDef.items.properties,
-            required: paramDef.items.required || [],
-          },
-        });
-      }
-
-      const param: any = {
-        name: paramName,
-        type: type,
-        description: description,
-        required: requiredParams.has(paramName),
-      };
-
-      // Preserve enum values for string parameters
-      if (type === "string" && enumValues) {
-        param.enum = enumValues;
-      }
-
-      // Preserve nested attributes for object and object[] types
-      if (attributes && attributes.length > 0) {
-        param.attributes = attributes;
-        if (type === "array") {
-          param.type = "object[]";
-        }
-      }
-
-      parameters.push(param);
-    }
-  }
-
-  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)
-          }`, { cause: 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

@@ -1,141 +0,0 @@
-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],
-  // Maximum Retry-After value (in seconds) we're willing to honor
-  maxRetryAfterSeconds: 60,
-  // 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));
-}
-
-// Parse the Retry-After header value into milliseconds.
-// Returns undefined if the header is missing or unparseable.
-export function parseRetryAfter(response: Response): number | undefined {
-  const retryAfter = response.headers.get("Retry-After");
-  if (!retryAfter) return undefined;
-
-  // Try as seconds (integer)
-  const seconds = Number(retryAfter);
-  if (!Number.isNaN(seconds) && seconds >= 0) {
-    return seconds * 1000;
-  }
-
-  // Try as HTTP-date
-  const date = Date.parse(retryAfter);
-  if (!Number.isNaN(date)) {
-    const delayMs = date - Date.now();
-    return delayMs > 0 ? delayMs : 0;
-  }
-
-  return undefined;
-}
-
-// 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
-      ) {
-        let delay = calculateDelay(attempt);
-
-        // Honor Retry-After header on 429 responses
-        if (response.status === 429) {
-          const retryAfterMs = parseRetryAfter(response);
-          if (retryAfterMs !== undefined) {
-            const maxMs = RETRY_CONFIG.maxRetryAfterSeconds * 1000;
-            if (retryAfterMs > maxMs) {
-              throw new Error(
-                `Server requested Retry-After of ${Math.ceil(retryAfterMs / 1000)}s ` +
-                  `which exceeds the maximum of ${RETRY_CONFIG.maxRetryAfterSeconds}s`,
-              );
-            }
-            delay = retryAfterMs;
-          }
-        }
-
-        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

@@ -1,151 +0,0 @@
-/**
- * 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 "../../v2/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

@@ -1,48 +0,0 @@
-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",
-}