@copilotkit/runtime 1.62.2 → 1.63.0

package/dist/v2/runtime/handlers/header-utils.d.cts

@@ -0,0 +1,54 @@
+require("reflect-metadata");
+//#region src/v2/runtime/handlers/header-utils.d.ts
+/**
+ * Fully-resolved inbound-header forwarding policy read by the call sites.
+ *
+ * Distinct from the public `ForwardHeadersConfig` option an integrator passes:
+ * the runtime resolves that option ONCE in its constructor into this shape
+ * (lowercasing names/prefixes, defaulting `useDefaultDenylist`, building the
+ * `allow` set) so the predicate stays branch-simple and the policy can never be
+ * re-resolved divergently at a call site. See `resolveForwardHeadersPolicy`.
+ */
+interface ResolvedForwardHeadersPolicy {
+  /** When true, the built-in infra/platform denylist is active. */
+  useDefaultDenylist: boolean;
+  /** Extra exact names to strip (lowercased). */
+  denyNames: ReadonlySet<string>;
+  /** Extra prefixes to strip (lowercased). */
+  denyPrefixes: readonly string[];
+  /**
+   * If set, allowlist mode: ONLY these (lowercased) names are candidates to
+   * forward — and `denyNames` / `denyPrefixes` still subtract from them.
+   */
+  allow?: ReadonlySet<string>;
+}
+/**
+ * Public, integrator-facing config for inbound-header forwarding. Resolved into
+ * a {@link ResolvedForwardHeadersPolicy} by {@link resolveForwardHeadersPolicy}.
+ */
+interface ForwardHeadersConfig {
+  /** Strip the built-in infra/platform denylist. @default true */
+  useDefaultDenylist?: boolean;
+  /** Additional exact header names to strip (case-insensitive). */
+  deny?: string[];
+  /** Additional header-name prefixes to strip (case-insensitive). */
+  denyPrefixes?: string[];
+  /**
+   * If set (with at least one non-empty entry), switch to allowlist mode: ONLY
+   * these headers are candidates to forward, overriding the default `x-*` /
+   * `authorization` eligibility (case-insensitive). `deny` / `denyPrefixes`
+   * still apply and subtract from this set — a header listed in both `allow` and
+   * `deny` is NOT forwarded.
+   *
+   * Footgun: in allowlist mode the built-in DEFAULT denylist (and
+   * `useDefaultDenylist`) is BYPASSED — only your `allow` set, minus your own
+   * `deny` / `denyPrefixes`, is forwarded. Do NOT allow-list protected/platform
+   * headers (e.g. `x-copilotcloud-public-api-key`, `x-forwarded-*`) unless you
+   * truly intend to forward them, since the default protection does not apply
+   * here.
+   */
+  allow?: string[];
+}
+//#endregion
+export { ForwardHeadersConfig, ResolvedForwardHeadersPolicy };
+//# sourceMappingURL=header-utils.d.cts.map

package/dist/v2/runtime/handlers/header-utils.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.d.cts","names":[],"sources":["../../../../src/v2/runtime/handlers/header-utils.ts"],"mappings":";;;;;;;;;;;UA0DiB,4BAAA;;EAEf,kBAAA;;EAEA,SAAA,EAAW,WAAA;;EAEX,YAAA;;;;;EAKA,KAAA,GAAQ,WAAA;AAAA;;;;;UAOO,oBAAA;;EAEf,kBAAA;;EAEA,IAAA;;EAEA,YAAA;;;;;;;;;;;;;;;EAeA,KAAA;AAAA"}

package/dist/v2/runtime/handlers/header-utils.d.mts

@@ -0,0 +1,54 @@
+import "reflect-metadata";
+//#region src/v2/runtime/handlers/header-utils.d.ts
+/**
+ * Fully-resolved inbound-header forwarding policy read by the call sites.
+ *
+ * Distinct from the public `ForwardHeadersConfig` option an integrator passes:
+ * the runtime resolves that option ONCE in its constructor into this shape
+ * (lowercasing names/prefixes, defaulting `useDefaultDenylist`, building the
+ * `allow` set) so the predicate stays branch-simple and the policy can never be
+ * re-resolved divergently at a call site. See `resolveForwardHeadersPolicy`.
+ */
+interface ResolvedForwardHeadersPolicy {
+  /** When true, the built-in infra/platform denylist is active. */
+  useDefaultDenylist: boolean;
+  /** Extra exact names to strip (lowercased). */
+  denyNames: ReadonlySet<string>;
+  /** Extra prefixes to strip (lowercased). */
+  denyPrefixes: readonly string[];
+  /**
+   * If set, allowlist mode: ONLY these (lowercased) names are candidates to
+   * forward — and `denyNames` / `denyPrefixes` still subtract from them.
+   */
+  allow?: ReadonlySet<string>;
+}
+/**
+ * Public, integrator-facing config for inbound-header forwarding. Resolved into
+ * a {@link ResolvedForwardHeadersPolicy} by {@link resolveForwardHeadersPolicy}.
+ */
+interface ForwardHeadersConfig {
+  /** Strip the built-in infra/platform denylist. @default true */
+  useDefaultDenylist?: boolean;
+  /** Additional exact header names to strip (case-insensitive). */
+  deny?: string[];
+  /** Additional header-name prefixes to strip (case-insensitive). */
+  denyPrefixes?: string[];
+  /**
+   * If set (with at least one non-empty entry), switch to allowlist mode: ONLY
+   * these headers are candidates to forward, overriding the default `x-*` /
+   * `authorization` eligibility (case-insensitive). `deny` / `denyPrefixes`
+   * still apply and subtract from this set — a header listed in both `allow` and
+   * `deny` is NOT forwarded.
+   *
+   * Footgun: in allowlist mode the built-in DEFAULT denylist (and
+   * `useDefaultDenylist`) is BYPASSED — only your `allow` set, minus your own
+   * `deny` / `denyPrefixes`, is forwarded. Do NOT allow-list protected/platform
+   * headers (e.g. `x-copilotcloud-public-api-key`, `x-forwarded-*`) unless you
+   * truly intend to forward them, since the default protection does not apply
+   * here.
+   */
+  allow?: string[];
+}
+//#endregion
+export { ForwardHeadersConfig, ResolvedForwardHeadersPolicy };
+//# sourceMappingURL=header-utils.d.mts.map

package/dist/v2/runtime/handlers/header-utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"header-utils.d.mts","names":[],"sources":["../../../../src/v2/runtime/handlers/header-utils.ts"],"mappings":";;;;;;;;;;;UA0DiB,4BAAA;;EAEf,kBAAA;;EAEA,SAAA,EAAW,WAAA;;EAEX,YAAA;;;;;EAKA,KAAA,GAAQ,WAAA;AAAA;;;;;UAOO,oBAAA;;EAEf,kBAAA;;EAEA,IAAA;;EAEA,YAAA;;;;;;;;;;;;;;;EAeA,KAAA;AAAA"}

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

@@ -1,25 +1,184 @@
 import "reflect-metadata";
 //#region src/v2/runtime/handlers/header-utils.ts
 /**
-* Determines if a header should be forwarded based on the allowlist.
-* Forwards: authorization header and all x-* custom headers.
+* Exact header names (lowercased) stripped from forwarding by default.
+*
+* These are infrastructure/proxy/platform artifacts that no legitimate agent
+* integration depends on receiving *forwarded from the inbound edge* — the
+* inbound request has already traversed a browser, CDN/edge, load balancer, and
+* hosting platform, each of which stamps its own `x-*` headers. Forwarding them
+* verbatim to an arbitrary configured agent URL leaks client topology and, in
+* the Copilot Cloud case, a platform credential (#5712).
+*
+* `x-amz-cf-id` and `x-copilotcloud-public-api-key` are also covered by the
+* `x-amz-` / `x-copilotcloud-` prefixes below; the exact entries are kept
+* intentionally as documentation anchors for the highest-severity headers
+* (notably the platform API key), not as drift/oversight.
 */
-function shouldForwardHeader(headerName) {
+const DEFAULT_DENY_HEADER_NAMES = new Set([
+	"x-forwarded-for",
+	"x-forwarded-proto",
+	"x-forwarded-host",
+	"x-forwarded-port",
+	"x-forwarded-server",
+	"x-real-ip",
+	"x-amzn-trace-id",
+	"x-amz-cf-id",
+	"x-cloud-trace-context",
+	"x-cache",
+	"x-served-by",
+	"x-request-id",
+	"x-copilotcloud-public-api-key"
+]);
+/**
+* Header-name prefixes (lowercased) stripped from forwarding by default.
+*
+* Prefix matching covers the well-known platform/CDN families so a new member
+* of a family (e.g. a future `x-vercel-foo`) is denied without a constant edit.
+*/
+const DEFAULT_DENY_HEADER_PREFIXES = [
+	"x-amz-",
+	"x-azure-",
+	"x-fastly-",
+	"x-vercel-",
+	"x-middleware-",
+	"x-copilotcloud-"
+];
+/**
+* Normalizes a public {@link ForwardHeadersConfig} (or `undefined`) into a
+* fully-resolved {@link ResolvedForwardHeadersPolicy}.
+*
+* - `useDefaultDenylist` defaults to `true` (the built-in denylist is active
+*   on upgrade); pass `false` to restore the previous wide-open behavior.
+* - `deny` / `denyPrefixes` extend (do not replace) the defaults.
+* - `allow` activates allowlist mode only when it has at least one non-empty
+*   entry after normalization.
+*
+* All names/prefixes are trimmed, lowercased, and stripped of empty/
+* whitespace-only entries before use. Trimming/lowercasing keeps matching a
+* plain set/prefix check against the lowercased inbound keys; dropping empties
+* is a safety guard: a stray `denyPrefixes: [""]` would make `startsWith("")`
+* true for every header (silently denying ALL forwarding). Because empties are
+* dropped BEFORE the allowlist-mode decision, an `allow: [""]` / `allow: [" "]`
+* normalizes to an empty set and does NOT switch on allowlist mode — the runtime
+* stays in denylist mode. Allowlist mode activates only when `allow` has at
+* least one non-empty entry; these empty/whitespace-only entries are integrator
+* typos, not intent, so we filter them.
+*/
+function normalizeHeaderEntries(entries) {
+	return (entries ?? []).map((entry) => entry.trim().toLowerCase()).filter((entry) => entry.length > 0);
+}
+function resolveForwardHeadersPolicy(config) {
+	const denyNames = new Set(normalizeHeaderEntries(config?.deny));
+	const denyPrefixes = normalizeHeaderEntries(config?.denyPrefixes);
+	const allowEntries = normalizeHeaderEntries(config?.allow);
+	const allow = allowEntries.length > 0 ? new Set(allowEntries) : void 0;
+	return {
+		useDefaultDenylist: config?.useDefaultDenylist ?? true,
+		denyNames,
+		denyPrefixes,
+		allow
+	};
+}
+/**
+* True iff the (already-lowercased) header name matches the integrator's OWN
+* `deny` / `denyPrefixes`. This is the authoritative subtractive check: it is
+* consulted in BOTH allowlist and denylist mode. It deliberately does NOT
+* include the built-in {@link DEFAULT_DENY_HEADER_NAMES} /
+* {@link DEFAULT_DENY_HEADER_PREFIXES} — an explicit `allow` opts the integrator
+* back into a default-denied header on purpose, so only their own `deny`
+* subtracts from an allowlist.
+*/
+function matchesIntegratorDeny(lower, policy) {
+	if (policy.denyNames.has(lower)) return true;
+	return policy.denyPrefixes.some((prefix) => lower.startsWith(prefix));
+}
+/**
+* Determines if a header should be forwarded under the given resolved policy.
+*
+* The integrator's `deny` / `denyPrefixes` ALWAYS strip, including in allowlist
+* mode: `allow` selects the candidate set, `deny` removes from it. A header the
+* integrator lists in BOTH `allow` and `deny` is NOT forwarded — deny is
+* authoritative so a security-motivated `deny` can never be silently defeated
+* by an overlapping `allow` (the footgun this hardens against).
+*
+* Modes:
+* - Allowlist (`policy.allow` set): forward iff the name is in `allow` AND is
+*   NOT matched by the integrator's `deny` / `denyPrefixes`. Nothing else
+*   forwards — not even the usual `authorization` / `x-*` eligibility.
+* - Denylist (default): base eligibility is `authorization` or any `x-*`, then
+*   the built-in denylist (when enabled) and the integrator's own
+*   names/prefixes strip from that set.
+*
+* Note: the built-in default denylist applies ONLY in denylist mode; an
+* explicit `allow` is treated as the integrator deliberately opting back into
+* those headers, so only their OWN `deny` subtracts in allowlist mode.
+*/
+function shouldForwardHeader(headerName, policy) {
 	const lower = headerName.toLowerCase();
-	return lower === "authorization" || lower.startsWith("x-");
+	if (policy.allow) return policy.allow.has(lower) && !matchesIntegratorDeny(lower, policy);
+	if (!(lower === "authorization" || lower.startsWith("x-"))) return false;
+	if (policy.useDefaultDenylist) {
+		if (DEFAULT_DENY_HEADER_NAMES.has(lower)) return false;
+		if (DEFAULT_DENY_HEADER_PREFIXES.some((prefix) => lower.startsWith(prefix))) return false;
+	}
+	if (matchesIntegratorDeny(lower, policy)) return false;
+	return true;
 }
 /**
-* Extracts headers that should be forwarded from a Request object.
-* Forwards only authorization and x-* headers.
+* Extracts headers that should be forwarded from a Request object, applying the
+* resolved forwarding policy. Keys are normalized to the lowercased form the
+* `Headers` iterator yields.
 */
-function extractForwardableHeaders(request) {
+function extractForwardableHeaders(request, policy) {
 	const forwardableHeaders = {};
 	request.headers.forEach((value, key) => {
-		if (shouldForwardHeader(key)) forwardableHeaders[key] = value;
+		if (shouldForwardHeader(key, policy)) forwardableHeaders[key] = value;
 	});
 	return forwardableHeaders;
 }
+/**
+* Merges forwardable inbound request headers onto the headers a server
+* explicitly configured on an agent, letting the SERVER-CONFIGURED headers WIN
+* on collision — a server-set service-to-service token (e.g. an IAM bearer)
+* must never be silently overridden by a browser/edge/platform-injected inbound
+* header (#5712).
+*
+* The collision check is case-insensitive: `extractForwardableHeaders`
+* normalizes inbound keys to lowercase (`authorization`) while the server
+* typically configures canonical casing (`Authorization`). A plain object
+* spread would treat those as distinct keys and emit BOTH — which downstream
+* (undici) comma-joins into a single invalid "multiple JWTs" value. So we drop
+* any forwarded header the agent already sets, matched case-insensitively, and
+* let non-colliding inbound headers pass through unchanged.
+*
+* The same comma-join hazard exists if the SERVER CONFIG ITSELF contains two
+* case-variants of one header (e.g. both `Authorization` and `authorization`
+* in `agent.headers`). A plain `{ ...serverHeaders }` spread would keep both,
+* so we additionally collapse server-self case-collisions to a SINGLE entry,
+* FIRST-OCCURRENCE WINS: the first key seen (in `Object.keys` order) keeps its
+* exact casing and value, and any later case-variant of that name is dropped.
+* Server-wins-over-inbound and case-insensitive inbound suppression are
+* otherwise unchanged.
+*
+* Breadth (which inbound headers are eligible to forward at all) is decided by
+* `policy` upstream in `extractForwardableHeaders` → `shouldForwardHeader`; the
+* merge never re-widens or re-narrows the set.
+*/
+function mergeForwardableHeaders(serverHeaders, request, policy) {
+	const base = serverHeaders ?? {};
+	const merged = {};
+	const serverHeaderNames = /* @__PURE__ */ new Set();
+	for (const [name, value] of Object.entries(base)) {
+		const lower = name.toLowerCase();
+		if (serverHeaderNames.has(lower)) continue;
+		serverHeaderNames.add(lower);
+		merged[name] = value;
+	}
+	for (const [name, value] of Object.entries(extractForwardableHeaders(request, policy))) if (!serverHeaderNames.has(name.toLowerCase())) merged[name] = value;
+	return merged;
+}
 
 //#endregion
-export { extractForwardableHeaders };
+export { mergeForwardableHeaders, resolveForwardHeadersPolicy };
 //# sourceMappingURL=header-utils.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"header-utils.mjs","names":[],"sources":["../../../../src/v2/runtime/handlers/header-utils.ts"],"sourcesContent":["/**\n * Determines if a header should be forwarded based on the allowlist.\n * Forwards: authorization header and all x-* custom headers.\n */\nexport function shouldForwardHeader(headerName: string): boolean {\n  const lower = headerName.toLowerCase();\n  return lower === \"authorization\" || lower.startsWith(\"x-\");\n}\n\n/**\n * Extracts headers that should be forwarded from a Request object.\n * Forwards only authorization and x-* headers.\n */\nexport function extractForwardableHeaders(\n  request: Request,\n): Record<string, string> {\n  const forwardableHeaders: Record<string, string> = {};\n  request.headers.forEach((value, key) => {\n    if (shouldForwardHeader(key)) {\n      forwardableHeaders[key] = value;\n    }\n  });\n  return forwardableHeaders;\n}\n"],"mappings":";;;;;;AAIA,SAAgB,oBAAoB,YAA6B;CAC/D,MAAM,QAAQ,WAAW,aAAa;AACtC,QAAO,UAAU,mBAAmB,MAAM,WAAW,KAAK;;;;;;AAO5D,SAAgB,0BACd,SACwB;CACxB,MAAM,qBAA6C,EAAE;AACrD,SAAQ,QAAQ,SAAS,OAAO,QAAQ;AACtC,MAAI,oBAAoB,IAAI,CAC1B,oBAAmB,OAAO;GAE5B;AACF,QAAO"}
+{"version":3,"file":"header-utils.mjs","names":[],"sources":["../../../../src/v2/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/v2/runtime/handlers/intelligence/memories.cjs

@@ -0,0 +1,209 @@
+require("reflect-metadata");
+const require_runtime = require('../../../../_virtual/_rolldown/runtime.cjs');
+const require_runtime$1 = require('../../core/runtime.cjs');
+const require_client = require('../../intelligence-platform/client.cjs');
+const require_json_response = require('../shared/json-response.cjs');
+const require_resolve_intelligence_user = require('../shared/resolve-intelligence-user.cjs');
+let _copilotkit_shared = require("@copilotkit/shared");
+
+//#region src/v2/runtime/handlers/intelligence/memories.ts
+const MISSING_INTELLIGENCE_MESSAGE = "Missing CopilotKitIntelligence configuration. Memory operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.";
+/** Allowed `kind` vocabulary the platform's memory endpoints accept. */
+const MEMORY_KINDS = new Set([
+	"topical",
+	"episodic",
+	"operational"
+]);
+/** Allowed `scope` vocabulary the platform's memory endpoints accept. */
+const MEMORY_SCOPES = new Set(["user", "project"]);
+/**
+* Maps a thrown error to a `Response`.
+*
+* For a {@link PlatformRequestError}, forward only client-actionable **4xx**
+* statuses verbatim (e.g. 404 missing/wrong-scope memory, 409 conflict, 422
+* unprocessable) so a `useMemories` consumer can branch on them — a flat 500
+* would erase that distinction. A platform **5xx** (or any non-4xx / malformed
+* status) means the runtime is healthy but its dependency failed, so it surfaces
+* as `502 Bad Gateway` rather than echoing the upstream status as if the runtime
+* itself broke — and this also avoids a `new Response(..., { status })`
+* `RangeError` on an out-of-range status. Non-platform throws stay 500.
+*/
+function memoryErrorResponse(error, message) {
+	if (error instanceof require_client.PlatformRequestError) {
+		const { status } = error;
+		if (Number.isInteger(status) && status >= 400 && status <= 499) return require_json_response.errorResponse(message, status);
+		return require_json_response.errorResponse(message, 502);
+	}
+	return require_json_response.errorResponse(message, 500);
+}
+async function parseJsonBody(request) {
+	try {
+		return await request.json();
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Malformed JSON in memory request body");
+		return require_json_response.errorResponse("Invalid request body", 400);
+	}
+}
+/**
+* Extracts and validates the create/supersede body fields the platform's
+* memory endpoints require. Returns a `Response` (400) on invalid input.
+*/
+function parseMemoryBody(body) {
+	const { content, kind, scope, sourceThreadIds } = body;
+	if (typeof content !== "string" || typeof kind !== "string") return require_json_response.errorResponse("Memory requires string `content` and `kind`", 400);
+	if (!MEMORY_KINDS.has(kind)) return require_json_response.errorResponse("Memory `kind` must be one of: topical, episodic, operational", 400);
+	if (scope !== void 0 && typeof scope !== "string") return require_json_response.errorResponse("Memory `scope` must be a string when provided", 400);
+	if (typeof scope === "string" && !MEMORY_SCOPES.has(scope)) return require_json_response.errorResponse("Memory `scope` must be one of: user, project", 400);
+	if (sourceThreadIds !== void 0 && (!Array.isArray(sourceThreadIds) || !sourceThreadIds.every((id) => typeof id === "string"))) return require_json_response.errorResponse("Memory `sourceThreadIds` must be an array of strings when provided", 400);
+	return {
+		content,
+		kind,
+		...typeof scope === "string" ? { scope } : {},
+		...Array.isArray(sourceThreadIds) ? { sourceThreadIds } : {}
+	};
+}
+/**
+* Lists the resolved user's long-term memories via the Intelligence platform.
+*
+* Mirrors {@link handleListThreads}: requires a `CopilotKitIntelligence`
+* runtime, resolves the user with `identifyUser` (never trusting a
+* client-supplied id), and proxies to the platform's `GET /api/memories`
+* with the project API key + resolved user. The `?includeInvalidated=true`
+* query is forwarded so callers can opt into retired rows. The response is
+* the platform's `{ memories }` envelope, which the client memory store
+* consumes directly.
+*/
+async function handleListMemories({ runtime, request }) {
+	if (require_runtime$1.isIntelligenceRuntime(runtime)) try {
+		const includeInvalidated = new URL(request.url).searchParams.get("includeInvalidated") === "true";
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		const data = await runtime.intelligence.listMemories({
+			userId: user.id,
+			...includeInvalidated ? { includeInvalidated: true } : {}
+		});
+		if (data == null || typeof data !== "object" || !Array.isArray(data.memories)) {
+			_copilotkit_shared.logger.error({ data }, "listMemories: platform returned a response without a `memories` array");
+			return require_json_response.errorResponse("Memory platform returned an invalid list response", 502);
+		}
+		return Response.json(data);
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error listing memories");
+		return memoryErrorResponse(error, "Failed to list memories");
+	}
+	return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+}
+/**
+* Mints memory-realtime join credentials (platform `POST
+* /api/memories/subscribe`). Mirrors {@link handleSubscribeToThreads}: requires
+* a `CopilotKitIntelligence` runtime and resolves the user with `identifyUser`
+* (never a client-supplied id). Returns `{ joinToken, joinCode }` — memory needs
+* the `joinCode` here (unlike threads, where it rides the thread-list response)
+* because the client builds the `user_meta:memories:<joinCode>` channel topic
+* from it.
+*/
+async function handleSubscribeToMemories({ runtime, request }) {
+	if (require_runtime$1.isIntelligenceRuntime(runtime)) try {
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		const credentials = await runtime.intelligence.ɵsubscribeToMemories({ userId: user.id });
+		return Response.json({
+			joinToken: credentials.joinToken,
+			joinCode: credentials.joinCode
+		});
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error subscribing to memories");
+		return memoryErrorResponse(error, "Failed to subscribe to memories");
+	}
+	return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+}
+/**
+* Creates a memory for the resolved user (platform `POST /api/memories`).
+* Identity comes from `identifyUser`, never the request body. Returns 201
+* with the stored memory (the client store applies it server-authoritatively).
+*/
+async function handleCreateMemory({ runtime, request }) {
+	if (!require_runtime$1.isIntelligenceRuntime(runtime)) return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+	try {
+		const body = await parseJsonBody(request);
+		if (require_json_response.isHandlerResponse(body)) return body;
+		const fields = parseMemoryBody(body);
+		if (require_json_response.isHandlerResponse(fields)) return fields;
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		const data = await runtime.intelligence.createMemory({
+			userId: user.id,
+			...fields
+		});
+		return Response.json(data, { status: 201 });
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error creating memory");
+		return memoryErrorResponse(error, "Failed to create memory");
+	}
+}
+/**
+* Supersedes a memory (platform `PATCH /api/memories/:id`): retires `:id` and
+* inserts the new content atomically; the response carries `retiredId`.
+*/
+async function handleUpdateMemory({ runtime, request, memoryId }) {
+	if (!require_runtime$1.isIntelligenceRuntime(runtime)) return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+	try {
+		const body = await parseJsonBody(request);
+		if (require_json_response.isHandlerResponse(body)) return body;
+		const fields = parseMemoryBody(body);
+		if (require_json_response.isHandlerResponse(fields)) return fields;
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		const data = await runtime.intelligence.updateMemory({
+			userId: user.id,
+			id: memoryId,
+			...fields
+		});
+		return Response.json(data);
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error updating memory");
+		return memoryErrorResponse(error, "Failed to update memory");
+	}
+}
+/**
+* Retires (forgets) a memory (platform `DELETE /api/memories/:id`). Non-lossy
+* on the platform side; returns 204.
+*/
+async function handleRemoveMemory({ runtime, request, memoryId }) {
+	if (!require_runtime$1.isIntelligenceRuntime(runtime)) return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+	try {
+		const user = await require_resolve_intelligence_user.resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (require_json_response.isHandlerResponse(user)) return user;
+		await runtime.intelligence.removeMemory({
+			userId: user.id,
+			id: memoryId
+		});
+		return new Response(null, { status: 204 });
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error removing memory");
+		return memoryErrorResponse(error, "Failed to remove memory");
+	}
+}
+
+//#endregion
+exports.handleCreateMemory = handleCreateMemory;
+exports.handleListMemories = handleListMemories;
+exports.handleRemoveMemory = handleRemoveMemory;
+exports.handleSubscribeToMemories = handleSubscribeToMemories;
+exports.handleUpdateMemory = handleUpdateMemory;
+//# sourceMappingURL=memories.cjs.map

package/dist/v2/runtime/handlers/intelligence/memories.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memories.cjs","names":["PlatformRequestError","errorResponse","isIntelligenceRuntime","resolveIntelligenceUser","isHandlerResponse"],"sources":["../../../../../src/v2/runtime/handlers/intelligence/memories.ts"],"sourcesContent":["import type { CopilotRuntimeLike } from \"../../core/runtime\";\nimport { isIntelligenceRuntime } from \"../../core/runtime\";\nimport { logger } from \"@copilotkit/shared\";\nimport { errorResponse, isHandlerResponse } from \"../shared/json-response\";\nimport { resolveIntelligenceUser } from \"../shared/resolve-intelligence-user\";\nimport { PlatformRequestError } from \"../../intelligence-platform/client\";\n\ninterface MemoriesHandlerParams {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n}\n\ninterface MemoryMutationParams extends MemoriesHandlerParams {\n  memoryId: string;\n}\n\nconst MISSING_INTELLIGENCE_MESSAGE =\n  \"Missing CopilotKitIntelligence configuration. Memory operations require a CopilotKitIntelligence instance to be provided in CopilotRuntime options.\";\n\n/** Allowed `kind` vocabulary the platform's memory endpoints accept. */\nconst MEMORY_KINDS: ReadonlySet<string> = new Set([\n  \"topical\",\n  \"episodic\",\n  \"operational\",\n]);\n/** Allowed `scope` vocabulary the platform's memory endpoints accept. */\nconst MEMORY_SCOPES: ReadonlySet<string> = new Set([\"user\", \"project\"]);\n\n/**\n * Maps a thrown error to a `Response`.\n *\n * For a {@link PlatformRequestError}, forward only client-actionable **4xx**\n * statuses verbatim (e.g. 404 missing/wrong-scope memory, 409 conflict, 422\n * unprocessable) so a `useMemories` consumer can branch on them — a flat 500\n * would erase that distinction. A platform **5xx** (or any non-4xx / malformed\n * status) means the runtime is healthy but its dependency failed, so it surfaces\n * as `502 Bad Gateway` rather than echoing the upstream status as if the runtime\n * itself broke — and this also avoids a `new Response(..., { status })`\n * `RangeError` on an out-of-range status. Non-platform throws stay 500.\n */\nfunction memoryErrorResponse(error: unknown, message: string): Response {\n  if (error instanceof PlatformRequestError) {\n    const { status } = error;\n    if (Number.isInteger(status) && status >= 400 && status <= 499) {\n      return errorResponse(message, status);\n    }\n    return errorResponse(message, 502);\n  }\n  return errorResponse(message, 500);\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 memory request body\");\n    return errorResponse(\"Invalid request body\", 400);\n  }\n}\n\n/**\n * Extracts and validates the create/supersede body fields the platform's\n * memory endpoints require. Returns a `Response` (400) on invalid input.\n */\nfunction parseMemoryBody(body: Record<string, unknown>):\n  | {\n      content: string;\n      kind: string;\n      scope?: string;\n      sourceThreadIds?: string[];\n    }\n  | Response {\n  const { content, kind, scope, sourceThreadIds } = body;\n  if (typeof content !== \"string\" || typeof kind !== \"string\") {\n    return errorResponse(\"Memory requires string `content` and `kind`\", 400);\n  }\n  // `kind` must be one of the platform's known kinds. Reject an out-of-vocabulary\n  // value here rather than forwarding it for the platform to reject.\n  if (!MEMORY_KINDS.has(kind)) {\n    return errorResponse(\n      \"Memory `kind` must be one of: topical, episodic, operational\",\n      400,\n    );\n  }\n  // `scope` is optional: when omitted the platform applies its default\n  // (`\"user\"`). Only reject a present-but-wrong-typed scope.\n  if (scope !== undefined && typeof scope !== \"string\") {\n    return errorResponse(\"Memory `scope` must be a string when provided\", 400);\n  }\n  // When `scope` is present, it must be one of the known scopes.\n  if (typeof scope === \"string\" && !MEMORY_SCOPES.has(scope)) {\n    return errorResponse(\"Memory `scope` must be one of: user, project\", 400);\n  }\n  // `sourceThreadIds` is optional, but when present it must be a string array.\n  // Validate every element so non-string ids are not forwarded to the platform.\n  if (\n    sourceThreadIds !== undefined &&\n    (!Array.isArray(sourceThreadIds) ||\n      !sourceThreadIds.every((id) => typeof id === \"string\"))\n  ) {\n    return errorResponse(\n      \"Memory `sourceThreadIds` must be an array of strings when provided\",\n      400,\n    );\n  }\n  return {\n    content,\n    kind,\n    ...(typeof scope === \"string\" ? { scope } : {}),\n    ...(Array.isArray(sourceThreadIds)\n      ? { sourceThreadIds: sourceThreadIds as string[] }\n      : {}),\n    // `sourceThreadIds` elements are validated as strings above; the cast is safe.\n  };\n}\n\n/**\n * Lists the resolved user's long-term memories via the Intelligence platform.\n *\n * Mirrors {@link handleListThreads}: requires a `CopilotKitIntelligence`\n * runtime, resolves the user with `identifyUser` (never trusting a\n * client-supplied id), and proxies to the platform's `GET /api/memories`\n * with the project API key + resolved user. The `?includeInvalidated=true`\n * query is forwarded so callers can opt into retired rows. The response is\n * the platform's `{ memories }` envelope, which the client memory store\n * consumes directly.\n */\nexport async function handleListMemories({\n  runtime,\n  request,\n}: MemoriesHandlerParams): Promise<Response> {\n  if (isIntelligenceRuntime(runtime)) {\n    try {\n      const url = new URL(request.url);\n      const includeInvalidated =\n        url.searchParams.get(\"includeInvalidated\") === \"true\";\n\n      const user = await resolveIntelligenceUser({ runtime, request });\n      if (isHandlerResponse(user)) return user;\n\n      const data = await runtime.intelligence.listMemories({\n        userId: user.id,\n        ...(includeInvalidated ? { includeInvalidated: true } : {}),\n      });\n\n      // The client memory store consumes the `{ memories: [...] }` envelope\n      // directly. Assert the shape before forwarding so a platform contract\n      // violation surfaces as a clear 502 (the runtime is healthy but its\n      // dependency returned the wrong shape) instead of a 200 the client will\n      // choke on.\n      if (\n        data == null ||\n        typeof data !== \"object\" ||\n        !Array.isArray((data as { memories?: unknown }).memories)\n      ) {\n        logger.error(\n          { data },\n          \"listMemories: platform returned a response without a `memories` array\",\n        );\n        return errorResponse(\n          \"Memory platform returned an invalid list response\",\n          502,\n        );\n      }\n\n      return Response.json(data);\n    } catch (error) {\n      logger.error({ err: error }, \"Error listing memories\");\n      return memoryErrorResponse(error, \"Failed to list memories\");\n    }\n  }\n\n  return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);\n}\n\n/**\n * Mints memory-realtime join credentials (platform `POST\n * /api/memories/subscribe`). Mirrors {@link handleSubscribeToThreads}: requires\n * a `CopilotKitIntelligence` runtime and resolves the user with `identifyUser`\n * (never a client-supplied id). Returns `{ joinToken, joinCode }` — memory needs\n * the `joinCode` here (unlike threads, where it rides the thread-list response)\n * because the client builds the `user_meta:memories:<joinCode>` channel topic\n * from it.\n */\nexport async function handleSubscribeToMemories({\n  runtime,\n  request,\n}: MemoriesHandlerParams): Promise<Response> {\n  if (isIntelligenceRuntime(runtime)) {\n    try {\n      const user = await resolveIntelligenceUser({ runtime, request });\n      if (isHandlerResponse(user)) return user;\n\n      const credentials = await runtime.intelligence.ɵsubscribeToMemories({\n        userId: user.id,\n      });\n\n      return Response.json({\n        joinToken: credentials.joinToken,\n        joinCode: credentials.joinCode,\n      });\n    } catch (error) {\n      logger.error({ err: error }, \"Error subscribing to memories\");\n      return memoryErrorResponse(error, \"Failed to subscribe to memories\");\n    }\n  }\n\n  return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);\n}\n\n/**\n * Creates a memory for the resolved user (platform `POST /api/memories`).\n * Identity comes from `identifyUser`, never the request body. Returns 201\n * with the stored memory (the client store applies it server-authoritatively).\n */\nexport async function handleCreateMemory({\n  runtime,\n  request,\n}: MemoriesHandlerParams): Promise<Response> {\n  if (!isIntelligenceRuntime(runtime)) {\n    return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);\n  }\n  try {\n    const body = await parseJsonBody(request);\n    if (isHandlerResponse(body)) return body;\n    const fields = parseMemoryBody(body);\n    if (isHandlerResponse(fields)) return fields;\n\n    const user = await resolveIntelligenceUser({ runtime, request });\n    if (isHandlerResponse(user)) return user;\n\n    const data = await runtime.intelligence.createMemory({\n      userId: user.id,\n      ...fields,\n    });\n    return Response.json(data, { status: 201 });\n  } catch (error) {\n    logger.error({ err: error }, \"Error creating memory\");\n    return memoryErrorResponse(error, \"Failed to create memory\");\n  }\n}\n\n/**\n * Supersedes a memory (platform `PATCH /api/memories/:id`): retires `:id` and\n * inserts the new content atomically; the response carries `retiredId`.\n */\nexport async function handleUpdateMemory({\n  runtime,\n  request,\n  memoryId,\n}: MemoryMutationParams): Promise<Response> {\n  if (!isIntelligenceRuntime(runtime)) {\n    return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);\n  }\n  try {\n    const body = await parseJsonBody(request);\n    if (isHandlerResponse(body)) return body;\n    const fields = parseMemoryBody(body);\n    if (isHandlerResponse(fields)) return fields;\n\n    const user = await resolveIntelligenceUser({ runtime, request });\n    if (isHandlerResponse(user)) return user;\n\n    const data = await runtime.intelligence.updateMemory({\n      userId: user.id,\n      id: memoryId,\n      ...fields,\n    });\n    return Response.json(data);\n  } catch (error) {\n    logger.error({ err: error }, \"Error updating memory\");\n    return memoryErrorResponse(error, \"Failed to update memory\");\n  }\n}\n\n/**\n * Retires (forgets) a memory (platform `DELETE /api/memories/:id`). Non-lossy\n * on the platform side; returns 204.\n */\nexport async function handleRemoveMemory({\n  runtime,\n  request,\n  memoryId,\n}: MemoryMutationParams): Promise<Response> {\n  if (!isIntelligenceRuntime(runtime)) {\n    return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);\n  }\n  try {\n    const user = await resolveIntelligenceUser({ runtime, request });\n    if (isHandlerResponse(user)) return user;\n\n    await runtime.intelligence.removeMemory({ userId: user.id, id: memoryId });\n    return new Response(null, { status: 204 });\n  } catch (error) {\n    logger.error({ err: error }, \"Error removing memory\");\n    return memoryErrorResponse(error, \"Failed to remove memory\");\n  }\n}\n"],"mappings":"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"}