@anuma/sdk 10.0.4 → 10.1.1

package/dist/server/index.d.mts

@@ -3954,6 +3954,159 @@ declare function makeSyntheticStoredMessage(opts: CreateMessageOptions): StoredM
  */
 declare function makeSyntheticStoredConversation(opts?: CreateConversationOptions, defaultTitle?: string): StoredConversation;
 
+/**
+ * Types for the conversation-memory storage module.
+ *
+ * A conversation-memory row links a conversation to a vault memory it drew on,
+ * so the conversation Memories panel survives reload. Only the memory id and
+ * recall score are stored; content lives in the encrypted memory_vault.
+ */
+/** Plain object representation of a conversation-memory record. */
+interface StoredConversationMemory {
+    /** WatermelonDB internal ID */
+    uniqueId: string;
+    /** The conversation this memory was drawn on in */
+    conversationId: string;
+    /** The memory_vault record id this row points at */
+    memoryId: string;
+    /** Recall relevance score (~0–1) at the time it was recorded */
+    score: number;
+    createdAt: Date;
+}
+/** One memory drawn on during a turn, passed to addConversationMemoriesOp. */
+interface ConversationMemoryInput {
+    memoryId: string;
+    score: number;
+}
+
+/**
+ * Minimal interface for an observable (reactive) query result.
+ *
+ * Shaped to be compatible with RxJS-style `Observable` (which is what
+ * WatermelonDB returns) and with a simple polling fallback, so non-reactive
+ * backends can implement it without depending on rxjs.
+ */
+interface ChatStorageObservable<T> {
+    subscribe(observer: {
+        next: (value: T) => void;
+        error?: (err: unknown) => void;
+        complete?: () => void;
+    }): {
+        unsubscribe: () => void;
+    };
+}
+/**
+ * Common filter options for conversation queries. Kept deliberately narrow —
+ * most call sites only need these.
+ */
+interface ConversationQueryOptions {
+    /** If set, only return conversations in this project. `null` = no project. */
+    projectId?: string | null;
+}
+/**
+ * Backend-agnostic interface for chat/conversation storage.
+ *
+ * The method set mirrors the operations we actually use across the SDK:
+ * `*Op` functions in `src/lib/db/chat/operations.ts` plus the `observe*`
+ * patterns used by react hooks. Targeted updates (e.g., `updateMessageError`)
+ * are exposed as separate methods rather than a generic `update()` because
+ * several of them have special semantics (encryption bypass for embeddings,
+ * unique constraints on feedback, etc).
+ */
+interface ChatStorageAdapter {
+    getConversation(conversationId: string): Promise<StoredConversation | null>;
+    getConversations(options?: ConversationQueryOptions): Promise<StoredConversation[]>;
+    createConversation(options?: CreateConversationOptions): Promise<StoredConversation>;
+    updateConversationTitle(conversationId: string, title: string): Promise<boolean>;
+    updateConversationProject(conversationId: string, projectId: string | null): Promise<boolean>;
+    /** Pin or unpin a conversation. Pinning stamps `pinnedAt`; list queries are
+     * NOT reordered — consumers sort pinned chats first using `pinnedAt`. */
+    updateConversationPinned(conversationId: string, pinned: boolean): Promise<boolean>;
+    /** Soft delete. Implementations are responsible for cascading to messages/media. */
+    deleteConversation(conversationId: string): Promise<boolean>;
+    observeConversations(options?: ConversationQueryOptions): ChatStorageObservable<StoredConversation[]>;
+    getMessages(conversationId: string): Promise<StoredMessage[]>;
+    /**
+     * Paginated display read: newest `limit` messages (optionally below
+     * `beforeMessageId`), ascending, with embeddings skipped. See
+     * `getMessagesPageOp`.
+     *
+     * Optional so this is an additive, non-breaking interface change (same
+     * rationale as {@link updateMessageFileIds}). The default
+     * {@link WatermelonChatStorageAdapter} provides it.
+     */
+    getMessagesPage?(conversationId: string, options: GetMessagesPageOptions): Promise<StoredMessage[]>;
+    /**
+     * Whole-thread branch-tree skeleton (no decrypt). See
+     * `getMessageSkeletonsOp`. Optional for the same additive-change rationale.
+     */
+    getMessageSkeletons?(conversationId: string): Promise<MessageSkeleton[]>;
+    /** Total message count for a conversation. Optional (additive change). */
+    getMessageCount?(conversationId: string): Promise<number>;
+    createMessage(options: CreateMessageOptions): Promise<StoredMessage>;
+    updateMessageEmbedding(uniqueId: string, vector: number[], embeddingModel: string): Promise<StoredMessage | null>;
+    updateMessageChunks(uniqueId: string, chunks: MessageChunk[], embeddingModel: string): Promise<StoredMessage | null>;
+    updateMessageError(uniqueId: string, error: string): Promise<StoredMessage | null>;
+    updateMessageFeedback(uniqueId: string, feedback: MessageFeedback): Promise<StoredMessage | null>;
+    /**
+     * Replace a message's attached media ids (`fileIds`). Used to attach a
+     * generated artifact (e.g. a rendered document PDF) to the assistant message
+     * that produced it, after streaming. Pass the FULL desired list.
+     *
+     * Optional so this is an additive, non-breaking interface change: only hosts
+     * wiring document/artifact generation need it, and existing custom adapters
+     * keep compiling without implementing it. The default
+     * {@link WatermelonChatStorageAdapter} provides it.
+     */
+    updateMessageFileIds?(uniqueId: string, fileIds: string[]): Promise<StoredMessage | null>;
+    /** Clears all messages in a conversation (used for the "clear chat" action). */
+    clearMessages(conversationId: string): Promise<void>;
+    observeMessages(conversationId: string): ChatStorageObservable<StoredMessage[]>;
+    getAllFiles(): Promise<StoredFileWithContext[]>;
+    /**
+     * Run a set of mutations inside a single write transaction. Any mutation
+     * calls made on the adapter inside the callback are grouped into one atomic
+     * write on backends that support it.
+     *
+     * On backends without transaction support, this may fall back to sequential
+     * writes. Implementations must document the guarantee they provide.
+     */
+    write<T>(fn: (adapter: ChatStorageAdapter) => Promise<T>): Promise<T>;
+}
+
+interface ChatChunkSearchOptions {
+    limit?: number;
+    minSimilarity?: number;
+    conversationId?: string;
+    excludeConversationId?: string;
+    embeddingModel?: string;
+    chunkCache?: ChunkVectorCache;
+    onStats?: (stats: ChunkSearchStats) => void;
+}
+/** Everything `useChatStorage` reads and writes for chats, so a hook can run on local or server storage. */
+interface ChatBackend extends ChatStorageAdapter {
+    createConversation(options?: CreateConversationOptions, defaultTitle?: string): Promise<StoredConversation>;
+    getAllFiles(options?: Parameters<typeof getAllFilesOp>[1]): Promise<StoredFileWithContext[]>;
+    getMessagesPage(conversationId: string, options: GetMessagesPageOptions): Promise<StoredMessage[]>;
+    getMessageSkeletons(conversationId: string): Promise<MessageSkeleton[]>;
+    /** Reads messages by id in the order asked, leaving out ids that are not stored. */
+    getMessagesByIds(uniqueIds: readonly string[]): Promise<StoredMessage[]>;
+    getMessageCount(conversationId: string): Promise<number>;
+    getToolCallEventIds(conversationId: string): Promise<Set<string>>;
+    upsertMessage(options: CreateMessageOptions & {
+        uniqueId: string;
+    }): Promise<StoredMessage>;
+    searchChunks(queryVector: number[], options?: ChatChunkSearchOptions): Promise<ChunkSearchResult[]>;
+    getSummary(conversationId: string): Promise<StoredConversationSummary | null>;
+    upsertSummary(conversationId: string, summary: string, summarizedUpTo: string, tokenCount: number): Promise<StoredConversationSummary>;
+    deleteSummary(conversationId: string): Promise<void>;
+    deleteMessage(uniqueId: string): Promise<string | null>;
+    getMemoryLinks(conversationId: string): Promise<StoredConversationMemory[]>;
+    /** Records the memories a turn drew on in recall order, moving already-linked ones to this turn with their new score. */
+    addMemoryLinks(conversationId: string, items: ConversationMemoryInput[]): Promise<void>;
+    clearMemoryLinks(conversationId: string): Promise<void>;
+}
+
 /** Recent window — observations inside this count as "active". */
 declare const TREND_RECENT_WINDOW_DAYS = 30;
 /** Beyond this since last observation → stale. */
@@ -4221,8 +4374,10 @@ interface RecallContext {
     factSource?: RecallFactSource;
     /** Required when `types` includes 'fact'. */
     vaultCtx?: VaultMemoryOperationsContext;
-    /** Required when `types` includes 'chunk'. */
+    /** Required when `types` includes 'chunk', unless `chats` is given. */
     storageCtx?: StorageOperationsContext;
+    /** Chat chunk search; takes precedence over `storageCtx`. */
+    chats?: Pick<ChatBackend, "searchChunks">;
     /** Embedding API options. */
     embeddingOptions: EmbeddingOptions;
     /** Vault embedding LRU cache. */
@@ -7248,6 +7403,32 @@ interface SearchSource {
     snippet?: string;
     date?: string;
 }
+/** Options for paginated message reads ({@link getMessagesPageOp}). */
+interface GetMessagesPageOptions {
+    /**
+     * Upper-bound cursor. Without `boundaryExcludeUniqueIds` it is EXCLUSIVE:
+     * only messages with `messageId < beforeMessageId` are returned. Omit to
+     * fetch the newest page (the conversation tail).
+     */
+    beforeMessageId?: number;
+    /**
+     * uniqueIds of the rows the caller already holds AT the `beforeMessageId`
+     * boundary. `message_id` is not guaranteed unique in legacy data (ids were
+     * assigned count-based, so a mid-thread delete let the next create reuse a
+     * freed id) — with an exclusive cursor, an unseen row sharing the boundary
+     * id would be silently skipped by every page. When this is provided, the
+     * boundary id is fetched INCLUSIVELY and these known rows are filtered
+     * out, so a duplicated boundary row is returned exactly once.
+     */
+    boundaryExcludeUniqueIds?: string[];
+    /**
+     * Maximum rows to return — the NEWEST `limit` rows of the matching range.
+     * Must be a positive integer: non-positive or non-finite values yield an
+     * EMPTY page (never an unbounded read — SQLite treats `LIMIT -1` as "no
+     * limit"), and fractional values are floored.
+     */
+    limit: number;
+}
 /** Options for keyset-paginated conversation-list reads ({@link getConversationsPageOp}). */
 interface GetConversationsPageOptions {
     /**
@@ -7274,6 +7455,27 @@ interface GetConversationsPageOptions {
      */
     limit?: number;
 }
+/**
+ * Lightweight, mostly-undecrypted projection of a message row. Contains just
+ * enough for consumers to build the conversation's branch tree (parent/child
+ * structure) without paying the decrypt + embedding-parse cost of a full
+ * {@link StoredMessage} read.
+ *
+ * `content` is populated (decrypted) ONLY for user-role rows whose parent is
+ * also a user-role row — the regeneration artifacts that branch logic must
+ * classify by content prefix. All other rows leave `content` undefined.
+ */
+interface MessageSkeleton {
+    uniqueId: string;
+    messageId: number;
+    conversationId: string;
+    role: ChatRole;
+    createdAt: Date;
+    parentMessageId?: string;
+    model?: string;
+    /** See interface docs — only set for user rows with a user-role parent. */
+    content?: string;
+}
 interface StoredMessage {
     uniqueId: string;
     messageId: number;
@@ -7588,6 +7790,7 @@ declare function summaryToSystemMessage(summary: string): LlmapiMessage;
 /** Options for `maybeSummarizeHistory` */
 interface MaybeSummarizeHistoryOptions {
     database: Database;
+    summaries?: Pick<ChatBackend, "getSummary" | "upsertSummary">;
     conversationId: string;
     messages: StoredMessage[];
     summarizeHistory: boolean;
@@ -7620,7 +7823,7 @@ declare function maybeSummarizeHistory(options: MaybeSummarizeHistoryOptions): P
  * Delete the conversation summary cache. Logs a warning on failure
  * rather than throwing, since this is a cascade cleanup operation.
  */
-declare function cleanupConversationSummary(database: Database, conversationId: string): Promise<void>;
+declare function cleanupConversationSummary(storage: Database | Pick<ChatBackend, "deleteSummary">, conversationId: string): Promise<void>;
 
 interface WeatherClassification {
     /** Whether the prompt likely asks for weather data. */
@@ -7825,12 +8028,12 @@ declare function clearLazyTitleCache(): void;
 declare function decryptConversationTitle(encryptedTitle: string, address: string): Promise<string>;
 
 /** Context needed for summary operations */
-interface SummaryOperationsContext {
+interface SummaryOperationsContext extends Pick<StorageOperationsContext, "walletAddress" | "signMessage" | "embeddedWalletSigner"> {
     database: Database;
     summariesCollection: Collection<ConversationSummary>;
 }
 /** Create a summary operations context from a database instance */
-declare function createSummaryContext(database: Database): SummaryOperationsContext;
+declare function createSummaryContext(database: Database, encryption?: Pick<SummaryOperationsContext, "walletAddress" | "signMessage" | "embeddedWalletSigner">): SummaryOperationsContext;
 /**
  * Get the cached summary for a conversation.
  * Returns null if no summary exists yet.
@@ -10442,7 +10645,7 @@ declare function chunkAndEmbedAllMessages(ctx: StorageOperationsContext, options
  * The tool allows the LLM to search through past conversation messages
  * using semantic similarity. Messages must have embeddings stored to be searchable.
  *
- * @param storageCtx - Storage operations context for database access
+ * @param storage - Chat storage: a WatermelonDB operations context or a chat backend
  * @param embeddingOptions - Options for embedding generation
  * @param searchOptions - Default search options (can be overridden per-call)
  * @returns A ToolConfig that can be passed to chat completion tools
@@ -10462,7 +10665,7 @@ declare function chunkAndEmbedAllMessages(ctx: StorageOperationsContext, options
  * });
  * ```
  */
-declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, embeddingOptions: EmbeddingOptions, searchOptions?: Partial<MemoryEngineSearchOptions>, callbacks?: {
+declare function createMemoryEngineTool(storage: StorageOperationsContext | Pick<ChatBackend, "searchChunks" | "getMessages">, embeddingOptions: EmbeddingOptions, searchOptions?: Partial<MemoryEngineSearchOptions>, callbacks?: {
     /** Called after retrieval with the conversation IDs that were actually returned to the LLM. */
     onRetrieve?: (conversationIds: string[]) => void;
 }): ToolConfig;

package/dist/server/index.d.ts

@@ -3954,6 +3954,159 @@ declare function makeSyntheticStoredMessage(opts: CreateMessageOptions): StoredM
  */
 declare function makeSyntheticStoredConversation(opts?: CreateConversationOptions, defaultTitle?: string): StoredConversation;
 
+/**
+ * Types for the conversation-memory storage module.
+ *
+ * A conversation-memory row links a conversation to a vault memory it drew on,
+ * so the conversation Memories panel survives reload. Only the memory id and
+ * recall score are stored; content lives in the encrypted memory_vault.
+ */
+/** Plain object representation of a conversation-memory record. */
+interface StoredConversationMemory {
+    /** WatermelonDB internal ID */
+    uniqueId: string;
+    /** The conversation this memory was drawn on in */
+    conversationId: string;
+    /** The memory_vault record id this row points at */
+    memoryId: string;
+    /** Recall relevance score (~0–1) at the time it was recorded */
+    score: number;
+    createdAt: Date;
+}
+/** One memory drawn on during a turn, passed to addConversationMemoriesOp. */
+interface ConversationMemoryInput {
+    memoryId: string;
+    score: number;
+}
+
+/**
+ * Minimal interface for an observable (reactive) query result.
+ *
+ * Shaped to be compatible with RxJS-style `Observable` (which is what
+ * WatermelonDB returns) and with a simple polling fallback, so non-reactive
+ * backends can implement it without depending on rxjs.
+ */
+interface ChatStorageObservable<T> {
+    subscribe(observer: {
+        next: (value: T) => void;
+        error?: (err: unknown) => void;
+        complete?: () => void;
+    }): {
+        unsubscribe: () => void;
+    };
+}
+/**
+ * Common filter options for conversation queries. Kept deliberately narrow —
+ * most call sites only need these.
+ */
+interface ConversationQueryOptions {
+    /** If set, only return conversations in this project. `null` = no project. */
+    projectId?: string | null;
+}
+/**
+ * Backend-agnostic interface for chat/conversation storage.
+ *
+ * The method set mirrors the operations we actually use across the SDK:
+ * `*Op` functions in `src/lib/db/chat/operations.ts` plus the `observe*`
+ * patterns used by react hooks. Targeted updates (e.g., `updateMessageError`)
+ * are exposed as separate methods rather than a generic `update()` because
+ * several of them have special semantics (encryption bypass for embeddings,
+ * unique constraints on feedback, etc).
+ */
+interface ChatStorageAdapter {
+    getConversation(conversationId: string): Promise<StoredConversation | null>;
+    getConversations(options?: ConversationQueryOptions): Promise<StoredConversation[]>;
+    createConversation(options?: CreateConversationOptions): Promise<StoredConversation>;
+    updateConversationTitle(conversationId: string, title: string): Promise<boolean>;
+    updateConversationProject(conversationId: string, projectId: string | null): Promise<boolean>;
+    /** Pin or unpin a conversation. Pinning stamps `pinnedAt`; list queries are
+     * NOT reordered — consumers sort pinned chats first using `pinnedAt`. */
+    updateConversationPinned(conversationId: string, pinned: boolean): Promise<boolean>;
+    /** Soft delete. Implementations are responsible for cascading to messages/media. */
+    deleteConversation(conversationId: string): Promise<boolean>;
+    observeConversations(options?: ConversationQueryOptions): ChatStorageObservable<StoredConversation[]>;
+    getMessages(conversationId: string): Promise<StoredMessage[]>;
+    /**
+     * Paginated display read: newest `limit` messages (optionally below
+     * `beforeMessageId`), ascending, with embeddings skipped. See
+     * `getMessagesPageOp`.
+     *
+     * Optional so this is an additive, non-breaking interface change (same
+     * rationale as {@link updateMessageFileIds}). The default
+     * {@link WatermelonChatStorageAdapter} provides it.
+     */
+    getMessagesPage?(conversationId: string, options: GetMessagesPageOptions): Promise<StoredMessage[]>;
+    /**
+     * Whole-thread branch-tree skeleton (no decrypt). See
+     * `getMessageSkeletonsOp`. Optional for the same additive-change rationale.
+     */
+    getMessageSkeletons?(conversationId: string): Promise<MessageSkeleton[]>;
+    /** Total message count for a conversation. Optional (additive change). */
+    getMessageCount?(conversationId: string): Promise<number>;
+    createMessage(options: CreateMessageOptions): Promise<StoredMessage>;
+    updateMessageEmbedding(uniqueId: string, vector: number[], embeddingModel: string): Promise<StoredMessage | null>;
+    updateMessageChunks(uniqueId: string, chunks: MessageChunk[], embeddingModel: string): Promise<StoredMessage | null>;
+    updateMessageError(uniqueId: string, error: string): Promise<StoredMessage | null>;
+    updateMessageFeedback(uniqueId: string, feedback: MessageFeedback): Promise<StoredMessage | null>;
+    /**
+     * Replace a message's attached media ids (`fileIds`). Used to attach a
+     * generated artifact (e.g. a rendered document PDF) to the assistant message
+     * that produced it, after streaming. Pass the FULL desired list.
+     *
+     * Optional so this is an additive, non-breaking interface change: only hosts
+     * wiring document/artifact generation need it, and existing custom adapters
+     * keep compiling without implementing it. The default
+     * {@link WatermelonChatStorageAdapter} provides it.
+     */
+    updateMessageFileIds?(uniqueId: string, fileIds: string[]): Promise<StoredMessage | null>;
+    /** Clears all messages in a conversation (used for the "clear chat" action). */
+    clearMessages(conversationId: string): Promise<void>;
+    observeMessages(conversationId: string): ChatStorageObservable<StoredMessage[]>;
+    getAllFiles(): Promise<StoredFileWithContext[]>;
+    /**
+     * Run a set of mutations inside a single write transaction. Any mutation
+     * calls made on the adapter inside the callback are grouped into one atomic
+     * write on backends that support it.
+     *
+     * On backends without transaction support, this may fall back to sequential
+     * writes. Implementations must document the guarantee they provide.
+     */
+    write<T>(fn: (adapter: ChatStorageAdapter) => Promise<T>): Promise<T>;
+}
+
+interface ChatChunkSearchOptions {
+    limit?: number;
+    minSimilarity?: number;
+    conversationId?: string;
+    excludeConversationId?: string;
+    embeddingModel?: string;
+    chunkCache?: ChunkVectorCache;
+    onStats?: (stats: ChunkSearchStats) => void;
+}
+/** Everything `useChatStorage` reads and writes for chats, so a hook can run on local or server storage. */
+interface ChatBackend extends ChatStorageAdapter {
+    createConversation(options?: CreateConversationOptions, defaultTitle?: string): Promise<StoredConversation>;
+    getAllFiles(options?: Parameters<typeof getAllFilesOp>[1]): Promise<StoredFileWithContext[]>;
+    getMessagesPage(conversationId: string, options: GetMessagesPageOptions): Promise<StoredMessage[]>;
+    getMessageSkeletons(conversationId: string): Promise<MessageSkeleton[]>;
+    /** Reads messages by id in the order asked, leaving out ids that are not stored. */
+    getMessagesByIds(uniqueIds: readonly string[]): Promise<StoredMessage[]>;
+    getMessageCount(conversationId: string): Promise<number>;
+    getToolCallEventIds(conversationId: string): Promise<Set<string>>;
+    upsertMessage(options: CreateMessageOptions & {
+        uniqueId: string;
+    }): Promise<StoredMessage>;
+    searchChunks(queryVector: number[], options?: ChatChunkSearchOptions): Promise<ChunkSearchResult[]>;
+    getSummary(conversationId: string): Promise<StoredConversationSummary | null>;
+    upsertSummary(conversationId: string, summary: string, summarizedUpTo: string, tokenCount: number): Promise<StoredConversationSummary>;
+    deleteSummary(conversationId: string): Promise<void>;
+    deleteMessage(uniqueId: string): Promise<string | null>;
+    getMemoryLinks(conversationId: string): Promise<StoredConversationMemory[]>;
+    /** Records the memories a turn drew on in recall order, moving already-linked ones to this turn with their new score. */
+    addMemoryLinks(conversationId: string, items: ConversationMemoryInput[]): Promise<void>;
+    clearMemoryLinks(conversationId: string): Promise<void>;
+}
+
 /** Recent window — observations inside this count as "active". */
 declare const TREND_RECENT_WINDOW_DAYS = 30;
 /** Beyond this since last observation → stale. */
@@ -4221,8 +4374,10 @@ interface RecallContext {
     factSource?: RecallFactSource;
     /** Required when `types` includes 'fact'. */
     vaultCtx?: VaultMemoryOperationsContext;
-    /** Required when `types` includes 'chunk'. */
+    /** Required when `types` includes 'chunk', unless `chats` is given. */
     storageCtx?: StorageOperationsContext;
+    /** Chat chunk search; takes precedence over `storageCtx`. */
+    chats?: Pick<ChatBackend, "searchChunks">;
     /** Embedding API options. */
     embeddingOptions: EmbeddingOptions;
     /** Vault embedding LRU cache. */
@@ -7248,6 +7403,32 @@ interface SearchSource {
     snippet?: string;
     date?: string;
 }
+/** Options for paginated message reads ({@link getMessagesPageOp}). */
+interface GetMessagesPageOptions {
+    /**
+     * Upper-bound cursor. Without `boundaryExcludeUniqueIds` it is EXCLUSIVE:
+     * only messages with `messageId < beforeMessageId` are returned. Omit to
+     * fetch the newest page (the conversation tail).
+     */
+    beforeMessageId?: number;
+    /**
+     * uniqueIds of the rows the caller already holds AT the `beforeMessageId`
+     * boundary. `message_id` is not guaranteed unique in legacy data (ids were
+     * assigned count-based, so a mid-thread delete let the next create reuse a
+     * freed id) — with an exclusive cursor, an unseen row sharing the boundary
+     * id would be silently skipped by every page. When this is provided, the
+     * boundary id is fetched INCLUSIVELY and these known rows are filtered
+     * out, so a duplicated boundary row is returned exactly once.
+     */
+    boundaryExcludeUniqueIds?: string[];
+    /**
+     * Maximum rows to return — the NEWEST `limit` rows of the matching range.
+     * Must be a positive integer: non-positive or non-finite values yield an
+     * EMPTY page (never an unbounded read — SQLite treats `LIMIT -1` as "no
+     * limit"), and fractional values are floored.
+     */
+    limit: number;
+}
 /** Options for keyset-paginated conversation-list reads ({@link getConversationsPageOp}). */
 interface GetConversationsPageOptions {
     /**
@@ -7274,6 +7455,27 @@ interface GetConversationsPageOptions {
      */
     limit?: number;
 }
+/**
+ * Lightweight, mostly-undecrypted projection of a message row. Contains just
+ * enough for consumers to build the conversation's branch tree (parent/child
+ * structure) without paying the decrypt + embedding-parse cost of a full
+ * {@link StoredMessage} read.
+ *
+ * `content` is populated (decrypted) ONLY for user-role rows whose parent is
+ * also a user-role row — the regeneration artifacts that branch logic must
+ * classify by content prefix. All other rows leave `content` undefined.
+ */
+interface MessageSkeleton {
+    uniqueId: string;
+    messageId: number;
+    conversationId: string;
+    role: ChatRole;
+    createdAt: Date;
+    parentMessageId?: string;
+    model?: string;
+    /** See interface docs — only set for user rows with a user-role parent. */
+    content?: string;
+}
 interface StoredMessage {
     uniqueId: string;
     messageId: number;
@@ -7588,6 +7790,7 @@ declare function summaryToSystemMessage(summary: string): LlmapiMessage;
 /** Options for `maybeSummarizeHistory` */
 interface MaybeSummarizeHistoryOptions {
     database: Database;
+    summaries?: Pick<ChatBackend, "getSummary" | "upsertSummary">;
     conversationId: string;
     messages: StoredMessage[];
     summarizeHistory: boolean;
@@ -7620,7 +7823,7 @@ declare function maybeSummarizeHistory(options: MaybeSummarizeHistoryOptions): P
  * Delete the conversation summary cache. Logs a warning on failure
  * rather than throwing, since this is a cascade cleanup operation.
  */
-declare function cleanupConversationSummary(database: Database, conversationId: string): Promise<void>;
+declare function cleanupConversationSummary(storage: Database | Pick<ChatBackend, "deleteSummary">, conversationId: string): Promise<void>;
 
 interface WeatherClassification {
     /** Whether the prompt likely asks for weather data. */
@@ -7825,12 +8028,12 @@ declare function clearLazyTitleCache(): void;
 declare function decryptConversationTitle(encryptedTitle: string, address: string): Promise<string>;
 
 /** Context needed for summary operations */
-interface SummaryOperationsContext {
+interface SummaryOperationsContext extends Pick<StorageOperationsContext, "walletAddress" | "signMessage" | "embeddedWalletSigner"> {
     database: Database;
     summariesCollection: Collection<ConversationSummary>;
 }
 /** Create a summary operations context from a database instance */
-declare function createSummaryContext(database: Database): SummaryOperationsContext;
+declare function createSummaryContext(database: Database, encryption?: Pick<SummaryOperationsContext, "walletAddress" | "signMessage" | "embeddedWalletSigner">): SummaryOperationsContext;
 /**
  * Get the cached summary for a conversation.
  * Returns null if no summary exists yet.
@@ -10442,7 +10645,7 @@ declare function chunkAndEmbedAllMessages(ctx: StorageOperationsContext, options
  * The tool allows the LLM to search through past conversation messages
  * using semantic similarity. Messages must have embeddings stored to be searchable.
  *
- * @param storageCtx - Storage operations context for database access
+ * @param storage - Chat storage: a WatermelonDB operations context or a chat backend
  * @param embeddingOptions - Options for embedding generation
  * @param searchOptions - Default search options (can be overridden per-call)
  * @returns A ToolConfig that can be passed to chat completion tools
@@ -10462,7 +10665,7 @@ declare function chunkAndEmbedAllMessages(ctx: StorageOperationsContext, options
  * });
  * ```
  */
-declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, embeddingOptions: EmbeddingOptions, searchOptions?: Partial<MemoryEngineSearchOptions>, callbacks?: {
+declare function createMemoryEngineTool(storage: StorageOperationsContext | Pick<ChatBackend, "searchChunks" | "getMessages">, embeddingOptions: EmbeddingOptions, searchOptions?: Partial<MemoryEngineSearchOptions>, callbacks?: {
     /** Called after retrieval with the conversation IDs that were actually returned to the LLM. */
     onRetrieve?: (conversationIds: string[]) => void;
 }): ToolConfig;