@copilotkit/runtime/dist/v2/runtime/core/fetch-handler.d.mts

<img src="https://github.com/user-attachments/assets/0a6b64d9-e193-4940-a3f6-60334ac34084" alt="banner" style="border-radius: 12px; border: 2px solid #d6d4fa;" />

import "reflect-metadata";
import { CopilotRuntimeLike, RuntimeWithDeclaredChannels } from "./runtime.mjs";
import { CopilotCorsConfig } from "./fetch-cors.mjs";
import { CopilotRuntimeHooks } from "./hooks.mjs";
import { ActivateChannelEngine, ChannelsControl } from "./channel-manager.mjs";

//#region src/v2/runtime/core/fetch-handler.d.ts
interface CopilotRuntimeHandlerOptions {
  runtime: CopilotRuntimeLike;
  /**
   * Optional base path for routing.
   *
   * When provided: strict prefix stripping. The handler strips this prefix from the
   * URL pathname and matches the remainder against known routes.
   *
   * When omitted: suffix matching. The handler matches known route patterns as
   * suffixes of the URL pathname.
   */
  basePath?: string;
  /**
   * Endpoint mode:
   * - "multi-route" (default): Routes like POST /agent/:agentId/run, GET /info, etc.
   * - "single-route": Single POST endpoint with JSON envelope { method, params, body }
   */
  mode?: "multi-route" | "single-route";
  /**
   * Optional CORS configuration.
   * When not provided, no CORS headers are added (let the framework handle it).
   * Set to true for permissive defaults, or provide an object.
   */
  cors?: boolean | CopilotCorsConfig;
  /**
   * Lifecycle hooks for request processing.
   */
  hooks?: CopilotRuntimeHooks;
  /**
   * Whether the handler builds the runtime's declared managed-Channel control
   * surface. Defaults to `true`, which constructs the {@link ChannelManager} and
   * exposes `handler.channels` — but does NOT open any connection: activation is
   * lazy and triggered by the first `handler.channels.ready()` (see the factory
   * TSDoc). Set `false` to opt out entirely: no {@link ChannelManager} is
   * constructed and the returned handler has no `.channels`. Non-intelligence or
   * channel-less runtimes never build a control surface regardless of this flag.
   */
  activateChannels?: boolean;
  /**
   * @internal Test seam: inject a fake Channel activation engine so channel
   * activation runs without opening a real transport. Not part of the public
   * API and may change or be removed without notice.
   */
  __channelEngine?: ActivateChannelEngine;
}
/**
 * A framework-agnostic runtime handler: a `(Request) => Promise<Response>`
 * function that is also a callable object carrying an optional {@link channels}
 * control surface. A plain function is assignable to this type, so existing
 * call sites that treat it as `(Request) => Promise<Response>` keep working.
 */
type CopilotRuntimeFetchHandler = ((request: Request) => Promise<Response>) & {
  /**
   * Present only when the handler activated managed Channels for an
   * Intelligence runtime; the lifecycle control surface for those Channels.
   */
  channels?: ChannelsControl;
};
/**
 * A {@link CopilotRuntimeFetchHandler} whose {@link ChannelsControl} surface is
 * guaranteed present. Returned when the runtime was constructed with at least
 * one declared Intelligence Channel and activation was not opted out of, so the
 * documented `handler.channels.ready(...)` call type-checks without a `!` or
 * `?.` under strict TypeScript.
 */
type CopilotRuntimeFetchHandlerWithChannels = ((request: Request) => Promise<Response>) & {
  /** Lifecycle control surface for the runtime's activated managed Channels. */channels: ChannelsControl;
};
/**
 * Overload: a runtime constructed with at least one declared Intelligence
 * Channel (a {@link RuntimeWithDeclaredChannels}-branded runtime), when
 * activation is not disabled, yields a handler with a **non-optional**
 * {@link ChannelsControl}. `activateChannels` is constrained to `true | undefined`
 * here so passing `activateChannels: false` (which skips activation and leaves no
 * `.channels`) falls through to the optional-shape overload below rather than
 * dishonestly promising a control surface that will not exist.
 */
declare function createCopilotRuntimeHandler(options: CopilotRuntimeHandlerOptions & {
  runtime: RuntimeWithDeclaredChannels;
  activateChannels?: true | undefined;
}): CopilotRuntimeFetchHandlerWithChannels;
/**
 * Overload: every other runtime (SSE, Intelligence without channels, or with
 * activation disabled) yields a handler whose `.channels` is optional.
 */
declare function createCopilotRuntimeHandler(options: CopilotRuntimeHandlerOptions): CopilotRuntimeFetchHandler;
//#endregion
export { CopilotRuntimeFetchHandler, CopilotRuntimeFetchHandlerWithChannels, CopilotRuntimeHandlerOptions, createCopilotRuntimeHandler };
//# sourceMappingURL=fetch-handler.d.mts.map