@copilotkit/runtime 1.50.0-beta.9 → 1.50.0

package/dist/service-adapters/index.mjs

@@ -4,16 +4,14 @@ import {
   EmptyAdapter,
   ExperimentalEmptyAdapter,
   ExperimentalOllamaAdapter,
-  RemoteChain
-} from "../chunk-TTUAEJLD.mjs";
-import {
   GoogleGenerativeAIAdapter,
   GroqAdapter,
   LangChainAdapter,
   OpenAIAdapter,
   OpenAIAssistantAdapter,
+  RemoteChain,
   UnifyAdapter
-} from "../chunk-SBCOROE4.mjs";
+} from "../chunk-27JKTS6P.mjs";
 import {
   convertServiceAdapterError
 } from "../chunk-AMUJQ6IR.mjs";

package/dist/shared-0a7346ce.d.ts

@@ -0,0 +1,466 @@
+import * as graphql from 'graphql';
+import * as createPinoLogger from 'pino';
+import createPinoLogger__default from 'pino';
+import { YogaInitialContext, createYoga } from 'graphql-yoga';
+import { Parameter, Action, CopilotErrorHandler } from '@copilotkit/shared';
+import { b as CopilotServiceAdapter, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, R as RemoteChainParameters, f as RuntimeEventSource, g as ExtensionsResponse } from './langserve-0c6100e3.js';
+import { b as MessageInput, M as Message } from './index-96b330da.js';
+import { CopilotCloudOptions } from './lib/cloud/index.js';
+import { AbstractAgent } from '@ag-ui/client';
+
+declare enum MetaEventName {
+    LangGraphInterruptEvent = "LangGraphInterruptEvent",
+    CopilotKitLangGraphInterruptEvent = "CopilotKitLangGraphInterruptEvent"
+}
+
+declare class MetaEventInput {
+    name: MetaEventName;
+    value?: string;
+    response?: string;
+    messages?: MessageInput[];
+}
+
+declare class CopilotContextInput {
+    description: string;
+    value: string;
+}
+
+type EndpointDefinition = CopilotKitEndpoint | LangGraphPlatformEndpoint;
+declare enum EndpointType {
+    CopilotKit = "copilotKit",
+    LangGraphPlatform = "langgraph-platform"
+}
+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[];
+}
+
+declare class Agent {
+    id: string;
+    name: string;
+    description?: string;
+}
+
+declare class LoadAgentStateResponse {
+    threadId: string;
+    threadExists: boolean;
+    state: string;
+    messages: string;
+}
+
+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>;
+
+interface CopilotRuntimeRequest {
+    serviceAdapter: CopilotServiceAdapter;
+    messages: MessageInput[];
+    actions: ActionInput[];
+    agentSession?: AgentSessionInput;
+    agentStates?: AgentStateInput[];
+    outputMessagesPromise: Promise<Message[]>;
+    threadId?: string;
+    runId?: string;
+    publicApiKey?: string;
+    graphqlContext: GraphQLContext;
+    forwardedParameters?: ForwardedParametersInput;
+    url?: string;
+    extensions?: ExtensionsInput;
+    metaEvents?: MetaEventInput[];
+    context?: CopilotContextInput[];
+}
+interface CopilotRuntimeResponse {
+    threadId: string;
+    runId?: string;
+    eventSource: RuntimeEventSource;
+    serverSideActions: Action<any>[];
+    actionInputsWithoutAgents: ActionInput[];
+    extensions?: ExtensionsResponse;
+}
+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.
+     */
+    onBeforeRequest?: OnBeforeRequestHandler;
+    /**
+     * A function that is called after the request is processed.
+     */
+    onAfterRequest?: OnAfterRequestHandler;
+}
+type AgentWithEndpoint = Agent & {
+    endpoint: EndpointDefinition;
+};
+interface CopilotRuntimeConstructorParams<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>;
+     * ```
+     */
+    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;
+}
+declare class CopilotRuntime<const T extends Parameter[] | [] = []> {
+    actions: ActionsConfiguration<T>;
+    agents: Record<string, AbstractAgent>;
+    remoteEndpointDefinitions: EndpointDefinition[];
+    private langserve;
+    private onBeforeRequest?;
+    private onAfterRequest?;
+    private onStopGeneration?;
+    private delegateAgentProcessingToServiceAdapter;
+    private observability?;
+    private availableAgents;
+    private onError?;
+    private hasWarnedAboutError;
+    private readonly mcpServersConfig?;
+    private mcpActionCache;
+    private readonly createMCPClientImpl?;
+    constructor(params?: CopilotRuntimeConstructorParams<T>);
+    private injectMCPToolInstructions;
+    processRuntimeRequest(request: CopilotRuntimeRequest): Promise<CopilotRuntimeResponse>;
+    getAllAgents(graphqlContext: GraphQLContext): Promise<(AgentWithEndpoint | Agent)[]>;
+    discoverAgentsFromEndpoints(graphqlContext: GraphQLContext): Promise<AgentWithEndpoint[]>;
+    discoverAgentsFromAgui(): Agent[];
+    loadAgentState(graphqlContext: GraphQLContext, threadId: string, agentName: string): Promise<LoadAgentStateResponse>;
+    private processAgentRequest;
+    private getServerSideActions;
+    private detectProvider;
+    private convertStreamingErrorToStructured;
+    private error;
+    /**
+     * Public method to handle GraphQL validation errors
+     * This allows the GraphQL resolver to send validation errors through the error system
+     */
+    errorGraphQLError(error: {
+        message: string;
+        code: string;
+        type: string;
+    }, context: {
+        operation: string;
+        cloudConfigPresent: boolean;
+        guardrailsEnabled: boolean;
+    }): Promise<void>;
+}
+declare function flattenToolCallsNoDuplicates(toolsByPriority: ActionInput[]): ActionInput[];
+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;
+}): createPinoLogger__default.Logger<never>;
+
+declare const logger: createPinoLogger.default.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<any>;
+    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, CopilotRuntimeRequest as i, CopilotRuntimeConstructorParams as j, CopilotRuntime as k, flattenToolCallsNoDuplicates as l, copilotKitEndpoint as m, langGraphPlatformEndpoint as n, MCPClient as o, MCPEndpointConfig as p, extractParametersFromSchema as q, resolveEndpointType as r, convertMCPToolsToActions as s, generateMcpToolInstructions as t };

package/dist/{shared-f6d43ef8.d.ts → shared-35c6eb04.d.ts}

@@ -2,7 +2,7 @@ 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 { b as CopilotServiceAdapter, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, R as RemoteChainParameters } from './langserve-74a52292.js';
+import { b as CopilotServiceAdapter, A as ActionInput, d as AgentSessionInput, e as AgentStateInput, F as ForwardedParametersInput, E as ExtensionsInput, R as RemoteChainParameters } from './langserve-9fc76ce5.js';
 import { CopilotRuntime as CopilotRuntime$1, CopilotRuntimeOptions } from '@copilotkitnext/runtime';
 import { a as MessageInput, M as Message } from './index-adbd78f1.js';
 import { CopilotCloudOptions } from './lib/cloud/index.js';
@@ -362,6 +362,8 @@ interface CopilotRuntimeConstructorParams_BASE<T extends Parameter[] | [] = []>
 }
 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`