brain-memory 0.4.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/git-sync.js CHANGED
@@ -20,7 +20,7 @@ const CONFIG_FILE = 'config.json';
20
20
  // Files/dirs inside ~/.brain/ that should NOT be synced. `.cloud` holds Brain
21
21
  // Cloud OAuth tokens and pre-restore backups — credentials must never be
22
22
  // committed to a git remote.
23
- const EXCLUDED = new Set(['.sync', '.cloud', '.DS_Store']);
23
+ const EXCLUDED = new Set(['.sync', '.cloud', '.local', '.DS_Store']);
24
24
 
25
25
  /**
26
26
  * Check whether `git` is available on PATH.
@@ -38,11 +38,15 @@ const DEFAULT_CONFIG = {
38
38
  // here or approves them one by one with `brain verify approve`.
39
39
  sensitive_topics: false,
40
40
  // ASI06 quarantine for low-trust writes: 'off' (never flag), 'flag'
41
- // (recallable but marked + surfaced for verification — the default), or
42
- // 'enforce' (excluded from recall/session-start until approved). Exclusion
43
- // is evaluated at read time, so flipping the knob retroactively
44
- // hides/reveals already-pending memories.
45
- quarantine_mode: 'flag',
41
+ // (recallable but marked + surfaced for verification), or 'enforce'
42
+ // (excluded from recall/session-start until approved — the default).
43
+ // Exclusion is evaluated at read time, so flipping the knob retroactively
44
+ // hides/reveals already-pending memories. src/quarantine.js owns the
45
+ // default; keep the two in step.
46
+ quarantine_mode: 'enforce',
47
+ // Most low-trust (tool-output / external) memories one recall result set
48
+ // may hold, approved or not. See capLowTrust in src/provenance.js.
49
+ recall_low_trust_max: 1,
46
50
  };
47
51
 
48
52
  /**
package/src/installer.js CHANGED
@@ -260,7 +260,7 @@ function removeInstructionsEntry(configPath, entry) {
260
260
  // host); here the placeholder is expanded to this package's root.
261
261
  // ---------------------------------------------------------------------------
262
262
 
263
- const HOOK_SCRIPT_RE = /[\\/]hooks[\\/](session-start|prompt-recall|session-end)\.mjs"?$/;
263
+ const HOOK_SCRIPT_RE = /[\\/]hooks[\\/](session-start|prompt-recall|citation-check|session-end)\.mjs"?$/;
264
264
 
265
265
  function isBrainHook(hook) {
266
266
  return Boolean(hook) && typeof hook.command === 'string' && HOOK_SCRIPT_RE.test(hook.command);
@@ -658,6 +658,39 @@ function initializeBrain(overrideBase) {
658
658
  return { alreadyExists: false, brainDir };
659
659
  }
660
660
 
661
+ // ---------------------------------------------------------------------------
662
+ // Fragile-install detection. A global install made under a per-version Node
663
+ // manager puts `brain` in that ONE version's bin dir. The command then
664
+ // vanishes whenever the default version moves (a `22` alias drifting to a
665
+ // newer 22.x is enough), and it is invisible to any shell that does not load
666
+ // the manager — agent hooks, GUI-launched agents, non-interactive shells. The
667
+ // failure is silent and intermittent: agents just fall back to hand-editing
668
+ // memory files. Volta and `n` are absent on purpose — Volta shims global
669
+ // packages across versions and `n` installs into a fixed /usr/local prefix.
670
+ // ---------------------------------------------------------------------------
671
+ const VERSION_MANAGERS = [
672
+ { manager: 'nvm', re: /\/\.?nvm\/versions\/node\/([^/]+)\// },
673
+ // nvm-windows: %APPDATA%\nvm\v22.16.0\node_modules\…
674
+ { manager: 'nvm', re: /\/nvm\/(v\d+\.\d+\.\d+)\/node_modules\// },
675
+ { manager: 'fnm', re: /\/\.?fnm\/node-versions\/([^/]+)\// },
676
+ { manager: 'asdf', re: /\/\.asdf\/installs\/nodejs\/([^/]+)\// },
677
+ { manager: 'mise', re: /\/mise\/installs\/node\/([^/]+)\// },
678
+ { manager: 'nodenv', re: /\/\.nodenv\/versions\/([^/]+)\// },
679
+ ];
680
+
681
+ /**
682
+ * @param {string} [packageRoot] - Where this package is installed
683
+ * @returns {{ manager: string, version: string } | null}
684
+ */
685
+ function detectVersionManager(packageRoot = PACKAGE_ROOT) {
686
+ const p = `${String(packageRoot).replace(/\\/g, '/')}/`;
687
+ for (const { manager, re } of VERSION_MANAGERS) {
688
+ const m = p.match(re);
689
+ if (m) return { manager, version: m[1] };
690
+ }
691
+ return null;
692
+ }
693
+
661
694
  module.exports = {
662
695
  RUNTIMES,
663
696
  BRAIN_MARKER_START,
@@ -680,4 +713,5 @@ module.exports = {
680
713
  installHooks,
681
714
  uninstallHooks,
682
715
  hooksInstalled,
716
+ detectVersionManager,
683
717
  };
package/src/pinning.js CHANGED
@@ -77,6 +77,18 @@ function setFrontmatterFields(brainDir, memPath, fields, opts = {}) {
77
77
  * @param {Object} [opts] - { scope = "global"|"project:<name>", priority = 0 }
78
78
  * @returns {Object} Result or { error }
79
79
  */
80
+ /**
81
+ * Whether a memory carrying an authorization claim (src/content-lint.js) may
82
+ * be pinned. Only a user-origin claim qualifies, and only once it is backed by
83
+ * the user's own words (`authorized_by`) or a human approved it in
84
+ * `brain verify` — anything else would load a permission into every session on
85
+ * the writer's say-so.
86
+ */
87
+ function authorizationPinnable(entry) {
88
+ if (!entry || !entry.authorization) return true;
89
+ return entry.origin === 'user' && Boolean(entry.authorized_by || entry.vetted);
90
+ }
91
+
80
92
  function pinMemory(projectRoot, id, opts = {}) {
81
93
  const scope = opts.scope || 'global';
82
94
  const priority = Number.isFinite(opts.priority) ? opts.priority : 0;
@@ -95,6 +107,12 @@ function pinMemory(projectRoot, id, opts = {}) {
95
107
  error: `Memory is pending verification — approve it first: brain verify approve ${id}`,
96
108
  };
97
109
  }
110
+ if (!authorizationPinnable(entry)) {
111
+ return {
112
+ error: `Memory grants the agent a permission and is not backed by the user — ` +
113
+ `only a user-origin claim with authorized_by, or one approved in brain verify, can be pinned: ${id}`,
114
+ };
115
+ }
98
116
  entry.pinned = true;
99
117
  entry.pin_scope = scope;
100
118
  entry.pin_priority = priority;
@@ -143,4 +161,5 @@ function unpinMemory(projectRoot, id) {
143
161
  return { id, pinned: false, was_pinned: wasPinned, removed: before !== pinned.pins.length };
144
162
  }
145
163
 
146
- module.exports = { pinMemory, unpinMemory, estimateTokens, setFrontmatterFields };
164
+ module.exports = {
165
+ authorizationPinnable, pinMemory, unpinMemory, estimateTokens, setFrontmatterFields };
package/src/provenance.js CHANGED
@@ -70,7 +70,41 @@ function isLowTrust(origin) {
70
70
  return LOW_TRUST_ORIGINS.has(origin);
71
71
  }
72
72
 
73
+ // Default number of low-trust memories one result set may hold. Down-weighting
74
+ // alone leaves a poisoned memory in the context window whenever it is the best
75
+ // lexical match; bounding its *occupancy* does not depend on outranking it.
76
+ const DEFAULT_LOW_TRUST_MAX = 1;
77
+
78
+ /**
79
+ * Take the top `top` of a ranked list while holding at most `max` low-trust
80
+ * memories. Low-trust memories past the cap are skipped (the next trusted one
81
+ * takes the slot) and counted, so the caller can report the suppression
82
+ * rather than hide it.
83
+ *
84
+ * @param {Object[]} ranked - Best first; each with `origin`
85
+ * @param {number} top - Result size
86
+ * @param {number} [max] - Low-trust ceiling (config `recall_low_trust_max`)
87
+ * @returns {{ kept: Object[], suppressed: number }}
88
+ */
89
+ function capLowTrust(ranked, top, max = DEFAULT_LOW_TRUST_MAX) {
90
+ const ceiling = Number.isInteger(max) && max >= 0 ? max : DEFAULT_LOW_TRUST_MAX;
91
+ const kept = [];
92
+ let lowTrust = 0;
93
+ let suppressed = 0;
94
+ for (const mem of ranked) {
95
+ if (kept.length >= top) break;
96
+ if (isLowTrust(mem.origin)) {
97
+ if (lowTrust >= ceiling) { suppressed++; continue; }
98
+ lowTrust++;
99
+ }
100
+ kept.push(mem);
101
+ }
102
+ return { kept, suppressed };
103
+ }
104
+
73
105
  module.exports = {
106
+ DEFAULT_LOW_TRUST_MAX,
107
+ capLowTrust,
74
108
  ORIGIN_POLICY,
75
109
  DEFAULT_ORIGIN,
76
110
  PRUNE_EXEMPT_SALIENCE,
package/src/quarantine.js CHANGED
@@ -10,7 +10,7 @@
10
10
  * Naming: the SM-2 spaced-repetition queue owns "review" (review-queue.json,
11
11
  * due_for_review). This subsystem is quarantine / verify / pending_verification.
12
12
  *
13
- * Modes (config.json `quarantine_mode`, default 'flag'):
13
+ * Modes (config.json `quarantine_mode`, default 'enforce'):
14
14
  * off Nothing is flagged; existing flags persist inertly.
15
15
  * flag Flagged memories stay recallable, marked (⊘ unverified receipts,
16
16
  * quarantine_pending in results, session-start count).
@@ -18,6 +18,11 @@
18
18
  * approved. Evaluated at read time, so flipping the knob
19
19
  * retroactively hides/reveals already-pending items.
20
20
  *
21
+ * Exclusion is the default because down-weighting is not a defense: a
22
+ * poisoned memory that is merely ranked lower still reaches the context
23
+ * window whenever it is the best lexical match for the query. Only keeping it
24
+ * out of the candidate pool removes it.
25
+ *
21
26
  * Approval clears the flag only — origin, write-time clamps, and the recall
22
27
  * trust factor all stay. `vetted: true` records that a human/agent looked, and
23
28
  * stops `brain audit` from re-proposing the memory.
@@ -25,6 +30,34 @@
25
30
 
26
31
  const { isLowTrust } = require('./provenance');
27
32
  const { setFrontmatterFields } = require('./pinning');
33
+ const { SENSITIVE_OPT_OUT_REASON } = require('./sensitivity');
34
+
35
+ const QUARANTINE_MODES = new Set(['off', 'flag', 'enforce']);
36
+ const DEFAULT_QUARANTINE_MODE = 'enforce';
37
+
38
+ /**
39
+ * The effective quarantine mode. An unknown value falls back to the default
40
+ * rather than to 'off' — a typo in config.json must never disable the defense.
41
+ */
42
+ function quarantineMode(config) {
43
+ const mode = config && config.quarantine_mode;
44
+ return QUARANTINE_MODES.has(mode) ? mode : DEFAULT_QUARANTINE_MODE;
45
+ }
46
+
47
+ /** True when pending-verification memories are hidden from recall. */
48
+ function hidesPending(config) {
49
+ return quarantineMode(config) === 'enforce';
50
+ }
51
+
52
+ /** True when the lint result carries an authorization claim. */
53
+ function isAuthorizationClaim(lintResult) {
54
+ return ((lintResult && lintResult.flags) || []).some((f) => f.severity === 'authorization');
55
+ }
56
+
57
+ /** `authorized_by` counts as backing only with a non-empty quote of the user. */
58
+ function hasBacking(authorizedBy) {
59
+ return Boolean(authorizedBy && typeof authorizedBy.quote === 'string' && authorizedBy.quote.trim());
60
+ }
28
61
 
29
62
  /**
30
63
  * Decide whether a write should be quarantined.
@@ -33,12 +66,18 @@ const { setFrontmatterFields } = require('./pinning');
33
66
  * - agent-inferred: flagged only on injection-severity lint — the default
34
67
  * agent write path stays friction-free.
35
68
  * - user: never auto-flagged (lint is still recorded in the audit trail).
69
+ * - An authorization claim (lint severity `authorization`) is the exception
70
+ * to both: from any origin but `user` it is flagged `authz:unbacked`, and a
71
+ * `user` one is flagged `authz:no-source` unless the caller passed the
72
+ * user's own words in `authorized_by.quote`. Origin is asserted by the
73
+ * writer, and a writer inventing permission is exactly the failure this
74
+ * guards — so the claim needs evidence, not a label.
36
75
  *
37
- * @param {Object} opts - { origin, lintResult, config }
76
+ * @param {Object} opts - { origin, lintResult, config, authorizedBy }
38
77
  * @returns {{ quarantined: boolean, reasons: string[] }}
39
78
  */
40
- function quarantineDecision({ origin, lintResult, config }) {
41
- const mode = (config && config.quarantine_mode) || 'flag';
79
+ function quarantineDecision({ origin, lintResult, config, authorizedBy }) {
80
+ const mode = quarantineMode(config);
42
81
  if (mode === 'off') return { quarantined: false, reasons: [] };
43
82
 
44
83
  const reasons = [];
@@ -53,6 +92,10 @@ function quarantineDecision({ origin, lintResult, config }) {
53
92
  else if (f.severity === 'suspect' && isLowTrust(origin)) reasons.push(`lint:${f.rule}`);
54
93
  }
55
94
  }
95
+ if (isAuthorizationClaim(lintResult)) {
96
+ if (origin !== 'user') reasons.push('authz:unbacked');
97
+ else if (!hasBacking(authorizedBy)) reasons.push('authz:no-source');
98
+ }
56
99
 
57
100
  return { quarantined: reasons.length > 0, reasons };
58
101
  }
@@ -108,4 +151,38 @@ function approveQuarantine(brainDir, index, id, now) {
108
151
  return { id, vetted: true };
109
152
  }
110
153
 
111
- module.exports = { quarantineDecision, listPending, applyQuarantine, approveQuarantine };
154
+ /**
155
+ * Put an approved memory back into pending verification — the undo for a
156
+ * mistaken approve. Re-flags it and strips vetted/vetted_at, so `brain audit`
157
+ * is free to propose it again. Approval dropped the original reasons, so they
158
+ * are rebuilt: the origin reason (when low-trust), the consent reason (when the
159
+ * memory is sensitive and the user has not opted in), plus `requeued`.
160
+ *
161
+ * Clearing `vetted` is also what withdraws per-item consent: a sensitive
162
+ * memory goes back to hidden, because isSensitiveHidden() keys on it.
163
+ *
164
+ * A pinned memory is refused rather than silently unpinned: pending memories
165
+ * can never be pinned, and dropping an always-apply constraint is the user's
166
+ * call. A supersession the approval released is NOT reverted — the caller
167
+ * surfaces it. Caller writes the index.
168
+ */
169
+ function requeueQuarantine(brainDir, index, id, now, config) {
170
+ const entry = index.memories[id];
171
+ if (!entry) return { error: `Memory not found: ${id}` };
172
+ if (entry.quarantined) return { error: `Memory is already pending verification: ${id}` };
173
+ if (entry.pinned) return { error: `Memory is pinned — unpin it first (a pending memory can never be pinned): ${id}` };
174
+ const optedOut = entry.sensitivity === 'sensitive' && !(config && config.sensitive_topics === true);
175
+ const reasons = [
176
+ ...(isLowTrust(entry.origin) ? [`origin:${entry.origin}`] : []),
177
+ ...(optedOut ? [SENSITIVE_OPT_OUT_REASON] : []),
178
+ 'requeued',
179
+ ];
180
+ delete entry.vetted;
181
+ delete entry.vetted_at;
182
+ setFrontmatterFields(brainDir, entry.path, { vetted: null, vetted_at: null });
183
+ return applyQuarantine(brainDir, index, id, reasons, now);
184
+ }
185
+
186
+ module.exports = {
187
+ DEFAULT_QUARANTINE_MODE, quarantineMode, hidesPending,
188
+ isAuthorizationClaim, hasBacking, quarantineDecision, listPending, applyQuarantine, approveQuarantine, requeueQuarantine };
package/src/receipt.js CHANGED
@@ -15,8 +15,10 @@
15
15
  * Memories pending verification (quarantined — see src/quarantine.js) carry a
16
16
  * further "⊘ unverified" segment, and memories whose validity window has closed
17
17
  * (see src/temporal.js) a "⌛ expired" one, and sensitive-topic memories (see
18
- * src/sensitivity.js) a "⚠ sensitive" one. User/agent-inferred, vetted, current,
19
- * standard receipts are byte-identical to the base format.
18
+ * src/sensitivity.js) a "⚠ sensitive" one, and memories that grant the agent a
19
+ * permission (see src/content-lint.js) a "⚠ authorization" one. User/agent-
20
+ * inferred, vetted, current, standard receipts are byte-identical to the base
21
+ * format.
20
22
  *
21
23
  * Age is derived from the memory's `created` timestamp (falling back to
22
24
  * `last_accessed`; omitted entirely when neither parses):
@@ -82,10 +84,13 @@ function receiptFor(memoryLike, nowFn) {
82
84
  // Consent: a sensitive-topic memory stays visibly marked even after the user
83
85
  // opted in or approved it, so the agent knows to handle it with care.
84
86
  const sensitive = mem.sensitivity === 'sensitive' ? ', ⚠ sensitive' : '';
87
+ // A permission recalled from memory is a claim about the past, never
88
+ // consent for the action in front of the agent now.
89
+ const authz = mem.authorization ? ', ⚠ authorization' : '';
85
90
 
86
91
  return age
87
- ? `◉ memory: "${title}" (${type}, ${age}${trust}${pending}${expired}${sensitive})`
88
- : `◉ memory: "${title}" (${type}${trust}${pending}${expired}${sensitive})`;
92
+ ? `◉ memory: "${title}" (${type}, ${age}${trust}${pending}${expired}${sensitive}${authz})`
93
+ : `◉ memory: "${title}" (${type}${trust}${pending}${expired}${sensitive}${authz})`;
89
94
  }
90
95
 
91
96
  module.exports = { receiptFor, ageLabel };
@@ -0,0 +1,188 @@
1
+ /**
2
+ * Brain Memory — Surfaced Ledger (citation lock)
3
+ *
4
+ * A receipt line (`◉ memory: "<title>" (…)`) tells the user a memory shaped an
5
+ * answer. src/receipt.js guarantees the engine mints it; this module checks
6
+ * the other half — that the agent only cites memories brain actually showed
7
+ * it. Every read path (recall, session-start, prompt-recall) records what it
8
+ * surfaced; `brain reinforce` records what was used; the Stop hook compares
9
+ * the receipts in the final reply against the ledger.
10
+ *
11
+ * Device-local by design: `.local/` is excluded from git sync, cloud sync,
12
+ * export and restore. What one machine's session saw says nothing about
13
+ * another's, and the ledger is telemetry, not memory.
14
+ *
15
+ * Bounded: past MAX_LINES the file is trimmed to its newest KEEP_LINES. Every
16
+ * write is best-effort — a full disk must never break recall.
17
+ */
18
+
19
+ const fs = require('fs');
20
+ const path = require('path');
21
+
22
+ const LOCAL_DIR = '.local';
23
+ const LEDGER_FILE = 'surfaced.jsonl';
24
+ const MAX_LINES = 4000;
25
+ const KEEP_LINES = 2000;
26
+ // Receipts in a reply are matched against memories surfaced this session, or
27
+ // in this window when the reader could not name its session (a bare CLI call).
28
+ const UNSCOPED_WINDOW_MS = 12 * 3600 * 1000;
29
+
30
+ // Titles are not escaped in receipts (src/receipt.js), so match lazily up to
31
+ // the `" (` that opens the type segment.
32
+ const RECEIPT_RE = /◉ memory: "(.*?)" \(/g;
33
+
34
+ function ledgerPath(brainDir) {
35
+ return path.join(brainDir, LOCAL_DIR, LEDGER_FILE);
36
+ }
37
+
38
+ /** The session id a CLI process can see, or null. Hooks pass theirs in. */
39
+ function envSession(env = process.env) {
40
+ return env.BRAIN_SESSION_ID || env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || null;
41
+ }
42
+
43
+ function append(brainDir, entries) {
44
+ if (!entries.length) return;
45
+ try {
46
+ const file = ledgerPath(brainDir);
47
+ fs.mkdirSync(path.dirname(file), { recursive: true });
48
+ fs.appendFileSync(file, entries.map((e) => JSON.stringify(e)).join('\n') + '\n');
49
+ trim(file);
50
+ } catch (_) {
51
+ // Telemetry only — never fail the read path that called us.
52
+ }
53
+ }
54
+
55
+ function trim(file) {
56
+ const lines = fs.readFileSync(file, 'utf-8').split('\n').filter(Boolean);
57
+ if (lines.length <= MAX_LINES) return;
58
+ fs.writeFileSync(file, lines.slice(-KEEP_LINES).join('\n') + '\n');
59
+ }
60
+
61
+ /**
62
+ * Record memories a read path put in front of the agent.
63
+ *
64
+ * @param {string} brainDir
65
+ * @param {Object} opts - { session, source, results: [{id, title, receipt}], now }
66
+ */
67
+ function recordSurfaced(brainDir, { session, source, results, now }) {
68
+ const ts = now || new Date().toISOString();
69
+ append(brainDir, (results || []).filter((r) => r && r.id).map((r) => ({
70
+ ts, kind: 'surfaced', session: session || null, source, id: r.id, title: receiptTitle(r.receipt) ?? r.title,
71
+ })));
72
+ }
73
+
74
+ /** Record memories the agent reported using (`brain reinforce`). */
75
+ function recordUsed(brainDir, { session, ids, now }) {
76
+ const ts = now || new Date().toISOString();
77
+ append(brainDir, (ids || []).map((id) => ({ ts, kind: 'used', session: session || null, id })));
78
+ }
79
+
80
+ /** Record a reply that cited memories brain never surfaced. */
81
+ function recordViolation(brainDir, { session, titles, now }) {
82
+ append(brainDir, [{ ts: now || new Date().toISOString(), kind: 'violation', session: session || null, titles }]);
83
+ }
84
+
85
+ /** Mark a session's violations as shown to the agent. */
86
+ function recordAck(brainDir, { session, now }) {
87
+ append(brainDir, [{ ts: now || new Date().toISOString(), kind: 'ack', session: session || null }]);
88
+ }
89
+
90
+ function readLedger(brainDir) {
91
+ try {
92
+ return fs.readFileSync(ledgerPath(brainDir), 'utf-8').split('\n').filter(Boolean).map((line) => {
93
+ try { return JSON.parse(line); } catch (_) { return null; }
94
+ }).filter(Boolean);
95
+ } catch (_) {
96
+ return [];
97
+ }
98
+ }
99
+
100
+ /** The title inside a receipt line; null when it is not one. */
101
+ function receiptTitle(receipt) {
102
+ if (typeof receipt !== 'string') return null;
103
+ RECEIPT_RE.lastIndex = 0;
104
+ const m = RECEIPT_RE.exec(receipt);
105
+ return m ? m[1] : null;
106
+ }
107
+
108
+ /** Every receipt title cited in a reply. */
109
+ function citedTitles(text) {
110
+ const titles = [];
111
+ if (typeof text !== 'string') return titles;
112
+ RECEIPT_RE.lastIndex = 0;
113
+ let m;
114
+ while ((m = RECEIPT_RE.exec(text)) !== null) titles.push(m[1]);
115
+ return titles;
116
+ }
117
+
118
+ /**
119
+ * Compare the receipts in a reply against what was surfaced to this session.
120
+ *
121
+ * @param {string} brainDir
122
+ * @param {Object} opts - { session, text, nowMs }
123
+ * @returns {{ cited: string[], unsurfaced: string[] }}
124
+ */
125
+ function checkCitations(brainDir, { session, text, nowMs }) {
126
+ const cited = citedTitles(text);
127
+ if (!cited.length) return { cited, unsurfaced: [] };
128
+ const now = nowMs ?? Date.now();
129
+ const seen = new Set();
130
+ for (const e of readLedger(brainDir)) {
131
+ if (e.kind !== 'surfaced') continue;
132
+ const sameSession = session && e.session === session;
133
+ const unscoped = !e.session && now - Date.parse(e.ts) <= UNSCOPED_WINDOW_MS;
134
+ if (sameSession || unscoped) seen.add(e.title);
135
+ }
136
+ return { cited, unsurfaced: [...new Set(cited.filter((t) => !seen.has(t)))] };
137
+ }
138
+
139
+ /** Violations recorded for a session since its last ack. */
140
+ function pendingViolations(brainDir, session) {
141
+ if (!session) return [];
142
+ let pending = [];
143
+ for (const e of readLedger(brainDir)) {
144
+ if (e.session !== session) continue;
145
+ if (e.kind === 'ack') pending = [];
146
+ else if (e.kind === 'violation') pending.push(...(e.titles || []));
147
+ }
148
+ return [...new Set(pending)];
149
+ }
150
+
151
+ /**
152
+ * Surfaced vs used over a window — how much of what brain injects the agent
153
+ * actually relies on. A low ratio means injection is mostly noise.
154
+ */
155
+ function usageSummary(brainDir, { sinceMs }) {
156
+ let surfaced = 0;
157
+ let used = 0;
158
+ const surfacedIds = new Set();
159
+ const usedIds = new Set();
160
+ for (const e of readLedger(brainDir)) {
161
+ if (Date.parse(e.ts) < sinceMs) continue;
162
+ if (e.kind === 'surfaced') { surfaced++; surfacedIds.add(e.id); }
163
+ else if (e.kind === 'used') { used++; usedIds.add(e.id); }
164
+ }
165
+ const usedOfSurfaced = [...usedIds].filter((id) => surfacedIds.has(id)).length;
166
+ return {
167
+ surfaced,
168
+ used,
169
+ distinct_surfaced: surfacedIds.size,
170
+ distinct_used_of_surfaced: usedOfSurfaced,
171
+ use_rate: surfacedIds.size ? Math.round((usedOfSurfaced / surfacedIds.size) * 1000) / 1000 : null,
172
+ };
173
+ }
174
+
175
+ module.exports = {
176
+ LOCAL_DIR,
177
+ envSession,
178
+ recordSurfaced,
179
+ recordUsed,
180
+ recordViolation,
181
+ recordAck,
182
+ readLedger,
183
+ receiptTitle,
184
+ citedTitles,
185
+ checkCitations,
186
+ pendingViolations,
187
+ usageSummary,
188
+ };
@@ -8,6 +8,8 @@
8
8
 
9
9
  const crypto = require('crypto');
10
10
  const fs = require('fs');
11
+ const http = require('http');
12
+ const https = require('https');
11
13
  const os = require('os');
12
14
  const path = require('path');
13
15
  const zlib = require('zlib');
@@ -65,20 +67,77 @@ function sha256(buf) {
65
67
 
66
68
  // -- a thin client -----------------------------------------------------------
67
69
 
70
+ /**
71
+ * One HTTP request on a socket of its own, closed when the response ends.
72
+ *
73
+ * Deliberately not `fetch`: fetch keeps connections alive in a pool, and on
74
+ * Node 18 a pooled socket to a server that has just been shut down could keep a
75
+ * finished test process from exiting, which hung CI. With `agent: false` and
76
+ * `Connection: close` nothing outlives the request, on any Node version.
77
+ *
78
+ * @returns {Promise<{status: number, headers: {get: (name: string) => string|null}, body: Buffer}>}
79
+ */
80
+ function rawRequest(method, url, { headers, body } = {}) {
81
+ return new Promise((resolve, reject) => {
82
+ const target = new URL(url);
83
+ const mod = target.protocol === 'https:' ? https : http;
84
+ const req = mod.request(target, {
85
+ method,
86
+ agent: false,
87
+ headers: {
88
+ Connection: 'close',
89
+ ...(headers || {}),
90
+ ...(body != null ? { 'Content-Length': Buffer.byteLength(body) } : {}),
91
+ },
92
+ }, (res) => {
93
+ const chunks = [];
94
+ res.on('data', (chunk) => chunks.push(chunk));
95
+ res.on('error', reject);
96
+ res.on('end', () => resolve({
97
+ status: res.statusCode,
98
+ headers: {
99
+ get(name) {
100
+ const value = res.headers[String(name).toLowerCase()];
101
+ if (value == null) return null;
102
+ return Array.isArray(value) ? value.join(', ') : value;
103
+ },
104
+ },
105
+ body: Buffer.concat(chunks),
106
+ }));
107
+ });
108
+ req.on('error', reject);
109
+ req.setTimeout(30000, () => req.destroy(new Error(`${method} ${url} timed out`)));
110
+ req.end(body != null ? body : undefined);
111
+ });
112
+ }
113
+
114
+ function parseBody(buf) {
115
+ const text = buf.toString('utf8');
116
+ try { return text ? JSON.parse(text) : null; } catch { return text; }
117
+ }
118
+
119
+ /** The subset of `fetch` the OIDC verifier uses, without a connection pool. */
120
+ async function plainFetch(url, opts = {}) {
121
+ const res = await rawRequest(opts.method || 'GET', String(url), { headers: opts.headers, body: opts.body });
122
+ return {
123
+ ok: res.status >= 200 && res.status < 300,
124
+ status: res.status,
125
+ headers: res.headers,
126
+ json: async () => JSON.parse(res.body.toString('utf8')),
127
+ text: async () => res.body.toString('utf8'),
128
+ };
129
+ }
130
+
68
131
  function client(baseUrl, token) {
69
132
  const base = baseUrl.replace(/\/$/, '');
70
133
  const auth = token ? { Authorization: `Bearer ${token}` } : {};
71
134
 
72
135
  async function json(method, pathname, body, headers) {
73
- const res = await fetch(base + pathname, {
74
- method,
136
+ const res = await rawRequest(method, base + pathname, {
75
137
  headers: { ...auth, ...(body ? { 'Content-Type': 'application/json' } : {}), ...(headers || {}) },
76
138
  body: body ? JSON.stringify(body) : undefined,
77
139
  });
78
- const text = await res.text();
79
- let data = null;
80
- try { data = text ? JSON.parse(text) : null; } catch { data = text; }
81
- return { status: res.status, headers: res.headers, data };
140
+ return { status: res.status, headers: res.headers, data: parseBody(res.body) };
82
141
  }
83
142
 
84
143
  async function upload(brainId, archive, { headers, query, field } = {}) {
@@ -89,23 +148,18 @@ function client(baseUrl, token) {
89
148
  'Content-Type: application/gzip\r\n\r\n'
90
149
  );
91
150
  const tail = Buffer.from(`\r\n--${boundary}--\r\n`);
92
- const res = await fetch(`${base}/api/brains/${brainId}/sync${query || ''}`, {
93
- method: 'PUT',
151
+ const res = await rawRequest('PUT', `${base}/api/brains/${brainId}/sync${query || ''}`, {
94
152
  headers: { ...auth, 'Content-Type': `multipart/form-data; boundary=${boundary}`, ...(headers || {}) },
95
153
  body: Buffer.concat([head, archive, tail]),
96
154
  });
97
- const text = await res.text();
98
- let data = null;
99
- try { data = text ? JSON.parse(text) : null; } catch { data = text; }
100
- return { status: res.status, headers: res.headers, data };
155
+ return { status: res.status, headers: res.headers, data: parseBody(res.body) };
101
156
  }
102
157
 
103
158
  async function download(brainId, { headers, query } = {}) {
104
- const res = await fetch(`${base}/api/brains/${brainId}/sync${query || ''}`, {
159
+ const res = await rawRequest('GET', `${base}/api/brains/${brainId}/sync${query || ''}`, {
105
160
  headers: { ...auth, ...(headers || {}) },
106
161
  });
107
- const body = Buffer.from(await res.arrayBuffer());
108
- return { status: res.status, headers: res.headers, body };
162
+ return { status: res.status, headers: res.headers, body: res.body };
109
163
  }
110
164
 
111
165
  return { json, upload, download };
@@ -142,4 +196,4 @@ async function startReferenceStore(options = {}) {
142
196
  };
143
197
  }
144
198
 
145
- module.exports = { makeArchive, sampleArchive, sha256, client, startReferenceStore };
199
+ module.exports = { makeArchive, sampleArchive, sha256, client, plainFetch, startReferenceStore };