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,368 @@
1
+ /**
2
+ * extraction.ts — shared, single-source extraction helpers for session
3
+ * transcripts and their derivatives (fix2, continuity wave, 2026-07-31).
4
+ *
5
+ * WHY this module exists: session-card.ts (F3, hook-end mechanical
6
+ * distillation) and resurrect.ts (F6, read-only cross-slug session finder)
7
+ * independently reimplemented Linear-ref / artifact-path / next-step-line
8
+ * extraction. M9's tool_result exclusion (session-card.ts, review fix
9
+ * 2026-07-31) and a markdown-heading exclusion never reached resurrect.ts's
10
+ * copies, because there was nothing forcing the two to stay in sync — see
11
+ * reports/2026-07-31-verifier-report.md §V3 and "additional findings" #3/#5.
12
+ * This module is the ONE place those extraction rules live now; both
13
+ * callers consume it, so a future fix to the rule only has to land once.
14
+ *
15
+ * Two input shapes are genuinely different and BOTH are covered here:
16
+ * - Record-based: parsed JSONL transcript records (`{type, message}`) —
17
+ * the shape of session-card.ts's rawHead/rawTail, and ALSO the shape
18
+ * embedded (after a frontmatter block) inside resurrect.ts's raw-archive
19
+ * bodies (journal/archive/raw/*.md — archive-write.ts writes the
20
+ * verbatim transcript JSONL as-is after its own frontmatter).
21
+ * - Text-based: a single flat prose/markdown string — session-card.ts's
22
+ * own already-reduced `finalAssistantText`/`finalUserText`, and
23
+ * resurrect.ts's session-card markdown bodies (journal/*--card--*.md,
24
+ * the RENDERED OUTPUT of session-card.ts, re-parsed generically per
25
+ * resurrect.ts's own design note: it must stay buildable without
26
+ * importing the card renderer itself).
27
+ *
28
+ * M9 (tool_result exclusion) is a RECORD-level concept — it distinguishes a
29
+ * tool_use block (the assistant's own intentional call) from a tool_result
30
+ * block (a tool's returned data, which can legitimately reference OTHER,
31
+ * unrelated projects' ticket IDs). It only makes sense where records are
32
+ * available: session-card.ts's rawHead/rawTail, and resurrect.ts's raw
33
+ * archive bodies (Source 2), which are parsed here via `parseJsonlLenient`.
34
+ * resurrect.ts's session-card bodies (Source 3) are already-rendered plain
35
+ * markdown produced BY session-card.ts's own M9-protected extractors — they
36
+ * never contain a raw tool_result JSON blob to exclude in the first place,
37
+ * so a text-level M9 guard would have nothing to do there (see resurrect.ts
38
+ * for the call site and this note reiterated at the point it matters).
39
+ */
40
+ // ---------------------------------------------------------------------------
41
+ // Shared regex
42
+ // ---------------------------------------------------------------------------
43
+ // NOTE (CHALLENGE — deviates from the design doc's literal regex): the spec
44
+ // says `/[A-Z]{2,6}-\d+/g`, but that pattern cannot match THIS repo's own
45
+ // real Linear ID convention — team "TongWu" issues are "TOW2-357" etc., and
46
+ // `[A-Z]{2,6}` is uppercase-LETTERS-only, so the digit "2" inside "TOW2"
47
+ // breaks the letter run before the hyphen is ever reached (verified: the
48
+ // literal spec regex returns zero matches on "TOW2-357"). Widened to allow
49
+ // trailing digits in the team-key prefix while keeping the same safety
50
+ // properties (must start with a letter, so plain numbers/hex/versions never
51
+ // match; still requires a hyphen + digits, so bare words like "HEAD" don't).
52
+ const LINEAR_REF_SOURCE = "\\b[A-Z][A-Z0-9]{1,5}-\\d+\\b";
53
+ /** Decision-line marker, shared so both callers recognize the same vocabulary. */
54
+ export const DECISION_LINE_RE = /决定|decided|locked|confirmed/i;
55
+ /** Next-step-line marker, shared so both callers recognize the same vocabulary. */
56
+ export const NEXT_STEP_LINE_RE = /next|下一步|待办|todo/i;
57
+ /** A markdown ATX heading line (`#`..`######` + whitespace) — never a real content line. */
58
+ const MARKDOWN_HEADING_RE = /^#{1,6}\s/;
59
+ /** Fresh global-flagged RegExp per call — a shared stateful instance would corrupt concurrent `lastIndex` scans. */
60
+ function linearRefRegex() {
61
+ return new RegExp(LINEAR_REF_SOURCE, "g");
62
+ }
63
+ function matchAllLinearRefs(text) {
64
+ const re = linearRefRegex();
65
+ const out = [];
66
+ let m;
67
+ while ((m = re.exec(text)) !== null)
68
+ out.push(m[0]);
69
+ return out;
70
+ }
71
+ // ---------------------------------------------------------------------------
72
+ // Small shared utilities
73
+ // ---------------------------------------------------------------------------
74
+ export function unescapeJsonString(s) {
75
+ try {
76
+ return JSON.parse(`"${s}"`);
77
+ }
78
+ catch {
79
+ return s;
80
+ }
81
+ }
82
+ export function dedupCapped(items, cap) {
83
+ const seen = new Set();
84
+ const out = [];
85
+ for (const item of items) {
86
+ if (seen.has(item))
87
+ continue;
88
+ seen.add(item);
89
+ out.push(item);
90
+ if (out.length >= cap)
91
+ break;
92
+ }
93
+ return out;
94
+ }
95
+ // ---------------------------------------------------------------------------
96
+ // Record-based extraction (parsed JSONL transcript records)
97
+ // ---------------------------------------------------------------------------
98
+ /**
99
+ * Lenient per-line JSONL parse. Raw archive bodies and rawHead/rawTail
100
+ * samples are near-JSONL, not valid line-delimited JSON as a whole (they can
101
+ * be head/tail-truncated mid-record, and raw-archive bodies are preceded by
102
+ * a non-JSON YAML-ish frontmatter block) — this deliberately does NOT
103
+ * attempt a full-document parse; it parses one line at a time and silently
104
+ * skips whatever doesn't parse.
105
+ */
106
+ export function parseJsonlLenient(text) {
107
+ const out = [];
108
+ for (const line of text.split("\n")) {
109
+ const trimmed = line.trim();
110
+ if (!trimmed)
111
+ continue;
112
+ try {
113
+ const parsed = JSON.parse(trimmed);
114
+ if (parsed && typeof parsed === "object")
115
+ out.push(parsed);
116
+ }
117
+ catch {
118
+ /* skip malformed/truncated lines — expected at head/tail boundaries and at frontmatter/non-JSON lines */
119
+ }
120
+ }
121
+ return out;
122
+ }
123
+ /** Hook stdout/boilerplate records are never real conversation content. */
124
+ export function isBoilerplateRecord(rec) {
125
+ return rec.type === "attachment";
126
+ }
127
+ /** First `type: "text"` block of a message's content (string or content-block array). */
128
+ export function textFromContent(content) {
129
+ if (typeof content === "string")
130
+ return content;
131
+ if (Array.isArray(content)) {
132
+ for (const c of content) {
133
+ if (c && typeof c === "object" && c.type === "text") {
134
+ return String(c.text ?? "");
135
+ }
136
+ }
137
+ }
138
+ return "";
139
+ }
140
+ /** Write/Edit tool_use `input.file_path` values, in first-seen order, from parsed transcript records. */
141
+ export function extractArtifactPathsFromRecords(lines, cap) {
142
+ const paths = [];
143
+ for (const rec of lines) {
144
+ if (isBoilerplateRecord(rec))
145
+ continue;
146
+ if (rec.type !== "assistant")
147
+ continue;
148
+ const msg = rec.message;
149
+ const content = msg?.content;
150
+ if (!Array.isArray(content))
151
+ continue;
152
+ for (const c of content) {
153
+ const cr = c;
154
+ if (cr.type !== "tool_use")
155
+ continue;
156
+ if (cr.name !== "Write" && cr.name !== "Edit")
157
+ continue;
158
+ const input = cr.input;
159
+ const filePath = input?.file_path;
160
+ if (typeof filePath === "string" && filePath)
161
+ paths.push(filePath);
162
+ }
163
+ }
164
+ return dedupCapped(paths, cap);
165
+ }
166
+ /**
167
+ * Linear IDs from parsed transcript records. M9: scoped to content the
168
+ * user/assistant actually AUTHORED this turn — a plain string message body,
169
+ * a `type: "text"` content block, or a `type: "tool_use"` block's OWN
170
+ * `input` (the assistant's intentional tool-call arguments, e.g.
171
+ * `mcp__linear__save_issue` called with `{identifier: "TOW2-360"}` — real,
172
+ * intentional content, scanned regardless of which tool). Explicitly
173
+ * EXCLUDES `type: "tool_result"` content blocks — those carry a tool's
174
+ * RETURNED data (e.g. the output of `mcp__agent-recall__recall` or
175
+ * `mcp__linear__list_issues`), which can legitimately contain OTHER,
176
+ * unrelated projects' ticket IDs the assistant never decided or acted on
177
+ * this session.
178
+ */
179
+ export function extractLinearRefsFromRecords(lines, cap) {
180
+ const refs = [];
181
+ for (const rec of lines) {
182
+ if (isBoilerplateRecord(rec))
183
+ continue;
184
+ if (rec.type !== "user" && rec.type !== "assistant")
185
+ continue;
186
+ const msg = rec.message;
187
+ const content = msg?.content;
188
+ if (typeof content === "string") {
189
+ refs.push(...matchAllLinearRefs(content));
190
+ continue;
191
+ }
192
+ if (!Array.isArray(content))
193
+ continue;
194
+ for (const block of content) {
195
+ if (!block || typeof block !== "object")
196
+ continue;
197
+ const b = block;
198
+ if (b.type === "text" && typeof b.text === "string") {
199
+ refs.push(...matchAllLinearRefs(b.text));
200
+ }
201
+ else if (b.type === "tool_use") {
202
+ // The assistant's OWN tool-call arguments — real, intentional
203
+ // content, unlike a tool_result's returned data (never scanned).
204
+ try {
205
+ refs.push(...matchAllLinearRefs(JSON.stringify(b.input ?? {})));
206
+ }
207
+ catch {
208
+ /* unstringifiable input — skip */
209
+ }
210
+ }
211
+ // `tool_result` blocks are deliberately NOT scanned (M9).
212
+ }
213
+ }
214
+ return dedupCapped(refs, cap);
215
+ }
216
+ // ---------------------------------------------------------------------------
217
+ // System/injected-text exclusion + record-based "real text" reduction
218
+ // ---------------------------------------------------------------------------
219
+ // fix3 (2026-07-31, continuity wave): promoted from session-card.ts's private
220
+ // isSystemText/extractFirstUserText/extractFinal (identical logic, same
221
+ // minLen defaults) to a shared home here — resurrect.ts's raw-archive Source
222
+ // 2 needs the SAME record-aware "first real user text" / "final real
223
+ // assistant text" reduction session-card.ts already uses for its title
224
+ // fallback and finalAssistantText/finalUserText, and reimplementing it a
225
+ // second time (as a flat text-level regex scan, which is exactly what
226
+ // resurrect.ts used to do — see the "additional findings" this fix closes)
227
+ // is the precise class of bug fix2's consolidation already killed once.
228
+ /** Harness/system-injected text markers a real user/assistant turn never authors verbatim (slash-command scaffolding, `<system-reminder>` blocks, etc.). */
229
+ const SYSTEM_TEXT_PREFIXES = [
230
+ /^dangerously-skip/i,
231
+ /^<local-command/,
232
+ /^<command-name/,
233
+ /^<command-message/,
234
+ /^<command-args/,
235
+ /^<system-reminder/,
236
+ /^<user-prompt-submit/,
237
+ ];
238
+ /** True when `text` opens with one of `SYSTEM_TEXT_PREFIXES` — never real user/assistant content. */
239
+ export function isSystemText(text) {
240
+ const t = text.trimStart();
241
+ return SYSTEM_TEXT_PREFIXES.some((re) => re.test(t));
242
+ }
243
+ /**
244
+ * First real (non-boilerplate-record, non-system-text) user message text
245
+ * from parsed transcript records, scanning forward. Record- and content-
246
+ * block-aware via `textFromContent`: a `tool_result` content block (a
247
+ * tool's RETURNED data — e.g. a `remember()` call's own confirmation echo,
248
+ * "Saved → ... Find again: recall(...)") is never returned here, because
249
+ * `textFromContent` only surfaces a `type:"text"` block, never a sibling
250
+ * `tool_result` block in the same content array. This is the "goal" side of
251
+ * M9's tool_result exclusion, generalized from Linear-ref scanning to
252
+ * free-text goal extraction.
253
+ */
254
+ export function extractFirstUserTextFromRecords(records, minLen = 10) {
255
+ for (const rec of records) {
256
+ if (isBoilerplateRecord(rec))
257
+ continue;
258
+ if (rec.type !== "user")
259
+ continue;
260
+ const msg = rec.message;
261
+ const text = textFromContent(msg?.content);
262
+ if (text.length < minLen || isSystemText(text))
263
+ continue;
264
+ return text;
265
+ }
266
+ return null;
267
+ }
268
+ /**
269
+ * Last real (non-boilerplate-record, non-system-text) record of `type`,
270
+ * scanning from the end of `records`. Shared by session-card.ts's
271
+ * finalAssistantText/finalUserText reduction and resurrect.ts's raw-archive
272
+ * next-step derivation — both need "the final thing a user/assistant
273
+ * actually said", never a raw JSONL line matched by substring.
274
+ */
275
+ export function extractFinalRecordText(records, type, minLen = 1) {
276
+ for (let i = records.length - 1; i >= 0; i--) {
277
+ const rec = records[i];
278
+ if (isBoilerplateRecord(rec))
279
+ continue;
280
+ if (rec.type !== type)
281
+ continue;
282
+ const msg = rec.message;
283
+ const text = textFromContent(msg?.content);
284
+ if (!text || text.length < minLen || isSystemText(text))
285
+ continue;
286
+ return text;
287
+ }
288
+ return null;
289
+ }
290
+ // ---------------------------------------------------------------------------
291
+ // Text-based extraction (flat prose/markdown — no record structure available)
292
+ // ---------------------------------------------------------------------------
293
+ /** Plain global scan for Linear refs across a flat text/markdown string. No record structure is available at this
294
+ * level, so there is no tool_result to exclude — see the file header note on why that's the case in practice for
295
+ * every current text-based caller (already-distilled session-card markdown). */
296
+ export function extractLinearRefsFromText(text, cap) {
297
+ return dedupCapped(matchAllLinearRefs(text), cap);
298
+ }
299
+ /**
300
+ * Artifact paths from a flat text/markdown body, precision-first: only a
301
+ * `"file_path":"..."` JSON value or a markdown list-item path is trusted —
302
+ * never a bare path floating in prose/hook-boilerplate text, which is
303
+ * exactly how naive extraction gets misled by folder-lint warnings quoting
304
+ * unrelated files.
305
+ *
306
+ * fix2 (2026-07-31): the list-item pattern now tolerates a backtick or bold
307
+ * marker immediately after the list marker (`- \`~/path\`` / `- **~/path**`)
308
+ * — real session cards (session-card.ts's own
309
+ * `sections.push("## Artifacts", ...artifacts.map((p) => \`- \\\`${p}\\\`\`))`)
310
+ * ALWAYS wrap the path in backticks, and the pre-fix pattern required the
311
+ * character right after the marker + space to be `~`/`/` directly, so it
312
+ * silently never matched a real card's own artifact list (confirmed against
313
+ * the real store — verifier-report V3, `交付物2_MCP原型_V14.html`).
314
+ *
315
+ * The opening marker is matched as a literal alternation (backtick / `**` /
316
+ * `__`), NOT folded into the captured path's character class — a char-class
317
+ * exclusion of `_`/`*` would also strip those characters from the MIDDLE of
318
+ * a legitimate path, and this repo's own real filenames routinely contain
319
+ * underscores (e.g. `交付物2_MCP原型_V14.html`, verified: an earlier draft of
320
+ * this fix corrupted exactly that path to `交付物2` by excluding `_` from the
321
+ * capture class). Any trailing closing marker is stripped in a separate,
322
+ * bounded cleanup step after the capture completes.
323
+ */
324
+ export function extractArtifactPathsFromText(text, cap) {
325
+ const found = new Set();
326
+ const filePathRe = /"file_path"\s*:\s*"((?:\\.|[^"\\])*)"/g;
327
+ let m;
328
+ while ((m = filePathRe.exec(text)) !== null) {
329
+ if (found.size >= cap)
330
+ break;
331
+ found.add(unescapeJsonString(m[1]));
332
+ }
333
+ const listItemRe = /^\s*[-*]\s+(?:`|\*\*|__)?(~\/[^\s`]+|\/[^\s`]+)/;
334
+ for (const line of text.split("\n")) {
335
+ if (found.size >= cap)
336
+ break;
337
+ const li = line.match(listItemRe);
338
+ if (!li)
339
+ continue;
340
+ const cleaned = li[1].replace(/(`|\*\*|__)+$/, "");
341
+ if (cleaned)
342
+ found.add(cleaned);
343
+ }
344
+ return [...found].slice(0, cap);
345
+ }
346
+ /**
347
+ * Lines matching `re`, each capped to `lineCharCap` chars (ellipsis-suffixed
348
+ * when truncated). Markdown ATX heading lines (`^#{1,6}\s`) are always
349
+ * skipped — a card's own "## Next steps" section heading must never be
350
+ * mistaken for one of its own next-step bullet lines (a real, reproduced
351
+ * bug in resurrect.ts's pre-refactor copy of this logic, which had no such
352
+ * exclusion and produced a spurious duplicate "next step" entry).
353
+ */
354
+ export function extractLinesMatching(text, re, cap, lineCharCap = 200) {
355
+ const out = [];
356
+ for (const rawLine of text.split("\n")) {
357
+ const line = rawLine.trim();
358
+ if (!line || MARKDOWN_HEADING_RE.test(line))
359
+ continue;
360
+ if (!re.test(line))
361
+ continue;
362
+ out.push(line.length > lineCharCap ? line.slice(0, lineCharCap) + "…" : line);
363
+ if (out.length >= cap)
364
+ break;
365
+ }
366
+ return out;
367
+ }
368
+ //# sourceMappingURL=extraction.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"extraction.js","sourceRoot":"","sources":["../../src/storage/extraction.ts"],"names":[],"mappings":"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"}
@@ -5,4 +5,25 @@ export declare function ensureDir(dir: string): void;
5
5
  export declare function todayISO(): string;
6
6
  export declare function readJsonSafe<T>(filePath: string): T | null;
7
7
  export declare function writeJsonAtomic(filePath: string, data: unknown): void;
8
+ /**
9
+ * Largest N in [0, buf.length] such that `buf.subarray(0, N)` never ends
10
+ * mid-way through a multi-byte UTF-8 sequence. Used both for a plain
11
+ * byte-cap truncation (session-card.ts's truncateBytes) and for trimming the
12
+ * END of a fixed-size read window (transcript-reader.ts's head sample).
13
+ */
14
+ export declare function utf8SafeEndBoundary(buf: Buffer, maxBytes: number): number;
15
+ /**
16
+ * Smallest N in [offset, buf.length] such that `buf.subarray(N)` never
17
+ * starts with an orphaned continuation byte. Used for trimming the START of
18
+ * a fixed-size read window that begins at an arbitrary file offset (e.g. a
19
+ * tail sample) — the sequence's lead byte can live BEFORE `offset`, outside
20
+ * the window, leaving only dangling continuation bytes at the front.
21
+ */
22
+ export declare function utf8SafeStartBoundary(buf: Buffer, offset: number): number;
23
+ /**
24
+ * Truncate `input` to at most `maxBytes` UTF-8 bytes, backing off to the last
25
+ * complete character (never emits a mid-character U+FFFD replacement char).
26
+ * Returns `input` unchanged when it already fits within `maxBytes`.
27
+ */
28
+ export declare function truncateUtf8Bytes(input: string, maxBytes: number): string;
8
29
  //# sourceMappingURL=fs-utils.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../src/storage/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3C;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAO1D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAKrE"}
1
+ {"version":3,"file":"fs-utils.d.ts","sourceRoot":"","sources":["../../src/storage/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAI3C;AAED,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAO1D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAKrE;AAgBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAuCzE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAKzE"}
@@ -27,4 +27,90 @@ export function writeJsonAtomic(filePath, data) {
27
27
  fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
28
28
  fs.renameSync(tmp, filePath); // atomic on POSIX
29
29
  }
30
+ // ---------------------------------------------------------------------------
31
+ // M8 (review fix, 2026-07-31) — shared UTF-8-safe byte-boundary helpers.
32
+ //
33
+ // A fixed-byte-offset cut into UTF-8 text (a truncation limit, or a raw
34
+ // head/tail file-read window) can easily land in the MIDDLE of a multi-byte
35
+ // character. Node's default lenient UTF-8 decode does not error on this — it
36
+ // silently substitutes one or more U+FFFD replacement characters for the
37
+ // incomplete sequence, corrupting content instead of failing loudly. These
38
+ // two helpers back off byte-by-byte from a proposed cut point until it lands
39
+ // on a clean character boundary, so decoding the resulting bytes never
40
+ // produces a replacement character. Continuation bytes are `10xxxxxx`
41
+ // (0x80-0xBF, i.e. `byte & 0xC0 === 0x80`).
42
+ // ---------------------------------------------------------------------------
43
+ /**
44
+ * Largest N in [0, buf.length] such that `buf.subarray(0, N)` never ends
45
+ * mid-way through a multi-byte UTF-8 sequence. Used both for a plain
46
+ * byte-cap truncation (session-card.ts's truncateBytes) and for trimming the
47
+ * END of a fixed-size read window (transcript-reader.ts's head sample).
48
+ */
49
+ export function utf8SafeEndBoundary(buf, maxBytes) {
50
+ const end = Math.max(0, Math.min(maxBytes, buf.length));
51
+ if (end === 0)
52
+ return 0;
53
+ // Walk back from the last byte we'd keep (end - 1) over continuation bytes
54
+ // to find the LEAD byte of the sequence touching the cut point. A
55
+ // continuation byte here does NOT by itself mean truncation — it may be
56
+ // the (correct) final byte of a sequence that fits entirely within `end`;
57
+ // that is decided below by comparing the sequence's own length against
58
+ // `end`, not by how many continuation bytes precede the cut. Capped at 3
59
+ // backoff steps (the longest UTF-8 sequence is 4 bytes, so at most 3
60
+ // continuation bytes can precede its lead byte) so malformed input can
61
+ // never walk past the buffer start.
62
+ let leadPos = end - 1;
63
+ let backoff = 0;
64
+ while (leadPos > 0 && backoff < 3 && (buf[leadPos] & 0xC0) === 0x80) {
65
+ leadPos--;
66
+ backoff++;
67
+ }
68
+ const lead = buf[leadPos];
69
+ let seqLen = 1;
70
+ if ((lead & 0x80) === 0x00)
71
+ seqLen = 1; // ASCII
72
+ else if ((lead & 0xE0) === 0xC0)
73
+ seqLen = 2;
74
+ else if ((lead & 0xF0) === 0xE0)
75
+ seqLen = 3;
76
+ else if ((lead & 0xF8) === 0xF0)
77
+ seqLen = 4;
78
+ else {
79
+ // buf[leadPos] is itself still a continuation byte (backoff cap hit, or
80
+ // reached the buffer start) — no valid lead byte found in range; treat
81
+ // everything from leadPos onward as an unrecoverable fragment.
82
+ return leadPos;
83
+ }
84
+ // The sequence starting at leadPos fits entirely within `end` — keep it
85
+ // (this is the common case: end - 1 landed exactly on a complete
86
+ // sequence's own final byte, or on a lone ASCII byte). Otherwise the
87
+ // sequence is truncated regardless of how many of its bytes we captured —
88
+ // drop the whole thing, cutting right before it starts.
89
+ return leadPos + seqLen <= end ? leadPos + seqLen : leadPos;
90
+ }
91
+ /**
92
+ * Smallest N in [offset, buf.length] such that `buf.subarray(N)` never
93
+ * starts with an orphaned continuation byte. Used for trimming the START of
94
+ * a fixed-size read window that begins at an arbitrary file offset (e.g. a
95
+ * tail sample) — the sequence's lead byte can live BEFORE `offset`, outside
96
+ * the window, leaving only dangling continuation bytes at the front.
97
+ */
98
+ export function utf8SafeStartBoundary(buf, offset) {
99
+ let start = Math.max(0, Math.min(offset, buf.length));
100
+ while (start < buf.length && (buf[start] & 0xC0) === 0x80)
101
+ start++;
102
+ return start;
103
+ }
104
+ /**
105
+ * Truncate `input` to at most `maxBytes` UTF-8 bytes, backing off to the last
106
+ * complete character (never emits a mid-character U+FFFD replacement char).
107
+ * Returns `input` unchanged when it already fits within `maxBytes`.
108
+ */
109
+ export function truncateUtf8Bytes(input, maxBytes) {
110
+ const buf = Buffer.from(input, "utf-8");
111
+ if (buf.length <= maxBytes)
112
+ return input;
113
+ const end = utf8SafeEndBoundary(buf, maxBytes);
114
+ return buf.subarray(0, end).toString("utf-8");
115
+ }
30
116
  //# sourceMappingURL=fs-utils.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../../src/storage/fs-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ;IACtB,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,YAAY,CAAI,QAAgB;IAC9C,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAM,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,QAAgB,EAAE,IAAa;IAC7D,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IAClC,MAAM,GAAG,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC;IAC7C,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAC9D,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,kBAAkB;AAClD,CAAC"}
1
+ {"version":3,"file":"fs-utils.js","sourceRoot":"","sources":["../../src/storage/fs-utils.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,50 @@
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
+ export interface HookFailureRow {
25
+ /** ISO-8601 timestamp of the failure. */
26
+ ts: string;
27
+ /** Which hook failed (e.g. "hook-end", "hook-start", "consolidate"). */
28
+ hook: string;
29
+ /** Best-effort string form of the error, capped at MESSAGE_CAP chars. */
30
+ message: string;
31
+ }
32
+ export interface HookHealthState {
33
+ /** The most recent recorded failure, or null if none recorded yet. */
34
+ last_failure: HookFailureRow | null;
35
+ /** Count of failures with ts in the past 24h (relative to when this was computed). */
36
+ failures_24h: number;
37
+ }
38
+ /**
39
+ * Record one hook failure. Best-effort: NEVER throws into the caller — a
40
+ * failure to record a failure must not compound into a second failure.
41
+ */
42
+ export declare function recordHookFailure(hook: string, err: unknown): void;
43
+ /**
44
+ * Read the derived hook health state for renderers (Wave-2's `ar health` /
45
+ * hook-start ⚠️ line). Never throws — returns a zeroed/empty state on any
46
+ * read error (missing file, corrupt JSON) so a renderer never needs its own
47
+ * try/catch around this call.
48
+ */
49
+ export declare function readHookHealth(): HookHealthState;
50
+ //# sourceMappingURL=hook-health.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"hook-health.d.ts","sourceRoot":"","sources":["../../src/storage/hook-health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,YAAY,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC,sFAAsF;IACtF,YAAY,EAAE,MAAM,CAAC;CACtB;AAsFD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,IAAI,CA0BlE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,IAAI,eAAe,CA0BhD"}