@vellumai/assistant 0.10.3 → 0.10.4-dev.202607010028.1a4efcc

package/src/plugins/defaults/memory/context-search/agent-runner.ts

@@ -0,0 +1,1311 @@
+import type {
+  Message,
+  Provider,
+  ProviderResponse,
+  ToolUseContent,
+} from "@vellumai/plugin-api";
+
+import { getConfiguredProvider } from "../../../../providers/provider-send-message.js";
+import { redactSecrets } from "../../../../security/secret-scanner.js";
+import {
+  buildRecallAgentPromptBundle,
+  FINISH_RECALL_TOOL_DEFINITION,
+  RECALL_AGENT_TOOL_DEFINITIONS,
+  type RecallAgentFinish,
+  validateFinishRecallPayload,
+} from "./agent-protocol.js";
+import {
+  formatDeterministicRecallAnswer,
+  formatRecallFooter,
+} from "./format.js";
+import {
+  isRecallSource,
+  type NormalizedRecallInput,
+  normalizeRecallInput,
+  normalizeRecallMaxResults,
+  normalizeRecallSources,
+} from "./limits.js";
+import {
+  type DeterministicRecallSearchOptions,
+  type DeterministicRecallSearchResult,
+  runDeterministicRecallSearch,
+} from "./search.js";
+import {
+  extractWorkspacePathLiterals,
+  inspectWorkspacePaths,
+  isSafeWorkspaceRelativePath,
+  normalizeWorkspacePathLiteral,
+} from "./sources/workspace.js";
+import type {
+  RecallAnswer,
+  RecallEvidence,
+  RecallInput,
+  RecallSearchContext,
+  RecallSource,
+} from "./types.js";
+
+type AgenticRecallFallbackReason =
+  | "no_provider"
+  | "provider_error"
+  | "timeout"
+  | "no_valid_finish"
+  | "round_limit"
+  | "citation_validation_failed"
+  | "finish_answer_validation_failed";
+
+interface AgenticRecallSearchDebug {
+  round: number;
+  query: string;
+  sources: RecallSource[];
+  limit: number;
+  reason: string;
+  evidenceCount: number;
+  error?: string;
+}
+
+interface AgenticRecallInspectDebug {
+  round: number;
+  paths: string[];
+  reason: string;
+  evidenceCount: number;
+  errors?: Array<{ path: string; reason: string }>;
+}
+
+interface AgenticRecallDebug {
+  mode: "agentic" | "deterministic_fallback";
+  normalizedInput: NormalizedRecallInput;
+  roundLimit: number;
+  roundsUsed: number;
+  seedEvidenceCount: number;
+  searchCalls: AgenticRecallSearchDebug[];
+  inspectCalls: AgenticRecallInspectDebug[];
+  finish?: {
+    confidence: string;
+    citationIds: string[];
+    unresolved?: string[];
+  };
+  fallbackReason?: AgenticRecallFallbackReason;
+  fallbackDetail?: string;
+}
+
+interface AgenticRecallAnswer extends RecallAnswer {
+  content: string;
+  debug: AgenticRecallDebug;
+}
+
+interface RunAgenticRecallOptions {
+  searchOptions?: DeterministicRecallSearchOptions;
+}
+
+const REFERENT_QUERY_PATTERN =
+  /\b(asked about|referred to|talking about|mentioned|meant by|referent)\b/i;
+const DETAIL_QUERY_PATTERN =
+  /\b(details?|specifics?|flavor|decoration|design|message|inscription|recipient|timing|plan)\b/i;
+const QUESTION_QUERY_PATTERN = /\b(where|what|why|how)\b/i;
+const LOCATION_QUERY_PATTERN =
+  /\b(where|live|lives|lived|living|residence|home|address|location|located)\b/i;
+const LEAD_IN_QUERY_PATTERN =
+  /\b(led to|lead to|leads to|what led|why|how did|chain|context|cause|reason)\b/i;
+
+const LOW_CONFIDENCE_AVAILABLE_EVIDENCE_MAX_ITEMS = 5;
+const AVAILABLE_EVIDENCE_EXCERPT_MAX_CHARS = 220;
+
+const DETAIL_EXPANSION_TERMS = [
+  "paid",
+  "delivery",
+  "design",
+  "inscription",
+  "flavor",
+  "message",
+];
+
+const DETAIL_FIELD_TERMS = new Set([
+  "decoration",
+  "design",
+  "details",
+  "detail",
+  "flavor",
+  "inscription",
+  "message",
+  "recipient",
+  "specifics",
+  "timing",
+  "plan",
+]);
+
+const LOCATION_FIELD_TERMS = new Set([
+  "address",
+  "home",
+  "live",
+  "lived",
+  "lives",
+  "living",
+  "located",
+  "location",
+  "residence",
+  "where",
+]);
+
+const LEAD_IN_FIELD_TERMS = new Set([
+  "cause",
+  "chain",
+  "context",
+  "did",
+  "how",
+  "lead",
+  "leads",
+  "led",
+  "reason",
+  "to",
+  "what",
+  "why",
+]);
+
+const NON_SALIENT_REFERENT_TERMS = new Set([
+  "a",
+  "about",
+  "and",
+  "any",
+  "asked",
+  "by",
+  "did",
+  "does",
+  "find",
+  "for",
+  "from",
+  "is",
+  "it",
+  "me",
+  "mean",
+  "meant",
+  "mention",
+  "mentioned",
+  "of",
+  "on",
+  "or",
+  "referent",
+  "referred",
+  "that",
+  "the",
+  "to",
+  "was",
+  "were",
+  "what",
+  "when",
+  "where",
+  "which",
+  "who",
+  "with",
+]);
+
+const FINISH_NEGATIVE_PATTERNS = [
+  /\bavailable evidence does not contain\b/i,
+  /\bavailable evidence doesn't contain\b/i,
+  /\bevidence does not contain\b/i,
+  /\bevidence doesn't contain\b/i,
+  /\bdoes not contain information\b/i,
+  /\bdoesn't contain information\b/i,
+  /\bno (?:reliable |available |relevant )?(?:evidence|information|results|answer)\b/i,
+  /\bnot enough evidence\b/i,
+  /\binsufficient evidence\b/i,
+  /\bunable to (?:answer|determine|find|provide)\b/i,
+  /\bcannot (?:answer|determine|find|provide)\b/i,
+  /\bcan't (?:answer|determine|find|provide)\b/i,
+  /\bonly the locator path\b/i,
+  /\bno text\b/i,
+];
+
+export async function runAgenticRecall(
+  input: RecallInput,
+  context: RecallSearchContext,
+  options: RunAgenticRecallOptions = {},
+): Promise<AgenticRecallAnswer> {
+  const normalizedInput = normalizeRecallInput(input);
+  const roundLimit = normalizedInput.sourceRounds;
+  const debug: AgenticRecallDebug = {
+    mode: "agentic",
+    normalizedInput,
+    roundLimit,
+    roundsUsed: 0,
+    seedEvidenceCount: 0,
+    searchCalls: [],
+    inspectCalls: [],
+  };
+
+  const provider = await getConfiguredProvider("recall");
+  if (!provider) {
+    const fallbackResult = await runSeedRecallSearch(
+      normalizedInput,
+      context,
+      options.searchOptions,
+    );
+    const autoInspect = await runAutomaticWorkspaceInspection(
+      normalizedInput,
+      context,
+      fallbackResult.evidence,
+    );
+    if (autoInspect.debug) {
+      debug.inspectCalls.push(autoInspect.debug);
+    }
+    const fallbackEvidence = mergeEvidence(
+      fallbackResult.evidence,
+      autoInspect.evidence,
+    );
+    debug.seedEvidenceCount = fallbackEvidence.length;
+    return deterministicFallback(
+      withFallbackEvidence(fallbackResult, fallbackEvidence),
+      debug,
+      "no_provider",
+      "No recall provider is configured.",
+    );
+  }
+
+  const seedResult = await runSeedRecallSearch(
+    normalizedInput,
+    context,
+    options.searchOptions,
+  );
+  let evidence = [...seedResult.evidence];
+  const autoInspect = await runAutomaticWorkspaceInspection(
+    normalizedInput,
+    context,
+    evidence,
+  );
+  if (autoInspect.debug) {
+    debug.inspectCalls.push(autoInspect.debug);
+    evidence = mergeEvidence(evidence, autoInspect.evidence);
+  }
+  debug.seedEvidenceCount = evidence.length;
+  let fallbackReason: AgenticRecallFallbackReason = "no_valid_finish";
+  let fallbackDetail = "Recall provider did not return a valid finish_recall.";
+
+  for (let round = 1; round <= roundLimit; round++) {
+    debug.roundsUsed = round;
+    const promptBundle = buildPromptBundle(
+      normalizedInput,
+      evidence,
+      roundLimit,
+    );
+
+    let response: ProviderResponse;
+    try {
+      response = await provider.sendMessage(
+        [userTextMessage(promptBundle.prompt)],
+        {
+          tools: [...RECALL_AGENT_TOOL_DEFINITIONS],
+          // `thinking: disabled` is required because we set `temperature: 0`
+          // explicitly. Anthropic 400s on `temperature` ≠ 1 whenever thinking
+          // is enabled or in adaptive mode; without this, profiles that
+          // resolve thinking-enabled (Opus 4.x at `effort: high|xhigh`, etc.)
+          // would fail. Recall is tool-call-heavy reasoning where determinism
+          // matters more than extended chain-of-thought.
+          config: {
+            callSite: "recall",
+            temperature: 0,
+            thinking: { type: "disabled" },
+          },
+          signal: context.signal,
+        },
+      );
+    } catch (err) {
+      fallbackReason = isAbortError(err) ? "timeout" : "provider_error";
+      fallbackDetail = errorToMessage(err);
+      break;
+    }
+
+    const toolUses = extractToolUses(response);
+    const finishTool = toolUses.find((tool) => tool.name === "finish_recall");
+    if (finishTool) {
+      const finishResult = finishRecallFromToolUse(
+        finishTool,
+        promptBundle.evidence,
+        evidence,
+        debug,
+        normalizedInput,
+        withFallbackEvidence(seedResult, evidence),
+      );
+      if (finishResult.ok) {
+        return finishResult.answer;
+      }
+
+      if (!finishResult.ok) {
+        fallbackReason = finishResult.reason;
+        fallbackDetail = finishResult.detail;
+        break;
+      }
+    }
+
+    const inspectTools = toolUses.filter(
+      (tool) => tool.name === "inspect_workspace_paths",
+    );
+    const searchTools = toolUses.filter(
+      (tool) => tool.name === "search_sources",
+    );
+    if (inspectTools.length === 0 && searchTools.length === 0) {
+      fallbackReason = "no_valid_finish";
+      fallbackDetail =
+        "Recall provider returned no search_sources, inspect_workspace_paths, or finish_recall tool call.";
+      break;
+    }
+
+    for (const inspectTool of inspectTools) {
+      const inspectResult = await executeInspectWorkspacePaths(
+        inspectTool.input,
+        normalizedInput,
+        context,
+        evidence,
+        round,
+      );
+      debug.inspectCalls.push(inspectResult.debug);
+      evidence = mergeEvidence(evidence, inspectResult.evidence);
+    }
+
+    if (searchTools.length > 0) {
+      const remainingSearchBudget = roundLimit - debug.searchCalls.length;
+      if (remainingSearchBudget <= 0) {
+        fallbackReason = "round_limit";
+        fallbackDetail =
+          "Recall provider exhausted the configured search budget.";
+        break;
+      }
+
+      for (const searchTool of searchTools.slice(0, remainingSearchBudget)) {
+        const searchResult = await executeSearchSources(
+          searchTool.input,
+          normalizedInput,
+          context,
+          round,
+          options.searchOptions,
+        );
+        debug.searchCalls.push(searchResult.debug);
+        evidence = mergeEvidence(evidence, searchResult.evidence);
+      }
+    }
+
+    if (round === roundLimit) {
+      fallbackReason = "round_limit";
+      fallbackDetail = "Recall provider exhausted the configured round budget.";
+    }
+  }
+
+  if (fallbackReason === "round_limit") {
+    const finalFinish = await tryFinalFinishRecall({
+      provider,
+      normalizedInput,
+      evidence,
+      debug,
+      context,
+      searchResult: withFallbackEvidence(seedResult, evidence),
+    });
+    if (finalFinish.ok) {
+      return finalFinish.answer;
+    }
+    fallbackReason = finalFinish.reason;
+    fallbackDetail = finalFinish.detail;
+  }
+
+  return deterministicFallback(
+    withFallbackEvidence(seedResult, evidence),
+    debug,
+    fallbackReason,
+    fallbackDetail,
+  );
+}
+
+/**
+ * Redact secrets from workspace-sourced evidence excerpts before they are
+ * serialised into a prompt that will be sent to an external LLM provider.
+ *
+ * Memory and conversation evidence is already controlled content —
+ * only workspace files can contain arbitrary secrets (API keys, tokens, etc.)
+ * written by the user or by tools. This runs the same pattern-based scanner
+ * used for shell command summaries and approval prompts, replacing any
+ * detected secrets with `<redacted type="…" />` markers.
+ *
+ * The original evidence array is not mutated; citations and local fallback
+ * paths continue to reference unredacted values.
+ */
+export function redactWorkspaceEvidence(
+  evidence: readonly RecallEvidence[],
+): readonly RecallEvidence[] {
+  return evidence.map((item) => {
+    if (item.source !== "workspace") return item;
+    const redacted = redactSecrets(item.excerpt);
+    if (redacted === item.excerpt) return item;
+    return { ...item, excerpt: redacted };
+  });
+}
+
+function buildPromptBundle(
+  input: NormalizedRecallInput,
+  evidence: readonly RecallEvidence[],
+  roundLimit: number,
+): ReturnType<typeof buildRecallAgentPromptBundle> {
+  return buildRecallAgentPromptBundle({
+    query: input.query,
+    availableSources: input.sources,
+    evidence: redactWorkspaceEvidence(evidence),
+    maxSearchCalls: roundLimit,
+  });
+}
+
+function userTextMessage(text: string): Message {
+  return { role: "user", content: [{ type: "text", text }] };
+}
+
+function extractToolUses(response: ProviderResponse): ToolUseContent[] {
+  return response.content.filter(
+    (block): block is ToolUseContent => block.type === "tool_use",
+  );
+}
+
+async function runSeedRecallSearch(
+  input: NormalizedRecallInput,
+  context: RecallSearchContext,
+  searchOptions: DeterministicRecallSearchOptions | undefined,
+): Promise<DeterministicRecallSearchResult> {
+  const baseResult = await runDeterministicRecallSearch(
+    toRecallInput(input),
+    context,
+    searchOptions,
+  );
+  const expansionQueries = buildReferentExpansionQueries(input.query);
+  if (expansionQueries.length === 0) {
+    return baseResult;
+  }
+
+  let evidence = [...baseResult.evidence];
+  for (const query of expansionQueries) {
+    const expansionResult = await runDeterministicRecallSearch(
+      {
+        ...toRecallInput(input),
+        query,
+        depth: "fast",
+        max_results: Math.min(input.maxResults, 8),
+      },
+      context,
+      searchOptions,
+    );
+    evidence = mergeEvidence(evidence, expansionResult.evidence);
+  }
+
+  return withFallbackEvidence(baseResult, evidence);
+}
+
+function buildReferentExpansionQueries(query: string): string[] {
+  const shouldExpandReferent = REFERENT_QUERY_PATTERN.test(query);
+  const shouldExpandDetails = DETAIL_QUERY_PATTERN.test(query);
+  const shouldExpandQuestion = QUESTION_QUERY_PATTERN.test(query);
+  const shouldExpandLocation = LOCATION_QUERY_PATTERN.test(query);
+  const shouldExpandLeadIn = LEAD_IN_QUERY_PATTERN.test(query);
+  const terms = tokenizeReferentTerms(query);
+  if (
+    terms.length === 0 ||
+    (!shouldExpandReferent && !shouldExpandDetails && !shouldExpandQuestion)
+  ) {
+    return [];
+  }
+
+  const queries: string[] = [];
+  const objectTerms = terms.filter((term) => !DETAIL_FIELD_TERMS.has(term));
+  const searchTerms = objectTerms.length > 0 ? objectTerms : terms;
+  const firstTerm = searchTerms[0];
+  const lastTerm = searchTerms[searchTerms.length - 1];
+
+  if (shouldExpandReferent && firstTerm) {
+    queries.push(firstTerm);
+  }
+
+  if (shouldExpandReferent && searchTerms.length > 1) {
+    queries.push(searchTerms.slice(0, 2).join(" "));
+  }
+
+  if ((shouldExpandReferent || shouldExpandDetails) && firstTerm) {
+    queries.push(`${firstTerm} ${DETAIL_EXPANSION_TERMS.join(" ")}`);
+  }
+
+  if (
+    shouldExpandDetails &&
+    lastTerm &&
+    lastTerm !== firstTerm &&
+    !DETAIL_FIELD_TERMS.has(lastTerm)
+  ) {
+    queries.push(`${lastTerm} ${DETAIL_EXPANSION_TERMS.join(" ")}`);
+  }
+
+  if (shouldExpandQuestion && !shouldExpandLocation && terms.length > 1) {
+    queries.push(terms.join(" "));
+  }
+
+  if (shouldExpandLocation && firstTerm) {
+    const entityTerms = terms.filter((term) => !LOCATION_FIELD_TERMS.has(term));
+    const entity = entityTerms[0] ?? firstTerm;
+    queries.push(`${entity} home address location`);
+    queries.push(`${entity} lives residence`);
+  }
+
+  if (shouldExpandLeadIn && terms.length > 1) {
+    const leadTerms = terms.filter((term) => !LEAD_IN_FIELD_TERMS.has(term));
+    const focusedTerms = leadTerms.length > 0 ? leadTerms : terms;
+    queries.push(focusedTerms.join(" "));
+    if (focusedTerms.length > 1) {
+      queries.push(`${focusedTerms.join(" ")} context reason before chain`);
+    }
+  }
+
+  return [...new Set(queries)].filter((candidate) => candidate !== query);
+}
+
+function tokenizeReferentTerms(query: string): string[] {
+  const tokens = query.toLowerCase().match(/[a-z0-9_]+/g) ?? [];
+  return [...new Set(tokens)].filter(
+    (term) =>
+      term.length >= 2 &&
+      !NON_SALIENT_REFERENT_TERMS.has(term) &&
+      !term.endsWith("'s"),
+  );
+}
+
+async function tryFinalFinishRecall(options: {
+  provider: Provider;
+  normalizedInput: NormalizedRecallInput;
+  evidence: readonly RecallEvidence[];
+  debug: AgenticRecallDebug;
+  context: RecallSearchContext;
+  searchResult: DeterministicRecallSearchResult;
+}): Promise<
+  | { ok: true; answer: AgenticRecallAnswer }
+  | {
+      ok: false;
+      reason: AgenticRecallFallbackReason;
+      detail: string;
+    }
+> {
+  const promptBundle = buildPromptBundle(
+    options.normalizedInput,
+    options.evidence,
+    0,
+  );
+
+  let response: ProviderResponse;
+  try {
+    response = await options.provider.sendMessage(
+      [userTextMessage(promptBundle.prompt)],
+      {
+        tools: [FINISH_RECALL_TOOL_DEFINITION],
+        // `thinking: disabled` required for the same reason as the agent
+        // round above — Anthropic 400s on `temperature` ≠ 1 whenever
+        // thinking is enabled or in adaptive mode.
+        config: {
+          callSite: "recall",
+          temperature: 0,
+          thinking: { type: "disabled" },
+        },
+        signal: options.context.signal,
+      },
+    );
+  } catch (err) {
+    return {
+      ok: false,
+      reason: isAbortError(err) ? "timeout" : "provider_error",
+      detail: errorToMessage(err),
+    };
+  }
+
+  const finishTool = extractToolUses(response).find(
+    (tool) => tool.name === "finish_recall",
+  );
+  if (!finishTool) {
+    return {
+      ok: false,
+      reason: "no_valid_finish",
+      detail:
+        "Recall provider exhausted the search budget and did not return a final finish_recall.",
+    };
+  }
+
+  const finishResult = finishRecallFromToolUse(
+    finishTool,
+    promptBundle.evidence,
+    options.evidence,
+    options.debug,
+    options.normalizedInput,
+    options.searchResult,
+  );
+  if (finishResult.ok) {
+    return finishResult;
+  }
+
+  return {
+    ok: false,
+    reason: finishResult.reason,
+    detail: finishResult.detail,
+  };
+}
+
+function finishRecallFromToolUse(
+  finishTool: ToolUseContent,
+  promptEvidence: readonly RecallEvidence[],
+  allEvidence: readonly RecallEvidence[],
+  debug: AgenticRecallDebug,
+  input: NormalizedRecallInput,
+  searchResult: DeterministicRecallSearchResult,
+):
+  | { ok: true; answer: AgenticRecallAnswer }
+  | { ok: false; reason: AgenticRecallFallbackReason; detail: string } {
+  const validation = validateFinishRecallPayload(
+    finishTool.input,
+    promptEvidence,
+  );
+  if (!validation.ok) {
+    return {
+      ok: false,
+      reason: "citation_validation_failed",
+      detail: validation.reason,
+    };
+  }
+
+  const finish = validation.finish;
+  const answerValidation = validateFinishAnswerAgainstEvidence(
+    input.query,
+    finish,
+    allEvidence,
+  );
+  if (!answerValidation.ok) {
+    return {
+      ok: false,
+      reason: "finish_answer_validation_failed",
+      detail: answerValidation.reason,
+    };
+  }
+
+  const citedEvidence = selectCitedEvidence(promptEvidence, finish.citationIds);
+  if (citedEvidence.length === 0) {
+    return {
+      ok: false,
+      reason: "citation_validation_failed",
+      detail: "finish_recall returned no resolvable citations",
+    };
+  }
+  debug.finish = {
+    confidence: finish.confidence,
+    citationIds: finish.citationIds,
+    ...(finish.unresolved ? { unresolved: finish.unresolved } : {}),
+  };
+  const content = formatAgenticRecallContent({
+    answer: finish.answer,
+    availableEvidence: shouldAppendAvailableEvidence(finish)
+      ? selectAvailableEvidence(input.query, allEvidence, citedEvidence)
+      : [],
+    footer: formatRecallFooter({
+      searchedSources: searchResult.searchedSources,
+      inspectCalls: debug.inspectCalls,
+    }),
+  });
+
+  return {
+    ok: true,
+    answer: {
+      content,
+      answer: content,
+      evidence: citedEvidence,
+      debug,
+    },
+  };
+}
+
+function validateFinishAnswerAgainstEvidence(
+  query: string,
+  finish: RecallAgentFinish,
+  evidence: readonly RecallEvidence[],
+): { ok: true } | { ok: false; reason: string } {
+  if (!isNegativeOrIncompleteFinish(finish)) {
+    return { ok: true };
+  }
+
+  const relevantEvidence = selectRelevantEvidence(query, evidence);
+  if (relevantEvidence.length === 0) {
+    return { ok: true };
+  }
+
+  return {
+    ok: false,
+    reason: "negative_or_incomplete_finish_with_relevant_evidence",
+  };
+}
+
+function isNegativeOrIncompleteFinish(finish: RecallAgentFinish): boolean {
+  const finishText = [finish.answer, ...(finish.unresolved ?? [])].join("\n");
+  return FINISH_NEGATIVE_PATTERNS.some((pattern) => pattern.test(finishText));
+}
+
+function shouldAppendAvailableEvidence(finish: RecallAgentFinish): boolean {
+  return finish.confidence === "low" || (finish.unresolved?.length ?? 0) > 0;
+}
+
+function selectAvailableEvidence(
+  query: string,
+  evidence: readonly RecallEvidence[],
+  citedEvidence: readonly RecallEvidence[],
+): RecallEvidence[] {
+  return dedupeEvidenceById([
+    ...citedEvidence,
+    ...selectRelevantEvidence(query, evidence),
+    ...evidence.filter(isUsableEvidence),
+  ]).slice(0, LOW_CONFIDENCE_AVAILABLE_EVIDENCE_MAX_ITEMS);
+}
+
+function selectRelevantEvidence(
+  query: string,
+  evidence: readonly RecallEvidence[],
+): RecallEvidence[] {
+  const queryTerms = tokenizeValidationTerms(query);
+  if (queryTerms.size === 0) {
+    return [];
+  }
+
+  return evidence.filter(
+    (item) =>
+      isUsableEvidence(item) &&
+      hasTermOverlap(queryTerms, tokenizeValidationTerms(evidenceText(item))),
+  );
+}
+
+function isUsableEvidence(item: RecallEvidence): boolean {
+  return item.excerpt.trim().length > 0 && item.metadata?.inspectError !== true;
+}
+
+function evidenceText(item: RecallEvidence): string {
+  const metadataPath = item.metadata?.path;
+  return [
+    item.title,
+    item.locator,
+    item.excerpt,
+    typeof metadataPath === "string" ? metadataPath : "",
+  ].join("\n");
+}
+
+function hasTermOverlap(
+  queryTerms: ReadonlySet<string>,
+  evidenceTerms: ReadonlySet<string>,
+): boolean {
+  for (const term of queryTerms) {
+    if (evidenceTerms.has(term)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function tokenizeValidationTerms(text: string): Set<string> {
+  const terms = new Set<string>();
+  for (const token of text.toLowerCase().match(/[a-z0-9_]+/g) ?? []) {
+    if (token.length < 2 || NON_SALIENT_REFERENT_TERMS.has(token)) {
+      continue;
+    }
+    terms.add(token);
+    terms.add(stemValidationTerm(token));
+  }
+  return terms;
+}
+
+function stemValidationTerm(term: string): string {
+  if (term.length > 4 && term.endsWith("ies")) {
+    return `${term.slice(0, -3)}y`;
+  }
+  if (term.length > 3 && term.endsWith("s") && !term.endsWith("ss")) {
+    return term.slice(0, -1);
+  }
+  return term;
+}
+
+function formatAgenticRecallContent(options: {
+  answer: string;
+  availableEvidence: readonly RecallEvidence[];
+  footer: string;
+}): string {
+  return [
+    options.answer.trim(),
+    formatAvailableEvidence(options.availableEvidence),
+    options.footer,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function formatAvailableEvidence(evidence: readonly RecallEvidence[]): string {
+  if (evidence.length === 0) {
+    return "";
+  }
+
+  return [
+    "Available evidence:",
+    ...evidence.map((item, index) => {
+      const excerpt = compactText(
+        item.excerpt,
+        AVAILABLE_EVIDENCE_EXCERPT_MAX_CHARS,
+      );
+      return `${index + 1}. [${item.source}] ${item.title} (${item.locator}): ${excerpt}`;
+    }),
+  ].join("\n");
+}
+
+function compactText(text: string, maxChars: number): string {
+  const compacted = text.trim().replace(/\s+/g, " ");
+  if (compacted.length <= maxChars) {
+    return compacted;
+  }
+  if (maxChars <= 3) {
+    return compacted.slice(0, maxChars);
+  }
+  return `${compacted.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+function dedupeEvidenceById(
+  evidence: readonly RecallEvidence[],
+): RecallEvidence[] {
+  const seen = new Set<string>();
+  const deduped: RecallEvidence[] = [];
+
+  for (const item of evidence) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+    seen.add(item.id);
+    deduped.push(item);
+  }
+
+  return deduped;
+}
+
+async function executeSearchSources(
+  payload: Record<string, unknown>,
+  input: NormalizedRecallInput,
+  context: RecallSearchContext,
+  round: number,
+  searchOptions: DeterministicRecallSearchOptions | undefined,
+): Promise<{
+  evidence: RecallEvidence[];
+  debug: AgenticRecallSearchDebug;
+}> {
+  const query = readSearchQuery(payload.query);
+  const reason = readSearchReason(payload.reason);
+  const rawLimit = readSearchLimit(payload.limit);
+  const limit =
+    rawLimit === undefined
+      ? input.maxResults
+      : normalizeRecallMaxResults(rawLimit);
+  const sources = narrowSearchSources(payload.sources, input.sources);
+
+  const debug: AgenticRecallSearchDebug = {
+    round,
+    query,
+    sources,
+    limit,
+    reason,
+    evidenceCount: 0,
+  };
+
+  if (!query || sources.length === 0) {
+    return {
+      evidence: [],
+      debug: {
+        ...debug,
+        error: !query
+          ? "search_sources query must be a non-empty string"
+          : "search_sources requested no allowed local sources",
+      },
+    };
+  }
+
+  try {
+    const result = await runDeterministicRecallSearch(
+      {
+        query,
+        sources,
+        max_results: limit,
+        depth: "fast",
+      },
+      context,
+      searchOptions,
+    );
+    return {
+      evidence: result.evidence,
+      debug: { ...debug, evidenceCount: result.evidence.length },
+    };
+  } catch (err) {
+    return {
+      evidence: [],
+      debug: { ...debug, error: errorToMessage(err) },
+    };
+  }
+}
+
+async function executeInspectWorkspacePaths(
+  payload: Record<string, unknown>,
+  input: NormalizedRecallInput,
+  context: RecallSearchContext,
+  evidence: readonly RecallEvidence[],
+  round: number,
+): Promise<{
+  evidence: RecallEvidence[];
+  debug: AgenticRecallInspectDebug;
+}> {
+  const reason = readSearchReason(payload.reason);
+  const requestedPaths = readInspectPaths(payload.paths);
+  const workspaceSourceEnabled = input.sources.includes("workspace");
+  const allowedPaths = workspaceSourceEnabled
+    ? collectInspectableWorkspacePaths(input.query, evidence)
+    : new Set<string>();
+  const acceptedPaths: string[] = [];
+  const rejectedPaths: string[] = [];
+  for (const requestedPath of requestedPaths) {
+    const acceptedPath = workspaceSourceEnabled
+      ? normalizeRequestedWorkspaceInspectionPath(requestedPath, allowedPaths)
+      : null;
+    if (acceptedPath) {
+      acceptedPaths.push(acceptedPath);
+    } else {
+      rejectedPaths.push(requestedPath);
+    }
+  }
+
+  const debug: AgenticRecallInspectDebug = {
+    round,
+    paths: requestedPaths,
+    reason,
+    evidenceCount: 0,
+  };
+
+  if (requestedPaths.length === 0) {
+    return {
+      evidence: [
+        makeWorkspaceInspectionErrorEvidence({
+          round,
+          index: 0,
+          path: "inspect_workspace_paths",
+          reason: "inspect_workspace_paths paths must be non-empty strings",
+        }),
+      ],
+      debug: {
+        ...debug,
+        evidenceCount: 1,
+        errors: [
+          {
+            path: "inspect_workspace_paths",
+            reason: "paths must be non-empty strings",
+          },
+        ],
+      },
+    };
+  }
+
+  const errors = rejectedPaths.map((path) => ({
+    path,
+    reason: workspaceSourceEnabled
+      ? "path was not a safe relative workspace file surfaced by the query or prior evidence"
+      : "workspace source is disabled for this recall request",
+  }));
+
+  let inspectionEvidence: RecallEvidence[] = [];
+  if (acceptedPaths.length > 0) {
+    const inspectionResult = await inspectWorkspacePaths(
+      acceptedPaths,
+      input.query,
+      context,
+    );
+    inspectionEvidence = inspectionResult.evidence;
+    errors.push(...inspectionResult.errors);
+  }
+
+  const errorEvidence = errors.map((error, index) =>
+    makeWorkspaceInspectionErrorEvidence({
+      round,
+      index,
+      path: error.path,
+      reason: error.reason,
+    }),
+  );
+  const allEvidence = [...inspectionEvidence, ...errorEvidence];
+
+  return {
+    evidence: allEvidence,
+    debug: {
+      ...debug,
+      evidenceCount: allEvidence.length,
+      ...(errors.length > 0 ? { errors } : {}),
+    },
+  };
+}
+
+async function runAutomaticWorkspaceInspection(
+  input: NormalizedRecallInput,
+  context: RecallSearchContext,
+  evidence: readonly RecallEvidence[],
+): Promise<{
+  evidence: RecallEvidence[];
+  debug?: AgenticRecallInspectDebug;
+}> {
+  if (!input.sources.includes("workspace")) {
+    return { evidence: [] };
+  }
+
+  const paths = collectAutomaticWorkspaceInspectionPaths(input.query, evidence);
+  if (paths.length === 0) {
+    return { evidence: [] };
+  }
+
+  const inspectionResult = await inspectWorkspacePaths(
+    paths,
+    input.query,
+    context,
+  );
+  const debug: AgenticRecallInspectDebug = {
+    round: 0,
+    paths,
+    reason:
+      "Automatically inspect exact workspace paths surfaced by seed evidence.",
+    evidenceCount: inspectionResult.evidence.length,
+    ...(inspectionResult.errors.length > 0
+      ? { errors: inspectionResult.errors }
+      : {}),
+  };
+  return { evidence: inspectionResult.evidence, debug };
+}
+
+function readSearchQuery(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readSearchReason(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+function readSearchLimit(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  return value;
+}
+
+function readInspectPaths(value: unknown): string[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [
+    ...new Set(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0),
+    ),
+  ].slice(0, 5);
+}
+
+function collectAutomaticWorkspaceInspectionPaths(
+  query: string,
+  evidence: readonly RecallEvidence[],
+): string[] {
+  const paths = new Set(extractWorkspacePathLiterals(query));
+  for (const item of evidence) {
+    collectEvidenceWorkspacePaths(item).forEach((path) => paths.add(path));
+  }
+  return [...paths].slice(0, 3);
+}
+
+function collectInspectableWorkspacePaths(
+  query: string,
+  evidence: readonly RecallEvidence[],
+): Set<string> {
+  const paths = new Set(extractWorkspacePathLiterals(query));
+  for (const item of evidence) {
+    collectEvidenceWorkspacePaths(item).forEach((path) => paths.add(path));
+  }
+  return paths;
+}
+
+function collectEvidenceWorkspacePaths(item: RecallEvidence): string[] {
+  const paths = new Set<string>();
+  const metadataPath = item.metadata?.path;
+  if (
+    typeof metadataPath === "string" &&
+    isSafeWorkspaceRelativePath(metadataPath)
+  ) {
+    paths.add(metadataPath);
+  }
+  for (const text of [item.locator, item.title, item.excerpt]) {
+    for (const path of extractWorkspacePathLiterals(text)) {
+      if (isSafeWorkspaceRelativePath(path)) {
+        paths.add(path);
+      }
+    }
+  }
+  return [...paths];
+}
+
+function normalizeRequestedWorkspaceInspectionPath(
+  requestedPath: string,
+  allowedPaths: ReadonlySet<string>,
+): string | null {
+  const normalized = normalizeWorkspacePathLiteral(requestedPath);
+  if (!normalized) {
+    return null;
+  }
+  return allowedPaths.has(normalized) ? normalized : null;
+}
+
+function makeWorkspaceInspectionErrorEvidence(options: {
+  round: number;
+  index: number;
+  path: string;
+  reason: string;
+}): RecallEvidence {
+  return {
+    id: `workspace:inspect-error:${options.round}:${options.index}`,
+    source: "workspace",
+    title: "Workspace path inspection",
+    locator: options.path,
+    excerpt: `Could not inspect workspace path: ${options.reason}.`,
+    score: 0,
+    metadata: {
+      retrieval: "path",
+      inspectError: true,
+      path: options.path,
+      reason: options.reason,
+    },
+  };
+}
+
+function narrowSearchSources(
+  value: unknown,
+  allowedSources: readonly RecallSource[],
+): RecallSource[] {
+  const allowed = new Set(allowedSources);
+  const requested = Array.isArray(value)
+    ? normalizeRequestedSources(value)
+    : [...allowedSources];
+
+  return requested.filter((source) => allowed.has(source));
+}
+
+function normalizeRequestedSources(value: readonly unknown[]): RecallSource[] {
+  const sources = value.filter(isRecallSource);
+  return sources.length > 0 ? normalizeRecallSources(sources) : [];
+}
+
+function mergeEvidence(
+  existing: readonly RecallEvidence[],
+  next: readonly RecallEvidence[],
+): RecallEvidence[] {
+  const seen = new Set(existing.map((item) => item.id));
+  const merged = [...existing];
+
+  for (const item of next) {
+    if (seen.has(item.id)) {
+      continue;
+    }
+    seen.add(item.id);
+    merged.push(item);
+  }
+
+  return merged;
+}
+
+function toRecallInput(input: NormalizedRecallInput): RecallInput {
+  return {
+    query: input.query,
+    sources: input.sources,
+    max_results: input.maxResults,
+    depth: input.depth,
+  };
+}
+
+function selectCitedEvidence(
+  evidence: readonly RecallEvidence[],
+  citationIds: readonly string[],
+): RecallEvidence[] {
+  const byId = new Map(evidence.map((item) => [item.id, item]));
+  return citationIds.flatMap((id) => {
+    const item = byId.get(id);
+    return item ? [item] : [];
+  });
+}
+
+function withFallbackEvidence(
+  result: DeterministicRecallSearchResult,
+  evidence: readonly RecallEvidence[],
+): DeterministicRecallSearchResult {
+  const orderedEvidence = dedupeEvidenceByContent(evidence);
+  const evidenceCountBySource = new Map<RecallSource, number>();
+  for (const item of orderedEvidence) {
+    evidenceCountBySource.set(
+      item.source,
+      (evidenceCountBySource.get(item.source) ?? 0) + 1,
+    );
+  }
+
+  return {
+    ...result,
+    evidence: orderedEvidence,
+    searchedSources: result.searchedSources.map((note) => ({
+      ...note,
+      evidenceCount: evidenceCountBySource.get(note.source) ?? 0,
+    })),
+  };
+}
+
+function dedupeEvidenceByContent(
+  evidence: readonly RecallEvidence[],
+): RecallEvidence[] {
+  const seenIds = new Set<string>();
+  const seenContent = new Set<string>();
+  const deduped: RecallEvidence[] = [];
+
+  for (const item of evidence) {
+    if (seenIds.has(item.id)) {
+      continue;
+    }
+    const contentKey = `${item.source}\0${item.locator}\0${item.excerpt}`;
+    if (seenContent.has(contentKey)) {
+      continue;
+    }
+    seenIds.add(item.id);
+    seenContent.add(contentKey);
+    deduped.push(item);
+  }
+
+  return deduped;
+}
+
+function deterministicFallback(
+  result: DeterministicRecallSearchResult,
+  debug: AgenticRecallDebug,
+  reason: AgenticRecallFallbackReason,
+  detail: string,
+): AgenticRecallAnswer {
+  const fallback = formatDeterministicRecallAnswer(result, {
+    inspectCalls: debug.inspectCalls,
+  });
+  return {
+    content: fallback.answer,
+    answer: fallback.answer,
+    evidence: fallback.evidence,
+    debug: {
+      ...debug,
+      mode: "deterministic_fallback",
+      fallbackReason: reason,
+      fallbackDetail: detail,
+    },
+  };
+}
+
+function isAbortError(err: unknown): boolean {
+  return err instanceof Error && err.name === "AbortError";
+}
+
+function errorToMessage(err: unknown): string {
+  if (err instanceof Error && err.message) {
+    return err.message;
+  }
+  return String(err);
+}