recallnest 2.3.0 → 2.6.0

package/src/env-config.ts

@@ -0,0 +1,118 @@
+/**
+ * Centralized RECALLNEST_* environment variable accessors (P3-C config 收口).
+ *
+ * Single source of truth for every fixed `RECALLNEST_*` env flag read across `src/`:
+ * the env NAME, its default, and its parsing all live here. Consumers call these
+ * accessors instead of reading `process.env` directly.
+ *
+ * This is a PURE-MOVEMENT refactor — each accessor preserves the exact original
+ * parsing. Do not "improve" them; the following invariants are load-bearing:
+ *
+ * - Boolean flags use strict `=== "true"` — no trim, no case-folding, no truthy
+ *   coercion. `"True"` / `" true "` / `"1"` must NOT enable a flag.
+ * - String defaults use `||`, NOT `??` — an empty string falls through to the
+ *   default (matches the original inline reads).
+ * - Raw-value accessors (recall mode, ports) return the UNPARSED env value so the
+ *   caller keeps its existing validation / clamping / config-fallback logic. In
+ *   particular `recallModeRaw()` must not default to "summary" here, or it would
+ *   bypass the `config.recallMode` fallback in resolveRecallMode().
+ * - `mcpTier()` keeps only the type assertion with NO runtime validation — an
+ *   illegal non-empty value is preserved as-is (downstream shouldRegisterTool()
+ *   relies on this), so do not coerce unknown values back to the default.
+ *
+ * Accessors are FUNCTIONS (lazy): they read `process.env` at call time. Never
+ * freeze them into module-load constants — 100+ tests toggle `process.env` at
+ * runtime. Consumers must substitute in place and never relocate a read across
+ * the `loadDotEnv()` boundary or into a different evaluation phase: five reads are
+ * intentionally module-init-time eager (mcp-server tier, api/ui ports,
+ * activity-counter / distill-lock data dir) and must stay eager.
+ *
+ * Intentionally NOT centralized here:
+ * - scope-policy.ts's RECALLNEST_DEFAULT_SCOPE / _SCOPE / _PROJECT_SCOPE /
+ *   _SESSION_ID — an injectable `options.env || process.env` policy entry that is
+ *   already consolidated in that module with caller-injection semantics.
+ * - store.ts's `RECALLNEST_NS` — a local hash-namespace constant, not an env var.
+ * - config-template `${VAR}` expansion in runtime-config / embedder / llm-client.
+ */
+
+// --- Boolean feature flags (strict === "true") ---
+
+export const multiVector = (): boolean => process.env.RECALLNEST_MULTI_VECTOR === "true";
+
+export const emotionScoring = (): boolean => process.env.RECALLNEST_EMOTION_SCORING === "true";
+
+export const predictiveMemory = (): boolean => process.env.RECALLNEST_PREDICTIVE_MEMORY === "true";
+
+export const synthesize = (): boolean => process.env.RECALLNEST_SYNTHESIZE === "true";
+
+export const llmConsolidation = (): boolean => process.env.RECALLNEST_LLM_CONSOLIDATION === "true";
+
+export const constructiveRetrieval = (): boolean =>
+  process.env.RECALLNEST_CONSTRUCTIVE_RETRIEVAL === "true";
+
+export const narrativeMode = (): boolean => process.env.RECALLNEST_NARRATIVE_MODE === "true";
+
+export const kgMode = (): boolean => process.env.RECALLNEST_KG_MODE === "true";
+
+export const coreSummary = (): boolean => process.env.RECALLNEST_CORE_SUMMARY === "true";
+
+export const errorSignatureBoost = (): boolean =>
+  process.env.RECALLNEST_ERROR_SIGNATURE_BOOST === "true";
+
+export const usageDecay = (): boolean => process.env.RECALLNEST_USAGE_DECAY === "true";
+
+// --- LA-1: Layer admission (tri-state, defaults to off) ---
+
+/**
+ * 资格层准入模式：默认检索是否只召回 durable 层（提炼结论），把 evidence
+ * （transcript 碎片）留给 deja / 显式溯源。
+ *
+ *   off      — 默认，完全不生效（现网行为不变）
+ *   observe  — 只计算并记录"会过滤掉什么"，返回结果不变（影子期）
+ *   on       — 真正过滤
+ */
+export const layerAdmission = (): "off" | "observe" | "on" => {
+  const v = process.env.RECALLNEST_LAYER_ADMISSION;
+  return v === "on" || v === "observe" ? v : "off";
+};
+
+/** durable 层命中数低于此值时回退到全量候选池，避免"宁缺毋滥"变成"什么都没有"。 */
+export const layerAdmissionMin = (): number => {
+  const n = Number(process.env.RECALLNEST_LAYER_ADMISSION_MIN);
+  return Number.isFinite(n) && n > 0 ? n : 3;
+};
+
+// --- String settings with `||` default (empty string falls through) ---
+
+export const dataDir = (): string => process.env.RECALLNEST_DATA_DIR || "data";
+
+export const mcpTier = (): "core" | "advanced" | "full" =>
+  (process.env.RECALLNEST_MCP_TIER || "advanced") as "core" | "advanced" | "full";
+
+// --- LanceDB read consistency (cross-process visibility) ---
+
+/**
+ * Read consistency interval (seconds) resolved for lancedb.connect().
+ * Without it a long-lived table handle pins its manifest version and never
+ * sees writes committed by other processes (CLI ingest vs resident MCP/API/UI
+ * servers). Explicit StoreConfig.readConsistencyInterval wins over this env.
+ *
+ * Unset / empty  → 0 (strong consistency: check for external commits per read)
+ * "off" | "none" → undefined (legacy unchecked-handle behavior, escape hatch)
+ * number ≥ 0     → bounded staleness window in seconds (invalid values → 0)
+ */
+export const readConsistencyInterval = (): number | undefined => {
+  const raw = process.env.RECALLNEST_READ_CONSISTENCY_INTERVAL;
+  if (raw === undefined || raw === "") return 0;
+  if (raw === "off" || raw === "none") return undefined;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+};
+
+// --- Raw env values (caller validates / clamps / falls back to config) ---
+
+export const recallModeRaw = (): string | undefined => process.env.RECALLNEST_RECALL_MODE;
+
+export const uiPortRaw = (): string | undefined => process.env.RECALLNEST_UI_PORT;
+
+export const apiPortRaw = (): string | undefined => process.env.RECALLNEST_API_PORT;

package/src/error-signature.ts

@@ -0,0 +1,153 @@
+/**
+ * A1 · Error-signature extractor — zero-LLM 结构化错误指纹（debug case 精确召回用）。
+ *
+ * 借鉴 MemOS local-plugin `core/capture/error-signature.ts`（repo-insight 审计 2026-06-13），
+ * 针对 RecallNest 本地化适配（Codex read-only 验证指出的三处不适配）：
+ *   - case 没有 toolCalls，错误指纹藏在 problem/context 自由文本里（MemOS 面向 tool output）
+ *   - 补裸 `X not found` / `No such file or directory` / 中文错误模式（MemOS 原 6 正则抽不到
+ *     裸的 `xmlsec1 not found`，也会被英文 alpha 检查滤掉中文）
+ *   - normaliseFragment 放宽长度/字母检查以保留中文短片段
+ *
+ * **读写对称**：纯函数。写入端（persistCaseMemory）抽指纹存 metadata.error_signature；
+ * 未来 P3-A 检索精确召回通道复用同一个 extractErrorSignatures，保证读写抽取规则一致。
+ * 零 LLM、确定性——每次 case 写入都跑，必须便宜。
+ */
+
+/** 每条 case 最多保留的指纹数（控制 hot-path 边界）。 */
+export const MAX_SIGNATURES = 4;
+const MIN_FRAGMENT_LEN = 6;
+const MAX_FRAGMENT_LEN = 160;
+
+/**
+ * verbatim 抽取模式——顺序即优先级，整段 match（m[0]）作为 fragment。
+ */
+const ERROR_PATTERNS: RegExp[] = [
+  // <Name>Error: / <Name>Exception: body
+  /\b([A-Z][A-Za-z0-9]*(?:Error|Exception)):\s*([^\n]{4,160})/g,
+  // error: / fatal: / ERROR: body
+  /\b(?:error|Error|fatal|FATAL|ERROR)\s*:\s*([^\n]{4,160})/g,
+  // <cmd>: ... not found / no such file / permission denied（带冒号）
+  /\b([A-Za-z0-9_\-./]+):\s*[^\n]{0,40}\b(not found|no such (?:file|directory)|permission denied|undefined reference|command not found)\b[^\n]*/g,
+  // 裸 <thing> [command] not found（无冒号——MemOS 原版抽不到 "xmlsec1 not found"）
+  /\b([A-Za-z0-9_.\-/]{2,60})\s+(?:command )?not found\b/gi,
+  // No such file or directory（独立出现）
+  /\bno such file or directory\b/gi,
+  // <thing> is required / must be / cannot / could not / failed to
+  /\b([A-Za-z0-9_]{3,40})\s+(is required|must be|cannot|could not|failed to)\s+[^\n]{3,120}/g,
+  // exit code / status N
+  /\bexit (?:code|status)\s*[:=]?\s*(\d{1,4})\b[^\n]{0,80}/g,
+  // HTTP 4xx/5xx + 标准状态短语（收紧：避免 "500 ms" / "404 rows" 这类裸数字误抽）
+  /\b(4\d\d|5\d\d)\s+(Bad Request|Unauthorized|Payment Required|Forbidden|Not Found|Method Not Allowed|Not Acceptable|Request Timeout|Conflict|Gone|Payload Too Large|Unprocessable Entity|Too Many Requests|Internal Server Error|Internal|Not Implemented|Bad Gateway|Service Unavailable|Gateway Timeout)\b/g,
+  // 中文错误现象 + 后续短语
+  /(找不到|没有找到|不存在|无法|没有权限|权限被拒|拒绝访问|命令不存在|没有那个文件|连接失败|连接超时|超时|崩溃|段错误|空指针|未定义|报错|异常|失败)[^\n]{0,24}/g,
+  // 中文 退出码/状态码/错误码/返回码 N
+  /(退出码|状态码|错误码|返回码)\s*[:=：]?\s*\d{1,4}/g,
+];
+
+const STOP_WORDS = new Set([
+  "the", "for", "this", "that", "your", "from", "with", "have", "has",
+  "not", "a", "an", "of", "to", "is", "in", "on", "by", "was", "were",
+]);
+
+/**
+ * 过泛中文错误词——单独出现（裸词 + 语气助词、无具体锚点）会在检索端过度匹配。
+ * 具体短语（找不到 / 权限被拒 / 连接失败 / 段错误 / 空指针）不在此列、照常保留。
+ * 已有 cjk<3 长度门挡掉 2 字裸词；本表治的是 3+ 字「裸词+助词」（失败了 / 超时了）。
+ */
+const GENERIC_CN_ERROR = /^(?:报错|出错|错误|异常|失败|超时|崩溃|无法|未定义|不能)[了的过着吧呢啊啦哦呀嘛。，！？!?,\s]*$/;
+
+/** 失败信号词——outcome/solutionSteps 仅在命中时才纳入语料（避免成功态反向噪声）。 */
+const FAILURE_HINT = /(error|fail|failed|failure|exception|not found|cannot|denied|timeout|拒绝|失败|报错|错误|异常|不能|无法|超时|崩溃)/i;
+
+export interface ExtractInput {
+  /** 主信号：case 的 problem 字段（"What problem happened"）。 */
+  problem: string;
+  /** case 的 context（原始 stderr / 触发条件常在此）。 */
+  context?: string;
+  /** case 的 outcome（解决后状态——偏成功态，仅含失败词时参与）。 */
+  outcome?: string;
+  /** solution 步骤（修复命令噪声多，仅含失败词时参与）。 */
+  solutionSteps?: string[];
+}
+
+/**
+ * 抽取至多 MAX_SIGNATURES 条规范化错误指纹，按 specificity 降序。
+ * problem + context 是主语料；outcome / solutionSteps 仅当包含失败词时纳入
+ * （outcome 多为成功态，否则会抽到 "exit code 0 / 不再报错" 这类反向信号）。
+ */
+export function extractErrorSignatures(input: ExtractInput): string[] {
+  const corpus: string[] = [input.problem];
+  if (input.context) corpus.push(input.context);
+  const tail = [input.outcome ?? "", ...(input.solutionSteps ?? [])].join("\n");
+  if (tail.trim() && FAILURE_HINT.test(tail)) corpus.push(tail);
+
+  // dedup by lowercased/collapsed key（重叠正则不产近似重复）；first-seen casing 胜出。
+  const candidates = new Map<string, { frag: string; freq: number }>();
+  for (const text of corpus) {
+    for (const frag of extractFragments(text)) {
+      const normalised = normaliseFragment(frag);
+      if (!normalised) continue;
+      const key = normalised.toLowerCase().replace(/\s+/g, " ");
+      const existing = candidates.get(key);
+      if (existing) existing.freq++;
+      else candidates.set(key, { frag: normalised, freq: 1 });
+    }
+  }
+
+  const scored = Array.from(candidates.values()).map(({ frag, freq }) => ({
+    frag,
+    score: specificityScore(frag, freq),
+  }));
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, MAX_SIGNATURES).map((s) => s.frag);
+}
+
+function extractFragments(text: string): string[] {
+  if (!text) return [];
+  const out: string[] = [];
+  for (const pattern of ERROR_PATTERNS) {
+    pattern.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    while ((m = pattern.exec(text))) {
+      out.push(m[0]);
+      if (m.index === pattern.lastIndex) pattern.lastIndex++; // 防零宽匹配死循环
+      if (out.length >= 32) break; // 每个 pattern 硬上限
+    }
+  }
+  return out;
+}
+
+function normaliseFragment(frag: string): string | null {
+  const collapsed = frag.replace(/\s+/g, " ").trim();
+  const cjk = collapsed.replace(/[^一-鿿]/g, "");
+  // 长度门：英文片段 ≥MIN_FRAGMENT_LEN，或中文 ≥3 字（中文短片段如"找不到文件"也保留）
+  if (collapsed.length < MIN_FRAGMENT_LEN && cjk.length < 3) return null;
+  const truncated = collapsed.length > MAX_FRAGMENT_LEN ? collapsed.slice(0, MAX_FRAGMENT_LEN) : collapsed;
+  // 信息量门：英文字母 ≥4 或 中文 ≥2 字（MemOS 原版只看 alpha≥4，会滤掉纯中文）
+  const alpha = truncated.replace(/[^A-Za-z]/g, "");
+  if (alpha.length < 4 && cjk.length < 2) return null;
+  // 纯英文停用词片段才拒；纯中文（words 为空）不走这条
+  const words = truncated.toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean);
+  if (words.length > 0 && words.every((w) => STOP_WORDS.has(w))) return null;
+  // P3-A 收紧：裸过泛中文词（报错/失败/超时…+语气助词）且无具体锚点（latin≥3 / 多位数字 / 路径）→ 拒，
+  // 避免检索端 error-signature 精确通道被这类词过度匹配成噪声。
+  const hasSpecificAnchor = /[A-Za-z]{3,}|\d{2,}|\//.test(truncated);
+  if (!hasSpecificAnchor && GENERIC_CN_ERROR.test(truncated)) return null;
+  return truncated;
+}
+
+/** specificity：不寻常 token（PascalCase Error / 路径 / 错误码 / 中文错误）得分更高。 */
+function specificityScore(frag: string, freq: number): number {
+  let score = 0;
+  if (/\b[A-Z][a-zA-Z]*Error\b/.test(frag)) score += 3;
+  if (/\b[A-Z][a-zA-Z]*Exception\b/.test(frag)) score += 3;
+  if (/(\b|_)E[A-Z]{3,}\b/.test(frag)) score += 2; // ENOENT, EACCES
+  if (/\/[a-zA-Z0-9._\-/]+/.test(frag)) score += 2; // path
+  if (/\bcode\s*=\s*\d+/.test(frag)) score += 1;
+  if (/\b\d{3}\b/.test(frag)) score += 1; // status
+  if (/_/.test(frag)) score += 1; // snake_case id
+  if (/[一-鿿]/.test(frag)) score += 1; // 中文错误片段值得保留
+  score += Math.min(2, freq - 1); // 重复片段小幅加权
+  if (frag.length > 120) score -= 1; // 过长片段降权
+  return score;
+}

package/src/error-taxonomy.ts

@@ -0,0 +1,115 @@
+/**
+ * MCP 错误分类学 — 借鉴 RepoPrompt CE 的 error taxonomy。
+ *
+ * 问题：RecallNest 43 个 MCP 工具的错误现在三种风格混着（fail-open 空结果 /
+ * 错误当正常 content / 局部 catch 返回文本），agent 拿到错误无法判断该重试、
+ * 改参数还是上报用户。
+ *
+ * 方案：给每种失败标三元组 {reasonCode, retryable, responsibility}，在 registerTool
+ * 外层统一兜底分类，返回带机器可读 block 的 isError result。
+ *
+ * 范围（第一阶段）：只兜底「抛到 handler 顶层、未被内部 catch」的错误。各 handler
+ * 内部的 fail-open / 文本错误风格统一是后续第二阶段，不在此处改（避免破坏客户端兼容）。
+ */
+
+/** 责任方：host=运行环境/配置，app=RecallNest 自身逻辑，peer=调用方输入或上游 API，transport=网络层。 */
+export type ErrorResponsibility = "host" | "app" | "peer" | "transport";
+
+export interface ErrorClassification {
+  /** 稳定错误码（机器可读，跨版本稳定，供 agent 分支判断）。 */
+  reasonCode: string;
+  /** 是否值得重试（transient vs permanent）。 */
+  retryable: boolean;
+  /** 责任方，决定 agent 是重试 / 改参数 / 上报用户。 */
+  responsibility: ErrorResponsibility;
+}
+
+/**
+ * 失败模式表：按 error message 模式分类。
+ * 未匹配 → internal_error / app / non-retryable（保守：不误导 agent 去重试一个未知错误）。
+ */
+export function classifyError(err: unknown): ErrorClassification {
+  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+
+  // transport：网络/连接层，可重试
+  if (/econnreset|etimedout|enotfound|econnrefused|socket|network|fetch failed|timed out|timeout/.test(msg)) {
+    return { reasonCode: "transport_error", retryable: true, responsibility: "transport" };
+  }
+  // 上游 API 过载/限流，可重试（退避后）
+  if (/rate.?limit|\b429\b|\b529\b|overloaded|too many requests|quota exceeded/.test(msg)) {
+    return { reasonCode: "upstream_overloaded", retryable: true, responsibility: "peer" };
+  }
+  // 上游 API 鉴权/密钥，不可重试（需修 host 配置）
+  if (/\b401\b|\b403\b|unauthorized|invalid api key|authentication failed|missing api key/.test(msg)) {
+    return { reasonCode: "upstream_auth", retryable: false, responsibility: "host" };
+  }
+  // 运行环境/配置缺失（host）：缺 env var、未配置（Codex 复审 P2-3，关联 lazy-init 失败 P2-1）
+  if (/environment variable .* not set|not configured|missing required (config|environment)/.test(msg)) {
+    return { reasonCode: "config_missing", retryable: false, responsibility: "host" };
+  }
+  // 调用方未给 scope（resolveScopeSelection 抛出）
+  if (/requires a scope|scope is required|pass scope/.test(msg)) {
+    return { reasonCode: "scope_required", retryable: false, responsibility: "peer" };
+  }
+  // 调用方给的 memory 引用无效：ID 格式错 / 前缀歧义 / 不在可访问 scope（Codex 复审 P2-3）。
+  // 指引 agent 给有效 ID / 更长前缀 / 正确 scope，而非误以为 RecallNest 内部故障。
+  if (/invalid memory id|ambiguous prefix|invalid .* id format|outside accessible scope|not accessible/.test(msg)) {
+    return { reasonCode: "invalid_memory_ref", retryable: false, responsibility: "peer" };
+  }
+  // 调用方输入非法（zod/validation）
+  if (/validation|invalid input|expected .* received|must be a|is required|not a valid|failed to parse/.test(msg)) {
+    return { reasonCode: "invalid_input", retryable: false, responsibility: "peer" };
+  }
+  // 存储层（LanceDB / 向量 / 索引）
+  if (/lancedb|database|\btable\b|vector ?search|embedding failed|index/.test(msg)) {
+    return { reasonCode: "store_error", retryable: false, responsibility: "app" };
+  }
+  // 默认：保守归为 app 内部错误，不可重试
+  return { reasonCode: "internal_error", retryable: false, responsibility: "app" };
+}
+
+/** MCP tool error content item 类型（与 handler 成功路径的 content 同构）。 */
+interface ErrorResult {
+  content: { type: "text"; text: string }[];
+  isError: true;
+}
+
+/**
+ * 把任意错误转成带机器可读分类 block 的 MCP isError result。
+ * agent 可解析 reason_code / retryable / responsibility 决定下一步。
+ */
+export function toErrorResult(toolName: string, err: unknown): ErrorResult {
+  const cls = classifyError(err);
+  const detail = err instanceof Error ? err.message : String(err);
+  return {
+    content: [{
+      type: "text",
+      text: [
+        `❌ Tool "${toolName}" failed`,
+        `reason_code: ${cls.reasonCode}`,
+        `retryable: ${cls.retryable}`,
+        `responsibility: ${cls.responsibility}`,
+        `detail: ${detail}`,
+      ].join("\n"),
+    }],
+    isError: true,
+  };
+}
+
+/**
+ * 安全执行 tool 逻辑：捕获任意抛错（含 lazy-init / handler 执行），分类 + 结构化
+ * stderr 日志 + 返回 isError result。提取成独立函数以便单测锁定回归（Codex 复审建议）。
+ * registerTool 的 lazyHandler 把「ensureComponents + handler 调用」整体交给它。
+ */
+export async function runToolSafely<T>(toolName: string, fn: () => Promise<T>): Promise<T | ErrorResult> {
+  try {
+    return await fn();
+  } catch (err) {
+    const cls = classifyError(err);
+    console.error(
+      `[recallnest] tool ${toolName} failed [${cls.reasonCode}/${cls.responsibility}/retryable=${cls.retryable}]:`,
+      err instanceof Error ? err.stack || err.message : String(err),
+    );
+    return toErrorResult(toolName, err);
+  }
+}