memorix 1.5.0 → 1.6.0

package/src/knowledge/workset.ts

@@ -8,6 +8,7 @@ import { WorkflowStore } from './workflow-store.js';
 import { OutcomeStore } from './outcome-store.js';
 import { qualityFromOutcome, type OutcomeQuality } from './outcome-types.js';
 import { selectWorkflows } from './workflows.js';
+import type { AgentTarget } from '../types.js';
 import { renderLongTermMemorySummary, selectLongTermMemoriesForTask } from '../memory/long-term.js';
 import { governContextCandidates, type GovernancePlan } from './governor.js';
 import type {
@@ -73,6 +74,18 @@ export interface WorksetWorkflow {
   cautions: string[];
 }
 
+/**
+ * A task-scoped plan assembled from existing workflow and wiki assets. It is
+ * descriptive rather than an authorization boundary: host agents retain their
+ * own tool and approval policies.
+ */
+export interface WorksetAgentLoadout {
+  agent: AgentTarget;
+  workflowIds: string[];
+  requiredContext: string[];
+  allowedTools: string[];
+}
+
 export interface WorksetMemorySource {
   id: number;
   title: string;
@@ -156,6 +169,7 @@ export interface TaskWorkset {
   pages: WorksetPage[];
   durableMemory: WorksetLongTermMemory[];
   workflows: WorksetWorkflow[];
+  agentLoadout?: WorksetAgentLoadout;
   cautions: WorksetCaution[];
   verification: string[];
   evidenceIds: string[];
@@ -179,6 +193,8 @@ export interface BuildTaskWorksetInput {
   projectId: string;
   dataDir: string;
   task?: string;
+  /** Optional target used to select workflows explicitly compatible with this agent. */
+  agent?: AgentTarget;
   lens: string;
   currentFacts?: string[];
   continuation?: WorksetContinuation;
@@ -313,6 +329,18 @@ function workflowOutput(selection: WorkflowSelection): WorksetWorkflow {
   };
 }
 
+function workflowLoadout(agent: AgentTarget | undefined, selections: WorkflowSelection[]): WorksetAgentLoadout | undefined {
+  if (!agent) return undefined;
+  return {
+    agent,
+    workflowIds: selections.map(selection => selection.workflow.id),
+    requiredContext: unique(selections.flatMap(selection => selection.workflow.requiredContext))
+      .map(item => short(item, 18)).slice(0, 4),
+    allowedTools: unique(selections.flatMap(selection => selection.workflow.allowedTools))
+      .map(item => short(item, 12)).slice(0, 6),
+  };
+}
+
 function appendLine(
   lines: string[],
   candidate: string,
@@ -853,6 +881,23 @@ export function renderTaskWorksetPrompt(input: Omit<TaskWorkset, 'prompt' | 'bud
     }
   }
 
+  if (input.agentLoadout) {
+    appendLine(lines, '', maxTokens, omitted, 'agent-loadout-heading');
+    appendLine(lines, 'Agent loadout (' + input.agentLoadout.agent + ')', maxTokens, omitted, 'agent-loadout-heading');
+    for (const required of input.agentLoadout.requiredContext.slice(0, 2)) {
+      appendLine(lines, '- Need: ' + required, maxTokens, omitted, 'agent-loadout-context');
+    }
+    if (input.agentLoadout.allowedTools.length > 0) {
+      appendLine(
+        lines,
+        '- Workflow tools: ' + input.agentLoadout.allowedTools.join(', '),
+        maxTokens,
+        omitted,
+        'agent-loadout-tools',
+      );
+    }
+  }
+
   if (input.verification.length > 0) {
     appendLine(lines, '', maxTokens, omitted, 'verification-heading');
     appendLine(lines, 'Verify', maxTokens, omitted, 'verification-heading');
@@ -965,6 +1010,7 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
   let workspace: KnowledgeWorkspace | undefined;
   let pages: WorksetPage[] = [];
   let workflows: WorksetWorkflow[] = [];
+  let workflowSelections: WorkflowSelection[] = [];
   try {
     workspace = await preferredWorkspace(input.projectId, input.dataDir);
     if (workspace) {
@@ -985,14 +1031,15 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
       if (task) {
         const workflowStore = new WorkflowStore();
         await workflowStore.init(input.dataDir);
-        const selected = selectWorkflows({
+        workflowSelections = selectWorkflows({
           workflows: workflowStore.listWorkflows(workspace.id, 'active'),
           task,
           projectId: input.projectId,
           store: workflowStore,
+          ...(input.agent ? { agent: input.agent } : {}),
           limit: 2,
         });
-        workflows = selected.map(workflowOutput);
+        workflows = workflowSelections.map(workflowOutput);
         for (const workflow of workflows) {
           for (const caution of workflow.cautions) {
             cautions.push({ kind: 'workflow-failed-verification', message: caution });
@@ -1018,6 +1065,10 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     workflows,
   });
   const governedDurableIds = new Set(governed.durableMemory.map(memory => memory.id));
+  const agentLoadout = workflowLoadout(
+    input.agent,
+    workflowSelections.filter(selection => governed.workflows.some(workflow => workflow.id === selection.workflow.id)),
+  );
   const evidenceIds = unique(governed.claims.flatMap(claim => evidenceIdsForClaim(
     claim,
     evidenceByClaim.get(claim.id) ?? [],
@@ -1084,6 +1135,9 @@ export async function buildTaskWorkset(input: BuildTaskWorksetInput): Promise<Ta
     pages: pages.filter(page => page.claimIds.some(claimId => governed.claims.some(claim => claim.id === claimId))),
     durableMemory: governed.durableMemory,
     workflows: governed.workflows,
+    ...(agentLoadout
+      ? { agentLoadout }
+      : {}),
     cautions: normalizedCautions,
     verification,
     evidenceIds,

package/src/llm/provider.ts

@@ -237,16 +237,17 @@ export function setLLMConfig(config: LLMConfig | null): void {
 export async function callLLM(
   systemPrompt: string,
   userMessage: string,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   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);
 }
 
 /**
@@ -255,6 +256,7 @@ export async function callLLM(
 async function callOpenAICompatible(
   systemPrompt: string,
   userMessage: string,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   const config = currentConfig!;
   // Auto-fix: append /v1 if baseUrl doesn't end with it (common user mistake)
@@ -262,8 +264,11 @@ async function callOpenAICompatible(
   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',
@@ -281,14 +286,14 @@ async function callOpenAICompatible(
   });
 
   if (!response.ok) {
-    const error = await readResponseText(response, undefined, 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<{
     choices: Array<{ message: { content: string } }>;
     usage?: { prompt_tokens: number; completion_tokens: number };
-  }>(response);
+  }>(response, signal);
 
   return {
     content: data.choices[0]?.message?.content ?? '',
@@ -305,12 +310,16 @@ async function callOpenAICompatible(
 async function callAnthropic(
   systemPrompt: string,
   userMessage: string,
+  signal?: AbortSignal,
 ): Promise<LLMResponse> {
   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',
@@ -329,14 +338,14 @@ async function callAnthropic(
   });
 
   if (!response.ok) {
-    const error = await readResponseText(response, undefined, 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<{
     content: Array<{ text: string }>;
     usage?: { input_tokens: number; output_tokens: number };
-  }>(response);
+  }>(response, signal);
 
   return {
     content: data.content[0]?.text ?? '',

package/src/memory/formation/extract.ts

@@ -278,11 +278,12 @@ async function extractFactsWithLLM(
   narrative: string,
   title: string,
   existingFacts: string[],
+  signal?: AbortSignal,
 ): Promise<string[]> {
   try {
     const { callLLM } = await import('../../llm/provider.js');
     const input = `Title: ${title}\nContent: ${narrative}${existingFacts.length > 0 ? `\nAlready known facts (don't repeat): ${existingFacts.join('; ')}` : ''}`;
-    const response = await callLLM(LLM_EXTRACT_PROMPT, input);
+    const response = await callLLM(LLM_EXTRACT_PROMPT, input, signal);
     const text = response.content.trim();
 
     // Parse JSON response
@@ -298,7 +299,8 @@ async function extractFactsWithLLM(
       .filter((f: unknown): f is string => typeof f === 'string' && f.length >= 5)
       .filter((f: string) => !existingLower.has(f.toLowerCase().trim()))
       .slice(0, 10);
-  } catch {
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return []; // LLM failure → fall back to rules
   }
 }
@@ -318,6 +320,7 @@ export async function runExtract(
   input: FormationInput,
   existingEntities: string[],
   useLLM = false,
+  signal?: AbortSignal,
 ): Promise<ExtractResult> {
   const callerFacts = input.facts ?? [];
 
@@ -325,7 +328,7 @@ export async function runExtract(
   let extractedFacts: string[];
   if (useLLM) {
     // LLM extraction (quality-first, Mem0-style)
-    extractedFacts = await extractFactsWithLLM(input.narrative, input.title, callerFacts);
+    extractedFacts = await extractFactsWithLLM(input.narrative, input.title, callerFacts, signal);
     // If LLM returned nothing, fall back to rules
     if (extractedFacts.length === 0) {
       extractedFacts = extractFacts(input.narrative, callerFacts);

package/src/memory/formation/index.ts

@@ -293,7 +293,7 @@ export async function runFormation(
   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;
@@ -317,6 +317,7 @@ export async function runFormation(
       config.searchMemories,
       config.getObservation,
       config.useLLM,
+      config.signal,
     );
     stageDurationsMs.resolve = Date.now() - resolveStartTime;
     emitStageEvent('resolve', 'success', stageDurationsMs.resolve);

package/src/memory/formation/resolve.ts

@@ -152,6 +152,7 @@ async function resolveWithLLM(
   extracted: ExtractResult,
   hits: SearchHit[],
   getObservation: (id: number) => ExistingMemoryRef | null,
+  signal?: AbortSignal,
 ): Promise<ResolveResult | null> {
   try {
     const { callLLM } = await import('../../llm/provider.js');
@@ -173,7 +174,7 @@ Facts: ${extracted.facts.join('; ')}
 EXISTING MEMORIES:
 ${existingMemories.map(m => `[ID:${m.id}] ${m.title} | ${m.content} | Facts: ${m.facts}`).join('\n')}`;
 
-    const response = await callLLM(LLM_RESOLVE_PROMPT, input);
+    const response = await callLLM(LLM_RESOLVE_PROMPT, input, signal);
     const text = response.content.trim();
 
     const jsonMatch = text.match(/\{[\s\S]*\}/);
@@ -214,7 +215,8 @@ ${existingMemories.map(m => `[ID:${m.id}] ${m.title} | ${m.content} | Facts: ${m
     }
 
     return null; // Unrecognized action
-  } catch {
+  } catch (error) {
+    if (signal?.aborted) throw error;
     return null; // LLM failure → fall back to rules
   }
 }
@@ -260,16 +262,18 @@ function scoreCandidate(
 export async function runResolve(
   extracted: ExtractResult,
   projectId: string,
-  searchMemories: (query: string, limit: number, projectId: string) => Promise<SearchHit[]>,
+  searchMemories: (query: string, limit: number, projectId: string, signal?: AbortSignal) => Promise<SearchHit[]>,
   getObservation: (id: number) => ExistingMemoryRef | null,
   useLLM = false,
+  signal?: AbortSignal,
 ): Promise<ResolveResult> {
   // Search for similar existing memories
   const query = `${extracted.title} ${extracted.narrative.substring(0, 200)}`;
   let hits: SearchHit[];
   try {
-    hits = await searchMemories(query, 5, projectId);
-  } catch {
+    hits = await searchMemories(query, 5, projectId, signal);
+  } catch (error) {
+    if (signal?.aborted) throw error;
     // Search failed — default to ADD
     return { action: 'new', reason: 'Search unavailable, defaulting to new' };
   }
@@ -280,7 +284,7 @@ export async function runResolve(
 
   // LLM-powered resolution (Mem0-style, quality-first)
   if (useLLM) {
-    const llmResult = await resolveWithLLM(extracted, hits, getObservation);
+    const llmResult = await resolveWithLLM(extracted, hits, getObservation, signal);
     if (llmResult) return llmResult;
     // LLM failed → fall through to rules-based resolution
   }

package/src/memory/formation/types.ts

@@ -201,12 +201,14 @@ export interface FormationConfig {
   shadow?: boolean;
   /** Enable LLM-powered stages (requires LLM API key) */
   useLLM: boolean;
+  /** Abort in-flight LLM work when the formation budget expires. */
+  signal?: AbortSignal;
   /** Minimum value score to proceed with storage (default: 0.3) */
   minValueScore: number;
   /** Sampling rate for hooks path (0-1). 0 = always shadow, 1 = always full resolve */
   hooksSamplingRate?: number;
   /** Function to search existing memories (injected dependency) */
-  searchMemories: (query: string, limit: number, projectId: string) => Promise<SearchHit[]>;
+  searchMemories: (query: string, limit: number, projectId: string, signal?: AbortSignal) => Promise<SearchHit[]>;
   /** Function to get observation by ID (injected dependency) */
   getObservation: (id: number) => ExistingMemoryRef | null;
   /** Function to list existing entity names (injected dependency) */

package/src/memory/long-term.ts

@@ -589,7 +589,13 @@ export 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 {

package/src/server.ts

@@ -50,7 +50,7 @@ import type { ExistingMemory } from './llm/memory-manager.js';
 import { runFormation, getMetricsSummary, getBeforeAfterMetrics } from './memory/formation/index.js';
 import type { FormationConfig, SearchHit, FormedMemory, FormationStage, FormationStageEvent } from './memory/formation/types.js';
 import { parseFormationTimeoutMs } from './server/formation-timeout.js';
-import { withTimeout } from './timeout.js';
+import { withTimeout, withTimeoutSignal } from './timeout.js';
 import { sanitizeCredentials } from './memory/secret-filter.js';
 import { getSurfacedIds, recordSurfacedIds } from './search/surfaced-registry.js';
 import {
@@ -828,8 +828,8 @@ export async function createMemorixServer(
             mode: 'active',
             useLLM: isLLMEnabled(),
             minValueScore: 0.3,
-            searchMemories: async (q: string, limit: number, pid: string): Promise<SearchHit[]> => {
-              const result = await compactSearch({ query: q, limit, projectId: pid, status: 'active', reader });
+            searchMemories: async (q: string, limit: number, pid: string, signal?: AbortSignal): Promise<SearchHit[]> => {
+              const result = await compactSearch({ query: q, limit, projectId: pid, status: 'active', reader, signal });
               if (result.entries.length === 0) return [];
               const details = await compactDetail(result.entries.map(e => e.id), { reader });
               return details.documents.map((d, i) => ({
@@ -860,8 +860,9 @@ export async function createMemorixServer(
             onStageEvent: onFormationStageEvent,
           };
 
-          formationResult = await withTimeout(
-            runFormation({
+          formationResult = await withTimeoutSignal(async (signal) => {
+            formationConfig.signal = signal;
+            return runFormation({
               entityName,
               type: type as ObservationType,
               title,
@@ -869,7 +870,8 @@ export async function createMemorixServer(
               facts: safeFacts,
               projectId: project.id,
               source: 'explicit',
-            }, formationConfig),
+            }, formationConfig);
+          },
             FORMATION_TIMEOUT_MS,
             'Formation pipeline',
           );
@@ -1265,8 +1267,8 @@ export async function createMemorixServer(
             mode: formationMode,
             useLLM: isLLMEnabled(),
             minValueScore: 0.3,
-            searchMemories: async (q: string, limit: number, pid: string): Promise<SearchHit[]> => {
-              const result = await compactSearch({ query: q, limit, projectId: pid, status: 'active', reader });
+            searchMemories: async (q: string, limit: number, pid: string, signal?: AbortSignal): Promise<SearchHit[]> => {
+              const result = await compactSearch({ query: q, limit, projectId: pid, status: 'active', reader, signal });
               if (result.entries.length === 0) return [];
               const details = await compactDetail(result.entries.map(e => e.id), { reader });
               return details.documents.map((d, i) => ({
@@ -1288,8 +1290,10 @@ export async function createMemorixServer(
             getEntityNames: () => graphManager.getEntityNames(),
           };
 
-          const formed = await withTimeout(
-            runFormation({ entityName, type: type as ObservationType, title, narrative, facts: safeFacts, projectId: project.id, source: 'explicit', topicKey }, formationConfig),
+          const formed = await withTimeoutSignal(async (signal) => {
+            formationConfig.signal = signal;
+            return runFormation({ entityName, type: type as ObservationType, title, narrative, facts: safeFacts, projectId: project.id, source: 'explicit', topicKey }, formationConfig);
+          },
             FORMATION_TIMEOUT_MS,
             'Shadow formation',
           );
@@ -1575,13 +1579,17 @@ export async function createMemorixServer(
         refresh: z.enum(['auto', 'always', 'never']).optional().default('auto').describe(
           'Code Memory refresh policy. auto refreshes only when missing or stale.',
         ),
-        format: z.enum(['prompt', 'summary', 'json']).optional().default('prompt').describe(
-          'Output format. "prompt" is agent-ready; "summary" is human-readable; "json" is structured.',
+        format: z.enum(['prompt', 'summary', 'json', 'receipt']).optional().default('prompt').describe(
+          'Output format. "prompt" is agent-ready; "summary" is human-readable; "receipt" is bounded JSON; "json" is detailed diagnostics.',
         ),
+        agent: z.enum([
+          'windsurf', 'cursor', 'claude-code', 'codex', 'copilot', 'antigravity', 'gemini-cli',
+          'openclaw', 'hermes', 'omp', 'kiro', 'opencode', 'trae',
+        ]).optional().describe('Optional target agent for compatible workflow selection.'),
         limit: z.number().optional().describe('Reserved for future source limits; current prompt stays compact by default.'),
       },
     },
-    async ({ task, refresh, format }) => {
+    async ({ task, refresh, format, agent }) => {
       const unresolved = requireResolvedProject('build project context for the current project');
       if (unresolved) return unresolved;
 
@@ -1595,11 +1603,13 @@ export async function createMemorixServer(
         { getObservationStore },
         { MaintenanceJobStore },
         { enqueueCodegraphRefresh },
+        { buildBoundedContextReceipt },
       ] = await Promise.all([
         import('./codegraph/auto-context.js'),
         import('./store/obs-store.js'),
         import('./runtime/maintenance-jobs.js'),
         import('./runtime/lifecycle.js'),
+        import('./knowledge/context-receipt.js'),
       ]);
       const observations = filterReadableObservations(
         await getObservationStore().loadByProject(project.id, { status: 'active' }),
@@ -1610,6 +1620,7 @@ export async function createMemorixServer(
         dataDir: projectDir,
         observations,
         task,
+        agent,
         refresh: refresh ?? 'auto',
         reader: getObservationReader(),
         enqueueRefresh: () => {
@@ -1624,6 +1635,11 @@ export async function createMemorixServer(
       });
       const text = format === 'json'
         ? JSON.stringify({ ...context, brief: buildAutoProjectBrief(context) }, null, 2)
+        : format === 'receipt'
+          ? JSON.stringify(buildBoundedContextReceipt({
+            workset: context.workset,
+            providerQuality: context.providerQuality,
+          }), null, 2)
         : format === 'summary'
           ? formatAutoProjectContextSummary(context)
           : formatAutoProjectContextPrompt(context);

package/src/store/orama-store.ts

@@ -23,7 +23,7 @@ import {
 import { calculateProjectAffinity, extractProjectKeywords, type AffinityContext, type MemoryContent } from './project-affinity.js';
 import { detectQueryIntent, applyIntentBoost } from '../search/intent-detector.js';
 import { maybeExpandSearchQuery } from '../search/query-expansion.js';
-import { withTimeout } from '../timeout.js';
+import { withTimeout, withTimeoutSignal } from '../timeout.js';
 
 let db: AnyOrama | null = null;
 let dbInitPromise: Promise<AnyOrama> | null = null;
@@ -642,18 +642,20 @@ export async function searchObservations(options: SearchOptions): Promise<IndexE
         } else {
           // Embedding timeout: 15 seconds
           const EMBEDDING_TIMEOUT_MS = 15000;
-          queryVector = await withTimeout(
-            provider.embedInput
+          queryVector = await withTimeoutSignal(
+            (signal) => provider.embedInput
               ? provider.embedInput(
                 { modality: 'text', text: expandedEmbeddingQuery! },
-                { intent: 'query', timeoutMs: EMBEDDING_TIMEOUT_MS, retry: false },
+                { intent: 'query', timeoutMs: EMBEDDING_TIMEOUT_MS, retry: false, signal },
               )
               : provider.embed(expandedEmbeddingQuery!, {
                 timeoutMs: EMBEDDING_TIMEOUT_MS,
                 retry: false,
+                signal,
               }),
             EMBEDDING_TIMEOUT_MS,
             'Embedding',
+            options.signal,
           );
           mark('embedding');
           // Detect CJK-heavy queries: BM25 can't tokenize Chinese/Japanese/Korean well

package/src/timeout.ts

@@ -21,3 +21,70 @@ export function withTimeout<T>(promise: Promise<T>, ms: number, label: string):
     );
   });
 }
+
+/**
+ * Run an operation with a deadline and an AbortSignal for cancellable work.
+ * Callers should pass the signal to fetch/embedding/LLM APIs they own.
+ */
+export function withTimeoutSignal<T>(
+  operation: (signal: AbortSignal) => Promise<T>,
+  ms: number,
+  label: string,
+  parentSignal?: AbortSignal,
+): Promise<T> {
+  const controller = new AbortController();
+  const signal = parentSignal
+    ? AbortSignal.any([parentSignal, controller.signal])
+    : controller.signal;
+
+  return new Promise<T>((resolve, reject) => {
+    let settled = false;
+    let timedOut = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const cleanup = () => {
+      if (timer !== undefined) 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: Promise<T>;
+    try {
+      pending = operation(signal);
+    } catch (error) {
+      settled = true;
+      cleanup();
+      reject(error);
+      return;
+    }
+
+    pending.then(
+      (value) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        resolve(value);
+      },
+      (error: unknown) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(timedOut ? new Error(`${label} timed out after ${ms}ms`) : error);
+      },
+    );
+  });
+}

package/src/types.ts

@@ -328,6 +328,8 @@ export 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 */