@agenr/agenr-plugin 2.0.0 → 2.1.0

package/dist/chunk-IMQIJPIP.js

@@ -0,0 +1,886 @@
+import {
+  projectClaimCentricRecallEntry,
+  runProcedureRecall
+} from "./chunk-7TDALVPY.js";
+import {
+  recall
+} from "./chunk-6T5RXGIR.js";
+
+// src/app/before-turn/service.ts
+var DEFAULT_MAX_DURABLE_ENTRIES = 1;
+var DEFAULT_MAX_HIGH_CONFIDENCE_DURABLE_ENTRIES = 2;
+var DEFAULT_MAX_RECENT_TURNS = 2;
+var DEFAULT_MAX_QUERY_CHARS = 450;
+var DEFAULT_MAX_PROCEDURE_CANDIDATES = 3;
+var DEFAULT_RECALL_THRESHOLD = 0.6;
+var DEFAULT_HIGH_CONFIDENCE_RECALL_THRESHOLD = 0.97;
+var DEFAULT_PROCEDURE_THRESHOLD = 0.72;
+var DEFAULT_SKIP_TRIVIAL_TURNS = true;
+var DEFAULT_REQUIRE_TURN_SIGNAL = true;
+var SHORT_TURN_MAX_WORDS = 4;
+var SHORT_TURN_MAX_CHARS = 24;
+var SOCIAL_TURN_RE = /^(?:hi|hello|hey|hey there|hello there|thanks|thank you|ok|okay|cool|sounds good|got it|yep|yes|no|nice|great|awesome|perfect|ping)(?:[.!?]+)?$/iu;
+var TASK_SIGNAL_RE = /\b(?:do|make|create|draft|write|send|schedule|book|reserve|organize|arrange|prepare|plan|choose|decide|contact|call|email|message|buy|order|find|search|check|compare|review|explain|summarize|investigate|research|use|apply|remember|recall|assist|help|should|need to|help me)\b/iu;
+var FACTUAL_SIGNAL_RE = /\b(?:what(?:'s|\s+is|\s+was|\s+were)?|which|where|who|when|how much|how many|what time|what day|did we|do we|previous|prior|earlier|before|last|again|decision|preference|fact|rule|policy|status|availability|location|address|phone|email|price|cost|budget|deadline|date|time|name|called|uses|used|change(?:d)?|order|reservation|appointment|account|contact)\b/iu;
+var PROCEDURAL_SIGNAL_RE = /\b(?:how do i|how should i|how can i|how to|what should i do|what do i need to do|steps|procedure|process|workflow|runbook|playbook|guide|guidance|instructions|checklist|recipe|template|walk me through|step by step|best way to|planning|arrange|prepare|book|reserve|schedule|rollout|migration|incident response)\b/iu;
+var CONTEXT_REFERENCE_RE = /\b(?:it|its|that|this|they|them|their|those|these|he|him|his|she|her|hers|other one|other ones)\b/iu;
+var HARD_CONTEXT_PREFIX_RE = /^(?:and\b|also\b|what about\b|how about\b|same\b|same as\b)/iu;
+var SOFT_CONTEXT_FALLBACK_RE = /\b(?:next|follow up|follow-up|continue|continuation)\b/iu;
+var CONTEXT_QUESTION_PREFIX_RE = /^(?:when|where|why|should|does|is|are|what should)\b/iu;
+var MAX_CONTEXT_ANCHOR_CHARS = 120;
+var DIRECTNESS_STABLE_GAP = 0.08;
+var DIRECTNESS_SUBJECT_ENTITY_MATCH_BONUS = 0.16;
+var DIRECTNESS_SUBJECT_IDENTITY_WRAPPER_BONUS = 0.12;
+var DIRECTNESS_DEFINITIONAL_CONTENT_BONUS = 0.22;
+var DIRECTNESS_CLAIM_KEY_ENTITY_MATCH_BONUS = 0.18;
+var DIRECTNESS_ADJACENT_RELATIONSHIP_PENALTY = 0.18;
+var DIRECTNESS_LIST_LORE_PENALTY = 0.08;
+var ENTITY_DIRECTNESS_MAX_WORDS = 5;
+var ENTITY_DIRECTNESS_RECALL_CANDIDATE_LIMIT = 5;
+var DIRECTNESS_IDENTITY_WRAPPERS = /* @__PURE__ */ new Set(["identity", "profile", "bio", "biography", "definition", "overview", "summary"]);
+var DIRECTNESS_RELATIONSHIP_KEYWORDS = /* @__PURE__ */ new Set([
+  "cousin",
+  "cousins",
+  "family",
+  "brother",
+  "brothers",
+  "sister",
+  "sisters",
+  "mother",
+  "father",
+  "parent",
+  "parents",
+  "friend",
+  "friends",
+  "relationship",
+  "relationships",
+  "owner",
+  "owners"
+]);
+var DIRECTNESS_LIST_LORE_KEYWORDS = /* @__PURE__ */ new Set(["list", "notes", "timeline", "history", "background", "facts", "lore"]);
+async function runBeforeTurn(input, deps) {
+  const policy = normalizePolicy(input.policy);
+  const currentTurnText = normalizeOptionalString(input.currentTurnText);
+  const recentTurns = normalizeRecentTurns(input.recentTurns, policy.maxRecentTurns, currentTurnText);
+  const diagnostics = {
+    queryVariants: [],
+    recentTurnCount: recentTurns.length,
+    turnSignalLabels: [],
+    durableRecallUsed: false,
+    durableRecallCandidateCount: 0,
+    procedureRecallUsed: false,
+    procedureCandidateCount: 0,
+    abstained: false,
+    abstentionReasons: [],
+    notices: []
+  };
+  if (!currentTurnText) {
+    diagnostics.abstained = true;
+    diagnostics.abstentionReasons.push("Current turn text was empty after normalization.");
+    return {
+      durableMemory: [],
+      diagnostics
+    };
+  }
+  const turnSignal = inspectTurnSignal(currentTurnText);
+  diagnostics.turnSignalLabels = turnSignal.signalLabels;
+  if (turnSignal.suppressedTurnCategory) {
+    diagnostics.suppressedTurnCategory = turnSignal.suppressedTurnCategory;
+  }
+  if (policy.skipTrivialTurns && turnSignal.suppressedTurnCategory && turnSignal.suppressedTurnCategory !== "low_signal") {
+    diagnostics.abstained = true;
+    diagnostics.abstentionReasons.push(turnSignal.reason);
+    return {
+      durableMemory: [],
+      diagnostics
+    };
+  }
+  if (policy.requireTurnSignal && turnSignal.signalLabels.length === 0) {
+    diagnostics.abstained = true;
+    diagnostics.abstentionReasons.push(turnSignal.reason);
+    return {
+      durableMemory: [],
+      diagnostics
+    };
+  }
+  const durableQueryPlan = buildDurableRecallQueryPlan(currentTurnText, recentTurns, policy.maxQueryChars);
+  const procedureQuery = buildProcedureQuery(currentTurnText, recentTurns, policy.maxQueryChars);
+  if (!durableQueryPlan) {
+    diagnostics.abstained = true;
+    diagnostics.abstentionReasons.push("No usable before-turn query could be derived from the turn context.");
+    return {
+      durableMemory: [],
+      diagnostics
+    };
+  }
+  const [durableMemory, procedure] = await Promise.all([
+    policy.enableDurableRecall ? runDurableRecallSelection(currentTurnText, durableQueryPlan, input.sessionKey, policy, deps, diagnostics) : Promise.resolve([]),
+    policy.enableProcedureSuggestion && procedureQuery ? runProcedureSelection(procedureQuery, policy, deps, diagnostics) : Promise.resolve(void 0)
+  ]);
+  if (!policy.enableDurableRecall) {
+    diagnostics.abstentionReasons.push("Durable recall disabled by before-turn policy.");
+  } else if (durableMemory.length === 0) {
+    diagnostics.abstentionReasons.push("No durable memory entries cleared the before-turn threshold.");
+  }
+  if (!policy.enableProcedureSuggestion) {
+    diagnostics.abstentionReasons.push("Procedure suggestion disabled by before-turn policy.");
+  } else if (!procedure) {
+    diagnostics.abstentionReasons.push("No canonical procedure suggestion cleared the before-turn threshold.");
+  }
+  diagnostics.abstained = durableMemory.length === 0 && !procedure;
+  return {
+    durableMemory: assignRanks(durableMemory),
+    ...procedure ? { procedure } : {},
+    diagnostics
+  };
+}
+async function runDurableRecallSelection(currentTurnText, queryPlan, sessionKey, policy, deps, diagnostics) {
+  diagnostics.durableRecallUsed = true;
+  const attemptedVariants = [];
+  const primaryResult = await runDurableRecallAttempt(currentTurnText, queryPlan.primary.query, sessionKey, policy, deps, diagnostics);
+  attemptedVariants.push({
+    kind: queryPlan.primary.kind,
+    query: queryPlan.primary.query,
+    candidateCount: primaryResult.candidateCount,
+    selected: primaryResult.items.length > 0
+  });
+  if (queryPlan.fallback === void 0 || primaryResult.items.length > 0 && !shouldRetryWeakPrimaryWithContext(primaryResult, policy)) {
+    diagnostics.query = queryPlan.primary.query;
+    diagnostics.queryPolicy = queryPlan.policy;
+    diagnostics.queryVariants = attemptedVariants;
+    diagnostics.durableRecallTrace = primaryResult.durableRecallTrace;
+    diagnostics.durableRecallCandidateCount = primaryResult.candidateCount;
+    diagnostics.directness = primaryResult.directness;
+    if (primaryResult.notices.length > 0) {
+      diagnostics.notices.push(...primaryResult.notices);
+    }
+    if (primaryResult.directness?.decision === "abstained") {
+      diagnostics.abstentionReasons.push(primaryResult.directness.reason);
+    }
+    return primaryResult.items;
+  }
+  const fallbackPlan = queryPlan.fallback;
+  const primaryItems = primaryResult.items;
+  const fallbackResult = await runDurableRecallAttempt(currentTurnText, fallbackPlan.query, sessionKey, policy, deps, diagnostics);
+  const shouldUseFallback = fallbackResult.items.length > 0;
+  attemptedVariants[0] = {
+    ...attemptedVariants[0],
+    selected: primaryItems.length > 0 && !shouldUseFallback
+  };
+  attemptedVariants.push({
+    kind: fallbackPlan.kind,
+    query: fallbackPlan.query,
+    candidateCount: fallbackResult.candidateCount,
+    selected: shouldUseFallback
+  });
+  const selectedResult = shouldUseFallback ? fallbackResult : primaryResult;
+  const selectedQuery = shouldUseFallback ? fallbackPlan.query : queryPlan.primary.query;
+  const selectedPolicy = shouldUseFallback ? "contextual_fallback" : queryPlan.policy;
+  diagnostics.query = selectedQuery;
+  diagnostics.queryPolicy = selectedPolicy;
+  diagnostics.queryVariants = attemptedVariants;
+  diagnostics.durableRecallTrace = selectedResult.durableRecallTrace;
+  diagnostics.durableRecallCandidateCount = selectedResult.candidateCount;
+  diagnostics.directness = selectedResult.directness;
+  if (primaryResult.notices.length > 0) {
+    diagnostics.notices.push(...primaryResult.notices);
+  }
+  if (fallbackResult.notices.length > 0) {
+    diagnostics.notices.push(...fallbackResult.notices);
+  }
+  if (selectedResult.directness?.decision === "abstained") {
+    diagnostics.abstentionReasons.push(selectedResult.directness.reason);
+  }
+  return selectedResult.items;
+}
+function shouldRetryWeakPrimaryWithContext(primaryResult, policy) {
+  const topScore = primaryResult.items[0]?.score;
+  return typeof topScore === "number" && topScore < policy.highConfidenceRecallThreshold;
+}
+async function runDurableRecallAttempt(currentTurnText, query, sessionKey, policy, deps, diagnostics) {
+  const directnessQuery = detectEntityDefinitionTurn(currentTurnText);
+  const durableRecallLimit = directnessQuery ? Math.max(policy.maxDurableEntries, policy.maxHighConfidenceDurableEntries, ENTITY_DIRECTNESS_RECALL_CANDIDATE_LIMIT) : Math.max(policy.maxDurableEntries, policy.maxHighConfidenceDurableEntries);
+  let durableRecallTrace;
+  try {
+    const recalled = await recall(
+      {
+        text: query,
+        limit: durableRecallLimit,
+        threshold: policy.recallThreshold,
+        sessionKey
+      },
+      deps.recall,
+      {
+        trace: {
+          reportSummary(summary) {
+            durableRecallTrace = summary;
+          }
+        },
+        slotPolicyConfig: deps.slotPolicyConfig
+      }
+    );
+    const notices = durableRecallTrace?.degraded.notices.length ? [...durableRecallTrace.degraded.notices] : [];
+    const directnessSelection = applyDirectnessSelection(
+      currentTurnText,
+      recalled.map((item) => buildDurablePatchItem(item, deps))
+    );
+    return {
+      items: selectDurablePatchItems(directnessSelection.items, policy, diagnostics),
+      candidateCount: recalled.length,
+      durableRecallTrace,
+      directness: directnessSelection.diagnostics,
+      notices
+    };
+  } catch (error) {
+    return {
+      items: [],
+      candidateCount: 0,
+      durableRecallTrace,
+      notices: [`Before-turn durable recall failed: ${formatErrorMessage(error)}`]
+    };
+  }
+}
+async function runProcedureSelection(query, policy, deps, diagnostics) {
+  diagnostics.procedureRecallUsed = true;
+  try {
+    const result = await runProcedureRecall(
+      {
+        text: query,
+        limit: policy.maxProcedureCandidates,
+        threshold: policy.procedureThreshold
+      },
+      {
+        db: deps.procedures,
+        ...deps.embedQuery ? { embedQuery: deps.embedQuery } : {}
+      }
+    );
+    diagnostics.procedureCandidateCount = result.candidates.length;
+    if (result.notices.length > 0) {
+      diagnostics.notices.push(...result.notices);
+    }
+    const canonicalProcedure = result.canonicalProcedure;
+    if (!canonicalProcedure) {
+      return void 0;
+    }
+    const leader = result.candidates.find((candidate) => candidate.procedure.id === canonicalProcedure.id);
+    if (!leader) {
+      diagnostics.notices.push("Procedure recall returned a canonical procedure without a matching ranked candidate.");
+      return void 0;
+    }
+    return {
+      procedure: canonicalProcedure,
+      score: leader.score,
+      scores: {
+        relevance: leader.scores.relevance,
+        lexical: leader.scores.lexical,
+        vector: leader.scores.vector
+      },
+      whySurfaced: {
+        summary: `canonical procedure match; score ${leader.score.toFixed(2)}`,
+        reasons: [
+          "canonical procedure match",
+          `score ${leader.score.toFixed(2)}`,
+          `lexical ${leader.scores.lexical.toFixed(2)}`,
+          `vector ${leader.scores.vector.toFixed(2)}`
+        ]
+      }
+    };
+  } catch (error) {
+    diagnostics.notices.push(`Before-turn procedure recall failed: ${formatErrorMessage(error)}`);
+    return void 0;
+  }
+}
+function buildDurablePatchItem(recalled, deps) {
+  const projected = projectClaimCentricRecallEntry(recalled, {
+    slotPolicyConfig: deps.slotPolicyConfig
+  });
+  return {
+    rank: 0,
+    entry: recalled.entry,
+    sourceKind: "turn_recall",
+    score: recalled.score,
+    whySurfaced: projected.whySurfaced,
+    memoryState: projected.memoryState,
+    claimStatus: projected.claimStatus,
+    freshnessLabel: projected.freshness.label,
+    ...formatProjectedProvenance(projected.provenance) ? { provenanceSummary: formatProjectedProvenance(projected.provenance) } : {}
+  };
+}
+function buildDurableRecallQueryPlan(currentTurnText, recentTurns, maxChars) {
+  const currentOnlyQuery = buildCurrentTurnOnlyQuery(currentTurnText, maxChars);
+  if (!currentOnlyQuery) {
+    return void 0;
+  }
+  const contextualQuery = buildContextualAnchorQuery(currentOnlyQuery, recentTurns, maxChars);
+  if (!contextualQuery) {
+    return {
+      policy: "current_only",
+      primary: {
+        kind: "current_only",
+        query: currentOnlyQuery
+      }
+    };
+  }
+  if (requiresContextualQuery(currentTurnText)) {
+    return {
+      policy: "contextual_required",
+      primary: {
+        kind: "contextual_anchor",
+        query: contextualQuery
+      }
+    };
+  }
+  if (shouldAllowContextualFallback(currentTurnText, recentTurns)) {
+    return {
+      policy: "current_only",
+      primary: {
+        kind: "current_only",
+        query: currentOnlyQuery
+      },
+      fallback: {
+        kind: "contextual_anchor",
+        query: contextualQuery
+      }
+    };
+  }
+  return {
+    policy: "current_only",
+    primary: {
+      kind: "current_only",
+      query: currentOnlyQuery
+    }
+  };
+}
+function buildCurrentTurnOnlyQuery(currentTurnText, maxChars) {
+  if (maxChars <= 0) {
+    return void 0;
+  }
+  const query = truncate(normalizeWhitespace(currentTurnText), maxChars);
+  return query.length > 0 ? query : void 0;
+}
+function buildContextualAnchorQuery(currentTurnQuery, recentTurns, maxChars) {
+  const anchor = buildCompactContextAnchor(recentTurns);
+  if (!anchor || maxChars <= currentTurnQuery.length) {
+    return void 0;
+  }
+  const prefix = "Topic: ";
+  const separator = "\n";
+  const remaining = maxChars - currentTurnQuery.length - separator.length - prefix.length;
+  if (remaining <= 0) {
+    return void 0;
+  }
+  return `${currentTurnQuery}${separator}${prefix}${truncate(anchor, remaining)}`;
+}
+function buildCompactContextAnchor(recentTurns) {
+  const recentTurn = recentTurns[recentTurns.length - 1];
+  if (!recentTurn) {
+    return void 0;
+  }
+  const normalized = normalizeWhitespace(recentTurn.text);
+  return normalized.length > 0 ? truncate(normalized, MAX_CONTEXT_ANCHOR_CHARS) : void 0;
+}
+function requiresContextualQuery(currentTurnText) {
+  const normalizedTurn = normalizeWhitespace(currentTurnText);
+  const lowerTurn = normalizedTurn.toLowerCase();
+  const wordCount = normalizedTurn.split(/\s+/u).filter((token) => token.length > 0).length;
+  const hasContextReference = CONTEXT_REFERENCE_RE.test(lowerTurn);
+  if (HARD_CONTEXT_PREFIX_RE.test(lowerTurn) && (hasContextReference || lowerTurn.includes("other one"))) {
+    return true;
+  }
+  if (CONTEXT_QUESTION_PREFIX_RE.test(lowerTurn) && hasContextReference && wordCount <= 8) {
+    return true;
+  }
+  return hasContextReference && wordCount <= 6;
+}
+function shouldAllowContextualFallback(currentTurnText, recentTurns) {
+  if (recentTurns.length === 0 || requiresContextualQuery(currentTurnText)) {
+    return false;
+  }
+  return SOFT_CONTEXT_FALLBACK_RE.test(normalizeWhitespace(currentTurnText).toLowerCase());
+}
+function buildProcedureQuery(currentTurnText, recentTurns, maxChars) {
+  const normalizedCurrentTurn = normalizeWhitespace(currentTurnText);
+  if (normalizedCurrentTurn.length > 0) {
+    return truncate(normalizedCurrentTurn, maxChars);
+  }
+  const recentUserTurn = [...recentTurns].reverse().find((turn) => turn.role === "user");
+  return recentUserTurn ? truncate(normalizeWhitespace(recentUserTurn.text), maxChars) : void 0;
+}
+function applyDirectnessSelection(currentTurnText, items) {
+  if (items.length === 0) {
+    return { items };
+  }
+  const queryMatch = detectEntityDefinitionTurn(currentTurnText);
+  if (!queryMatch) {
+    return { items };
+  }
+  const scoredCandidates = items.map((item, index) => scoreDirectnessCandidate(queryMatch, item, index + 1));
+  const rerankedCandidates = [...scoredCandidates].sort(compareDirectnessCandidates);
+  const winner = rerankedCandidates[0];
+  const runnerUp = rerankedCandidates[1];
+  const winnerGap = runnerUp ? winner.adjustedScore - runnerUp.adjustedScore : void 0;
+  const winnerHasPositiveIdentitySignal = hasPositiveIdentitySignal(winner);
+  const runnerUpHasPositiveIdentitySignal = runnerUp ? hasPositiveIdentitySignal(runnerUp) : false;
+  const winnerHasOnlyAdjacentSignals = winner.signals.includes("adjacent_relationship") && !winner.signals.includes("definitional_content") && !winner.signals.includes("subject_entity_match") && !winner.signals.includes("subject_identity_wrapper");
+  const requiresStrictStableGap = runnerUpHasPositiveIdentitySignal;
+  const winnerGapTooSmall = requiresStrictStableGap && runnerUp !== void 0 && winnerGap !== void 0 && winnerGap < DIRECTNESS_STABLE_GAP;
+  if (!winnerHasPositiveIdentitySignal || winnerHasOnlyAdjacentSignals || winnerGapTooSmall) {
+    const reason2 = !winnerHasPositiveIdentitySignal || winnerHasOnlyAdjacentSignals ? `Before-turn directness check abstained for "${queryMatch.entity}" because the top candidate looked adjacent rather than definitional.` : `Before-turn directness check abstained for "${queryMatch.entity}" because the top candidates remained too close after reranking.`;
+    return {
+      items: [],
+      diagnostics: buildDirectnessDiagnostics(queryMatch, "abstained", reason2, rerankedCandidates, winnerGap)
+    };
+  }
+  const decision = winner.baseRank === 1 ? "kept" : "reranked";
+  const reason = decision === "kept" ? `Before-turn directness check kept ${winner.item.entry.id} because it stayed the clearest definitional match for "${queryMatch.entity}".` : `Before-turn directness check reranked ${winner.item.entry.id} ahead of an adjacent match for "${queryMatch.entity}".`;
+  return {
+    items: [winner.item],
+    diagnostics: buildDirectnessDiagnostics(queryMatch, decision, reason, rerankedCandidates, winnerGap)
+  };
+}
+function detectEntityDefinitionTurn(currentTurnText) {
+  const normalizedTurn = normalizeWhitespace(currentTurnText);
+  const patterns = [/^(?:who|what)\s+is\s+(.+?)(?:\s+again)?[?!.,]*$/iu, /^who'?s\s+(.+?)(?:\s+again)?[?!.,]*$/iu, /^tell\s+me\s+about\s+(.+?)[?!.,]*$/iu];
+  for (const pattern of patterns) {
+    const match = pattern.exec(normalizedTurn);
+    const candidateEntity = normalizeDirectnessEntity(match?.[1]);
+    if (candidateEntity) {
+      return {
+        kind: "entity_definition",
+        entity: candidateEntity,
+        normalizedEntity: normalizeDirectnessText(candidateEntity)
+      };
+    }
+  }
+  return void 0;
+}
+function normalizeDirectnessEntity(entityText) {
+  const cleaned = entityText ? normalizeWhitespace(entityText).replace(/^[("'`]+/u, "").replace(/[)"'`?!.,]+$/u, "").replace(/^(?:the|a|an)\s+/iu, "").trim() : "";
+  if (cleaned.length === 0) {
+    return void 0;
+  }
+  const wordCount = cleaned.split(/\s+/u).filter((token) => token.length > 0).length;
+  const normalized = normalizeDirectnessText(cleaned);
+  if (wordCount === 0 || wordCount > ENTITY_DIRECTNESS_MAX_WORDS || CONTEXT_REFERENCE_RE.test(normalized) || normalized.includes("'s") || containsKeyword(normalized, DIRECTNESS_RELATIONSHIP_KEYWORDS)) {
+    return void 0;
+  }
+  return cleaned;
+}
+function scoreDirectnessCandidate(queryMatch, item, baseRank) {
+  const subject = normalizeDirectnessText(item.entry.subject);
+  const content = normalizeDirectnessText(item.entry.content);
+  const signals = [];
+  let directnessDelta = 0;
+  if (subject === queryMatch.normalizedEntity) {
+    signals.push("subject_entity_match");
+    directnessDelta += DIRECTNESS_SUBJECT_ENTITY_MATCH_BONUS;
+  } else if (isIdentityWrapperSubject(subject, queryMatch.normalizedEntity)) {
+    signals.push("subject_identity_wrapper");
+    directnessDelta += DIRECTNESS_SUBJECT_IDENTITY_WRAPPER_BONUS;
+  }
+  if (hasDefinitionalContent(content, queryMatch.normalizedEntity)) {
+    signals.push("definitional_content");
+    directnessDelta += DIRECTNESS_DEFINITIONAL_CONTENT_BONUS;
+  }
+  if (hasEntityClaimKey(item.entry.claim_key, queryMatch.normalizedEntity)) {
+    signals.push("claim_key_entity_match");
+    directnessDelta += DIRECTNESS_CLAIM_KEY_ENTITY_MATCH_BONUS;
+  }
+  if (looksLikeAdjacentRelationship(subject, content, queryMatch.normalizedEntity)) {
+    signals.push("adjacent_relationship");
+    directnessDelta -= DIRECTNESS_ADJACENT_RELATIONSHIP_PENALTY;
+  }
+  if (looksLikeListLore(subject, content)) {
+    signals.push("list_lore");
+    directnessDelta -= DIRECTNESS_LIST_LORE_PENALTY;
+  }
+  return {
+    item,
+    baseRank,
+    baseScore: item.score,
+    directnessDelta,
+    adjustedScore: item.score + directnessDelta,
+    signals
+  };
+}
+function buildDirectnessDiagnostics(queryMatch, decision, reason, candidates, winnerGap) {
+  const winner = decision === "abstained" ? void 0 : candidates[0];
+  const runnerUp = candidates[1];
+  return {
+    queryKind: queryMatch.kind,
+    entity: queryMatch.entity,
+    decision,
+    winnerEntryId: winner?.item.entry.id,
+    runnerUpEntryId: runnerUp?.item.entry.id,
+    ...winnerGap !== void 0 ? { winnerGap: roundToThreeDecimals(winnerGap) } : {},
+    reason,
+    candidates: candidates.map((candidate) => ({
+      entryId: candidate.item.entry.id,
+      baseRank: candidate.baseRank,
+      baseScore: roundToThreeDecimals(candidate.baseScore),
+      directnessDelta: roundToThreeDecimals(candidate.directnessDelta),
+      adjustedScore: roundToThreeDecimals(candidate.adjustedScore),
+      signals: candidate.signals
+    }))
+  };
+}
+function hasPositiveIdentitySignal(candidate) {
+  return candidate.signals.includes("definitional_content") || candidate.signals.includes("subject_entity_match") || candidate.signals.includes("subject_identity_wrapper");
+}
+function isIdentityWrapperSubject(subject, entity) {
+  for (const wrapper of DIRECTNESS_IDENTITY_WRAPPERS) {
+    if (subject === `${entity} ${wrapper}` || subject === `${wrapper} ${entity}`) {
+      return true;
+    }
+  }
+  return false;
+}
+function hasDefinitionalContent(content, entity) {
+  const escapedEntity = escapeRegExp(entity);
+  if (startsWithBareRelationshipPredicate(content, escapedEntity)) {
+    return false;
+  }
+  const anchoredPatterns = [new RegExp(`^${escapedEntity}\\s+(?:is|was|means)\\b`, "u"), new RegExp(`^${escapedEntity}\\s+refers\\s+to\\b`, "u")];
+  if (anchoredPatterns.some((pattern) => pattern.test(content))) {
+    return true;
+  }
+  return hasEmbeddedDefinitionalContent(content, escapedEntity);
+}
+function hasEmbeddedDefinitionalContent(content, escapedEntity) {
+  const embeddedLead = `(?:^|[.!?;:]\\s+)${escapedEntity}\\s+(?:is|was)\\s+`;
+  const fullNameLead = `(?:^|[.!?;:]\\s+)${escapedEntity}(?:\\s+[\\p{L}\\p{N}]+){1,2}\\s+(?:is|was)\\s+`;
+  if (startsWithBareRelationshipPredicate(content, escapedEntity)) {
+    return false;
+  }
+  const patterns = [
+    new RegExp(`${embeddedLead}(?:a|an|the)\\b`, "u"),
+    new RegExp(`${embeddedLead}[\\p{L}\\p{N}]+(?:['\u2019]s)\\b`, "u"),
+    // Allow short-name queries like "who is John?" to match a leading
+    // full-name clause such as "John Doe is married to Beverly".
+    new RegExp(`${fullNameLead}(?:a|an|the)\\b`, "u"),
+    new RegExp(`${fullNameLead}[\\p{L}\\p{N}]+\\b`, "u")
+  ];
+  return patterns.some((pattern) => pattern.test(content));
+}
+function startsWithBareRelationshipPredicate(content, escapedEntity) {
+  const relationshipAlternation = Array.from(DIRECTNESS_RELATIONSHIP_KEYWORDS).join("|");
+  const embeddedLead = `(?:^|[.!?;:]\\s+)${escapedEntity}\\s+(?:is|was)\\s+`;
+  return new RegExp(`${embeddedLead}(?:${relationshipAlternation})\\b`, "u").test(content);
+}
+function looksLikeAdjacentRelationship(subject, content, entity) {
+  if (!subject.includes(entity) && !content.includes(entity)) {
+    return false;
+  }
+  return containsKeyword(subject, DIRECTNESS_RELATIONSHIP_KEYWORDS) || containsKeyword(content, DIRECTNESS_RELATIONSHIP_KEYWORDS);
+}
+function looksLikeListLore(subject, content) {
+  return containsKeyword(subject, DIRECTNESS_LIST_LORE_KEYWORDS) || containsKeyword(content, DIRECTNESS_LIST_LORE_KEYWORDS);
+}
+function compareDirectnessCandidates(left, right) {
+  if (right.adjustedScore !== left.adjustedScore) {
+    return right.adjustedScore - left.adjustedScore;
+  }
+  if (right.baseScore !== left.baseScore) {
+    return right.baseScore - left.baseScore;
+  }
+  return left.baseRank - right.baseRank;
+}
+function normalizeDirectnessText(value) {
+  return normalizeWhitespace(value).toLocaleLowerCase();
+}
+function hasEntityClaimKey(claimKey, entity) {
+  const head = claimKey?.split("/", 1)[0]?.replace(/[-_]+/g, " ");
+  return normalizeDirectnessText(head ?? "") === entity;
+}
+function containsKeyword(text, keywords) {
+  const tokens = new Set(text.match(/[\p{L}\p{N}]+/gu) ?? []);
+  for (const keyword of keywords) {
+    if (tokens.has(keyword)) {
+      return true;
+    }
+  }
+  return false;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function roundToThreeDecimals(value) {
+  return Math.round(value * 1e3) / 1e3;
+}
+function selectDurablePatchItems(items, policy, diagnostics) {
+  if (policy.maxDurableEntries <= 0 || items.length === 0) {
+    return [];
+  }
+  const boundedItems = items.slice(0, policy.maxDurableEntries);
+  const expandedLimit = Math.max(policy.maxDurableEntries, policy.maxHighConfidenceDurableEntries);
+  if (expandedLimit <= policy.maxDurableEntries || items.length <= policy.maxDurableEntries) {
+    return boundedItems;
+  }
+  const expansionCandidates = items.slice(0, expandedLimit);
+  const canExpand = expansionCandidates.length > policy.maxDurableEntries && expansionCandidates.every((item) => item.score >= policy.highConfidenceRecallThreshold);
+  if (canExpand) {
+    diagnostics.notices.push(`Before-turn durable recall expanded to ${expansionCandidates.length} high-confidence items.`);
+    return expansionCandidates;
+  }
+  diagnostics.notices.push(
+    `Before-turn durable recall kept the top ${boundedItems.length} item${boundedItems.length === 1 ? "" : "s"} because additional candidates were not high confidence.`
+  );
+  return boundedItems;
+}
+function inspectTurnSignal(currentTurnText) {
+  const normalizedTurn = normalizeWhitespace(currentTurnText);
+  const lowerTurn = normalizedTurn.toLowerCase();
+  const signalLabels = collectTurnSignalLabels(lowerTurn);
+  const wordCount = normalizedTurn.split(/\s+/u).filter((token) => token.length > 0).length;
+  const isShortTurn = wordCount <= SHORT_TURN_MAX_WORDS || normalizedTurn.length <= SHORT_TURN_MAX_CHARS;
+  if (signalLabels.length === 0 && (SOCIAL_TURN_RE.test(lowerTurn) || isShortTurn)) {
+    return {
+      signalLabels,
+      suppressedTurnCategory: "short_social",
+      reason: "Current turn was short or social without clear factual, procedural, or task intent."
+    };
+  }
+  if (signalLabels.length === 0) {
+    return {
+      signalLabels,
+      suppressedTurnCategory: "low_signal",
+      reason: "Current turn lacked clear factual, procedural, or task signal, so before-turn recall abstained."
+    };
+  }
+  return {
+    signalLabels,
+    reason: `Current turn showed ${signalLabels.join(", ")} recall signal.`
+  };
+}
+function collectTurnSignalLabels(lowerTurn) {
+  const labels = [];
+  if (TASK_SIGNAL_RE.test(lowerTurn)) {
+    labels.push("task");
+  }
+  if (FACTUAL_SIGNAL_RE.test(lowerTurn)) {
+    labels.push("factual");
+  }
+  if (PROCEDURAL_SIGNAL_RE.test(lowerTurn)) {
+    labels.push("procedural");
+  }
+  return labels;
+}
+function assignRanks(items) {
+  return items.map((item, index) => ({
+    ...item,
+    rank: index + 1
+  }));
+}
+function normalizePolicy(policy) {
+  const maxDurableEntries = normalizeCount(policy?.maxDurableEntries, DEFAULT_MAX_DURABLE_ENTRIES);
+  const maxHighConfidenceDurableEntries = Math.max(
+    maxDurableEntries,
+    normalizeCount(policy?.maxHighConfidenceDurableEntries, DEFAULT_MAX_HIGH_CONFIDENCE_DURABLE_ENTRIES)
+  );
+  return {
+    enableDurableRecall: policy?.enableDurableRecall !== false,
+    enableProcedureSuggestion: policy?.enableProcedureSuggestion !== false,
+    maxRecentTurns: normalizeCount(policy?.maxRecentTurns, DEFAULT_MAX_RECENT_TURNS),
+    maxQueryChars: normalizeCount(policy?.maxQueryChars, DEFAULT_MAX_QUERY_CHARS),
+    maxDurableEntries,
+    maxHighConfidenceDurableEntries,
+    maxProcedureCandidates: normalizeCount(policy?.maxProcedureCandidates, DEFAULT_MAX_PROCEDURE_CANDIDATES),
+    recallThreshold: normalizeThreshold(policy?.recallThreshold, DEFAULT_RECALL_THRESHOLD),
+    highConfidenceRecallThreshold: normalizeThreshold(policy?.highConfidenceRecallThreshold, DEFAULT_HIGH_CONFIDENCE_RECALL_THRESHOLD),
+    procedureThreshold: normalizeThreshold(policy?.procedureThreshold, DEFAULT_PROCEDURE_THRESHOLD),
+    skipTrivialTurns: policy?.skipTrivialTurns ?? DEFAULT_SKIP_TRIVIAL_TURNS,
+    requireTurnSignal: policy?.requireTurnSignal ?? DEFAULT_REQUIRE_TURN_SIGNAL
+  };
+}
+function normalizeCount(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.max(0, Math.trunc(value));
+}
+function normalizeThreshold(value, fallback) {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return Math.min(1, Math.max(0, value));
+}
+function normalizeRecentTurns(recentTurns, maxRecentTurns, currentTurnText) {
+  if (!recentTurns || recentTurns.length === 0 || maxRecentTurns <= 0) {
+    return [];
+  }
+  const normalizedTurns = recentTurns.flatMap((turn) => {
+    if (turn.role !== "user" && turn.role !== "assistant") {
+      return [];
+    }
+    const text = normalizeOptionalString(turn.text);
+    return text ? [{ role: turn.role, text }] : [];
+  });
+  const currentTurnFingerprint = currentTurnText ? normalizeWhitespace(currentTurnText).toLowerCase() : void 0;
+  const deduped = [...normalizedTurns];
+  while (deduped.length > 0 && currentTurnFingerprint) {
+    const last = deduped[deduped.length - 1];
+    if (!last || last.role !== "user") {
+      break;
+    }
+    if (normalizeWhitespace(last.text).toLowerCase() !== currentTurnFingerprint) {
+      break;
+    }
+    deduped.pop();
+  }
+  return deduped.slice(-maxRecentTurns);
+}
+function formatProjectedProvenance(provenance) {
+  const parts = [
+    provenance.supersededById ? `superseded_by=${provenance.supersededById}` : void 0,
+    provenance.supersessionKind ? `kind=${provenance.supersessionKind}` : void 0,
+    provenance.supersessionReason ? `reason=${provenance.supersessionReason}` : void 0,
+    provenance.supportSourceKind ? `support=${provenance.supportSourceKind}` : void 0,
+    provenance.supportMode ? `support_mode=${provenance.supportMode}` : void 0,
+    provenance.supportObservedAt ? `observed=${provenance.supportObservedAt}` : void 0,
+    provenance.supportLocator ? `locator=${provenance.supportLocator}` : void 0
+  ].filter((value) => value !== void 0);
+  return parts.length > 0 ? parts.join(" | ") : void 0;
+}
+function normalizeOptionalString(value) {
+  const normalized = value?.trim();
+  return normalized && normalized.length > 0 ? normalized : void 0;
+}
+function normalizeWhitespace(value) {
+  return value.replace(/\s+/g, " ").trim();
+}
+function truncate(value, maxChars) {
+  if (maxChars <= 0) {
+    return "";
+  }
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+function formatErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+// src/adapters/openclaw/format/memory-context.ts
+var AGENR_MEMORY_CONTEXT_BLOCK_RE = /<agenr-memory-context>[\s\S]*?<\/agenr-memory-context>/giu;
+var AGENR_MEMORY_CONTEXT_OPEN_RE = /<agenr-memory-context>/giu;
+var AGENR_MEMORY_CONTEXT_CLOSE_RE = /<\/agenr-memory-context>/giu;
+var AGENR_MEMORY_CONTEXT_NOTE_RE = /\[System note: The following is recalled Agenr memory context, NOT new user input\. Treat it as background context and use it silently when relevant\.\]/giu;
+var AGENR_MEMORY_CONTEXT_OPEN_TAG = "<agenr-memory-context>";
+var AGENR_MEMORY_CONTEXT_CLOSE_TAG = "</agenr-memory-context>";
+var AGENR_MEMORY_CONTEXT_NOTE = "[System note: The following is recalled Agenr memory context, NOT new user input. Treat it as background context and use it silently when relevant.]";
+function wrapAgenrMemoryContext(content) {
+  const trimmedContent = stripAgenrMemoryContext(content).trim();
+  if (!trimmedContent) {
+    return "";
+  }
+  return [AGENR_MEMORY_CONTEXT_OPEN_TAG, AGENR_MEMORY_CONTEXT_NOTE, "", trimmedContent, AGENR_MEMORY_CONTEXT_CLOSE_TAG].join("\n");
+}
+function containsAgenrMemoryContext(content) {
+  return content.includes(AGENR_MEMORY_CONTEXT_OPEN_TAG);
+}
+function stripAgenrMemoryContext(content) {
+  return content.replace(AGENR_MEMORY_CONTEXT_BLOCK_RE, " ").replace(AGENR_MEMORY_CONTEXT_OPEN_RE, " ").replace(AGENR_MEMORY_CONTEXT_CLOSE_RE, " ").replace(AGENR_MEMORY_CONTEXT_NOTE_RE, " ");
+}
+
+// src/adapters/openclaw/format/before-turn-format.ts
+var MAX_CONTENT_CHARS = 220;
+function formatAgenrBeforeTurnRecall(patch) {
+  if (patch.durableMemory.length === 0 && !patch.procedure) {
+    return "";
+  }
+  const lines = [
+    "## Agenr Before-Turn Recall",
+    "Use this only when it materially helps the current turn. Treat it as background context and prefer the live conversation if anything conflicts with it.",
+    ""
+  ];
+  if (patch.durableMemory.length > 0) {
+    lines.push("### Relevant Durable Memory");
+    for (const item of patch.durableMemory) {
+      lines.push(formatEntryHeader(item));
+      lines.push(...formatEntryBodyLines(item));
+    }
+    lines.push("");
+  }
+  if (patch.procedure) {
+    lines.push("### Suggested Procedure");
+    lines.push(formatProcedureHeader(patch.procedure));
+    lines.push(...formatProcedureBodyLines(patch.procedure));
+    lines.push("");
+  }
+  return wrapAgenrMemoryContext(lines.join("\n").trim());
+}
+function formatEntryHeader(item) {
+  const metadata = [
+    `rank ${item.rank}`,
+    item.entry.id,
+    item.entry.type,
+    item.entry.expiry,
+    `importance ${item.entry.importance}`,
+    `score ${item.score.toFixed(2)}`
+  ];
+  return `- [${metadata.join(" | ")}] ${item.entry.subject}`;
+}
+function formatEntryBodyLines(item) {
+  const lines = [`  ${truncate2(item.entry.content.trim(), MAX_CONTENT_CHARS)}`];
+  lines.push(`  why: ${item.whySurfaced.summary}`);
+  const metadata = [
+    item.entry.tags.length > 0 ? `tags: ${item.entry.tags.join(", ")}` : void 0,
+    item.freshnessLabel ? `freshness: ${item.freshnessLabel}` : void 0,
+    item.provenanceSummary ? `provenance: ${truncate2(item.provenanceSummary, MAX_CONTENT_CHARS)}` : void 0
+  ].filter((value) => value !== void 0);
+  if (metadata.length > 0) {
+    lines.push(`  ${metadata.join(" | ")}`);
+  }
+  return lines;
+}
+function formatProcedureHeader(suggestion) {
+  const metadata = [
+    suggestion.procedure.id,
+    suggestion.procedure.procedure_key,
+    `score ${suggestion.score.toFixed(2)}`,
+    `lexical ${suggestion.scores.lexical.toFixed(2)}`,
+    `vector ${suggestion.scores.vector.toFixed(2)}`
+  ];
+  return `- [${metadata.join(" | ")}] ${suggestion.procedure.title}`;
+}
+function formatProcedureBodyLines(suggestion) {
+  const lines = [`  goal: ${truncate2(suggestion.procedure.goal.trim(), MAX_CONTENT_CHARS)}`];
+  lines.push(`  why: ${suggestion.whySurfaced.summary}`);
+  if (suggestion.procedure.when_to_use.length > 0) {
+    lines.push(`  when to use: ${truncate2(suggestion.procedure.when_to_use.join("; "), MAX_CONTENT_CHARS)}`);
+  }
+  if (suggestion.procedure.verification.length > 0) {
+    lines.push(`  verification: ${truncate2(suggestion.procedure.verification.join("; "), MAX_CONTENT_CHARS)}`);
+  }
+  return lines;
+}
+function truncate2(value, maxChars) {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, maxChars - 3).trimEnd()}...`;
+}
+
+// src/app/debug-artifacts/before-turn.ts
+var BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K = 10;
+var BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K = 25;
+
+// src/app/debug-artifacts/recall.ts
+var RECALL_DEBUG_ARTIFACT_DEFAULT_TOP_K = 10;
+var RECALL_DEBUG_ARTIFACT_MAX_TOP_K = 25;
+
+export {
+  runBeforeTurn,
+  wrapAgenrMemoryContext,
+  containsAgenrMemoryContext,
+  stripAgenrMemoryContext,
+  formatAgenrBeforeTurnRecall,
+  BEFORE_TURN_DEBUG_ARTIFACT_DEFAULT_TOP_K,
+  BEFORE_TURN_DEBUG_ARTIFACT_MAX_TOP_K,
+  RECALL_DEBUG_ARTIFACT_DEFAULT_TOP_K,
+  RECALL_DEBUG_ARTIFACT_MAX_TOP_K
+};