@copilotkit/runtime

require("reflect-metadata"); import { ForwardHeadersConfig, ResolvedForwardHeadersPolicy } from "../handlers/header-utils.cjs"; import { AfterRequestMiddleware, BeforeRequestMiddleware } from "./middleware.cjs"; import { CopilotRuntimeLogger } from "../../../lib/logger.cjs"; import { TranscriptionService } from "../transcription-service/transcription-service.cjs"; import { DebugEventBus } from "./debug-event-bus.cjs"; import { AgentRunner } from "../runner/agent-runner.cjs"; import { CopilotKitIntelligence } from "../intelligence-platform/client.cjs"; import { DebugConfig, MaybePromise, NonEmptyRecord, RUNTIME_MODE_INTELLIGENCE, RUNTIME_MODE_SSE, ResolvedDebugConfig, RuntimeMode } from "@copilotkit/shared"; import { LicenseChecker } from "@copilotkit/license-verifier"; import { AbstractAgent } from "@ag-ui/client"; import { MCPClientConfig } from "@ag-ui/mcp-apps-middleware"; import { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware"; import { Channel } from "@copilotkit/channels-core"; //#region src/v2/runtime/core/runtime.d.ts declare const VERSION: string; interface BaseCopilotRuntimeMiddlewareOptions { /** If set, middleware only applies to these named agents. Applies to all agents if omitted. */ agents?: string[]; } type McpAppsServerConfig = MCPClientConfig & { /** Agent to bind this server to. If omitted, the server is available to all agents. */agentId?: string; }; interface McpAppsConfig { /** List of MCP server configurations. */ servers: McpAppsServerConfig[]; } interface OpenGenerativeUIOptions extends BaseCopilotRuntimeMiddlewareOptions {} type OpenGenerativeUIConfig = boolean | OpenGenerativeUIOptions; interface CopilotRuntimeMiddlewares { /** * Auto-apply A2UIMiddleware to agents at run time. * Pass an object to enable and customise behaviour, or omit to disable. */ a2ui?: BaseCopilotRuntimeMiddlewareOptions & A2UIMiddlewareConfig & { /** * Explicit on/off switch. Omit (or set `true`) to enable; set `false` * to disable A2UI for this runtime while keeping the rest of the config * (e.g. a `schema`/`catalog`) in place. A bare `a2ui: {}` stays enabled * for backwards compatibility. */ enabled?: boolean; }; /** Auto-apply MCPAppsMiddleware to agents at run time. */ mcpApps?: McpAppsConfig; /** Auto-apply OpenGenerativeUIMiddleware to agents at run time. */ openGenerativeUI?: OpenGenerativeUIConfig; } /** * Context passed to agent factory functions for per-request agent resolution. */ interface AgentFactoryContext { /** The incoming HTTP request. */ request: Request; } /** * A function that dynamically creates agents on a per-request basis. * Useful for multi-tenant scenarios or request-scoped agent configuration. */ type AgentsFactory = (ctx: AgentFactoryContext) => MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>; /** * Agents can be provided as: * - A static record of agents * - A Promise that resolves to a record of agents * - A factory function that receives request context and returns agents (or a Promise of agents) */ type AgentsConfig = MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>> | AgentsFactory; /** * Resolve an AgentsConfig value to a concrete record of agents. * If the config is a factory function, it is called with the given request context. * Otherwise it is awaited directly (static record or Promise). */ declare function resolveAgents(agents: AgentsConfig, request?: Request): Promise<Record<string, AbstractAgent>>; interface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares { /** * Map of available agents, or a factory function for per-request agent resolution. * * Static record: * ```ts * agents: { support: new SupportAgent(), technical: new TechnicalAgent() } * ``` * * Factory function (called per-request): * ```ts * agents: ({ request }) => { * const tenantId = request.headers.get("x-tenant-id"); * return { default: createAgentForTenant(tenantId) }; * } * ``` */ agents: AgentsConfig; /** Optional transcription service for audio processing. */ transcriptionService?: TranscriptionService; /** Optional *before* middleware – callback function or webhook URL. */ beforeRequestMiddleware?: BeforeRequestMiddleware; /** Optional *after* middleware – callback function or webhook URL. */ afterRequestMiddleware?: AfterRequestMiddleware; /** Signed license token for server-side feature verification. Falls back to COPILOTKIT_LICENSE_TOKEN env var. */ licenseToken?: string; /** Enable debug logging for the event pipeline. */ debug?: DebugConfig; /** * Policy controlling which inbound HTTP headers are forwarded onto the * outgoing agent call. By default a built-in denylist strips known * infrastructure/proxy/platform headers (`x-forwarded-*`, `x-real-ip`, * `x-vercel-*`, `x-copilotcloud-*`, etc.) while `authorization` and custom * `x-*` application headers continue to forward (#5712). Set * `{ useDefaultDenylist: false }` to restore the previous wide-open behavior. */ forwardHeaders?: ForwardHeadersConfig; } interface CopilotRuntimeUser { id: string; name: string; } type IdentifyUserCallback = (request: Request) => MaybePromise<CopilotRuntimeUser>; interface CopilotSseRuntimeOptions extends BaseCopilotRuntimeOptions { /** The runner to use for running agents in SSE mode. */ runner?: AgentRunner; intelligence?: undefined; generateThreadNames?: undefined; /** Intelligence Channels require the Intelligence runtime; not available in SSE mode. */ channels?: undefined; } interface CopilotIntelligenceRuntimeOptions extends BaseCopilotRuntimeOptions { /** Configures Intelligence mode for durable threads and realtime events. */ intelligence: CopilotKitIntelligence; /** Resolves the authenticated user for intelligence requests. */ identifyUser: IdentifyUserCallback; /** Auto-generate short names for newly created threads. */ generateThreadNames?: boolean; /** Max delay (ms) for WebSocket reconnect backoff. @default 10_000 */ maxReconnectMs?: number; /** Max delay (ms) for channel rejoin backoff. @default 30_000 */ maxRejoinMs?: number; /** Lock TTL in seconds. Clamped to a maximum of 3600 (1 hour). @default 20 */ lockTtlSeconds?: number; /** Custom Redis key prefix for the thread lock. */ lockKeyPrefix?: string; /** Interval in seconds at which the runtime renews the thread lock. Clamped to a maximum of 3000 (50 minutes). @default 15 */ lockHeartbeatIntervalSeconds?: number; /** * Intelligence Channels declared by this runtime. Each is a * `createChannel({ name })` instance. Only available on the Intelligence runtime * path. Names are validated (required, lowercase kebab-case, unique) and wired * to delivery/egress transports when activated via `startChannels` from * `@copilotkit/channels-intelligence` — not at construction. */ channels?: Channel[]; } type CopilotRuntimeOptions = CopilotSseRuntimeOptions | CopilotIntelligenceRuntimeOptions; interface CopilotRuntimeLike { agents: CopilotRuntimeOptions["agents"]; transcriptionService: CopilotRuntimeOptions["transcriptionService"]; beforeRequestMiddleware: CopilotRuntimeOptions["beforeRequestMiddleware"]; afterRequestMiddleware: CopilotRuntimeOptions["afterRequestMiddleware"]; runner: AgentRunner; a2ui: CopilotRuntimeOptions["a2ui"]; mcpApps: CopilotRuntimeOptions["mcpApps"]; openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"]; intelligence?: CopilotKitIntelligence; identifyUser?: IdentifyUserCallback; mode: RuntimeMode; licenseChecker?: LicenseChecker; debugEventBus?: DebugEventBus; debug: ResolvedDebugConfig; debugLogger?: CopilotRuntimeLogger; /** * Resolved inbound-header forwarding policy read by the /run and /connect call * sites. Optional on the published interface so an external `CopilotRuntimeLike` * implementor predating this field stays source-compatible (non-breaking minor * release). Concrete runtimes (`BaseCopilotRuntime`) always resolve and set it; * the call sites coalesce a missing value to the default resolved policy * (`resolveForwardHeadersPolicy(undefined)` — default-on denylist). */ forwardHeadersPolicy?: ResolvedForwardHeadersPolicy; } interface CopilotSseRuntimeLike extends CopilotRuntimeLike { intelligence?: undefined; mode: typeof RUNTIME_MODE_SSE; } interface CopilotIntelligenceRuntimeLike extends CopilotRuntimeLike { intelligence: CopilotKitIntelligence; identifyUser: IdentifyUserCallback; generateThreadNames: boolean; lockTtlSeconds: number; lockKeyPrefix?: string; lockHeartbeatIntervalSeconds: number; channels: Channel[]; mode: typeof RUNTIME_MODE_INTELLIGENCE; } declare abstract class BaseCopilotRuntime implements CopilotRuntimeLike { agents: CopilotRuntimeOptions["agents"]; transcriptionService: CopilotRuntimeOptions["transcriptionService"]; beforeRequestMiddleware: CopilotRuntimeOptions["beforeRequestMiddleware"]; afterRequestMiddleware: CopilotRuntimeOptions["afterRequestMiddleware"]; runner: AgentRunner; a2ui: CopilotRuntimeOptions["a2ui"]; mcpApps: CopilotRuntimeOptions["mcpApps"]; openGenerativeUI: CopilotRuntimeOptions["openGenerativeUI"]; licenseChecker?: LicenseChecker; readonly debugEventBus?: DebugEventBus; debug: ResolvedDebugConfig; debugLogger?: CopilotRuntimeLogger; readonly forwardHeadersPolicy: ResolvedForwardHeadersPolicy; /** * License token resolved once with the env fallback, so telemetry * attribution (below) and subclass feature gating * (CopilotIntelligenceRuntime's licenseChecker) read the exact same value * instead of each re-applying `?? COPILOTKIT_LICENSE_TOKEN`. */ protected readonly resolvedLicenseToken?: string; abstract readonly intelligence?: CopilotKitIntelligence; abstract readonly mode: RuntimeMode; constructor(options: BaseCopilotRuntimeOptions, runner: AgentRunner); } declare class CopilotSseRuntime extends BaseCopilotRuntime implements CopilotSseRuntimeLike { readonly intelligence: any; readonly mode: "sse"; constructor(options: CopilotSseRuntimeOptions); } declare class CopilotIntelligenceRuntime extends BaseCopilotRuntime implements CopilotIntelligenceRuntimeLike { readonly intelligence: CopilotKitIntelligence; readonly identifyUser: IdentifyUserCallback; readonly generateThreadNames: boolean; readonly lockTtlSeconds: number; readonly lockKeyPrefix?: string; readonly lockHeartbeatIntervalSeconds: number; readonly channels: Channel[]; readonly mode: "intelligence"; /** Maximum allowed lock TTL in seconds (1 hour). */ static readonly MAX_LOCK_TTL_SECONDS = 3600; /** Maximum allowed heartbeat interval in seconds (50 minutes). */ static readonly MAX_HEARTBEAT_INTERVAL_SECONDS = 3000; constructor(options: CopilotIntelligenceRuntimeOptions); } declare function isIntelligenceRuntime(runtime: CopilotRuntimeLike): runtime is CopilotIntelligenceRuntimeLike; /** * Single source of truth for "is A2UI on for this runtime?". Both the run path * (which applies `A2UIMiddleware`) and the `/info` response (which tells the * client whether to mount the A2UI renderer + catalog context) MUST go through * this, so they can never disagree — the divergence between them was the root * of CopilotKit/CopilotKit#5369. * * Backwards compatible: any config object is enabled (matching the historical * `!!runtime.a2ui`); only an explicit `enabled: false` turns it off. */ declare function isA2UIEnabled(a2ui: CopilotRuntimeOptions["a2ui"]): a2ui is NonNullable<CopilotRuntimeOptions["a2ui"]>; /** * Compile-time phantom brand marking a {@link CopilotRuntime} that was * constructed with at least one declared Intelligence Channel. It has no runtime * representation — the shim never sets this property; it exists purely so * `createCopilotRuntimeHandler` can tell, at the type level, that the resulting * handler will carry a non-optional `.channels` control surface. */ interface RuntimeWithDeclaredChannels { /** * @internal Phantom brand key. Never present at runtime; do not read or set. */ readonly __copilotkitChannelsDeclared: true; } /** * Instance shape of the {@link CopilotRuntime} compatibility shim. Extends * {@link CopilotRuntimeLike} with the Intelligence-only accessors the shim * surfaces (all `undefined` in SSE mode). Declared explicitly so the exported * `CopilotRuntime` name resolves as a type as well as a value. */ interface CopilotRuntime extends CopilotRuntimeLike { /** Auto-generate short thread names; `undefined` in SSE mode. */ generateThreadNames?: boolean; /** Thread lock TTL in seconds; `undefined` in SSE mode. */ lockTtlSeconds?: number; /** Custom Redis key prefix for the thread lock; `undefined` in SSE mode. */ lockKeyPrefix?: string; /** Thread lock heartbeat interval in seconds; `undefined` in SSE mode. */ lockHeartbeatIntervalSeconds?: number; /** Declared Intelligence Channels; `undefined` in SSE mode. */ channels?: Channel[]; } /** * Constructor type for the {@link CopilotRuntime} compatibility shim. * * The first overload fires when the caller passes `intelligence` together with a * non-empty `channels` tuple: it returns a {@link RuntimeWithDeclaredChannels}- * branded runtime, which `createCopilotRuntimeHandler` maps to a handler whose * `.channels` is non-optional. Every other configuration (SSE, or Intelligence * without channels, or an empty `channels: []`) falls through to the second * overload and stays unbranded, so its handler keeps `.channels` optional. * * A class constructor cannot vary its return type across overloads (it is pinned * to the instance type), so the branding lives on this construct-signature * interface instead of on the class itself. */ interface CopilotRuntimeConstructor { new (options: Omit<CopilotIntelligenceRuntimeOptions, "channels"> & { channels: readonly [Channel, ...Channel[]]; }): CopilotRuntime & RuntimeWithDeclaredChannels; new (options: CopilotRuntimeOptions): CopilotRuntime; } /** * The public `CopilotRuntime` constructor. Backed by {@link CopilotRuntimeShim} * but typed as {@link CopilotRuntimeConstructor} so that constructing with a * non-empty `channels` array yields a {@link RuntimeWithDeclaredChannels}-branded * runtime type. * * The `as unknown as` cast is required (not dishonest widening): the brand is a * phantom, compile-time-only marker with no runtime representation, so the shim * instances legitimately do not carry the brand property. Behavior is identical * to the former `class CopilotRuntime` — this only refines the static type. */ declare const CopilotRuntime: CopilotRuntimeConstructor; //#endregion export { AgentFactoryContext, AgentsConfig, AgentsFactory, CopilotIntelligenceRuntime, CopilotIntelligenceRuntimeLike, CopilotIntelligenceRuntimeOptions, CopilotRuntime, CopilotRuntimeConstructor, CopilotRuntimeLike, CopilotRuntimeOptions, CopilotRuntimeUser, CopilotSseRuntime, CopilotSseRuntimeLike, CopilotSseRuntimeOptions, IdentifyUserCallback, McpAppsConfig, McpAppsServerConfig, OpenGenerativeUIConfig, OpenGenerativeUIOptions, RuntimeWithDeclaredChannels, VERSION, isA2UIEnabled, isIntelligenceRuntime, resolveAgents }; //# sourceMappingURL=runtime.d.cts.map