@copilotkit/runtime 2.0.0-next.1 → 2.0.0-rc.0

package/dist/runtime/core/fetch-handler.d.cts

@@ -0,0 +1,100 @@
+import { CopilotRuntimeLike, RuntimeWithDeclaredChannels } from "./runtime.cjs";
+import { ActivateChannelEngine, ChannelsControl } from "./channel-manager.cjs";
+import { CopilotRuntimeHooks } from "./hooks.cjs";
+import { CopilotCorsConfig } from "./fetch-cors.cjs";
+
+//#region src/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.
+   *
+   * The process-owning wrappers (`createCopilotNodeListener`,
+   * `createCopilotExpressHandler`) also START activation when this is left on,
+   * so `false` is the opt-out that keeps a mounted listener socket-free in a test
+   * or a short-lived script.
+   */
+  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.cts.map

package/dist/runtime/core/fetch-handler.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-handler.d.cts","names":[],"sources":["../../../src/runtime/core/fetch-handler.ts"],"mappings":";;;;;;UAgJiB,4BAAA;EACf,OAAA,EAAS,kBAAA;;;;;;;;;;EAWT,QAAA;EA8JA;;;;AASF;EAhKE,IAAA;;;;;;EAOA,IAAA,aAAiB,iBAAA;EA2JU;;;EAtJ3B,KAAA,GAAQ,mBAAA;;;;;;;;;;;;;;;EAgBR,gBAAA;;;;;;EAOA,eAAA,GAAkB,qBAAA;AAAA;;;;;;;KASR,0BAAA,KACV,OAAA,EAAS,OAAA,KACN,OAAA,CAAQ,QAAA;;;;;EAKX,QAAA,GAAW,eAAA;AAAA;;;;;;;;KAUD,sCAAA,KACV,OAAA,EAAS,OAAA,KACN,OAAA,CAAQ,QAAA;gFAEX,QAAA,EAAU,eAAA;AAAA;;;;;;;;;;iBAqFI,2BAAA,CACd,OAAA,EAAS,4BAAA;EACP,OAAA,EAAS,2BAAA;EACT,gBAAA;AAAA,IAED,sCAAA;;;;;iBAKa,2BAAA,CACd,OAAA,EAAS,4BAAA,GACR,0BAAA"}

package/dist/runtime/core/fetch-handler.d.mts

@@ -0,0 +1,100 @@
+import { CopilotRuntimeLike, RuntimeWithDeclaredChannels } from "./runtime.mjs";
+import { ActivateChannelEngine, ChannelsControl } from "./channel-manager.mjs";
+import { CopilotRuntimeHooks } from "./hooks.mjs";
+import { CopilotCorsConfig } from "./fetch-cors.mjs";
+
+//#region src/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.
+   *
+   * The process-owning wrappers (`createCopilotNodeListener`,
+   * `createCopilotExpressHandler`) also START activation when this is left on,
+   * so `false` is the opt-out that keeps a mounted listener socket-free in a test
+   * or a short-lived script.
+   */
+  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

package/dist/runtime/core/fetch-handler.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-handler.d.mts","names":[],"sources":["../../../src/runtime/core/fetch-handler.ts"],"mappings":";;;;;;UAgJiB,4BAAA;EACf,OAAA,EAAS,kBAAA;;;;;;;;;;EAWT,QAAA;EA8JA;;;;AASF;EAhKE,IAAA;;;;;;EAOA,IAAA,aAAiB,iBAAA;EA2JU;;;EAtJ3B,KAAA,GAAQ,mBAAA;;;;;;;;;;;;;;;EAgBR,gBAAA;;;;;;EAOA,eAAA,GAAkB,qBAAA;AAAA;;;;;;;KASR,0BAAA,KACV,OAAA,EAAS,OAAA,KACN,OAAA,CAAQ,QAAA;;;;;EAKX,QAAA,GAAW,eAAA;AAAA;;;;;;;;KAUD,sCAAA,KACV,OAAA,EAAS,OAAA,KACN,OAAA,CAAQ,QAAA;gFAEX,QAAA,EAAU,eAAA;AAAA;;;;;;;;;;iBAqFI,2BAAA,CACd,OAAA,EAAS,4BAAA;EACP,OAAA,EAAS,2BAAA;EACT,gBAAA;AAAA,IAED,sCAAA;;;;;iBAKa,2BAAA,CACd,OAAA,EAAS,4BAAA,GACR,0BAAA"}