@copilotkit/runtime 1.64.1 → 1.64.2-canary.rc-1

package/dist/v2/runtime/core/runtime.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.mjs","names":["pkg"],"sources":["../../../../src/v2/runtime/core/runtime.ts"],"sourcesContent":["import type {\n  MaybePromise,\n  NonEmptyRecord,\n  RuntimeMode,\n} from \"@copilotkit/shared\";\nimport {\n  RUNTIME_MODE_SSE,\n  RUNTIME_MODE_INTELLIGENCE,\n} from \"@copilotkit/shared\";\nimport { createLicenseChecker } from \"@copilotkit/license-verifier\";\nimport type { LicenseChecker } from \"@copilotkit/license-verifier\";\nimport { resolveDebugConfig } from \"@copilotkit/shared\";\nimport type { ResolvedDebugConfig, DebugConfig } from \"@copilotkit/shared\";\nimport { resolveForwardHeadersPolicy } from \"../handlers/header-utils\";\nimport type {\n  ForwardHeadersConfig,\n  ResolvedForwardHeadersPolicy,\n} from \"../handlers/header-utils\";\nimport type { AbstractAgent } from \"@ag-ui/client\";\nimport type { MCPClientConfig } from \"@ag-ui/mcp-apps-middleware\";\nimport type { A2UIMiddlewareConfig } from \"@ag-ui/a2ui-middleware\";\nimport pkg from \"../../../../package.json\";\nimport type {\n  BeforeRequestMiddleware,\n  AfterRequestMiddleware,\n} from \"./middleware\";\nimport { createLogger } from \"../../../lib/logger\";\nimport type { CopilotRuntimeLogger } from \"../../../lib/logger\";\nimport { logRuntimeTelemetryDisclosure } from \"../../../lib/telemetry-disclosure\";\nimport type { TranscriptionService } from \"../transcription-service/transcription-service\";\nimport { DebugEventBus } from \"./debug-event-bus\";\nimport type { AgentRunner } from \"../runner/agent-runner\";\nimport { InMemoryAgentRunner } from \"../runner/in-memory\";\nimport { IntelligenceAgentRunner } from \"../runner/intelligence\";\nimport type { CopilotKitIntelligence } from \"../intelligence-platform\";\n// Type-only: @copilotkit/channels-core is the pure-ESM type source, so a value import would break this\n// package's CJS output. The channels are validated + activated (wired to delivery\n// transports) by `startChannels` from @copilotkit/channels-intelligence, called\n// by the Channel-listener bootstrap — not here.\nimport type { Channel } from \"@copilotkit/channels-core\";\nimport telemetry from \"../telemetry/telemetry-client\";\n\nexport const VERSION = pkg.version;\n\ninterface BaseCopilotRuntimeMiddlewareOptions {\n  /** If set, middleware only applies to these named agents. Applies to all agents if omitted. */\n  agents?: string[];\n}\n\nexport type McpAppsServerConfig = MCPClientConfig & {\n  /** Agent to bind this server to. If omitted, the server is available to all agents. */\n  agentId?: string;\n};\n\nexport interface McpAppsConfig {\n  /** List of MCP server configurations. */\n  servers: McpAppsServerConfig[];\n}\n\nexport interface OpenGenerativeUIOptions extends BaseCopilotRuntimeMiddlewareOptions {}\n\nexport type OpenGenerativeUIConfig = boolean | OpenGenerativeUIOptions;\n\ninterface CopilotRuntimeMiddlewares {\n  /**\n   * Auto-apply A2UIMiddleware to agents at run time.\n   * Pass an object to enable and customise behaviour, or omit to disable.\n   */\n  a2ui?: BaseCopilotRuntimeMiddlewareOptions &\n    A2UIMiddlewareConfig & {\n      /**\n       * Explicit on/off switch. Omit (or set `true`) to enable; set `false`\n       * to disable A2UI for this runtime while keeping the rest of the config\n       * (e.g. a `schema`/`catalog`) in place. A bare `a2ui: {}` stays enabled\n       * for backwards compatibility.\n       */\n      enabled?: boolean;\n    };\n  /** Auto-apply MCPAppsMiddleware to agents at run time. */\n  mcpApps?: McpAppsConfig;\n  /** Auto-apply OpenGenerativeUIMiddleware to agents at run time. */\n  openGenerativeUI?: OpenGenerativeUIConfig;\n}\n\n/**\n * Context passed to agent factory functions for per-request agent resolution.\n */\nexport interface AgentFactoryContext {\n  /** The incoming HTTP request. */\n  request: Request;\n}\n\n/**\n * A function that dynamically creates agents on a per-request basis.\n * Useful for multi-tenant scenarios or request-scoped agent configuration.\n */\nexport type AgentsFactory = (\n  ctx: AgentFactoryContext,\n) => MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;\n\n/**\n * Agents can be provided as:\n * - A static record of agents\n * - A Promise that resolves to a record of agents\n * - A factory function that receives request context and returns agents (or a Promise of agents)\n */\nexport type AgentsConfig =\n  | MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>\n  | AgentsFactory;\n\n/**\n * Resolve an AgentsConfig value to a concrete record of agents.\n * If the config is a factory function, it is called with the given request context.\n * Otherwise it is awaited directly (static record or Promise).\n */\nexport async function resolveAgents(\n  agents: AgentsConfig,\n  request?: Request,\n): Promise<Record<string, AbstractAgent>> {\n  if (typeof agents === \"function\") {\n    if (!request) {\n      throw new Error(\n        \"Agent factory function requires a request context, but none was provided.\",\n      );\n    }\n    return agents({ request });\n  }\n  return agents;\n}\n\ninterface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {\n  /**\n   * Map of available agents, or a factory function for per-request agent resolution.\n   *\n   * Static record:\n   * ```ts\n   * agents: { support: new SupportAgent(), technical: new TechnicalAgent() }\n   * ```\n   *\n   * Factory function (called per-request):\n   * ```ts\n   * agents: ({ request }) => {\n   *   const tenantId = request.headers.get(\"x-tenant-id\");\n   *   return { default: createAgentForTenant(tenantId) };\n   * }\n   * ```\n   */\n  agents: AgentsConfig;\n  /** Optional transcription service for audio processing. */\n  transcriptionService?: TranscriptionService;\n  /** Optional *before* middleware – callback function or webhook URL. */\n  beforeRequestMiddleware?: BeforeRequestMiddleware;\n  /** Optional *after* middleware – callback function or webhook URL. */\n  afterRequestMiddleware?: AfterRequestMiddleware;\n  /** Signed license token for server-side feature verification. Falls back to COPILOTKIT_LICENSE_TOKEN env var. */\n  licenseToken?: string;\n  /** Enable debug logging for the event pipeline. */\n  debug?: DebugConfig;\n  /**\n   * Policy controlling which inbound HTTP headers are forwarded onto the\n   * outgoing agent call. By default a built-in denylist strips known\n   * infrastructure/proxy/platform headers (`x-forwarded-*`, `x-real-ip`,\n   * `x-vercel-*`, `x-copilotcloud-*`, etc.) while `authorization` and custom\n   * `x-*` application headers continue to forward (#5712). Set\n   * `{ useDefaultDenylist: false }` to restore the previous wide-open behavior.\n   */\n  forwardHeaders?: ForwardHeadersConfig;\n}\n\nexport interface CopilotRuntimeUser {\n  id: string;\n  name: string;\n}\n\nexport type IdentifyUserCallback = (\n  request: Request,\n) => MaybePromise<CopilotRuntimeUser>;\n\nexport interface CopilotSseRuntimeOptions extends BaseCopilotRuntimeOptions {\n  /** The runner to use for running agents in SSE mode. */\n  runner?: AgentRunner;\n  intelligence?: undefined;\n  generateThreadNames?: undefined;\n  /** Intelligence Channels require the Intelligence runtime; not available in SSE mode. */\n  channels?: undefined;\n}\n\nexport interface CopilotIntelligenceRuntimeOptions extends BaseCopilotRuntimeOptions {\n  /** Configures Intelligence mode for durable threads and realtime events. */\n  intelligence: CopilotKitIntelligence;\n  /** Resolves the authenticated user for intelligence requests. */\n  identifyUser: IdentifyUserCallback;\n  /** Auto-generate short names for newly created threads. */\n  generateThreadNames?: boolean;\n  /** Max delay (ms) for WebSocket reconnect backoff. @default 10_000 */\n  maxReconnectMs?: number;\n  /** Max delay (ms) for channel rejoin backoff. @default 30_000 */\n  maxRejoinMs?: number;\n  /** Lock TTL in seconds. Clamped to a maximum of 3600 (1 hour). @default 20 */\n  lockTtlSeconds?: number;\n  /** Custom Redis key prefix for the thread lock. */\n  lockKeyPrefix?: string;\n  /** Interval in seconds at which the runtime renews the thread lock. Clamped to a maximum of 3000 (50 minutes). @default 15 */\n  lockHeartbeatIntervalSeconds?: number;\n  /**\n   * Intelligence Channels declared by this runtime. Each is a\n   * `createChannel({ name })` instance. Only available on the Intelligence runtime\n   * path. Names are validated (required, lowercase kebab-case, unique) and wired\n   * to delivery/egress transports when activated via `startChannels` from\n   * `@copilotkit/channels-intelligence` — not at construction.\n   */\n  channels?: Channel[];\n}\n\nexport type CopilotRuntimeOptions =\n  | CopilotSseRuntimeOptions\n  | CopilotIntelligenceRuntimeOptions;\n\nexport interface CopilotRuntimeLike {\n  agents: CopilotRuntimeOptions[\"agents\"];\n  transcriptionService: CopilotRuntimeOptions[\"transcriptionService\"];\n  beforeRequestMiddleware: CopilotRuntimeOptions[\"beforeRequestMiddleware\"];\n  afterRequestMiddleware: CopilotRuntimeOptions[\"afterRequestMiddleware\"];\n  runner: AgentRunner;\n  a2ui: CopilotRuntimeOptions[\"a2ui\"];\n  mcpApps: CopilotRuntimeOptions[\"mcpApps\"];\n  openGenerativeUI: CopilotRuntimeOptions[\"openGenerativeUI\"];\n  intelligence?: CopilotKitIntelligence;\n  identifyUser?: IdentifyUserCallback;\n  mode: RuntimeMode;\n  licenseChecker?: LicenseChecker;\n  debugEventBus?: DebugEventBus;\n  debug: ResolvedDebugConfig;\n  debugLogger?: CopilotRuntimeLogger;\n  /**\n   * Resolved inbound-header forwarding policy read by the /run and /connect call\n   * sites. Optional on the published interface so an external `CopilotRuntimeLike`\n   * implementor predating this field stays source-compatible (non-breaking minor\n   * release). Concrete runtimes (`BaseCopilotRuntime`) always resolve and set it;\n   * the call sites coalesce a missing value to the default resolved policy\n   * (`resolveForwardHeadersPolicy(undefined)` — default-on denylist).\n   */\n  forwardHeadersPolicy?: ResolvedForwardHeadersPolicy;\n}\n\nexport interface CopilotSseRuntimeLike extends CopilotRuntimeLike {\n  intelligence?: undefined;\n  mode: typeof RUNTIME_MODE_SSE;\n}\n\nexport interface CopilotIntelligenceRuntimeLike extends CopilotRuntimeLike {\n  intelligence: CopilotKitIntelligence;\n  identifyUser: IdentifyUserCallback;\n  generateThreadNames: boolean;\n  lockTtlSeconds: number;\n  lockKeyPrefix?: string;\n  lockHeartbeatIntervalSeconds: number;\n  channels: Channel[];\n  mode: typeof RUNTIME_MODE_INTELLIGENCE;\n}\n\nabstract class BaseCopilotRuntime implements CopilotRuntimeLike {\n  public agents: CopilotRuntimeOptions[\"agents\"];\n  public transcriptionService: CopilotRuntimeOptions[\"transcriptionService\"];\n  public beforeRequestMiddleware: CopilotRuntimeOptions[\"beforeRequestMiddleware\"];\n  public afterRequestMiddleware: CopilotRuntimeOptions[\"afterRequestMiddleware\"];\n  public runner: AgentRunner;\n  public a2ui: CopilotRuntimeOptions[\"a2ui\"];\n  public mcpApps: CopilotRuntimeOptions[\"mcpApps\"];\n  public openGenerativeUI: CopilotRuntimeOptions[\"openGenerativeUI\"];\n  public licenseChecker?: LicenseChecker;\n  public readonly debugEventBus?: DebugEventBus;\n  public debug: ResolvedDebugConfig;\n  public debugLogger?: CopilotRuntimeLogger;\n  public readonly forwardHeadersPolicy: ResolvedForwardHeadersPolicy;\n\n  /**\n   * License token resolved once with the env fallback, so telemetry\n   * attribution (below) and subclass feature gating\n   * (CopilotIntelligenceRuntime's licenseChecker) read the exact same value\n   * instead of each re-applying `?? COPILOTKIT_LICENSE_TOKEN`.\n   */\n  protected readonly resolvedLicenseToken?: string;\n\n  abstract readonly intelligence?: CopilotKitIntelligence;\n  abstract readonly mode: RuntimeMode;\n\n  constructor(options: BaseCopilotRuntimeOptions, runner: AgentRunner) {\n    logRuntimeTelemetryDisclosure();\n\n    const {\n      agents,\n      transcriptionService,\n      beforeRequestMiddleware,\n      afterRequestMiddleware,\n      a2ui,\n      mcpApps,\n      openGenerativeUI,\n    } = options;\n\n    this.agents = agents;\n    this.transcriptionService = transcriptionService;\n    this.beforeRequestMiddleware = beforeRequestMiddleware;\n    this.afterRequestMiddleware = afterRequestMiddleware;\n    this.a2ui = a2ui || undefined;\n    this.mcpApps = mcpApps;\n    this.openGenerativeUI = openGenerativeUI;\n    this.runner = runner;\n\n    // Resolve the license token once (matching the license-verifier's env\n    // fallback) so telemetry attribution and subclass feature gating share\n    // one value.\n    this.resolvedLicenseToken =\n      options.licenseToken ?? process.env.COPILOTKIT_LICENSE_TOKEN;\n\n    // Attribute telemetry to the licensed customer for *every* runtime mode.\n    // Done in the shared base (not the subclasses) so SSE and Intelligence\n    // runtimes behave identically — previously only CopilotIntelligenceRuntime\n    // set this, so self-hosted SSE users never got a telemetry_id on their\n    // runtime events even with a license token configured.\n    if (this.resolvedLicenseToken) {\n      telemetry.setLicenseToken(this.resolvedLicenseToken);\n    }\n\n    if (process.env.NODE_ENV !== \"production\") {\n      this.debugEventBus = new DebugEventBus();\n    }\n    // Resolve the inbound-header forwarding policy once (mirroring the\n    // `debug` → `ResolvedDebugConfig` resolve-once above) so both the /run and\n    // /connect call sites read the exact same resolved policy off the runtime\n    // and can never diverge.\n    this.forwardHeadersPolicy = resolveForwardHeadersPolicy(\n      options.forwardHeaders,\n    );\n    this.debug = resolveDebugConfig(options.debug);\n    if (this.debug.enabled) {\n      this.debugLogger = createLogger({\n        level: \"debug\",\n        component: \"copilotkit-debug\",\n      });\n    }\n  }\n}\n\nexport class CopilotSseRuntime\n  extends BaseCopilotRuntime\n  implements CopilotSseRuntimeLike\n{\n  readonly intelligence = undefined;\n  readonly mode = RUNTIME_MODE_SSE;\n\n  constructor(options: CopilotSseRuntimeOptions) {\n    // Runtime guard mirroring the discriminated-union type: the SSE runtime has\n    // no Intelligence delivery path, so `channels` cannot be honored here. The\n    // type forbids it, but a JS / `as any` caller passing `{ agents, channels }`\n    // would otherwise land here and have `channels` silently dropped — fail\n    // loud instead.\n    const channels = (options as { channels?: unknown[] }).channels;\n    if (Array.isArray(channels) && channels.length > 0) {\n      throw new Error(\n        \"`channels` requires the Intelligence runtime (pass `intelligence`); \" +\n          \"Intelligence Channels are not available in SSE mode.\",\n      );\n    }\n    super(options, options.runner ?? new InMemoryAgentRunner());\n  }\n}\n\nexport class CopilotIntelligenceRuntime\n  extends BaseCopilotRuntime\n  implements CopilotIntelligenceRuntimeLike\n{\n  readonly intelligence: CopilotKitIntelligence;\n  readonly identifyUser: IdentifyUserCallback;\n  readonly generateThreadNames: boolean;\n  readonly lockTtlSeconds: number;\n  readonly lockKeyPrefix?: string;\n  readonly lockHeartbeatIntervalSeconds: number;\n  readonly channels: Channel[];\n  readonly mode = RUNTIME_MODE_INTELLIGENCE;\n\n  /** Maximum allowed lock TTL in seconds (1 hour). */\n  static readonly MAX_LOCK_TTL_SECONDS = 3_600;\n  /** Maximum allowed heartbeat interval in seconds (50 minutes). */\n  static readonly MAX_HEARTBEAT_INTERVAL_SECONDS = 3_000;\n\n  constructor(options: CopilotIntelligenceRuntimeOptions) {\n    super(\n      options,\n      new IntelligenceAgentRunner({\n        url: options.intelligence.ɵgetRunnerWsUrl(),\n        authToken: options.intelligence.ɵgetRunnerAuthToken(),\n        maxReconnectMs: options.maxReconnectMs,\n        maxRejoinMs: options.maxRejoinMs,\n      }),\n    );\n    this.intelligence = options.intelligence;\n    this.identifyUser = options.identifyUser;\n    this.generateThreadNames = options.generateThreadNames ?? true;\n    // Telemetry attribution is handled by the base constructor for all modes;\n    // here we only need the token for feature gating. Reuse the base-resolved\n    // value so gating and attribution can never disagree.\n    this.licenseChecker = createLicenseChecker(this.resolvedLicenseToken);\n    this.lockTtlSeconds = Math.min(\n      options.lockTtlSeconds ?? 20,\n      CopilotIntelligenceRuntime.MAX_LOCK_TTL_SECONDS,\n    );\n    this.lockKeyPrefix = options.lockKeyPrefix;\n    this.lockHeartbeatIntervalSeconds = Math.min(\n      options.lockHeartbeatIntervalSeconds ?? 15,\n      CopilotIntelligenceRuntime.MAX_HEARTBEAT_INTERVAL_SECONDS,\n    );\n    // Declared Intelligence Channels. Lowercase kebab-case name-shape validation\n    // (`assertValidChannelNames`) lives in the channels-intelligence launcher —\n    // it can't run here because it's a value import from the pure-ESM\n    // `@copilotkit/channels-intelligence`, which this CJS package must not pull in.\n    // Name UNIQUENESS across declared Channels is enforced by\n    // `ChannelManager.activate()`, not the launcher: the managed path activates\n    // one Channel per launcher call, so the launcher never sees the full set.\n    // Fail fast on the most common misconfiguration (a missing name) right here\n    // at construction, though, rather than only at activation.\n    this.channels = options.channels ?? [];\n    for (const c of this.channels) {\n      if (!c.name) {\n        throw new Error(\n          \"Intelligence Channel is missing a `name` — pass createChannel({ name }) for each Channel in `channels`\",\n        );\n      }\n    }\n  }\n}\n\nfunction hasIntelligenceOptions(\n  options: CopilotRuntimeOptions,\n): options is CopilotIntelligenceRuntimeOptions {\n  return \"intelligence\" in options && !!options.intelligence;\n}\n\nexport function isIntelligenceRuntime(\n  runtime: CopilotRuntimeLike,\n): runtime is CopilotIntelligenceRuntimeLike {\n  return runtime.mode === RUNTIME_MODE_INTELLIGENCE && !!runtime.intelligence;\n}\n\n/**\n * Single source of truth for \"is A2UI on for this runtime?\". Both the run path\n * (which applies `A2UIMiddleware`) and the `/info` response (which tells the\n * client whether to mount the A2UI renderer + catalog context) MUST go through\n * this, so they can never disagree — the divergence between them was the root\n * of CopilotKit/CopilotKit#5369.\n *\n * Backwards compatible: any config object is enabled (matching the historical\n * `!!runtime.a2ui`); only an explicit `enabled: false` turns it off.\n */\nexport function isA2UIEnabled(\n  a2ui: CopilotRuntimeOptions[\"a2ui\"],\n): a2ui is NonNullable<CopilotRuntimeOptions[\"a2ui\"]> {\n  return !!a2ui && a2ui.enabled !== false;\n}\n\n/**\n * Compile-time phantom brand marking a {@link CopilotRuntime} that was\n * constructed with at least one declared Intelligence Channel. It has no runtime\n * representation — the shim never sets this property; it exists purely so\n * `createCopilotRuntimeHandler` can tell, at the type level, that the resulting\n * handler will carry a non-optional `.channels` control surface.\n */\nexport interface RuntimeWithDeclaredChannels {\n  /**\n   * @internal Phantom brand key. Never present at runtime; do not read or set.\n   */\n  readonly __copilotkitChannelsDeclared: true;\n}\n\n/**\n * Instance shape of the {@link CopilotRuntime} compatibility shim. Extends\n * {@link CopilotRuntimeLike} with the Intelligence-only accessors the shim\n * surfaces (all `undefined` in SSE mode). Declared explicitly so the exported\n * `CopilotRuntime` name resolves as a type as well as a value.\n */\nexport interface CopilotRuntime extends CopilotRuntimeLike {\n  /** Auto-generate short thread names; `undefined` in SSE mode. */\n  generateThreadNames?: boolean;\n  /** Thread lock TTL in seconds; `undefined` in SSE mode. */\n  lockTtlSeconds?: number;\n  /** Custom Redis key prefix for the thread lock; `undefined` in SSE mode. */\n  lockKeyPrefix?: string;\n  /** Thread lock heartbeat interval in seconds; `undefined` in SSE mode. */\n  lockHeartbeatIntervalSeconds?: number;\n  /** Declared Intelligence Channels; `undefined` in SSE mode. */\n  channels?: Channel[];\n}\n\n/**\n * Constructor type for the {@link CopilotRuntime} compatibility shim.\n *\n * The first overload fires when the caller passes `intelligence` together with a\n * non-empty `channels` tuple: it returns a {@link RuntimeWithDeclaredChannels}-\n * branded runtime, which `createCopilotRuntimeHandler` maps to a handler whose\n * `.channels` is non-optional. Every other configuration (SSE, or Intelligence\n * without channels, or an empty `channels: []`) falls through to the second\n * overload and stays unbranded, so its handler keeps `.channels` optional.\n *\n * A class constructor cannot vary its return type across overloads (it is pinned\n * to the instance type), so the branding lives on this construct-signature\n * interface instead of on the class itself.\n */\nexport interface CopilotRuntimeConstructor {\n  new (\n    options: Omit<CopilotIntelligenceRuntimeOptions, \"channels\"> & {\n      channels: readonly [Channel, ...Channel[]];\n    },\n  ): CopilotRuntime & RuntimeWithDeclaredChannels;\n  new (options: CopilotRuntimeOptions): CopilotRuntime;\n}\n\n/**\n * Compatibility shim that preserves the legacy `CopilotRuntime` entrypoint.\n * New code should prefer `CopilotSseRuntime` or `CopilotIntelligenceRuntime`.\n *\n * Exported to consumers as the {@link CopilotRuntime} value (typed as\n * {@link CopilotRuntimeConstructor}) rather than as a class, so that the\n * channel-presence brand can flow from construction into the handler type.\n */\nclass CopilotRuntimeShim implements CopilotRuntime {\n  private delegate: CopilotRuntimeLike;\n\n  constructor(options: CopilotRuntimeOptions) {\n    this.delegate = hasIntelligenceOptions(options)\n      ? new CopilotIntelligenceRuntime(options)\n      : new CopilotSseRuntime(options);\n  }\n\n  get agents(): CopilotRuntimeOptions[\"agents\"] {\n    return this.delegate.agents;\n  }\n\n  get transcriptionService(): CopilotRuntimeOptions[\"transcriptionService\"] {\n    return this.delegate.transcriptionService;\n  }\n\n  get beforeRequestMiddleware(): CopilotRuntimeOptions[\"beforeRequestMiddleware\"] {\n    return this.delegate.beforeRequestMiddleware;\n  }\n\n  get afterRequestMiddleware(): CopilotRuntimeOptions[\"afterRequestMiddleware\"] {\n    return this.delegate.afterRequestMiddleware;\n  }\n\n  get runner(): AgentRunner {\n    return this.delegate.runner;\n  }\n\n  get a2ui(): CopilotRuntimeOptions[\"a2ui\"] {\n    return this.delegate.a2ui;\n  }\n\n  get mcpApps(): CopilotRuntimeOptions[\"mcpApps\"] {\n    return this.delegate.mcpApps;\n  }\n\n  get openGenerativeUI(): CopilotRuntimeOptions[\"openGenerativeUI\"] {\n    return this.delegate.openGenerativeUI;\n  }\n\n  get intelligence(): CopilotKitIntelligence | undefined {\n    return this.delegate.intelligence;\n  }\n\n  get generateThreadNames(): boolean | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.generateThreadNames\n      : undefined;\n  }\n\n  get identifyUser(): IdentifyUserCallback | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.identifyUser\n      : undefined;\n  }\n\n  get lockTtlSeconds(): number | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockTtlSeconds\n      : undefined;\n  }\n\n  get lockKeyPrefix(): string | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockKeyPrefix\n      : undefined;\n  }\n\n  get lockHeartbeatIntervalSeconds(): number | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockHeartbeatIntervalSeconds\n      : undefined;\n  }\n\n  get channels(): Channel[] | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.channels\n      : undefined;\n  }\n\n  get mode(): RuntimeMode {\n    return this.delegate.mode;\n  }\n\n  get licenseChecker() {\n    return this.delegate.licenseChecker;\n  }\n\n  get debugEventBus() {\n    return this.delegate.debugEventBus;\n  }\n\n  get debug(): ResolvedDebugConfig {\n    return this.delegate.debug;\n  }\n\n  get debugLogger(): CopilotRuntimeLogger | undefined {\n    return this.delegate.debugLogger;\n  }\n\n  get forwardHeadersPolicy(): ResolvedForwardHeadersPolicy {\n    return this.delegate.forwardHeadersPolicy;\n  }\n}\n\n/**\n * The public `CopilotRuntime` constructor. Backed by {@link CopilotRuntimeShim}\n * but typed as {@link CopilotRuntimeConstructor} so that constructing with a\n * non-empty `channels` array yields a {@link RuntimeWithDeclaredChannels}-branded\n * runtime type.\n *\n * The `as unknown as` cast is required (not dishonest widening): the brand is a\n * phantom, compile-time-only marker with no runtime representation, so the shim\n * instances legitimately do not carry the brand property. Behavior is identical\n * to the former `class CopilotRuntime` — this only refines the static type.\n */\nexport const CopilotRuntime: CopilotRuntimeConstructor =\n  CopilotRuntimeShim as unknown as CopilotRuntimeConstructor;\n"],"mappings":"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"}
+{"version":3,"file":"runtime.mjs","names":["pkg"],"sources":["../../../../src/v2/runtime/core/runtime.ts"],"sourcesContent":["import type {\n  MaybePromise,\n  NonEmptyRecord,\n  RuntimeMode,\n} from \"@copilotkit/shared\";\nimport {\n  RUNTIME_MODE_SSE,\n  RUNTIME_MODE_INTELLIGENCE,\n} from \"@copilotkit/shared\";\nimport { createLicenseChecker } from \"@copilotkit/license-verifier\";\nimport type { LicenseChecker } from \"@copilotkit/license-verifier\";\nimport { resolveDebugConfig } from \"@copilotkit/shared\";\nimport type { ResolvedDebugConfig, DebugConfig } from \"@copilotkit/shared\";\nimport { resolveForwardHeadersPolicy } from \"../handlers/header-utils\";\nimport type {\n  ForwardHeadersConfig,\n  ResolvedForwardHeadersPolicy,\n} from \"../handlers/header-utils\";\nimport type { AbstractAgent } from \"@ag-ui/client\";\nimport type { MCPClientConfig } from \"@ag-ui/mcp-apps-middleware\";\nimport type { A2UIMiddlewareConfig } from \"@ag-ui/a2ui-middleware\";\nimport pkg from \"../../../../package.json\";\nimport type {\n  BeforeRequestMiddleware,\n  AfterRequestMiddleware,\n} from \"./middleware\";\nimport { createLogger } from \"../../../lib/logger\";\nimport type { CopilotRuntimeLogger } from \"../../../lib/logger\";\nimport { logRuntimeTelemetryDisclosure } from \"../../../lib/telemetry-disclosure\";\nimport type { TranscriptionService } from \"../transcription-service/transcription-service\";\nimport { DebugEventBus } from \"./debug-event-bus\";\nimport type { AgentRunner } from \"../runner/agent-runner\";\nimport { InMemoryAgentRunner } from \"../runner/in-memory\";\nimport { IntelligenceAgentRunner } from \"../runner/intelligence\";\nimport type { CopilotKitIntelligence } from \"../intelligence-platform\";\n// Type-only: @copilotkit/channels-core is the pure-ESM type source, so a value import would break this\n// package's CJS output. The channels are validated + activated (wired to delivery\n// transports) by `startChannels` from @copilotkit/channels-intelligence, called\n// by the Channel-listener bootstrap — not here.\nimport type { Channel } from \"@copilotkit/channels-core\";\nimport telemetry from \"../telemetry/telemetry-client\";\n\nexport const VERSION = pkg.version;\n\ninterface BaseCopilotRuntimeMiddlewareOptions {\n  /** If set, middleware only applies to these named agents. Applies to all agents if omitted. */\n  agents?: string[];\n}\n\nexport type McpAppsServerConfig = MCPClientConfig & {\n  /** Agent to bind this server to. If omitted, the server is available to all agents. */\n  agentId?: string;\n};\n\nexport interface McpAppsConfig {\n  /** List of MCP server configurations. */\n  servers: McpAppsServerConfig[];\n}\n\nexport interface OpenGenerativeUIOptions extends BaseCopilotRuntimeMiddlewareOptions {}\n\nexport type OpenGenerativeUIConfig = boolean | OpenGenerativeUIOptions;\n\ninterface CopilotRuntimeMiddlewares {\n  /**\n   * Auto-apply A2UIMiddleware to agents at run time.\n   * Pass an object to enable and customise behaviour, or omit to disable.\n   */\n  a2ui?: BaseCopilotRuntimeMiddlewareOptions &\n    A2UIMiddlewareConfig & {\n      /**\n       * Explicit on/off switch. Omit (or set `true`) to enable; set `false`\n       * to disable A2UI for this runtime while keeping the rest of the config\n       * (e.g. a `schema`/`catalog`) in place. A bare `a2ui: {}` stays enabled\n       * for backwards compatibility.\n       */\n      enabled?: boolean;\n    };\n  /** Auto-apply MCPAppsMiddleware to agents at run time. */\n  mcpApps?: McpAppsConfig;\n  /** Auto-apply OpenGenerativeUIMiddleware to agents at run time. */\n  openGenerativeUI?: OpenGenerativeUIConfig;\n}\n\n/**\n * Context passed to agent factory functions for per-request agent resolution.\n */\nexport interface AgentFactoryContext {\n  /** The incoming HTTP request. */\n  request: Request;\n}\n\n/**\n * A function that dynamically creates agents on a per-request basis.\n * Useful for multi-tenant scenarios or request-scoped agent configuration.\n */\nexport type AgentsFactory = (\n  ctx: AgentFactoryContext,\n) => MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>;\n\n/**\n * Agents can be provided as:\n * - A static record of agents\n * - A Promise that resolves to a record of agents\n * - A factory function that receives request context and returns agents (or a Promise of agents)\n */\nexport type AgentsConfig =\n  | MaybePromise<NonEmptyRecord<Record<string, AbstractAgent>>>\n  | AgentsFactory;\n\n/**\n * Resolve an AgentsConfig value to a concrete record of agents.\n * If the config is a factory function, it is called with the given request context.\n * Otherwise it is awaited directly (static record or Promise).\n */\nexport async function resolveAgents(\n  agents: AgentsConfig,\n  request?: Request,\n): Promise<Record<string, AbstractAgent>> {\n  if (typeof agents === \"function\") {\n    if (!request) {\n      throw new Error(\n        \"Agent factory function requires a request context, but none was provided.\",\n      );\n    }\n    return agents({ request });\n  }\n  return agents;\n}\n\ninterface BaseCopilotRuntimeOptions extends CopilotRuntimeMiddlewares {\n  /**\n   * Map of available agents, or a factory function for per-request agent resolution.\n   *\n   * Static record:\n   * ```ts\n   * agents: { support: new SupportAgent(), technical: new TechnicalAgent() }\n   * ```\n   *\n   * Factory function (called per-request):\n   * ```ts\n   * agents: ({ request }) => {\n   *   const tenantId = request.headers.get(\"x-tenant-id\");\n   *   return { default: createAgentForTenant(tenantId) };\n   * }\n   * ```\n   */\n  agents: AgentsConfig;\n  /** Optional transcription service for audio processing. */\n  transcriptionService?: TranscriptionService;\n  /** Optional *before* middleware – callback function or webhook URL. */\n  beforeRequestMiddleware?: BeforeRequestMiddleware;\n  /** Optional *after* middleware – callback function or webhook URL. */\n  afterRequestMiddleware?: AfterRequestMiddleware;\n  /** Signed license token for server-side feature verification. Falls back to COPILOTKIT_LICENSE_TOKEN env var. */\n  licenseToken?: string;\n  /** Enable debug logging for the event pipeline. */\n  debug?: DebugConfig;\n  /**\n   * Policy controlling which inbound HTTP headers are forwarded onto the\n   * outgoing agent call. By default a built-in denylist strips known\n   * infrastructure/proxy/platform headers (`x-forwarded-*`, `x-real-ip`,\n   * `x-vercel-*`, `x-copilotcloud-*`, etc.) while `authorization` and custom\n   * `x-*` application headers continue to forward (#5712). Set\n   * `{ useDefaultDenylist: false }` to restore the previous wide-open behavior.\n   */\n  forwardHeaders?: ForwardHeadersConfig;\n  /**\n   * Opt-in flag exposing the client-facing memory proxy routes\n   * (`/memories`, `/memories/recall`, `/memories/subscribe`, `/memories/:id`).\n   *\n   * Defaults to `false` — a **secure default**. When off, every `/memories/*`\n   * request 404s as if the route did not exist, so an un-opted-in deployment\n   * reveals nothing about memory even when Intelligence is configured. This does\n   * NOT affect the agent's own server-side memory tooling (`recall_memory` runs\n   * via the Intelligence MCP path, separate from this client REST proxy).\n   *\n   * Flip to `true` to power a client memory inspector (e.g. the dev console's\n   * Memory tab). Existing Intelligence deployments relying on the previously\n   * always-on Learning tab must set this to restore it.\n   */\n  exposeMemoryRoutes?: boolean;\n}\n\nexport interface CopilotRuntimeUser {\n  id: string;\n  name: string;\n}\n\nexport type IdentifyUserCallback = (\n  request: Request,\n) => MaybePromise<CopilotRuntimeUser>;\n\nexport interface CopilotSseRuntimeOptions extends BaseCopilotRuntimeOptions {\n  /** The runner to use for running agents in SSE mode. */\n  runner?: AgentRunner;\n  intelligence?: undefined;\n  generateThreadNames?: undefined;\n  /** Intelligence Channels require the Intelligence runtime; not available in SSE mode. */\n  channels?: undefined;\n}\n\nexport interface CopilotIntelligenceRuntimeOptions extends BaseCopilotRuntimeOptions {\n  /** Configures Intelligence mode for durable threads and realtime events. */\n  intelligence: CopilotKitIntelligence;\n  /** Resolves the authenticated user for intelligence requests. */\n  identifyUser: IdentifyUserCallback;\n  /** Auto-generate short names for newly created threads. */\n  generateThreadNames?: boolean;\n  /** Max delay (ms) for WebSocket reconnect backoff. @default 10_000 */\n  maxReconnectMs?: number;\n  /** Max delay (ms) for channel rejoin backoff. @default 30_000 */\n  maxRejoinMs?: number;\n  /** Lock TTL in seconds. Clamped to a maximum of 3600 (1 hour). @default 20 */\n  lockTtlSeconds?: number;\n  /** Custom Redis key prefix for the thread lock. */\n  lockKeyPrefix?: string;\n  /** Interval in seconds at which the runtime renews the thread lock. Clamped to a maximum of 3000 (50 minutes). @default 15 */\n  lockHeartbeatIntervalSeconds?: number;\n  /**\n   * Intelligence Channels declared by this runtime. Each is a\n   * `createChannel({ name })` instance. Only available on the Intelligence runtime\n   * path. Names are validated (required, lowercase kebab-case, unique) and wired\n   * to delivery/egress transports when activated via `startChannels` from\n   * `@copilotkit/channels-intelligence` — not at construction.\n   */\n  channels?: Channel[];\n}\n\nexport type CopilotRuntimeOptions =\n  | CopilotSseRuntimeOptions\n  | CopilotIntelligenceRuntimeOptions;\n\nexport interface CopilotRuntimeLike {\n  agents: CopilotRuntimeOptions[\"agents\"];\n  transcriptionService: CopilotRuntimeOptions[\"transcriptionService\"];\n  beforeRequestMiddleware: CopilotRuntimeOptions[\"beforeRequestMiddleware\"];\n  afterRequestMiddleware: CopilotRuntimeOptions[\"afterRequestMiddleware\"];\n  runner: AgentRunner;\n  a2ui: CopilotRuntimeOptions[\"a2ui\"];\n  mcpApps: CopilotRuntimeOptions[\"mcpApps\"];\n  openGenerativeUI: CopilotRuntimeOptions[\"openGenerativeUI\"];\n  intelligence?: CopilotKitIntelligence;\n  identifyUser?: IdentifyUserCallback;\n  mode: RuntimeMode;\n  licenseChecker?: LicenseChecker;\n  debugEventBus?: DebugEventBus;\n  debug: ResolvedDebugConfig;\n  debugLogger?: CopilotRuntimeLogger;\n  /**\n   * Resolved inbound-header forwarding policy read by the /run and /connect call\n   * sites. Optional on the published interface so an external `CopilotRuntimeLike`\n   * implementor predating this field stays source-compatible (non-breaking minor\n   * release). Concrete runtimes (`BaseCopilotRuntime`) always resolve and set it;\n   * the call sites coalesce a missing value to the default resolved policy\n   * (`resolveForwardHeadersPolicy(undefined)` — default-on denylist).\n   */\n  forwardHeadersPolicy?: ResolvedForwardHeadersPolicy;\n  /**\n   * Resolved opt-in flag for the client-facing memory proxy routes. Optional on\n   * the published interface so an external `CopilotRuntimeLike` implementor\n   * predating this field stays source-compatible; the dispatcher coalesces a\n   * missing value to `false` (secure default — routes hidden). Concrete runtimes\n   * (`BaseCopilotRuntime`) always resolve and set it.\n   */\n  exposeMemoryRoutes?: boolean;\n}\n\nexport interface CopilotSseRuntimeLike extends CopilotRuntimeLike {\n  intelligence?: undefined;\n  mode: typeof RUNTIME_MODE_SSE;\n}\n\nexport interface CopilotIntelligenceRuntimeLike extends CopilotRuntimeLike {\n  intelligence: CopilotKitIntelligence;\n  identifyUser: IdentifyUserCallback;\n  generateThreadNames: boolean;\n  lockTtlSeconds: number;\n  lockKeyPrefix?: string;\n  lockHeartbeatIntervalSeconds: number;\n  channels: Channel[];\n  mode: typeof RUNTIME_MODE_INTELLIGENCE;\n}\n\nabstract class BaseCopilotRuntime implements CopilotRuntimeLike {\n  public agents: CopilotRuntimeOptions[\"agents\"];\n  public transcriptionService: CopilotRuntimeOptions[\"transcriptionService\"];\n  public beforeRequestMiddleware: CopilotRuntimeOptions[\"beforeRequestMiddleware\"];\n  public afterRequestMiddleware: CopilotRuntimeOptions[\"afterRequestMiddleware\"];\n  public runner: AgentRunner;\n  public a2ui: CopilotRuntimeOptions[\"a2ui\"];\n  public mcpApps: CopilotRuntimeOptions[\"mcpApps\"];\n  public openGenerativeUI: CopilotRuntimeOptions[\"openGenerativeUI\"];\n  public licenseChecker?: LicenseChecker;\n  public readonly debugEventBus?: DebugEventBus;\n  public debug: ResolvedDebugConfig;\n  public debugLogger?: CopilotRuntimeLogger;\n  public readonly forwardHeadersPolicy: ResolvedForwardHeadersPolicy;\n  public readonly exposeMemoryRoutes: boolean;\n\n  /**\n   * License token resolved once with the env fallback, so telemetry\n   * attribution (below) and subclass feature gating\n   * (CopilotIntelligenceRuntime's licenseChecker) read the exact same value\n   * instead of each re-applying `?? COPILOTKIT_LICENSE_TOKEN`.\n   */\n  protected readonly resolvedLicenseToken?: string;\n\n  abstract readonly intelligence?: CopilotKitIntelligence;\n  abstract readonly mode: RuntimeMode;\n\n  constructor(options: BaseCopilotRuntimeOptions, runner: AgentRunner) {\n    logRuntimeTelemetryDisclosure();\n\n    const {\n      agents,\n      transcriptionService,\n      beforeRequestMiddleware,\n      afterRequestMiddleware,\n      a2ui,\n      mcpApps,\n      openGenerativeUI,\n    } = options;\n\n    this.agents = agents;\n    this.transcriptionService = transcriptionService;\n    this.beforeRequestMiddleware = beforeRequestMiddleware;\n    this.afterRequestMiddleware = afterRequestMiddleware;\n    this.a2ui = a2ui || undefined;\n    this.mcpApps = mcpApps;\n    this.openGenerativeUI = openGenerativeUI;\n    this.runner = runner;\n\n    // Resolve the license token once (matching the license-verifier's env\n    // fallback) so telemetry attribution and subclass feature gating share\n    // one value.\n    this.resolvedLicenseToken =\n      options.licenseToken ?? process.env.COPILOTKIT_LICENSE_TOKEN;\n\n    // Attribute telemetry to the licensed customer for *every* runtime mode.\n    // Done in the shared base (not the subclasses) so SSE and Intelligence\n    // runtimes behave identically — previously only CopilotIntelligenceRuntime\n    // set this, so self-hosted SSE users never got a telemetry_id on their\n    // runtime events even with a license token configured.\n    if (this.resolvedLicenseToken) {\n      telemetry.setLicenseToken(this.resolvedLicenseToken);\n    }\n\n    if (process.env.NODE_ENV !== \"production\") {\n      this.debugEventBus = new DebugEventBus();\n    }\n    // Resolve the inbound-header forwarding policy once (mirroring the\n    // `debug` → `ResolvedDebugConfig` resolve-once above) so both the /run and\n    // /connect call sites read the exact same resolved policy off the runtime\n    // and can never diverge.\n    this.forwardHeadersPolicy = resolveForwardHeadersPolicy(\n      options.forwardHeaders,\n    );\n    // Secure default: the client-facing memory proxy routes stay hidden (404)\n    // unless a deployment explicitly opts in.\n    this.exposeMemoryRoutes = options.exposeMemoryRoutes ?? false;\n    this.debug = resolveDebugConfig(options.debug);\n    if (this.debug.enabled) {\n      this.debugLogger = createLogger({\n        level: \"debug\",\n        component: \"copilotkit-debug\",\n      });\n    }\n  }\n}\n\nexport class CopilotSseRuntime\n  extends BaseCopilotRuntime\n  implements CopilotSseRuntimeLike\n{\n  readonly intelligence = undefined;\n  readonly mode = RUNTIME_MODE_SSE;\n\n  constructor(options: CopilotSseRuntimeOptions) {\n    // Runtime guard mirroring the discriminated-union type: the SSE runtime has\n    // no Intelligence delivery path, so `channels` cannot be honored here. The\n    // type forbids it, but a JS / `as any` caller passing `{ agents, channels }`\n    // would otherwise land here and have `channels` silently dropped — fail\n    // loud instead.\n    const channels = (options as { channels?: unknown[] }).channels;\n    if (Array.isArray(channels) && channels.length > 0) {\n      throw new Error(\n        \"`channels` requires the Intelligence runtime (pass `intelligence`); \" +\n          \"Intelligence Channels are not available in SSE mode.\",\n      );\n    }\n    super(options, options.runner ?? new InMemoryAgentRunner());\n  }\n}\n\nexport class CopilotIntelligenceRuntime\n  extends BaseCopilotRuntime\n  implements CopilotIntelligenceRuntimeLike\n{\n  readonly intelligence: CopilotKitIntelligence;\n  readonly identifyUser: IdentifyUserCallback;\n  readonly generateThreadNames: boolean;\n  readonly lockTtlSeconds: number;\n  readonly lockKeyPrefix?: string;\n  readonly lockHeartbeatIntervalSeconds: number;\n  readonly channels: Channel[];\n  readonly mode = RUNTIME_MODE_INTELLIGENCE;\n\n  /** Maximum allowed lock TTL in seconds (1 hour). */\n  static readonly MAX_LOCK_TTL_SECONDS = 3_600;\n  /** Maximum allowed heartbeat interval in seconds (50 minutes). */\n  static readonly MAX_HEARTBEAT_INTERVAL_SECONDS = 3_000;\n\n  constructor(options: CopilotIntelligenceRuntimeOptions) {\n    super(\n      options,\n      new IntelligenceAgentRunner({\n        url: options.intelligence.ɵgetRunnerWsUrl(),\n        authToken: options.intelligence.ɵgetRunnerAuthToken(),\n        maxReconnectMs: options.maxReconnectMs,\n        maxRejoinMs: options.maxRejoinMs,\n      }),\n    );\n    this.intelligence = options.intelligence;\n    this.identifyUser = options.identifyUser;\n    this.generateThreadNames = options.generateThreadNames ?? true;\n    // Telemetry attribution is handled by the base constructor for all modes;\n    // here we only need the token for feature gating. Reuse the base-resolved\n    // value so gating and attribution can never disagree.\n    this.licenseChecker = createLicenseChecker(this.resolvedLicenseToken);\n    this.lockTtlSeconds = Math.min(\n      options.lockTtlSeconds ?? 20,\n      CopilotIntelligenceRuntime.MAX_LOCK_TTL_SECONDS,\n    );\n    this.lockKeyPrefix = options.lockKeyPrefix;\n    this.lockHeartbeatIntervalSeconds = Math.min(\n      options.lockHeartbeatIntervalSeconds ?? 15,\n      CopilotIntelligenceRuntime.MAX_HEARTBEAT_INTERVAL_SECONDS,\n    );\n    // Declared Intelligence Channels. Lowercase kebab-case name-shape validation\n    // (`assertValidChannelNames`) lives in the channels-intelligence launcher —\n    // it can't run here because it's a value import from the pure-ESM\n    // `@copilotkit/channels-intelligence`, which this CJS package must not pull in.\n    // Name UNIQUENESS across declared Channels is enforced by\n    // `ChannelManager.activate()`, not the launcher: the managed path activates\n    // one Channel per launcher call, so the launcher never sees the full set.\n    // Fail fast on the most common misconfiguration (a missing name) right here\n    // at construction, though, rather than only at activation.\n    this.channels = options.channels ?? [];\n    for (const c of this.channels) {\n      if (!c.name) {\n        throw new Error(\n          \"Intelligence Channel is missing a `name` — pass createChannel({ name }) for each Channel in `channels`\",\n        );\n      }\n    }\n  }\n}\n\nfunction hasIntelligenceOptions(\n  options: CopilotRuntimeOptions,\n): options is CopilotIntelligenceRuntimeOptions {\n  return \"intelligence\" in options && !!options.intelligence;\n}\n\nexport function isIntelligenceRuntime(\n  runtime: CopilotRuntimeLike,\n): runtime is CopilotIntelligenceRuntimeLike {\n  return runtime.mode === RUNTIME_MODE_INTELLIGENCE && !!runtime.intelligence;\n}\n\n/**\n * Single source of truth for \"is A2UI on for this runtime?\". Both the run path\n * (which applies `A2UIMiddleware`) and the `/info` response (which tells the\n * client whether to mount the A2UI renderer + catalog context) MUST go through\n * this, so they can never disagree — the divergence between them was the root\n * of CopilotKit/CopilotKit#5369.\n *\n * Backwards compatible: any config object is enabled (matching the historical\n * `!!runtime.a2ui`); only an explicit `enabled: false` turns it off.\n */\nexport function isA2UIEnabled(\n  a2ui: CopilotRuntimeOptions[\"a2ui\"],\n): a2ui is NonNullable<CopilotRuntimeOptions[\"a2ui\"]> {\n  return !!a2ui && a2ui.enabled !== false;\n}\n\n/**\n * Compile-time phantom brand marking a {@link CopilotRuntime} that was\n * constructed with at least one declared Intelligence Channel. It has no runtime\n * representation — the shim never sets this property; it exists purely so\n * `createCopilotRuntimeHandler` can tell, at the type level, that the resulting\n * handler will carry a non-optional `.channels` control surface.\n */\nexport interface RuntimeWithDeclaredChannels {\n  /**\n   * @internal Phantom brand key. Never present at runtime; do not read or set.\n   */\n  readonly __copilotkitChannelsDeclared: true;\n}\n\n/**\n * Instance shape of the {@link CopilotRuntime} compatibility shim. Extends\n * {@link CopilotRuntimeLike} with the Intelligence-only accessors the shim\n * surfaces (all `undefined` in SSE mode). Declared explicitly so the exported\n * `CopilotRuntime` name resolves as a type as well as a value.\n */\nexport interface CopilotRuntime extends CopilotRuntimeLike {\n  /** Auto-generate short thread names; `undefined` in SSE mode. */\n  generateThreadNames?: boolean;\n  /** Thread lock TTL in seconds; `undefined` in SSE mode. */\n  lockTtlSeconds?: number;\n  /** Custom Redis key prefix for the thread lock; `undefined` in SSE mode. */\n  lockKeyPrefix?: string;\n  /** Thread lock heartbeat interval in seconds; `undefined` in SSE mode. */\n  lockHeartbeatIntervalSeconds?: number;\n  /** Declared Intelligence Channels; `undefined` in SSE mode. */\n  channels?: Channel[];\n}\n\n/**\n * Constructor type for the {@link CopilotRuntime} compatibility shim.\n *\n * The first overload fires when the caller passes `intelligence` together with a\n * non-empty `channels` tuple: it returns a {@link RuntimeWithDeclaredChannels}-\n * branded runtime, which `createCopilotRuntimeHandler` maps to a handler whose\n * `.channels` is non-optional. Every other configuration (SSE, or Intelligence\n * without channels, or an empty `channels: []`) falls through to the second\n * overload and stays unbranded, so its handler keeps `.channels` optional.\n *\n * A class constructor cannot vary its return type across overloads (it is pinned\n * to the instance type), so the branding lives on this construct-signature\n * interface instead of on the class itself.\n */\nexport interface CopilotRuntimeConstructor {\n  new (\n    options: Omit<CopilotIntelligenceRuntimeOptions, \"channels\"> & {\n      channels: readonly [Channel, ...Channel[]];\n    },\n  ): CopilotRuntime & RuntimeWithDeclaredChannels;\n  new (options: CopilotRuntimeOptions): CopilotRuntime;\n}\n\n/**\n * Compatibility shim that preserves the legacy `CopilotRuntime` entrypoint.\n * New code should prefer `CopilotSseRuntime` or `CopilotIntelligenceRuntime`.\n *\n * Exported to consumers as the {@link CopilotRuntime} value (typed as\n * {@link CopilotRuntimeConstructor}) rather than as a class, so that the\n * channel-presence brand can flow from construction into the handler type.\n */\nclass CopilotRuntimeShim implements CopilotRuntime {\n  private delegate: CopilotRuntimeLike;\n\n  constructor(options: CopilotRuntimeOptions) {\n    this.delegate = hasIntelligenceOptions(options)\n      ? new CopilotIntelligenceRuntime(options)\n      : new CopilotSseRuntime(options);\n  }\n\n  get agents(): CopilotRuntimeOptions[\"agents\"] {\n    return this.delegate.agents;\n  }\n\n  get transcriptionService(): CopilotRuntimeOptions[\"transcriptionService\"] {\n    return this.delegate.transcriptionService;\n  }\n\n  get beforeRequestMiddleware(): CopilotRuntimeOptions[\"beforeRequestMiddleware\"] {\n    return this.delegate.beforeRequestMiddleware;\n  }\n\n  get afterRequestMiddleware(): CopilotRuntimeOptions[\"afterRequestMiddleware\"] {\n    return this.delegate.afterRequestMiddleware;\n  }\n\n  get runner(): AgentRunner {\n    return this.delegate.runner;\n  }\n\n  get a2ui(): CopilotRuntimeOptions[\"a2ui\"] {\n    return this.delegate.a2ui;\n  }\n\n  get mcpApps(): CopilotRuntimeOptions[\"mcpApps\"] {\n    return this.delegate.mcpApps;\n  }\n\n  get openGenerativeUI(): CopilotRuntimeOptions[\"openGenerativeUI\"] {\n    return this.delegate.openGenerativeUI;\n  }\n\n  get intelligence(): CopilotKitIntelligence | undefined {\n    return this.delegate.intelligence;\n  }\n\n  get generateThreadNames(): boolean | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.generateThreadNames\n      : undefined;\n  }\n\n  get identifyUser(): IdentifyUserCallback | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.identifyUser\n      : undefined;\n  }\n\n  get lockTtlSeconds(): number | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockTtlSeconds\n      : undefined;\n  }\n\n  get lockKeyPrefix(): string | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockKeyPrefix\n      : undefined;\n  }\n\n  get lockHeartbeatIntervalSeconds(): number | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.lockHeartbeatIntervalSeconds\n      : undefined;\n  }\n\n  get channels(): Channel[] | undefined {\n    return isIntelligenceRuntime(this.delegate)\n      ? this.delegate.channels\n      : undefined;\n  }\n\n  get mode(): RuntimeMode {\n    return this.delegate.mode;\n  }\n\n  get licenseChecker() {\n    return this.delegate.licenseChecker;\n  }\n\n  get debugEventBus() {\n    return this.delegate.debugEventBus;\n  }\n\n  get debug(): ResolvedDebugConfig {\n    return this.delegate.debug;\n  }\n\n  get debugLogger(): CopilotRuntimeLogger | undefined {\n    return this.delegate.debugLogger;\n  }\n\n  get forwardHeadersPolicy(): ResolvedForwardHeadersPolicy {\n    return this.delegate.forwardHeadersPolicy;\n  }\n\n  get exposeMemoryRoutes(): boolean | undefined {\n    return this.delegate.exposeMemoryRoutes;\n  }\n}\n\n/**\n * The public `CopilotRuntime` constructor. Backed by {@link CopilotRuntimeShim}\n * but typed as {@link CopilotRuntimeConstructor} so that constructing with a\n * non-empty `channels` array yields a {@link RuntimeWithDeclaredChannels}-branded\n * runtime type.\n *\n * The `as unknown as` cast is required (not dishonest widening): the brand is a\n * phantom, compile-time-only marker with no runtime representation, so the shim\n * instances legitimately do not carry the brand property. Behavior is identical\n * to the former `class CopilotRuntime` — this only refines the static type.\n */\nexport const CopilotRuntime: CopilotRuntimeConstructor =\n  CopilotRuntimeShim as unknown as CopilotRuntimeConstructor;\n"],"mappings":"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"}

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

@@ -63,6 +63,25 @@ function parseMemoryBody(body) {
 	};
 }
 /**
+* Validates the recall body: `query` required non-empty string (trimmed);
+* `limit` optional finite positive integer; `scope` optional and in the known
+* scopes. Returns a 400 Response on invalid input. The returned `query` is the
+* trimmed value so a whitespace-padded query is never forwarded to the platform.
+*/
+function parseRecallBody(body) {
+	const { query, limit, scope } = body;
+	const trimmedQuery = typeof query === "string" ? query.trim() : query;
+	if (typeof trimmedQuery !== "string" || trimmedQuery.length === 0) return require_json_response.errorResponse("Recall requires a non-empty string `query`", 400);
+	if (limit !== void 0 && !(typeof limit === "number" && Number.isInteger(limit) && limit > 0)) return require_json_response.errorResponse("Recall `limit` must be a positive integer", 400);
+	if (scope !== void 0 && typeof scope !== "string") return require_json_response.errorResponse("Recall `scope` must be a string when provided", 400);
+	if (typeof scope === "string" && !MEMORY_SCOPES.has(scope)) return require_json_response.errorResponse("Recall `scope` must be one of: user, project", 400);
+	return {
+		query: trimmedQuery,
+		...typeof limit === "number" ? { limit } : {},
+		...typeof scope === "string" ? { scope } : {}
+	};
+}
+/**
 * Lists the resolved user's long-term memories via the Intelligence platform.
 *
 * Mirrors {@link handleListThreads}: requires a `CopilotKitIntelligence`
@@ -97,6 +116,40 @@ async function handleListMemories({ runtime, request }) {
 	return require_json_response.errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
 }
 /**
+* Semantically recalls the resolved user's memories via the platform (`POST
+* /api/memories/recall`, hybrid RAG). Mirrors {@link handleListMemories}:
+* requires a `CopilotKitIntelligence` runtime, resolves the user with
+* `identifyUser` (never a client-supplied id), proxies with the project API
+* key + resolved user. Body `{ query, limit?, scope? }`; response `{ memories }`,
+* each optionally carrying `score`.
+*/
+async function handleRecallMemories({ 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 = parseRecallBody(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.recallMemories({
+			userId: user.id,
+			...fields
+		});
+		if (data == null || typeof data !== "object" || !Array.isArray(data.memories)) {
+			_copilotkit_shared.logger.error({ data }, "recallMemories: platform returned a response without a `memories` array");
+			return require_json_response.errorResponse("Memory platform returned an invalid recall response", 502);
+		}
+		return Response.json(data);
+	} catch (error) {
+		_copilotkit_shared.logger.error({ err: error }, "Error recalling memories");
+		return memoryErrorResponse(error, "Failed to recall memories");
+	}
+}
+/**
 * Mints memory-realtime join credentials (platform `POST
 * /api/memories/subscribe`). Mirrors {@link handleSubscribeToThreads}: requires
 * a `CopilotKitIntelligence` runtime and resolves the user with `identifyUser`
@@ -104,6 +157,12 @@ async function handleListMemories({ runtime, request }) {
 * 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.
+*
+* When the platform also resolves a project scope, the response additionally
+* carries `projectJoinToken` / `projectJoinCode`, which the client uses to open
+* a second `project_meta:memories:<projectJoinCode>` channel. These are
+* optional: absent project scope → both fields are omitted (silent-degrade
+* contract; the client opens only the user channel).
 */
 async function handleSubscribeToMemories({ runtime, request }) {
 	if (require_runtime$1.isIntelligenceRuntime(runtime)) try {
@@ -115,7 +174,9 @@ async function handleSubscribeToMemories({ runtime, request }) {
 		const credentials = await runtime.intelligence.ɵsubscribeToMemories({ userId: user.id });
 		return Response.json({
 			joinToken: credentials.joinToken,
-			joinCode: credentials.joinCode
+			joinCode: credentials.joinCode,
+			...credentials.projectJoinToken !== void 0 ? { projectJoinToken: credentials.projectJoinToken } : {},
+			...credentials.projectJoinCode !== void 0 ? { projectJoinCode: credentials.projectJoinCode } : {}
 		});
 	} catch (error) {
 		_copilotkit_shared.logger.error({ err: error }, "Error subscribing to memories");
@@ -203,6 +264,7 @@ async function handleRemoveMemory({ runtime, request, memoryId }) {
 //#endregion
 exports.handleCreateMemory = handleCreateMemory;
 exports.handleListMemories = handleListMemories;
+exports.handleRecallMemories = handleRecallMemories;
 exports.handleRemoveMemory = handleRemoveMemory;
 exports.handleSubscribeToMemories = handleSubscribeToMemories;
 exports.handleUpdateMemory = handleUpdateMemory;

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

@@ -1 +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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"}
+{"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 * Validates the recall body: `query` required non-empty string (trimmed);\n * `limit` optional finite positive integer; `scope` optional and in the known\n * scopes. Returns a 400 Response on invalid input. The returned `query` is the\n * trimmed value so a whitespace-padded query is never forwarded to the platform.\n */\nfunction parseRecallBody(\n  body: Record<string, unknown>,\n): { query: string; limit?: number; scope?: string } | Response {\n  const { query, limit, scope } = body;\n  // Trim before the emptiness check so whitespace-only queries (e.g. \"   \")\n  // are rejected rather than forwarded as a useless query to the platform.\n  const trimmedQuery = typeof query === \"string\" ? query.trim() : query;\n  if (typeof trimmedQuery !== \"string\" || trimmedQuery.length === 0) {\n    return errorResponse(\"Recall requires a non-empty string `query`\", 400);\n  }\n  // When provided, `limit` must be a finite positive integer. `Number.isInteger`\n  // already rejects NaN, Infinity, and fractions (NaN/Infinity would otherwise\n  // JSON-serialize to `null` and silently corrupt the forwarded request);\n  // the `> 0` guard rejects zero and negatives.\n  if (\n    limit !== undefined &&\n    !(typeof limit === \"number\" && Number.isInteger(limit) && limit > 0)\n  ) {\n    return errorResponse(\"Recall `limit` must be a positive integer\", 400);\n  }\n  if (scope !== undefined && typeof scope !== \"string\") {\n    return errorResponse(\"Recall `scope` must be a string when provided\", 400);\n  }\n  if (typeof scope === \"string\" && !MEMORY_SCOPES.has(scope)) {\n    return errorResponse(\"Recall `scope` must be one of: user, project\", 400);\n  }\n  return {\n    query: trimmedQuery,\n    ...(typeof limit === \"number\" ? { limit } : {}),\n    ...(typeof scope === \"string\" ? { scope } : {}),\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 * Semantically recalls the resolved user's memories via the platform (`POST\n * /api/memories/recall`, hybrid RAG). Mirrors {@link handleListMemories}:\n * requires a `CopilotKitIntelligence` runtime, resolves the user with\n * `identifyUser` (never a client-supplied id), proxies with the project API\n * key + resolved user. Body `{ query, limit?, scope? }`; response `{ memories }`,\n * each optionally carrying `score`.\n */\nexport async function handleRecallMemories({\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 = parseRecallBody(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.recallMemories({\n      userId: user.id,\n      ...fields,\n    });\n\n    if (\n      data == null ||\n      typeof data !== \"object\" ||\n      !Array.isArray((data as { memories?: unknown }).memories)\n    ) {\n      logger.error(\n        { data },\n        \"recallMemories: platform returned a response without a `memories` array\",\n      );\n      return errorResponse(\n        \"Memory platform returned an invalid recall response\",\n        502,\n      );\n    }\n    return Response.json(data);\n  } catch (error) {\n    logger.error({ err: error }, \"Error recalling memories\");\n    return memoryErrorResponse(error, \"Failed to recall memories\");\n  }\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 *\n * When the platform also resolves a project scope, the response additionally\n * carries `projectJoinToken` / `projectJoinCode`, which the client uses to open\n * a second `project_meta:memories:<projectJoinCode>` channel. These are\n * optional: absent project scope → both fields are omitted (silent-degrade\n * contract; the client opens only the user channel).\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        // Project-scoped credentials ride along only when the platform minted\n        // them; omit both when absent (silent-degrade contract).\n        ...(credentials.projectJoinToken !== undefined\n          ? { projectJoinToken: credentials.projectJoinToken }\n          : {}),\n        ...(credentials.projectJoinCode !== undefined\n          ? { projectJoinCode: credentials.projectJoinCode }\n          : {}),\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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"}

package/dist/v2/runtime/handlers/intelligence/memories.mjs

@@ -62,6 +62,25 @@ function parseMemoryBody(body) {
 	};
 }
 /**
+* Validates the recall body: `query` required non-empty string (trimmed);
+* `limit` optional finite positive integer; `scope` optional and in the known
+* scopes. Returns a 400 Response on invalid input. The returned `query` is the
+* trimmed value so a whitespace-padded query is never forwarded to the platform.
+*/
+function parseRecallBody(body) {
+	const { query, limit, scope } = body;
+	const trimmedQuery = typeof query === "string" ? query.trim() : query;
+	if (typeof trimmedQuery !== "string" || trimmedQuery.length === 0) return errorResponse("Recall requires a non-empty string `query`", 400);
+	if (limit !== void 0 && !(typeof limit === "number" && Number.isInteger(limit) && limit > 0)) return errorResponse("Recall `limit` must be a positive integer", 400);
+	if (scope !== void 0 && typeof scope !== "string") return errorResponse("Recall `scope` must be a string when provided", 400);
+	if (typeof scope === "string" && !MEMORY_SCOPES.has(scope)) return errorResponse("Recall `scope` must be one of: user, project", 400);
+	return {
+		query: trimmedQuery,
+		...typeof limit === "number" ? { limit } : {},
+		...typeof scope === "string" ? { scope } : {}
+	};
+}
+/**
 * Lists the resolved user's long-term memories via the Intelligence platform.
 *
 * Mirrors {@link handleListThreads}: requires a `CopilotKitIntelligence`
@@ -96,6 +115,40 @@ async function handleListMemories({ runtime, request }) {
 	return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
 }
 /**
+* Semantically recalls the resolved user's memories via the platform (`POST
+* /api/memories/recall`, hybrid RAG). Mirrors {@link handleListMemories}:
+* requires a `CopilotKitIntelligence` runtime, resolves the user with
+* `identifyUser` (never a client-supplied id), proxies with the project API
+* key + resolved user. Body `{ query, limit?, scope? }`; response `{ memories }`,
+* each optionally carrying `score`.
+*/
+async function handleRecallMemories({ runtime, request }) {
+	if (!isIntelligenceRuntime(runtime)) return errorResponse(MISSING_INTELLIGENCE_MESSAGE, 422);
+	try {
+		const body = await parseJsonBody(request);
+		if (isHandlerResponse(body)) return body;
+		const fields = parseRecallBody(body);
+		if (isHandlerResponse(fields)) return fields;
+		const user = await resolveIntelligenceUser({
+			runtime,
+			request
+		});
+		if (isHandlerResponse(user)) return user;
+		const data = await runtime.intelligence.recallMemories({
+			userId: user.id,
+			...fields
+		});
+		if (data == null || typeof data !== "object" || !Array.isArray(data.memories)) {
+			logger.error({ data }, "recallMemories: platform returned a response without a `memories` array");
+			return errorResponse("Memory platform returned an invalid recall response", 502);
+		}
+		return Response.json(data);
+	} catch (error) {
+		logger.error({ err: error }, "Error recalling memories");
+		return memoryErrorResponse(error, "Failed to recall memories");
+	}
+}
+/**
 * Mints memory-realtime join credentials (platform `POST
 * /api/memories/subscribe`). Mirrors {@link handleSubscribeToThreads}: requires
 * a `CopilotKitIntelligence` runtime and resolves the user with `identifyUser`
@@ -103,6 +156,12 @@ async function handleListMemories({ runtime, request }) {
 * 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.
+*
+* When the platform also resolves a project scope, the response additionally
+* carries `projectJoinToken` / `projectJoinCode`, which the client uses to open
+* a second `project_meta:memories:<projectJoinCode>` channel. These are
+* optional: absent project scope → both fields are omitted (silent-degrade
+* contract; the client opens only the user channel).
 */
 async function handleSubscribeToMemories({ runtime, request }) {
 	if (isIntelligenceRuntime(runtime)) try {
@@ -114,7 +173,9 @@ async function handleSubscribeToMemories({ runtime, request }) {
 		const credentials = await runtime.intelligence.ɵsubscribeToMemories({ userId: user.id });
 		return Response.json({
 			joinToken: credentials.joinToken,
-			joinCode: credentials.joinCode
+			joinCode: credentials.joinCode,
+			...credentials.projectJoinToken !== void 0 ? { projectJoinToken: credentials.projectJoinToken } : {},
+			...credentials.projectJoinCode !== void 0 ? { projectJoinCode: credentials.projectJoinCode } : {}
 		});
 	} catch (error) {
 		logger.error({ err: error }, "Error subscribing to memories");
@@ -200,5 +261,5 @@ async function handleRemoveMemory({ runtime, request, memoryId }) {
 }
 
 //#endregion
-export { handleCreateMemory, handleListMemories, handleRemoveMemory, handleSubscribeToMemories, handleUpdateMemory };
+export { handleCreateMemory, handleListMemories, handleRecallMemories, handleRemoveMemory, handleSubscribeToMemories, handleUpdateMemory };
 //# sourceMappingURL=memories.mjs.map

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

@@ -1 +1 @@
-{"version":3,"file":"memories.mjs","names":[],"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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"}
+{"version":3,"file":"memories.mjs","names":[],"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 * Validates the recall body: `query` required non-empty string (trimmed);\n * `limit` optional finite positive integer; `scope` optional and in the known\n * scopes. Returns a 400 Response on invalid input. The returned `query` is the\n * trimmed value so a whitespace-padded query is never forwarded to the platform.\n */\nfunction parseRecallBody(\n  body: Record<string, unknown>,\n): { query: string; limit?: number; scope?: string } | Response {\n  const { query, limit, scope } = body;\n  // Trim before the emptiness check so whitespace-only queries (e.g. \"   \")\n  // are rejected rather than forwarded as a useless query to the platform.\n  const trimmedQuery = typeof query === \"string\" ? query.trim() : query;\n  if (typeof trimmedQuery !== \"string\" || trimmedQuery.length === 0) {\n    return errorResponse(\"Recall requires a non-empty string `query`\", 400);\n  }\n  // When provided, `limit` must be a finite positive integer. `Number.isInteger`\n  // already rejects NaN, Infinity, and fractions (NaN/Infinity would otherwise\n  // JSON-serialize to `null` and silently corrupt the forwarded request);\n  // the `> 0` guard rejects zero and negatives.\n  if (\n    limit !== undefined &&\n    !(typeof limit === \"number\" && Number.isInteger(limit) && limit > 0)\n  ) {\n    return errorResponse(\"Recall `limit` must be a positive integer\", 400);\n  }\n  if (scope !== undefined && typeof scope !== \"string\") {\n    return errorResponse(\"Recall `scope` must be a string when provided\", 400);\n  }\n  if (typeof scope === \"string\" && !MEMORY_SCOPES.has(scope)) {\n    return errorResponse(\"Recall `scope` must be one of: user, project\", 400);\n  }\n  return {\n    query: trimmedQuery,\n    ...(typeof limit === \"number\" ? { limit } : {}),\n    ...(typeof scope === \"string\" ? { scope } : {}),\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 * Semantically recalls the resolved user's memories via the platform (`POST\n * /api/memories/recall`, hybrid RAG). Mirrors {@link handleListMemories}:\n * requires a `CopilotKitIntelligence` runtime, resolves the user with\n * `identifyUser` (never a client-supplied id), proxies with the project API\n * key + resolved user. Body `{ query, limit?, scope? }`; response `{ memories }`,\n * each optionally carrying `score`.\n */\nexport async function handleRecallMemories({\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 = parseRecallBody(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.recallMemories({\n      userId: user.id,\n      ...fields,\n    });\n\n    if (\n      data == null ||\n      typeof data !== \"object\" ||\n      !Array.isArray((data as { memories?: unknown }).memories)\n    ) {\n      logger.error(\n        { data },\n        \"recallMemories: platform returned a response without a `memories` array\",\n      );\n      return errorResponse(\n        \"Memory platform returned an invalid recall response\",\n        502,\n      );\n    }\n    return Response.json(data);\n  } catch (error) {\n    logger.error({ err: error }, \"Error recalling memories\");\n    return memoryErrorResponse(error, \"Failed to recall memories\");\n  }\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 *\n * When the platform also resolves a project scope, the response additionally\n * carries `projectJoinToken` / `projectJoinCode`, which the client uses to open\n * a second `project_meta:memories:<projectJoinCode>` channel. These are\n * optional: absent project scope → both fields are omitted (silent-degrade\n * contract; the client opens only the user channel).\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        // Project-scoped credentials ride along only when the platform minted\n        // them; omit both when absent (silent-degrade contract).\n        ...(credentials.projectJoinToken !== undefined\n          ? { projectJoinToken: credentials.projectJoinToken }\n          : {}),\n        ...(credentials.projectJoinCode !== undefined\n          ? { projectJoinCode: credentials.projectJoinCode }\n          : {}),\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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"}

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

@@ -287,6 +287,19 @@ var CopilotKitIntelligence = class {
 	async removeMemory(params) {
 		await this.#request("DELETE", `/api/memories/${encodeURIComponent(params.id)}`, void 0, { [INTELLIGENCE_USER_ID_HEADER]: params.userId });
 	}
+	/**
+	* Semantically recall the given user's memories (platform `POST
+	* /api/memories/recall`, hybrid RAG). Each returned memory carries a
+	* relevance `score`. `scope` narrows to `"user"`/`"project"`; omitted → platform default.
+	* @throws {@link PlatformRequestError} on non-2xx responses.
+	*/
+	async recallMemories(params) {
+		return this.#request("POST", `/api/memories/recall`, {
+			query: params.query,
+			...params.limit !== void 0 ? { limit: params.limit } : {},
+			...params.scope !== void 0 ? { scope: params.scope } : {}
+		}, { [INTELLIGENCE_USER_ID_HEADER]: params.userId });
+	}
 	async ɵsubscribeToThreads(params) {
 		return this.#request("POST", "/api/threads/subscribe", { userId: params.userId });
 	}
@@ -294,7 +307,10 @@ var CopilotKitIntelligence = class {
 	* Mint memory-realtime join credentials (platform `POST
 	* /api/memories/subscribe`). Returns both the single-use `joinToken` and the
 	* per-user `joinCode` the client needs to build the
-	* `user_meta:memories:<joinCode>` channel topic.
+	* `user_meta:memories:<joinCode>` channel topic. When the platform also
+	* resolves a project scope it returns optional `projectJoinToken` /
+	* `projectJoinCode`; both are passed through verbatim (omitted when absent,
+	* the silent-degrade contract).
 	*
 	* The user is supplied via the `x-cpki-user-id` header — the same way every
 	* other memory endpoint (`listMemories`/`createMemory`/…) identifies the app