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,79 @@
1
+ /**
2
+ * Cross-project recency index (F2, continuity wave 2026-07-31).
3
+ *
4
+ * A single, project-agnostic JSONL ledger of recent sessions. Written by the
5
+ * CLI hook-end path (Wave 2 integration wires the actual `appendRecentSession`
6
+ * call site — out of scope here, see packages/cli/src/index.ts) and read at
7
+ * `session_start` to render a "Continuity" card: what was worked on most
8
+ * recently, ACROSS projects, ranked by pure recency. This is deliberately
9
+ * NOT relevance-scored — `recallInsights` (session-start.ts's `cross_project`
10
+ * field) already covers semantic matching; this module's only job is "what
11
+ * happened most recently, anywhere".
12
+ *
13
+ * Root incident (2026-07-31 continuity-wave design doc, fact 6): session_start
14
+ * had zero recency signal outside the CURRENT project's own journal — a long
15
+ * work session captured under one slug was completely invisible from every
16
+ * OTHER slug's session_start next time around. This index is deliberately
17
+ * GLOBAL (stored directly under the AR root, not under projects/<slug>/) so
18
+ * it survives slug fragmentation (the F1 misfiling bug) by design: even when
19
+ * a session lands under the wrong/unexpected slug, its continuity entry is
20
+ * still visible from ANY project's cold start, because the reader never
21
+ * filters by the current slug.
22
+ *
23
+ * Storage: `<AR_ROOT>/recent-sessions.jsonl`, one JSON object per line,
24
+ * append-only, rolling-truncated at 500 lines — same append+roll shape as
25
+ * `logSyncError` (packages/core/src/supabase/sync.ts:79-94), except the path
26
+ * here resolves via `getRoot()` (respects `setRoot()` / `AGENT_RECALL_ROOT`)
27
+ * instead of sync.ts's hardcoded `os.homedir()`. That hardcoding is a KNOWN,
28
+ * separately-tracked test-pollution bug (design doc fact 8, fixed under F5) —
29
+ * this module is written correctly from the start rather than copying it.
30
+ */
31
+ export interface RecentSessionEntry {
32
+ /** ISO-8601 timestamp of the session (when the entry was appended). */
33
+ ts: string;
34
+ /** Claude Code session id. */
35
+ sid: string;
36
+ /** Project slug this session was filed under. */
37
+ slug: string;
38
+ /** F1 slug-resolution confidence (0 when "auto"/unresolved), if known. */
39
+ slug_confidence?: number;
40
+ /** Short session title/summary. */
41
+ title: string;
42
+ /** Best-effort next-step text, if one was distilled for this session. */
43
+ next_step?: string;
44
+ /** Count of artifacts (files touched) this session, if known. */
45
+ artifact_count?: number;
46
+ }
47
+ /**
48
+ * Append one entry to the recency index.
49
+ *
50
+ * Best-effort: any fs failure (permissions, disk full, concurrent-write
51
+ * race) is swallowed. This ledger is a "nice to have" continuity aid, not a
52
+ * system of record — a broken write here must never break the caller's hot
53
+ * path (hook-end / session_end).
54
+ */
55
+ export declare function appendRecentSession(entry: RecentSessionEntry): void;
56
+ /**
57
+ * Read the last `n` entries, newest-first.
58
+ *
59
+ * Cross-project by design: this index is not scoped to any one project's
60
+ * directory (unlike journal/palace storage), so entries written under ANY
61
+ * slug are returned without filtering. Corrupt/partial lines (e.g. a torn
62
+ * write from a crash mid-append) are skipped individually rather than
63
+ * aborting the whole read. Returns `[]` when the index does not exist yet,
64
+ * when `n <= 0`, or on any read failure — never throws.
65
+ */
66
+ export declare function readRecentSessions(n: number): RecentSessionEntry[];
67
+ /**
68
+ * Render an ISO timestamp as a short relative "ago" string for the
69
+ * continuity card (e.g. "just now", "12m ago", "3h ago", "2d ago").
70
+ *
71
+ * Worker Done-Definition #4 (date logic vs TODAY): a future-dated or
72
+ * clock-skewed timestamp (client clock drift, a bad manual entry, or a
73
+ * process crossing a DST boundary) must never render as a nonsensical
74
+ * negative duration — clamped to "just now" instead. Beyond a week, falls
75
+ * back to a plain ISO date: a relative "23d ago" stops being useful and an
76
+ * absolute anchor reads better at that distance.
77
+ */
78
+ export declare function formatAgo(ts: string, now?: number): string;
79
+ //# sourceMappingURL=recency-index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recency-index.d.ts","sourceRoot":"","sources":["../../src/storage/recency-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAuBH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAgED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CASnE;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAqBlE;AAOD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,GAAE,MAAmB,GAAG,MAAM,CAUtE"}
@@ -0,0 +1,204 @@
1
+ /**
2
+ * Cross-project recency index (F2, continuity wave 2026-07-31).
3
+ *
4
+ * A single, project-agnostic JSONL ledger of recent sessions. Written by the
5
+ * CLI hook-end path (Wave 2 integration wires the actual `appendRecentSession`
6
+ * call site — out of scope here, see packages/cli/src/index.ts) and read at
7
+ * `session_start` to render a "Continuity" card: what was worked on most
8
+ * recently, ACROSS projects, ranked by pure recency. This is deliberately
9
+ * NOT relevance-scored — `recallInsights` (session-start.ts's `cross_project`
10
+ * field) already covers semantic matching; this module's only job is "what
11
+ * happened most recently, anywhere".
12
+ *
13
+ * Root incident (2026-07-31 continuity-wave design doc, fact 6): session_start
14
+ * had zero recency signal outside the CURRENT project's own journal — a long
15
+ * work session captured under one slug was completely invisible from every
16
+ * OTHER slug's session_start next time around. This index is deliberately
17
+ * GLOBAL (stored directly under the AR root, not under projects/<slug>/) so
18
+ * it survives slug fragmentation (the F1 misfiling bug) by design: even when
19
+ * a session lands under the wrong/unexpected slug, its continuity entry is
20
+ * still visible from ANY project's cold start, because the reader never
21
+ * filters by the current slug.
22
+ *
23
+ * Storage: `<AR_ROOT>/recent-sessions.jsonl`, one JSON object per line,
24
+ * append-only, rolling-truncated at 500 lines — same append+roll shape as
25
+ * `logSyncError` (packages/core/src/supabase/sync.ts:79-94), except the path
26
+ * here resolves via `getRoot()` (respects `setRoot()` / `AGENT_RECALL_ROOT`)
27
+ * instead of sync.ts's hardcoded `os.homedir()`. That hardcoding is a KNOWN,
28
+ * separately-tracked test-pollution bug (design doc fact 8, fixed under F5) —
29
+ * this module is written correctly from the start rather than copying it.
30
+ */
31
+ import * as fs from "node:fs";
32
+ import * as path from "node:path";
33
+ import { getRoot } from "../types.js";
34
+ const RECENCY_FILENAME = "recent-sessions.jsonl";
35
+ const MAX_LINES = 500;
36
+ /**
37
+ * H2 (review fix, 2026-07-31): only roll once the file is this far PAST
38
+ * MAX_LINES, trimming back down to MAX_LINES. Without this throttle, EVERY
39
+ * append past 500 lines triggered a fresh read→writeFileSync(tmp)→renameSync
40
+ * roll — a second process's plain `appendFileSync` straddling that rename
41
+ * lands on the unlinked inode: its write succeeds but the data silently
42
+ * vanishes once the rename swaps the directory entry to the new (trimmed)
43
+ * inode. Rolling only once every SLACK appends shrinks the number of roll
44
+ * events — and therefore the number of chances for another process's append
45
+ * to land inside one — by ~50x.
46
+ */
47
+ const ROLL_SLACK = 50;
48
+ /** H2: best-effort exclusive lock guarding the roll itself (see rollIfNeeded). */
49
+ const ROLL_LOCK_STALE_MS = 5000;
50
+ function recencyIndexPath() {
51
+ return path.join(getRoot(), RECENCY_FILENAME);
52
+ }
53
+ /**
54
+ * Rolling truncate at MAX_LINES, mirroring `logSyncError`'s pattern
55
+ * (packages/core/src/supabase/sync.ts:79-94): read back, filter blank
56
+ * lines, keep only the last MAX_LINES, write to a temp file, then rename
57
+ * over the original (avoids a reader ever observing a half-written file).
58
+ *
59
+ * H2 (review fix, 2026-07-31): two additional safeguards against a
60
+ * concurrent-append race that could otherwise silently lose a second
61
+ * process's just-written entry (see ROLL_SLACK's doc comment above):
62
+ * 1. Throttle — only roll once `lines.length` exceeds MAX_LINES + ROLL_SLACK
63
+ * (not on every single append past MAX_LINES), shrinking how often the
64
+ * read→write→rename window opens at all.
65
+ * 2. Best-effort exclusive lockfile (`<file>.lock`, O_EXCL create, stale
66
+ * after ROLL_LOCK_STALE_MS) guarding the roll itself, so two processes
67
+ * that both cross the threshold near-simultaneously can't run competing
68
+ * rolls. Mirrors the O_EXCL-style lock convention used elsewhere in this
69
+ * codebase (e.g. the CLI's `.hook-end-lock`) rather than the heavier
70
+ * mkdir-based `filelock.ts` (that one busy-waits up to 5s on EVERY
71
+ * acquire — overkill for an operation that fires once per ~50 appends).
72
+ * Best-effort: if the lock can't be acquired (another process is
73
+ * actively rolling), this call simply SKIPS its own roll — the file is a
74
+ * little larger until the next append tries again; it never blocks or
75
+ * throws. This is defense-in-depth on top of the throttle above, not a
76
+ * complete substitute for it — the append itself is still lock-free.
77
+ */
78
+ function rollIfNeeded(filePath) {
79
+ const content = fs.readFileSync(filePath, "utf-8");
80
+ const lines = content.split("\n").filter(Boolean);
81
+ if (lines.length <= MAX_LINES + ROLL_SLACK)
82
+ return;
83
+ const trimmed = lines.slice(-MAX_LINES).join("\n") + "\n";
84
+ const lockPath = filePath + ".lock";
85
+ let fd;
86
+ try {
87
+ fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
88
+ }
89
+ catch {
90
+ // Lock already held. If it's stale (a crashed writer, >ROLL_LOCK_STALE_MS
91
+ // old), force-break it and take it; otherwise skip this roll entirely.
92
+ try {
93
+ const stat = fs.statSync(lockPath);
94
+ if (Date.now() - stat.mtimeMs <= ROLL_LOCK_STALE_MS)
95
+ return; // held by an active writer
96
+ fs.unlinkSync(lockPath);
97
+ fd = fs.openSync(lockPath, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY);
98
+ }
99
+ catch {
100
+ return; // lost the race to break the stale lock, or another fs error — skip, never throw
101
+ }
102
+ }
103
+ try {
104
+ const tmpPath = filePath + ".tmp";
105
+ fs.writeFileSync(tmpPath, trimmed, "utf-8");
106
+ fs.renameSync(tmpPath, filePath);
107
+ }
108
+ finally {
109
+ try {
110
+ fs.closeSync(fd);
111
+ }
112
+ catch { /* already closed */ }
113
+ try {
114
+ fs.unlinkSync(lockPath);
115
+ }
116
+ catch { /* already removed */ }
117
+ }
118
+ }
119
+ /**
120
+ * Append one entry to the recency index.
121
+ *
122
+ * Best-effort: any fs failure (permissions, disk full, concurrent-write
123
+ * race) is swallowed. This ledger is a "nice to have" continuity aid, not a
124
+ * system of record — a broken write here must never break the caller's hot
125
+ * path (hook-end / session_end).
126
+ */
127
+ export function appendRecentSession(entry) {
128
+ try {
129
+ const filePath = recencyIndexPath();
130
+ fs.mkdirSync(path.dirname(filePath), { recursive: true });
131
+ fs.appendFileSync(filePath, JSON.stringify(entry) + "\n", "utf-8");
132
+ rollIfNeeded(filePath);
133
+ }
134
+ catch {
135
+ // Best-effort — never throw from an append-only telemetry ledger.
136
+ }
137
+ }
138
+ /**
139
+ * Read the last `n` entries, newest-first.
140
+ *
141
+ * Cross-project by design: this index is not scoped to any one project's
142
+ * directory (unlike journal/palace storage), so entries written under ANY
143
+ * slug are returned without filtering. Corrupt/partial lines (e.g. a torn
144
+ * write from a crash mid-append) are skipped individually rather than
145
+ * aborting the whole read. Returns `[]` when the index does not exist yet,
146
+ * when `n <= 0`, or on any read failure — never throws.
147
+ */
148
+ export function readRecentSessions(n) {
149
+ if (n <= 0)
150
+ return [];
151
+ try {
152
+ const filePath = recencyIndexPath();
153
+ if (!fs.existsSync(filePath))
154
+ return [];
155
+ const lines = fs.readFileSync(filePath, "utf-8").split("\n").filter(Boolean);
156
+ const out = [];
157
+ for (let i = lines.length - 1; i >= 0 && out.length < n; i--) {
158
+ try {
159
+ const parsed = JSON.parse(lines[i]);
160
+ if (parsed && typeof parsed.slug === "string" && typeof parsed.title === "string" && typeof parsed.ts === "string") {
161
+ out.push(parsed);
162
+ }
163
+ }
164
+ catch {
165
+ // Skip a corrupt/partial line rather than aborting the whole read.
166
+ }
167
+ }
168
+ return out;
169
+ }
170
+ catch {
171
+ return [];
172
+ }
173
+ }
174
+ const MINUTE_MS = 60_000;
175
+ const HOUR_MS = 60 * MINUTE_MS;
176
+ const DAY_MS = 24 * HOUR_MS;
177
+ const WEEK_MS = 7 * DAY_MS;
178
+ /**
179
+ * Render an ISO timestamp as a short relative "ago" string for the
180
+ * continuity card (e.g. "just now", "12m ago", "3h ago", "2d ago").
181
+ *
182
+ * Worker Done-Definition #4 (date logic vs TODAY): a future-dated or
183
+ * clock-skewed timestamp (client clock drift, a bad manual entry, or a
184
+ * process crossing a DST boundary) must never render as a nonsensical
185
+ * negative duration — clamped to "just now" instead. Beyond a week, falls
186
+ * back to a plain ISO date: a relative "23d ago" stops being useful and an
187
+ * absolute anchor reads better at that distance.
188
+ */
189
+ export function formatAgo(ts, now = Date.now()) {
190
+ const then = new Date(ts).getTime();
191
+ if (Number.isNaN(then))
192
+ return "unknown time";
193
+ const diffMs = now - then;
194
+ if (diffMs < MINUTE_MS)
195
+ return "just now"; // covers <60s AND any future/skewed timestamp
196
+ if (diffMs < HOUR_MS)
197
+ return `${Math.floor(diffMs / MINUTE_MS)}m ago`;
198
+ if (diffMs < DAY_MS)
199
+ return `${Math.floor(diffMs / HOUR_MS)}h ago`;
200
+ if (diffMs < WEEK_MS)
201
+ return `${Math.floor(diffMs / DAY_MS)}d ago`;
202
+ return new Date(then).toISOString().slice(0, 10);
203
+ }
204
+ //# sourceMappingURL=recency-index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recency-index.js","sourceRoot":"","sources":["../../src/storage/recency-index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,74 @@
1
+ /**
2
+ * session-card.ts — mechanical session-card distillation (F3).
3
+ *
4
+ * Pure-mechanical, NO LLM: this runs on the hook-end path and must stay
5
+ * fast/offline. Built directly from the 2026-07-31 continuity-fixture
6
+ * incident (reports/2026-07-31-continuity-fixture.md §2 — "session-card
7
+ * field feasibility"): frontmatter, tool-call artifacts, and Linear refs
8
+ * sourced from direct tool calls are ~70% mechanical; goal/narrative state
9
+ * genuinely needs an LLM pass (out of scope here) — this module only builds
10
+ * the mechanical 70%, unconditionally, on every session end.
11
+ *
12
+ * The card is a NORMAL journal file (written under journal/, not
13
+ * journal/archive/raw/) so it enters existing retrieval + consolidation
14
+ * pipelines for free — no new read path required.
15
+ *
16
+ * Precision rule (fixture report §2): hook-injected `attachment` records
17
+ * (startup-hook stdout, folder-lint dumps, memory-stale-check output, etc.)
18
+ * are NEVER a valid source for artifacts/Linear-refs/title/decisions — that
19
+ * is exactly how the incident's forensics got misdirected. Every extractor
20
+ * below filters those out before scanning.
21
+ */
22
+ export interface SessionCardMeta {
23
+ /** Session UUID — untrusted, sanitized before any path.join. */
24
+ sid: string;
25
+ /** Resolved project slug (may be "auto"). */
26
+ slug: string;
27
+ /** F1's resolveSessionProject() confidence, 0 when slug === "auto". */
28
+ slugConfidence: number;
29
+ /** F1's full candidate ranking — kept so a low-confidence card is re-fileable later. */
30
+ slugCandidates: Array<{
31
+ slug: string;
32
+ count: number;
33
+ }>;
34
+ /** ISO date (YYYY-MM-DD). Defaults to today if omitted. */
35
+ date?: string;
36
+ }
37
+ export interface SessionCardInput {
38
+ /** Head sample of the transcript (JSONL text) — same shape as transcript-reader's `head`. */
39
+ rawHead: string;
40
+ /** Tail sample of the transcript (JSONL text) — same shape as transcript-reader's `tail`. */
41
+ rawTail: string;
42
+ meta: SessionCardMeta;
43
+ }
44
+ export interface SessionCardResult {
45
+ markdown: string;
46
+ title: string;
47
+ artifacts: string[];
48
+ linearRefs: string[];
49
+ decisions: string[];
50
+ nextStep: string[];
51
+ sid: string;
52
+ slug: string;
53
+ date: string;
54
+ }
55
+ /**
56
+ * Build a session card (F3) — pure-mechanical distillation of a session's
57
+ * head+tail transcript sample. Never throws: any internal failure degrades
58
+ * to an empty/best-effort card rather than breaking the hook-end path.
59
+ */
60
+ export declare function buildSessionCard(raw: SessionCardInput): SessionCardResult;
61
+ /**
62
+ * Write a session card as a normal journal file: projects/<slug>/journal/
63
+ * <date>--card--<sid>.md — no new directory, no new read path; existing
64
+ * journal search/consolidation reach it automatically.
65
+ *
66
+ * Idempotent on the session UUID (never overwrites an existing card, matching
67
+ * archive-write.ts's convention) and never throws — a failed write must not
68
+ * break the hook-end / Stop turn.
69
+ */
70
+ export declare function writeSessionCard(card: SessionCardResult): {
71
+ path: string;
72
+ bytes: number;
73
+ };
74
+ //# sourceMappingURL=session-card.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-card.d.ts","sourceRoot":"","sources":["../../src/storage/session-card.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAsBH,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,GAAG,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,cAAc,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,cAAc,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACvD,2DAA2D;IAC3D,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAwED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,iBAAiB,CA+GzE;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAoBzF"}
@@ -0,0 +1,219 @@
1
+ /**
2
+ * session-card.ts — mechanical session-card distillation (F3).
3
+ *
4
+ * Pure-mechanical, NO LLM: this runs on the hook-end path and must stay
5
+ * fast/offline. Built directly from the 2026-07-31 continuity-fixture
6
+ * incident (reports/2026-07-31-continuity-fixture.md §2 — "session-card
7
+ * field feasibility"): frontmatter, tool-call artifacts, and Linear refs
8
+ * sourced from direct tool calls are ~70% mechanical; goal/narrative state
9
+ * genuinely needs an LLM pass (out of scope here) — this module only builds
10
+ * the mechanical 70%, unconditionally, on every session end.
11
+ *
12
+ * The card is a NORMAL journal file (written under journal/, not
13
+ * journal/archive/raw/) so it enters existing retrieval + consolidation
14
+ * pipelines for free — no new read path required.
15
+ *
16
+ * Precision rule (fixture report §2): hook-injected `attachment` records
17
+ * (startup-hook stdout, folder-lint dumps, memory-stale-check output, etc.)
18
+ * are NEVER a valid source for artifacts/Linear-refs/title/decisions — that
19
+ * is exactly how the incident's forensics got misdirected. Every extractor
20
+ * below filters those out before scanning.
21
+ */
22
+ import * as fs from "node:fs";
23
+ import * as path from "node:path";
24
+ import { journalDir, sanitizeSlug } from "./paths.js";
25
+ import { ensureDir, todayISO, truncateUtf8Bytes } from "./fs-utils.js";
26
+ import { generateFrontmatter } from "../palace/obsidian.js";
27
+ import { DECISION_LINE_RE, NEXT_STEP_LINE_RE, parseJsonlLenient, extractArtifactPathsFromRecords, extractLinearRefsFromRecords, extractLinesMatching, extractFirstUserTextFromRecords, extractFinalRecordText, } from "./extraction.js";
28
+ // ---------------------------------------------------------------------------
29
+ // Field size budget (Card <= ~2KB, enforced in BYTES — this repo's content is
30
+ // routinely bilingual/CJK-heavy, where a char-length cap would silently blow
31
+ // well past 2KB on disk).
32
+ // ---------------------------------------------------------------------------
33
+ const CARD_BYTE_CAP = 2000;
34
+ const TITLE_CHAR_CAP = 120;
35
+ const ARTIFACTS_CAP = 10;
36
+ const LINEAR_REFS_CAP = 10;
37
+ const DECISIONS_CAP = 5;
38
+ const NEXT_STEP_CAP = 3;
39
+ const LAST_USER_CHAR_CAP = 300;
40
+ const LAST_ASSISTANT_CHAR_CAP = 800;
41
+ /** H4 fix: cap on F1's ranked slugCandidates list — see the call site in buildSessionCard. */
42
+ const SLUG_CANDIDATES_CAP = 5;
43
+ // DECISION_LINE_RE / NEXT_STEP_LINE_RE / the Linear-ref pattern now live in
44
+ // ./extraction.ts (fix2, 2026-07-31) — single source shared with
45
+ // tools-logic/resurrect.ts. See that module for the "TOW2-357" digit-prefix
46
+ // rationale previously documented inline here.
47
+ // ---------------------------------------------------------------------------
48
+ // Lenient JSONL parsing, boilerplate/content-block/system-text helpers:
49
+ // imported from ./extraction.ts (fix2 + fix3, 2026-07-31) — single source
50
+ // shared with tools-logic/resurrect.ts. SYSTEM_PREFIXES/isSystemText/
51
+ // extractFirstUserText/extractFinal used to be private copies here; they
52
+ // are now extraction.ts's isSystemText/extractFirstUserTextFromRecords/
53
+ // extractFinalRecordText (identical logic, same minLen defaults: 10 for the
54
+ // first-user-text fallback, 1 for the final-record reduction below).
55
+ // ---------------------------------------------------------------------------
56
+ /**
57
+ * Truncate to at most maxBytes, UTF-8 safe (never splits mid multi-byte char
58
+ * into garbage). M8 fix (review, 2026-07-31): delegates to the shared
59
+ * `truncateUtf8Bytes` helper (fs-utils.ts) — the PREVIOUS local implementation
60
+ * here (`buf.subarray(0, maxBytes).toString("utf-8")`) only claimed to be
61
+ * UTF-8 safe; a cut landing mid-multi-byte-sequence silently produced one or
62
+ * more U+FFFD replacement characters (repro'd), which could even push the
63
+ * re-encoded byte length back OVER maxBytes.
64
+ */
65
+ function truncateBytes(text, maxBytes) {
66
+ return truncateUtf8Bytes(text, maxBytes);
67
+ }
68
+ // ---------------------------------------------------------------------------
69
+ // Field extraction
70
+ // ---------------------------------------------------------------------------
71
+ /** Transcript summary record (`{"type":"ai-title","aiTitle":"..."}`), if the transcript has one. */
72
+ function extractAiTitle(lines) {
73
+ for (const rec of lines) {
74
+ if (rec.type === "ai-title" && typeof rec.aiTitle === "string" && rec.aiTitle.trim()) {
75
+ return rec.aiTitle.trim();
76
+ }
77
+ }
78
+ return null;
79
+ }
80
+ // extractFirstUserText / extractFinal / extractArtifacts / extractLinearRefs
81
+ // (M9-fixed) / extractLinesMatching now live in ./extraction.ts as
82
+ // extractFirstUserTextFromRecords / extractFinalRecordText /
83
+ // extractArtifactPathsFromRecords / extractLinearRefsFromRecords /
84
+ // extractLinesMatching — imported above. Single source shared with
85
+ // tools-logic/resurrect.ts (fix2 + fix3, 2026-07-31).
86
+ // ---------------------------------------------------------------------------
87
+ // Public API
88
+ // ---------------------------------------------------------------------------
89
+ /**
90
+ * Build a session card (F3) — pure-mechanical distillation of a session's
91
+ * head+tail transcript sample. Never throws: any internal failure degrades
92
+ * to an empty/best-effort card rather than breaking the hook-end path.
93
+ */
94
+ export function buildSessionCard(raw) {
95
+ const sid = raw?.meta?.sid ?? "";
96
+ const slug = raw?.meta?.slug ?? "auto";
97
+ const date = raw?.meta?.date ?? todayISO();
98
+ try {
99
+ const headLines = parseJsonlLenient(raw.rawHead ?? "");
100
+ const tailLines = parseJsonlLenient(raw.rawTail ?? "");
101
+ const allLines = [...headLines, ...tailLines];
102
+ const title = (extractAiTitle(allLines) ??
103
+ extractFirstUserTextFromRecords(allLines) ??
104
+ "(untitled session)").slice(0, TITLE_CHAR_CAP);
105
+ const artifacts = extractArtifactPathsFromRecords(allLines, ARTIFACTS_CAP);
106
+ const linearRefs = extractLinearRefsFromRecords(allLines, LINEAR_REFS_CAP);
107
+ const finalAssistantText = extractFinalRecordText(allLines, "assistant") ?? "";
108
+ const finalUserText = extractFinalRecordText(allLines, "user") ?? "";
109
+ const decisions = extractLinesMatching(finalAssistantText, DECISION_LINE_RE, DECISIONS_CAP);
110
+ const nextStep = extractLinesMatching(finalAssistantText, NEXT_STEP_LINE_RE, NEXT_STEP_CAP);
111
+ // H4 fix (review, 2026-07-31): cap slugCandidates to the top SLUG_CANDIDATES_CAP
112
+ // by count BEFORE frontmatter serialization. Every other list field on this
113
+ // card already has its own _CAP constant (ARTIFACTS_CAP, LINEAR_REFS_CAP, ...)
114
+ // — this one didn't, and F1's ranked candidate list is NOT length-limited
115
+ // upstream. An uncapped list let a single JSON.stringify'd frontmatter field
116
+ // alone consume the ENTIRE CARD_BYTE_CAP, so the whole-markdown byte
117
+ // truncation below cut mid-YAML — invalid frontmatter (no closing `---`),
118
+ // and every body section after the cut point silently vanished.
119
+ const cappedSlugCandidates = [...(raw?.meta?.slugCandidates ?? [])]
120
+ .sort((a, b) => b.count - a.count)
121
+ .slice(0, SLUG_CANDIDATES_CAP);
122
+ const frontmatter = generateFrontmatter({
123
+ sid,
124
+ date,
125
+ slug,
126
+ slug_confidence: Number((raw?.meta?.slugConfidence ?? 0).toFixed(3)),
127
+ slug_candidates: cappedSlugCandidates,
128
+ source: "hook-end",
129
+ });
130
+ const sections = [`# ${title}`, ""];
131
+ if (linearRefs.length > 0) {
132
+ sections.push("## Linear", linearRefs.join(", "), "");
133
+ }
134
+ if (artifacts.length > 0) {
135
+ sections.push("## Artifacts", ...artifacts.map((p) => `- \`${p}\``), "");
136
+ }
137
+ if (decisions.length > 0) {
138
+ sections.push("## Decisions", ...decisions.map((d) => `- ${d}`), "");
139
+ }
140
+ if (nextStep.length > 0) {
141
+ sections.push("## Next steps", ...nextStep.map((n) => `- ${n}`), "");
142
+ }
143
+ if (finalUserText || finalAssistantText) {
144
+ sections.push("## Last exchange");
145
+ if (finalUserText) {
146
+ const u = finalUserText.trim();
147
+ sections.push(`**User:** ${u.length > LAST_USER_CHAR_CAP ? u.slice(0, LAST_USER_CHAR_CAP) + "…" : u}`, "");
148
+ }
149
+ if (finalAssistantText) {
150
+ const a = finalAssistantText.trim();
151
+ sections.push(`**Assistant:** ${a.length > LAST_ASSISTANT_CHAR_CAP ? a.slice(0, LAST_ASSISTANT_CHAR_CAP) + "…" : a}`, "");
152
+ }
153
+ }
154
+ // H4 fix: byte-truncate ONLY the body, never the frontmatter. A cut
155
+ // mid-YAML produces an invalid card with no closing `---` and silently
156
+ // drops every section after the cut point. Frontmatter is now bounded
157
+ // (capped candidates above, plus the existing per-field caps on every
158
+ // other frontmatter value) so it always fits comfortably on its own; the
159
+ // body absorbs whatever budget remains, BYTE-based (CJK content can far
160
+ // exceed a char-based cap on disk).
161
+ const body = sections.join("\n");
162
+ const frontmatterBytes = Buffer.byteLength(frontmatter, "utf-8");
163
+ const bodyBudget = Math.max(0, CARD_BYTE_CAP - frontmatterBytes);
164
+ const markdown = frontmatter + truncateBytes(body, bodyBudget);
165
+ return { markdown, title, artifacts, linearRefs, decisions, nextStep, sid, slug, date };
166
+ }
167
+ catch {
168
+ // Never throw into the hook-end path — degrade to a minimal, valid card.
169
+ const frontmatter = generateFrontmatter({
170
+ sid,
171
+ date,
172
+ slug,
173
+ slug_confidence: 0,
174
+ slug_candidates: [],
175
+ source: "hook-end",
176
+ });
177
+ const markdown = truncateBytes(`${frontmatter}# (session card build failed)\n`, CARD_BYTE_CAP);
178
+ return {
179
+ markdown,
180
+ title: "(session card build failed)",
181
+ artifacts: [],
182
+ linearRefs: [],
183
+ decisions: [],
184
+ nextStep: [],
185
+ sid,
186
+ slug,
187
+ date,
188
+ };
189
+ }
190
+ }
191
+ /**
192
+ * Write a session card as a normal journal file: projects/<slug>/journal/
193
+ * <date>--card--<sid>.md — no new directory, no new read path; existing
194
+ * journal search/consolidation reach it automatically.
195
+ *
196
+ * Idempotent on the session UUID (never overwrites an existing card, matching
197
+ * archive-write.ts's convention) and never throws — a failed write must not
198
+ * break the hook-end / Stop turn.
199
+ */
200
+ export function writeSessionCard(card) {
201
+ try {
202
+ const slug = sanitizeSlug(card.slug); // slug is caller-controlled; harden before path.join
203
+ const sid = sanitizeSlug(card.sid); // sid is UNTRUSTED (from hook stdin) — sanitize first
204
+ const dir = journalDir(slug);
205
+ ensureDir(dir);
206
+ const dest = path.join(dir, `${card.date}--card--${sid}.md`);
207
+ if (fs.existsSync(dest)) {
208
+ return { path: dest, bytes: 0 };
209
+ }
210
+ const tmp = dest + ".tmp." + process.pid;
211
+ fs.writeFileSync(tmp, card.markdown, "utf-8");
212
+ fs.renameSync(tmp, dest);
213
+ return { path: dest, bytes: Buffer.byteLength(card.markdown, "utf-8") };
214
+ }
215
+ catch {
216
+ return { path: "", bytes: 0 };
217
+ }
218
+ }
219
+ //# sourceMappingURL=session-card.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-card.js","sourceRoot":"","sources":["../../src/storage/session-card.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,31 @@
1
+ /**
2
+ * store-manifest.ts — the store-ROOT self-description (sibling of
3
+ * memory-protocol.ts, one level up). Writes a `MANIFEST.md` at the top of the
4
+ * AgentRecall store (default `~/.agent-recall`, or `AGENT_RECALL_ROOT`) so a
5
+ * cold agent with ONLY filesystem access — no AgentRecall code, no MCP, a
6
+ * bare copy of the directory dropped into a VM — can orient itself.
7
+ *
8
+ * Design rationale (2026-07-27 round table): `MEMORY-PROTOCOL.md` (see
9
+ * memory-protocol.ts) explains ONE project's folder layout, but nothing
10
+ * explains the STORE itself — which of the many `projects/<slug>/`
11
+ * directories are canonical vs. throwaway test junk, which root files are
12
+ * pinned source-of-truth vs. regenerable caches, that `_index.md` files are
13
+ * machine indexes and not memory entries, or that a naming grammar exists at
14
+ * all. That knowledge lived only in this code repo's docs — invisible from
15
+ * the data directory alone. This file closes that gap.
16
+ *
17
+ * Same write-once contract as memory-protocol.ts: written ONCE, never
18
+ * overwrites an existing MANIFEST.md (a user may hand-edit it), and every
19
+ * path inside the generated body is store-root-RELATIVE — never `~` or a
20
+ * machine-absolute path, so the body stays valid after the store is copied
21
+ * to a different machine or home directory.
22
+ */
23
+ /**
24
+ * Write the store-root MANIFEST.md if it is absent (write-once). Mirrors
25
+ * writeMemoryProtocol's contract exactly: best-effort, never throws — returns
26
+ * the path (written or pre-existing) or an empty string on failure. `root` is
27
+ * the store root (typically the caller's `getRoot()`), passed explicitly so
28
+ * this function stays fs-root-agnostic and testable against a temp directory.
29
+ */
30
+ export declare function ensureStoreManifest(root: string): string;
31
+ //# sourceMappingURL=store-manifest.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store-manifest.d.ts","sourceRoot":"","sources":["../../src/storage/store-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsEH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAUxD"}