@copilotkit/runtime 1.63.2 → 1.64.0

package/dist/v2/runtime/endpoints/express.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"express.mjs","names":[],"sources":["../../../../src/v2/runtime/endpoints/express.ts"],"sourcesContent":["import express from \"express\";\nimport type {\n  Request as ExpressRequest,\n  Response as ExpressResponse,\n  NextFunction,\n  Router,\n} from \"express\";\nimport cors from \"cors\";\nimport type { CorsOptions } from \"cors\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\nimport { createExpressNodeHandler } from \"./express-fetch-bridge\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\n\n/**\n * An Express {@link Router} that may also carry an optional\n * {@link ChannelsControl} surface. Express's Router is a request-scoped\n * middleware object, not a long-running process owner — Node\n * (`createCopilotNodeListener`) is the lifecycle-owning surface for\n * `.channels`. It is attached here too, best-effort, for callers that mount\n * the router directly and want to observe/stop managed Channel activation\n * without also standing up a Node listener.\n */\nexport type CopilotExpressRouter = Router & { channels?: ChannelsControl };\n\nexport interface CopilotExpressEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * CORS configuration for the Express router.\n   * - `true` (default): permissive CORS (`origin: \"*\"`, all methods, all headers).\n   * - `false`: no CORS middleware is applied — handle it yourself.\n   * - object: passed directly to the Express `cors()` middleware.\n   */\n  cors?: boolean | CorsOptions;\n\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler activates the runtime's declared managed\n   * Channels at creation time. Defaults to `true`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n\n/**\n * Creates an Express router that serves the CopilotKit runtime.\n *\n * In **multi-route** mode (default) the router exposes:\n * - `GET  {basePath}/info` — runtime info\n * - `POST {basePath}/agent/:agentId/run` — start an agent run\n * - `POST {basePath}/agent/:agentId/connect` — connect to an agent run\n * - `POST {basePath}/agent/:agentId/stop/:threadId` — stop an agent run\n * - `POST {basePath}/transcribe` — transcribe audio\n *\n * In **single-route** mode a single `POST {basePath}` endpoint accepts a JSON\n * envelope `{ method, params, body }` and dispatches to the appropriate handler.\n *\n * @example\n * ```typescript\n * import express from \"express\";\n * import { CopilotRuntime } from \"@copilotkit/runtime/v2\";\n * import { createCopilotExpressHandler } from \"@copilotkit/runtime/v2/express\";\n *\n * const runtime = new CopilotRuntime({\n *   agents: { default: new BuiltInAgent({ model: \"openai/gpt-4o-mini\" }) },\n * });\n *\n * const app = express();\n * app.use(createCopilotExpressHandler({\n *   runtime,\n *   basePath: \"/api/copilotkit\",\n *   cors: true,\n * }));\n * app.listen(4000);\n * ```\n *\n * @example Single-route mode with lifecycle hooks\n * ```typescript\n * app.use(createCopilotExpressHandler({\n *   runtime,\n *   basePath: \"/api/copilotkit\",\n *   mode: \"single-route\",\n *   hooks: {\n *     onRequest: ({ request }) => {\n *       if (!request.headers.get(\"authorization\")) {\n *         throw new Response(\"Unauthorized\", { status: 401 });\n *       }\n *     },\n *   },\n * }));\n * ```\n */\n/** @deprecated Use `createCopilotExpressHandler` instead. */\nexport { createCopilotExpressHandler as createCopilotEndpointExpress };\n\nexport function createCopilotExpressHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsOption = true,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotExpressEndpointParams): CopilotExpressRouter {\n  const normalizedBase = normalizeBasePath(basePath);\n\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath: normalizedBase,\n    mode,\n    cors: false, // CORS is handled at the Express middleware layer\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const nodeHandler = createExpressNodeHandler(handler);\n\n  const expressHandler = async (\n    req: ExpressRequest,\n    res: ExpressResponse,\n    next: NextFunction,\n  ) => {\n    try {\n      await nodeHandler(req, res);\n    } catch (err) {\n      next(err);\n    }\n  };\n\n  const router = express.Router();\n\n  // CORS middleware\n  if (corsOption) {\n    const corsConfig: CorsOptions =\n      corsOption === true\n        ? {\n            origin: \"*\",\n            methods: [\n              \"GET\",\n              \"HEAD\",\n              \"PUT\",\n              \"POST\",\n              \"DELETE\",\n              \"PATCH\",\n              \"OPTIONS\",\n            ],\n            allowedHeaders: [\"*\"],\n          }\n        : corsOption;\n    router.use(cors(corsConfig));\n  }\n\n  // Route mounting\n  if (mode === \"single-route\") {\n    router.post(normalizedBase, expressHandler);\n    router.options(normalizedBase, expressHandler);\n  } else if (normalizedBase === \"/\") {\n    router.all(/.*/, expressHandler);\n  } else {\n    router.all(\n      new RegExp(`^${escapeRegExp(normalizedBase)}(\\\\/.*)?$`),\n      expressHandler,\n    );\n  }\n\n  const exposedRouter: CopilotExpressRouter = router;\n  exposedRouter.channels = handler.channels;\n  return exposedRouter;\n}\n\nfunction escapeRegExp(s: string): string {\n  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\nfunction normalizeBasePath(path: string): string {\n  if (!path) {\n    throw new Error(\"basePath must be provided for Express endpoint\");\n  }\n\n  if (!path.startsWith(\"/\")) {\n    return `/${path}`;\n  }\n\n  if (path.length > 1 && path.endsWith(\"/\")) {\n    return path.slice(0, -1);\n  }\n\n  return path;\n}\n"],"mappings":";;;;;;;AAsHA,SAAgB,4BAA4B,EAC1C,SACA,UACA,OAAO,eACP,MAAM,aAAa,MACnB,OACA,kBACA,mBACqD;CACrD,MAAM,iBAAiB,kBAAkB,SAAS;CAElD,MAAM,UAAU,4BAA4B;EAC1C;EACA,UAAU;EACV;EACA,MAAM;EACN;EACA;EACA;EACD,CAAC;CAEF,MAAM,cAAc,yBAAyB,QAAQ;CAErD,MAAM,iBAAiB,OACrB,KACA,KACA,SACG;AACH,MAAI;AACF,SAAM,YAAY,KAAK,IAAI;WACpB,KAAK;AACZ,QAAK,IAAI;;;CAIb,MAAM,SAAS,QAAQ,QAAQ;AAG/B,KAAI,YAAY;EACd,MAAM,aACJ,eAAe,OACX;GACE,QAAQ;GACR,SAAS;IACP;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,gBAAgB,CAAC,IAAI;GACtB,GACD;AACN,SAAO,IAAI,KAAK,WAAW,CAAC;;AAI9B,KAAI,SAAS,gBAAgB;AAC3B,SAAO,KAAK,gBAAgB,eAAe;AAC3C,SAAO,QAAQ,gBAAgB,eAAe;YACrC,mBAAmB,IAC5B,QAAO,IAAI,MAAM,eAAe;KAEhC,QAAO,IACL,IAAI,OAAO,IAAI,aAAa,eAAe,CAAC,WAAW,EACvD,eACD;CAGH,MAAM,gBAAsC;AAC5C,eAAc,WAAW,QAAQ;AACjC,QAAO;;AAGT,SAAS,aAAa,GAAmB;AACvC,QAAO,EAAE,QAAQ,uBAAuB,OAAO;;AAGjD,SAAS,kBAAkB,MAAsB;AAC/C,KAAI,CAAC,KACH,OAAM,IAAI,MAAM,iDAAiD;AAGnE,KAAI,CAAC,KAAK,WAAW,IAAI,CACvB,QAAO,IAAI;AAGb,KAAI,KAAK,SAAS,KAAK,KAAK,SAAS,IAAI,CACvC,QAAO,KAAK,MAAM,GAAG,GAAG;AAG1B,QAAO"}
+{"version":3,"file":"express.mjs","names":[],"sources":["../../../../src/v2/runtime/endpoints/express.ts"],"sourcesContent":["import express from \"express\";\nimport type {\n  Request as ExpressRequest,\n  Response as ExpressResponse,\n  NextFunction,\n  Router,\n} from \"express\";\nimport cors from \"cors\";\nimport type { CorsOptions } from \"cors\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\nimport { createExpressNodeHandler } from \"./express-fetch-bridge\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\n\n/**\n * An Express {@link Router} that may also carry an optional\n * {@link ChannelsControl} surface. Express's Router is a request-scoped\n * middleware object, not a long-running process owner — Node\n * (`createCopilotNodeListener`) is the lifecycle-owning surface for\n * `.channels`. It is attached here too, best-effort, for callers that mount\n * the router directly and want to start (`ready()`), observe, or stop managed\n * Channel activation without also standing up a Node listener.\n */\nexport type CopilotExpressRouter = Router & { channels?: ChannelsControl };\n\nexport interface CopilotExpressEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * CORS configuration for the Express router.\n   * - `true` (default): permissive CORS (`origin: \"*\"`, all methods, all headers).\n   * - `false`: no CORS middleware is applied — handle it yourself.\n   * - object: passed directly to the Express `cors()` middleware.\n   */\n  cors?: boolean | CorsOptions;\n\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler builds the control surface for the runtime's\n   * declared managed Channels. Defaults to `true`. Building it opens no\n   * connection — activation is deferred to the first `channels.ready()`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n\n/**\n * Creates an Express router that serves the CopilotKit runtime.\n *\n * In **multi-route** mode (default) the router exposes:\n * - `GET  {basePath}/info` — runtime info\n * - `POST {basePath}/agent/:agentId/run` — start an agent run\n * - `POST {basePath}/agent/:agentId/connect` — connect to an agent run\n * - `POST {basePath}/agent/:agentId/stop/:threadId` — stop an agent run\n * - `POST {basePath}/transcribe` — transcribe audio\n *\n * In **single-route** mode a single `POST {basePath}` endpoint accepts a JSON\n * envelope `{ method, params, body }` and dispatches to the appropriate handler.\n *\n * @example\n * ```typescript\n * import express from \"express\";\n * import { CopilotRuntime } from \"@copilotkit/runtime/v2\";\n * import { createCopilotExpressHandler } from \"@copilotkit/runtime/v2/express\";\n *\n * const runtime = new CopilotRuntime({\n *   agents: { default: new BuiltInAgent({ model: \"openai/gpt-4o-mini\" }) },\n * });\n *\n * const app = express();\n * app.use(createCopilotExpressHandler({\n *   runtime,\n *   basePath: \"/api/copilotkit\",\n *   cors: true,\n * }));\n * app.listen(4000);\n * ```\n *\n * @example Single-route mode with lifecycle hooks\n * ```typescript\n * app.use(createCopilotExpressHandler({\n *   runtime,\n *   basePath: \"/api/copilotkit\",\n *   mode: \"single-route\",\n *   hooks: {\n *     onRequest: ({ request }) => {\n *       if (!request.headers.get(\"authorization\")) {\n *         throw new Response(\"Unauthorized\", { status: 401 });\n *       }\n *     },\n *   },\n * }));\n * ```\n */\n/** @deprecated Use `createCopilotExpressHandler` instead. */\nexport { createCopilotExpressHandler as createCopilotEndpointExpress };\n\nexport function createCopilotExpressHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsOption = true,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotExpressEndpointParams): CopilotExpressRouter {\n  const normalizedBase = normalizeBasePath(basePath);\n\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath: normalizedBase,\n    mode,\n    cors: false, // CORS is handled at the Express middleware layer\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const nodeHandler = createExpressNodeHandler(handler);\n\n  const expressHandler = async (\n    req: ExpressRequest,\n    res: ExpressResponse,\n    next: NextFunction,\n  ) => {\n    try {\n      await nodeHandler(req, res);\n    } catch (err) {\n      next(err);\n    }\n  };\n\n  const router = express.Router();\n\n  // CORS middleware\n  if (corsOption) {\n    const corsConfig: CorsOptions =\n      corsOption === true\n        ? {\n            origin: \"*\",\n            methods: [\n              \"GET\",\n              \"HEAD\",\n              \"PUT\",\n              \"POST\",\n              \"DELETE\",\n              \"PATCH\",\n              \"OPTIONS\",\n            ],\n            allowedHeaders: [\"*\"],\n          }\n        : corsOption;\n    router.use(cors(corsConfig));\n  }\n\n  // Route mounting\n  if (mode === \"single-route\") {\n    router.post(normalizedBase, expressHandler);\n    router.options(normalizedBase, expressHandler);\n  } else if (normalizedBase === \"/\") {\n    router.all(/.*/, expressHandler);\n  } else {\n    router.all(\n      new RegExp(`^${escapeRegExp(normalizedBase)}(\\\\/.*)?$`),\n      expressHandler,\n    );\n  }\n\n  const exposedRouter: CopilotExpressRouter = router;\n  exposedRouter.channels = handler.channels;\n  return exposedRouter;\n}\n\nfunction escapeRegExp(s: string): string {\n  return s.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\nfunction normalizeBasePath(path: string): string {\n  if (!path) {\n    throw new Error(\"basePath must be provided for Express endpoint\");\n  }\n\n  if (!path.startsWith(\"/\")) {\n    return `/${path}`;\n  }\n\n  if (path.length > 1 && path.endsWith(\"/\")) {\n    return path.slice(0, -1);\n  }\n\n  return path;\n}\n"],"mappings":";;;;;;;AAuHA,SAAgB,4BAA4B,EAC1C,SACA,UACA,OAAO,eACP,MAAM,aAAa,MACnB,OACA,kBACA,mBACqD;CACrD,MAAM,iBAAiB,kBAAkB,SAAS;CAElD,MAAM,UAAU,4BAA4B;EAC1C;EACA,UAAU;EACV;EACA,MAAM;EACN;EACA;EACA;EACD,CAAC;CAEF,MAAM,cAAc,yBAAyB,QAAQ;CAErD,MAAM,iBAAiB,OACrB,KACA,KACA,SACG;AACH,MAAI;AACF,SAAM,YAAY,KAAK,IAAI;WACpB,KAAK;AACZ,QAAK,IAAI;;;CAIb,MAAM,SAAS,QAAQ,QAAQ;AAG/B,KAAI,YAAY;EACd,MAAM,aACJ,eAAe,OACX;GACE,QAAQ;GACR,SAAS;IACP;IACA;IACA;IACA;IACA;IACA;IACA;IACD;GACD,gBAAgB,CAAC,IAAI;GACtB,GACD;AACN,SAAO,IAAI,KAAK,WAAW,CAAC;;AAI9B,KAAI,SAAS,gBAAgB;AAC3B,SAAO,KAAK,gBAAgB,eAAe;AAC3C,SAAO,QAAQ,gBAAgB,eAAe;YACrC,mBAAmB,IAC5B,QAAO,IAAI,MAAM,eAAe;KAEhC,QAAO,IACL,IAAI,OAAO,IAAI,aAAa,eAAe,CAAC,WAAW,EACvD,eACD;CAGH,MAAM,gBAAsC;AAC5C,eAAc,WAAW,QAAQ;AACjC,QAAO;;AAGT,SAAS,aAAa,GAAmB;AACvC,QAAO,EAAE,QAAQ,uBAAuB,OAAO;;AAGjD,SAAS,kBAAkB,MAAsB;AAC/C,KAAI,CAAC,KACH,OAAM,IAAI,MAAM,iDAAiD;AAGnE,KAAI,CAAC,KAAK,WAAW,IAAI,CACvB,QAAO,IAAI;AAGb,KAAI,KAAK,SAAS,KAAK,KAAK,SAAS,IAAI,CACvC,QAAO,KAAK,MAAM,GAAG,GAAG;AAG1B,QAAO"}

package/dist/v2/runtime/endpoints/hono.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hono.cjs","names":["createCopilotRuntimeHandler","Hono"],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotCorsConfig } from \"../core/fetch-cors\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\n\n/**\n * A Hono app that may also carry an optional {@link ChannelsControl} surface.\n * Hono's app object is request-scoped routing config, not a long-running\n * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning\n * surface for `.channels`. It is attached here too, best-effort, for callers\n * that mount the Hono app directly and want to observe/stop managed Channel\n * activation without also standing up a Node listener.\n */\nexport type CopilotHonoApp = Hono & { channels?: ChannelsControl };\n\n/**\n * CORS configuration for CopilotKit endpoints.\n * When using credentials (e.g., HTTP-only cookies), you must specify an explicit origin.\n */\nexport interface CopilotEndpointCorsConfig {\n  /**\n   * Allowed origin(s) for CORS. Can be:\n   * - A string: exact origin (e.g., \"https://myapp.com\")\n   * - An array: list of allowed origins\n   * - A function: dynamic origin resolution\n   *\n   * Note: When credentials is true, origin cannot be \"*\"\n   */\n  origin:\n    | string\n    | string[]\n    | ((origin: string, c: any) => string | undefined | null);\n  /**\n   * Whether to allow credentials (cookies, HTTP authentication).\n   * When true, origin must be explicitly specified (not \"*\").\n   */\n  credentials?: boolean;\n}\n\ninterface CopilotEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * Optional CORS configuration. When not provided, defaults to allowing all origins without credentials.\n   * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.\n   */\n  cors?: CopilotEndpointCorsConfig;\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler activates the runtime's declared managed\n   * Channels at creation time. Defaults to `true`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n/** @deprecated Use `createCopilotHonoHandler` instead. */\nexport const createCopilotEndpoint = createCopilotHonoHandler;\n\nexport function createCopilotHonoHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsConfig,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotEndpointParams): CopilotHonoApp {\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath,\n    mode,\n    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const app = new Hono();\n\n  const scopedApp: CopilotHonoApp = app\n    .basePath(basePath)\n    .all(\"*\", async (c) => handler(c.req.raw));\n  scopedApp.channels = handler.channels;\n  return scopedApp;\n}\n\n/**\n * Convert Hono-specific CORS config to the fetch handler's CopilotCorsConfig.\n */\nexport function toFetchCorsConfig(\n  config: CopilotEndpointCorsConfig,\n): CopilotCorsConfig {\n  const origin = config.origin;\n  return {\n    origin:\n      typeof origin === \"function\"\n        ? (reqOrigin: string) => origin(reqOrigin, undefined) ?? null\n        : origin,\n    credentials: config.credentials,\n  };\n}\n"],"mappings":";;;;;;;AA+EA,MAAa,wBAAwB;AAErC,SAAgB,yBAAyB,EACvC,SACA,UACA,OAAO,eACP,MAAM,YACN,OACA,kBACA,mBACwC;CACxC,MAAM,UAAUA,kDAA4B;EAC1C;EACA;EACA;EACA,MAAM,aAAa,kBAAkB,WAAW,GAAG;EACnD;EACA;EACA;EACD,CAAC;CAIF,MAAM,YAFM,IAAIC,WAAM,CAGnB,SAAS,SAAS,CAClB,IAAI,KAAK,OAAO,MAAM,QAAQ,EAAE,IAAI,IAAI,CAAC;AAC5C,WAAU,WAAW,QAAQ;AAC7B,QAAO;;;;;AAMT,SAAgB,kBACd,QACmB;CACnB,MAAM,SAAS,OAAO;AACtB,QAAO;EACL,QACE,OAAO,WAAW,cACb,cAAsB,OAAO,WAAW,OAAU,IAAI,OACvD;EACN,aAAa,OAAO;EACrB"}
+{"version":3,"file":"hono.cjs","names":["createCopilotRuntimeHandler","Hono"],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotCorsConfig } from \"../core/fetch-cors\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\n\n/**\n * A Hono app that may also carry an optional {@link ChannelsControl} surface.\n * Hono's app object is request-scoped routing config, not a long-running\n * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning\n * surface for `.channels`. It is attached here too, best-effort, for callers\n * that mount the Hono app directly and want to start (`ready()`), observe, or\n * stop managed Channel activation without also standing up a Node listener.\n */\nexport type CopilotHonoApp = Hono & { channels?: ChannelsControl };\n\n/**\n * CORS configuration for CopilotKit endpoints.\n * When using credentials (e.g., HTTP-only cookies), you must specify an explicit origin.\n */\nexport interface CopilotEndpointCorsConfig {\n  /**\n   * Allowed origin(s) for CORS. Can be:\n   * - A string: exact origin (e.g., \"https://myapp.com\")\n   * - An array: list of allowed origins\n   * - A function: dynamic origin resolution\n   *\n   * Note: When credentials is true, origin cannot be \"*\"\n   */\n  origin:\n    | string\n    | string[]\n    | ((origin: string, c: any) => string | undefined | null);\n  /**\n   * Whether to allow credentials (cookies, HTTP authentication).\n   * When true, origin must be explicitly specified (not \"*\").\n   */\n  credentials?: boolean;\n}\n\ninterface CopilotEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * Optional CORS configuration. When not provided, defaults to allowing all origins without credentials.\n   * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.\n   */\n  cors?: CopilotEndpointCorsConfig;\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler builds the control surface for the runtime's\n   * declared managed Channels. Defaults to `true`. Building it opens no\n   * connection — activation is deferred to the first `channels.ready()`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n/** @deprecated Use `createCopilotHonoHandler` instead. */\nexport const createCopilotEndpoint = createCopilotHonoHandler;\n\nexport function createCopilotHonoHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsConfig,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotEndpointParams): CopilotHonoApp {\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath,\n    mode,\n    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const app = new Hono();\n\n  const scopedApp: CopilotHonoApp = app\n    .basePath(basePath)\n    .all(\"*\", async (c) => handler(c.req.raw));\n  scopedApp.channels = handler.channels;\n  return scopedApp;\n}\n\n/**\n * Convert Hono-specific CORS config to the fetch handler's CopilotCorsConfig.\n */\nexport function toFetchCorsConfig(\n  config: CopilotEndpointCorsConfig,\n): CopilotCorsConfig {\n  const origin = config.origin;\n  return {\n    origin:\n      typeof origin === \"function\"\n        ? (reqOrigin: string) => origin(reqOrigin, undefined) ?? null\n        : origin,\n    credentials: config.credentials,\n  };\n}\n"],"mappings":";;;;;;;AAgFA,MAAa,wBAAwB;AAErC,SAAgB,yBAAyB,EACvC,SACA,UACA,OAAO,eACP,MAAM,YACN,OACA,kBACA,mBACwC;CACxC,MAAM,UAAUA,kDAA4B;EAC1C;EACA;EACA;EACA,MAAM,aAAa,kBAAkB,WAAW,GAAG;EACnD;EACA;EACA;EACD,CAAC;CAIF,MAAM,YAFM,IAAIC,WAAM,CAGnB,SAAS,SAAS,CAClB,IAAI,KAAK,OAAO,MAAM,QAAQ,EAAE,IAAI,IAAI,CAAC;AAC5C,WAAU,WAAW,QAAQ;AAC7B,QAAO;;;;;AAMT,SAAgB,kBACd,QACmB;CACnB,MAAM,SAAS,OAAO;AACtB,QAAO;EACL,QACE,OAAO,WAAW,cACb,cAAsB,OAAO,WAAW,OAAU,IAAI,OACvD;EACN,aAAa,OAAO;EACrB"}

package/dist/v2/runtime/endpoints/hono.d.cts

@@ -11,8 +11,8 @@ import { Hono } from "hono";
  * Hono's app object is request-scoped routing config, not a long-running
  * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning
  * surface for `.channels`. It is attached here too, best-effort, for callers
- * that mount the Hono app directly and want to observe/stop managed Channel
- * activation without also standing up a Node listener.
+ * that mount the Hono app directly and want to start (`ready()`), observe, or
+ * stop managed Channel activation without also standing up a Node listener.
  */
 type CopilotHonoApp = Hono & {
   channels?: ChannelsControl;
@@ -56,8 +56,9 @@ interface CopilotEndpointParams {
    */
   hooks?: CopilotRuntimeHooks;
   /**
-   * Whether the underlying handler activates the runtime's declared managed
-   * Channels at creation time. Defaults to `true`. See
+   * Whether the underlying handler builds the control surface for the runtime's
+   * declared managed Channels. Defaults to `true`. Building it opens no
+   * connection — activation is deferred to the first `channels.ready()`. See
    * `CopilotRuntimeHandlerOptions.activateChannels`.
    */
   activateChannels?: boolean;

package/dist/v2/runtime/endpoints/hono.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.cts","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"mappings":";;;;;;;;;;AAkBA;;;;;;KAAY,cAAA,GAAiB,IAAA;EAAS,QAAA,GAAW,eAAA;AAAA;AAMjD;;;;AAAA,UAAiB,yBAAA;EAYT;;;;;AAMP;;;EATC,MAAA,wBAGM,MAAA,UAAgB,CAAA;EAuBf;;;;EAlBP,WAAA;AAAA;AAAA,UAGQ,qBAAA;EACR,OAAA,EAAS,kBAAA;EACT,QAAA;EAaA;;;;;EANA,IAAA;EAuBkB;;;AAGpB;EApBE,IAAA,GAAO,yBAAA;;;;EAIP,KAAA,GAAQ,mBAAA;EAkB8B;;;;;EAXtC,gBAAA;EAgBA;;;;EAVA,eAAA,GAAkB,qBAAA;AAAA;;cAGP,qBAAA,SAAqB,wBAAA;AAAA,iBAElB,wBAAA,CAAA;EACd,OAAA;EACA,QAAA;EACA,IAAA;EACA,IAAA,EAAM,UAAA;EACN,KAAA;EACA,gBAAA;EACA;AAAA,GACC,qBAAA,GAAwB,cAAA;;;;iBAuBX,iBAAA,CACd,MAAA,EAAQ,yBAAA,GACP,iBAAA"}
+{"version":3,"file":"hono.d.cts","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"mappings":";;;;;;;;;;AAkBA;;;;;;KAAY,cAAA,GAAiB,IAAA;EAAS,QAAA,GAAW,eAAA;AAAA;AAMjD;;;;AAAA,UAAiB,yBAAA;EAYT;;;;;AAMP;;;EATC,MAAA,wBAGM,MAAA,UAAgB,CAAA;EAuBf;;;;EAlBP,WAAA;AAAA;AAAA,UAGQ,qBAAA;EACR,OAAA,EAAS,kBAAA;EACT,QAAA;EAaA;;;;;EANA,IAAA;EAwBkB;;;AAGpB;EArBE,IAAA,GAAO,yBAAA;;;;EAIP,KAAA,GAAQ,mBAAA;EAmB8B;;;;;;EAXtC,gBAAA;EAiBA;;;;EAXA,eAAA,GAAkB,qBAAA;AAAA;;cAGP,qBAAA,SAAqB,wBAAA;AAAA,iBAElB,wBAAA,CAAA;EACd,OAAA;EACA,QAAA;EACA,IAAA;EACA,IAAA,EAAM,UAAA;EACN,KAAA;EACA,gBAAA;EACA;AAAA,GACC,qBAAA,GAAwB,cAAA;;;;iBAuBX,iBAAA,CACd,MAAA,EAAQ,yBAAA,GACP,iBAAA"}

package/dist/v2/runtime/endpoints/hono.d.mts

@@ -11,8 +11,8 @@ import { Hono } from "hono";
  * Hono's app object is request-scoped routing config, not a long-running
  * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning
  * surface for `.channels`. It is attached here too, best-effort, for callers
- * that mount the Hono app directly and want to observe/stop managed Channel
- * activation without also standing up a Node listener.
+ * that mount the Hono app directly and want to start (`ready()`), observe, or
+ * stop managed Channel activation without also standing up a Node listener.
  */
 type CopilotHonoApp = Hono & {
   channels?: ChannelsControl;
@@ -56,8 +56,9 @@ interface CopilotEndpointParams {
    */
   hooks?: CopilotRuntimeHooks;
   /**
-   * Whether the underlying handler activates the runtime's declared managed
-   * Channels at creation time. Defaults to `true`. See
+   * Whether the underlying handler builds the control surface for the runtime's
+   * declared managed Channels. Defaults to `true`. Building it opens no
+   * connection — activation is deferred to the first `channels.ready()`. See
    * `CopilotRuntimeHandlerOptions.activateChannels`.
    */
   activateChannels?: boolean;

package/dist/v2/runtime/endpoints/hono.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"hono.d.mts","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"mappings":";;;;;;;;;;AAkBA;;;;;;KAAY,cAAA,GAAiB,IAAA;EAAS,QAAA,GAAW,eAAA;AAAA;AAMjD;;;;AAAA,UAAiB,yBAAA;EAYT;;;;;AAMP;;;EATC,MAAA,wBAGM,MAAA,UAAgB,CAAA;EAuBf;;;;EAlBP,WAAA;AAAA;AAAA,UAGQ,qBAAA;EACR,OAAA,EAAS,kBAAA;EACT,QAAA;EAaA;;;;;EANA,IAAA;EAuBkB;;;AAGpB;EApBE,IAAA,GAAO,yBAAA;;;;EAIP,KAAA,GAAQ,mBAAA;EAkB8B;;;;;EAXtC,gBAAA;EAgBA;;;;EAVA,eAAA,GAAkB,qBAAA;AAAA;;cAGP,qBAAA,SAAqB,wBAAA;AAAA,iBAElB,wBAAA,CAAA;EACd,OAAA;EACA,QAAA;EACA,IAAA;EACA,IAAA,EAAM,UAAA;EACN,KAAA;EACA,gBAAA;EACA;AAAA,GACC,qBAAA,GAAwB,cAAA;;;;iBAuBX,iBAAA,CACd,MAAA,EAAQ,yBAAA,GACP,iBAAA"}
+{"version":3,"file":"hono.d.mts","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"mappings":";;;;;;;;;;AAkBA;;;;;;KAAY,cAAA,GAAiB,IAAA;EAAS,QAAA,GAAW,eAAA;AAAA;AAMjD;;;;AAAA,UAAiB,yBAAA;EAYT;;;;;AAMP;;;EATC,MAAA,wBAGM,MAAA,UAAgB,CAAA;EAuBf;;;;EAlBP,WAAA;AAAA;AAAA,UAGQ,qBAAA;EACR,OAAA,EAAS,kBAAA;EACT,QAAA;EAaA;;;;;EANA,IAAA;EAwBkB;;;AAGpB;EArBE,IAAA,GAAO,yBAAA;;;;EAIP,KAAA,GAAQ,mBAAA;EAmB8B;;;;;;EAXtC,gBAAA;EAiBA;;;;EAXA,eAAA,GAAkB,qBAAA;AAAA;;cAGP,qBAAA,SAAqB,wBAAA;AAAA,iBAElB,wBAAA,CAAA;EACd,OAAA;EACA,QAAA;EACA,IAAA;EACA,IAAA,EAAM,UAAA;EACN,KAAA;EACA,gBAAA;EACA;AAAA,GACC,qBAAA,GAAwB,cAAA;;;;iBAuBX,iBAAA,CACd,MAAA,EAAQ,yBAAA,GACP,iBAAA"}

package/dist/v2/runtime/endpoints/hono.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"hono.mjs","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotCorsConfig } from \"../core/fetch-cors\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\n\n/**\n * A Hono app that may also carry an optional {@link ChannelsControl} surface.\n * Hono's app object is request-scoped routing config, not a long-running\n * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning\n * surface for `.channels`. It is attached here too, best-effort, for callers\n * that mount the Hono app directly and want to observe/stop managed Channel\n * activation without also standing up a Node listener.\n */\nexport type CopilotHonoApp = Hono & { channels?: ChannelsControl };\n\n/**\n * CORS configuration for CopilotKit endpoints.\n * When using credentials (e.g., HTTP-only cookies), you must specify an explicit origin.\n */\nexport interface CopilotEndpointCorsConfig {\n  /**\n   * Allowed origin(s) for CORS. Can be:\n   * - A string: exact origin (e.g., \"https://myapp.com\")\n   * - An array: list of allowed origins\n   * - A function: dynamic origin resolution\n   *\n   * Note: When credentials is true, origin cannot be \"*\"\n   */\n  origin:\n    | string\n    | string[]\n    | ((origin: string, c: any) => string | undefined | null);\n  /**\n   * Whether to allow credentials (cookies, HTTP authentication).\n   * When true, origin must be explicitly specified (not \"*\").\n   */\n  credentials?: boolean;\n}\n\ninterface CopilotEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * Optional CORS configuration. When not provided, defaults to allowing all origins without credentials.\n   * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.\n   */\n  cors?: CopilotEndpointCorsConfig;\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler activates the runtime's declared managed\n   * Channels at creation time. Defaults to `true`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n/** @deprecated Use `createCopilotHonoHandler` instead. */\nexport const createCopilotEndpoint = createCopilotHonoHandler;\n\nexport function createCopilotHonoHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsConfig,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotEndpointParams): CopilotHonoApp {\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath,\n    mode,\n    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const app = new Hono();\n\n  const scopedApp: CopilotHonoApp = app\n    .basePath(basePath)\n    .all(\"*\", async (c) => handler(c.req.raw));\n  scopedApp.channels = handler.channels;\n  return scopedApp;\n}\n\n/**\n * Convert Hono-specific CORS config to the fetch handler's CopilotCorsConfig.\n */\nexport function toFetchCorsConfig(\n  config: CopilotEndpointCorsConfig,\n): CopilotCorsConfig {\n  const origin = config.origin;\n  return {\n    origin:\n      typeof origin === \"function\"\n        ? (reqOrigin: string) => origin(reqOrigin, undefined) ?? null\n        : origin,\n    credentials: config.credentials,\n  };\n}\n"],"mappings":";;;;;;AA+EA,MAAa,wBAAwB;AAErC,SAAgB,yBAAyB,EACvC,SACA,UACA,OAAO,eACP,MAAM,YACN,OACA,kBACA,mBACwC;CACxC,MAAM,UAAU,4BAA4B;EAC1C;EACA;EACA;EACA,MAAM,aAAa,kBAAkB,WAAW,GAAG;EACnD;EACA;EACA;EACD,CAAC;CAIF,MAAM,YAFM,IAAI,MAAM,CAGnB,SAAS,SAAS,CAClB,IAAI,KAAK,OAAO,MAAM,QAAQ,EAAE,IAAI,IAAI,CAAC;AAC5C,WAAU,WAAW,QAAQ;AAC7B,QAAO;;;;;AAMT,SAAgB,kBACd,QACmB;CACnB,MAAM,SAAS,OAAO;AACtB,QAAO;EACL,QACE,OAAO,WAAW,cACb,cAAsB,OAAO,WAAW,OAAU,IAAI,OACvD;EACN,aAAa,OAAO;EACrB"}
+{"version":3,"file":"hono.mjs","names":[],"sources":["../../../../src/v2/runtime/endpoints/hono.ts"],"sourcesContent":["import { Hono } from \"hono\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotCorsConfig } from \"../core/fetch-cors\";\nimport type { CopilotRuntimeHooks } from \"../core/hooks\";\nimport type {\n  ActivateChannelEngine,\n  ChannelsControl,\n} from \"../core/channel-manager\";\n\n/**\n * A Hono app that may also carry an optional {@link ChannelsControl} surface.\n * Hono's app object is request-scoped routing config, not a long-running\n * process owner — Node (`createCopilotNodeListener`) is the lifecycle-owning\n * surface for `.channels`. It is attached here too, best-effort, for callers\n * that mount the Hono app directly and want to start (`ready()`), observe, or\n * stop managed Channel activation without also standing up a Node listener.\n */\nexport type CopilotHonoApp = Hono & { channels?: ChannelsControl };\n\n/**\n * CORS configuration for CopilotKit endpoints.\n * When using credentials (e.g., HTTP-only cookies), you must specify an explicit origin.\n */\nexport interface CopilotEndpointCorsConfig {\n  /**\n   * Allowed origin(s) for CORS. Can be:\n   * - A string: exact origin (e.g., \"https://myapp.com\")\n   * - An array: list of allowed origins\n   * - A function: dynamic origin resolution\n   *\n   * Note: When credentials is true, origin cannot be \"*\"\n   */\n  origin:\n    | string\n    | string[]\n    | ((origin: string, c: any) => string | undefined | null);\n  /**\n   * Whether to allow credentials (cookies, HTTP authentication).\n   * When true, origin must be explicitly specified (not \"*\").\n   */\n  credentials?: boolean;\n}\n\ninterface CopilotEndpointParams {\n  runtime: CopilotRuntimeLike;\n  basePath: string;\n\n  /**\n   * Endpoint mode.\n   * - `\"multi-route\"` (default): separate routes for each operation\n   * - `\"single-route\"`: single POST endpoint with JSON envelope dispatch\n   */\n  mode?: \"multi-route\" | \"single-route\";\n\n  /**\n   * Optional CORS configuration. When not provided, defaults to allowing all origins without credentials.\n   * To support HTTP-only cookies, provide cors config with credentials: true and explicit origin.\n   */\n  cors?: CopilotEndpointCorsConfig;\n  /**\n   * Lifecycle hooks for request processing.\n   */\n  hooks?: CopilotRuntimeHooks;\n\n  /**\n   * Whether the underlying handler builds the control surface for the runtime's\n   * declared managed Channels. Defaults to `true`. Building it opens no\n   * connection — activation is deferred to the first `channels.ready()`. See\n   * `CopilotRuntimeHandlerOptions.activateChannels`.\n   */\n  activateChannels?: boolean;\n\n  /**\n   * @internal Test seam: inject a fake Channel activation engine. Forwarded\n   * to `createCopilotRuntimeHandler`. Not part of the public API.\n   */\n  __channelEngine?: ActivateChannelEngine;\n}\n/** @deprecated Use `createCopilotHonoHandler` instead. */\nexport const createCopilotEndpoint = createCopilotHonoHandler;\n\nexport function createCopilotHonoHandler({\n  runtime,\n  basePath,\n  mode = \"multi-route\",\n  cors: corsConfig,\n  hooks,\n  activateChannels,\n  __channelEngine,\n}: CopilotEndpointParams): CopilotHonoApp {\n  const handler = createCopilotRuntimeHandler({\n    runtime,\n    basePath,\n    mode,\n    cors: corsConfig ? toFetchCorsConfig(corsConfig) : true,\n    hooks,\n    activateChannels,\n    __channelEngine,\n  });\n\n  const app = new Hono();\n\n  const scopedApp: CopilotHonoApp = app\n    .basePath(basePath)\n    .all(\"*\", async (c) => handler(c.req.raw));\n  scopedApp.channels = handler.channels;\n  return scopedApp;\n}\n\n/**\n * Convert Hono-specific CORS config to the fetch handler's CopilotCorsConfig.\n */\nexport function toFetchCorsConfig(\n  config: CopilotEndpointCorsConfig,\n): CopilotCorsConfig {\n  const origin = config.origin;\n  return {\n    origin:\n      typeof origin === \"function\"\n        ? (reqOrigin: string) => origin(reqOrigin, undefined) ?? null\n        : origin,\n    credentials: config.credentials,\n  };\n}\n"],"mappings":";;;;;;AAgFA,MAAa,wBAAwB;AAErC,SAAgB,yBAAyB,EACvC,SACA,UACA,OAAO,eACP,MAAM,YACN,OACA,kBACA,mBACwC;CACxC,MAAM,UAAU,4BAA4B;EAC1C;EACA;EACA;EACA,MAAM,aAAa,kBAAkB,WAAW,GAAG;EACnD;EACA;EACA;EACD,CAAC;CAIF,MAAM,YAFM,IAAI,MAAM,CAGnB,SAAS,SAAS,CAClB,IAAI,KAAK,OAAO,MAAM,QAAQ,EAAE,IAAI,IAAI,CAAC;AAC5C,WAAU,WAAW,QAAQ;AAC7B,QAAO;;;;;AAMT,SAAgB,kBACd,QACmB;CACnB,MAAM,SAAS,OAAO;AACtB,QAAO;EACL,QACE,OAAO,WAAW,cACb,cAAsB,OAAO,WAAW,OAAU,IAAI,OACvD;EACN,aAAa,OAAO;EACrB"}

package/dist/v2/runtime/endpoints/node.cjs

@@ -3,32 +3,6 @@ const require_fetch_handler = require('../core/fetch-handler.cjs');
 const require_node_fetch_handler = require('./node-fetch-handler.cjs');
 
 //#region src/v2/runtime/endpoints/node.ts
-/**
-* Convenience wrapper for creating a Node.js HTTP request listener
-* from CopilotKit runtime handler options.
-*
-* When the runtime declares managed Channels (and activation was not opted
-* out of via `activateChannels: false`), the returned listener exposes
-* `.channels` — the same {@link ChannelsControl} surface the underlying
-* fetch handler activates at creation time.
-*
-* @example
-* ```typescript
-* import { createServer } from "node:http";
-* import { CopilotRuntime } from "@copilotkit/runtime/v2";
-* import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
-*
-* const listener = createCopilotNodeListener({
-*   runtime: new CopilotRuntime({ agents: { ... } }),
-*   basePath: "/api/copilotkit",
-*   cors: true,
-* });
-* createServer(listener).listen(3000);
-*
-* // Optional: observe/stop managed Channel activation.
-* await listener.channels?.ready();
-* ```
-*/
 function createCopilotNodeListener(options) {
 	const handler = require_fetch_handler.createCopilotRuntimeHandler(options);
 	const listener = require_node_fetch_handler.createCopilotNodeHandler(handler);

package/dist/v2/runtime/endpoints/node.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"node.cjs","names":["createCopilotRuntimeHandler","createCopilotNodeHandler"],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"sourcesContent":["import { createCopilotRuntimeHandler } from \"../core/fetch-handler\";\nimport type { CopilotRuntimeHandlerOptions } from \"../core/fetch-handler\";\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 observe or stop managed\n * Channel activation.\n */\nexport type NodeCopilotListener = NodeFetchHandler & {\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 the underlying\n * fetch handler activates at creation time.\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 * // Optional: observe/stop managed Channel activation.\n * await listener.channels?.ready();\n * ```\n */\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,0BACd,SACqB;CACrB,MAAM,UAAUA,kDAA4B,QAAQ;CACpD,MAAM,WAAgCC,oDAAyB,QAAQ;AACvE,UAAS,WAAW,QAAQ;AAC5B,QAAO"}
+{"version":3,"file":"node.cjs","names":["createCopilotRuntimeHandler","createCopilotNodeHandler"],"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,UAAUA,kDAA4B,QAAQ;CACpD,MAAM,WAAgCC,oDAAyB,QAAQ;AACvE,UAAS,WAAW,QAAQ;AAC5B,QAAO"}

package/dist/v2/runtime/endpoints/node.d.cts

@@ -1,4 +1,5 @@
 require("reflect-metadata");
+import { RuntimeWithDeclaredChannels } from "../core/runtime.cjs";
 import { ChannelsControl } from "../core/channel-manager.cjs";
 import { CopilotRuntimeHandlerOptions } from "../core/fetch-handler.cjs";
 import { NodeFetchHandler } from "./node-fetch-handler.cjs";
@@ -9,20 +10,43 @@ import { NodeFetchHandler } from "./node-fetch-handler.cjs";
  * optional {@link ChannelsControl} surface, mirroring
  * `CopilotRuntimeFetchHandler.channels`. Node is the long-running,
  * lifecycle-owning entry point for the runtime, so it is the surface that
- * exposes `.channels` for callers that need to observe or stop managed
+ * exposes `.channels` for callers that need to start, observe, or stop managed
  * Channel activation.
  */
 type NodeCopilotListener = NodeFetchHandler & {
   channels?: ChannelsControl;
 };
+/**
+ * A {@link NodeCopilotListener} 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 `listener.channels.ready(...)` call type-checks without a `!` or a
+ * `?.` under strict TypeScript — the Node mirror of
+ * `CopilotRuntimeFetchHandlerWithChannels`.
+ */
+type NodeCopilotListenerWithChannels = NodeFetchHandler & {
+  /** Lifecycle control surface for the runtime's declared managed Channels. */channels: ChannelsControl;
+};
 /**
  * Convenience wrapper for creating a Node.js HTTP request listener
  * from CopilotKit runtime handler options.
  *
  * When the runtime declares managed Channels (and activation was not opted
  * out of via `activateChannels: false`), the returned listener exposes
- * `.channels` — the same {@link ChannelsControl} surface the underlying
- * fetch handler activates at creation time.
+ * `.channels` — the same {@link ChannelsControl} surface carried by the
+ * underlying fetch handler.
+ *
+ * ## Managed Channels lifecycle
+ *
+ * Creating the listener opens NO connection. Activation — which opens the
+ * persistent Realtime Gateway WebSocket and starts every direct adapter on the
+ * declared Channels — is LAZY: it is triggered by the first
+ * `await listener.channels.ready()` and never before, neither at creation nor on
+ * the first HTTP request. On a long-running host that call is REQUIRED, not
+ * optional: without it the process serves HTTP but no Channel is ever connected.
+ * `listener.channels.stop()` tears activation down. See the
+ * `createCopilotRuntimeHandler` TSDoc for why activation is deferred
+ * (serverless/edge safety).
  *
  * @example
  * ```typescript
@@ -37,11 +61,35 @@ type NodeCopilotListener = NodeFetchHandler & {
  * });
  * createServer(listener).listen(3000);
  *
- * // Optional: observe/stop managed Channel activation.
- * await listener.channels?.ready();
+ * // Required to connect declared managed Channels. Bound it so one wedged
+ * // adapter cannot hang startup forever.
+ * await listener.channels.ready({ timeoutMs: 30_000 });
  * ```
  */
+/**
+ * Overload: a runtime constructed with at least one declared Intelligence
+ * Channel (a {@link RuntimeWithDeclaredChannels}-branded runtime), when
+ * activation is not disabled, yields a listener with a **non-optional**
+ * {@link ChannelsControl}. `activateChannels` is constrained to
+ * `true | undefined` here so passing `activateChannels: false` (which leaves no
+ * `.channels`) falls through to the optional-shape overload below rather than
+ * dishonestly promising a control surface that will not exist. Mirrors the
+ * `createCopilotRuntimeHandler` overload pair so the brand survives the wrapper.
+ *
+ * The brand comes from constructing the runtime with a literal non-empty
+ * `channels` list (`readonly [Channel, ...Channel[]]`). A runtime built from a
+ * dynamically-assembled `Channel[]` is not branded, so it falls to the
+ * optional-shape overload and its call sites still need `?.`.
+ */
+declare function createCopilotNodeListener(options: CopilotRuntimeHandlerOptions & {
+  runtime: RuntimeWithDeclaredChannels;
+  activateChannels?: true | undefined;
+}): NodeCopilotListenerWithChannels;
+/**
+ * Overload: every other runtime (SSE, Intelligence without channels, or with
+ * activation disabled) yields a listener whose `.channels` is optional.
+ */
 declare function createCopilotNodeListener(options: CopilotRuntimeHandlerOptions): NodeCopilotListener;
 //#endregion
-export { createCopilotNodeListener };
+export { NodeCopilotListener, NodeCopilotListenerWithChannels, createCopilotNodeListener };
 //# sourceMappingURL=node.d.cts.map

package/dist/v2/runtime/endpoints/node.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.cts","names":[],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"mappings":";;;;;;;;AAcA;;;;;;KAAY,mBAAA,GAAsB,gBAAA;EAChC,QAAA,GAAW,eAAA;AAAA;AA6Bb;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,yBAAA,CACd,OAAA,EAAS,4BAAA,GACR,mBAAA"}
+{"version":3,"file":"node.d.cts","names":[],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"mappings":";;;;;;;;;AAeA;;;;;;KAAY,mBAAA,GAAsB,gBAAA;EAChC,QAAA,GAAW,eAAA;AAAA;AAWb;;;;;;;;AAAA,KAAY,+BAAA,GAAkC,gBAAA;EA2D9B,6EAzDd,QAAA,EAAU,eAAA;AAAA;;;;;;;;;;;;;;AAmEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAVgB,yBAAA,CACd,OAAA,EAAS,4BAAA;EACP,OAAA,EAAS,2BAAA;EACT,gBAAA;AAAA,IAED,+BAAA;;;;;iBAKa,yBAAA,CACd,OAAA,EAAS,4BAAA,GACR,mBAAA"}

package/dist/v2/runtime/endpoints/node.d.mts

@@ -1,4 +1,5 @@
 import "reflect-metadata";
+import { RuntimeWithDeclaredChannels } from "../core/runtime.mjs";
 import { ChannelsControl } from "../core/channel-manager.mjs";
 import { CopilotRuntimeHandlerOptions } from "../core/fetch-handler.mjs";
 import { NodeFetchHandler } from "./node-fetch-handler.mjs";
@@ -9,20 +10,43 @@ import { NodeFetchHandler } from "./node-fetch-handler.mjs";
  * optional {@link ChannelsControl} surface, mirroring
  * `CopilotRuntimeFetchHandler.channels`. Node is the long-running,
  * lifecycle-owning entry point for the runtime, so it is the surface that
- * exposes `.channels` for callers that need to observe or stop managed
+ * exposes `.channels` for callers that need to start, observe, or stop managed
  * Channel activation.
  */
 type NodeCopilotListener = NodeFetchHandler & {
   channels?: ChannelsControl;
 };
+/**
+ * A {@link NodeCopilotListener} 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 `listener.channels.ready(...)` call type-checks without a `!` or a
+ * `?.` under strict TypeScript — the Node mirror of
+ * `CopilotRuntimeFetchHandlerWithChannels`.
+ */
+type NodeCopilotListenerWithChannels = NodeFetchHandler & {
+  /** Lifecycle control surface for the runtime's declared managed Channels. */channels: ChannelsControl;
+};
 /**
  * Convenience wrapper for creating a Node.js HTTP request listener
  * from CopilotKit runtime handler options.
  *
  * When the runtime declares managed Channels (and activation was not opted
  * out of via `activateChannels: false`), the returned listener exposes
- * `.channels` — the same {@link ChannelsControl} surface the underlying
- * fetch handler activates at creation time.
+ * `.channels` — the same {@link ChannelsControl} surface carried by the
+ * underlying fetch handler.
+ *
+ * ## Managed Channels lifecycle
+ *
+ * Creating the listener opens NO connection. Activation — which opens the
+ * persistent Realtime Gateway WebSocket and starts every direct adapter on the
+ * declared Channels — is LAZY: it is triggered by the first
+ * `await listener.channels.ready()` and never before, neither at creation nor on
+ * the first HTTP request. On a long-running host that call is REQUIRED, not
+ * optional: without it the process serves HTTP but no Channel is ever connected.
+ * `listener.channels.stop()` tears activation down. See the
+ * `createCopilotRuntimeHandler` TSDoc for why activation is deferred
+ * (serverless/edge safety).
  *
  * @example
  * ```typescript
@@ -37,11 +61,35 @@ type NodeCopilotListener = NodeFetchHandler & {
  * });
  * createServer(listener).listen(3000);
  *
- * // Optional: observe/stop managed Channel activation.
- * await listener.channels?.ready();
+ * // Required to connect declared managed Channels. Bound it so one wedged
+ * // adapter cannot hang startup forever.
+ * await listener.channels.ready({ timeoutMs: 30_000 });
  * ```
  */
+/**
+ * Overload: a runtime constructed with at least one declared Intelligence
+ * Channel (a {@link RuntimeWithDeclaredChannels}-branded runtime), when
+ * activation is not disabled, yields a listener with a **non-optional**
+ * {@link ChannelsControl}. `activateChannels` is constrained to
+ * `true | undefined` here so passing `activateChannels: false` (which leaves no
+ * `.channels`) falls through to the optional-shape overload below rather than
+ * dishonestly promising a control surface that will not exist. Mirrors the
+ * `createCopilotRuntimeHandler` overload pair so the brand survives the wrapper.
+ *
+ * The brand comes from constructing the runtime with a literal non-empty
+ * `channels` list (`readonly [Channel, ...Channel[]]`). A runtime built from a
+ * dynamically-assembled `Channel[]` is not branded, so it falls to the
+ * optional-shape overload and its call sites still need `?.`.
+ */
+declare function createCopilotNodeListener(options: CopilotRuntimeHandlerOptions & {
+  runtime: RuntimeWithDeclaredChannels;
+  activateChannels?: true | undefined;
+}): NodeCopilotListenerWithChannels;
+/**
+ * Overload: every other runtime (SSE, Intelligence without channels, or with
+ * activation disabled) yields a listener whose `.channels` is optional.
+ */
 declare function createCopilotNodeListener(options: CopilotRuntimeHandlerOptions): NodeCopilotListener;
 //#endregion
-export { createCopilotNodeListener };
+export { NodeCopilotListener, NodeCopilotListenerWithChannels, createCopilotNodeListener };
 //# sourceMappingURL=node.d.mts.map

package/dist/v2/runtime/endpoints/node.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"node.d.mts","names":[],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"mappings":";;;;;;;;AAcA;;;;;;KAAY,mBAAA,GAAsB,gBAAA;EAChC,QAAA,GAAW,eAAA;AAAA;AA6Bb;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,yBAAA,CACd,OAAA,EAAS,4BAAA,GACR,mBAAA"}
+{"version":3,"file":"node.d.mts","names":[],"sources":["../../../../src/v2/runtime/endpoints/node.ts"],"mappings":";;;;;;;;;AAeA;;;;;;KAAY,mBAAA,GAAsB,gBAAA;EAChC,QAAA,GAAW,eAAA;AAAA;AAWb;;;;;;;;AAAA,KAAY,+BAAA,GAAkC,gBAAA;EA2D9B,6EAzDd,QAAA,EAAU,eAAA;AAAA;;;;;;;;;;;;;;AAmEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAVgB,yBAAA,CACd,OAAA,EAAS,4BAAA;EACP,OAAA,EAAS,2BAAA;EACT,gBAAA;AAAA,IAED,+BAAA;;;;;iBAKa,yBAAA,CACd,OAAA,EAAS,4BAAA,GACR,mBAAA"}

package/dist/v2/runtime/endpoints/node.mjs

@@ -3,32 +3,6 @@ import { createCopilotRuntimeHandler } from "../core/fetch-handler.mjs";
 import { createCopilotNodeHandler } from "./node-fetch-handler.mjs";
 
 //#region src/v2/runtime/endpoints/node.ts
-/**
-* Convenience wrapper for creating a Node.js HTTP request listener
-* from CopilotKit runtime handler options.
-*
-* When the runtime declares managed Channels (and activation was not opted
-* out of via `activateChannels: false`), the returned listener exposes
-* `.channels` — the same {@link ChannelsControl} surface the underlying
-* fetch handler activates at creation time.
-*
-* @example
-* ```typescript
-* import { createServer } from "node:http";
-* import { CopilotRuntime } from "@copilotkit/runtime/v2";
-* import { createCopilotNodeListener } from "@copilotkit/runtime/v2/node";
-*
-* const listener = createCopilotNodeListener({
-*   runtime: new CopilotRuntime({ agents: { ... } }),
-*   basePath: "/api/copilotkit",
-*   cors: true,
-* });
-* createServer(listener).listen(3000);
-*
-* // Optional: observe/stop managed Channel activation.
-* await listener.channels?.ready();
-* ```
-*/
 function createCopilotNodeListener(options) {
 	const handler = createCopilotRuntimeHandler(options);
 	const listener = createCopilotNodeHandler(handler);

package/dist/v2/runtime/endpoints/node.mjs.map

@@ -1 +1 @@
-{"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 { 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 observe or stop managed\n * Channel activation.\n */\nexport type NodeCopilotListener = NodeFetchHandler & {\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 the underlying\n * fetch handler activates at creation time.\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 * // Optional: observe/stop managed Channel activation.\n * await listener.channels?.ready();\n * ```\n */\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4CA,SAAgB,0BACd,SACqB;CACrB,MAAM,UAAU,4BAA4B,QAAQ;CACpD,MAAM,WAAgC,yBAAyB,QAAQ;AACvE,UAAS,WAAW,QAAQ;AAC5B,QAAO"}
+{"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"}

package/dist/v2/runtime/intelligence-platform/client.cjs

@@ -16,6 +16,19 @@ let crypto = require("crypto");
 */
 const INTELLIGENCE_USER_ID_HEADER = "x-cpki-user-id";
 /**
+* REST base URL of CopilotKit's managed Intelligence platform — the default
+* when {@link CopilotKitIntelligenceConfig.apiUrl} is omitted.
+*/
+const MANAGED_INTELLIGENCE_API_URL = "https://api.intelligence.copilotkit.ai";
+/**
+* Websocket base URL of CopilotKit's managed Intelligence platform — the
+* default when {@link CopilotKitIntelligenceConfig.wsUrl} is omitted.
+*
+* A different host from {@link MANAGED_INTELLIGENCE_API_URL}: the API and
+* realtime planes are deployed separately.
+*/
+const MANAGED_INTELLIGENCE_WS_URL = "wss://realtime.intelligence.copilotkit.ai";
+/**
 * Error thrown when an Intelligence platform HTTP request returns a non-2xx
 * status. Carries the HTTP {@link status} code so callers can branch on
 * specific failures (e.g. 404 for "not found", 409 for "conflict") without
@@ -39,6 +52,36 @@ var PlatformRequestError = class extends Error {
 		this.name = "PlatformRequestError";
 	}
 };
+/**
+* Client for the CopilotKit Intelligence Platform REST API.
+*
+* Construct the client once and pass it to any consumers that need it
+* (e.g. `CopilotRuntime`, `IntelligenceAgentRunner`):
+*
+* ```ts
+* import { CopilotKitIntelligence, CopilotRuntime } from "@copilotkit/runtime";
+*
+* const intelligence = new CopilotKitIntelligence({
+*   apiKey: process.env.COPILOTKIT_API_KEY!,
+* });
+*
+* const runtime = new CopilotRuntime({
+*   agents,
+*   intelligence,
+* });
+* ```
+*
+* `apiUrl` and `wsUrl` default to CopilotKit's managed Intelligence platform.
+* Override both together to target a self-hosted or non-production deployment:
+*
+* ```ts
+* const intelligence = new CopilotKitIntelligence({
+*   apiUrl: "https://intelligence.internal",
+*   wsUrl: "wss://realtime.intelligence.internal",
+*   apiKey: process.env.COPILOTKIT_API_KEY!,
+* });
+* ```
+*/
 var CopilotKitIntelligence = class {
 	#apiUrl;
 	#runnerWsUrl;
@@ -49,8 +92,11 @@ var CopilotKitIntelligence = class {
 	#threadUpdatedListeners = /* @__PURE__ */ new Set();
 	#threadDeletedListeners = /* @__PURE__ */ new Set();
 	constructor(config) {
-		const intelligenceWsUrl = normalizeIntelligenceWsUrl(config.wsUrl);
-		this.#apiUrl = config.apiUrl.replace(/\/$/, "");
+		const configuredApiUrl = configuredUrl(config.apiUrl);
+		const configuredWsUrl = configuredUrl(config.wsUrl);
+		warnOnPartialHostOverride(configuredApiUrl, configuredWsUrl);
+		const intelligenceWsUrl = normalizeIntelligenceWsUrl(configuredWsUrl ?? MANAGED_INTELLIGENCE_WS_URL);
+		this.#apiUrl = (configuredApiUrl ?? MANAGED_INTELLIGENCE_API_URL).replace(/\/$/, "");
 		this.#runnerWsUrl = deriveRunnerWsUrl(intelligenceWsUrl);
 		this.#clientWsUrl = deriveClientWsUrl(intelligenceWsUrl);
 		this.#apiKey = config.apiKey;
@@ -492,6 +538,31 @@ var CopilotKitIntelligence = class {
 		}) ?? null;
 	}
 };
+/**
+* Normalize a configured URL to "provided" or "not provided". A blank string
+* counts as not provided: these URLs are typically wired from environment
+* variables, and a declared-but-empty variable (`COPILOTKIT_INTELLIGENCE_URL=`,
+* common in generated `.env` files and container configs) arrives as `""`. Left
+* as-is it would produce host-relative requests instead of falling back to the
+* managed platform.
+*/
+function configuredUrl(url) {
+	const trimmed = url?.trim();
+	return trimmed ? trimmed : void 0;
+}
+/**
+* Warn when exactly one of `apiUrl`/`wsUrl` is configured. The API and realtime
+* planes are separate hosts, so a lone override silently leaves the other plane
+* on CopilotKit's managed platform — a self-hosted API paired with the managed
+* gateway (or vice versa), which fails as a hang rather than an error.
+*/
+function warnOnPartialHostOverride(apiUrl, wsUrl) {
+	if (apiUrl && !wsUrl) {
+		_copilotkit_shared.logger.warn(`CopilotKitIntelligence: apiUrl is set to "${apiUrl}" but wsUrl is not, so wsUrl falls back to the managed default "${MANAGED_INTELLIGENCE_WS_URL}". The API and realtime planes are separate hosts — set both when pointing at a self-hosted deployment.`);
+		return;
+	}
+	if (wsUrl && !apiUrl) _copilotkit_shared.logger.warn(`CopilotKitIntelligence: wsUrl is set to "${wsUrl}" but apiUrl is not, so apiUrl falls back to the managed default "${MANAGED_INTELLIGENCE_API_URL}". The API and realtime planes are separate hosts — set both when pointing at a self-hosted deployment.`);
+}
 function normalizeIntelligenceWsUrl(wsUrl) {
 	return wsUrl.replace(/\/$/, "");
 }