@copilotkit/runtime

Version:

github.com/CopilotKit/CopilotKit

CopilotKit/CopilotKit

1 lines • 5.18 kB

Source Map (JSON)

View Raw

{"version":3,"file":"node.mjs","names":[],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"sourcesContent":["import { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotRuntimeHandlerOptions } from \"../core/fetch-handler\";\nimport type { RuntimeWithDeclaredChannels } from \"../core/runtime\";\nimport type { ChannelsControl } from \"../core/channel-manager\";\nimport { createCopilotNodeHandler } from \"./node-fetch-handler\";\nimport type { NodeFetchHandler } from \"./node-fetch-handler\";\n\n/**\n * A Node.js HTTP request listener that is also a callable object carrying an\n * optional {@link ChannelsControl} surface, mirroring\n * `CopilotRuntimeFetchHandler.channels`. Node is the long-running,\n * lifecycle-owning entry point for the runtime, so it is the surface that\n * exposes `.channels` for callers that need to start, observe, or stop managed\n * Channel activation.\n */\nexport type NodeCopilotListener = NodeFetchHandler & {\n channels?: ChannelsControl;\n};\n\n/**\n * A {@link NodeCopilotListener} whose {@link ChannelsControl} surface is\n * guaranteed present. Returned when the runtime was constructed with at least\n * one declared Intelligence Channel and activation was not opted out of, so the\n * documented `listener.channels.ready(...)` call type-checks without a `!` or a\n * `?.` under strict TypeScript — the Node mirror of\n * `CopilotRuntimeFetchHandlerWithChannels`.\n */\nexport type NodeCopilotListenerWithChannels = NodeFetchHandler & {\n /** Lifecycle control surface for the runtime's declared managed Channels. */\n channels: ChannelsControl;\n};\n\n/**\n * Convenience wrapper for creating a Node.js HTTP request listener\n * from CopilotKit runtime handler options.\n *\n * When the runtime declares managed Channels (and activation was not opted\n * out of via `activateChannels: false`), the returned listener exposes\n * `.channels` — the same {@link ChannelsControl} surface carried by the\n * underlying fetch handler.\n *\n * ## Managed Channels lifecycle\n *\n * Creating the listener opens NO connection. Activation — which opens the\n * persistent Realtime Gateway WebSocket and starts every direct adapter on the\n * declared Channels — is LAZY: it is triggered by the first\n * `await listener.channels.ready()` and never before, neither at creation nor on\n * the first HTTP request. On a long-running host that call is REQUIRED, not\n * optional: without it the process serves HTTP but no Channel is ever connected.\n * `listener.channels.stop()` tears activation down. See the\n * `createCopilotRuntimeHandler` TSDoc for why activation is deferred\n * (serverless/edge safety).\n *\n * @example\n * ```typescript\n * import { createServer } from \"node:http\";\n * import { CopilotRuntime } from \"@copilotkit/runtime/v2\";\n * import { createCopilotNodeListener } from \"@copilotkit/runtime/v2/node\";\n *\n * const listener = createCopilotNodeListener({\n * runtime: new CopilotRuntime({ agents: { ... } }),\n * basePath: \"/api/copilotkit\",\n * cors: true,\n * });\n * createServer(listener).listen(3000);\n *\n * // Required to connect declared managed Channels. Bound it so one wedged\n * // adapter cannot hang startup forever.\n * await listener.channels.ready({ timeoutMs: 30_000 });\n * ```\n */\n/**\n * Overload: a runtime constructed with at least one declared Intelligence\n * Channel (a {@link RuntimeWithDeclaredChannels}-branded runtime), when\n * activation is not disabled, yields a listener with a **non-optional**\n * {@link ChannelsControl}. `activateChannels` is constrained to\n * `true | undefined` here so passing `activateChannels: false` (which leaves no\n * `.channels`) falls through to the optional-shape overload below rather than\n * dishonestly promising a control surface that will not exist. Mirrors the\n * `createCopilotRuntimeHandler` overload pair so the brand survives the wrapper.\n *\n * The brand comes from constructing the runtime with a literal non-empty\n * `channels` list (`readonly [Channel, ...Channel[]]`). A runtime built from a\n * dynamically-assembled `Channel[]` is not branded, so it falls to the\n * optional-shape overload and its call sites still need `?.`.\n */\nexport function createCopilotNodeListener(\n options: CopilotRuntimeHandlerOptions & {\n runtime: RuntimeWithDeclaredChannels;\n activateChannels?: true | undefined;\n },\n): NodeCopilotListenerWithChannels;\n/**\n * Overload: every other runtime (SSE, Intelligence without channels, or with\n * activation disabled) yields a listener whose `.channels` is optional.\n */\nexport function createCopilotNodeListener(\n options: CopilotRuntimeHandlerOptions,\n): NodeCopilotListener;\nexport function createCopilotNodeListener(\n options: CopilotRuntimeHandlerOptions,\n): NodeCopilotListener {\n const handler = createCopilotRuntimeHandler(options);\n const listener: NodeCopilotListener = createCopilotNodeHandler(handler);\n listener.channels = handler.channels;\n return listener;\n}\n"],"mappings":";;;;;AAmGA,SAAgB,0BACd,SACqB;CACrB,MAAM,UAAU,4BAA4B,QAAQ;CACpD,MAAM,WAAgC,yBAAyB,QAAQ;AACvE,UAAS,WAAW,QAAQ;AAC5B,QAAO"}