memorix 1.4.6 → 1.5.1

package/dist/sdk.js

@@ -3377,6 +3377,7 @@ var init_resolved_config = __esm({
 // src/config.ts
 var config_exports = {};
 __export(config_exports, {
+  defaultEmbeddingModelFor: () => defaultEmbeddingModelFor,
   getAgentLLMApiKey: () => getAgentLLMApiKey,
   getAgentLLMBaseUrl: () => getAgentLLMBaseUrl,
   getAgentLLMModel: () => getAgentLLMModel,
@@ -3439,7 +3440,19 @@ function getEmbeddingBaseUrl() {
   return getResolvedEmbeddingLane().baseUrl || "https://api.openai.com/v1";
 }
 function getEmbeddingModel() {
-  return getResolvedEmbeddingLane().model || "text-embedding-3-small";
+  const lane = getResolvedEmbeddingLane();
+  return defaultEmbeddingModelFor(lane.baseUrl, lane.model);
+}
+function defaultEmbeddingModelFor(baseUrl, explicitModel) {
+  if (explicitModel) return explicitModel;
+  try {
+    const url = baseUrl ? new URL(baseUrl) : null;
+    if (url && (url.hostname === "openrouter.ai" || url.hostname.endsWith(".openrouter.ai"))) {
+      return "qwen/qwen3-embedding-8b";
+    }
+  } catch {
+  }
+  return "text-embedding-3-small";
 }
 function getEmbeddingDimensions() {
   return getResolvedEmbeddingLane().dimensions ?? null;
@@ -3978,6 +3991,8 @@ function getPreferredBatchSize(config) {
 }
 function parseBatchLimit(error) {
   if (!(error instanceof Error)) return null;
+  const status = error instanceof EmbeddingAPIError ? error.status : Number(error.message.match(/Embedding API error \((\d{3})\)/i)?.[1] ?? 0);
+  if (status > 0 && status !== 400) return null;
   const explicit = error.message.match(/should not be larger than\s+(\d+)/i);
   if (explicit) return parseInt(explicit[1], 10);
   if (/batch size/i.test(error.message)) {
@@ -3990,37 +4005,99 @@ async function fetchWithRetry(url, apiKey, body, options = {}, attempt = 0, nati
   const controller = new AbortController();
   const timeoutMs = typeof options.timeoutMs === "number" && Number.isFinite(options.timeoutMs) ? Math.max(100, Math.min(Math.floor(options.timeoutMs), 6e4)) : 1e4;
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const signal = options.signal ? AbortSignal.any([options.signal, controller.signal]) : controller.signal;
   let response;
   try {
     response = await fetch(url, {
       method: "POST",
       headers: nativeGemini ? { "Content-Type": "application/json", "x-goog-api-key": apiKey } : { "Content-Type": "application/json", "Authorization": `Bearer ${apiKey}` },
       body: JSON.stringify(body),
-      signal: controller.signal
+      signal
     });
   } catch (err) {
     clearTimeout(timeout);
-    if (err instanceof Error && err.name === "AbortError") {
+    if (err instanceof Error && (err.name === "AbortError" || controller.signal.aborted || options.signal?.aborted)) {
       throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
     }
     throw err;
   }
-  clearTimeout(timeout);
-  if (response.ok) {
-    return response.json();
+  try {
+    if (response.ok) {
+      return await raceWithAbort(
+        response.json(),
+        signal
+      );
+    }
+    if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES2) {
+      const delay2 = BASE_DELAY_MS * Math.pow(2, attempt);
+      const retryAfter = response.headers.get("retry-after");
+      const parsedRetryAfter = retryAfter ? parseInt(retryAfter, 10) * 1e3 : NaN;
+      const waitMs = Number.isFinite(parsedRetryAfter) ? parsedRetryAfter : delay2;
+      console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES2} in ${waitMs}ms`);
+      await waitForRetry(waitMs, options.signal);
+      return fetchWithRetry(url, apiKey, body, options, attempt + 1, nativeGemini);
+    }
+    const errorText2 = await raceWithAbort(
+      response.text().catch(() => "unknown error"),
+      signal
+    );
+    throw new EmbeddingAPIError(response.status, errorText2);
+  } catch (err) {
+    if (err instanceof Error && (err.name === "AbortError" || controller.signal.aborted || options.signal?.aborted)) {
+      throw new Error(`Embedding API timeout after ${timeoutMs}ms: ${url}`);
+    }
+    throw err;
+  } finally {
+    clearTimeout(timeout);
   }
-  if (options.retry !== false && (response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES2) {
-    const delay2 = BASE_DELAY_MS * Math.pow(2, attempt);
-    const retryAfter = response.headers.get("retry-after");
-    const waitMs = retryAfter ? parseInt(retryAfter, 10) * 1e3 : delay2;
-    console.error(`[memorix] Embedding API ${response.status}, retry ${attempt + 1}/${MAX_RETRIES2} in ${waitMs}ms`);
+}
+function abortError() {
+  const error = new Error("Embedding API request aborted");
+  error.name = "AbortError";
+  return error;
+}
+function raceWithAbort(promise, signal) {
+  if (signal.aborted) return Promise.reject(abortError());
+  return new Promise((resolve2, reject) => {
+    const onAbort = () => {
+      signal.removeEventListener("abort", onAbort);
+      reject(abortError());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve2(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      }
+    );
+  });
+}
+async function waitForRetry(waitMs, signal) {
+  if (!signal) {
     await new Promise((resolve2) => setTimeout(resolve2, waitMs));
-    return fetchWithRetry(url, apiKey, body, options, attempt + 1, nativeGemini);
+    return;
   }
-  const errorText2 = await response.text().catch(() => "unknown error");
-  throw new Error(`Embedding API error (${response.status}): ${errorText2}`);
+  const abortSignal = signal;
+  if (abortSignal.aborted) throw new Error("Embedding API retry aborted");
+  await new Promise((resolve2, reject) => {
+    const timer = setTimeout(done, waitMs);
+    const onAbort = () => {
+      clearTimeout(timer);
+      abortSignal.removeEventListener("abort", onAbort);
+      reject(new Error("Embedding API retry aborted"));
+    };
+    function done() {
+      abortSignal.removeEventListener("abort", onAbort);
+      resolve2();
+    }
+    abortSignal.addEventListener("abort", onAbort, { once: true });
+  });
 }
-var cache3, MAX_CACHE_SIZE3, diskCacheDirty2, diskSaveTimer, diskCacheLoaded, diskCacheLoadPromise, MAX_INPUT_CHARS, MAX_CONCURRENCY, DISK_SAVE_DEBOUNCE_MS, DEFAULT_MAX_BATCH_SIZE, DASHSCOPE_MAX_BATCH_SIZE, MAX_RETRIES2, BASE_DELAY_MS, APIEmbeddingProvider;
+var cache3, MAX_CACHE_SIZE3, diskCacheDirty2, diskSaveTimer, diskCacheLoaded, diskCacheLoadPromise, MAX_INPUT_CHARS, MAX_CONCURRENCY, DISK_SAVE_DEBOUNCE_MS, DEFAULT_MAX_BATCH_SIZE, DASHSCOPE_MAX_BATCH_SIZE, MAX_RETRIES2, BASE_DELAY_MS, EmbeddingAPIError, APIEmbeddingProvider;
 var init_api_provider = __esm({
   "src/embedding/api-provider.ts"() {
     "use strict";
@@ -4039,6 +4116,14 @@ var init_api_provider = __esm({
     DASHSCOPE_MAX_BATCH_SIZE = 10;
     MAX_RETRIES2 = 3;
     BASE_DELAY_MS = 500;
+    EmbeddingAPIError = class extends Error {
+      status;
+      constructor(status, detail) {
+        super(`Embedding API error (${status}): ${detail}`);
+        this.name = "EmbeddingAPIError";
+        this.status = status;
+      }
+    };
     APIEmbeddingProvider = class _APIEmbeddingProvider {
       name;
       dimensions;
@@ -4250,15 +4335,14 @@ var init_api_provider = __esm({
             }
           } catch (error) {
             const providerLimit = parseBatchLimit(error);
-            const fallbackSize = providerLimit ?? Math.ceil(chunkTexts.length / 2);
-            if (chunkTexts.length > 1 && fallbackSize < chunkTexts.length) {
+            if (providerLimit !== null && chunkTexts.length > 1 && providerLimit < chunkTexts.length) {
               console.error(
-                `[memorix] Embedding batch too large for provider, retrying in chunks of ${fallbackSize}`
+                `[memorix] Embedding batch too large for provider, retrying in chunks of ${providerLimit}`
               );
-              for (let start = 0; start < chunkTexts.length; start += fallbackSize) {
+              for (let start = 0; start < chunkTexts.length; start += providerLimit) {
                 await processChunk(
-                  chunkTexts.slice(start, start + fallbackSize),
-                  chunkIndices.slice(start, start + fallbackSize)
+                  chunkTexts.slice(start, start + providerLimit),
+                  chunkIndices.slice(start, start + providerLimit)
                 );
               }
               return;
@@ -5122,22 +5206,23 @@ function getLLMConfig() {
 function setLLMConfig(config) {
   currentConfig = config;
 }
-async function callLLM(systemPrompt, userMessage) {
+async function callLLM(systemPrompt, userMessage, signal) {
   if (!currentConfig) {
     throw new Error("LLM not configured. Set MEMORIX_LLM_API_KEY or OPENAI_API_KEY.");
   }
   if (currentConfig.provider === "anthropic") {
-    return callAnthropic(systemPrompt, userMessage);
+    return callAnthropic(systemPrompt, userMessage, signal);
   }
-  return callOpenAICompatible(systemPrompt, userMessage);
+  return callOpenAICompatible(systemPrompt, userMessage, signal);
 }
-async function callOpenAICompatible(systemPrompt, userMessage) {
+async function callOpenAICompatible(systemPrompt, userMessage, signal) {
   const config = currentConfig;
   let base = config.baseUrl.replace(/\/+$/, "");
   if (!base.endsWith("/v1")) base += "/v1";
   const url = `${base}/chat/completions`;
+  const fetchSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(LLM_CALL_TIMEOUT_MS)]) : AbortSignal.timeout(LLM_CALL_TIMEOUT_MS);
   const response = await fetch(url, {
-    signal: AbortSignal.timeout(LLM_CALL_TIMEOUT_MS),
+    signal: fetchSignal,
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -5154,10 +5239,10 @@ async function callOpenAICompatible(systemPrompt, userMessage) {
     })
   });
   if (!response.ok) {
-    const error = await readResponseText(response, void 0, 64 * 1024).catch(() => "unknown error");
+    const error = await readResponseText(response, signal, 64 * 1024).catch(() => "unknown error");
     throw new Error(`LLM API error (${response.status}): ${error}`);
   }
-  const data = await readResponseJson(response);
+  const data = await readResponseJson(response, signal);
   return {
     content: data.choices[0]?.message?.content ?? "",
     usage: data.usage ? {
@@ -5166,11 +5251,12 @@ async function callOpenAICompatible(systemPrompt, userMessage) {
     } : void 0
   };
 }
-async function callAnthropic(systemPrompt, userMessage) {
+async function callAnthropic(systemPrompt, userMessage, signal) {
   const config = currentConfig;
   const url = `${config.baseUrl}/messages`;
+  const fetchSignal = signal ? AbortSignal.any([signal, AbortSignal.timeout(LLM_CALL_TIMEOUT_MS)]) : AbortSignal.timeout(LLM_CALL_TIMEOUT_MS);
   const response = await fetch(url, {
-    signal: AbortSignal.timeout(LLM_CALL_TIMEOUT_MS),
+    signal: fetchSignal,
     method: "POST",
     headers: {
       "Content-Type": "application/json",
@@ -5188,10 +5274,10 @@ async function callAnthropic(systemPrompt, userMessage) {
     })
   });
   if (!response.ok) {
-    const error = await readResponseText(response, void 0, 64 * 1024).catch(() => "unknown error");
+    const error = await readResponseText(response, signal, 64 * 1024).catch(() => "unknown error");
     throw new Error(`Anthropic API error (${response.status}): ${error}`);
   }
-  const data = await readResponseJson(response);
+  const data = await readResponseJson(response, signal);
   return {
     content: data.content[0]?.text ?? "",
     usage: data.usage ? {
@@ -5696,6 +5782,57 @@ function withTimeout(promise, ms, label) {
     );
   });
 }
+function withTimeoutSignal(operation, ms, label, parentSignal) {
+  const controller = new AbortController();
+  const signal = parentSignal ? AbortSignal.any([parentSignal, controller.signal]) : controller.signal;
+  return new Promise((resolve2, reject) => {
+    let settled = false;
+    let timedOut = false;
+    let timer;
+    const cleanup = () => {
+      if (timer !== void 0) clearTimeout(timer);
+      parentSignal?.removeEventListener("abort", onParentAbort);
+    };
+    const onParentAbort = () => {
+      if (settled || timedOut) return;
+      settled = true;
+      cleanup();
+      reject(parentSignal?.reason ?? new Error(`${label} aborted`));
+    };
+    parentSignal?.addEventListener("abort", onParentAbort, { once: true });
+    timer = setTimeout(() => {
+      if (settled) return;
+      timedOut = true;
+      controller.abort(new Error(`${label} timed out after ${ms}ms`));
+      settled = true;
+      cleanup();
+      reject(new Error(`${label} timed out after ${ms}ms`));
+    }, ms);
+    let pending;
+    try {
+      pending = operation(signal);
+    } catch (error) {
+      settled = true;
+      cleanup();
+      reject(error);
+      return;
+    }
+    pending.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve2(value);
+      },
+      (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(timedOut ? new Error(`${label} timed out after ${ms}ms`) : error);
+      }
+    );
+  });
+}
 var init_timeout = __esm({
   "src/timeout.ts"() {
     "use strict";
@@ -6560,16 +6697,18 @@ async function searchObservations(options) {
           );
         } else {
           const EMBEDDING_TIMEOUT_MS = 15e3;
-          queryVector = await withTimeout(
-            provider2.embedInput ? provider2.embedInput(
+          queryVector = await withTimeoutSignal(
+            (signal) => provider2.embedInput ? provider2.embedInput(
               { modality: "text", text: expandedEmbeddingQuery },
-              { intent: "query", timeoutMs: EMBEDDING_TIMEOUT_MS, retry: false }
+              { intent: "query", timeoutMs: EMBEDDING_TIMEOUT_MS, retry: false, signal }
             ) : provider2.embed(expandedEmbeddingQuery, {
               timeoutMs: EMBEDDING_TIMEOUT_MS,
-              retry: false
+              retry: false,
+              signal
             }),
             EMBEDDING_TIMEOUT_MS,
-            "Embedding"
+            "Embedding",
+            options.signal
           );
           mark("embedding");
           const cjkRatio = (originalQuery.match(/[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff\uac00-\ud7af]/g) || []).length / originalQuery.length;
@@ -144989,7 +145128,13 @@ async function maintainLongTermMemories(input) {
   }
   for (const group of groups.values()) {
     if (group.length < 2) continue;
-    group.sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+    group.sort((a, b) => {
+      const byCreatedAt = Date.parse(b.createdAt) - Date.parse(a.createdAt);
+      if (byCreatedAt !== 0) return byCreatedAt;
+      const byUpdatedAt = Date.parse(b.updatedAt) - Date.parse(a.updatedAt);
+      if (byUpdatedAt !== 0) return byUpdatedAt;
+      return b.id.localeCompare(a.id);
+    });
     const newest = group[0];
     for (const older of group.slice(1)) {
       try {
@@ -151475,13 +151620,13 @@ function verifyType(declaredType, narrative, title) {
   }
   return { type: declaredType, corrected: false };
 }
-async function extractFactsWithLLM(narrative, title, existingFacts) {
+async function extractFactsWithLLM(narrative, title, existingFacts, signal) {
   try {
     const { callLLM: callLLM2 } = await Promise.resolve().then(() => (init_provider2(), provider_exports2));
     const input = `Title: ${title}
 Content: ${narrative}${existingFacts.length > 0 ? `
 Already known facts (don't repeat): ${existingFacts.join("; ")}` : ""}`;
-    const response = await callLLM2(LLM_EXTRACT_PROMPT, input);
+    const response = await callLLM2(LLM_EXTRACT_PROMPT, input, signal);
     const text2 = response.content.trim();
     const jsonMatch = text2.match(/\{[\s\S]*\}/);
     if (!jsonMatch) return [];
@@ -151490,15 +151635,16 @@ Already known facts (don't repeat): ${existingFacts.join("; ")}` : ""}`;
     if (!Array.isArray(facts)) return [];
     const existingLower = new Set(existingFacts.map((f3) => f3.toLowerCase().trim()));
     return facts.filter((f3) => typeof f3 === "string" && f3.length >= 5).filter((f3) => !existingLower.has(f3.toLowerCase().trim())).slice(0, 10);
-  } catch {
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return [];
   }
 }
-async function runExtract(input, existingEntities, useLLM = false) {
+async function runExtract(input, existingEntities, useLLM = false, signal) {
   const callerFacts = input.facts ?? [];
   let extractedFacts;
   if (useLLM) {
-    extractedFacts = await extractFactsWithLLM(input.narrative, input.title, callerFacts);
+    extractedFacts = await extractFactsWithLLM(input.narrative, input.title, callerFacts, signal);
     if (extractedFacts.length === 0) {
       extractedFacts = extractFacts2(input.narrative, callerFacts);
     }
@@ -151718,7 +151864,7 @@ function mergeFacts2(oldFacts, newFacts) {
   }
   return merged;
 }
-async function resolveWithLLM(extracted, hits, getObservation2) {
+async function resolveWithLLM(extracted, hits, getObservation2, signal) {
   try {
     const { callLLM: callLLM2 } = await Promise.resolve().then(() => (init_provider2(), provider_exports2));
     const existingMemories = hits.slice(0, 5).map((h2, i2) => ({
@@ -151735,7 +151881,7 @@ Facts: ${extracted.facts.join("; ")}
 
 EXISTING MEMORIES:
 ${existingMemories.map((m2) => `[ID:${m2.id}] ${m2.title} | ${m2.content} | Facts: ${m2.facts}`).join("\n")}`;
-    const response = await callLLM2(LLM_RESOLVE_PROMPT, input);
+    const response = await callLLM2(LLM_RESOLVE_PROMPT, input, signal);
     const text2 = response.content.trim();
     const jsonMatch = text2.match(/\{[\s\S]*\}/);
     if (!jsonMatch) return null;
@@ -151772,7 +151918,8 @@ ${existingMemories.map((m2) => `[ID:${m2.id}] ${m2.title} | ${m2.content} | Fact
       };
     }
     return null;
-  } catch {
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return null;
   }
 }
@@ -151790,19 +151937,20 @@ function scoreCandidate(extracted, candidate) {
   const contradiction = hasContradiction(candidate.narrative, extracted.narrative);
   return { score, searchSimilarity, entityMatch, richer, contradiction };
 }
-async function runResolve(extracted, projectId, searchMemories, getObservation2, useLLM = false) {
+async function runResolve(extracted, projectId, searchMemories, getObservation2, useLLM = false, signal) {
   const query = `${extracted.title} ${extracted.narrative.substring(0, 200)}`;
   let hits;
   try {
-    hits = await searchMemories(query, 5, projectId);
-  } catch {
+    hits = await searchMemories(query, 5, projectId, signal);
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return { action: "new", reason: "Search unavailable, defaulting to new" };
   }
   if (hits.length === 0) {
     return { action: "new", reason: "No similar existing memories found" };
   }
   if (useLLM) {
-    const llmResult = await resolveWithLLM(extracted, hits, getObservation2);
+    const llmResult = await resolveWithLLM(extracted, hits, getObservation2, signal);
     if (llmResult) return llmResult;
   }
   const scored = hits.map((hit) => ({
@@ -152224,7 +152372,7 @@ async function runFormation(input, config) {
   const existingEntities = config.getEntityNames();
   const extractStartTime = Date.now();
   emitStageEvent("extract", "start");
-  const extraction = await runExtract(input, existingEntities, config.useLLM);
+  const extraction = await runExtract(input, existingEntities, config.useLLM, config.signal);
   stageDurationsMs.extract = Date.now() - extractStartTime;
   emitStageEvent("extract", "success", stageDurationsMs.extract);
   stagesCompleted = 1;
@@ -152244,7 +152392,8 @@ async function runFormation(input, config) {
       input.projectId,
       config.searchMemories,
       config.getObservation,
-      config.useLLM
+      config.useLLM,
+      config.signal
     );
     stageDurationsMs.resolve = Date.now() - resolveStartTime;
     emitStageEvent("resolve", "success", stageDurationsMs.resolve);
@@ -165629,7 +165778,7 @@ The path should point to a directory containing a .git folder.`
   };
   const server = existingServer ?? new McpServer({
     name: "memorix",
-    version: true ? "1.4.6" : "1.0.1"
+    version: true ? "1.5.1" : "1.0.1"
   });
   const originalRegisterTool = server.registerTool.bind(server);
   server.registerTool = ((name, ...args) => {
@@ -165818,8 +165967,8 @@ The path should point to a directory containing a .git folder.`
                 mode: "active",
                 useLLM: isLLMEnabled(),
                 minValueScore: 0.3,
-                searchMemories: async (q, limit2, pid) => {
-                  const result = await compactSearch({ query: q, limit: limit2, projectId: pid, status: "active", reader });
+                searchMemories: async (q, limit2, pid, signal) => {
+                  const result = await compactSearch({ query: q, limit: limit2, projectId: pid, status: "active", reader, signal });
                   if (result.entries.length === 0) return [];
                   const details = await compactDetail(result.entries.map((e2) => e2.id), { reader });
                   return details.documents.map((d, i2) => ({
@@ -165849,16 +165998,19 @@ The path should point to a directory containing a .git folder.`
                 getEntityNames: () => graphManager.getEntityNames(),
                 onStageEvent: onFormationStageEvent
               };
-              formationResult = await withTimeout(
-                runFormation({
-                  entityName,
-                  type,
-                  title,
-                  narrative,
-                  facts: safeFacts,
-                  projectId: project.id,
-                  source: "explicit"
-                }, formationConfig),
+              formationResult = await withTimeoutSignal(
+                async (signal) => {
+                  formationConfig.signal = signal;
+                  return runFormation({
+                    entityName,
+                    type,
+                    title,
+                    narrative,
+                    facts: safeFacts,
+                    projectId: project.id,
+                    source: "explicit"
+                  }, formationConfig);
+                },
                 FORMATION_TIMEOUT_MS,
                 "Formation pipeline"
               );
@@ -166208,8 +166360,8 @@ Auto-enriched: ${enrichmentParts.join(", ")}` : "";
                 mode: formationMode,
                 useLLM: isLLMEnabled(),
                 minValueScore: 0.3,
-                searchMemories: async (q, limit2, pid) => {
-                  const result = await compactSearch({ query: q, limit: limit2, projectId: pid, status: "active", reader });
+                searchMemories: async (q, limit2, pid, signal) => {
+                  const result = await compactSearch({ query: q, limit: limit2, projectId: pid, status: "active", reader, signal });
                   if (result.entries.length === 0) return [];
                   const details = await compactDetail(result.entries.map((e2) => e2.id), { reader });
                   return details.documents.map((d, i2) => ({
@@ -166230,8 +166382,11 @@ Auto-enriched: ${enrichmentParts.join(", ")}` : "";
                 },
                 getEntityNames: () => graphManager.getEntityNames()
               };
-              const formed = await withTimeout(
-                runFormation({ entityName, type, title, narrative, facts: safeFacts, projectId: project.id, source: "explicit", topicKey }, formationConfig),
+              const formed = await withTimeoutSignal(
+                async (signal) => {
+                  formationConfig.signal = signal;
+                  return runFormation({ entityName, type, title, narrative, facts: safeFacts, projectId: project.id, source: "explicit", topicKey }, formationConfig);
+                },
                 FORMATION_TIMEOUT_MS,
                 "Shadow formation"
               );

package/dist/types.d.ts

@@ -360,6 +360,8 @@ interface SearchOptions {
      * `thorough` explicitly permits optional LLM query rewrite and reranking.
      */
     quality?: RetrievalQuality;
+    /** Abort provider-backed retrieval when the owning request is cancelled. */
+    signal?: AbortSignal;
 }
 /** Topic key family heuristics for suggesting stable topic keys */
 declare const TOPIC_KEY_FAMILIES: Record<string, string[]>;