@anuma/sdk 6.24.1 → 6.25.1

package/dist/server/index.d.mts

@@ -4371,6 +4371,13 @@ declare function searchChunksOp(ctx: StorageOperationsContext, queryVector: numb
     limit?: number;
     minSimilarity?: number;
     conversationId?: string;
+    /**
+     * Skip every message in this conversation BEFORE scoring, so it can't take
+     * top-K slots. Filtering after the cut (what recall() used to do) lets a
+     * long current conversation fill all `limit` slots and leaves
+     * past-conversation recall with nothing.
+     */
+    excludeConversationId?: string;
     /**
      * Current embedding model. When set, messages whose stored
      * `embedding_model` is non-null and differs are skipped — their vectors
@@ -5160,6 +5167,28 @@ interface EmbeddingOptions {
      * while real PII never reaches the server. Used when PII redaction is active.
      */
     maskInput?: (text: string) => string;
+    /**
+     * Deadline, in ms, for EACH embeddings HTTP attempt (default 15000). An
+     * attempt that exceeds it is aborted and counts as a transient failure, so the
+     * bounded retry still applies. `0` disables the deadline.
+     */
+    timeoutMs?: number;
+    /**
+     * Deadline, in ms, for the `getToken()` read that precedes a request (default
+     * 10000). A provider that never settles rejects instead of hanging the
+     * embedding — and the recall waiting on it. `0` disables the deadline.
+     */
+    tokenTimeoutMs?: number;
+    /**
+     * Overall deadline, in ms, for one `generateEmbedding` call — the token read,
+     * every retry attempt and the backoff between them. Unset (the default) means
+     * only the per-attempt deadlines apply, which is right for background/bulk
+     * embeds. The recall query path sets it (see
+     * `RecallOptions.queryEmbedTotalTimeoutMs`) so an outage degrades a turn to
+     * BM25 within a few seconds instead of ~4 x `timeoutMs`. Not applied by
+     * `generateEmbeddings`.
+     */
+    totalTimeoutMs?: number;
 }
 
 /**
@@ -5248,6 +5277,12 @@ interface MemoryVaultSearchOptions {
     rerankTopN?: number;
     /** Multiplicative cross-encoder blend weight. Default 0.1. Only used when `rerank` is true. */
     ceWeight?: number;
+    /**
+     * Max ms a rerank waits for the cross-encoder's FIRST model load (default
+     * 10000). On expiry the search degrades to the fused ranking and reports
+     * `reranked: false`; the load continues in the background for later calls.
+     */
+    rerankLoadTimeoutMs?: number;
     /** Recency boost slope applied in the fused ranker. Default 1.0. */
     recencyAlpha?: number;
     /** Recency decay curve overrides (per-year decay slope, floor, no-date multiplier). */
@@ -5315,6 +5350,23 @@ interface MemoryVaultSearchOptions {
      * prefix stays byte-identical.
      */
     decryptLast?: boolean;
+    /**
+     * A vector the caller already computed for THIS query, with the model named in
+     * `embeddingOptions`. When set, the search uses it instead of embedding the
+     * query a second time — `recall()` embeds once for its chunk lane and passes
+     * the vector here. An EMPTY array means the caller's embed failed: the search
+     * degrades to BM25 (reported as embeddings unavailable) without re-trying a
+     * provider that just failed.
+     */
+    queryEmbedding?: number[];
+    /**
+     * Overall deadline, in ms, for embedding the QUERY (token read + all attempts
+     * + backoff). On expiry the search degrades to BM25 and reports embeddings
+     * unavailable. Unset = only the per-attempt deadlines apply. `recall()` sets
+     * it (default 8000 — see `RecallOptions.queryEmbedTotalTimeoutMs`); row
+     * (re)embeds are never subject to it.
+     */
+    queryEmbedTotalTimeoutMs?: number;
     /** Admission window multiplier for decrypt-last (`limit * admitFactor`). Default 3. */
     admitFactor?: number;
     /** Admission window floor for decrypt-last. Default 30. */
@@ -5331,7 +5383,14 @@ declare function preEmbedVaultMemories(vaultCtx: VaultMemoryOperationsContext, e
  * Eagerly embed a single piece of content and store it in the cache.
  * Call this when a vault memory is created or updated.
  */
-declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, vaultCtx?: VaultMemoryOperationsContext, memoryId?: string): Promise<void>;
+declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, vaultCtx?: VaultMemoryOperationsContext, memoryId?: string, 
+/**
+ * `updatedAt` of the committed row this content belongs to. When given, the
+ * cache entry is tied to that row version; without it the entry is
+ * unversioned and a search re-resolves it from the stored column instead of
+ * trusting it (see `vectorVersion.ts`).
+ */
+updatedAt?: Date): Promise<void>;
 /**
  * A single vault search result with its similarity score.
  */
@@ -5372,21 +5431,6 @@ interface VaultSearchResult {
  * @returns Sorted results (empty array on invalid input or empty vault)
  */
 declare function searchVaultMemories(query: string, vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): Promise<VaultSearchResult[]>;
-/**
- * Creates a memory vault search tool for use with chat completions.
- *
- * The tool allows the LLM to search through vault memories using semantic
- * similarity. Vault entries should have their embeddings pre-computed in the
- * cache (via preEmbedVaultMemories or eagerEmbedContent). Any missing
- * embeddings are computed on the fly as a fallback.
- *
- * @param vaultCtx - Vault operations context for database access
- * @param embeddingOptions - Options for embedding generation (auth, base URL)
- * @param cache - Pre-populated embedding cache
- * @param searchOptions - Optional search configuration
- * @returns A ToolConfig that can be passed to chat completion tools
- */
-declare function createMemoryVaultSearchTool(vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): ToolConfig;
 
 /**
  * C2 — Observation trend labels.
@@ -5609,6 +5653,20 @@ interface RecallOptions {
     rerankTopN?: number;
     /** Multiplicative cross-encoder blend weight. Default: 0.1. */
     ceWeight?: number;
+    /**
+     * Max ms a `mid`/`high` recall waits for the cross-encoder's FIRST model load
+     * before degrading to the fused ranking (reported as `rerank-unavailable`).
+     * Default: 10000. The load keeps going in the background for later calls.
+     */
+    rerankLoadTimeoutMs?: number;
+    /**
+     * Overall deadline, in ms, for embedding the query — token read, every retry
+     * attempt and the backoff between them. Default: 8000. On expiry the fact lane
+     * degrades to BM25 and the (cosine-only) chunk lane is skipped, reported as
+     * `embeddings-unavailable`, so an embeddings outage costs a turn at most this
+     * long rather than ~4 x the per-attempt timeout. `0` disables it.
+     */
+    queryEmbedTotalTimeoutMs?: number;
     /** Recency boost slope in the fused ranker. Default: 1.0. */
     recencyAlpha?: number;
     /** Recency decay curve overrides (per-year decay slope, floor, no-date multiplier). */
@@ -5636,7 +5694,8 @@ interface RecallOptions {
     maxHops?: number;
     /** Max neighbor entities expanded per hop. Default: 8. */
     entityFanout?: number;
-    /** Hard cap on accumulated memory IDs across all hops. Default: 64. */
+    /** Hard cap on graph-lane memory IDs — across all hops, and on the single-hop
+     *  lane `low`/`mid` run. Default: 64. */
     nodeBudget?: number;
     /**
      * PR5 — enable LLM graph path-refinement: at each traversal hop a model picks
@@ -5871,6 +5930,10 @@ interface RecallDiagnostics {
          * fast `vault_size = 0` population never established a baseline for this
          * cost, and why the ~850ms floor on the smallest NON-empty vaults had no
          * attributable owner.
+         *
+         * EXCEPTION — a mixed fact + chunk recall embeds the query ONCE, during
+         * {@link prep}, and hands the vector to both lanes. There `queryEmbed` is
+         * that shared embed and sits inside `prep`, not `factLane`.
          */
         queryEmbed: number;
         /** Chunk-lane search (`searchChunksOp`). */
@@ -8011,6 +8074,38 @@ declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, em
     onRetrieve?: (conversationIds: string[]) => void;
 }): ToolConfig;
 
+/**
+ * `memory_vault_search` chat tool — the executor half of the vault search.
+ *
+ * Split out of `searchTool.ts` to break the `recall` <-> `searchTool` import
+ * cycle: `recall()` statically imports the vault search from `searchTool.ts`,
+ * and this executor routes through `recall()`. While both lived in one module
+ * the executor reached recall through a dynamic `import()`, and the cycle it
+ * papered over is what surfaced as the order-dependent
+ * `Cannot access 'nowMs' before initialization` flake. With the executor here,
+ * the graph is a straight line: executor -> recall -> searchTool.
+ *
+ * `searchTool.ts` must NOT import (or re-export) from this module, or the
+ * cycle comes back. The public name is re-exported from the barrel
+ * (`./index.ts`), which is the path every entry point already uses.
+ */
+
+/**
+ * Creates a memory vault search tool for use with chat completions.
+ *
+ * The tool allows the LLM to search through vault memories using semantic
+ * similarity. Vault entries should have their embeddings pre-computed in the
+ * cache (via preEmbedVaultMemories or eagerEmbedContent). Any missing
+ * embeddings are computed on the fly as a fallback.
+ *
+ * @param vaultCtx - Vault operations context for database access
+ * @param embeddingOptions - Options for embedding generation (auth, base URL)
+ * @param cache - Pre-populated embedding cache
+ * @param searchOptions - Optional search configuration
+ * @returns A ToolConfig that can be passed to chat completion tools
+ */
+declare function createMemoryVaultSearchTool(vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): ToolConfig;
+
 /**
  * Memory Vault Tool
  *
@@ -9319,7 +9414,7 @@ declare function reflect(query: string, ctx: RecallContext, options: ReflectOpti
 declare class RerankerUnavailableError extends Error {
     /** The underlying import failure, kept for debugging. */
     readonly reason: unknown;
-    constructor(reason: unknown);
+    constructor(reason: unknown, message?: string);
 }
 /**
  * Whether the cross-encoder reranker can run in this environment.

package/dist/server/index.d.ts

@@ -4371,6 +4371,13 @@ declare function searchChunksOp(ctx: StorageOperationsContext, queryVector: numb
     limit?: number;
     minSimilarity?: number;
     conversationId?: string;
+    /**
+     * Skip every message in this conversation BEFORE scoring, so it can't take
+     * top-K slots. Filtering after the cut (what recall() used to do) lets a
+     * long current conversation fill all `limit` slots and leaves
+     * past-conversation recall with nothing.
+     */
+    excludeConversationId?: string;
     /**
      * Current embedding model. When set, messages whose stored
      * `embedding_model` is non-null and differs are skipped — their vectors
@@ -5160,6 +5167,28 @@ interface EmbeddingOptions {
      * while real PII never reaches the server. Used when PII redaction is active.
      */
     maskInput?: (text: string) => string;
+    /**
+     * Deadline, in ms, for EACH embeddings HTTP attempt (default 15000). An
+     * attempt that exceeds it is aborted and counts as a transient failure, so the
+     * bounded retry still applies. `0` disables the deadline.
+     */
+    timeoutMs?: number;
+    /**
+     * Deadline, in ms, for the `getToken()` read that precedes a request (default
+     * 10000). A provider that never settles rejects instead of hanging the
+     * embedding — and the recall waiting on it. `0` disables the deadline.
+     */
+    tokenTimeoutMs?: number;
+    /**
+     * Overall deadline, in ms, for one `generateEmbedding` call — the token read,
+     * every retry attempt and the backoff between them. Unset (the default) means
+     * only the per-attempt deadlines apply, which is right for background/bulk
+     * embeds. The recall query path sets it (see
+     * `RecallOptions.queryEmbedTotalTimeoutMs`) so an outage degrades a turn to
+     * BM25 within a few seconds instead of ~4 x `timeoutMs`. Not applied by
+     * `generateEmbeddings`.
+     */
+    totalTimeoutMs?: number;
 }
 
 /**
@@ -5248,6 +5277,12 @@ interface MemoryVaultSearchOptions {
     rerankTopN?: number;
     /** Multiplicative cross-encoder blend weight. Default 0.1. Only used when `rerank` is true. */
     ceWeight?: number;
+    /**
+     * Max ms a rerank waits for the cross-encoder's FIRST model load (default
+     * 10000). On expiry the search degrades to the fused ranking and reports
+     * `reranked: false`; the load continues in the background for later calls.
+     */
+    rerankLoadTimeoutMs?: number;
     /** Recency boost slope applied in the fused ranker. Default 1.0. */
     recencyAlpha?: number;
     /** Recency decay curve overrides (per-year decay slope, floor, no-date multiplier). */
@@ -5315,6 +5350,23 @@ interface MemoryVaultSearchOptions {
      * prefix stays byte-identical.
      */
     decryptLast?: boolean;
+    /**
+     * A vector the caller already computed for THIS query, with the model named in
+     * `embeddingOptions`. When set, the search uses it instead of embedding the
+     * query a second time — `recall()` embeds once for its chunk lane and passes
+     * the vector here. An EMPTY array means the caller's embed failed: the search
+     * degrades to BM25 (reported as embeddings unavailable) without re-trying a
+     * provider that just failed.
+     */
+    queryEmbedding?: number[];
+    /**
+     * Overall deadline, in ms, for embedding the QUERY (token read + all attempts
+     * + backoff). On expiry the search degrades to BM25 and reports embeddings
+     * unavailable. Unset = only the per-attempt deadlines apply. `recall()` sets
+     * it (default 8000 — see `RecallOptions.queryEmbedTotalTimeoutMs`); row
+     * (re)embeds are never subject to it.
+     */
+    queryEmbedTotalTimeoutMs?: number;
     /** Admission window multiplier for decrypt-last (`limit * admitFactor`). Default 3. */
     admitFactor?: number;
     /** Admission window floor for decrypt-last. Default 30. */
@@ -5331,7 +5383,14 @@ declare function preEmbedVaultMemories(vaultCtx: VaultMemoryOperationsContext, e
  * Eagerly embed a single piece of content and store it in the cache.
  * Call this when a vault memory is created or updated.
  */
-declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, vaultCtx?: VaultMemoryOperationsContext, memoryId?: string): Promise<void>;
+declare function eagerEmbedContent(content: string, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, vaultCtx?: VaultMemoryOperationsContext, memoryId?: string, 
+/**
+ * `updatedAt` of the committed row this content belongs to. When given, the
+ * cache entry is tied to that row version; without it the entry is
+ * unversioned and a search re-resolves it from the stored column instead of
+ * trusting it (see `vectorVersion.ts`).
+ */
+updatedAt?: Date): Promise<void>;
 /**
  * A single vault search result with its similarity score.
  */
@@ -5372,21 +5431,6 @@ interface VaultSearchResult {
  * @returns Sorted results (empty array on invalid input or empty vault)
  */
 declare function searchVaultMemories(query: string, vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): Promise<VaultSearchResult[]>;
-/**
- * Creates a memory vault search tool for use with chat completions.
- *
- * The tool allows the LLM to search through vault memories using semantic
- * similarity. Vault entries should have their embeddings pre-computed in the
- * cache (via preEmbedVaultMemories or eagerEmbedContent). Any missing
- * embeddings are computed on the fly as a fallback.
- *
- * @param vaultCtx - Vault operations context for database access
- * @param embeddingOptions - Options for embedding generation (auth, base URL)
- * @param cache - Pre-populated embedding cache
- * @param searchOptions - Optional search configuration
- * @returns A ToolConfig that can be passed to chat completion tools
- */
-declare function createMemoryVaultSearchTool(vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): ToolConfig;
 
 /**
  * C2 — Observation trend labels.
@@ -5609,6 +5653,20 @@ interface RecallOptions {
     rerankTopN?: number;
     /** Multiplicative cross-encoder blend weight. Default: 0.1. */
     ceWeight?: number;
+    /**
+     * Max ms a `mid`/`high` recall waits for the cross-encoder's FIRST model load
+     * before degrading to the fused ranking (reported as `rerank-unavailable`).
+     * Default: 10000. The load keeps going in the background for later calls.
+     */
+    rerankLoadTimeoutMs?: number;
+    /**
+     * Overall deadline, in ms, for embedding the query — token read, every retry
+     * attempt and the backoff between them. Default: 8000. On expiry the fact lane
+     * degrades to BM25 and the (cosine-only) chunk lane is skipped, reported as
+     * `embeddings-unavailable`, so an embeddings outage costs a turn at most this
+     * long rather than ~4 x the per-attempt timeout. `0` disables it.
+     */
+    queryEmbedTotalTimeoutMs?: number;
     /** Recency boost slope in the fused ranker. Default: 1.0. */
     recencyAlpha?: number;
     /** Recency decay curve overrides (per-year decay slope, floor, no-date multiplier). */
@@ -5636,7 +5694,8 @@ interface RecallOptions {
     maxHops?: number;
     /** Max neighbor entities expanded per hop. Default: 8. */
     entityFanout?: number;
-    /** Hard cap on accumulated memory IDs across all hops. Default: 64. */
+    /** Hard cap on graph-lane memory IDs — across all hops, and on the single-hop
+     *  lane `low`/`mid` run. Default: 64. */
     nodeBudget?: number;
     /**
      * PR5 — enable LLM graph path-refinement: at each traversal hop a model picks
@@ -5871,6 +5930,10 @@ interface RecallDiagnostics {
          * fast `vault_size = 0` population never established a baseline for this
          * cost, and why the ~850ms floor on the smallest NON-empty vaults had no
          * attributable owner.
+         *
+         * EXCEPTION — a mixed fact + chunk recall embeds the query ONCE, during
+         * {@link prep}, and hands the vector to both lanes. There `queryEmbed` is
+         * that shared embed and sits inside `prep`, not `factLane`.
          */
         queryEmbed: number;
         /** Chunk-lane search (`searchChunksOp`). */
@@ -8011,6 +8074,38 @@ declare function createMemoryEngineTool(storageCtx: StorageOperationsContext, em
     onRetrieve?: (conversationIds: string[]) => void;
 }): ToolConfig;
 
+/**
+ * `memory_vault_search` chat tool — the executor half of the vault search.
+ *
+ * Split out of `searchTool.ts` to break the `recall` <-> `searchTool` import
+ * cycle: `recall()` statically imports the vault search from `searchTool.ts`,
+ * and this executor routes through `recall()`. While both lived in one module
+ * the executor reached recall through a dynamic `import()`, and the cycle it
+ * papered over is what surfaced as the order-dependent
+ * `Cannot access 'nowMs' before initialization` flake. With the executor here,
+ * the graph is a straight line: executor -> recall -> searchTool.
+ *
+ * `searchTool.ts` must NOT import (or re-export) from this module, or the
+ * cycle comes back. The public name is re-exported from the barrel
+ * (`./index.ts`), which is the path every entry point already uses.
+ */
+
+/**
+ * Creates a memory vault search tool for use with chat completions.
+ *
+ * The tool allows the LLM to search through vault memories using semantic
+ * similarity. Vault entries should have their embeddings pre-computed in the
+ * cache (via preEmbedVaultMemories or eagerEmbedContent). Any missing
+ * embeddings are computed on the fly as a fallback.
+ *
+ * @param vaultCtx - Vault operations context for database access
+ * @param embeddingOptions - Options for embedding generation (auth, base URL)
+ * @param cache - Pre-populated embedding cache
+ * @param searchOptions - Optional search configuration
+ * @returns A ToolConfig that can be passed to chat completion tools
+ */
+declare function createMemoryVaultSearchTool(vaultCtx: VaultMemoryOperationsContext, embeddingOptions: EmbeddingOptions, cache: VaultEmbeddingCache, searchOptions?: MemoryVaultSearchOptions): ToolConfig;
+
 /**
  * Memory Vault Tool
  *
@@ -9319,7 +9414,7 @@ declare function reflect(query: string, ctx: RecallContext, options: ReflectOpti
 declare class RerankerUnavailableError extends Error {
     /** The underlying import failure, kept for debugging. */
     readonly reason: unknown;
-    constructor(reason: unknown);
+    constructor(reason: unknown, message?: string);
 }
 /**
  * Whether the cross-encoder reranker can run in this environment.