recallnest 2.6.1 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (207) hide show
  1. package/CHANGELOG.md +292 -0
  2. package/README.md +280 -195
  3. package/README_CN.md +266 -199
  4. package/config.json.example +8 -1
  5. package/docs/api-reference.md +1 -1
  6. package/integrations/README.md +1 -1
  7. package/integrations/agy/README.md +73 -0
  8. package/integrations/agy/setup.sh +75 -0
  9. package/integrations/setup-all.sh +1 -1
  10. package/package.json +7 -5
  11. package/src/access-tracker.ts +10 -1
  12. package/src/activity-counter.ts +69 -11
  13. package/src/age-label.ts +29 -0
  14. package/src/audit-log.ts +35 -0
  15. package/src/auto-gc.ts +97 -30
  16. package/src/capture-engine.ts +26 -4
  17. package/src/cli.ts +224 -10
  18. package/src/consolidation-engine.ts +317 -123
  19. package/src/context-composer-stable.ts +5 -1
  20. package/src/data-checkup.ts +17 -3
  21. package/src/dream-pipeline.ts +90 -12
  22. package/src/embedder.ts +44 -5
  23. package/src/env-config.ts +71 -0
  24. package/src/forget-engine.ts +8 -2
  25. package/src/gateway-server.ts +272 -0
  26. package/src/ingest.ts +248 -22
  27. package/src/kg-extractor.ts +17 -0
  28. package/src/llm-client.ts +86 -25
  29. package/src/mcp-server.ts +2 -1
  30. package/src/mcp-tools-advanced.ts +7 -2
  31. package/src/mcp-tools-core.ts +11 -1
  32. package/src/mcp-tools-governance.ts +45 -3
  33. package/src/memory-evolution.ts +16 -0
  34. package/src/memory-output.ts +47 -8
  35. package/src/memory-promotion.ts +280 -0
  36. package/src/memory-store-port.ts +32 -3
  37. package/src/memory-utility.ts +314 -0
  38. package/src/pivot-apply.ts +52 -1
  39. package/src/pivot-evidence.ts +128 -0
  40. package/src/ppr-traversal.ts +25 -1
  41. package/src/recall-ledger.ts +76 -0
  42. package/src/retriever.ts +82 -9
  43. package/src/runtime-config.ts +9 -0
  44. package/src/scope-policy.ts +22 -1
  45. package/src/session-engine.ts +11 -4
  46. package/src/session-output.ts +13 -4
  47. package/src/session-store.ts +2 -3
  48. package/src/skill-promotion.ts +218 -1
  49. package/src/store.ts +231 -71
  50. package/src/synthesis-contract.ts +286 -0
  51. package/src/version-manager.ts +83 -0
  52. package/src/workflow-observation-schema.ts +26 -0
  53. package/integrations/gemini-cli/README.md +0 -57
  54. package/integrations/gemini-cli/setup.sh +0 -64
  55. package/src/__tests__/access-tracker-novelty.test.ts +0 -304
  56. package/src/__tests__/activity-counter.test.ts +0 -125
  57. package/src/__tests__/adaptive-fidelity.test.ts +0 -102
  58. package/src/__tests__/admission-control.test.ts +0 -206
  59. package/src/__tests__/anchor-generator.test.ts +0 -67
  60. package/src/__tests__/api-server-security.test.ts +0 -102
  61. package/src/__tests__/auto-consolidation.test.ts +0 -168
  62. package/src/__tests__/auto-recall.test.ts +0 -131
  63. package/src/__tests__/babel-integration.test.ts +0 -144
  64. package/src/__tests__/batch-dedup.test.ts +0 -65
  65. package/src/__tests__/belief-history.test.ts +0 -220
  66. package/src/__tests__/canary-eval.test.ts +0 -114
  67. package/src/__tests__/capture-engine.test.ts +0 -1328
  68. package/src/__tests__/capture-heuristic.test.ts +0 -171
  69. package/src/__tests__/cascade-forget.test.ts +0 -210
  70. package/src/__tests__/category-min-scores.test.ts +0 -116
  71. package/src/__tests__/cc8-cc1-essential-context.test.ts +0 -298
  72. package/src/__tests__/circuit-breaker.test.ts +0 -99
  73. package/src/__tests__/cluster-consolidation.test.ts +0 -945
  74. package/src/__tests__/confidence-metadata.test.ts +0 -125
  75. package/src/__tests__/confidence-tracker.test.ts +0 -261
  76. package/src/__tests__/conflict-advisor.test.ts +0 -206
  77. package/src/__tests__/conflict-escalation.test.ts +0 -149
  78. package/src/__tests__/conflict-lifecycle.test.ts +0 -83
  79. package/src/__tests__/conflict-output.test.ts +0 -85
  80. package/src/__tests__/conflict-store.test.ts +0 -418
  81. package/src/__tests__/connector-v1.test.ts +0 -181
  82. package/src/__tests__/consolidation-engine.test.ts +0 -430
  83. package/src/__tests__/constructive-retrieval.test.ts +0 -509
  84. package/src/__tests__/context-collapse-renderer.test.ts +0 -214
  85. package/src/__tests__/context-composer-pins.test.ts +0 -64
  86. package/src/__tests__/context-composer-task-selection.test.ts +0 -24
  87. package/src/__tests__/context-reconstructor.test.ts +0 -65
  88. package/src/__tests__/context-renderer.test.ts +0 -91
  89. package/src/__tests__/continuity-eval.test.ts +0 -275
  90. package/src/__tests__/continuity-schema.test.ts +0 -97
  91. package/src/__tests__/contracts.test.ts +0 -262
  92. package/src/__tests__/conversation-importer.test.ts +0 -692
  93. package/src/__tests__/core-recall-eval.test.ts +0 -235
  94. package/src/__tests__/core-summary.test.ts +0 -109
  95. package/src/__tests__/data-checkup.test.ts +0 -276
  96. package/src/__tests__/decay-exemption.test.ts +0 -129
  97. package/src/__tests__/dedup-actions.test.ts +0 -58
  98. package/src/__tests__/dedup-guard.test.ts +0 -39
  99. package/src/__tests__/deterministic-id.test.ts +0 -39
  100. package/src/__tests__/distill-lock.test.ts +0 -305
  101. package/src/__tests__/distill-session-argshape.test.ts +0 -79
  102. package/src/__tests__/doctor.test.ts +0 -319
  103. package/src/__tests__/dream-pipeline.test.ts +0 -780
  104. package/src/__tests__/drill-down.test.ts +0 -108
  105. package/src/__tests__/embedder.test.ts +0 -122
  106. package/src/__tests__/emotion-decay.test.ts +0 -46
  107. package/src/__tests__/emotion-detector.test.ts +0 -56
  108. package/src/__tests__/emotion-phase1-integration.test.ts +0 -153
  109. package/src/__tests__/emotion-retrieval.test.ts +0 -56
  110. package/src/__tests__/entity-resolver.test.ts +0 -58
  111. package/src/__tests__/env-config.test.ts +0 -151
  112. package/src/__tests__/error-signature-boost.test.ts +0 -87
  113. package/src/__tests__/error-signature.test.ts +0 -95
  114. package/src/__tests__/error-taxonomy.test.ts +0 -129
  115. package/src/__tests__/ethics-layer.test.ts +0 -476
  116. package/src/__tests__/event-segmenter.test.ts +0 -153
  117. package/src/__tests__/feature-flags-integration.test.ts +0 -54
  118. package/src/__tests__/frequency-tracker.test.ts +0 -113
  119. package/src/__tests__/freshness.test.ts +0 -186
  120. package/src/__tests__/graph-export.test.ts +0 -489
  121. package/src/__tests__/hotness-blend.test.ts +0 -283
  122. package/src/__tests__/ingest-chunking.test.ts +0 -44
  123. package/src/__tests__/ingest.test.ts +0 -360
  124. package/src/__tests__/interference-detector.test.ts +0 -203
  125. package/src/__tests__/kg-extractor.test.ts +0 -192
  126. package/src/__tests__/kg-store.test.ts +0 -300
  127. package/src/__tests__/llm-client-pivot.test.ts +0 -628
  128. package/src/__tests__/llm-consolidation.test.ts +0 -226
  129. package/src/__tests__/maintenance-locks.test.ts +0 -189
  130. package/src/__tests__/mcp-efficiency.test.ts +0 -288
  131. package/src/__tests__/mcp-related-scopes.test.ts +0 -151
  132. package/src/__tests__/memory-boundaries.test.ts +0 -282
  133. package/src/__tests__/memory-evolution-b2-b3-e1.test.ts +0 -345
  134. package/src/__tests__/memory-evolution.test.ts +0 -271
  135. package/src/__tests__/memory-health-rebalance.test.ts +0 -144
  136. package/src/__tests__/memory-lint.test.ts +0 -421
  137. package/src/__tests__/memory-output.test.ts +0 -215
  138. package/src/__tests__/memory-promotion.test.ts +0 -315
  139. package/src/__tests__/migrate-dedup-ids.test.ts +0 -65
  140. package/src/__tests__/multi-vector.test.ts +0 -242
  141. package/src/__tests__/narrative-architecture.test.ts +0 -456
  142. package/src/__tests__/noise-filter.test.ts +0 -205
  143. package/src/__tests__/noise-prototype-bank.test.ts +0 -280
  144. package/src/__tests__/obsidian-connector.test.ts +0 -363
  145. package/src/__tests__/omitted-reporting.test.ts +0 -98
  146. package/src/__tests__/pending-review.test.ts +0 -77
  147. package/src/__tests__/pii-redact.test.ts +0 -333
  148. package/src/__tests__/pivot-apply.test.ts +0 -373
  149. package/src/__tests__/pivot-distill-supervisor.test.ts +0 -457
  150. package/src/__tests__/pivot-distill.test.ts +0 -1178
  151. package/src/__tests__/post-retrieval-filter.test.ts +0 -178
  152. package/src/__tests__/ppr-traversal.test.ts +0 -256
  153. package/src/__tests__/prediction-engine.test.ts +0 -349
  154. package/src/__tests__/predictive-prospective-memory.test.ts +0 -416
  155. package/src/__tests__/preference-guard-smoke.test.ts +0 -211
  156. package/src/__tests__/preference-matcher.test.ts +0 -282
  157. package/src/__tests__/preference-slots.test.ts +0 -205
  158. package/src/__tests__/prospective-memory.test.ts +0 -283
  159. package/src/__tests__/pull-from-macbook-sync-only.test.ts +0 -679
  160. package/src/__tests__/query-entity-detector.test.ts +0 -171
  161. package/src/__tests__/query-expander-alias.test.ts +0 -146
  162. package/src/__tests__/query-expander.test.ts +0 -34
  163. package/src/__tests__/recall-gate.test.ts +0 -266
  164. package/src/__tests__/recall-governor.test.ts +0 -227
  165. package/src/__tests__/recall-mode.test.ts +0 -64
  166. package/src/__tests__/resolve-db-path.test.ts +0 -130
  167. package/src/__tests__/resolve-tier.test.ts +0 -64
  168. package/src/__tests__/result-synthesizer.test.ts +0 -198
  169. package/src/__tests__/resume-context.test.ts +0 -4898
  170. package/src/__tests__/retrieval-eval.test.ts +0 -163
  171. package/src/__tests__/retrieval-trace.test.ts +0 -213
  172. package/src/__tests__/retriever-boundary-weight.test.ts +0 -136
  173. package/src/__tests__/retriever-lazy-init-dispatch.test.ts +0 -123
  174. package/src/__tests__/retroactive-boost.test.ts +0 -223
  175. package/src/__tests__/salience-scoring.test.ts +0 -106
  176. package/src/__tests__/scope-inventory.test.ts +0 -200
  177. package/src/__tests__/scope-policy.test.ts +0 -69
  178. package/src/__tests__/scope-suggester.test.ts +0 -80
  179. package/src/__tests__/session-checkpoint.test.ts +0 -291
  180. package/src/__tests__/session-distiller.test.ts +0 -640
  181. package/src/__tests__/session-gc.test.ts +0 -215
  182. package/src/__tests__/skill-engine.test.ts +0 -552
  183. package/src/__tests__/skill-promotion.test.ts +0 -654
  184. package/src/__tests__/skill-verifier.test.ts +0 -122
  185. package/src/__tests__/source-heartbeat.test.ts +0 -250
  186. package/src/__tests__/stable-context-length-contract.test.ts +0 -62
  187. package/src/__tests__/store-patch-metadata.test.ts +0 -205
  188. package/src/__tests__/store-read-consistency.test.ts +0 -122
  189. package/src/__tests__/store-schema-migration.test.ts +0 -87
  190. package/src/__tests__/store-scope-audit.test.ts +0 -81
  191. package/src/__tests__/store-upsert.test.ts +0 -201
  192. package/src/__tests__/supersede-chain.test.ts +0 -154
  193. package/src/__tests__/temporal-parser.test.ts +0 -241
  194. package/src/__tests__/temporal-validity.test.ts +0 -160
  195. package/src/__tests__/term-registry-terminal-roster.test.ts +0 -127
  196. package/src/__tests__/term-registry.test.ts +0 -121
  197. package/src/__tests__/tool-error-surfacing.test.ts +0 -98
  198. package/src/__tests__/tool-output-compressor.test.ts +0 -160
  199. package/src/__tests__/topic-tag.test.ts +0 -113
  200. package/src/__tests__/trusted-memory.test.ts +0 -839
  201. package/src/__tests__/ui-server-security.test.ts +0 -93
  202. package/src/__tests__/usage-tracker.test.ts +0 -287
  203. package/src/__tests__/version-manager.test.ts +0 -213
  204. package/src/__tests__/workflow-observation-skill-outcome.test.ts +0 -352
  205. package/src/__tests__/workflow-observation.test.ts +0 -433
  206. package/src/__tests__/write-verifier.test.ts +0 -122
  207. /package/integrations/{gemini-cli/gemini-md-snippet.md → agy/agy-md-snippet.md} +0 -0
@@ -1,129 +0,0 @@
1
- import { describe, it, expect } from "bun:test";
2
- import { isDecayExempt } from "../decay-engine.js";
3
-
4
- describe("HP-7: Decay exemption rules", () => {
5
- describe("Rule 1: core tier + importance ≥ 0.95", () => {
6
- it("exempts explicit core with high importance", () => {
7
- const meta = JSON.stringify({ tier: "core", importance: 0.95 });
8
- expect(isDecayExempt(meta, 0.95)).toBe(true);
9
- });
10
-
11
- it("exempts inferred core (importance ≥ 0.95)", () => {
12
- const meta = JSON.stringify({ importance: 0.96 });
13
- expect(isDecayExempt(meta, 0.96)).toBe(true);
14
- });
15
-
16
- it("does NOT exempt core with importance < 0.95", () => {
17
- const meta = JSON.stringify({ tier: "core", importance: 0.90 });
18
- expect(isDecayExempt(meta, 0.90)).toBe(false);
19
- });
20
-
21
- it("does NOT exempt working tier even with high importance", () => {
22
- const meta = JSON.stringify({ tier: "working", importance: 0.96 });
23
- expect(isDecayExempt(meta, 0.96)).toBe(false);
24
- });
25
- });
26
-
27
- describe("Rule 2: recently accessed (within 7 days)", () => {
28
- it("exempts memory accessed 1 day ago", () => {
29
- const meta = JSON.stringify({
30
- lastAccessedAt: Date.now() - 1 * 86_400_000,
31
- });
32
- expect(isDecayExempt(meta, 0.50)).toBe(true);
33
- });
34
-
35
- it("does NOT exempt memory accessed 8 days ago", () => {
36
- const meta = JSON.stringify({
37
- lastAccessedAt: Date.now() - 8 * 86_400_000,
38
- });
39
- expect(isDecayExempt(meta, 0.50)).toBe(false);
40
- });
41
-
42
- it("does NOT exempt when lastAccessedAt is 0", () => {
43
- const meta = JSON.stringify({ lastAccessedAt: 0 });
44
- expect(isDecayExempt(meta, 0.50)).toBe(false);
45
- });
46
- });
47
-
48
- describe("Rule 3: pinned tag", () => {
49
- it("exempts memory with pinned tag", () => {
50
- const meta = JSON.stringify({ tags: ["workflow", "pinned"] });
51
- expect(isDecayExempt(meta, 0.40)).toBe(true);
52
- });
53
-
54
- it("does NOT exempt without pinned tag", () => {
55
- const meta = JSON.stringify({ tags: ["workflow", "pattern"] });
56
- expect(isDecayExempt(meta, 0.40)).toBe(false);
57
- });
58
- });
59
-
60
- describe("edge cases", () => {
61
- it("returns false for undefined metadata", () => {
62
- expect(isDecayExempt(undefined, 0.95)).toBe(false);
63
- });
64
-
65
- it("returns false for empty metadata", () => {
66
- expect(isDecayExempt("{}", 0.50)).toBe(false);
67
- });
68
-
69
- it("returns false for corrupt metadata", () => {
70
- expect(isDecayExempt("not-json", 0.95)).toBe(false);
71
- });
72
-
73
- it("multiple rules: first match wins", () => {
74
- // Core + pinned + recent — all three rules match
75
- const meta = JSON.stringify({
76
- tier: "core",
77
- importance: 0.98,
78
- lastAccessedAt: Date.now() - 3600000,
79
- tags: ["pinned"],
80
- });
81
- expect(isDecayExempt(meta, 0.98)).toBe(true);
82
- });
83
- });
84
-
85
- describe("Rule 0: procedural category", () => {
86
- // A procedural memory's defining trait is low access frequency + long validity.
87
- // Rules 1-3 all key off access statistics, so without Rule 0 these entries land
88
- // in the fastest-decaying tier forever.
89
- const coldPeripheral = JSON.stringify({
90
- tier: "peripheral",
91
- accessCount: 0,
92
- lastAccessedAt: 0,
93
- tags: ["workflow"],
94
- });
95
-
96
- it("exempts patterns even when cold, peripheral and low-importance", () => {
97
- expect(isDecayExempt(coldPeripheral, 0.30, "patterns")).toBe(true);
98
- });
99
-
100
- it("exempts patterns with no metadata at all", () => {
101
- // Checked before the `!metadata` guard on purpose.
102
- expect(isDecayExempt(undefined, 0.30, "patterns")).toBe(true);
103
- });
104
-
105
- it("exempts patterns with corrupt metadata", () => {
106
- expect(isDecayExempt("not-json", 0.30, "patterns")).toBe(true);
107
- });
108
-
109
- it("does NOT exempt cases — they carry an episodic component and should decay", () => {
110
- expect(isDecayExempt(coldPeripheral, 0.30, "cases")).toBe(false);
111
- });
112
-
113
- it("does NOT exempt declarative categories", () => {
114
- for (const category of ["events", "profile", "preferences", "entities"]) {
115
- expect(isDecayExempt(coldPeripheral, 0.30, category)).toBe(false);
116
- }
117
- });
118
-
119
- it("is backward compatible: omitting category preserves Rule 1-3 behaviour", () => {
120
- expect(isDecayExempt(coldPeripheral, 0.30)).toBe(false);
121
- expect(isDecayExempt(JSON.stringify({ tags: ["pinned"] }), 0.40)).toBe(true);
122
- });
123
-
124
- it("does not exempt on unknown category strings", () => {
125
- expect(isDecayExempt(coldPeripheral, 0.30, "skills")).toBe(false);
126
- expect(isDecayExempt(coldPeripheral, 0.30, "")).toBe(false);
127
- });
128
- });
129
- });
@@ -1,58 +0,0 @@
1
- import { describe, it, expect } from "bun:test";
2
- import type { DedupAction, DedupCheckResult } from "../ingest.js";
3
-
4
- describe("DedupAction types", () => {
5
- it("DedupCheckResult supports secondaryDeletes", () => {
6
- const result: DedupCheckResult = {
7
- action: "store",
8
- reason: "unique",
9
- secondaryDeletes: [
10
- { id: "abc12345", action: "delete", reason: "outdated by candidate" },
11
- ],
12
- };
13
- expect(result.secondaryDeletes).toHaveLength(1);
14
- expect(result.secondaryDeletes![0].action).toBe("delete");
15
- expect(result.secondaryDeletes![0].id).toBe("abc12345");
16
- });
17
-
18
- it("DedupCheckResult without secondaryDeletes is backward-compatible", () => {
19
- const result: DedupCheckResult = {
20
- action: "skip",
21
- reason: "hard",
22
- existingText: "existing memory text",
23
- };
24
- expect(result.secondaryDeletes).toBeUndefined();
25
- });
26
-
27
- it("DedupAction only supports delete", () => {
28
- const action: DedupAction = {
29
- id: "test-id",
30
- action: "delete",
31
- reason: "superseded by newer info",
32
- };
33
- expect(action.action).toBe("delete");
34
- });
35
-
36
- it("multiple secondary deletes are valid", () => {
37
- const result: DedupCheckResult = {
38
- action: "store",
39
- reason: "llm-merge",
40
- secondaryDeletes: [
41
- { id: "id1", action: "delete", reason: "outdated" },
42
- { id: "id2", action: "delete", reason: "duplicate of id1" },
43
- ],
44
- };
45
- expect(result.secondaryDeletes).toHaveLength(2);
46
- });
47
-
48
- it("empty secondaryDeletes array treated as no actions", () => {
49
- const result: DedupCheckResult = {
50
- action: "store",
51
- reason: "unique",
52
- secondaryDeletes: [],
53
- };
54
- expect(result.secondaryDeletes).toHaveLength(0);
55
- // In practice, we check .length before executing
56
- expect((result.secondaryDeletes?.length ?? 0) > 0).toBe(false);
57
- });
58
- });
@@ -1,39 +0,0 @@
1
- import { describe, it, expect } from "bun:test";
2
- import { isTemporalOrActionContent } from "../ingest.js";
3
-
4
- describe("Dedup guard: isTemporalOrActionContent", () => {
5
- describe("date-stamped events (must NOT be deduped)", () => {
6
- it("ISO date", () => expect(isTemporalOrActionContent("2026-03-25 部署了新版本")).toBe(true));
7
- it("今天", () => expect(isTemporalOrActionContent("今天跑了 benchmark")).toBe(true));
8
- it("昨天", () => expect(isTemporalOrActionContent("昨天讨论了架构")).toBe(true));
9
- it("上次", () => expect(isTemporalOrActionContent("上次的方案不行")).toBe(true));
10
- it("刚才", () => expect(isTemporalOrActionContent("刚才改了配置")).toBe(true));
11
- });
12
-
13
- describe("file operations (must NOT be deduped)", () => {
14
- it("file path", () => expect(isTemporalOrActionContent("修改了 /Users/xxx/src/foo.ts")).toBe(true));
15
- it("home path", () => expect(isTemporalOrActionContent("保存到 ~/recallnest/data/")).toBe(true));
16
- it("md file", () => expect(isTemporalOrActionContent("更新了 README.md")).toBe(true));
17
- it("mv command", () => expect(isTemporalOrActionContent("mv old.json new.json")).toBe(true));
18
- it("归档", () => expect(isTemporalOrActionContent("把旧文件归档了")).toBe(true));
19
- });
20
-
21
- describe("memory instructions (must NOT be deduped)", () => {
22
- it("记住", () => expect(isTemporalOrActionContent("记住不要用 rm")).toBe(true));
23
- it("remember", () => expect(isTemporalOrActionContent("remember to check tests")).toBe(true));
24
- it("别忘了", () => expect(isTemporalOrActionContent("别忘了跑测试")).toBe(true));
25
- it("务必", () => expect(isTemporalOrActionContent("务必先备份")).toBe(true));
26
- });
27
-
28
- describe("feedback/corrections (must NOT be deduped)", () => {
29
- it("不要再", () => expect(isTemporalOrActionContent("不要再用这个方法")).toBe(true));
30
- it("stop doing", () => expect(isTemporalOrActionContent("stop doing that")).toBe(true));
31
- it("don't", () => expect(isTemporalOrActionContent("don't mock the database")).toBe(true));
32
- });
33
-
34
- describe("generic content (CAN be deduped normally)", () => {
35
- it("plain description", () => expect(isTemporalOrActionContent("RecallNest 是一个记忆服务")).toBe(false));
36
- it("technical fact", () => expect(isTemporalOrActionContent("LanceDB 支持向量搜索")).toBe(false));
37
- it("preference without instruction marker", () => expect(isTemporalOrActionContent("我喜欢用 dark mode")).toBe(false));
38
- });
39
- });
@@ -1,39 +0,0 @@
1
- import { describe, expect, it } from "bun:test";
2
-
3
- import { deterministicId } from "../store.js";
4
-
5
- describe("deterministicId", () => {
6
- it("same scope+text always produce the same ID", () => {
7
- const id1 = deterministicId("project:test", "I prefer TypeScript");
8
- const id2 = deterministicId("project:test", "I prefer TypeScript");
9
- expect(id1).toBe(id2);
10
- });
11
-
12
- it("different text produces different ID", () => {
13
- const id1 = deterministicId("project:test", "I prefer TypeScript");
14
- const id2 = deterministicId("project:test", "I prefer JavaScript");
15
- expect(id1).not.toBe(id2);
16
- });
17
-
18
- it("different scope produces different ID", () => {
19
- const id1 = deterministicId("project:alpha", "same text");
20
- const id2 = deterministicId("project:beta", "same text");
21
- expect(id1).not.toBe(id2);
22
- });
23
-
24
- it("returns UUID-shaped string (8-4-4-4-12)", () => {
25
- const id = deterministicId("project:test", "hello world");
26
- expect(id).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/);
27
- });
28
-
29
- it("handles empty scope gracefully", () => {
30
- const id = deterministicId("", "some text");
31
- expect(id).toMatch(/^[0-9a-f]{8}-/);
32
- });
33
-
34
- it("handles CJK text", () => {
35
- const id1 = deterministicId("project:test", "我喜欢用Bun");
36
- const id2 = deterministicId("project:test", "我喜欢用Bun");
37
- expect(id1).toBe(id2);
38
- });
39
- });
@@ -1,305 +0,0 @@
1
- import { describe, expect, it, beforeEach, afterEach } from "bun:test";
2
- import { existsSync, writeFileSync, readFileSync, mkdirSync, statSync, utimesSync } from "node:fs";
3
- import { join, dirname } from "node:path";
4
- import { tmpdir } from "node:os";
5
-
6
- import {
7
- acquireLock,
8
- releaseLock,
9
- rollbackLock,
10
- shouldDistill,
11
- getLastDistillTime,
12
- withLock,
13
- withWriteLock,
14
- lockPathForKey,
15
- stampLock,
16
- type DistillLockConfig,
17
- } from "../distill-lock.js";
18
-
19
- // ---------------------------------------------------------------------------
20
- // Helpers
21
- // ---------------------------------------------------------------------------
22
-
23
- let tempDir: string;
24
- let lockPath: string;
25
-
26
- function cfg(overrides?: Partial<DistillLockConfig>): Partial<DistillLockConfig> {
27
- return { lockPath, ...overrides };
28
- }
29
-
30
- beforeEach(() => {
31
- tempDir = join(tmpdir(), `distill-lock-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
32
- mkdirSync(tempDir, { recursive: true });
33
- lockPath = join(tempDir, "distill.lock");
34
- });
35
-
36
- afterEach(() => {
37
- // Clean up lock file if it exists
38
- if (existsSync(lockPath)) {
39
- try {
40
- const { unlinkSync } = require("node:fs");
41
- unlinkSync(lockPath);
42
- } catch { /* ignore */ }
43
- }
44
- });
45
-
46
- // ---------------------------------------------------------------------------
47
- // acquireLock
48
- // ---------------------------------------------------------------------------
49
-
50
- describe("acquireLock", () => {
51
- it("creates lock file and returns true when no lock exists", () => {
52
- const result = acquireLock(cfg());
53
- expect(result).toBe(true);
54
- expect(existsSync(lockPath)).toBe(true);
55
- });
56
-
57
- it("writes current PID into lock file", () => {
58
- acquireLock(cfg());
59
- const { readFileSync } = require("node:fs");
60
- const content = readFileSync(lockPath, "utf-8").trim();
61
- // Lock body is now `<pid>:<ownership-token>` (P2), so assert the PID prefix.
62
- expect(content.startsWith(`${process.pid}:`)).toBe(true);
63
- });
64
-
65
- it("returns false when lock held by alive PID and not expired", () => {
66
- // Write current process PID (which is alive)
67
- writeFileSync(lockPath, String(process.pid), "utf-8");
68
-
69
- const result = acquireLock(cfg());
70
- expect(result).toBe(false);
71
- });
72
-
73
- it("overwrites lock when PID is dead", () => {
74
- // PID 999999 is almost certainly not running
75
- writeFileSync(lockPath, "999999", "utf-8");
76
-
77
- const result = acquireLock(cfg());
78
- expect(result).toBe(true);
79
-
80
- const { readFileSync } = require("node:fs");
81
- const content = readFileSync(lockPath, "utf-8").trim();
82
- // Reclaimed lock records our `<pid>:<token>` now (P2 ownership token).
83
- expect(content.startsWith(`${process.pid}:`)).toBe(true);
84
- });
85
-
86
- it("overwrites lock when mtime is expired even if PID alive", () => {
87
- writeFileSync(lockPath, String(process.pid), "utf-8");
88
- // Set mtime to 2 hours ago
89
- const twoHoursAgo = new Date(Date.now() - 7_200_000);
90
- utimesSync(lockPath, twoHoursAgo, twoHoursAgo);
91
-
92
- const result = acquireLock(cfg({ expireMs: 3_600_000 }));
93
- expect(result).toBe(true);
94
- });
95
-
96
- it("creates parent directories if missing", () => {
97
- const deepPath = join(tempDir, "nested", "dir", "distill.lock");
98
- const result = acquireLock(cfg({ lockPath: deepPath }));
99
- expect(result).toBe(true);
100
- expect(existsSync(deepPath)).toBe(true);
101
- });
102
- });
103
-
104
- // ---------------------------------------------------------------------------
105
- // releaseLock
106
- // ---------------------------------------------------------------------------
107
-
108
- describe("releaseLock", () => {
109
- it("deletes lock file", () => {
110
- writeFileSync(lockPath, String(process.pid), "utf-8");
111
- expect(existsSync(lockPath)).toBe(true);
112
-
113
- releaseLock(cfg());
114
- expect(existsSync(lockPath)).toBe(false);
115
- });
116
-
117
- it("is a no-op when lock file does not exist", () => {
118
- expect(() => releaseLock(cfg())).not.toThrow();
119
- });
120
- });
121
-
122
- // ---------------------------------------------------------------------------
123
- // rollbackLock
124
- // ---------------------------------------------------------------------------
125
-
126
- describe("rollbackLock", () => {
127
- it("sets lock mtime to the given previous value", () => {
128
- writeFileSync(lockPath, String(process.pid), "utf-8");
129
- const pastDate = new Date(Date.now() - 600_000); // 10 min ago
130
-
131
- rollbackLock(pastDate, cfg());
132
-
133
- const st = statSync(lockPath);
134
- // Allow 1 second tolerance for filesystem granularity
135
- expect(Math.abs(st.mtimeMs - pastDate.getTime())).toBeLessThan(1000);
136
- });
137
-
138
- it("is a no-op when lock file does not exist", () => {
139
- expect(() => rollbackLock(new Date(), cfg())).not.toThrow();
140
- });
141
- });
142
-
143
- // ---------------------------------------------------------------------------
144
- // shouldDistill
145
- // ---------------------------------------------------------------------------
146
-
147
- describe("shouldDistill", () => {
148
- it("returns true when checkpoint count >= minCheckpoints (default 3)", () => {
149
- expect(shouldDistill(3, cfg())).toBe(true);
150
- expect(shouldDistill(5, cfg())).toBe(true);
151
- });
152
-
153
- it("returns false when checkpoint count < minCheckpoints", () => {
154
- expect(shouldDistill(0, cfg())).toBe(false);
155
- expect(shouldDistill(1, cfg())).toBe(false);
156
- expect(shouldDistill(2, cfg())).toBe(false);
157
- });
158
-
159
- it("respects custom minCheckpoints", () => {
160
- expect(shouldDistill(4, cfg({ minCheckpoints: 5 }))).toBe(false);
161
- expect(shouldDistill(5, cfg({ minCheckpoints: 5 }))).toBe(true);
162
- });
163
- });
164
-
165
- // ---------------------------------------------------------------------------
166
- // getLastDistillTime
167
- // ---------------------------------------------------------------------------
168
-
169
- describe("getLastDistillTime", () => {
170
- it("returns lock file mtime when lock exists", () => {
171
- writeFileSync(lockPath, String(process.pid), "utf-8");
172
- const st = statSync(lockPath);
173
-
174
- const result = getLastDistillTime(cfg());
175
- expect(Math.abs(result - st.mtimeMs)).toBeLessThan(100);
176
- });
177
-
178
- it("returns 0 when lock file does not exist", () => {
179
- const result = getLastDistillTime(cfg());
180
- expect(result).toBe(0);
181
- });
182
- });
183
-
184
- // ---------------------------------------------------------------------------
185
- // P0-1: acquireLock atomicity + named withLock / withWriteLock
186
- // ---------------------------------------------------------------------------
187
-
188
- describe("acquireLock atomicity (O_EXCL)", () => {
189
- it("is exclusive: second acquire on a live-held lock fails", () => {
190
- expect(acquireLock(cfg({ expireMs: 60_000 }))).toBe(true);
191
- expect(acquireLock(cfg({ expireMs: 60_000 }))).toBe(false);
192
- });
193
- });
194
-
195
- describe("withLock", () => {
196
- it("runs fn and releases the lock afterwards", async () => {
197
- const out = await withLock("wl-run", async () => 42, { lockDir: tempDir });
198
- expect(out.ran).toBe(true);
199
- if (out.ran) expect(out.result).toBe(42);
200
- expect(existsSync(lockPathForKey("wl-run", tempDir))).toBe(false);
201
- });
202
-
203
- it("skips (ran:false) when a live process already holds the lock", async () => {
204
- const p = lockPathForKey("wl-skip", tempDir);
205
- mkdirSync(dirname(p), { recursive: true });
206
- writeFileSync(p, String(process.pid), "utf-8"); // current pid = alive
207
- let ran = false;
208
- const out = await withLock(
209
- "wl-skip",
210
- async () => { ran = true; return 1; },
211
- { lockDir: tempDir, expireMs: 60_000 },
212
- );
213
- expect(out.ran).toBe(false);
214
- if (!out.ran) expect(out.reason).toBe("locked_by_another_process");
215
- expect(ran).toBe(false);
216
- });
217
-
218
- it("does not block across different lock keys", async () => {
219
- const held = lockPathForKey("wl-keyA", tempDir);
220
- mkdirSync(dirname(held), { recursive: true });
221
- writeFileSync(held, String(process.pid), "utf-8");
222
- const out = await withLock("wl-keyB", async () => "ran", { lockDir: tempDir, expireMs: 60_000 });
223
- expect(out.ran).toBe(true);
224
- });
225
-
226
- it("releases the lock even when fn throws", async () => {
227
- await expect(
228
- withLock("wl-throw", async () => { throw new Error("boom"); }, { lockDir: tempDir }),
229
- ).rejects.toThrow("boom");
230
- expect(existsSync(lockPathForKey("wl-throw", tempDir))).toBe(false);
231
- });
232
- });
233
-
234
- describe("withWriteLock", () => {
235
- it("throws when a live holder never releases (timeout)", async () => {
236
- const p = lockPathForKey("ww-timeout", tempDir);
237
- mkdirSync(dirname(p), { recursive: true });
238
- writeFileSync(p, String(process.pid), "utf-8"); // alive, never released
239
- await expect(
240
- withWriteLock("ww-timeout", async () => 1, {
241
- lockDir: tempDir,
242
- expireMs: 60_000,
243
- waitTimeoutMs: 150,
244
- pollMs: 20,
245
- }),
246
- ).rejects.toThrow(/timed out/);
247
- });
248
-
249
- it("reclaims an expired lock and runs", async () => {
250
- const p = lockPathForKey("ww-expired", tempDir);
251
- mkdirSync(dirname(p), { recursive: true });
252
- writeFileSync(p, String(process.pid), "utf-8");
253
- const twoHoursAgo = new Date(Date.now() - 7_200_000);
254
- utimesSync(p, twoHoursAgo, twoHoursAgo);
255
- const result = await withWriteLock("ww-expired", async () => "done", {
256
- lockDir: tempDir,
257
- expireMs: 3_600_000,
258
- });
259
- expect(result).toBe("done");
260
- });
261
-
262
- it("returns fn result directly on a free lock", async () => {
263
- const result = await withWriteLock("ww-free", async () => 7, { lockDir: tempDir });
264
- expect(result).toBe(7);
265
- });
266
- });
267
-
268
- describe("stampLock", () => {
269
- it("touches an existing lock file's mtime to now", () => {
270
- const p = lockPathForKey("stamp", tempDir);
271
- mkdirSync(dirname(p), { recursive: true });
272
- writeFileSync(p, String(process.pid), "utf-8");
273
- utimesSync(p, new Date(Date.now() - 100_000), new Date(Date.now() - 100_000));
274
- stampLock({ lockPath: p });
275
- const st = statSync(p);
276
- expect(Math.abs(st.mtimeMs - Date.now())).toBeLessThan(2000);
277
- });
278
-
279
- it("creates the marker file when absent (mtime ~ now)", () => {
280
- const p = lockPathForKey("stamp-absent", tempDir);
281
- expect(existsSync(p)).toBe(false);
282
- stampLock({ lockPath: p });
283
- expect(existsSync(p)).toBe(true);
284
- expect(Math.abs(statSync(p).mtimeMs - Date.now())).toBeLessThan(2000);
285
- });
286
- });
287
-
288
- describe("lock ownership token (release safety)", () => {
289
- it("does not delete a lock reclaimed by another owner after expiry", () => {
290
- const p = lockPathForKey("own-reclaimed", tempDir);
291
- expect(acquireLock({ lockPath: p, expireMs: 60_000 })).toBe(true);
292
- // Simulate: our lock expired mid-run, another process reclaimed it (its own token).
293
- writeFileSync(p, "99999:other-owner-token", "utf-8");
294
- releaseLock({ lockPath: p });
295
- expect(existsSync(p)).toBe(true); // new owner's lock must survive our release
296
- expect(readFileSync(p, "utf-8")).toContain("other-owner-token");
297
- });
298
-
299
- it("removes a lock we still own", () => {
300
- const p = lockPathForKey("own-normal", tempDir);
301
- expect(acquireLock({ lockPath: p, expireMs: 60_000 })).toBe(true);
302
- releaseLock({ lockPath: p });
303
- expect(existsSync(p)).toBe(false);
304
- });
305
- });
@@ -1,79 +0,0 @@
1
- import { describe, it, expect } from "bun:test";
2
- import { distillSession, type ConversationMessage } from "../session-distiller.js";
3
-
4
- /**
5
- * Regression test for mcp-server.ts:1894 P0 bug (fixed 2026-05-13).
6
- *
7
- * The bug: mcp-server.ts passed { messages, scope, preserveRecent, keepRecentTools, persist }
8
- * as first arg, but distillSession signature is (messages: ConversationMessage[], deps, opts).
9
- *
10
- * Result before fix: microcompact internally saw undefined.length, silently skipped all
11
- * loops, returned empty result. distill_session MCP appeared to work but produced 0 output.
12
- *
13
- * Fix: split call into 3 args: messages (array), deps, opts.
14
- *
15
- * These tests verify the fix works (microcompact actually clears tools, tokens freed)
16
- * and document the bug shape (calling with object as first arg returns silent noop, not error).
17
- */
18
- describe("distillSession parameter shape regression", () => {
19
- const buildMessages = (): ConversationMessage[] => [
20
- { role: "user", content: "start task" },
21
- { role: "assistant", content: "calling tool" },
22
- { role: "tool", content: "tool result 1 ".repeat(50), tool_name: "Read" },
23
- { role: "assistant", content: "more work" },
24
- { role: "tool", content: "tool result 2 ".repeat(50), tool_name: "Read" },
25
- { role: "assistant", content: "more work" },
26
- { role: "tool", content: "tool result 3 ".repeat(50), tool_name: "Read" },
27
- { role: "user", content: "preserved recent" },
28
- ];
29
-
30
- // Mock llm.chatLong returns empty string → summarize falls through to {text:"",dimensions:{}}
31
- // → persist block skipped (Object.keys(dimensions).length === 0)
32
- const mockDeps = {
33
- llm: { chatLong: async () => "" } as any,
34
- persistMemory: async () => ({ disposition: "stored" as const, id: "test-id" }),
35
- };
36
-
37
- it("microcompact actually processes messages when called with correct (array, deps, opts) shape", async () => {
38
- const messages = buildMessages();
39
- // preserveRecent=1 → cutoff = 8 - 1 = 7 → scan first 7 messages, find 3 Read tools (idx 2/4/6)
40
- // keepRecentTools=1 → clear 3-1 = 2 tools (idx 2,4)
41
- const result = await distillSession(messages, mockDeps, {
42
- scope: "test:regression-2026-05-13",
43
- preserveRecent: 1,
44
- keepRecentTools: 1,
45
- persist: false,
46
- });
47
- expect(result).toBeDefined();
48
- expect(result.compacted_messages).toBeDefined();
49
- expect(result.compacted_messages.length).toBe(messages.length);
50
- expect(result.microcompact.tools_cleared).toBe(2);
51
- expect(result.microcompact.tokens_freed).toBeGreaterThan(0);
52
- // Verify the cleared tool messages have been replaced with placeholder
53
- const clearedMsg = result.compacted_messages[2];
54
- expect(clearedMsg.role).toBe("tool");
55
- expect(clearedMsg.content).toContain("[Cleared:");
56
- });
57
-
58
- it("documents bug shape: object as first arg = silent noop (no error, empty result)", async () => {
59
- // BUG REPRODUCTION (pre-fix mcp-server.ts:1894 behavior)
60
- // distillSession expects messages: ConversationMessage[]
61
- // but received an object — microcompact internally does messages.length / .forEach
62
- // → on object, .length === undefined → loops skip → empty result returned silently
63
- const wrongShape = {
64
- messages: buildMessages(),
65
- scope: "test:bug-shape",
66
- preserveRecent: 1,
67
- };
68
- const result = await distillSession(
69
- // @ts-expect-error: intentional wrong shape to verify silent noop characteristic
70
- wrongShape,
71
- mockDeps,
72
- {},
73
- );
74
- // The bug signature: silent noop — no exception, but no work either
75
- expect(result.compacted_messages).toEqual([]);
76
- expect(result.microcompact.tools_cleared).toBe(0);
77
- expect(result.microcompact.tokens_freed).toBe(0);
78
- });
79
- });