recallnest 2.2.1 → 2.5.4

package/src/__tests__/env-config.test.ts

@@ -0,0 +1,151 @@
+import { describe, expect, it, afterEach, beforeEach } from "bun:test";
+
+import * as envConfig from "../env-config.js";
+
+// Every RECALLNEST_* key this suite mutates. Snapshot + restore so we never leak
+// env state into sibling test files (the whole `bun test` run shares one process).
+const KEYS = [
+  "RECALLNEST_MULTI_VECTOR",
+  "RECALLNEST_EMOTION_SCORING",
+  "RECALLNEST_PREDICTIVE_MEMORY",
+  "RECALLNEST_SYNTHESIZE",
+  "RECALLNEST_LLM_CONSOLIDATION",
+  "RECALLNEST_CONSTRUCTIVE_RETRIEVAL",
+  "RECALLNEST_NARRATIVE_MODE",
+  "RECALLNEST_KG_MODE",
+  "RECALLNEST_CORE_SUMMARY",
+  "RECALLNEST_ERROR_SIGNATURE_BOOST",
+  "RECALLNEST_USAGE_DECAY",
+  "RECALLNEST_DATA_DIR",
+  "RECALLNEST_MCP_TIER",
+  "RECALLNEST_RECALL_MODE",
+  "RECALLNEST_UI_PORT",
+  "RECALLNEST_API_PORT",
+];
+
+const saved: Record<string, string | undefined> = {};
+
+beforeEach(() => {
+  for (const key of KEYS) {
+    saved[key] = process.env[key];
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  for (const key of KEYS) {
+    if (saved[key] === undefined) delete process.env[key];
+    else process.env[key] = saved[key];
+  }
+});
+
+describe('env-config boolean flags — strict === "true"', () => {
+  const accessors: Array<[string, () => boolean, string]> = [
+    ["multiVector", envConfig.multiVector, "RECALLNEST_MULTI_VECTOR"],
+    ["emotionScoring", envConfig.emotionScoring, "RECALLNEST_EMOTION_SCORING"],
+    ["predictiveMemory", envConfig.predictiveMemory, "RECALLNEST_PREDICTIVE_MEMORY"],
+    ["synthesize", envConfig.synthesize, "RECALLNEST_SYNTHESIZE"],
+    ["llmConsolidation", envConfig.llmConsolidation, "RECALLNEST_LLM_CONSOLIDATION"],
+    ["constructiveRetrieval", envConfig.constructiveRetrieval, "RECALLNEST_CONSTRUCTIVE_RETRIEVAL"],
+    ["narrativeMode", envConfig.narrativeMode, "RECALLNEST_NARRATIVE_MODE"],
+    ["kgMode", envConfig.kgMode, "RECALLNEST_KG_MODE"],
+    ["coreSummary", envConfig.coreSummary, "RECALLNEST_CORE_SUMMARY"],
+    ["errorSignatureBoost", envConfig.errorSignatureBoost, "RECALLNEST_ERROR_SIGNATURE_BOOST"],
+    ["usageDecay", envConfig.usageDecay, "RECALLNEST_USAGE_DECAY"],
+  ];
+
+  for (const [name, accessor, key] of accessors) {
+    it(`${name}: false unless the value is exactly "true"`, () => {
+      delete process.env[key];
+      expect(accessor()).toBe(false);
+
+      process.env[key] = "true";
+      expect(accessor()).toBe(true);
+
+      // No trim, no case-folding, no truthy coercion — only the literal "true".
+      for (const fuzzy of ["True", "TRUE", " true ", "1", "yes", "false", ""]) {
+        process.env[key] = fuzzy;
+        expect(accessor()).toBe(false);
+      }
+    });
+  }
+});
+
+describe("env-config string settings — || default (empty string falls through)", () => {
+  it('dataDir defaults to "data" when unset or empty', () => {
+    delete process.env.RECALLNEST_DATA_DIR;
+    expect(envConfig.dataDir()).toBe("data");
+
+    process.env.RECALLNEST_DATA_DIR = ""; // || not ??
+    expect(envConfig.dataDir()).toBe("data");
+
+    process.env.RECALLNEST_DATA_DIR = "/tmp/custom-data";
+    expect(envConfig.dataDir()).toBe("/tmp/custom-data");
+  });
+
+  it('mcpTier defaults to "advanced"; valid passes through; illegal value kept verbatim', () => {
+    delete process.env.RECALLNEST_MCP_TIER;
+    expect(envConfig.mcpTier()).toBe("advanced");
+
+    process.env.RECALLNEST_MCP_TIER = ""; // || not ??
+    expect(envConfig.mcpTier()).toBe("advanced");
+
+    process.env.RECALLNEST_MCP_TIER = "core";
+    expect(envConfig.mcpTier()).toBe("core");
+
+    // No runtime validation — an unknown non-empty value is preserved as-is
+    // (downstream shouldRegisterTool relies on this; do not coerce to default).
+    process.env.RECALLNEST_MCP_TIER = "garbage";
+    expect(envConfig.mcpTier()).toBe("garbage");
+  });
+});
+
+describe("env-config raw passthrough — caller validates / clamps / falls back", () => {
+  const rawAccessors: Array<[string, () => string | undefined, string]> = [
+    ["recallModeRaw", envConfig.recallModeRaw, "RECALLNEST_RECALL_MODE"],
+    ["uiPortRaw", envConfig.uiPortRaw, "RECALLNEST_UI_PORT"],
+    ["apiPortRaw", envConfig.apiPortRaw, "RECALLNEST_API_PORT"],
+  ];
+
+  for (const [name, accessor, key] of rawAccessors) {
+    it(`${name}: returns the raw env value, undefined when unset`, () => {
+      delete process.env[key];
+      expect(accessor()).toBeUndefined();
+
+      process.env[key] = "verbatim-123";
+      expect(accessor()).toBe("verbatim-123");
+
+      // Raw passthrough: empty string is NOT defaulted here — the caller decides.
+      process.env[key] = "";
+      expect(accessor()).toBe("");
+    });
+  }
+});
+
+describe("env-config recallModeRaw — must not pre-default (preserves resolveRecallMode config fallback)", () => {
+  it('returns the raw value or undefined, never a hardcoded mode like "summary"', () => {
+    delete process.env.RECALLNEST_RECALL_MODE;
+    // Must be undefined, NOT "summary" — resolveRecallMode owns the config fallback.
+    expect(envConfig.recallModeRaw()).toBeUndefined();
+
+    process.env.RECALLNEST_RECALL_MODE = "light";
+    expect(envConfig.recallModeRaw()).toBe("light");
+
+    // Invalid modes pass through verbatim — the whitelist check lives in resolveRecallMode.
+    process.env.RECALLNEST_RECALL_MODE = "bogus";
+    expect(envConfig.recallModeRaw()).toBe("bogus");
+  });
+});
+
+describe("env-config accessors are lazy (read at call time, never frozen)", () => {
+  it("reflect runtime mutation rather than a module-load snapshot", () => {
+    delete process.env.RECALLNEST_EMOTION_SCORING;
+    expect(envConfig.emotionScoring()).toBe(false);
+
+    process.env.RECALLNEST_EMOTION_SCORING = "true";
+    expect(envConfig.emotionScoring()).toBe(true); // would fail if cached at import
+
+    delete process.env.RECALLNEST_EMOTION_SCORING;
+    expect(envConfig.emotionScoring()).toBe(false);
+  });
+});

package/src/__tests__/error-signature-boost.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, afterEach, beforeEach } from "bun:test";
+
+import { applyErrorSignatureBoost } from "../retriever.js";
+import type { RetrievalResult } from "../retriever.js";
+import { extractErrorSignatures } from "../error-signature.js";
+
+const FLAG = "RECALLNEST_ERROR_SIGNATURE_BOOST";
+
+function makeResult(opts: { category: string; score: number; sigs?: string[] }): RetrievalResult {
+  const metadata = opts.sigs ? JSON.stringify({ error_signature: opts.sigs }) : "{}";
+  return {
+    entry: {
+      id: "m1",
+      text: "x",
+      scope: "test",
+      category: opts.category,
+      timestamp: "2026-06-13T00:00:00.000Z",
+      metadata,
+    },
+    score: opts.score,
+    sources: {},
+  } as unknown as RetrievalResult;
+}
+
+let saved: string | undefined;
+beforeEach(() => {
+  saved = process.env[FLAG];
+  delete process.env[FLAG];
+});
+afterEach(() => {
+  if (saved === undefined) delete process.env[FLAG];
+  else process.env[FLAG] = saved;
+});
+
+describe("applyErrorSignatureBoost — A1 检索端精确召回 boost", () => {
+  const QUERY = "build broke: xmlsec1 not found";
+  const matchingSig = () => extractErrorSignatures({ problem: QUERY })[0];
+
+  it("flag off（默认）→ 原样返回同一引用、分数不变", () => {
+    const input = [makeResult({ category: "cases", score: 0.4, sigs: [matchingSig()] })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out).toBe(input); // no-op，bit-identical
+    expect(out[0].score).toBe(0.4);
+  });
+
+  it("flag on + 指纹命中 case → 乘法 boost (×1.5)", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "cases", score: 0.4, sigs: [matchingSig()] })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out[0].score).toBeCloseTo(0.6, 6); // 0.4 * 1.5
+  });
+
+  it("flag on + 命中但高分 → clamp 到 1、不溢出", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "cases", score: 0.8, sigs: [matchingSig()] })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out[0].score).toBe(1); // 0.8 * 1.5 = 1.2 → clamp 1
+  });
+
+  it("flag on + 非 case category（patterns）→ 不 boost", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "patterns", score: 0.4, sigs: [matchingSig()] })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out[0].score).toBe(0.4);
+  });
+
+  it("flag on + case 但指纹不重叠 → 不 boost", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "cases", score: 0.4, sigs: ["zzz_nonexistent_signature_xyz"] })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out[0].score).toBe(0.4);
+  });
+
+  it("flag on + case 无 error_signature metadata → 不 boost", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "cases", score: 0.4 })];
+    const out = applyErrorSignatureBoost(input, QUERY);
+    expect(out[0].score).toBe(0.4);
+  });
+
+  it("flag on + query 抽不出错误指纹 → 原样返回同一引用", () => {
+    process.env[FLAG] = "true";
+    const input = [makeResult({ category: "cases", score: 0.4, sigs: [matchingSig()] })];
+    const out = applyErrorSignatureBoost(input, "今天天气不错，喝杯咖啡");
+    expect(out).toBe(input);
+  });
+});

package/src/__tests__/error-signature.test.ts

@@ -0,0 +1,95 @@
+import { describe, test, expect } from "bun:test";
+import { extractErrorSignatures, MAX_SIGNATURES } from "../error-signature.js";
+
+describe("extractErrorSignatures — English patterns", () => {
+  test("bare 'X not found' (no colon) is extracted — MemOS 原 6 正则会漏", () => {
+    const sigs = extractErrorSignatures({ problem: "Build broke: xmlsec1 not found" });
+    expect(sigs.some(s => s.includes("xmlsec1 not found"))).toBe(true);
+  });
+
+  test("'exit code N' is extracted", () => {
+    const sigs = extractErrorSignatures({ problem: "Deploy failed with exit code 1" });
+    expect(sigs.some(s => s.includes("exit code 1"))).toBe(true);
+  });
+
+  test("'<Name>Error: body' extracted and ranks top by specificity", () => {
+    const sigs = extractErrorSignatures({ problem: "NameError: name foo is not defined" });
+    expect(sigs.some(s => s.includes("NameError"))).toBe(true);
+    expect(sigs[0]).toContain("NameError");
+  });
+
+  test("'No such file or directory' standalone is extracted (case-insensitive)", () => {
+    const sigs = extractErrorSignatures({ problem: "open config: No such file or directory" });
+    expect(sigs.some(s => /No such file or directory/i.test(s))).toBe(true);
+  });
+
+  test("bare 3-digit numbers in benign text do NOT false-match as HTTP error", () => {
+    const sigs = extractErrorSignatures({ problem: "deployed 500 records and processed 404 rows in the weekly batch" });
+    expect(sigs.some(s => s.includes("500 records") || s.includes("404 rows"))).toBe(false);
+  });
+
+  test("real HTTP status phrase is still extracted after tightening", () => {
+    const sigs = extractErrorSignatures({ problem: "API call returned 500 Internal Server Error on submit" });
+    expect(sigs.some(s => s.includes("500 Internal"))).toBe(true);
+  });
+});
+
+describe("extractErrorSignatures — Chinese (MemOS 原版会被 alpha 检查滤掉)", () => {
+  test("中文错误现象被抽取", () => {
+    const sigs = extractErrorSignatures({ problem: "部署时权限被拒绝，找不到文件" });
+    expect(sigs.some(s => s.includes("找不到") || s.includes("权限被拒"))).toBe(true);
+  });
+
+  test("中文短片段（<6 字符但 ≥3 中文字）保留", () => {
+    const sigs = extractErrorSignatures({ problem: "找不到模块" });
+    expect(sigs.length).toBeGreaterThan(0);
+  });
+});
+
+describe("extractErrorSignatures — input gating", () => {
+  test("outcome 成功态（无失败词）不被纳入，不抽反向信号", () => {
+    const sigs = extractErrorSignatures({
+      problem: "ImportError: no module named requests",
+      outcome: "exit code 0 部署成功",
+    });
+    expect(sigs.some(s => s.includes("ImportError"))).toBe(true);
+    expect(sigs.some(s => s.includes("exit code 0"))).toBe(false);
+  });
+
+  test("context 参与抽取（原始 stderr 常在 context）", () => {
+    const sigs = extractErrorSignatures({
+      problem: "服务起不来",
+      context: "stderr: pg_config: command not found",
+    });
+    expect(sigs.some(s => s.includes("pg_config") || s.includes("command not found"))).toBe(true);
+  });
+
+  test("结果不超过 MAX_SIGNATURES 条", () => {
+    const sigs = extractErrorSignatures({
+      problem: "NameError: a. TypeError: b. ValueError: c. KeyError: d. exit code 1. 404 Not Found. 权限被拒绝.",
+    });
+    expect(sigs.length).toBeLessThanOrEqual(MAX_SIGNATURES);
+  });
+});
+
+describe("extractErrorSignatures — 过泛中文词收紧（P3-A 检索端噪声治理）", () => {
+  const BARE_GENERIC = /^(?:报错|出错|错误|异常|失败|超时|崩溃|无法|未定义|不能)[了的过着吧呢啊啦哦呀嘛。，！？!?,\s]*$/;
+
+  test("裸过泛词 + 语气助词不被抽成指纹（失败了 / 超时了 / 崩溃了 / 报错了）", () => {
+    for (const bare of ["部署失败了", "请求超时了", "程序崩溃了", "系统报错了"]) {
+      const sigs = extractErrorSignatures({ problem: bare });
+      expect(sigs.some(s => BARE_GENERIC.test(s.trim()))).toBe(false);
+    }
+  });
+
+  test("过泛词带具体锚点（英文 / 路径 / 多位数字）时保留", () => {
+    const sigs = extractErrorSignatures({ problem: "操作失败：xmlsec1 not found" });
+    expect(sigs.some(s => s.includes("xmlsec1"))).toBe(true);
+  });
+
+  test("具体中文短语不受收紧影响（找不到 / 权限被拒 / 连接失败）", () => {
+    expect(extractErrorSignatures({ problem: "找不到模块" }).length).toBeGreaterThan(0);
+    expect(extractErrorSignatures({ problem: "权限被拒绝" }).some(s => s.includes("权限被拒"))).toBe(true);
+    expect(extractErrorSignatures({ problem: "数据库连接失败" }).some(s => s.includes("连接失败"))).toBe(true);
+  });
+});

package/src/__tests__/error-taxonomy.test.ts

@@ -0,0 +1,129 @@
+import { describe, expect, it } from "bun:test";
+
+import { classifyError, toErrorResult, runToolSafely } from "../error-taxonomy.js";
+
+// P-error-taxonomy: 借鉴 RepoPrompt CE 的 error taxonomy。
+// 每种失败标 {reasonCode, retryable, responsibility}，让 agent 判断重试/改参/上报。
+
+describe("classifyError", () => {
+  it("classifies transport errors as retryable / transport", () => {
+    for (const m of ["ECONNRESET", "socket hang up", "fetch failed", "request timed out", "ETIMEDOUT"]) {
+      const c = classifyError(new Error(m));
+      expect(c.reasonCode).toBe("transport_error");
+      expect(c.retryable).toBe(true);
+      expect(c.responsibility).toBe("transport");
+    }
+  });
+
+  it("classifies rate-limit / overload as retryable / peer", () => {
+    for (const m of ["429 Too Many Requests", "rate limit exceeded", "529 overloaded", "quota exceeded"]) {
+      const c = classifyError(new Error(m));
+      expect(c.reasonCode).toBe("upstream_overloaded");
+      expect(c.retryable).toBe(true);
+      expect(c.responsibility).toBe("peer");
+    }
+  });
+
+  it("classifies auth failures as non-retryable / host", () => {
+    const c = classifyError(new Error("401 Unauthorized: invalid api key"));
+    expect(c.reasonCode).toBe("upstream_auth");
+    expect(c.retryable).toBe(false);
+    expect(c.responsibility).toBe("host");
+  });
+
+  it("classifies missing-scope as non-retryable / peer", () => {
+    const c = classifyError(new Error("search_memory requires a scope. Pass scope explicitly, provide sessionId..."));
+    expect(c.reasonCode).toBe("scope_required");
+    expect(c.retryable).toBe(false);
+    expect(c.responsibility).toBe("peer");
+  });
+
+  it("classifies validation errors as invalid_input / peer", () => {
+    const c = classifyError(new Error("validation failed: expected string received number"));
+    expect(c.reasonCode).toBe("invalid_input");
+    expect(c.responsibility).toBe("peer");
+  });
+
+  it("classifies store errors as app", () => {
+    const c = classifyError(new Error("LanceDB table not found"));
+    expect(c.reasonCode).toBe("store_error");
+    expect(c.responsibility).toBe("app");
+  });
+
+  it("classifies config/env-missing as non-retryable / host (P2-1/P2-3)", () => {
+    const c = classifyError(new Error("Environment variable OPENAI_API_KEY not set"));
+    expect(c.reasonCode).toBe("config_missing");
+    expect(c.retryable).toBe(false);
+    expect(c.responsibility).toBe("host");
+  });
+
+  it("classifies bad memory references as invalid_memory_ref / peer — caller-side (P2-3)", () => {
+    for (const m of [
+      "Invalid memory ID format: bad",
+      'Ambiguous prefix "12345678" matches 2+ memories. Use a longer prefix or full ID.',
+      "Memory 12345678 is outside accessible scopes",
+    ]) {
+      const c = classifyError(new Error(m));
+      expect(c.reasonCode).toBe("invalid_memory_ref");
+      expect(c.responsibility).toBe("peer");
+    }
+  });
+
+  it("falls back to internal_error / app / non-retryable for unknown errors", () => {
+    const c = classifyError(new Error("something totally unexpected happened"));
+    expect(c.reasonCode).toBe("internal_error");
+    expect(c.retryable).toBe(false);
+    expect(c.responsibility).toBe("app");
+  });
+
+  it("handles non-Error throwables", () => {
+    const c = classifyError("plain string failure");
+    expect(c.reasonCode).toBe("internal_error");
+    expect(c.responsibility).toBe("app");
+  });
+});
+
+describe("toErrorResult", () => {
+  it("produces an isError result with a machine-readable classification block", () => {
+    const r = toErrorResult("search_memory", new Error("ECONNRESET"));
+    expect(r.isError).toBe(true);
+    expect(r.content[0].type).toBe("text");
+    const text = r.content[0].text;
+    expect(text).toContain('Tool "search_memory" failed');
+    expect(text).toContain("reason_code: transport_error");
+    expect(text).toContain("retryable: true");
+    expect(text).toContain("responsibility: transport");
+    expect(text).toContain("detail: ECONNRESET");
+  });
+
+  it("preserves the original detail for unknown errors", () => {
+    const r = toErrorResult("forget_memory", new Error("boom"));
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("reason_code: internal_error");
+    expect(r.content[0].text).toContain("detail: boom");
+  });
+});
+
+describe("runToolSafely", () => {
+  it("returns handler result on success (pass-through)", async () => {
+    const ok = { content: [{ type: "text", text: "ok" }] };
+    const r = await runToolSafely("search_memory", async () => ok);
+    expect(r).toEqual(ok);
+  });
+
+  it("catches handler throw and returns a classified isError result", async () => {
+    const r = await runToolSafely("search_memory", async () => { throw new Error("ECONNRESET"); }) as { isError: boolean; content: { text: string }[] };
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("reason_code: transport_error");
+  });
+
+  it("catches lazy-init failure and classifies it (P2-1 regression lock)", async () => {
+    // 模拟 ensureComponents 抛错（缺 env var）——必须被分类返回 isError，而非裸抛绕过。
+    const r = await runToolSafely("store_memory", async () => {
+      throw new Error("Environment variable JINA_API_KEY not set");
+    }) as { isError: boolean; content: { text: string }[] };
+    expect(r.isError).toBe(true);
+    expect(r.content[0].text).toContain("reason_code: config_missing");
+    expect(r.content[0].text).toContain("responsibility: host");
+  });
+});