@copilotkit/runtime 1.50.0-beta.9 → 1.50.0

package/dist/shared-9ed1dc31.d.ts

@@ -0,0 +1,414 @@
+import * as graphql from 'graphql';
+import * as pino from 'pino';
+import { YogaInitialContext, createYoga } from 'graphql-yoga';
+import { Parameter, Action, CopilotErrorHandler, PartialBy, MaybePromise, NonEmptyRecord } from '@copilotkit/shared';
+import { R as RemoteChainParameters, b as CopilotServiceAdapter } from './langserve-978d5790.js';
+import { CopilotRuntimeOptions, CopilotRuntime as CopilotRuntime$1 } from '@copilotkitnext/runtime';
+import { a as MessageInput, M as Message } from './index-adbd78f1.js';
+import { CopilotCloudOptions } from './lib/cloud/index.js';
+import { AbstractAgent } from '@ag-ui/client';
+
+interface BaseEndpointDefinition<TActionType extends EndpointType> {
+    type?: TActionType;
+}
+interface CopilotKitEndpoint extends BaseEndpointDefinition<EndpointType.CopilotKit> {
+    url: string;
+    onBeforeRequest?: ({ ctx }: {
+        ctx: GraphQLContext;
+    }) => {
+        headers?: Record<string, string> | undefined;
+    };
+}
+interface LangGraphPlatformAgent {
+    name: string;
+    description: string;
+    assistantId?: string;
+}
+interface LangGraphPlatformEndpoint extends BaseEndpointDefinition<EndpointType.LangGraphPlatform> {
+    deploymentUrl: string;
+    langsmithApiKey?: string | null;
+    agents: LangGraphPlatformAgent[];
+}
+type EndpointDefinition = CopilotKitEndpoint | LangGraphPlatformEndpoint;
+declare enum EndpointType {
+    CopilotKit = "copilotKit",
+    LangGraphPlatform = "langgraph-platform"
+}
+
+interface LLMRequestData {
+    threadId?: string;
+    runId?: string;
+    model?: string;
+    messages: any[];
+    actions?: any[];
+    forwardedParameters?: any;
+    timestamp: number;
+    provider?: string;
+    [key: string]: any;
+}
+interface LLMResponseData {
+    threadId: string;
+    runId?: string;
+    model?: string;
+    output: any;
+    latency: number;
+    timestamp: number;
+    provider?: string;
+    isProgressiveChunk?: boolean;
+    isFinalResponse?: boolean;
+    [key: string]: any;
+}
+interface LLMErrorData {
+    threadId?: string;
+    runId?: string;
+    model?: string;
+    error: Error | string;
+    timestamp: number;
+    provider?: string;
+    [key: string]: any;
+}
+interface CopilotObservabilityHooks {
+    handleRequest: (data: LLMRequestData) => void | Promise<void>;
+    handleResponse: (data: LLMResponseData) => void | Promise<void>;
+    handleError: (data: LLMErrorData) => void | Promise<void>;
+}
+/**
+ * Configuration for CopilotKit logging functionality.
+ *
+ * @remarks
+ * Custom logging handlers require a valid CopilotKit public API key.
+ * Sign up at https://docs.copilotkit.ai/quickstart#get-a-copilot-cloud-public-api-key to get your key.
+ */
+interface CopilotObservabilityConfig {
+    /**
+     * Enable or disable logging functionality.
+     *
+     * @default false
+     */
+    enabled: boolean;
+    /**
+     * Controls whether logs are streamed progressively or buffered.
+     * - When true: Each token and update is logged as it's generated (real-time)
+     * - When false: Complete responses are logged after completion (batched)
+     *
+     * @default true
+     */
+    progressive: boolean;
+    /**
+     * Custom observability hooks for request, response, and error events.
+     *
+     * @remarks
+     * Using custom observability hooks requires a valid CopilotKit public API key.
+     */
+    hooks: CopilotObservabilityHooks;
+}
+
+/**
+ * Represents a tool provided by an MCP server.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function extractParametersFromSchema(toolOrSchema?: MCPTool | MCPTool["schema"]): Parameter[];
+/**
+ * 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.
+ */
+declare function convertMCPToolsToActions(mcpTools: Record<string, MCPTool>, mcpEndpoint: string): Action<any>[];
+/**
+ * Generate better instructions for using MCP tools
+ * This is used to enhance the system prompt with tool documentation
+ */
+declare function generateMcpToolInstructions(toolsMap: Record<string, MCPTool>): string;
+
+/**
+ * <Callout type="info">
+ *   This is the reference for the `CopilotRuntime` class. For more information and example code snippets, please see [Concept: Copilot Runtime](/concepts/copilot-runtime).
+ * </Callout>
+ *
+ * ## Usage
+ *
+ * ```tsx
+ * import { CopilotRuntime } from "@copilotkit/runtime";
+ *
+ * const copilotKit = new CopilotRuntime();
+ * ```
+ */
+
+type CreateMCPClientFunction = (config: MCPEndpointConfig) => Promise<MCPClient>;
+type ActionsConfiguration<T extends Parameter[] | [] = []> = Action<T>[] | ((ctx: {
+    properties: any;
+    url?: string;
+}) => Action<T>[]);
+interface OnBeforeRequestOptions {
+    threadId?: string;
+    runId?: string;
+    inputMessages: Message[];
+    properties: any;
+    url?: string;
+}
+type OnBeforeRequestHandler = (options: OnBeforeRequestOptions) => void | Promise<void>;
+interface OnAfterRequestOptions {
+    threadId: string;
+    runId?: string;
+    inputMessages: Message[];
+    outputMessages: Message[];
+    properties: any;
+    url?: string;
+}
+type OnAfterRequestHandler = (options: OnAfterRequestOptions) => void | Promise<void>;
+interface OnStopGenerationOptions {
+    threadId: string;
+    runId?: string;
+    url?: string;
+    agentName?: string;
+    lastMessage: MessageInput;
+}
+type OnStopGenerationHandler = (options: OnStopGenerationOptions) => void | Promise<void>;
+interface Middleware {
+    /**
+     * A function that is called before the request is processed.
+     */
+    /**
+     * @deprecated This middleware hook is deprecated and will be removed in a future version.
+     * Use updated middleware integration methods in CopilotRuntimeVNext instead.
+     */
+    onBeforeRequest?: OnBeforeRequestHandler;
+    /**
+     * A function that is called after the request is processed.
+     */
+    /**
+     * @deprecated This middleware hook is deprecated and will be removed in a future version.
+     * Use updated middleware integration methods in CopilotRuntimeVNext instead.
+     */
+    onAfterRequest?: OnAfterRequestHandler;
+}
+interface CopilotRuntimeConstructorParams_BASE<T extends Parameter[] | [] = []> {
+    /**
+     * Middleware to be used by the runtime.
+     *
+     * ```ts
+     * onBeforeRequest: (options: {
+     *   threadId?: string;
+     *   runId?: string;
+     *   inputMessages: Message[];
+     *   properties: any;
+     * }) => void | Promise<void>;
+     * ```
+     *
+     * ```ts
+     * onAfterRequest: (options: {
+     *   threadId?: string;
+     *   runId?: string;
+     *   inputMessages: Message[];
+     *   outputMessages: Message[];
+     *   properties: any;
+     * }) => void | Promise<void>;
+     * ```
+     */
+    /**
+     * @deprecated This middleware hook is deprecated and will be removed in a future version.
+     * Use updated middleware integration methods in CopilotRuntimeVNext instead.
+     */
+    middleware?: Middleware;
+    actions?: ActionsConfiguration<T>;
+    remoteActions?: CopilotKitEndpoint[];
+    remoteEndpoints?: EndpointDefinition[];
+    langserve?: RemoteChainParameters[];
+    agents?: Record<string, AbstractAgent>;
+    delegateAgentProcessingToServiceAdapter?: boolean;
+    /**
+     * Configuration for LLM request/response logging.
+     * Requires publicApiKey from CopilotKit component to be set:
+     *
+     * ```tsx
+     * <CopilotKit publicApiKey="ck_pub_..." />
+     * ```
+     *
+     * Example logging config:
+     * ```ts
+     * logging: {
+     *   enabled: true, // Enable or disable logging
+     *   progressive: true, // Set to false for buffered logging
+     *   logger: {
+     *     logRequest: (data) => langfuse.trace({ name: "LLM Request", input: data }),
+     *     logResponse: (data) => langfuse.trace({ name: "LLM Response", output: data }),
+     *     logError: (errorData) => langfuse.trace({ name: "LLM Error", metadata: errorData }),
+     *   },
+     * }
+     * ```
+     */
+    observability_c?: CopilotObservabilityConfig;
+    /**
+     * Configuration for connecting to Model Context Protocol (MCP) servers.
+     * Allows fetching and using tools defined on external MCP-compliant servers.
+     * Requires providing the `createMCPClient` function during instantiation.
+     * @experimental
+     */
+    mcpServers?: MCPEndpointConfig[];
+    /**
+     * A function that creates an MCP client instance for a given endpoint configuration.
+     * This function is responsible for using the appropriate MCP client library
+     * (e.g., `@copilotkit/runtime`, `ai`) to establish a connection.
+     * Required if `mcpServers` is provided.
+     *
+     * ```typescript
+     * import { experimental_createMCPClient } from "ai"; // Import from vercel ai library
+     * // ...
+     * const runtime = new CopilotRuntime({
+     *   mcpServers: [{ endpoint: "..." }],
+     *   async createMCPClient(config) {
+     *     return await experimental_createMCPClient({
+     *       transport: {
+     *         type: "sse",
+     *         url: config.endpoint,
+     *         headers: config.apiKey
+     *           ? { Authorization: `Bearer ${config.apiKey}` }
+     *           : undefined,
+     *       },
+     *     });
+     *   }
+     * });
+     * ```
+     */
+    createMCPClient?: CreateMCPClientFunction;
+    /**
+     * Optional error handler for comprehensive debugging and observability.
+     *
+     * **Requires publicApiKey**: Error handling only works when requests include a valid publicApiKey.
+     * This is a premium Copilot Cloud feature.
+     *
+     * @param errorEvent - Structured error event with rich debugging context
+     *
+     * @example
+     * ```typescript
+     * const runtime = new CopilotRuntime({
+     *   onError: (errorEvent) => {
+     *     debugDashboard.capture(errorEvent);
+     *   }
+     * });
+     * ```
+     */
+    onError?: CopilotErrorHandler;
+    onStopGeneration?: OnStopGenerationHandler;
+}
+interface CopilotRuntimeConstructorParams<T extends Parameter[] | [] = []> extends Omit<CopilotRuntimeConstructorParams_BASE<T>, "agents">, Omit<CopilotRuntimeOptions, "agents" | "transcriptionService"> {
+    /**
+     * TODO: un-omit `transcriptionService` above once it's supported
+     *
+     * This satisfies...
+     *  – the optional constraint in `CopilotRuntimeConstructorParams_BASE`
+     *  – the `MaybePromise<NonEmptyRecord<T>>` constraint in `CopilotRuntimeOptionsVNext`
+     *  – the `Record<string, AbstractAgent>` constraint in `both
+     */
+    agents?: MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;
+}
+/**
+ * Central runtime object passed to all request handlers.
+ */
+declare class CopilotRuntime {
+    params?: CopilotRuntimeConstructorParams;
+    private observability?;
+    private mcpToolsCache;
+    private runtimeArgs;
+    private _instance;
+    constructor(params?: CopilotRuntimeConstructorParams & PartialBy<CopilotRuntimeOptions, "agents">);
+    get instance(): CopilotRuntime$1;
+    private assignEndpointsToAgents;
+    handleServiceAdapter(serviceAdapter: CopilotServiceAdapter): void;
+    private getToolsFromActions;
+    private assignToolsToAgents;
+    private createOnBeforeRequestHandler;
+    private createOnAfterRequestHandler;
+    /**
+     * Log LLM request if observability is enabled
+     */
+    private logObservabilityBeforeRequest;
+    /**
+     * Log final LLM response after request completes
+     */
+    private logObservabilityAfterRequest;
+    private getToolsFromMCP;
+}
+declare function copilotKitEndpoint(config: Omit<CopilotKitEndpoint, "type">): CopilotKitEndpoint;
+declare function langGraphPlatformEndpoint(config: Omit<LangGraphPlatformEndpoint, "type">): LangGraphPlatformEndpoint;
+declare function resolveEndpointType(endpoint: EndpointDefinition): EndpointType;
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+type CopilotRuntimeLogger = ReturnType<typeof createLogger>;
+declare function createLogger(options?: {
+    level?: LogLevel;
+    component?: string;
+}): pino.Logger<never>;
+
+declare const logger: pino.Logger<never>;
+declare const addCustomHeaderPlugin: {
+    onResponse({ response }: {
+        response: any;
+    }): void;
+};
+type AnyPrimitive = string | boolean | number | null;
+type CopilotRequestContextProperties = Record<string, AnyPrimitive | Record<string, AnyPrimitive>>;
+type GraphQLContext = YogaInitialContext & {
+    _copilotkit: CreateCopilotRuntimeServerOptions;
+    properties: CopilotRequestContextProperties;
+    logger: typeof logger;
+};
+interface CreateCopilotRuntimeServerOptions {
+    runtime: CopilotRuntime;
+    serviceAdapter: CopilotServiceAdapter;
+    endpoint: string;
+    baseUrl?: string;
+    cloud?: CopilotCloudOptions;
+    properties?: CopilotRequestContextProperties;
+    logLevel?: LogLevel;
+}
+declare function createContext(initialContext: YogaInitialContext, copilotKitContext: CreateCopilotRuntimeServerOptions, contextLogger: typeof logger, properties?: CopilotRequestContextProperties): Promise<Partial<GraphQLContext>>;
+declare function buildSchema(options?: {
+    emitSchemaFile?: string;
+}): graphql.GraphQLSchema;
+type CommonConfig = {
+    logging: typeof logger;
+    schema: ReturnType<typeof buildSchema>;
+    plugins: Parameters<typeof createYoga>[0]["plugins"];
+    context: (ctx: YogaInitialContext) => Promise<Partial<GraphQLContext>>;
+    maskedErrors: {
+        maskError: (error: any, message: string, isDev?: boolean) => any;
+    };
+};
+declare function getCommonConfig(options: CreateCopilotRuntimeServerOptions): CommonConfig;
+
+export { CopilotRequestContextProperties as C, GraphQLContext as G, LogLevel as L, MCPTool as M, addCustomHeaderPlugin as a, CreateCopilotRuntimeServerOptions as b, createContext as c, buildSchema as d, CommonConfig as e, CopilotRuntimeLogger as f, getCommonConfig as g, createLogger as h, CopilotRuntimeConstructorParams_BASE as i, CopilotRuntime as j, copilotKitEndpoint as k, langGraphPlatformEndpoint as l, MCPClient as m, MCPEndpointConfig as n, extractParametersFromSchema as o, convertMCPToolsToActions as p, generateMcpToolInstructions as q, resolveEndpointType as r };