@copilotkit/runtime 2.0.0-next.1 → 2.0.0-rc.0

package/dist/runtime/intelligence-platform/client.d.mts

@@ -0,0 +1,824 @@
+import { ExperimentalLearningManagement } from "./experimental.mjs";
+import { GetLearningContainerId, GetTrajectoryLearningContainerIds } from "../core/learning.mjs";
+import { TrajectoryConnectionGrant } from "./trajectories.mjs";
+import { GetLearnedSkillsSnapshotRequest, GetLearnedSkillsSnapshotsRequest, LearnedSkillsBatchResult, LearnedSkillsSnapshotResult } from "./learned-skills.mjs";
+import { InspectorLearningRequestV1, InspectorLearningSnapshotV1, InspectorMetadataV1, RuntimeEntitlementResponse } from "@copilotkit/shared";
+
+//#region src/runtime/intelligence-platform/client.d.ts
+interface RuntimeMemoryGrant {
+  readonly user: "none" | "read" | "read-write";
+  readonly project: "none" | "read" | "read-write";
+}
+/**
+ * Error thrown when a CopilotKit Intelligence HTTP request returns a non-2xx
+ * status. Carries the HTTP {@link status} code so callers can branch on
+ * specific failures (e.g. 404 for "not found", 409 for "conflict") without
+ * parsing the error message string.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await intelligence.getThread({ threadId, userId });
+ * } catch (error) {
+ *   if (error instanceof PlatformRequestError && error.status === 404) {
+ *     // thread does not exist yet
+ *   }
+ * }
+ * ```
+ */
+declare class PlatformRequestError extends Error {
+  /** The HTTP status code returned by the platform (e.g. 404, 409, 500). */
+  readonly status: number;
+  /** Whether retrying may succeed without changing client configuration. */
+  readonly retryable?: boolean;
+  /** Stable backend error code, when supplied by a validated error envelope. */
+  readonly code?: string;
+  constructor(message: string, /** The HTTP status code returned by the platform (e.g. 404, 409, 500). */status: number, /** Whether retrying may succeed without changing client configuration. */retryable?: boolean, /** Stable backend error code, when supplied by a validated error envelope. */code?: string);
+}
+/** Payload passed to `onThreadDeleted` listeners. */
+interface ThreadDeletedPayload {
+  threadId: string;
+  userId: string;
+  agentId: string;
+}
+interface CopilotKitIntelligenceConfig {
+  /**
+   * Base URL of the CopilotKit Intelligence API.
+   *
+   * Defaults to CopilotKit's managed platform,
+   * `https://api.intelligence.copilotkit.ai`. Set it only when pointing at a
+   * self-hosted or non-production deployment — and set {@link wsUrl} with it.
+   */
+  apiUrl?: string;
+  /**
+   * Intelligence websocket base URL. Runner and client socket URLs are derived
+   * from this by appending `/runner` or `/client`, so pass the bare base.
+   *
+   * Defaults to CopilotKit's managed platform,
+   * `wss://realtime.intelligence.copilotkit.ai`.
+   *
+   * This is a DIFFERENT host from {@link apiUrl} — the API and realtime planes are
+   * deployed separately — so it cannot be derived by scheme-swapping `apiUrl`.
+   * Overriding one without the other therefore points the two planes at
+   * different deployments, which logs a warning.
+   */
+  wsUrl?: string;
+  /** API key for authenticating with CopilotKit Intelligence */
+  apiKey: string;
+  /**
+   * Chooses the stable Learning Container ID for each Intelligence run.
+   * The callback receives the resolved application user and AG-UI run input.
+   * It must return the same ID for every run on one Thread because a Thread
+   * cannot move between Learning Containers after its first assignment.
+   * Return `null` or `undefined` to leave the Thread unassigned.
+   */
+  getLearningContainerId?: GetLearningContainerId;
+  /**
+   * Assigns a Trajectory to existing Learning Spaces using server-resolved user
+   * identity. Browser-supplied assignments are ignored. Return null or undefined
+   * to leave activity unassigned. Reconnects call the selector again; keep the
+   * selection stable for a Trajectory because assignments are additive.
+   */
+  getTrajectoryLearningContainerIds?: GetTrajectoryLearningContainerIds;
+  /**
+   * Enable Enterprise Learning — expose CopilotKit Intelligence's
+   * built-in tools (bash + thread/memory tools) to agent runs on an
+   * intelligence runtime that resolve a user. Attached uniformly across
+   * agent frameworks by `attachIntelligenceEnterpriseLearning` via
+   * `@ag-ui/mcp-middleware`, with the resolved user-id and project apiKey
+   * baked into the transport headers for that request's clone.
+   *
+   * Defaults to `false` — opt-in. Existing intelligence setups continue
+   * to work without these tools unless they flip this flag.
+   *
+   * @deprecated Configure `memory.access` on `CopilotRuntime` so each web
+   * request receives an explicit agent or client Memory grant.
+   */
+  enableEnterpriseLearning?: boolean;
+  /**
+   * Initial listener invoked after a thread is created.
+   * Prefer {@link CopilotKitIntelligence.onThreadCreated} for multiple listeners.
+   */
+  onThreadCreated?: (thread: ThreadSummary) => void;
+  /**
+   * Initial listener invoked after a thread is updated.
+   * Prefer {@link CopilotKitIntelligence.onThreadUpdated} for multiple listeners.
+   */
+  onThreadUpdated?: (thread: ThreadSummary) => void;
+  /**
+   * Initial listener invoked after a thread is deleted.
+   * Prefer {@link CopilotKitIntelligence.onThreadDeleted} for multiple listeners.
+   */
+  onThreadDeleted?: (params: ThreadDeletedPayload) => void;
+}
+/**
+ * Summary metadata for a single thread returned by the platform.
+ *
+ * This is the shape returned by list, get, create, and update operations.
+ * It does not include the thread's message history — use
+ * {@link CopilotKitIntelligence.getThreadMessages} for that.
+ */
+interface ThreadSummary {
+  /** Existing Learning membership for single-container Threads; null for zero or multiple memberships. */
+  learningContainerId?: string | null;
+  /** Existing Learning memberships. Absent on older platform responses; do not infer a new assignment from absence. */
+  learningContainerIds?: string[];
+  /** Platform-assigned unique identifier. */
+  id: string;
+  /** Human-readable display name, or `null` if the thread has not been named. */
+  name: string | null;
+  /** ISO-8601 timestamp of the most recent agent run on this thread. */
+  lastRunAt?: string;
+  /** ISO-8601 timestamp of the most recent metadata update. */
+  lastUpdatedAt?: string;
+  /** ISO-8601 timestamp when the thread was created. */
+  createdAt?: string;
+  /** ISO-8601 timestamp when the thread was last updated. */
+  updatedAt?: string;
+  /** Whether the thread has been archived. Archived threads are excluded from default list results. */
+  archived?: boolean;
+  /** The agent that owns this thread. */
+  agentId?: string;
+  /** The user who created this thread. */
+  createdById?: string;
+  /** The organization this thread belongs to. */
+  organizationId?: string;
+}
+/** Response from listing threads for a user/agent pair. */
+interface ListThreadsResponse {
+  /** The matching threads, sorted by the platform's default ordering. */
+  threads: ThreadSummary[];
+  /** Join code for subscribing to realtime metadata updates for these threads. */
+  joinCode: string;
+  /** Short-lived token for authenticating the realtime subscription. */
+  joinToken?: string;
+  /** Opaque cursor for fetching the next page. `null` or absent when there are no more pages. */
+  nextCursor?: string | null;
+}
+/**
+ * A single memory as returned by the platform's list endpoint. Mirrors the
+ * public projection the client memory store consumes (tenant ids stripped).
+ */
+interface MemorySummary {
+  /** Platform-assigned unique identifier. */
+  id: string;
+  /** Memory kind, e.g. `"topical"`, `"episodic"`, `"operational"`. */
+  kind: string;
+  /** Memory scope: `"user"` (private) or `"project"` (shared). */
+  scope: string;
+  /** The remembered fact, preference, or procedure. */
+  content: string;
+  /** Ids of the threads this memory was learned from. */
+  sourceThreadIds: string[];
+  /** ISO-8601 timestamp when the memory was retired, or `null` if live. */
+  invalidatedAt: string | null;
+  /** Relevance score from a `recall` (hybrid RAG) query. Present only on recall responses. */
+  score?: number;
+}
+/** Response from {@link CopilotKitIntelligence.listMemories}. */
+interface ListMemoriesResponse {
+  memories: MemorySummary[];
+}
+/** Response from {@link CopilotKitIntelligence.recallMemories}. */
+interface RecallMemoriesResponse {
+  memories: MemorySummary[];
+}
+/**
+ * Response from a create ({@link CopilotKitIntelligence.createMemory}) or
+ * supersede ({@link CopilotKitIntelligence.updateMemory}) call: the stored
+ * memory, plus the operation-specific marker the client store consumes.
+ */
+interface SaveMemoryResponse extends MemorySummary {
+  /** Create only: content was merged into a near-duplicate, not inserted new. */
+  absorbed?: boolean;
+  /** Supersede only: the id of the memory retired by this call. */
+  retiredId?: string;
+}
+/**
+ * Fields that can be updated on a thread via {@link CopilotKitIntelligence.updateThread}.
+ *
+ * Additional platform-specific fields can be passed as extra keys and will be
+ * forwarded to the PATCH request body.
+ */
+interface UpdateThreadRequest {
+  /** New human-readable display name for the thread. */
+  name?: string;
+  [key: string]: unknown;
+}
+/** Parameters for creating a new thread via {@link CopilotKitIntelligence.createThread}. */
+interface CreateThreadRequest {
+  /** Client-generated unique identifier for the new thread. */
+  threadId: string;
+  /** The user creating the thread. Used for authorization and scoping. */
+  userId: string;
+  /** The agent this thread belongs to. */
+  agentId: string;
+  /** Optional initial display name. If omitted, the thread is unnamed until explicitly renamed. */
+  name?: string;
+  /** Developer-set stable ID of the Learning Container for this Thread. */
+  learningContainerId?: string;
+}
+/** Credentials returned when locking or joining a thread's realtime channel. */
+interface ThreadConnectionResponse {
+  /** Canonical platform thread identifier for the run or connection. */
+  threadId: string;
+  /** Canonical platform run identifier for an active run lock. */
+  runId?: string;
+  /** Short-lived token for authenticating the Phoenix channel join. */
+  joinToken: string;
+  /** Lock metadata echoed back by the platform. */
+  lock?: ThreadLockInfo;
+}
+interface SubscribeToThreadsRequest {
+  userId: string;
+}
+interface SubscribeToThreadsResponse {
+  joinToken: string;
+}
+interface SubscribeToMemoriesRequest {
+  userId: string;
+  memoryGrant?: RuntimeMemoryGrant;
+}
+/**
+ * Memory subscribe returns both the token and the join code, unlike threads
+ * (whose join code reaches the client via the thread-list response). Memory has
+ * no list-borne code, so the code is delivered here and used to build the
+ * `user_meta:memories:<joinCode>` channel topic.
+ */
+interface SubscribeToMemoriesResponse {
+  joinToken?: string;
+  joinCode?: string;
+  /**
+   * Project-scoped realtime credentials, minted by the platform only when the
+   * caller's API key resolves to a project scope. Absent when project scope is
+   * unavailable — a silent-degrade contract: the client then opens only the
+   * user channel. When present, the client builds the second
+   * `project_meta:memories:<projectJoinCode>` channel topic from them.
+   */
+  projectJoinToken?: string;
+  projectJoinCode?: string;
+}
+type ConnectThreadResponse = ThreadConnectionResponse | null;
+interface AcquireThreadLockResponse extends ThreadConnectionResponse {
+  /** Server-owned native ID for backend execution; public identity remains threadId. */
+  backendThreadId?: string;
+  /** Canonical platform run identifier for the acquired lock. */
+  runId: string;
+  /**
+   * Seconds the lock remains valid from acquisition, as set by the platform.
+   * The platform may ignore the requested TTL, so callers should trust this
+   * value. Absent on platforms that predate the field.
+   */
+  ttlSeconds?: number;
+}
+/**
+ * Parameters for annotating a thread event via
+ * {@link CopilotKitIntelligence.annotate}. The runtime resolves `userId`
+ * from the customer's BFF auth before calling this; the platform prefixes
+ * it with the project id at write time.
+ *
+ * `payload` is the type-specific JSON blob for the annotation (for example, a
+ * `"user_action"` event carries the recorded fields). The exact
+ * shape per type is validated by the Intelligence backend; canonical shapes
+ * are documented on the Intelligence react-core side.
+ */
+interface AnnotateParams {
+  /** The user the annotation belongs to. */
+  userId: string;
+  /** The thread the annotation is associated with. May be unknown to the platform. */
+  threadId: string;
+  /**
+   * Discriminator identifying the annotation type.
+   * Must match a type known to CopilotKit Intelligence
+   * (for example, `"user_action"`).
+   */
+  type: string;
+  /** Type-specific payload. Shape varies by `type`. */
+  payload?: unknown;
+  /**
+   * Caller-supplied idempotency key (any RFC-compliant UUID). When omitted,
+   * a UUID is auto-generated. Every call hits the platform's idempotent
+   * `PUT /connector/annotate/:clientEventId` endpoint; a retry with the
+   * same id collapses to the original row.
+   */
+  clientEventId?: string;
+  /** ISO-8601 client-asserted timestamp. Defaults to server NOW() when absent. */
+  occurredAt?: string;
+}
+/** Response from {@link CopilotKitIntelligence.annotate}. */
+interface AnnotateResponse {
+  /** Database id of the annotation row (BIGINT, returned as a string). */
+  id: string;
+  /**
+   * True when the platform recognized the `clientEventId` as a retry of
+   * a previous call and returned the original row id instead of inserting
+   * a new one.
+   */
+  duplicate: boolean;
+}
+/** A single message within a thread's persisted history. */
+interface ThreadMessage {
+  /** Unique identifier for this message. */
+  id: string;
+  /** Message role, e.g. `"user"`, `"assistant"`, `"tool"`. */
+  role: string;
+  /** Structured AG-UI content. May be absent for tool-call-only messages. */
+  content?: unknown;
+  /** Standard AG-UI activity type when `role` is `"activity"`. */
+  activityType?: string;
+  /** Tool calls initiated by this message (assistant role only). */
+  toolCalls?: Array<{
+    id: string;
+    name: string; /** JSON-encoded arguments passed to the tool. */
+    args: string;
+  }>;
+  /** For tool-result messages, the ID of the tool call this message responds to. */
+  toolCallId?: string;
+}
+/** Response from {@link CopilotKitIntelligence.getThreadMessages}. */
+interface ThreadMessagesResponse {
+  messages: ThreadMessage[];
+}
+/**
+ * Persisted AG-UI event for the inspector's debugging views. The platform
+ * stores raw events keyed by run; the `_inspect` route returns them in
+ * replay order (oldest first) across every run that targeted the thread.
+ */
+interface ThreadInspectEvent {
+  type: string;
+  [key: string]: unknown;
+}
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadEvents}. Mirrors the
+ * `ThreadEventsResult` shape returned by the platform's
+ * `GET /api/_inspect/threads/:id/events` endpoint.
+ */
+interface ThreadEventsResponse {
+  events: ThreadInspectEvent[];
+  /** Row IDs the platform failed to decode (raw column corrupted). */
+  decodeErrorRowIds: string[];
+  /** True when the platform hit its per-thread event cap. */
+  truncated: boolean;
+}
+/**
+ * Response from {@link CopilotKitIntelligence.getThreadState}. Mirrors the
+ * discriminated `ThreadStateResult` returned by the platform's
+ * `GET /api/_inspect/threads/:id/state` endpoint, which folds RFC 6902
+ * STATE_DELTA events on top of the latest STATE_SNAPSHOT.
+ */
+type ThreadStateResponse = {
+  kind: "no-snapshot";
+} | {
+  kind: "snapshot-decode-error";
+} | {
+  kind: "snapshot";
+  state: unknown;
+  skippedDeltas: number;
+};
+interface AcquireThreadLockRequest {
+  /** Caller can forward a server-owned native ID while retaining public ownership. */
+  supportsBackendThreadId?: boolean;
+  threadId: string;
+  runId: string;
+  userId: string;
+  agentId: string;
+  /** Developer-set stable ID to assign before the run lock is acquired. */
+  learningContainerId?: string;
+  /** Internal managed-Channel delivery context for shared Thread access. */
+  channelDeliveryId?: string;
+  /**
+   * The user request this run belongs to. Follow-up runs and resumes of one
+   * request send the same ID, so the platform counts the request once.
+   */
+  requestId?: string;
+  /** Custom Redis key prefix for the lock (default: "thread"). */
+  lockKeyPrefix?: string;
+  /** Lock TTL in seconds. When set, the lock auto-expires after this duration. */
+  ttlSeconds?: number;
+}
+interface RenewThreadLockRequest {
+  threadId: string;
+  runId: string;
+  /** New TTL to set on the lock in seconds. */
+  ttlSeconds: number;
+  /** Must match the prefix used when acquiring. */
+  lockKeyPrefix?: string;
+  /** Aborts the request, e.g. when the heartbeat gives up on this attempt. */
+  signal?: AbortSignal;
+}
+interface CleanupThreadLockRequest {
+  threadId: string;
+  runId: string;
+}
+interface RenewThreadLockResponse {
+  /**
+   * Seconds the lock remains valid from now, as set by the platform. The
+   * platform may ignore the requested TTL, so callers should trust this value.
+   * `0` when {@link status} is `"completed"`.
+   */
+  ttlSeconds: number;
+  threadId?: string;
+  runId?: string;
+  /**
+   * `"renewed"` when the lock was extended; `"completed"` when the run already
+   * reached a terminal event, so nothing was renewed and none is needed.
+   * Absent on platforms that predate the field.
+   */
+  status?: "renewed" | "completed";
+}
+interface ThreadLockInfo {
+  key: string;
+  ttlSeconds: number | null;
+}
+declare class CopilotKitIntelligence {
+  #private;
+  /** Experimental server-side APIs; their contracts may change before release. */
+  readonly experimental: {
+    readonly learning: ExperimentalLearningManagement;
+  };
+  constructor(config: CopilotKitIntelligenceConfig);
+  /**
+   * Register a listener invoked whenever a thread is created.
+   *
+   * Multiple listeners can be registered. Each call returns an unsubscribe
+   * function that removes the listener when called.
+   *
+   * @param callback - Receives the newly created {@link ThreadSummary}.
+   * @returns A function that removes this listener when called.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = intelligence.onThreadCreated((thread) => {
+   *   console.log("Thread created:", thread.id);
+   * });
+   * // later…
+   * unsubscribe();
+   * ```
+   */
+  onThreadCreated(callback: (thread: ThreadSummary) => void): () => void;
+  /**
+   * Register a listener invoked whenever a thread is updated (including archive).
+   *
+   * Multiple listeners can be registered. Each call returns an unsubscribe
+   * function that removes the listener when called.
+   *
+   * @param callback - Receives the updated {@link ThreadSummary}.
+   * @returns A function that removes this listener when called.
+   */
+  onThreadUpdated(callback: (thread: ThreadSummary) => void): () => void;
+  /**
+   * Register a listener invoked whenever a thread is deleted.
+   *
+   * Multiple listeners can be registered. Each call returns an unsubscribe
+   * function that removes the listener when called.
+   *
+   * @param callback - Receives the {@link ThreadDeletedPayload} identifying
+   *   the deleted thread.
+   * @returns A function that removes this listener when called.
+   */
+  onThreadDeleted(callback: (params: ThreadDeletedPayload) => void): () => void;
+  ɵgetApiUrl(): string;
+  ɵgetRunnerWsUrl(): string;
+  ɵgetClientWsUrl(): string;
+  ɵgetChannelsWsUrl(): string;
+  ɵgetRunnerAuthToken(): string;
+  /** @internal Used by `attachIntelligenceEnterpriseLearning` to populate `Authorization`. */
+  ɵgetApiKey(): string;
+  /** @internal Used by the Intelligence runtime to assign Learning Containers. */
+  ɵgetLearningContainerId(): GetLearningContainerId | undefined;
+  /** @internal Used by `attachIntelligenceEnterpriseLearning` to gate MCP attachment. */
+  ɵisEnterpriseLearningEnabled(): boolean;
+  /**
+   * Fetch one authorized learned-skills ZIP with this client's project key.
+   * No retries, archive parsing, or cache. A caller signal bounds the request
+   * and body read. Native cancellation is preserved; deadline failures use
+   * {@link LearnedSkillsError} with code `TIMEOUT`.
+   */
+  getLearnedSkillsSnapshot(params: GetLearnedSkillsSnapshotRequest): Promise<LearnedSkillsSnapshotResult>;
+  /** Fetch all requested containers in one authorized request, without retries. */
+  getLearnedSkillsSnapshots(params: GetLearnedSkillsSnapshotsRequest): Promise<LearnedSkillsBatchResult[]>;
+  /**
+   * Fetch trusted Inspector metadata for this runtime's Intelligence project.
+   *
+   * The request always uses the server-configured Intelligence API key. A 404
+   * is treated as compatible absence so runtimes can work with older App API
+   * deployments that do not expose this endpoint yet.
+   *
+   * @returns Sanitized V1 metadata, or `undefined` when the provider has no
+   *   supported metadata.
+   * @throws {@link PlatformRequestError} for provider failures other than 404.
+   */
+  getInspectorMetadata(): Promise<InspectorMetadataV1 | undefined>;
+  /** Fetches one credential-scoped, bounded Learning projection for Inspector. */
+  getInspectorLearning(request: InspectorLearningRequestV1 & {
+    readonly runtimeContainerId?: string;
+  }): Promise<InspectorLearningSnapshotV1>;
+  /**
+   * Resolve the Runtime entitlement projection for this project.
+   *
+   * Concurrent calls share one request. Active grants cache for 30 seconds;
+   * inactive results and failures cache for 5 seconds. Callers receive copies
+   * so they cannot mutate cached authority.
+   */
+  getRuntimeEntitlements(): Promise<RuntimeEntitlementResponse>;
+  /**
+   * Mint a browser capture grant using only the Runtime's project and user.
+   *
+   * Learning Container assignment never stops capture: a failed selection or
+   * an unknown Container is logged, and the Trajectory connects without
+   * assignments.
+   */
+  ɵconnectTrajectory(params: {
+    trajectoryId: string;
+    user: {
+      id: string;
+      name: string;
+    };
+    signal?: AbortSignal;
+  }): Promise<TrajectoryConnectionGrant>;
+  /**
+   * List all non-archived threads for a given user and agent.
+   *
+   * @param params.userId - User whose threads to list.
+   * @param params.agentId - Agent whose threads to list.
+   * @returns The thread list along with realtime subscription credentials.
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  listThreads(params: {
+    userId: string;
+    agentId: string;
+    includeArchived?: boolean;
+    limit?: number;
+    cursor?: string;
+  }): Promise<ListThreadsResponse>;
+  /**
+   * List the given user's long-term memories, newest first.
+   *
+   * The platform scopes by the opaque app user supplied in the
+   * `x-cpki-user-id` header (resolved by the runtime via `identifyUser`),
+   * not a query param. Pass `includeInvalidated` to also return retired rows.
+   *
+   * @returns The `{ memories }` envelope the client memory store consumes.
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  listMemories(params: {
+    userId: string;
+    memoryGrant?: RuntimeMemoryGrant;
+    includeInvalidated?: boolean;
+  }): Promise<ListMemoriesResponse>;
+  /**
+   * Create a memory for the given user (platform `POST /api/memories`).
+   * @returns The stored memory; `absorbed` is true if the content was merged
+   *   into a near-duplicate rather than inserted as a new row.
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  createMemory(params: {
+    userId: string;
+    memoryGrant?: RuntimeMemoryGrant;
+    content: string;
+    kind: string; /** Optional: when omitted, the platform applies its default (`"user"`). */
+    scope?: string;
+    sourceThreadIds?: string[];
+  }): Promise<SaveMemoryResponse>;
+  /**
+   * Supersede an existing memory (platform `PATCH /api/memories/:id`). The
+   * `:id` row is retired and a new memory with the supplied content is
+   * inserted atomically.
+   * @returns The new memory plus `retiredId` (the id of the retired row).
+   * @throws {@link PlatformRequestError} on non-2xx responses (e.g. 404 when
+   *   `:id` is not a live, same-scope memory for this user).
+   */
+  updateMemory(params: {
+    userId: string;
+    memoryGrant?: RuntimeMemoryGrant;
+    id: string;
+    content: string;
+    kind: string; /** Optional: when omitted, the platform applies its default (`"user"`). */
+    scope?: string;
+    sourceThreadIds?: string[];
+  }): Promise<SaveMemoryResponse>;
+  /**
+   * Non-lossily retire (forget) a memory (platform `DELETE /api/memories/:id`).
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  removeMemory(params: {
+    userId: string;
+    id: string;
+    memoryGrant?: RuntimeMemoryGrant;
+  }): Promise<void>;
+  /**
+   * 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.
+   */
+  recallMemories(params: {
+    userId: string;
+    memoryGrant?: RuntimeMemoryGrant;
+    query: string;
+    limit?: number;
+    scope?: string;
+  }): Promise<RecallMemoriesResponse>;
+  ɵsubscribeToThreads(params: SubscribeToThreadsRequest): Promise<SubscribeToThreadsResponse>;
+  /**
+   * 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. 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
+   * user — because the platform's memory routes resolve identity from that
+   * header, not the body. (This differs from `ɵsubscribeToThreads`, whose
+   * platform endpoint reads `userId` from the body.)
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  ɵsubscribeToMemories(params: SubscribeToMemoriesRequest): Promise<SubscribeToMemoriesResponse>;
+  /**
+   * Update thread metadata (e.g. name).
+   *
+   * Fields in updates take precedence, preserving the server-side SDK contract.
+   * HTTP handlers must remove untrusted identity fields before calling this method.
+   *
+   * Triggers the `onThreadUpdated` lifecycle callback on success.
+   *
+   * @returns The updated thread summary.
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  updateThread(params: {
+    threadId: string;
+    userId: string;
+    agentId: string;
+    updates: UpdateThreadRequest;
+  }): Promise<ThreadSummary>;
+  /**
+   * Create a new thread on the platform.
+   *
+   * Triggers the `onThreadCreated` lifecycle callback on success.
+   *
+   * @returns The newly created thread summary.
+   * @throws {@link PlatformRequestError} with status 409 if a thread with the
+   *   same `threadId` already exists.
+   */
+  createThread(params: CreateThreadRequest): Promise<ThreadSummary>;
+  /**
+   * Fetch a single thread by ID.
+   *
+   * @returns The thread summary.
+   * @throws {@link PlatformRequestError} with status 404 if the thread does
+   *   not exist.
+   */
+  getThread(params: {
+    threadId: string;
+    userId: string;
+  }): Promise<ThreadSummary>;
+  /**
+   * Get an existing thread or create it if it does not exist.
+   *
+   * Handles the race where a concurrent request creates the thread between
+   * the initial 404 and the subsequent `createThread` call by catching the
+   * 409 Conflict and retrying the get.
+   *
+   * Triggers the `onThreadCreated` lifecycle callback when a new thread is
+   * created.
+   *
+   * @returns An object containing the thread and a `created` flag indicating
+   *   whether the thread was newly created (`true`) or already existed (`false`).
+   * @throws {@link PlatformRequestError} on non-2xx responses other than
+   *   404 (get) and 409 (create race).
+   */
+  getOrCreateThread(params: CreateThreadRequest): Promise<{
+    thread: ThreadSummary;
+    created: boolean;
+  }>;
+  /**
+   * Fetch the full message history for a thread.
+   *
+   * @returns All persisted messages in chronological order.
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  getThreadMessages(params: {
+    threadId: string;
+    userId: string; /** Internal managed-Channel delivery context for shared Thread access. */
+    channelDeliveryId?: string;
+  }): Promise<ThreadMessagesResponse>;
+  /**
+   * @internal Fetch only the ids of a thread's persisted messages.
+   *
+   * Sends `fields=id` so the platform can omit message content. Platform
+   * versions that do not know the parameter ignore it and return the full
+   * transcript; ids are read from `messages[].id` either way.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  ɵgetThreadMessageIds(params: {
+    threadId: string;
+    userId: string; /** Internal managed-Channel delivery context for shared Thread access. */
+    channelDeliveryId?: string;
+  }): Promise<string[]>;
+  /** @internal Fetches one authorized managed Channel asset for history hydration. */
+  ɵgetManagedChannelAsset(assetId: string): Promise<{
+    bytes: Uint8Array;
+    mimeType?: string;
+  }>;
+  /**
+   * Fetch the persisted AG-UI event stream for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/events`
+   * introspection endpoint (see Intelligence PR #144). Events are returned
+   * in replay order across every run that targeted the thread. The
+   * `_inspect/` prefix flags this as debug-only — production code paths
+   * must not depend on it.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  getThreadEvents(params: {
+    threadId: string; /** The end user the read is for, as `identifyUser` returned it (not project-prefixed). */
+    userId: string;
+  }): Promise<ThreadEventsResponse>;
+  /**
+   * Fetch the current agent state for a thread.
+   *
+   * Backed by the platform's `GET /api/_inspect/threads/:id/state`
+   * introspection endpoint (see Intelligence PR #144). The platform folds
+   * RFC 6902 STATE_DELTA events on top of the latest STATE_SNAPSHOT, so
+   * the returned state reflects the thread's current state — not just the
+   * last snapshot. The discriminated response distinguishes "no snapshot
+   * persisted yet" from "snapshot present" so consumers can render the
+   * correct empty state.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  getThreadState(params: {
+    threadId: string; /** The end user the read is for, as `identifyUser` returned it (not project-prefixed). */
+    userId: string;
+  }): Promise<ThreadStateResponse>;
+  /**
+   * Mark a thread as archived.
+   *
+   * Archived threads are excluded from {@link listThreads} results.
+   * Triggers the `onThreadUpdated` lifecycle callback on success.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  archiveThread(params: {
+    threadId: string;
+    userId: string;
+    agentId: string;
+  }): Promise<void>;
+  /**
+   * Permanently delete a thread and its message history.
+   *
+   * This is irreversible. Triggers the `onThreadDeleted` lifecycle callback
+   * on success.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses.
+   */
+  deleteThread(params: {
+    threadId: string;
+    userId: string;
+    agentId: string;
+  }): Promise<void>;
+  /**
+   * Annotate a thread event on CopilotKit Intelligence's general annotation
+   * endpoint (`PUT /connector/annotate/:clientEventId`).
+   *
+   * This is the generalized replacement for the old
+   * `PUT /connector/user-actions/record/:clientEventId` endpoint. It supports
+   * multiple annotation types via the `type` discriminator. The
+   * `"user_action"` type records a user UI interaction for the self-learning
+   * loop.
+   *
+   * `userId` must be resolved on the runtime side before calling this — the
+   * platform prefixes it with the project id from the API key.
+   *
+   * Always hits the idempotent `PUT /connector/annotate/:clientEventId`
+   * endpoint. A retry with the same `clientEventId` returns
+   * `{ id: <original>, duplicate: true }` instead of creating a new row.
+   * When `clientEventId` is omitted, a UUID is auto-generated for this call.
+   *
+   * @throws {@link PlatformRequestError} on non-2xx responses, OR when the
+   *   platform returns an empty 2xx body (which would otherwise corrupt the
+   *   caller's typed result).
+   */
+  annotate(params: AnnotateParams): Promise<AnnotateResponse>;
+  ɵacquireThreadLock(params: AcquireThreadLockRequest): Promise<AcquireThreadLockResponse>;
+  ɵcleanupThreadLock(params: CleanupThreadLockRequest): Promise<void>;
+  ɵrenewThreadLock(params: RenewThreadLockRequest): Promise<RenewThreadLockResponse>;
+  ɵgetActiveJoinCode(params: {
+    threadId: string;
+    userId: string;
+  }): Promise<ThreadConnectionResponse>;
+  ɵconnectThread(params: {
+    threadId: string;
+    userId: string;
+    agentId: string;
+  }): Promise<ConnectThreadResponse>;
+}
+//#endregion
+export { CopilotKitIntelligence, CopilotKitIntelligenceConfig, CreateThreadRequest, ListThreadsResponse, PlatformRequestError, SubscribeToThreadsRequest, SubscribeToThreadsResponse, ThreadSummary, UpdateThreadRequest };
+//# sourceMappingURL=client.d.mts.map