@copilotkit/runtime 1.83.0 → 2.0.0-rc.0

package/dist/runtime/handlers/header-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.mjs","names":[],"sources":["../../../src/runtime/handlers/header-utils.ts"],"sourcesContent":["/**\n * Exact header names (lowercased) stripped from forwarding by default.\n *\n * These are infrastructure/proxy/platform artifacts that no legitimate agent\n * integration depends on receiving *forwarded from the inbound edge* — the\n * inbound request has already traversed a browser, CDN/edge, load balancer, and\n * hosting platform, each of which stamps its own `x-*` headers. Forwarding them\n * verbatim to an arbitrary configured agent URL leaks client topology and, in\n * the Copilot Cloud case, a platform credential (#5712).\n *\n * `x-amz-cf-id` and `x-copilotcloud-public-api-key` are also covered by the\n * `x-amz-` / `x-copilotcloud-` prefixes below; the exact entries are kept\n * intentionally as documentation anchors for the highest-severity headers\n * (notably the platform API key), not as drift/oversight.\n */\nexport const DEFAULT_DENY_HEADER_NAMES: ReadonlySet<string> = new Set([\n  // Hop-by-hop / proxy topology\n  \"x-forwarded-for\",\n  \"x-forwarded-proto\",\n  \"x-forwarded-host\",\n  \"x-forwarded-port\",\n  \"x-forwarded-server\",\n  \"x-real-ip\",\n  // Cloud / CDN tracing + infra\n  \"x-amzn-trace-id\",\n  \"x-amz-cf-id\",\n  \"x-cloud-trace-context\",\n  \"x-cache\",\n  \"x-served-by\",\n  \"x-request-id\",\n  // CopilotKit platform credentials/identifiers\n  \"x-copilotcloud-public-api-key\",\n]);\n\n/**\n * Header-name prefixes (lowercased) stripped from forwarding by default.\n *\n * Prefix matching covers the well-known platform/CDN families so a new member\n * of a family (e.g. a future `x-vercel-foo`) is denied without a constant edit.\n */\nexport const DEFAULT_DENY_HEADER_PREFIXES: readonly string[] = [\n  \"x-amz-\", // AWS\n  \"x-azure-\", // Azure Front Door\n  \"x-fastly-\", // Fastly\n  \"x-vercel-\", // Vercel\n  \"x-middleware-\", // Next.js\n  \"x-copilotcloud-\", // CopilotKit platform-internal\n];\n\n/**\n * Fully-resolved inbound-header forwarding policy read by the call sites.\n *\n * Distinct from the public `ForwardHeadersConfig` option an integrator passes:\n * the runtime resolves that option ONCE in its constructor into this shape\n * (lowercasing names/prefixes, defaulting `useDefaultDenylist`, building the\n * `allow` set) so the predicate stays branch-simple and the policy can never be\n * re-resolved divergently at a call site. See `resolveForwardHeadersPolicy`.\n */\nexport interface ResolvedForwardHeadersPolicy {\n  /** When true, the built-in infra/platform denylist is active. */\n  useDefaultDenylist: boolean;\n  /** Extra exact names to strip (lowercased). */\n  denyNames: ReadonlySet<string>;\n  /** Extra prefixes to strip (lowercased). */\n  denyPrefixes: readonly string[];\n  /**\n   * If set, allowlist mode: ONLY these (lowercased) names are candidates to\n   * forward — and `denyNames` / `denyPrefixes` still subtract from them.\n   */\n  allow?: ReadonlySet<string>;\n}\n\n/**\n * Public, integrator-facing config for inbound-header forwarding. Resolved into\n * a {@link ResolvedForwardHeadersPolicy} by {@link resolveForwardHeadersPolicy}.\n */\nexport interface ForwardHeadersConfig {\n  /** Strip the built-in infra/platform denylist. @default true */\n  useDefaultDenylist?: boolean;\n  /** Additional exact header names to strip (case-insensitive). */\n  deny?: string[];\n  /** Additional header-name prefixes to strip (case-insensitive). */\n  denyPrefixes?: string[];\n  /**\n   * If set (with at least one non-empty entry), switch to allowlist mode: ONLY\n   * these headers are candidates to forward, overriding the default `x-*` /\n   * `authorization` eligibility (case-insensitive). `deny` / `denyPrefixes`\n   * still apply and subtract from this set — a header listed in both `allow` and\n   * `deny` is NOT forwarded.\n   *\n   * Footgun: in allowlist mode the built-in DEFAULT denylist (and\n   * `useDefaultDenylist`) is BYPASSED — only your `allow` set, minus your own\n   * `deny` / `denyPrefixes`, is forwarded. Do NOT allow-list protected/platform\n   * headers (e.g. `x-copilotcloud-public-api-key`, `x-forwarded-*`) unless you\n   * truly intend to forward them, since the default protection does not apply\n   * here.\n   */\n  allow?: string[];\n}\n\n/**\n * Normalizes a public {@link ForwardHeadersConfig} (or `undefined`) into a\n * fully-resolved {@link ResolvedForwardHeadersPolicy}.\n *\n * - `useDefaultDenylist` defaults to `true` (the built-in denylist is active\n *   on upgrade); pass `false` to restore the previous wide-open behavior.\n * - `deny` / `denyPrefixes` extend (do not replace) the defaults.\n * - `allow` activates allowlist mode only when it has at least one non-empty\n *   entry after normalization.\n *\n * All names/prefixes are trimmed, lowercased, and stripped of empty/\n * whitespace-only entries before use. Trimming/lowercasing keeps matching a\n * plain set/prefix check against the lowercased inbound keys; dropping empties\n * is a safety guard: a stray `denyPrefixes: [\"\"]` would make `startsWith(\"\")`\n * true for every header (silently denying ALL forwarding). Because empties are\n * dropped BEFORE the allowlist-mode decision, an `allow: [\"\"]` / `allow: [\" \"]`\n * normalizes to an empty set and does NOT switch on allowlist mode — the runtime\n * stays in denylist mode. Allowlist mode activates only when `allow` has at\n * least one non-empty entry; these empty/whitespace-only entries are integrator\n * typos, not intent, so we filter them.\n */\nfunction normalizeHeaderEntries(entries: string[] | undefined): string[] {\n  return (entries ?? [])\n    .map((entry) => entry.trim().toLowerCase())\n    .filter((entry) => entry.length > 0);\n}\n\nexport function resolveForwardHeadersPolicy(\n  config: ForwardHeadersConfig | undefined,\n): ResolvedForwardHeadersPolicy {\n  const denyNames = new Set<string>(normalizeHeaderEntries(config?.deny));\n  const denyPrefixes = normalizeHeaderEntries(config?.denyPrefixes);\n  const allowEntries = normalizeHeaderEntries(config?.allow);\n  const allow =\n    allowEntries.length > 0 ? new Set<string>(allowEntries) : undefined;\n\n  return {\n    useDefaultDenylist: config?.useDefaultDenylist ?? true,\n    denyNames,\n    denyPrefixes,\n    allow,\n  };\n}\n\n/**\n * True iff the (already-lowercased) header name matches the integrator's OWN\n * `deny` / `denyPrefixes`. This is the authoritative subtractive check: it is\n * consulted in BOTH allowlist and denylist mode. It deliberately does NOT\n * include the built-in {@link DEFAULT_DENY_HEADER_NAMES} /\n * {@link DEFAULT_DENY_HEADER_PREFIXES} — an explicit `allow` opts the integrator\n * back into a default-denied header on purpose, so only their own `deny`\n * subtracts from an allowlist.\n */\nfunction matchesIntegratorDeny(\n  lower: string,\n  policy: ResolvedForwardHeadersPolicy,\n): boolean {\n  if (policy.denyNames.has(lower)) return true;\n  return policy.denyPrefixes.some((prefix) => lower.startsWith(prefix));\n}\n\n/**\n * Determines if a header should be forwarded under the given resolved policy.\n *\n * The integrator's `deny` / `denyPrefixes` ALWAYS strip, including in allowlist\n * mode: `allow` selects the candidate set, `deny` removes from it. A header the\n * integrator lists in BOTH `allow` and `deny` is NOT forwarded — deny is\n * authoritative so a security-motivated `deny` can never be silently defeated\n * by an overlapping `allow` (the footgun this hardens against).\n *\n * Modes:\n * - Allowlist (`policy.allow` set): forward iff the name is in `allow` AND is\n *   NOT matched by the integrator's `deny` / `denyPrefixes`. Nothing else\n *   forwards — not even the usual `authorization` / `x-*` eligibility.\n * - Denylist (default): base eligibility is `authorization` or any `x-*`, then\n *   the built-in denylist (when enabled) and the integrator's own\n *   names/prefixes strip from that set.\n *\n * Note: the built-in default denylist applies ONLY in denylist mode; an\n * explicit `allow` is treated as the integrator deliberately opting back into\n * those headers, so only their OWN `deny` subtracts in allowlist mode.\n */\nexport function shouldForwardHeader(\n  headerName: string,\n  policy: ResolvedForwardHeadersPolicy,\n): boolean {\n  const lower = headerName.toLowerCase();\n\n  // Allowlist mode: forward iff explicitly allowed AND not subtracted by the\n  // integrator's own deny/denyPrefixes. Nothing else forwards — not even the\n  // usual `authorization` / `x-*` eligibility.\n  if (policy.allow) {\n    return policy.allow.has(lower) && !matchesIntegratorDeny(lower, policy);\n  }\n\n  // Base eligibility (unchanged): authorization + any x-*.\n  const eligible = lower === \"authorization\" || lower.startsWith(\"x-\");\n  if (!eligible) return false;\n\n  // Built-in denylist (default-on): strip known infra/platform headers.\n  if (policy.useDefaultDenylist) {\n    if (DEFAULT_DENY_HEADER_NAMES.has(lower)) return false;\n    if (\n      DEFAULT_DENY_HEADER_PREFIXES.some((prefix) => lower.startsWith(prefix))\n    ) {\n      return false;\n    }\n  }\n\n  // Integrator-supplied additions extend the denylist regardless of the default.\n  if (matchesIntegratorDeny(lower, policy)) return false;\n\n  return true;\n}\n\n/**\n * Extracts headers that should be forwarded from a Request object, applying the\n * resolved forwarding policy. Keys are normalized to the lowercased form the\n * `Headers` iterator yields.\n */\nexport function extractForwardableHeaders(\n  request: Request,\n  policy: ResolvedForwardHeadersPolicy,\n): Record<string, string> {\n  const forwardableHeaders: Record<string, string> = {};\n  request.headers.forEach((value, key) => {\n    if (shouldForwardHeader(key, policy)) {\n      forwardableHeaders[key] = value;\n    }\n  });\n  return forwardableHeaders;\n}\n\n/**\n * Merges forwardable inbound request headers onto the headers a server\n * explicitly configured on an agent, letting the SERVER-CONFIGURED headers WIN\n * on collision — a server-set service-to-service token (e.g. an IAM bearer)\n * must never be silently overridden by a browser/edge/platform-injected inbound\n * header (#5712).\n *\n * The collision check is case-insensitive: `extractForwardableHeaders`\n * normalizes inbound keys to lowercase (`authorization`) while the server\n * typically configures canonical casing (`Authorization`). A plain object\n * spread would treat those as distinct keys and emit BOTH — which downstream\n * (undici) comma-joins into a single invalid \"multiple JWTs\" value. So we drop\n * any forwarded header the agent already sets, matched case-insensitively, and\n * let non-colliding inbound headers pass through unchanged.\n *\n * The same comma-join hazard exists if the SERVER CONFIG ITSELF contains two\n * case-variants of one header (e.g. both `Authorization` and `authorization`\n * in `agent.headers`). A plain `{ ...serverHeaders }` spread would keep both,\n * so we additionally collapse server-self case-collisions to a SINGLE entry,\n * FIRST-OCCURRENCE WINS: the first key seen (in `Object.keys` order) keeps its\n * exact casing and value, and any later case-variant of that name is dropped.\n * Server-wins-over-inbound and case-insensitive inbound suppression are\n * otherwise unchanged.\n *\n * Breadth (which inbound headers are eligible to forward at all) is decided by\n * `policy` upstream in `extractForwardableHeaders` → `shouldForwardHeader`; the\n * merge never re-widens or re-narrows the set.\n */\nexport function mergeForwardableHeaders(\n  serverHeaders: Record<string, string> | undefined,\n  request: Request,\n  policy: ResolvedForwardHeadersPolicy,\n): Record<string, string> {\n  const base = serverHeaders ?? {};\n  const merged: Record<string, string> = {};\n  const serverHeaderNames = new Set<string>();\n  // Collapse server-self case-collisions: first occurrence wins, later\n  // case-variants of the same name are dropped.\n  for (const [name, value] of Object.entries(base)) {\n    const lower = name.toLowerCase();\n    if (serverHeaderNames.has(lower)) {\n      continue;\n    }\n    serverHeaderNames.add(lower);\n    merged[name] = value;\n  }\n  for (const [name, value] of Object.entries(\n    extractForwardableHeaders(request, policy),\n  )) {\n    if (!serverHeaderNames.has(name.toLowerCase())) {\n      merged[name] = value;\n    }\n  }\n  return merged;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAeA,MAAa,4BAAiD,IAAI,IAAI;CAEpE;CACA;CACA;CACA;CACA;CACA;CAEA;CACA;CACA;CACA;CACA;CACA;CAEA;CACD,CAAC;;;;;;;AAQF,MAAa,+BAAkD;CAC7D;CACA;CACA;CACA;CACA;CACA;CACD;;;;;;;;;;;;;;;;;;;;;;AA0ED,SAAS,uBAAuB,SAAyC;AACvE,SAAQ,WAAW,EAAE,EAClB,KAAK,UAAU,MAAM,MAAM,CAAC,aAAa,CAAC,CAC1C,QAAQ,UAAU,MAAM,SAAS,EAAE;;AAGxC,SAAgB,4BACd,QAC8B;CAC9B,MAAM,YAAY,IAAI,IAAY,uBAAuB,QAAQ,KAAK,CAAC;CACvE,MAAM,eAAe,uBAAuB,QAAQ,aAAa;CACjE,MAAM,eAAe,uBAAuB,QAAQ,MAAM;CAC1D,MAAM,QACJ,aAAa,SAAS,IAAI,IAAI,IAAY,aAAa,GAAG;AAE5D,QAAO;EACL,oBAAoB,QAAQ,sBAAsB;EAClD;EACA;EACA;EACD;;;;;;;;;;;AAYH,SAAS,sBACP,OACA,QACS;AACT,KAAI,OAAO,UAAU,IAAI,MAAM,CAAE,QAAO;AACxC,QAAO,OAAO,aAAa,MAAM,WAAW,MAAM,WAAW,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;AAwBvE,SAAgB,oBACd,YACA,QACS;CACT,MAAM,QAAQ,WAAW,aAAa;AAKtC,KAAI,OAAO,MACT,QAAO,OAAO,MAAM,IAAI,MAAM,IAAI,CAAC,sBAAsB,OAAO,OAAO;AAKzE,KAAI,EADa,UAAU,mBAAmB,MAAM,WAAW,KAAK,EACrD,QAAO;AAGtB,KAAI,OAAO,oBAAoB;AAC7B,MAAI,0BAA0B,IAAI,MAAM,CAAE,QAAO;AACjD,MACE,6BAA6B,MAAM,WAAW,MAAM,WAAW,OAAO,CAAC,CAEvE,QAAO;;AAKX,KAAI,sBAAsB,OAAO,OAAO,CAAE,QAAO;AAEjD,QAAO;;;;;;;AAQT,SAAgB,0BACd,SACA,QACwB;CACxB,MAAM,qBAA6C,EAAE;AACrD,SAAQ,QAAQ,SAAS,OAAO,QAAQ;AACtC,MAAI,oBAAoB,KAAK,OAAO,CAClC,oBAAmB,OAAO;GAE5B;AACF,QAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BT,SAAgB,wBACd,eACA,SACA,QACwB;CACxB,MAAM,OAAO,iBAAiB,EAAE;CAChC,MAAM,SAAiC,EAAE;CACzC,MAAM,oCAAoB,IAAI,KAAa;AAG3C,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,KAAK,EAAE;EAChD,MAAM,QAAQ,KAAK,aAAa;AAChC,MAAI,kBAAkB,IAAI,MAAM,CAC9B;AAEF,oBAAkB,IAAI,MAAM;AAC5B,SAAO,QAAQ;;AAEjB,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QACjC,0BAA0B,SAAS,OAAO,CAC3C,CACC,KAAI,CAAC,kBAAkB,IAAI,KAAK,aAAa,CAAC,CAC5C,QAAO,QAAQ;AAGnB,QAAO"}

package/dist/runtime/handlers/intelligence/annotate.cjs

@@ -0,0 +1,83 @@
+const require_runtime = require('../../../_virtual/_rolldown/runtime.cjs');
+const require_json_response = require('../shared/json-response.cjs');
+const require_client = require('../../intelligence-platform/client.cjs');
+const require_resolve_intelligence_user = require('../shared/resolve-intelligence-user.cjs');
+const require_runtime$1 = require('../../core/runtime.cjs');
+let _copilotkit_shared = require("@copilotkit/shared");
+
+//#region src/runtime/handlers/intelligence/annotate.ts
+async function parseJsonBody(request) {
+	try {
+		return await request.json();
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Malformed JSON in annotate body");
+		return require_json_response.errorResponse("Invalid request body", 400);
+	}
+}
+function requireIntelligenceRuntime(runtime) {
+	if (!require_runtime$1.isIntelligenceRuntime(runtime)) return require_json_response.errorResponse("Missing CopilotKitIntelligence configuration. annotate requires a CopilotKitIntelligence instance to be provided in CopilotRuntime options.", 422);
+	return runtime;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+/**
+* `POST /annotate` handler.
+*
+* Three-tier flow:
+*   recordAnnotation() (frontend lib; called by useLearnFromUserAction)
+*     → POST ${runtimeUrl}/annotate
+*     → this handler resolves the Intel user from BFF auth
+*     → intelligence.annotate(...)
+*     → PUT ${apiUrl}/connector/annotate/:clientEventId
+*
+* The frontend hook may auto-generate a UUID `clientEventId` per call
+* so retries are idempotent end-to-end (the platform collapses to the
+* original row).
+*/
+async function handleAnnotate({ runtime, request }) {
+	const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+	if (require_json_response.isHandlerResponse(intelligenceRuntime)) return intelligenceRuntime;
+	const body = await parseJsonBody(request);
+	if (require_json_response.isHandlerResponse(body)) return body;
+	const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+		runtime: intelligenceRuntime,
+		request
+	});
+	if (require_json_response.isHandlerResponse(user)) return user;
+	const parsed = parseAnnotateBody(body);
+	if (require_json_response.isHandlerResponse(parsed)) return parsed;
+	try {
+		const result = await intelligenceRuntime.intelligence.annotate({
+			userId: user.id,
+			threadId: parsed.threadId,
+			type: parsed.type,
+			payload: parsed.payload,
+			clientEventId: parsed.clientEventId,
+			occurredAt: parsed.occurredAt
+		});
+		return new Response(JSON.stringify(result), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	} catch (err) {
+		_copilotkit_shared.logger.error({ err }, "annotate: platform call failed");
+		if (err instanceof require_client.PlatformRequestError && err.status >= 400 && err.status < 500) return require_json_response.errorResponse(err.message, err.status);
+		return require_json_response.errorResponse("Failed to annotate", 502);
+	}
+}
+function parseAnnotateBody(body) {
+	if (!isNonEmptyString(body.threadId)) return require_json_response.errorResponse("Valid threadId is required", 400);
+	if (!isNonEmptyString(body.type)) return require_json_response.errorResponse("Valid type is required", 400);
+	return {
+		type: body.type,
+		payload: body.payload,
+		threadId: body.threadId,
+		clientEventId: isNonEmptyString(body.clientEventId) ? body.clientEventId : void 0,
+		occurredAt: isNonEmptyString(body.occurredAt) ? body.occurredAt : void 0
+	};
+}
+
+//#endregion
+exports.handleAnnotate = handleAnnotate;
+//# sourceMappingURL=annotate.cjs.map

package/dist/runtime/handlers/intelligence/annotate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.cjs","names":["errorResponse","isIntelligenceRuntime","isHandlerResponse","resolveIntelligenceUser","PlatformRequestError"],"sources":["../../../../src/runtime/handlers/intelligence/annotate.ts"],"sourcesContent":["import { logger } from \"@copilotkit/shared\";\nimport type {\n  CopilotIntelligenceRuntimeLike,\n  CopilotRuntimeLike,\n} from \"../../core/runtime\";\nimport { isIntelligenceRuntime } from \"../../core/runtime\";\nimport { PlatformRequestError } from \"../../intelligence-platform/client\";\nimport { errorResponse, isHandlerResponse } from \"../shared/json-response\";\nimport { resolveIntelligenceUser } from \"../shared/resolve-intelligence-user\";\n\ninterface AnnotateHandlerParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n}\n\ninterface AnnotateBody {\n  /** Discriminator identifying the annotation type (e.g. `\"user_action\"`). */\n  type: string;\n  /** Type-specific payload. Shape varies by `type`. */\n  payload?: unknown;\n  /** The thread the annotation is associated with. */\n  threadId: string;\n  /** Caller-supplied idempotency key. Optional — platform auto-generates one when absent. */\n  clientEventId?: string;\n  /** ISO-8601 client-asserted timestamp. Defaults to server NOW() when absent. */\n  occurredAt?: string;\n}\n\nasync function parseJsonBody(\n  request: Request,\n): Promise<Record<string, unknown> | Response> {\n  try {\n    return (await request.json()) as Record<string, unknown>;\n  } catch (error) {\n    logger.error({ err: error }, \"Malformed JSON in annotate body\");\n    return errorResponse(\"Invalid request body\", 400);\n  }\n}\n\nfunction requireIntelligenceRuntime(\n  runtime: CopilotRuntimeLike,\n): CopilotIntelligenceRuntimeLike | Response {\n  if (!isIntelligenceRuntime(runtime)) {\n    return errorResponse(\n      \"Missing CopilotKitIntelligence configuration. annotate requires a CopilotKitIntelligence instance to be provided in CopilotRuntime options.\",\n      422,\n    );\n  }\n  return runtime;\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n\n/**\n * `POST /annotate` handler.\n *\n * Three-tier flow:\n *   recordAnnotation() (frontend lib; called by useLearnFromUserAction)\n *     → POST ${runtimeUrl}/annotate\n *     → this handler resolves the Intel user from BFF auth\n *     → intelligence.annotate(...)\n *     → PUT ${apiUrl}/connector/annotate/:clientEventId\n *\n * The frontend hook may auto-generate a UUID `clientEventId` per call\n * so retries are idempotent end-to-end (the platform collapses to the\n * original row).\n */\nexport async function handleAnnotate({\n  runtime,\n  request,\n}: AnnotateHandlerParams): Promise<Response> {\n  const intelligenceRuntime = requireIntelligenceRuntime(runtime);\n  if (isHandlerResponse(intelligenceRuntime)) return intelligenceRuntime;\n\n  const body = await parseJsonBody(request);\n  if (isHandlerResponse(body)) return body;\n\n  const user = await resolveIntelligenceUser({\n    runtime: intelligenceRuntime,\n    request,\n  });\n  if (isHandlerResponse(user)) return user;\n\n  const parsed = parseAnnotateBody(body);\n  if (isHandlerResponse(parsed)) return parsed;\n\n  try {\n    const result = await intelligenceRuntime.intelligence.annotate({\n      userId: user.id,\n      threadId: parsed.threadId,\n      type: parsed.type,\n      payload: parsed.payload,\n      clientEventId: parsed.clientEventId,\n      occurredAt: parsed.occurredAt,\n    });\n    return new Response(JSON.stringify(result), {\n      status: 200,\n      headers: { \"Content-Type\": \"application/json\" },\n    });\n  } catch (err) {\n    logger.error({ err }, \"annotate: platform call failed\");\n    // Forward the platform's HTTP status when it's a client error\n    // (4xx) so the SDK author sees an actionable response instead of\n    // a generic 502. 5xx and non-platform errors collapse to 502\n    // (\"Bad Gateway\") because the upstream is genuinely at fault.\n    if (\n      err instanceof PlatformRequestError &&\n      err.status >= 400 &&\n      err.status < 500\n    ) {\n      return errorResponse(err.message, err.status);\n    }\n    return errorResponse(\"Failed to annotate\", 502);\n  }\n}\n\nfunction parseAnnotateBody(\n  body: Record<string, unknown>,\n): AnnotateBody | Response {\n  if (!isNonEmptyString(body.threadId)) {\n    return errorResponse(\"Valid threadId is required\", 400);\n  }\n  if (!isNonEmptyString(body.type)) {\n    return errorResponse(\"Valid type is required\", 400);\n  }\n  return {\n    type: body.type,\n    payload: body.payload,\n    threadId: body.threadId,\n    clientEventId: isNonEmptyString(body.clientEventId)\n      ? body.clientEventId\n      : undefined,\n    occurredAt: isNonEmptyString(body.occurredAt) ? body.occurredAt : undefined,\n  };\n}\n"],"mappings":";;;;;;;;AA4BA,eAAe,cACb,SAC6C;AAC7C,KAAI;AACF,SAAQ,MAAM,QAAQ,MAAM;UACrB,OAAO;AACd,4BAAO,MAAM,EAAE,KAAK,OAAO,EAAE,kCAAkC;AAC/D,SAAOA,oCAAc,wBAAwB,IAAI;;;AAIrD,SAAS,2BACP,SAC2C;AAC3C,KAAI,CAACC,wCAAsB,QAAQ,CACjC,QAAOD,oCACL,+IACA,IACD;AAEH,QAAO;;AAGT,SAAS,iBAAiB,OAAiC;AACzD,QAAO,OAAO,UAAU,YAAY,MAAM,SAAS;;;;;;;;;;;;;;;;AAiBrD,eAAsB,eAAe,EACnC,SACA,WAC2C;CAC3C,MAAM,sBAAsB,2BAA2B,QAAQ;AAC/D,KAAIE,wCAAkB,oBAAoB,CAAE,QAAO;CAEnD,MAAM,OAAO,MAAM,cAAc,QAAQ;AACzC,KAAIA,wCAAkB,KAAK,CAAE,QAAO;CAEpC,MAAM,OAAO,MAAMC,0DAAwB;EACzC,SAAS;EACT;EACD,CAAC;AACF,KAAID,wCAAkB,KAAK,CAAE,QAAO;CAEpC,MAAM,SAAS,kBAAkB,KAAK;AACtC,KAAIA,wCAAkB,OAAO,CAAE,QAAO;AAEtC,KAAI;EACF,MAAM,SAAS,MAAM,oBAAoB,aAAa,SAAS;GAC7D,QAAQ,KAAK;GACb,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,eAAe,OAAO;GACtB,YAAY,OAAO;GACpB,CAAC;AACF,SAAO,IAAI,SAAS,KAAK,UAAU,OAAO,EAAE;GAC1C,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CAAC;UACK,KAAK;AACZ,4BAAO,MAAM,EAAE,KAAK,EAAE,iCAAiC;AAKvD,MACE,eAAeE,uCACf,IAAI,UAAU,OACd,IAAI,SAAS,IAEb,QAAOJ,oCAAc,IAAI,SAAS,IAAI,OAAO;AAE/C,SAAOA,oCAAc,sBAAsB,IAAI;;;AAInD,SAAS,kBACP,MACyB;AACzB,KAAI,CAAC,iBAAiB,KAAK,SAAS,CAClC,QAAOA,oCAAc,8BAA8B,IAAI;AAEzD,KAAI,CAAC,iBAAiB,KAAK,KAAK,CAC9B,QAAOA,oCAAc,0BAA0B,IAAI;AAErD,QAAO;EACL,MAAM,KAAK;EACX,SAAS,KAAK;EACd,UAAU,KAAK;EACf,eAAe,iBAAiB,KAAK,cAAc,GAC/C,KAAK,gBACL;EACJ,YAAY,iBAAiB,KAAK,WAAW,GAAG,KAAK,aAAa;EACnE"}

package/dist/runtime/handlers/intelligence/annotate.mjs

@@ -0,0 +1,82 @@
+import { errorResponse, isHandlerResponse } from "../shared/json-response.mjs";
+import { PlatformRequestError } from "../../intelligence-platform/client.mjs";
+import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user.mjs";
+import { isIntelligenceRuntime } from "../../core/runtime.mjs";
+import { logger } from "@copilotkit/shared";
+
+//#region src/runtime/handlers/intelligence/annotate.ts
+async function parseJsonBody(request) {
+	try {
+		return await request.json();
+	} catch (error) {
+		logger.error({ err: error }, "Malformed JSON in annotate body");
+		return errorResponse("Invalid request body", 400);
+	}
+}
+function requireIntelligenceRuntime(runtime) {
+	if (!isIntelligenceRuntime(runtime)) return errorResponse("Missing CopilotKitIntelligence configuration. annotate requires a CopilotKitIntelligence instance to be provided in CopilotRuntime options.", 422);
+	return runtime;
+}
+function isNonEmptyString(value) {
+	return typeof value === "string" && value.length > 0;
+}
+/**
+* `POST /annotate` handler.
+*
+* Three-tier flow:
+*   recordAnnotation() (frontend lib; called by useLearnFromUserAction)
+*     → POST ${runtimeUrl}/annotate
+*     → this handler resolves the Intel user from BFF auth
+*     → intelligence.annotate(...)
+*     → PUT ${apiUrl}/connector/annotate/:clientEventId
+*
+* The frontend hook may auto-generate a UUID `clientEventId` per call
+* so retries are idempotent end-to-end (the platform collapses to the
+* original row).
+*/
+async function handleAnnotate({ runtime, request }) {
+	const intelligenceRuntime = requireIntelligenceRuntime(runtime);
+	if (isHandlerResponse(intelligenceRuntime)) return intelligenceRuntime;
+	const body = await parseJsonBody(request);
+	if (isHandlerResponse(body)) return body;
+	const user = await resolveIntelligenceUser({
+		runtime: intelligenceRuntime,
+		request
+	});
+	if (isHandlerResponse(user)) return user;
+	const parsed = parseAnnotateBody(body);
+	if (isHandlerResponse(parsed)) return parsed;
+	try {
+		const result = await intelligenceRuntime.intelligence.annotate({
+			userId: user.id,
+			threadId: parsed.threadId,
+			type: parsed.type,
+			payload: parsed.payload,
+			clientEventId: parsed.clientEventId,
+			occurredAt: parsed.occurredAt
+		});
+		return new Response(JSON.stringify(result), {
+			status: 200,
+			headers: { "Content-Type": "application/json" }
+		});
+	} catch (err) {
+		logger.error({ err }, "annotate: platform call failed");
+		if (err instanceof PlatformRequestError && err.status >= 400 && err.status < 500) return errorResponse(err.message, err.status);
+		return errorResponse("Failed to annotate", 502);
+	}
+}
+function parseAnnotateBody(body) {
+	if (!isNonEmptyString(body.threadId)) return errorResponse("Valid threadId is required", 400);
+	if (!isNonEmptyString(body.type)) return errorResponse("Valid type is required", 400);
+	return {
+		type: body.type,
+		payload: body.payload,
+		threadId: body.threadId,
+		clientEventId: isNonEmptyString(body.clientEventId) ? body.clientEventId : void 0,
+		occurredAt: isNonEmptyString(body.occurredAt) ? body.occurredAt : void 0
+	};
+}
+
+//#endregion
+export { handleAnnotate };
+//# sourceMappingURL=annotate.mjs.map

package/dist/runtime/handlers/intelligence/annotate.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotate.mjs","names":[],"sources":["../../../../src/runtime/handlers/intelligence/annotate.ts"],"sourcesContent":["import { logger } from \"@copilotkit/shared\";\nimport type {\n  CopilotIntelligenceRuntimeLike,\n  CopilotRuntimeLike,\n} from \"../../core/runtime\";\nimport { isIntelligenceRuntime } from \"../../core/runtime\";\nimport { PlatformRequestError } from \"../../intelligence-platform/client\";\nimport { errorResponse, isHandlerResponse } from \"../shared/json-response\";\nimport { resolveIntelligenceUser } from \"../shared/resolve-intelligence-user\";\n\ninterface AnnotateHandlerParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n}\n\ninterface AnnotateBody {\n  /** Discriminator identifying the annotation type (e.g. `\"user_action\"`). */\n  type: string;\n  /** Type-specific payload. Shape varies by `type`. */\n  payload?: unknown;\n  /** The thread the annotation is associated with. */\n  threadId: string;\n  /** Caller-supplied idempotency key. Optional — platform auto-generates one when absent. */\n  clientEventId?: string;\n  /** ISO-8601 client-asserted timestamp. Defaults to server NOW() when absent. */\n  occurredAt?: string;\n}\n\nasync function parseJsonBody(\n  request: Request,\n): Promise<Record<string, unknown> | Response> {\n  try {\n    return (await request.json()) as Record<string, unknown>;\n  } catch (error) {\n    logger.error({ err: error }, \"Malformed JSON in annotate body\");\n    return errorResponse(\"Invalid request body\", 400);\n  }\n}\n\nfunction requireIntelligenceRuntime(\n  runtime: CopilotRuntimeLike,\n): CopilotIntelligenceRuntimeLike | Response {\n  if (!isIntelligenceRuntime(runtime)) {\n    return errorResponse(\n      \"Missing CopilotKitIntelligence configuration. annotate requires a CopilotKitIntelligence instance to be provided in CopilotRuntime options.\",\n      422,\n    );\n  }\n  return runtime;\n}\n\nfunction isNonEmptyString(value: unknown): value is string {\n  return typeof value === \"string\" && value.length > 0;\n}\n\n/**\n * `POST /annotate` handler.\n *\n * Three-tier flow:\n *   recordAnnotation() (frontend lib; called by useLearnFromUserAction)\n *     → POST ${runtimeUrl}/annotate\n *     → this handler resolves the Intel user from BFF auth\n *     → intelligence.annotate(...)\n *     → PUT ${apiUrl}/connector/annotate/:clientEventId\n *\n * The frontend hook may auto-generate a UUID `clientEventId` per call\n * so retries are idempotent end-to-end (the platform collapses to the\n * original row).\n */\nexport async function handleAnnotate({\n  runtime,\n  request,\n}: AnnotateHandlerParams): Promise<Response> {\n  const intelligenceRuntime = requireIntelligenceRuntime(runtime);\n  if (isHandlerResponse(intelligenceRuntime)) return intelligenceRuntime;\n\n  const body = await parseJsonBody(request);\n  if (isHandlerResponse(body)) return body;\n\n  const user = await resolveIntelligenceUser({\n    runtime: intelligenceRuntime,\n    request,\n  });\n  if (isHandlerResponse(user)) return user;\n\n  const parsed = parseAnnotateBody(body);\n  if (isHandlerResponse(parsed)) return parsed;\n\n  try {\n    const result = await intelligenceRuntime.intelligence.annotate({\n      userId: user.id,\n      threadId: parsed.threadId,\n      type: parsed.type,\n      payload: parsed.payload,\n      clientEventId: parsed.clientEventId,\n      occurredAt: parsed.occurredAt,\n    });\n    return new Response(JSON.stringify(result), {\n      status: 200,\n      headers: { \"Content-Type\": \"application/json\" },\n    });\n  } catch (err) {\n    logger.error({ err }, \"annotate: platform call failed\");\n    // Forward the platform's HTTP status when it's a client error\n    // (4xx) so the SDK author sees an actionable response instead of\n    // a generic 502. 5xx and non-platform errors collapse to 502\n    // (\"Bad Gateway\") because the upstream is genuinely at fault.\n    if (\n      err instanceof PlatformRequestError &&\n      err.status >= 400 &&\n      err.status < 500\n    ) {\n      return errorResponse(err.message, err.status);\n    }\n    return errorResponse(\"Failed to annotate\", 502);\n  }\n}\n\nfunction parseAnnotateBody(\n  body: Record<string, unknown>,\n): AnnotateBody | Response {\n  if (!isNonEmptyString(body.threadId)) {\n    return errorResponse(\"Valid threadId is required\", 400);\n  }\n  if (!isNonEmptyString(body.type)) {\n    return errorResponse(\"Valid type is required\", 400);\n  }\n  return {\n    type: body.type,\n    payload: body.payload,\n    threadId: body.threadId,\n    clientEventId: isNonEmptyString(body.clientEventId)\n      ? body.clientEventId\n      : undefined,\n    occurredAt: isNonEmptyString(body.occurredAt) ? body.occurredAt : undefined,\n  };\n}\n"],"mappings":";;;;;;;AA4BA,eAAe,cACb,SAC6C;AAC7C,KAAI;AACF,SAAQ,MAAM,QAAQ,MAAM;UACrB,OAAO;AACd,SAAO,MAAM,EAAE,KAAK,OAAO,EAAE,kCAAkC;AAC/D,SAAO,cAAc,wBAAwB,IAAI;;;AAIrD,SAAS,2BACP,SAC2C;AAC3C,KAAI,CAAC,sBAAsB,QAAQ,CACjC,QAAO,cACL,+IACA,IACD;AAEH,QAAO;;AAGT,SAAS,iBAAiB,OAAiC;AACzD,QAAO,OAAO,UAAU,YAAY,MAAM,SAAS;;;;;;;;;;;;;;;;AAiBrD,eAAsB,eAAe,EACnC,SACA,WAC2C;CAC3C,MAAM,sBAAsB,2BAA2B,QAAQ;AAC/D,KAAI,kBAAkB,oBAAoB,CAAE,QAAO;CAEnD,MAAM,OAAO,MAAM,cAAc,QAAQ;AACzC,KAAI,kBAAkB,KAAK,CAAE,QAAO;CAEpC,MAAM,OAAO,MAAM,wBAAwB;EACzC,SAAS;EACT;EACD,CAAC;AACF,KAAI,kBAAkB,KAAK,CAAE,QAAO;CAEpC,MAAM,SAAS,kBAAkB,KAAK;AACtC,KAAI,kBAAkB,OAAO,CAAE,QAAO;AAEtC,KAAI;EACF,MAAM,SAAS,MAAM,oBAAoB,aAAa,SAAS;GAC7D,QAAQ,KAAK;GACb,UAAU,OAAO;GACjB,MAAM,OAAO;GACb,SAAS,OAAO;GAChB,eAAe,OAAO;GACtB,YAAY,OAAO;GACpB,CAAC;AACF,SAAO,IAAI,SAAS,KAAK,UAAU,OAAO,EAAE;GAC1C,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CAAC;UACK,KAAK;AACZ,SAAO,MAAM,EAAE,KAAK,EAAE,iCAAiC;AAKvD,MACE,eAAe,wBACf,IAAI,UAAU,OACd,IAAI,SAAS,IAEb,QAAO,cAAc,IAAI,SAAS,IAAI,OAAO;AAE/C,SAAO,cAAc,sBAAsB,IAAI;;;AAInD,SAAS,kBACP,MACyB;AACzB,KAAI,CAAC,iBAAiB,KAAK,SAAS,CAClC,QAAO,cAAc,8BAA8B,IAAI;AAEzD,KAAI,CAAC,iBAAiB,KAAK,KAAK,CAC9B,QAAO,cAAc,0BAA0B,IAAI;AAErD,QAAO;EACL,MAAM,KAAK;EACX,SAAS,KAAK;EACd,UAAU,KAAK;EACf,eAAe,iBAAiB,KAAK,cAAc,GAC/C,KAAK,gBACL;EACJ,YAAY,iBAAiB,KAAK,WAAW,GAAG,KAAK,aAAa;EACnE"}

package/dist/runtime/handlers/intelligence/connect.cjs

@@ -0,0 +1,68 @@
+const require_json_response = require('../shared/json-response.cjs');
+const require_intelligence_utils = require('../shared/intelligence-utils.cjs');
+const require_resolve_intelligence_user = require('../shared/resolve-intelligence-user.cjs');
+
+//#region src/runtime/handlers/intelligence/connect.ts
+/**
+* Builds browser-facing realtime connection metadata owned by the runtime.
+*/
+function buildRealtimeConnectionInfo(params) {
+	return {
+		clientUrl: params.clientUrl,
+		topic: `thread:${params.threadId}`
+	};
+}
+async function handleIntelligenceConnect({ runtime, request, agentId, threadId }) {
+	if (!runtime.intelligence) return Response.json({
+		error: "Intelligence not configured",
+		message: "Intelligence mode requires a CopilotKitIntelligence"
+	}, { status: 500 });
+	try {
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		const result = await runtime.intelligence.ɵconnectThread({
+			threadId,
+			userId: user.id,
+			agentId
+		});
+		if (result === null) return new Response(null, { status: 204 });
+		return Response.json({
+			threadId: result.threadId,
+			joinToken: result.joinToken,
+			runId: result.runId,
+			realtime: buildRealtimeConnectionInfo({
+				clientUrl: runtime.intelligence.ɵgetClientWsUrl(),
+				threadId: result.threadId
+			})
+		}, { headers: {
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive"
+		} });
+	} catch (error) {
+		const status = require_intelligence_utils.getPlatformErrorStatus(error);
+		const message = error instanceof Error ? error.message : "Connect request failed";
+		if (status === 400 || status === 401 || status === 403 || status === 404 || status === 409) return Response.json({
+			error: "Connect request rejected",
+			message: error instanceof Error ? error.message : "Intelligence platform rejected the connect request"
+		}, { status });
+		if (typeof status === "number") {
+			console.error(`Connect request failed with status ${status}:`, error);
+			return Response.json({
+				error: "Connect request failed",
+				message
+			}, { status });
+		}
+		console.error("Connect request could not reach Intelligence:", error);
+		return Response.json({
+			error: "Connect request failed",
+			message
+		}, { status: 502 });
+	}
+}
+
+//#endregion
+exports.handleIntelligenceConnect = handleIntelligenceConnect;
+//# sourceMappingURL=connect.cjs.map

package/dist/runtime/handlers/intelligence/connect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.cjs","names":["resolveIntelligenceUser","isHandlerResponse","getPlatformErrorStatus"],"sources":["../../../../src/runtime/handlers/intelligence/connect.ts"],"sourcesContent":["import type { CopilotIntelligenceRuntimeLike } from \"../../core/runtime\";\nimport { getPlatformErrorStatus } from \"../shared/intelligence-utils\";\nimport { resolveIntelligenceUser } from \"../shared/resolve-intelligence-user\";\nimport { isHandlerResponse } from \"../shared/json-response\";\n\n/**\n * Builds browser-facing realtime connection metadata owned by the runtime.\n */\nfunction buildRealtimeConnectionInfo(params: {\n  clientUrl: string;\n  threadId: string;\n}): { clientUrl: string; topic: string } {\n  return {\n    clientUrl: params.clientUrl,\n    topic: `thread:${params.threadId}`,\n  };\n}\n\ninterface HandleIntelligenceConnectParams {\n  runtime: CopilotIntelligenceRuntimeLike;\n  request: Request;\n  agentId: string;\n  threadId: string;\n}\n\nexport async function handleIntelligenceConnect({\n  runtime,\n  request,\n  agentId,\n  threadId,\n}: HandleIntelligenceConnectParams): Promise<Response> {\n  if (!runtime.intelligence) {\n    return Response.json(\n      {\n        error: \"Intelligence not configured\",\n        message: \"Intelligence mode requires a CopilotKitIntelligence\",\n      },\n      { status: 500 },\n    );\n  }\n\n  try {\n    const user = await resolveIntelligenceUser({ runtime, request });\n    if (isHandlerResponse(user)) {\n      return user;\n    }\n\n    const result = await runtime.intelligence.ɵconnectThread({\n      threadId,\n      userId: user.id,\n      agentId,\n    });\n\n    if (result === null) {\n      return new Response(null, {\n        status: 204,\n      });\n    }\n\n    return Response.json(\n      {\n        threadId: result.threadId,\n        joinToken: result.joinToken,\n        runId: result.runId,\n        realtime: buildRealtimeConnectionInfo({\n          clientUrl: runtime.intelligence.ɵgetClientWsUrl(),\n          threadId: result.threadId,\n        }),\n      },\n      {\n        headers: { \"Cache-Control\": \"no-cache\", Connection: \"keep-alive\" },\n      },\n    );\n  } catch (error) {\n    const status = getPlatformErrorStatus(error);\n    const message =\n      error instanceof Error ? error.message : \"Connect request failed\";\n\n    if (\n      status === 400 ||\n      status === 401 ||\n      status === 403 ||\n      status === 404 ||\n      status === 409\n    ) {\n      return Response.json(\n        {\n          error: \"Connect request rejected\",\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Intelligence platform rejected the connect request\",\n        },\n        { status },\n      );\n    }\n\n    // The platform answered, but with a status we do not special-case above.\n    // Pass it through rather than relabelling it: reporting a 503 as a 404 tells\n    // the browser the thread does not exist, when the truth is that the platform\n    // is temporarily unwell and the request is worth retrying.\n    if (typeof status === \"number\") {\n      console.error(`Connect request failed with status ${status}:`, error);\n      return Response.json(\n        { error: \"Connect request failed\", message },\n        {\n          status,\n        },\n      );\n    }\n\n    // No status at all, so this never reached the platform: a socket timeout, a\n    // DNS failure, a connection reset, or a bug on our side. 502 says \"the thing\n    // behind me is unreachable\", which is both true and actionable. It must not\n    // be a 404, which asserts the thread does not exist and sends the caller off\n    // to investigate the wrong thing entirely.\n    console.error(\"Connect request could not reach Intelligence:\", error);\n    return Response.json(\n      {\n        error: \"Connect request failed\",\n        message,\n      },\n      { status: 502 },\n    );\n  }\n}\n"],"mappings":";;;;;;;;AAQA,SAAS,4BAA4B,QAGI;AACvC,QAAO;EACL,WAAW,OAAO;EAClB,OAAO,UAAU,OAAO;EACzB;;AAUH,eAAsB,0BAA0B,EAC9C,SACA,SACA,SACA,YACqD;AACrD,KAAI,CAAC,QAAQ,aACX,QAAO,SAAS,KACd;EACE,OAAO;EACP,SAAS;EACV,EACD,EAAE,QAAQ,KAAK,CAChB;AAGH,KAAI;EACF,MAAM,OAAO,MAAMA,0DAAwB;GAAE;GAAS;GAAS,CAAC;AAChE,MAAIC,wCAAkB,KAAK,CACzB,QAAO;EAGT,MAAM,SAAS,MAAM,QAAQ,aAAa,eAAe;GACvD;GACA,QAAQ,KAAK;GACb;GACD,CAAC;AAEF,MAAI,WAAW,KACb,QAAO,IAAI,SAAS,MAAM,EACxB,QAAQ,KACT,CAAC;AAGJ,SAAO,SAAS,KACd;GACE,UAAU,OAAO;GACjB,WAAW,OAAO;GAClB,OAAO,OAAO;GACd,UAAU,4BAA4B;IACpC,WAAW,QAAQ,aAAa,iBAAiB;IACjD,UAAU,OAAO;IAClB,CAAC;GACH,EACD,EACE,SAAS;GAAE,iBAAiB;GAAY,YAAY;GAAc,EACnE,CACF;UACM,OAAO;EACd,MAAM,SAASC,kDAAuB,MAAM;EAC5C,MAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU;AAE3C,MACE,WAAW,OACX,WAAW,OACX,WAAW,OACX,WAAW,OACX,WAAW,IAEX,QAAO,SAAS,KACd;GACE,OAAO;GACP,SACE,iBAAiB,QACb,MAAM,UACN;GACP,EACD,EAAE,QAAQ,CACX;AAOH,MAAI,OAAO,WAAW,UAAU;AAC9B,WAAQ,MAAM,sCAAsC,OAAO,IAAI,MAAM;AACrE,UAAO,SAAS,KACd;IAAE,OAAO;IAA0B;IAAS,EAC5C,EACE,QACD,CACF;;AAQH,UAAQ,MAAM,iDAAiD,MAAM;AACrE,SAAO,SAAS,KACd;GACE,OAAO;GACP;GACD,EACD,EAAE,QAAQ,KAAK,CAChB"}

package/dist/runtime/handlers/intelligence/connect.mjs

@@ -0,0 +1,68 @@
+import { isHandlerResponse } from "../shared/json-response.mjs";
+import { getPlatformErrorStatus } from "../shared/intelligence-utils.mjs";
+import { resolveIntelligenceUser } from "../shared/resolve-intelligence-user.mjs";
+
+//#region src/runtime/handlers/intelligence/connect.ts
+/**
+* Builds browser-facing realtime connection metadata owned by the runtime.
+*/
+function buildRealtimeConnectionInfo(params) {
+	return {
+		clientUrl: params.clientUrl,
+		topic: `thread:${params.threadId}`
+	};
+}
+async function handleIntelligenceConnect({ runtime, request, agentId, threadId }) {
+	if (!runtime.intelligence) return Response.json({
+		error: "Intelligence not configured",
+		message: "Intelligence mode requires a CopilotKitIntelligence"
+	}, { status: 500 });
+	try {
+		const user = await resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (isHandlerResponse(user)) return user;
+		const result = await runtime.intelligence.ɵconnectThread({
+			threadId,
+			userId: user.id,
+			agentId
+		});
+		if (result === null) return new Response(null, { status: 204 });
+		return Response.json({
+			threadId: result.threadId,
+			joinToken: result.joinToken,
+			runId: result.runId,
+			realtime: buildRealtimeConnectionInfo({
+				clientUrl: runtime.intelligence.ɵgetClientWsUrl(),
+				threadId: result.threadId
+			})
+		}, { headers: {
+			"Cache-Control": "no-cache",
+			Connection: "keep-alive"
+		} });
+	} catch (error) {
+		const status = getPlatformErrorStatus(error);
+		const message = error instanceof Error ? error.message : "Connect request failed";
+		if (status === 400 || status === 401 || status === 403 || status === 404 || status === 409) return Response.json({
+			error: "Connect request rejected",
+			message: error instanceof Error ? error.message : "Intelligence platform rejected the connect request"
+		}, { status });
+		if (typeof status === "number") {
+			console.error(`Connect request failed with status ${status}:`, error);
+			return Response.json({
+				error: "Connect request failed",
+				message
+			}, { status });
+		}
+		console.error("Connect request could not reach Intelligence:", error);
+		return Response.json({
+			error: "Connect request failed",
+			message
+		}, { status: 502 });
+	}
+}
+
+//#endregion
+export { handleIntelligenceConnect };
+//# sourceMappingURL=connect.mjs.map

package/dist/runtime/handlers/intelligence/connect.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.mjs","names":[],"sources":["../../../../src/runtime/handlers/intelligence/connect.ts"],"sourcesContent":["import type { CopilotIntelligenceRuntimeLike } from \"../../core/runtime\";\nimport { getPlatformErrorStatus } from \"../shared/intelligence-utils\";\nimport { resolveIntelligenceUser } from \"../shared/resolve-intelligence-user\";\nimport { isHandlerResponse } from \"../shared/json-response\";\n\n/**\n * Builds browser-facing realtime connection metadata owned by the runtime.\n */\nfunction buildRealtimeConnectionInfo(params: {\n  clientUrl: string;\n  threadId: string;\n}): { clientUrl: string; topic: string } {\n  return {\n    clientUrl: params.clientUrl,\n    topic: `thread:${params.threadId}`,\n  };\n}\n\ninterface HandleIntelligenceConnectParams {\n  runtime: CopilotIntelligenceRuntimeLike;\n  request: Request;\n  agentId: string;\n  threadId: string;\n}\n\nexport async function handleIntelligenceConnect({\n  runtime,\n  request,\n  agentId,\n  threadId,\n}: HandleIntelligenceConnectParams): Promise<Response> {\n  if (!runtime.intelligence) {\n    return Response.json(\n      {\n        error: \"Intelligence not configured\",\n        message: \"Intelligence mode requires a CopilotKitIntelligence\",\n      },\n      { status: 500 },\n    );\n  }\n\n  try {\n    const user = await resolveIntelligenceUser({ runtime, request });\n    if (isHandlerResponse(user)) {\n      return user;\n    }\n\n    const result = await runtime.intelligence.ɵconnectThread({\n      threadId,\n      userId: user.id,\n      agentId,\n    });\n\n    if (result === null) {\n      return new Response(null, {\n        status: 204,\n      });\n    }\n\n    return Response.json(\n      {\n        threadId: result.threadId,\n        joinToken: result.joinToken,\n        runId: result.runId,\n        realtime: buildRealtimeConnectionInfo({\n          clientUrl: runtime.intelligence.ɵgetClientWsUrl(),\n          threadId: result.threadId,\n        }),\n      },\n      {\n        headers: { \"Cache-Control\": \"no-cache\", Connection: \"keep-alive\" },\n      },\n    );\n  } catch (error) {\n    const status = getPlatformErrorStatus(error);\n    const message =\n      error instanceof Error ? error.message : \"Connect request failed\";\n\n    if (\n      status === 400 ||\n      status === 401 ||\n      status === 403 ||\n      status === 404 ||\n      status === 409\n    ) {\n      return Response.json(\n        {\n          error: \"Connect request rejected\",\n          message:\n            error instanceof Error\n              ? error.message\n              : \"Intelligence platform rejected the connect request\",\n        },\n        { status },\n      );\n    }\n\n    // The platform answered, but with a status we do not special-case above.\n    // Pass it through rather than relabelling it: reporting a 503 as a 404 tells\n    // the browser the thread does not exist, when the truth is that the platform\n    // is temporarily unwell and the request is worth retrying.\n    if (typeof status === \"number\") {\n      console.error(`Connect request failed with status ${status}:`, error);\n      return Response.json(\n        { error: \"Connect request failed\", message },\n        {\n          status,\n        },\n      );\n    }\n\n    // No status at all, so this never reached the platform: a socket timeout, a\n    // DNS failure, a connection reset, or a bug on our side. 502 says \"the thing\n    // behind me is unreachable\", which is both true and actionable. It must not\n    // be a 404, which asserts the thread does not exist and sends the caller off\n    // to investigate the wrong thing entirely.\n    console.error(\"Connect request could not reach Intelligence:\", error);\n    return Response.json(\n      {\n        error: \"Connect request failed\",\n        message,\n      },\n      { status: 502 },\n    );\n  }\n}\n"],"mappings":";;;;;;;;AAQA,SAAS,4BAA4B,QAGI;AACvC,QAAO;EACL,WAAW,OAAO;EAClB,OAAO,UAAU,OAAO;EACzB;;AAUH,eAAsB,0BAA0B,EAC9C,SACA,SACA,SACA,YACqD;AACrD,KAAI,CAAC,QAAQ,aACX,QAAO,SAAS,KACd;EACE,OAAO;EACP,SAAS;EACV,EACD,EAAE,QAAQ,KAAK,CAChB;AAGH,KAAI;EACF,MAAM,OAAO,MAAM,wBAAwB;GAAE;GAAS;GAAS,CAAC;AAChE,MAAI,kBAAkB,KAAK,CACzB,QAAO;EAGT,MAAM,SAAS,MAAM,QAAQ,aAAa,eAAe;GACvD;GACA,QAAQ,KAAK;GACb;GACD,CAAC;AAEF,MAAI,WAAW,KACb,QAAO,IAAI,SAAS,MAAM,EACxB,QAAQ,KACT,CAAC;AAGJ,SAAO,SAAS,KACd;GACE,UAAU,OAAO;GACjB,WAAW,OAAO;GAClB,OAAO,OAAO;GACd,UAAU,4BAA4B;IACpC,WAAW,QAAQ,aAAa,iBAAiB;IACjD,UAAU,OAAO;IAClB,CAAC;GACH,EACD,EACE,SAAS;GAAE,iBAAiB;GAAY,YAAY;GAAc,EACnE,CACF;UACM,OAAO;EACd,MAAM,SAAS,uBAAuB,MAAM;EAC5C,MAAM,UACJ,iBAAiB,QAAQ,MAAM,UAAU;AAE3C,MACE,WAAW,OACX,WAAW,OACX,WAAW,OACX,WAAW,OACX,WAAW,IAEX,QAAO,SAAS,KACd;GACE,OAAO;GACP,SACE,iBAAiB,QACb,MAAM,UACN;GACP,EACD,EAAE,QAAQ,CACX;AAOH,MAAI,OAAO,WAAW,UAAU;AAC9B,WAAQ,MAAM,sCAAsC,OAAO,IAAI,MAAM;AACrE,UAAO,SAAS,KACd;IAAE,OAAO;IAA0B;IAAS,EAC5C,EACE,QACD,CACF;;AAQH,UAAQ,MAAM,iDAAiD,MAAM;AACrE,SAAO,SAAS,KACd;GACE,OAAO;GACP;GACD,EACD,EAAE,QAAQ,KAAK,CAChB"}