@anuma/sdk 6.24.1 → 6.25.1

package/dist/index.cjs

@@ -1336,11 +1336,54 @@ var DEFAULT_API_EMBEDDING_MODEL = "qwen/qwen3-embedding-8b";
 
 // src/lib/memoryEngine/generate.ts
 var EMBED_MAX_ATTEMPTS = 4;
-async function withEmbeddingRetry(call) {
+var DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_EMBEDDING_TOKEN_TIMEOUT_MS = 1e4;
+async function withDeadline(run, ms, what, parent) {
+  if (!(ms > 0) || !Number.isFinite(ms)) return Promise.resolve().then(() => run(parent));
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort(parent?.reason);
+  let timer;
+  try {
+    if (parent?.aborted) onParentAbort();
+    else parent?.addEventListener("abort", onParentAbort, { once: true });
+    const work = Promise.resolve().then(() => run(controller.signal));
+    work.catch(() => {
+    });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const err = new Error(`${what} timed out after ${ms}ms`);
+        err.name = "TimeoutError";
+        controller.abort(err);
+        reject(err);
+      }, ms);
+    });
+    return await Promise.race([work, deadline]);
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener("abort", onParentAbort);
+  }
+}
+async function resolveAuthHeaders(options, parent) {
+  const { getToken, apiKey } = options;
+  if (apiKey) return { "X-API-Key": apiKey };
+  if (!getToken) throw new Error("Either apiKey or getToken must be provided");
+  const token = await withDeadline(
+    () => getToken(),
+    options.tokenTimeoutMs ?? DEFAULT_EMBEDDING_TOKEN_TIMEOUT_MS,
+    "embedding auth token read",
+    parent
+  );
+  if (!token) {
+    throw new Error("No token available for embedding generation");
+  }
+  return { Authorization: `Bearer ${token}` };
+}
+async function withEmbeddingRetry(call, stop) {
   let last;
   let lastThrown;
   let threw = false;
   for (let attempt = 1; attempt <= EMBED_MAX_ATTEMPTS; attempt++) {
+    if (stop?.aborted) throw stop.reason;
     try {
       threw = false;
       last = await call();
@@ -1375,34 +1418,36 @@ function embeddingErrorFrom(response) {
   return new EmbeddingHttpError(message, response.response?.status);
 }
 async function generateEmbedding(text, options) {
-  const { baseUrl = BASE_URL, getToken, apiKey, model, cache } = options;
+  const total = options.totalTimeoutMs;
+  if (total === void 0) return embedOne(text, options, void 0);
+  return withDeadline((signal) => embedOne(text, options, signal), total, "embedding");
+}
+async function embedOne(text, options, outer) {
+  const { baseUrl = BASE_URL, model, cache } = options;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   if (cache) {
     const cached = cache.get(text);
     if (cached) return Array.from(cached);
   }
-  let headers;
-  if (apiKey) {
-    headers = { "X-API-Key": apiKey };
-  } else if (getToken) {
-    const token = await getToken();
-    if (!token) {
-      throw new Error("No token available for embedding generation");
-    }
-    headers = { Authorization: `Bearer ${token}` };
-  } else {
-    throw new Error("Either apiKey or getToken must be provided");
-  }
+  const headers = await resolveAuthHeaders(options, outer);
   const response = await withEmbeddingRetry(
-    () => postApiV1Embeddings({
-      baseUrl,
-      body: {
-        // Mask PII from the request body only — the cache above still keys on
-        // the original `text`, so callers keep their original values.
-        input: options.maskInput ? options.maskInput(text) : text,
-        model: model ?? DEFAULT_API_EMBEDDING_MODEL
-      },
-      headers
-    })
+    () => withDeadline(
+      (signal) => postApiV1Embeddings({
+        baseUrl,
+        body: {
+          // Mask PII from the request body only — the cache above still keys on
+          // the original `text`, so callers keep their original values.
+          input: options.maskInput ? options.maskInput(text) : text,
+          model: model ?? DEFAULT_API_EMBEDDING_MODEL
+        },
+        headers,
+        ...signal && { signal }
+      }),
+      timeoutMs,
+      "embedding request",
+      outer
+    ),
+    outer
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -1425,14 +1470,19 @@ async function generateEmbedding(text, options) {
 }
 var DEFAULT_EMBEDDING_BATCH_SIZE = 100;
 var DEFAULT_EMBEDDING_BATCH_CONCURRENCY = 3;
-async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput) {
+async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs) {
   const response = await withEmbeddingRetry(
-    () => postApiV1Embeddings({
-      baseUrl,
-      // Mask PII from the request body only; cache/order still key on originals.
-      body: { input: maskInput ? texts.map(maskInput) : texts, model },
-      headers
-    })
+    () => withDeadline(
+      (signal) => postApiV1Embeddings({
+        baseUrl,
+        // Mask PII from the request body only; cache/order still key on originals.
+        body: { input: maskInput ? texts.map(maskInput) : texts, model },
+        headers,
+        ...signal && { signal }
+      }),
+      timeoutMs,
+      "embedding batch request"
+    )
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -1450,7 +1500,8 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
 }
 async function generateEmbeddings(texts, options) {
   if (texts.length === 0) return [];
-  const { baseUrl = BASE_URL, getToken, apiKey, model, batchSize, cache } = options;
+  const { baseUrl = BASE_URL, model, batchSize, cache } = options;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   const chunkSize = batchSize ?? DEFAULT_EMBEDDING_BATCH_SIZE;
   const results = new Array(texts.length).fill(null);
   const uncachedIndices = [];
@@ -1469,18 +1520,7 @@ async function generateEmbeddings(texts, options) {
   if (uncachedTexts.length === 0) {
     return results;
   }
-  let headers;
-  if (apiKey) {
-    headers = { "X-API-Key": apiKey };
-  } else if (getToken) {
-    const token = await getToken();
-    if (!token) {
-      throw new Error("No token available for embedding generation");
-    }
-    headers = { Authorization: `Bearer ${token}` };
-  } else {
-    throw new Error("Either apiKey or getToken must be provided");
-  }
+  const headers = await resolveAuthHeaders(options);
   const embeddingModel = model ?? DEFAULT_API_EMBEDDING_MODEL;
   let newEmbeddings;
   if (uncachedTexts.length <= chunkSize) {
@@ -1490,7 +1530,8 @@ async function generateEmbeddings(texts, options) {
       baseUrl,
       embeddingModel,
       options.onUsage,
-      options.maskInput
+      options.maskInput,
+      timeoutMs
     );
   } else {
     const chunks = [];
@@ -1508,7 +1549,8 @@ async function generateEmbeddings(texts, options) {
           baseUrl,
           embeddingModel,
           options.onUsage,
-          options.maskInput
+          options.maskInput,
+          timeoutMs
         );
       }
     };

package/dist/index.mjs

@@ -1134,11 +1134,54 @@ var DEFAULT_API_EMBEDDING_MODEL = "qwen/qwen3-embedding-8b";
 
 // src/lib/memoryEngine/generate.ts
 var EMBED_MAX_ATTEMPTS = 4;
-async function withEmbeddingRetry(call) {
+var DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS = 15e3;
+var DEFAULT_EMBEDDING_TOKEN_TIMEOUT_MS = 1e4;
+async function withDeadline(run, ms, what, parent) {
+  if (!(ms > 0) || !Number.isFinite(ms)) return Promise.resolve().then(() => run(parent));
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort(parent?.reason);
+  let timer;
+  try {
+    if (parent?.aborted) onParentAbort();
+    else parent?.addEventListener("abort", onParentAbort, { once: true });
+    const work = Promise.resolve().then(() => run(controller.signal));
+    work.catch(() => {
+    });
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const err = new Error(`${what} timed out after ${ms}ms`);
+        err.name = "TimeoutError";
+        controller.abort(err);
+        reject(err);
+      }, ms);
+    });
+    return await Promise.race([work, deadline]);
+  } finally {
+    clearTimeout(timer);
+    parent?.removeEventListener("abort", onParentAbort);
+  }
+}
+async function resolveAuthHeaders(options, parent) {
+  const { getToken, apiKey } = options;
+  if (apiKey) return { "X-API-Key": apiKey };
+  if (!getToken) throw new Error("Either apiKey or getToken must be provided");
+  const token = await withDeadline(
+    () => getToken(),
+    options.tokenTimeoutMs ?? DEFAULT_EMBEDDING_TOKEN_TIMEOUT_MS,
+    "embedding auth token read",
+    parent
+  );
+  if (!token) {
+    throw new Error("No token available for embedding generation");
+  }
+  return { Authorization: `Bearer ${token}` };
+}
+async function withEmbeddingRetry(call, stop) {
   let last;
   let lastThrown;
   let threw = false;
   for (let attempt = 1; attempt <= EMBED_MAX_ATTEMPTS; attempt++) {
+    if (stop?.aborted) throw stop.reason;
     try {
       threw = false;
       last = await call();
@@ -1173,34 +1216,36 @@ function embeddingErrorFrom(response) {
   return new EmbeddingHttpError(message, response.response?.status);
 }
 async function generateEmbedding(text, options) {
-  const { baseUrl = BASE_URL, getToken, apiKey, model, cache } = options;
+  const total = options.totalTimeoutMs;
+  if (total === void 0) return embedOne(text, options, void 0);
+  return withDeadline((signal) => embedOne(text, options, signal), total, "embedding");
+}
+async function embedOne(text, options, outer) {
+  const { baseUrl = BASE_URL, model, cache } = options;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   if (cache) {
     const cached = cache.get(text);
     if (cached) return Array.from(cached);
   }
-  let headers;
-  if (apiKey) {
-    headers = { "X-API-Key": apiKey };
-  } else if (getToken) {
-    const token = await getToken();
-    if (!token) {
-      throw new Error("No token available for embedding generation");
-    }
-    headers = { Authorization: `Bearer ${token}` };
-  } else {
-    throw new Error("Either apiKey or getToken must be provided");
-  }
+  const headers = await resolveAuthHeaders(options, outer);
   const response = await withEmbeddingRetry(
-    () => postApiV1Embeddings({
-      baseUrl,
-      body: {
-        // Mask PII from the request body only — the cache above still keys on
-        // the original `text`, so callers keep their original values.
-        input: options.maskInput ? options.maskInput(text) : text,
-        model: model ?? DEFAULT_API_EMBEDDING_MODEL
-      },
-      headers
-    })
+    () => withDeadline(
+      (signal) => postApiV1Embeddings({
+        baseUrl,
+        body: {
+          // Mask PII from the request body only — the cache above still keys on
+          // the original `text`, so callers keep their original values.
+          input: options.maskInput ? options.maskInput(text) : text,
+          model: model ?? DEFAULT_API_EMBEDDING_MODEL
+        },
+        headers,
+        ...signal && { signal }
+      }),
+      timeoutMs,
+      "embedding request",
+      outer
+    ),
+    outer
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -1223,14 +1268,19 @@ async function generateEmbedding(text, options) {
 }
 var DEFAULT_EMBEDDING_BATCH_SIZE = 100;
 var DEFAULT_EMBEDDING_BATCH_CONCURRENCY = 3;
-async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput) {
+async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage, maskInput, timeoutMs) {
   const response = await withEmbeddingRetry(
-    () => postApiV1Embeddings({
-      baseUrl,
-      // Mask PII from the request body only; cache/order still key on originals.
-      body: { input: maskInput ? texts.map(maskInput) : texts, model },
-      headers
-    })
+    () => withDeadline(
+      (signal) => postApiV1Embeddings({
+        baseUrl,
+        // Mask PII from the request body only; cache/order still key on originals.
+        body: { input: maskInput ? texts.map(maskInput) : texts, model },
+        headers,
+        ...signal && { signal }
+      }),
+      timeoutMs,
+      "embedding batch request"
+    )
   );
   if (response.error) {
     throw embeddingErrorFrom(response);
@@ -1248,7 +1298,8 @@ async function generateEmbeddingsBatch(texts, headers, baseUrl, model, onUsage,
 }
 async function generateEmbeddings(texts, options) {
   if (texts.length === 0) return [];
-  const { baseUrl = BASE_URL, getToken, apiKey, model, batchSize, cache } = options;
+  const { baseUrl = BASE_URL, model, batchSize, cache } = options;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_EMBEDDING_REQUEST_TIMEOUT_MS;
   const chunkSize = batchSize ?? DEFAULT_EMBEDDING_BATCH_SIZE;
   const results = new Array(texts.length).fill(null);
   const uncachedIndices = [];
@@ -1267,18 +1318,7 @@ async function generateEmbeddings(texts, options) {
   if (uncachedTexts.length === 0) {
     return results;
   }
-  let headers;
-  if (apiKey) {
-    headers = { "X-API-Key": apiKey };
-  } else if (getToken) {
-    const token = await getToken();
-    if (!token) {
-      throw new Error("No token available for embedding generation");
-    }
-    headers = { Authorization: `Bearer ${token}` };
-  } else {
-    throw new Error("Either apiKey or getToken must be provided");
-  }
+  const headers = await resolveAuthHeaders(options);
   const embeddingModel = model ?? DEFAULT_API_EMBEDDING_MODEL;
   let newEmbeddings;
   if (uncachedTexts.length <= chunkSize) {
@@ -1288,7 +1328,8 @@ async function generateEmbeddings(texts, options) {
       baseUrl,
       embeddingModel,
       options.onUsage,
-      options.maskInput
+      options.maskInput,
+      timeoutMs
     );
   } else {
     const chunks = [];
@@ -1306,7 +1347,8 @@ async function generateEmbeddings(texts, options) {
           baseUrl,
           embeddingModel,
           options.onUsage,
-          options.maskInput
+          options.maskInput,
+          timeoutMs
         );
       }
     };

package/dist/memory/context.d.mts

@@ -430,6 +430,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). */
@@ -457,7 +471,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
@@ -669,6 +684,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`). */

package/dist/memory/context.d.ts

@@ -430,6 +430,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). */
@@ -457,7 +471,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
@@ -669,6 +684,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`). */