@copilotkit/core 1.62.2 → 1.63.0

package/dist/index.d.mts

@@ -200,6 +200,7 @@ declare class AgentRegistry {
   private localAgents;
   private remoteAgents;
   private _runtimeUrl?;
+  private _connectionInFlight?;
   private _runtimeVersion?;
   private _runtimeConnectionStatus;
   private _runtimeTransport;
@@ -208,6 +209,7 @@ declare class AgentRegistry {
   private _runtimeMode;
   private _intelligence?;
   private _threadEndpoints?;
+  private _suggestions?;
   private _a2uiEnabled;
   private _a2uiAgents?;
   private _openGenerativeUIEnabled;
@@ -237,6 +239,7 @@ declare class AgentRegistry {
   get runtimeMode(): RuntimeMode$1;
   get intelligence(): IntelligenceRuntimeInfo$1 | undefined;
   get threadEndpoints(): ThreadEndpointRuntimeInfo$1 | undefined;
+  get suggestions(): boolean | undefined;
   get a2uiEnabled(): boolean;
   /**
    * Agent ids the runtime applies A2UI to (#5369). `undefined` means A2UI
@@ -253,7 +256,21 @@ declare class AgentRegistry {
   /**
    * Set the runtime URL and update connection
    */
-  setRuntimeUrl(runtimeUrl: string | undefined): void;
+  setRuntimeUrl(runtimeUrl: string | undefined, options?: {
+    deferConnection?: boolean;
+  }): void;
+  /**
+   * Start the initial runtime connection if it has not been started yet.
+   *
+   * Backs {@link CopilotKitCore.connect}. Idempotent: it only kicks off a fetch
+   * when a `runtimeUrl` is set and the connection is still `Disconnected` (its
+   * state before any connect attempt). `updateRuntimeConnection` flips the
+   * status to `Connecting` synchronously, so a second call — e.g. React
+   * StrictMode double-invoking the mount effect — bails here. A genuine config
+   * change still reconnects through `setRuntimeUrl`/`setRuntimeTransport`. See
+   * #5801.
+   */
+  connectRuntime(): void;
   setRuntimeTransport(runtimeTransport: CopilotRuntimeTransport): void;
   /**
    * Set all agents at once (for development use)
@@ -312,6 +329,7 @@ declare class AgentRegistry {
    * Update runtime connection and fetch remote agents
    */
   private updateRuntimeConnection;
+  private performRuntimeConnection;
   private fetchRuntimeInfo;
   private fetchRuntimeInfoSingle;
   /**
@@ -862,6 +880,14 @@ interface ThreadState {
   isLoading: boolean;
   isFetchingNextPage: boolean;
   error: Error | null;
+  /**
+   * Error from the most recent failed next-page (`fetchMore`) load, or `null`.
+   * Tracked SEPARATELY from `error` so a paginated-load failure surfaces an
+   * inline "couldn't load more" affordance without replacing the already-loaded
+   * list with a full-panel error. Cleared when a fetch-more is retried or when
+   * one succeeds; reset on context change / stop.
+   */
+  fetchMoreError: Error | null;
   context: ThreadRuntimeContext | null;
   sessionId: number;
   metadataCredentialsRequested: boolean;
@@ -887,6 +913,7 @@ interface ThreadSelectors {
   threads: (state: ThreadState) => ThreadRecord[];
   isLoading: (state: ThreadState) => boolean;
   error: (state: ThreadState) => Error | null;
+  fetchMoreError: (state: ThreadState) => Error | null;
   hasNextPage: (state: ThreadState) => boolean;
   isFetchingNextPage: (state: ThreadState) => boolean;
   isMutating: (state: ThreadState) => boolean;
@@ -994,6 +1021,7 @@ declare const ɵcreateThreadSelectors: typeof createThreadSelectors;
 declare const ɵselectThreads: (state: ThreadState) => ThreadRecord[];
 declare const ɵselectThreadsIsLoading: (state: ThreadState) => boolean;
 declare const ɵselectThreadsError: (state: ThreadState) => Error | null;
+declare const ɵselectFetchMoreError: (state: ThreadState) => Error | null;
 declare const ɵselectHasNextPage: (state: ThreadState) => boolean;
 declare const ɵselectIsFetchingNextPage: (state: ThreadState) => boolean;
 declare const ɵselectIsMutating: (state: ThreadState) => boolean;
@@ -1005,6 +1033,383 @@ declare const ɵselectIsMutating: (state: ThreadState) => boolean;
  */
 declare const ɵMAX_SOCKET_RETRIES = 5;
 //#endregion
+//#region src/memory-errors.d.ts
+/**
+ * Memory error registry — stable codes for the errors the memory store throws.
+ *
+ * The memory store (`memory.ts`) used to throw bare `new Error("Failed to fetch
+ * memories: 500")` / `"Request timed out"` / `"Request failed: <status>"`. Those
+ * reach the `error` selector (and the consumer UI via `useMemories` /
+ * `injectMemories`) verbatim, with no machine-readable `code`/`category`/
+ * `retryable`, so they cannot be grouped in observability or branched on by
+ * consumers.
+ *
+ * Per the repo's error-handling architecture standard (AGENTS.md: "Each project
+ * must maintain an explicit error registry"), this file is the explicit registry
+ * for the memory feature. It is deliberately scoped to memory — not a repo-wide
+ * registry refactor — because `packages/core` has no pre-existing
+ * code/category/retryable registry convention to plug into (the runtime's
+ * `lib/error-messages.ts` is a message-templating table, not a typed
+ * code/category/retryable registry). It mirrors the existing
+ * `AgentThreadLockedError extends Error` precedent in
+ * `intelligence-agent.ts`: a real `Error` subclass so `instanceof Error` holds
+ * and the public `MemoryState.error: Error | null` contract is preserved.
+ *
+ * `docsPath` is recorded per entry per the standard; there is no
+ * `docs/errors/<project>.md` in this repo, so this docblock plus the registry
+ * are the source of truth.
+ *
+ * Each registry entry carries:
+ * - `code`: stable identifier (e.g. `MEMORY_LIST_FAILED`).
+ * - `category`: one of the standard categories
+ *   (`validation`|`auth`|`permission`|`not_found`|`conflict`|`rate_limit`|`internal`|`dependency`).
+ * - `retryable`: whether a retry could plausibly succeed (timeouts + transient
+ *   dependency failures are retryable; client-caused 4xx are not).
+ * - `message`: the default human-readable message (callers may override with a
+ *   status-bearing string to preserve the prior wording).
+ * - `docsPath`: documentation pointer for the code.
+ */
+/** Standard error categories from the repo error-handling architecture. */
+type MemoryErrorCategory = "validation" | "auth" | "permission" | "not_found" | "conflict" | "rate_limit" | "internal" | "dependency";
+/** Stable codes for the memory store's surfaced errors. */
+type MemoryErrorCode = "MEMORY_LIST_FAILED" | "MEMORY_CREDENTIALS_FAILED" | "MEMORY_MUTATION_FAILED" | "MEMORY_REQUEST_TIMEOUT";
+/** A single registry entry describing one memory error code. */
+interface MemoryErrorRegistryEntry {
+  readonly code: MemoryErrorCode;
+  readonly category: MemoryErrorCategory;
+  readonly retryable: boolean;
+  readonly message: string;
+  readonly docsPath: string;
+}
+/**
+ * The memory error registry: the single source of truth for memory error
+ * metadata. Keyed by `code` so a code maps to exactly one category/retryable
+ * default.
+ *
+ * Categories/retryable rationale:
+ * - List/credentials/mutation failures are `dependency` (the runtime/platform
+ *   the store calls failed). A 5xx is transient (`retryable: true`); a 4xx is
+ *   caller-caused, so the helpers below downgrade those to non-retryable.
+ * - Timeouts are `dependency` and `retryable: true` (the request may simply be
+ *   slow).
+ */
+declare const MEMORY_ERROR_REGISTRY: Readonly<Record<MemoryErrorCode, MemoryErrorRegistryEntry>>;
+/**
+ * An `Error` carrying a stable memory error `code`, `category`, and `retryable`
+ * flag so consumers and observability can branch on it without string-matching
+ * the message.
+ *
+ * It is a real `Error` subclass: `instanceof Error` is true, so the public
+ * `MemoryState.error: Error | null` contract (and the `error: Error | null`
+ * surfaced by `useMemories` / `injectMemories`) holds unchanged. Existing
+ * consumers that only read `.message` keep working; the richer fields are
+ * additive.
+ */
+declare class MemoryError extends Error {
+  /** Stable, machine-readable error identifier. */
+  readonly code: MemoryErrorCode;
+  /** Coarse error category for grouping/observability. */
+  readonly category: MemoryErrorCategory;
+  /** Whether retrying the operation could plausibly succeed. */
+  readonly retryable: boolean;
+  /**
+   * @param code - Registry code identifying this error.
+   * @param options - Optional overrides:
+   *   - `message`: human-readable message (defaults to the registry message;
+   *     callers pass a status-bearing string to preserve prior wording).
+   *   - `retryable`: overrides the registry default (e.g. a 4xx list failure is
+   *     not retryable even though the code's default is).
+   *   - `cause`: the underlying error, preserved for debugging.
+   */
+  constructor(code: MemoryErrorCode, options?: {
+    message?: string;
+    retryable?: boolean;
+    cause?: unknown;
+  });
+}
+/**
+ * Narrows an HTTP status to whether the failure is worth retrying: a 5xx (or a
+ * missing/0 status) is a transient dependency failure and retryable; a 4xx is
+ * caller-caused and not. Used so a `MEMORY_LIST_FAILED`/`MEMORY_MUTATION_FAILED`
+ * carries an accurate `retryable` flag derived from the response status.
+ */
+declare function isRetryableStatus(status: number): boolean;
+//#endregion
+//#region src/memory.d.ts
+/** Public, customer-facing memory kind vocabulary (single taxonomy, no mapping). */
+type MemoryKind = "topical" | "episodic" | "operational";
+/** Visibility scope of a memory. */
+type MemoryScope = "user" | "project";
+/**
+ * Health of the realtime (`user_meta:memories:<code>`) connection that streams
+ * live `memory_metadata` deltas. Distinct from `available`/`error`, which
+ * describe the REST list route: `realtimeStatus` reports ONLY whether the
+ * realtime socket/channel is live so the UI can stop showing a "live" indicator
+ * over a frozen snapshot once the socket permanently gives up.
+ *
+ * - `"connecting"` — fetching join credentials / opening the socket / joining
+ *   the channel (the default, and the state every `contextChanged`/`stopped`
+ *   resets to).
+ * - `"connected"` — the channel join succeeded; live deltas are flowing.
+ * - `"unavailable"` — the socket exhausted its retries or the join failed
+ *   permanently; the snapshot is frozen and no deltas will arrive. This is a
+ *   silent degrade for `available`/`error` (those stay untouched) — only this
+ *   signal flips.
+ */
+type MemoryRealtimeStatus = "connecting" | "connected" | "unavailable";
+/**
+ * A memory as projected across the public REST/realtime boundary — the minimal
+ * shape the SDK surfaces. Mirrors the server's `PublicMemory` projection.
+ */
+interface Memory {
+  id: string;
+  kind: MemoryKind;
+  scope: MemoryScope;
+  content: string;
+  sourceThreadIds: readonly string[];
+  invalidatedAt: string | null;
+}
+/** Input for creating a memory; `scope` defaults to `"user"` (v1 is user-scoped). */
+interface NewMemory {
+  content: string;
+  kind: MemoryKind;
+  scope?: MemoryScope;
+  sourceThreadIds?: readonly string[];
+}
+/**
+ * New values for superseding (updating) a memory — same shape as create.
+ *
+ * Supersede is a FULL replacement, not a partial patch: this is the complete
+ * definition of the new memory that replaces the old one. `content` and `kind`
+ * are required and must be re-supplied, and an omitted `sourceThreadIds` resets
+ * the new memory's source threads to `[]` — it does NOT preserve the prior
+ * memory's value.
+ */
+type MemoryChanges = NewMemory;
+/** Outcome of a mutation, tracked so the caller's promise resolves/rejects. */
+type MemoryMutationOutcome = {
+  requestId: string;
+  sessionId: number;
+  ok: true;
+  memory: Memory | null;
+} | {
+  requestId: string;
+  sessionId: number;
+  ok: false;
+  error: Error;
+};
+/**
+ * Runtime wiring for the memory store: where to reach the REST surface and the
+ * headers (auth + `X-Cpki-User-Id`) to send. Scoped to the current user; v1
+ * surfaces user-scoped memories only.
+ */
+interface MemoryRuntimeContext {
+  runtimeUrl: string;
+  /** WebSocket URL for the realtime gateway (e.g. `wss://gw.example.com/client`). */
+  wsUrl: string;
+  headers: Record<string, string>;
+  includeInvalidated?: boolean;
+}
+/**
+ * In-memory state for the memory store. Session-guarded like the thread store:
+ * `sessionId` is bumped whenever the runtime context changes so that responses
+ * and realtime deltas from a previous context are ignored.
+ */
+interface MemoryState {
+  memories: Memory[];
+  isLoading: boolean;
+  inFlightMutationCount: number;
+  error: Error | null;
+  context: MemoryRuntimeContext | null;
+  sessionId: number;
+  available: boolean;
+  realtimeStatus: MemoryRealtimeStatus;
+}
+declare const memoryDomainEvents: ActionGroupResult<"Memory Domain", {
+  readonly memoryUpserted: PropsActionConfig<{
+    sessionId: number;
+    memory: Memory;
+  }>;
+  readonly memoryInvalidated: PropsActionConfig<{
+    sessionId: number;
+    memoryId: string;
+  }>;
+  readonly realtimeConnecting: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly realtimeConnected: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly realtimeUnavailable: PropsActionConfig<{
+    sessionId: number;
+  }>;
+}>;
+/** Wire shape of a memory inside a `memory_metadata` payload (carries tenant ids). */
+interface MemoryMetadataPayloadMemory extends Memory {
+  organizationId: string;
+  projectId: string;
+}
+/**
+ * The realtime `memory_metadata` event broadcast on the `user_meta` channel:
+ * `created`/`updated` carry the full memory, `invalidated` carries only its id.
+ * The gateway strips `userId` before broadcasting and only delivers
+ * user-scoped memories, so this is always the current user's stream.
+ */
+type MemoryMetadataEvent = {
+  operation: "created" | "updated";
+  memoryId: string;
+  organizationId: string;
+  projectId: string;
+  occurredAt: string;
+  memory: MemoryMetadataPayloadMemory;
+} | {
+  operation: "invalidated";
+  memoryId: string;
+  organizationId: string;
+  projectId: string;
+  occurredAt: string;
+  invalidated: {
+    id: string;
+  };
+};
+/**
+ * Maps a realtime `memory_metadata` event to the domain action that applies it:
+ * `created`/`updated` upsert the projected memory, `invalidated` removes it by
+ * id. Carries the current `sessionId` so the reducer's session guard can drop
+ * deltas left over from a previous context.
+ */
+declare function mapMemoryMetadataEvent(event: MemoryMetadataEvent, sessionId: number): ReturnType<typeof memoryDomainEvents.memoryUpserted> | ReturnType<typeof memoryDomainEvents.memoryInvalidated>;
+/**
+ * Dependencies injected into the memory store. The store opens its own
+ * `user_meta:memories:<joinCode>` socket/channel and does not share the
+ * thread store's socket, so only a `fetch` implementation is required.
+ */
+interface MemoryEnvironment {
+  fetch: typeof fetch;
+}
+interface MemoryStore {
+  start(): void;
+  stop(): void;
+  setContext(context: MemoryRuntimeContext | null): void;
+  /**
+   * Re-fetches the REST snapshot without clearing the current list. Resolves
+   * once the re-pull settles (success or failure) for the current context, so
+   * callers (e.g. a `useMemories` `refresh()`) can await it. Resolves
+   * immediately when no context is set.
+   */
+  refresh(): Promise<void>;
+  /** Creates a memory; resolves to the stored memory (server-authoritative). */
+  addMemory(input: NewMemory): Promise<Memory>;
+  /** Supersedes a memory; resolves to the new memory (its id changes). */
+  updateMemory(id: string, changes: MemoryChanges): Promise<Memory>;
+  /** Retires a memory (non-lossy delete). */
+  removeMemory(id: string): Promise<void>;
+  getState(): MemoryState;
+  /**
+   * Stable, render-safe state for SSR/prerender. React's
+   * `useSyncExternalStore` requires a `getServerSnapshot` during SSR/prerender
+   * (e.g. Next.js); without one React throws "Missing getServerSnapshot". The
+   * returned reference is stable across calls so React does not loop. There is
+   * no client-side memory data during prerender, so this is the empty initial
+   * state (no memories, not loading, no error).
+   */
+  getServerState(): MemoryState;
+  select: Store<MemoryState>["select"];
+}
+/**
+ * Creates the framework-agnostic memory store: a REST snapshot on `setContext`,
+ * server-authoritative add/update/remove mutations, and realtime
+ * `memory_metadata` deltas off the injected `user_meta` event source — all
+ * reduced into observable state.
+ */
+declare function createMemoryStore(environment: MemoryEnvironment): MemoryStore;
+type ɵMemoryState = MemoryState;
+type ɵMemoryRuntimeContext = MemoryRuntimeContext;
+type ɵMemoryMetadataEvent = MemoryMetadataEvent;
+type ɵMemoryEnvironment = MemoryEnvironment;
+type ɵMemoryStore = MemoryStore;
+declare const ɵmemoryAdapterEvents: ActionGroupResult<"Memory Adapter", {
+  readonly started: EmptyActionConfig;
+  readonly stopped: EmptyActionConfig;
+  readonly contextChanged: PropsActionConfig<{
+    context: MemoryRuntimeContext | null;
+  }>;
+  readonly addRequested: PropsActionConfig<{
+    requestId: string;
+    input: NewMemory;
+  }>;
+  readonly updateRequested: PropsActionConfig<{
+    requestId: string;
+    id: string;
+    changes: MemoryChanges;
+  }>;
+  readonly removeRequested: PropsActionConfig<{
+    requestId: string;
+    id: string;
+  }>;
+}>;
+declare const ɵmemoryRestEvents: ActionGroupResult<"Memory REST", {
+  readonly listRequested: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly listSucceeded: PropsActionConfig<{
+    sessionId: number;
+    memories: Memory[];
+  }>;
+  readonly listFailed: PropsActionConfig<{
+    sessionId: number;
+    error: Error;
+  }>;
+  readonly listUnavailable: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly mutationFinished: PropsActionConfig<{
+    outcome: MemoryMutationOutcome;
+  }>;
+  readonly credentialsRequested: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly credentialsSucceeded: PropsActionConfig<{
+    sessionId: number;
+    joinToken: string;
+    joinCode: string;
+  }>;
+  readonly credentialsFailed: PropsActionConfig<{
+    sessionId: number;
+    error: Error;
+  }>;
+  readonly credentialsUnavailable: PropsActionConfig<{
+    sessionId: number;
+  }>;
+}>;
+declare const ɵmemoryDomainEvents: ActionGroupResult<"Memory Domain", {
+  readonly memoryUpserted: PropsActionConfig<{
+    sessionId: number;
+    memory: Memory;
+  }>;
+  readonly memoryInvalidated: PropsActionConfig<{
+    sessionId: number;
+    memoryId: string;
+  }>;
+  readonly realtimeConnecting: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly realtimeConnected: PropsActionConfig<{
+    sessionId: number;
+  }>;
+  readonly realtimeUnavailable: PropsActionConfig<{
+    sessionId: number;
+  }>;
+}>;
+declare const ɵmemoryReducer: Reducer<MemoryState>;
+declare const ɵmapMemoryMetadataEvent: typeof mapMemoryMetadataEvent;
+declare const ɵselectMemories: Selector<MemoryState, Memory[]>;
+declare const ɵselectMemoriesIsLoading: Selector<MemoryState, boolean>;
+declare const ɵselectMemoriesError: Selector<MemoryState, Error | null>;
+declare const ɵselectMemoriesIsMutating: Selector<MemoryState, boolean>;
+declare const ɵselectMemoriesAvailable: Selector<MemoryState, boolean>;
+declare const ɵselectMemoriesRealtimeStatus: Selector<MemoryState, MemoryRealtimeStatus>;
+//#endregion
 //#region src/core/core.d.ts
 /** Configuration options for `CopilotKitCore`. */
 interface CopilotKitCoreConfig {
@@ -1012,6 +1417,15 @@ interface CopilotKitCoreConfig {
   runtimeUrl?: string;
   /** Transport style for CopilotRuntime endpoints. Defaults to REST. */
   runtimeTransport?: CopilotRuntimeTransport;
+  /**
+   * When true, the constructor sets the runtime config but does NOT start the
+   * `/info` connection. Call {@link CopilotKitCore.connect} to start it —
+   * typically from a host's commit-phase effect. This prevents a burst of
+   * duplicate `/info` requests when a host constructs (and discards) the core
+   * during render, e.g. React concurrent rendering / Suspense / StrictMode.
+   * See https://github.com/CopilotKit/CopilotKit/issues/5801.
+   */
+  deferInitialConnection?: boolean;
   /** Mapping from agent name to its `AbstractAgent` instance. For development only - production requires CopilotRuntime. */
   agents__unsafe_dev_only?: Record<string, AbstractAgent>;
   /**
@@ -1276,6 +1690,13 @@ declare class CopilotKitCore {
   private runHandler;
   private stateManager;
   private threadStoreRegistry;
+  /**
+   * The single core-owned memory store, created lazily on first
+   * `getMemoryStore()` and kept user-scoped for the lifetime of the core.
+   * Its runtime context is wired by the core itself (see `syncMemoryContext`),
+   * so callers never register or look it up by `agentId`.
+   */
+  private _memoryStore?;
   /**
    * Tracks the agent IDs from the most recent `onAgentsChanged` notification.
    * Used to gate thread-store auto-unregister so the FIRST empty-agents
@@ -1286,6 +1707,7 @@ declare class CopilotKitCore {
   constructor({
     runtimeUrl,
     runtimeTransport,
+    deferInitialConnection,
     headers,
     credentials,
     properties,
@@ -1315,6 +1737,16 @@ declare class CopilotKitCore {
   get tools(): Readonly<FrontendTool<any>[]>;
   get runtimeUrl(): string | undefined;
   setRuntimeUrl(runtimeUrl: string | undefined): void;
+  /**
+   * Start the runtime `/info` connection if it has not been started yet.
+   *
+   * Intended to be driven from a host's commit-phase effect when the core was
+   * constructed with {@link CopilotKitCoreConfig.deferInitialConnection}. Safe
+   * to call repeatedly — it is a no-op once a connection is in progress or
+   * settled, so a double-invoked mount effect (React StrictMode) collapses to a
+   * single request. See #5801.
+   */
+  connect(): void;
   get runtimeTransport(): CopilotRuntimeTransport;
   setRuntimeTransport(runtimeTransport: CopilotRuntimeTransport): void;
   get runtimeVersion(): string | undefined;
@@ -1342,6 +1774,7 @@ declare class CopilotKitCore {
   get runtimeMode(): RuntimeMode;
   get intelligence(): IntelligenceRuntimeInfo | undefined;
   get threadEndpoints(): ThreadEndpointRuntimeInfo | undefined;
+  get suggestions(): boolean | undefined;
   get a2uiEnabled(): boolean;
   /**
    * Agent ids the runtime applies A2UI to. `undefined` means A2UI applies to
@@ -1447,6 +1880,29 @@ declare class CopilotKitCore {
   unregisterThreadStore(agentId: string): void;
   getThreadStore(agentId: string): ɵThreadStore | undefined;
   getThreadStores(): Readonly<Record<string, ɵThreadStore>>;
+  /**
+   * Returns the single core-owned, user-scoped memory store, creating and
+   * starting it on first access. Unlike thread stores, memory is not scoped per
+   * agent: there is exactly one store whose runtime context the core wires
+   * itself (see `syncMemoryContext`), so consumers (e.g. a `useMemories`
+   * binding) just read this store rather than registering one.
+   */
+  getMemoryStore(): ɵMemoryStore;
+  /**
+   * Lazily creates, starts, and context-syncs the core-owned memory store on
+   * first access, then returns it. Subsequent calls return the existing store.
+   * The store is constructed with a bound `globalThis.fetch` and immediately
+   * has its runtime context synced from the current connection state.
+   */
+  private ensureMemoryStore;
+  /**
+   * Pushes the current runtime wiring into the memory store. When the runtime
+   * is connected and both the intelligence WebSocket URL and runtime URL are
+   * available, the store receives a context (runtime URL, WebSocket URL, and a
+   * copy of the current headers); otherwise its context is cleared. No-op when
+   * the store has not been created yet.
+   */
+  private syncMemoryContext;
   /**
    * Suggestions management (delegated to SuggestionEngine)
    */
@@ -1557,7 +2013,26 @@ declare class SuggestionEngine {
    */
   getSuggestions(agentId: string): CopilotKitCoreGetSuggestionsResult;
   /**
-   * Generate suggestions using a provider agent
+   * Generate suggestions by running a provider agent and extracting the
+   * `copilotkitSuggest` tool call from its streamed messages.
+   *
+   * Two transports, one set of mechanics: both seed an agent with the
+   * consumer's messages + state and the instruction, then `runAgent` with
+   * forced `copilotkitSuggest` tool choice, parsing suggestions as messages
+   * stream in via `onMessagesChanged`.
+   *
+   * - **Stateless** (runtime advertises `suggestions` and transport isn't
+   *   `single`): a stock `HttpAgent` pointed at `/agent/:id/suggest`. That
+   *   endpoint runs the provider directly and streams AG-UI SSE **without**
+   *   persisting a thread, and a plain `HttpAgent` only ever speaks REST SSE —
+   *   it never routes through the Intelligence websocket delegate (which would
+   *   persist a thread). This is the path that removes the thread flood.
+   * - **Fallback** (capability absent → old runtime, or `single` transport):
+   *   clone the provider agent and run it client-side, as before.
+   *
+   * Gated to non-`single` transports because this client only builds the
+   * multi-route `/agent/:id/suggest` URL; single-route deployments (not the
+   * persisting-thread/Intelligence case) fall through to the clone fallback.
    */
   private generateSuggestions;
   /**
@@ -1593,6 +2068,11 @@ declare class SuggestionEngine {
    */
   private addStaticSuggestions;
 }
+/**
+ * Detects an `AbortController`-driven cancellation so the stateless path can
+ * treat it as an expected (non-error) outcome on clear/reload.
+ */
+declare function isAbortError(error: unknown): boolean;
 //#endregion
 //#region src/core/state-manager.d.ts
 /**
@@ -1982,5 +2462,5 @@ type ɵCopilotKitFeature = (typeof ɵCOPILOTKIT_FEATURES)[number];
  */
 declare function ɵisCopilotKitFeature(name: string): name is ɵCopilotKitFeature;
 //#endregion
-export { ActionConfig, ActionCreator, ActionFromCreator, ActionFromCreators, ActionGroupConfig, ActionGroupResult, AgentRegistry, AgentThreadLockedError, AnyAction, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, CopilotKitCoreFriendsAccess, CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRegisterProxiedAgentParams, type CopilotKitCoreRegisterProxiedAgentResult, type CopilotKitCoreRunAgentParams, type CopilotKitCoreRunToolParams, type CopilotKitCoreRunToolResult, CopilotKitCoreRuntimeConnectionStatus, CopilotKitCoreStopAgentParams, CopilotKitCoreSubscriber, CopilotKitCoreSubscription, CopilotRuntimeTransport, DispatchingEffect, DispatchingEffectOptions, DynamicSuggestionsConfig, Effect, EmptyActionConfig, FrontendTool, FrontendToolHandlerContext, IntelligenceAgent, IntelligenceAgentConfig, type IntelligenceRuntimeInfo, NonDispatchingEffect, NonDispatchingEffectOptions, PropsActionConfig, ProxiedCopilotRuntimeAgent, ProxiedCopilotRuntimeAgentConfig, Reducer, RunCompletionAware, RunHandler, type RuntimeLicenseStatus, type RuntimeMode, ScopedContext, Selector, StateManager, StaticSuggestionsConfig, Store, StoreLifecycleAction, SubscribeToAgentOptions, SubscribeToAgentSubscriber, Suggestion, SuggestionAvailability, SuggestionEngine, SuggestionsConfig, type ThreadEndpointRuntimeInfo, ThreadRunActivityNotification, ToolCallStatus, completePartialMarkdown, createActionGroup, createEffect, createReducer, createSelector, createStore, empty, ensureObjectArgs, isRunCompletionAware, ofType, on, parseToolArguments, props, select, ɵCOPILOTKIT_FEATURES, ɵCopilotKitFeature, ɵMAX_SOCKET_RETRIES, ɵPhoenixChannelLike, ɵPhoenixChannelOptions, ɵPhoenixChannelSession, ɵPhoenixJoinOutcome, ɵPhoenixPushLike, ɵPhoenixSocketLike, ɵPhoenixSocketOptions, ɵPhoenixSocketSession, ɵPhoenixSocketSignal, ɵThread, ɵThreadEnvironment, ɵThreadMetadataEvent, ɵThreadRuntimeContext, ɵThreadSelectors, ɵThreadStore, ɵcreateThreadSelectors, createThreadStore as ɵcreateThreadStore, ɵisCopilotKitFeature, ɵjoinPhoenixChannel$, ɵobservePhoenixEvent$, ɵobservePhoenixJoinOutcome$, ɵobservePhoenixSocketHealth$, ɵobservePhoenixSocketSignals$, ɵphoenixChannel$, ɵphoenixSocket$, ɵselectHasNextPage, ɵselectIsFetchingNextPage, ɵselectIsMutating, ɵselectThreads, ɵselectThreadsError, ɵselectThreadsIsLoading, ɵthreadAdapterEvents };
+export { ActionConfig, ActionCreator, ActionFromCreator, ActionFromCreators, ActionGroupConfig, ActionGroupResult, AgentRegistry, AgentThreadLockedError, AnyAction, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, CopilotKitCoreFriendsAccess, CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRegisterProxiedAgentParams, type CopilotKitCoreRegisterProxiedAgentResult, type CopilotKitCoreRunAgentParams, type CopilotKitCoreRunToolParams, type CopilotKitCoreRunToolResult, CopilotKitCoreRuntimeConnectionStatus, CopilotKitCoreStopAgentParams, CopilotKitCoreSubscriber, CopilotKitCoreSubscription, CopilotRuntimeTransport, DispatchingEffect, DispatchingEffectOptions, DynamicSuggestionsConfig, Effect, EmptyActionConfig, FrontendTool, FrontendToolHandlerContext, IntelligenceAgent, IntelligenceAgentConfig, type IntelligenceRuntimeInfo, MEMORY_ERROR_REGISTRY, Memory, MemoryChanges, MemoryError, type MemoryErrorCategory, type MemoryErrorCode, type MemoryErrorRegistryEntry, MemoryKind, MemoryRealtimeStatus, MemoryScope, NewMemory, NonDispatchingEffect, NonDispatchingEffectOptions, PropsActionConfig, ProxiedCopilotRuntimeAgent, ProxiedCopilotRuntimeAgentConfig, Reducer, RunCompletionAware, RunHandler, type RuntimeLicenseStatus, type RuntimeMode, ScopedContext, Selector, StateManager, StaticSuggestionsConfig, Store, StoreLifecycleAction, SubscribeToAgentOptions, SubscribeToAgentSubscriber, Suggestion, SuggestionAvailability, SuggestionEngine, SuggestionsConfig, type ThreadEndpointRuntimeInfo, ThreadRunActivityNotification, ToolCallStatus, completePartialMarkdown, createActionGroup, createEffect, createReducer, createSelector, createStore, empty, ensureObjectArgs, isAbortError, isRunCompletionAware, ofType, on, parseToolArguments, props, select, ɵCOPILOTKIT_FEATURES, ɵCopilotKitFeature, ɵMAX_SOCKET_RETRIES, ɵMemoryEnvironment, ɵMemoryMetadataEvent, ɵMemoryRuntimeContext, ɵMemoryState, ɵMemoryStore, ɵPhoenixChannelLike, ɵPhoenixChannelOptions, ɵPhoenixChannelSession, ɵPhoenixJoinOutcome, ɵPhoenixPushLike, ɵPhoenixSocketLike, ɵPhoenixSocketOptions, ɵPhoenixSocketSession, ɵPhoenixSocketSignal, ɵThread, ɵThreadEnvironment, ɵThreadMetadataEvent, ɵThreadRuntimeContext, ɵThreadSelectors, ɵThreadStore, createMemoryStore as ɵcreateMemoryStore, ɵcreateThreadSelectors, createThreadStore as ɵcreateThreadStore, ɵisCopilotKitFeature, isRetryableStatus as ɵisRetryableMemoryStatus, ɵjoinPhoenixChannel$, ɵmapMemoryMetadataEvent, ɵmemoryAdapterEvents, ɵmemoryDomainEvents, ɵmemoryReducer, ɵmemoryRestEvents, ɵobservePhoenixEvent$, ɵobservePhoenixJoinOutcome$, ɵobservePhoenixSocketHealth$, ɵobservePhoenixSocketSignals$, ɵphoenixChannel$, ɵphoenixSocket$, ɵselectFetchMoreError, ɵselectHasNextPage, ɵselectIsFetchingNextPage, ɵselectIsMutating, ɵselectMemories, ɵselectMemoriesAvailable, ɵselectMemoriesError, ɵselectMemoriesIsLoading, ɵselectMemoriesIsMutating, ɵselectMemoriesRealtimeStatus, ɵselectThreads, ɵselectThreadsError, ɵselectThreadsIsLoading, ɵthreadAdapterEvents };
 //# sourceMappingURL=index.d.mts.map