agent-recall-core 3.4.39 → 3.4.41

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 (102) hide show
  1. package/dist/helpers/auto-name.d.ts +2 -1
  2. package/dist/helpers/auto-name.d.ts.map +1 -1
  3. package/dist/helpers/auto-name.js +45 -6
  4. package/dist/helpers/auto-name.js.map +1 -1
  5. package/dist/helpers/journal-files.d.ts +29 -1
  6. package/dist/helpers/journal-files.d.ts.map +1 -1
  7. package/dist/helpers/journal-files.js +124 -33
  8. package/dist/helpers/journal-files.js.map +1 -1
  9. package/dist/helpers/journal-sig-theme.d.ts +18 -0
  10. package/dist/helpers/journal-sig-theme.d.ts.map +1 -1
  11. package/dist/helpers/journal-sig-theme.js +45 -4
  12. package/dist/helpers/journal-sig-theme.js.map +1 -1
  13. package/dist/index.d.ts +11 -0
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +15 -0
  16. package/dist/index.js.map +1 -1
  17. package/dist/storage/archive-write.d.ts.map +1 -1
  18. package/dist/storage/archive-write.js +7 -1
  19. package/dist/storage/archive-write.js.map +1 -1
  20. package/dist/storage/blind-spots-store.d.ts +9 -1
  21. package/dist/storage/blind-spots-store.d.ts.map +1 -1
  22. package/dist/storage/blind-spots-store.js +9 -2
  23. package/dist/storage/blind-spots-store.js.map +1 -1
  24. package/dist/storage/corrections.d.ts +47 -3
  25. package/dist/storage/corrections.d.ts.map +1 -1
  26. package/dist/storage/corrections.js +53 -6
  27. package/dist/storage/corrections.js.map +1 -1
  28. package/dist/storage/extraction.d.ts +136 -0
  29. package/dist/storage/extraction.d.ts.map +1 -0
  30. package/dist/storage/extraction.js +368 -0
  31. package/dist/storage/extraction.js.map +1 -0
  32. package/dist/storage/fs-utils.d.ts +21 -0
  33. package/dist/storage/fs-utils.d.ts.map +1 -1
  34. package/dist/storage/fs-utils.js +86 -0
  35. package/dist/storage/fs-utils.js.map +1 -1
  36. package/dist/storage/hook-health.d.ts +50 -0
  37. package/dist/storage/hook-health.d.ts.map +1 -0
  38. package/dist/storage/hook-health.js +183 -0
  39. package/dist/storage/hook-health.js.map +1 -0
  40. package/dist/storage/hygiene.d.ts +111 -0
  41. package/dist/storage/hygiene.d.ts.map +1 -0
  42. package/dist/storage/hygiene.js +422 -0
  43. package/dist/storage/hygiene.js.map +1 -0
  44. package/dist/storage/memory-protocol.d.ts.map +1 -1
  45. package/dist/storage/memory-protocol.js +4 -1
  46. package/dist/storage/memory-protocol.js.map +1 -1
  47. package/dist/storage/paths.d.ts +23 -4
  48. package/dist/storage/paths.d.ts.map +1 -1
  49. package/dist/storage/paths.js +26 -9
  50. package/dist/storage/paths.js.map +1 -1
  51. package/dist/storage/recency-index.d.ts +79 -0
  52. package/dist/storage/recency-index.d.ts.map +1 -0
  53. package/dist/storage/recency-index.js +204 -0
  54. package/dist/storage/recency-index.js.map +1 -0
  55. package/dist/storage/session-card.d.ts +74 -0
  56. package/dist/storage/session-card.d.ts.map +1 -0
  57. package/dist/storage/session-card.js +219 -0
  58. package/dist/storage/session-card.js.map +1 -0
  59. package/dist/storage/store-manifest.d.ts +31 -0
  60. package/dist/storage/store-manifest.d.ts.map +1 -0
  61. package/dist/storage/store-manifest.js +108 -0
  62. package/dist/storage/store-manifest.js.map +1 -0
  63. package/dist/supabase/recall-backend.d.ts +1 -1
  64. package/dist/supabase/recall-backend.d.ts.map +1 -1
  65. package/dist/supabase/recall-backend.js.map +1 -1
  66. package/dist/supabase/sync.d.ts.map +1 -1
  67. package/dist/supabase/sync.js +13 -2
  68. package/dist/supabase/sync.js.map +1 -1
  69. package/dist/tools-logic/drill-down.d.ts +9 -2
  70. package/dist/tools-logic/drill-down.d.ts.map +1 -1
  71. package/dist/tools-logic/drill-down.js +32 -1
  72. package/dist/tools-logic/drill-down.js.map +1 -1
  73. package/dist/tools-logic/journal-search.d.ts.map +1 -1
  74. package/dist/tools-logic/journal-search.js +7 -1
  75. package/dist/tools-logic/journal-search.js.map +1 -1
  76. package/dist/tools-logic/predict-correction.d.ts +10 -0
  77. package/dist/tools-logic/predict-correction.d.ts.map +1 -1
  78. package/dist/tools-logic/predict-correction.js +6 -2
  79. package/dist/tools-logic/predict-correction.js.map +1 -1
  80. package/dist/tools-logic/recognition-builder.d.ts +9 -0
  81. package/dist/tools-logic/recognition-builder.d.ts.map +1 -1
  82. package/dist/tools-logic/recognition-builder.js +5 -3
  83. package/dist/tools-logic/recognition-builder.js.map +1 -1
  84. package/dist/tools-logic/resurrect.d.ts +106 -0
  85. package/dist/tools-logic/resurrect.d.ts.map +1 -0
  86. package/dist/tools-logic/resurrect.js +561 -0
  87. package/dist/tools-logic/resurrect.js.map +1 -0
  88. package/dist/tools-logic/session-start-lite.d.ts +6 -0
  89. package/dist/tools-logic/session-start-lite.d.ts.map +1 -1
  90. package/dist/tools-logic/session-start-lite.js +15 -0
  91. package/dist/tools-logic/session-start-lite.js.map +1 -1
  92. package/dist/tools-logic/session-start.d.ts +17 -0
  93. package/dist/tools-logic/session-start.d.ts.map +1 -1
  94. package/dist/tools-logic/session-start.js +87 -5
  95. package/dist/tools-logic/session-start.js.map +1 -1
  96. package/dist/tools-logic/smart-recall.d.ts +9 -4
  97. package/dist/tools-logic/smart-recall.d.ts.map +1 -1
  98. package/dist/tools-logic/smart-recall.js +170 -4
  99. package/dist/tools-logic/smart-recall.js.map +1 -1
  100. package/dist/types.d.ts +1 -1
  101. package/dist/types.js +1 -1
  102. package/package.json +1 -1
@@ -0,0 +1,183 @@
1
+ /**
2
+ * hook-health.ts — F5, fail-loud hook health (continuity wave, 2026-07-31).
3
+ *
4
+ * WHY: every hook catch block in the CLI is stderr-only today (index.ts:
5
+ * 932-935, 1079-1082, 1163-1165, 1184-1186) — a hook that silently fails
6
+ * leaves zero persistent trace, so a broken hook can run for weeks before
7
+ * anyone notices a session went unrecorded. This module is the storage layer
8
+ * a future CLI catch-block wiring (Wave-2 integrator) reports failures into.
9
+ *
10
+ * Pattern: same shape as supabase/sync.ts's logSyncError (append + roll@500)
11
+ * and storage/lifecycle-telemetry.ts (best-effort, AR_ROOT-aware, never
12
+ * throws into the caller). Two files:
13
+ * - hook-health.jsonl — append-only failure log, rolled to the last 500
14
+ * lines once it grows past that (same cap/roll contract as sync-errors).
15
+ * - hook-health.json — a small derived STATE snapshot a renderer can read
16
+ * in O(1) without re-parsing the whole JSONL: {last_failure, failures_24h}.
17
+ *
18
+ * Both paths are resolved via getRoot() (AGENT_RECALL_ROOT / setRoot()
19
+ * override-aware) — never os.homedir() directly. This is the same root-fix
20
+ * this wave applied to sync.ts's logSyncError for the identical reason: a
21
+ * hardcoded home-dir path would let test suites pollute the real user's
22
+ * store the same way sync-errors.log did.
23
+ */
24
+ import * as fs from "node:fs";
25
+ import * as path from "node:path";
26
+ import { getRoot } from "../types.js";
27
+ import { ensureDir, writeJsonAtomic } from "./fs-utils.js";
28
+ const ROLL_LIMIT = 500;
29
+ const WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
30
+ const MESSAGE_CAP = 500; // chars — a hook failure message is a log line, not a dump
31
+ function hookHealthJsonlPath() {
32
+ return path.join(getRoot(), "hook-health.jsonl");
33
+ }
34
+ function hookHealthJsonPath() {
35
+ return path.join(getRoot(), "hook-health.json");
36
+ }
37
+ /** Best-effort string form of an unknown error value. Never throws. */
38
+ function messageOf(err) {
39
+ try {
40
+ if (err instanceof Error)
41
+ return err.message;
42
+ if (typeof err === "string")
43
+ return err;
44
+ return JSON.stringify(err);
45
+ }
46
+ catch {
47
+ return String(err);
48
+ }
49
+ }
50
+ /**
51
+ * Roll `p` down to its last ROLL_LIMIT non-empty lines once it exceeds that
52
+ * count — same tmp+rename atomic-ish pattern as sync.ts's logSyncError cap.
53
+ * Best-effort: any read/write failure here is swallowed by the caller.
54
+ */
55
+ function rollJsonl(p) {
56
+ let content;
57
+ try {
58
+ content = fs.readFileSync(p, "utf-8");
59
+ }
60
+ catch {
61
+ return; // file doesn't exist yet (or unreadable) — nothing to roll
62
+ }
63
+ const lines = content.split("\n").filter(Boolean);
64
+ if (lines.length <= ROLL_LIMIT)
65
+ return;
66
+ const trimmed = lines.slice(-ROLL_LIMIT).join("\n") + "\n";
67
+ const tmp = p + ".tmp." + process.pid;
68
+ fs.writeFileSync(tmp, trimmed, "utf-8");
69
+ fs.renameSync(tmp, p);
70
+ }
71
+ /** Parse every well-formed row out of the JSONL file. Skips malformed lines. */
72
+ function readAllRows(p) {
73
+ let content;
74
+ try {
75
+ content = fs.readFileSync(p, "utf-8");
76
+ }
77
+ catch {
78
+ return [];
79
+ }
80
+ const rows = [];
81
+ for (const line of content.split("\n")) {
82
+ const trimmed = line.trim();
83
+ if (!trimmed)
84
+ continue;
85
+ try {
86
+ const row = JSON.parse(trimmed);
87
+ if (row && typeof row.ts === "string" && typeof row.hook === "string" && typeof row.message === "string") {
88
+ rows.push({ ts: row.ts, hook: row.hook, message: row.message });
89
+ }
90
+ }
91
+ catch {
92
+ // skip malformed line — one bad row must never break the whole read
93
+ }
94
+ }
95
+ return rows;
96
+ }
97
+ /**
98
+ * Count rows whose `ts` falls strictly within the last 24h of `now`.
99
+ *
100
+ * Date logic vs TODAY (Worker Done-Definition #4): a row timestamped in the
101
+ * FUTURE (clock skew, malformed input, or a hostile/buggy caller) must NOT
102
+ * count as "within the last 24h" — it is not in the past at all. Guard with
103
+ * `t <= now` in addition to the window bound, otherwise a future-dated row
104
+ * would render as recent (and even keep counting as "24h fresh" for the next
105
+ * WINDOW_MS milliseconds after `now` catches up to it).
106
+ */
107
+ function countWithin24h(rows, now) {
108
+ let count = 0;
109
+ for (const row of rows) {
110
+ const t = Date.parse(row.ts);
111
+ if (!Number.isFinite(t))
112
+ continue;
113
+ if (t > now)
114
+ continue; // future-dated — never counted as recent
115
+ if (now - t <= WINDOW_MS)
116
+ count++;
117
+ }
118
+ return count;
119
+ }
120
+ /**
121
+ * Record one hook failure. Best-effort: NEVER throws into the caller — a
122
+ * failure to record a failure must not compound into a second failure.
123
+ */
124
+ export function recordHookFailure(hook, err) {
125
+ try {
126
+ const root = getRoot();
127
+ ensureDir(root);
128
+ const jsonlPath = hookHealthJsonlPath();
129
+ const row = {
130
+ ts: new Date().toISOString(),
131
+ hook,
132
+ message: messageOf(err).slice(0, MESSAGE_CAP),
133
+ };
134
+ fs.appendFileSync(jsonlPath, JSON.stringify(row) + "\n", "utf-8");
135
+ rollJsonl(jsonlPath);
136
+ // Recompute failures_24h from the (now-rolled) log so the derived state
137
+ // file always reflects what's actually on disk, not a running counter
138
+ // that could drift from it across process restarts.
139
+ const rows = readAllRows(jsonlPath);
140
+ const state = {
141
+ last_failure: row,
142
+ failures_24h: countWithin24h(rows, Date.now()),
143
+ };
144
+ writeJsonAtomic(hookHealthJsonPath(), state);
145
+ }
146
+ catch {
147
+ // NEVER throw — hook health recording must not break the hook it reports on.
148
+ }
149
+ }
150
+ /**
151
+ * Read the derived hook health state for renderers (Wave-2's `ar health` /
152
+ * hook-start ⚠️ line). Never throws — returns a zeroed/empty state on any
153
+ * read error (missing file, corrupt JSON) so a renderer never needs its own
154
+ * try/catch around this call.
155
+ */
156
+ export function readHookHealth() {
157
+ try {
158
+ const p = hookHealthJsonPath();
159
+ if (!fs.existsSync(p)) {
160
+ return { last_failure: null, failures_24h: 0 };
161
+ }
162
+ const raw = fs.readFileSync(p, "utf-8");
163
+ const parsed = JSON.parse(raw);
164
+ const lastFailure = parsed.last_failure;
165
+ const validLastFailure = lastFailure &&
166
+ typeof lastFailure === "object" &&
167
+ typeof lastFailure.ts === "string" &&
168
+ typeof lastFailure.hook === "string" &&
169
+ typeof lastFailure.message === "string"
170
+ ? { ts: lastFailure.ts, hook: lastFailure.hook, message: lastFailure.message }
171
+ : null;
172
+ return {
173
+ last_failure: validLastFailure,
174
+ failures_24h: typeof parsed.failures_24h === "number" && Number.isFinite(parsed.failures_24h)
175
+ ? parsed.failures_24h
176
+ : 0,
177
+ };
178
+ }
179
+ catch {
180
+ return { last_failure: null, failures_24h: 0 };
181
+ }
182
+ }
183
+ //# sourceMappingURL=hook-health.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hook-health.js","sourceRoot":"","sources":["../../src/storage/hook-health.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,111 @@
1
+ /**
2
+ * hygiene.ts — DETECTION-ONLY store trash audit ("ar hygiene").
3
+ *
4
+ * Sibling to store-doctor.ts, but a different axis:
5
+ * - store-doctor = STRUCTURAL integrity (index drift, stale locks, stalled
6
+ * consolidation seam, orphaned markers, ledger divergence).
7
+ * - hygiene = STORE TRASH (junk project dirs, unbounded counter files,
8
+ * recurring-theme epidemics, case-fold forks, stale derived caches,
9
+ * leaked-secret-shaped strings, missing materialized indexes, reserved-
10
+ * word slug collisions).
11
+ *
12
+ * HARD INVARIANTS (owner-approved 2026-07-27):
13
+ * 1. Scan != clean. `runHygieneScan` NEVER deletes, renames, or quarantines
14
+ * anything — findings only. No mkdir, no unlink, no rename, no write of
15
+ * any kind. Only fs reads (existsSync/readdirSync/readFileSync/statSync).
16
+ * 2. The ONLY write this module ever performs is its own baseline file
17
+ * (`hygiene-baseline.json`), and ONLY via the explicit `updateBaseline`
18
+ * call — never as a side effect of scanning or of `applyBaseline`.
19
+ * 3. Each check runs independently try/caught inside `runHygieneScan` — one
20
+ * failing check (unreadable dir, permissions, malformed file) degrades
21
+ * that check to zero findings; it never kills the whole scan.
22
+ * 4. `runHygieneScan(root)` is PURE with respect to global state: unlike
23
+ * store-doctor.ts (which reads the process-global root via getRoot()),
24
+ * every path here is built from the explicit `root` parameter. This is
25
+ * deliberate — it lets tests exercise the scanner against a temp
26
+ * directory without mutating (or restoring) any global root state.
27
+ *
28
+ * Baseline: without one, every pre-existing finding (e.g. ~985 stray counter
29
+ * files) would resurface on every run and drown out anything NEW. The first
30
+ * invocation of `ar hygiene --baseline-update` snapshots every current
31
+ * finding's `stable_id`; subsequent bare `ar hygiene` runs report only
32
+ * findings whose `stable_id` is NOT in that snapshot ("fresh"), plus a
33
+ * one-line count of how many are already known.
34
+ */
35
+ export type HygieneSeverity = "red" | "yellow";
36
+ export type HygieneGrade = "clean" | "yellow" | "red";
37
+ export interface HygieneFinding {
38
+ /** Stable machine name of the check that produced this finding. */
39
+ check: string;
40
+ severity: HygieneSeverity;
41
+ /**
42
+ * A locator for the finding. Usually a store-root-relative path
43
+ * ("projects/<slug>", "foo-cache.json#L12"), but for an AGGREGATE finding
44
+ * (counter-accumulation) this is a symbolic glob ".ambient-counter-*"
45
+ * rather than a real filesystem path — it never varies with which specific
46
+ * files exist, so the finding's identity stays stable across baseline runs.
47
+ */
48
+ path: string;
49
+ /** Human-readable evidence. NEVER contains raw secret text (see check f). */
50
+ evidence: string;
51
+ /** sha256(check + ":" + path).slice(0, 16) — baseline identity. */
52
+ stable_id: string;
53
+ /** What an agent should do about this finding. Never instructs auto-delete. */
54
+ agent_instruction: string;
55
+ }
56
+ export interface HygieneScanResult {
57
+ findings: HygieneFinding[];
58
+ grade: HygieneGrade;
59
+ /** Number of findings per check name (0 for a check that found nothing). */
60
+ counts: Record<string, number>;
61
+ }
62
+ export interface HygieneBaseline {
63
+ created_at: string;
64
+ /** Sorted, de-duplicated stable_ids known at the time of the last update. */
65
+ stable_ids: string[];
66
+ }
67
+ export interface ApplyBaselineResult {
68
+ /** Findings whose stable_id is NOT in the baseline — report prominently. */
69
+ fresh: HygieneFinding[];
70
+ /** Findings whose stable_id IS in the baseline — report as a one-line count. */
71
+ known: HygieneFinding[];
72
+ }
73
+ /** The baseline file lives at the store root, alongside `projects/`. */
74
+ export declare const HYGIENE_BASELINE_FILENAME = "hygiene-baseline.json";
75
+ export declare function hygieneBaselinePath(root: string): string;
76
+ /**
77
+ * Pure mapping from case-variant fork groups (as returned by
78
+ * `listCaseVariantForks`) to HygieneFinding objects. Extracted for fs-free
79
+ * testability — real case-variant sibling directories cannot be fabricated on
80
+ * a case-insensitive-but-case-preserving filesystem (macOS APFS default: a
81
+ * second `mkdirSync("agentrecall")` silently collides with an existing
82
+ * "AgentRecall"). Same constraint documented on `pickProjectDirEntry` in
83
+ * paths.ts; same fix (test the pure mapping directly). Not part of the
84
+ * public core barrel — internal/test-only export.
85
+ */
86
+ export declare function caseFoldForksToFindings(forks: Array<{
87
+ project: string;
88
+ variants: string[];
89
+ }>): HygieneFinding[];
90
+ /**
91
+ * Run every hygiene check against `root`. READ-ONLY: never writes, never
92
+ * mkdirs, never renames, never acquires a lock. Each check is independently
93
+ * try/caught — one failing check degrades to zero findings for that check,
94
+ * never throws out of the scan as a whole.
95
+ */
96
+ export declare function runHygieneScan(root: string): HygieneScanResult;
97
+ /**
98
+ * Partition `findings` into `fresh` (stable_id NOT in the baseline) and
99
+ * `known` (stable_id IS in the baseline). READ-ONLY — only reads the
100
+ * baseline file; never writes it. Missing/malformed baseline degrades to
101
+ * "everything is fresh" (the honest first-run state).
102
+ */
103
+ export declare function applyBaseline(findings: HygieneFinding[], baselinePath: string): ApplyBaselineResult;
104
+ /**
105
+ * Snapshot every current finding's stable_id into the baseline file. This is
106
+ * the ONLY write this module ever performs, and it only happens when a
107
+ * caller explicitly invokes this function (CLI: `ar hygiene --baseline-update`).
108
+ * Atomic (tmp + rename), mode 0600.
109
+ */
110
+ export declare function updateBaseline(findings: HygieneFinding[], baselinePath: string): HygieneBaseline;
111
+ //# sourceMappingURL=hygiene.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hygiene.d.ts","sourceRoot":"","sources":["../../src/storage/hygiene.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAqBH,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,QAAQ,CAAC;AAC/C,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,CAAC;AAEtD,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,eAAe,CAAC;IAC1B;;;;;;OAMG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,+EAA+E;IAC/E,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;IACpB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,UAAU,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,4EAA4E;IAC5E,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,gFAAgF;IAChF,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAMD,wEAAwE;AACxE,eAAO,MAAM,yBAAyB,0BAA0B,CAAC;AAEjE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAsND;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,GACpD,cAAc,EAAE,CAUlB;AAwJD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CA8B9D;AAiBD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,mBAAmB,CASnG;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,cAAc,EAAE,EAAE,YAAY,EAAE,MAAM,GAAG,eAAe,CAQhG"}