@bom0792/herdgate 0.9.37 → 0.9.39

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.
@@ -0,0 +1,183 @@
1
+ // Journal GC for the experimental Pi receipt journal (see experiments/pi-receipt).
2
+ // "The Luggage" school of retention: eat everything past its days, keep what
3
+ // might still matter. Fail-closed like every other journal reader — an entry
4
+ // whose status is 'unknown' is evidence not yet understood, so it is ALWAYS
5
+ // kept; a scope that cannot be read is reported, never thrown; a watch store
6
+ // that cannot be parsed is never rewritten. Dry-run by default: nothing is
7
+ // written unless apply: true, and even then every rewrite is tmp+rename.
8
+
9
+ import { readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
10
+ import { join } from 'node:path';
11
+ import { RECEIPT_ID, readJournal } from './pi-receipts.mjs';
12
+ import { watchFile } from './pi-receipt-watch.mjs';
13
+
14
+ const SCOPE = /^[0-9a-f]{16}$/; // one hashed dir per Pi workspace
15
+ const RECEIPTS = 'receipts.jsonl';
16
+ const DAY_MS = 86400e3;
17
+ const DEVICE = /^[\w.-]{1,64}$/; // same shape the watch store validates
18
+
19
+ /**
20
+ * The durable watch intents at base/watch.json are the only "cursors" over the
21
+ * journals (requestId -> receipt id). Missing file: no references. Unreadable
22
+ * or corrupt file: no references AND never rewritten (fail-closed — apply must
23
+ * not destroy intents it could not read).
24
+ */
25
+ function loadCursors(base) {
26
+ const file = watchFile(base);
27
+ let raw;
28
+ try { raw = JSON.parse(readFileSync(file, 'utf8')); }
29
+ catch (error) {
30
+ return { subs: [], file, writable: false, broken: error.code !== 'ENOENT' };
31
+ }
32
+ const list = Array.isArray(raw?.subscriptions) ? raw.subscriptions : [];
33
+ const subs = list.filter(s => DEVICE.test(s?.device ?? '') && RECEIPT_ID.test(s?.requestId ?? '')
34
+ && typeof s.wantBody === 'boolean' && Number.isFinite(s.createdAt) && Number.isFinite(s.expiresAt));
35
+ return { subs, file, writable: true };
36
+ }
37
+
38
+ /** Same atomic-private pattern as the journal writer (experiments/pi-receipt/journal.mjs). */
39
+ function atomicWrite(file, text) {
40
+ const tmp = `${file}.tmp`;
41
+ writeFileSync(tmp, text, { mode: 0o600 });
42
+ rmSync(file, { force: true });
43
+ renameSync(tmp, file);
44
+ }
45
+
46
+ /**
47
+ * Sweep every workspace scope under base and collect receipts older than
48
+ * `days` for deletion — except:
49
+ * - status 'unknown' (fail-closed: unclear evidence is always kept), and
50
+ * - receipts still referenced by a watch intent (a device may still be
51
+ * waiting to be shown the result).
52
+ * Body archives (responses/<id>.md) of deleted receipts join the candidates;
53
+ * their bytes fold into the receipt's candidate bytes. Watch intents pointing
54
+ * at ids no journal holds anymore are orphan cursors, reported always and
55
+ * removed only on apply. Never throws; unreadable scopes land in report.errors.
56
+ *
57
+ * apply=false returns { scopes, candidates, orphanCursors, bytesReclaimable,
58
+ * keptUnknown, errors } and touches nothing. apply=true additionally rewrites
59
+ * each affected journal without the deleted entries (tmp+rename), removes the
60
+ * archived bodies, retires orphan cursors, and adds { applied, deleted,
61
+ * bytesFreed } to the report.
62
+ */
63
+ export function gcJournal({ base, days = 90, now = Date.now(), apply = false } = {}) {
64
+ const at = Number.isFinite(now) ? now : Date.now();
65
+ const span = Number.isFinite(days) ? Math.max(0, Math.floor(days)) : 90;
66
+ const cutoff = at - span * DAY_MS;
67
+
68
+ const report = {
69
+ scopes: 0, // scope dirs successfully read
70
+ candidates: [], // {id, scope, ts, status, bytes} — bytes = journal line + body archive
71
+ orphanCursors: [], // {device, requestId}
72
+ bytesReclaimable: 0,
73
+ keptUnknown: 0, // old entries kept because their status is unknown
74
+ errors: [], // {scope, code}
75
+ };
76
+
77
+ let names = [];
78
+ try { names = readdirSync(base).filter(name => SCOPE.test(name)).sort(); }
79
+ catch (error) {
80
+ report.errors.push({ scope: null, code: error.code ?? 'unreadable_base' });
81
+ return report; // nothing can be read, nothing will be written
82
+ }
83
+
84
+ const byScope = new Map(); // scope -> entries (validated by readJournal)
85
+ for (const name of names) {
86
+ try {
87
+ byScope.set(name, readJournal(join(base, name, RECEIPTS)));
88
+ report.scopes += 1;
89
+ } catch (error) {
90
+ report.errors.push({ scope: name, code: error.code ?? 'unreadable_scope' });
91
+ }
92
+ }
93
+
94
+ const cursors = loadCursors(base);
95
+ if (cursors.broken) report.errors.push({ scope: 'watch', code: 'unreadable_watch' });
96
+ const referenced = new Set(cursors.subs.map(sub => sub.requestId));
97
+
98
+ const allIds = new Set(); // every receipt id any journal holds (post-scan)
99
+ for (const entries of byScope.values()) for (const entry of entries) allIds.add(entry.id);
100
+
101
+ // Pass 1 — pick deletion candidates per entry, keeping the fail-closed set.
102
+ const keptIds = new Set(); // ids that must survive somewhere
103
+ const delByScope = new Map(); // scope -> Set<id to drop>
104
+ const lineBytes = new Map(); // "scope\0id" -> journal-line bytes
105
+ for (const [scope, entries] of byScope) {
106
+ for (const entry of entries) {
107
+ const old = entry.ts < cutoff;
108
+ if (old && entry.status === 'unknown') {
109
+ report.keptUnknown += 1;
110
+ keptIds.add(entry.id);
111
+ continue;
112
+ }
113
+ if (old && !referenced.has(entry.id)) {
114
+ const bytes = Buffer.byteLength(JSON.stringify(entry), 'utf8') + 1; // line + \n
115
+ report.candidates.push({ id: entry.id, scope, ts: entry.ts, status: entry.status, bytes });
116
+ lineBytes.set(`${scope}\0${entry.id}`, bytes);
117
+ const ids = delByScope.get(scope) ?? new Set();
118
+ ids.add(entry.id);
119
+ delByScope.set(scope, ids);
120
+ } else {
121
+ keptIds.add(entry.id); // fresh, or still referenced by a watch intent
122
+ }
123
+ }
124
+ }
125
+
126
+ // Pass 2 — archived bodies of deleted receipts (the writer files them in the
127
+ // same scope). A body stays when any surviving receipt elsewhere owns the id.
128
+ const bodyFiles = []; // {id, scope, path, size}
129
+ for (const candidate of report.candidates) {
130
+ if (keptIds.has(candidate.id)) continue;
131
+ const path = join(base, candidate.scope, 'responses', `${candidate.id}.md`);
132
+ try {
133
+ const size = statSync(path).size;
134
+ candidate.bytes += size;
135
+ bodyFiles.push({ id: candidate.id, scope: candidate.scope, path, size });
136
+ } catch { /* no retained body: fine */ }
137
+ }
138
+
139
+ report.orphanCursors = cursors.subs
140
+ .filter(sub => !allIds.has(sub.requestId))
141
+ .map(sub => ({ device: sub.device, requestId: sub.requestId }))
142
+ .sort((a, b) => `${a.device}${a.requestId}`.localeCompare(`${b.device}${b.requestId}`));
143
+
144
+ report.bytesReclaimable = report.candidates.reduce((sum, c) => sum + c.bytes, 0);
145
+
146
+ if (!apply) return report;
147
+
148
+ // apply — every write tmp+rename, every failure reported, never thrown.
149
+ let applied = true;
150
+ let deleted = 0;
151
+ let bytesFreed = 0;
152
+ for (const [scope, ids] of delByScope) {
153
+ try {
154
+ const kept = byScope.get(scope).filter(entry => !ids.has(entry.id));
155
+ atomicWrite(join(base, scope, RECEIPTS), kept.map(entry => JSON.stringify(entry)).join('\n') + (kept.length ? '\n' : ''));
156
+ deleted += ids.size;
157
+ for (const id of ids) bytesFreed += lineBytes.get(`${scope}\0${id}`) ?? 0;
158
+ } catch (error) {
159
+ applied = false;
160
+ report.errors.push({ scope, code: error.code ?? 'rewrite_failed' });
161
+ }
162
+ }
163
+ for (const body of bodyFiles) {
164
+ try {
165
+ rmSync(body.path, { force: true });
166
+ bytesFreed += body.size;
167
+ } catch (error) {
168
+ applied = false;
169
+ report.errors.push({ scope: body.scope, code: error.code ?? 'body_delete_failed' });
170
+ }
171
+ }
172
+ if (report.orphanCursors.length && cursors.writable) {
173
+ try {
174
+ const keep = cursors.subs.filter(sub => allIds.has(sub.requestId));
175
+ atomicWrite(cursors.file, JSON.stringify({ v: 1, subscriptions: keep }) + '\n');
176
+ } catch (error) {
177
+ applied = false;
178
+ report.errors.push({ scope: 'watch', code: error.code ?? 'watch_rewrite_failed' });
179
+ }
180
+ }
181
+
182
+ return { ...report, applied, deleted, bytesFreed };
183
+ }
@@ -0,0 +1,217 @@
1
+ // BM25 keyword search over the local Pi receipt journal — device-safe core.
2
+ // The scoring may read archived bodies and Pi session transcripts (host-local
3
+ // files its user can already read); the RESULT handed to a device carries
4
+ // publicReceipt-shaped metadata only: id, score, status, reason, usage.
5
+ // No snippet, no sessionId, no session file, no timestamps — and no title
6
+ // (prompt-derived text) unless the caller explicitly opts in with withTitle.
7
+
8
+ import { closeSync, openSync, readdirSync, readFileSync, readSync, statSync } from 'node:fs';
9
+ import { homedir } from 'node:os';
10
+ import { join } from 'node:path';
11
+ import { publicReceipt } from './pi-receipts.mjs';
12
+ import { workerBase } from './pi-worker.mjs';
13
+
14
+ const K1 = 1.2;
15
+ const B = 0.75;
16
+ const TRANSCRIPT_CAP = 512 * 1024;
17
+ const BODY_CAP = 128 * 1024;
18
+ const SCOPE = /^[0-9a-f]{16}$/;
19
+
20
+ /** Letters+digits (any script), plus inner . _ / - of words; NFC-folded. */
21
+ export function tokenize(text) {
22
+ const out = [];
23
+ const re = /[\p{L}\p{N}]+(?:[._/\-][\p{L}\p{N}]+)*/gu;
24
+ let m;
25
+ while ((m = re.exec(String(text ?? '').normalize('NFC')))) out.push(m[0].toLowerCase());
26
+ return out;
27
+ }
28
+
29
+ export function buildIndex(docs) {
30
+ const terms = docs.map(d => tokenize(d.text));
31
+ const lengths = terms.map(t => t.length);
32
+ const avgdl = lengths.reduce((a, b) => a + b, 0) / (docs.length || 1);
33
+ const df = new Map();
34
+ terms.forEach(t => {
35
+ const seen = new Set(t);
36
+ for (const term of seen) df.set(term, (df.get(term) ?? 0) + 1);
37
+ });
38
+ return {
39
+ docs, terms, lengths, avgdl, df, n: docs.length,
40
+ idf(term) {
41
+ const d = this.df.get(term) ?? 0;
42
+ return Math.log(1 + (this.n - d + 0.5) / (d + 0.5));
43
+ },
44
+ };
45
+ }
46
+
47
+ /** Score every document against the query; ties break on newest ts. */
48
+ export function searchIndex(index, query, limit = 10) {
49
+ const q = tokenize(query);
50
+ if (!q.length || !index.n) return [];
51
+ const scored = [];
52
+ for (let i = 0; i < index.n; i++) {
53
+ const tf = new Map();
54
+ for (const t of index.terms[i]) tf.set(t, (tf.get(t) ?? 0) + 1);
55
+ let score = 0;
56
+ for (const term of new Set(q)) {
57
+ const f = tf.get(term);
58
+ if (!f) continue;
59
+ const norm = K1 * (1 - B + B * (index.lengths[i] / (index.avgdl || 1)));
60
+ score += index.idf(term) * (f * (K1 + 1)) / (f + norm);
61
+ }
62
+ if (score > 0) scored.push({ doc: index.docs[i], score });
63
+ }
64
+ scored.sort((a, b) => b.score - a.score || (b.doc.meta.ts ?? 0) - (a.doc.meta.ts ?? 0));
65
+ return limit >= scored.length ? scored : scored.slice(0, limit);
66
+ }
67
+
68
+ /** Best window around the first query-term hit (host-local display only). */
69
+ export function snippet(text, query, width = 160) {
70
+ const hay = String(text ?? '');
71
+ const terms = tokenize(query);
72
+ const lower = hay.toLowerCase();
73
+ let at = -1;
74
+ for (const term of terms) { at = lower.indexOf(term); if (at >= 0) break; }
75
+ if (at < 0) return hay.slice(0, width).replace(/\s+/g, ' ').trim();
76
+ const start = Math.max(0, at - Math.floor(width / 2));
77
+ const cut = hay.slice(start, start + width).replace(/\s+/g, ' ').trim();
78
+ return start > 0 ? `…${cut}` : cut;
79
+ }
80
+
81
+ function readJsonl(file, cap) {
82
+ try {
83
+ const stat = statSync(file);
84
+ const fd = openSync(file, 'r');
85
+ try {
86
+ const size = Math.min(stat.size, cap);
87
+ const buf = Buffer.alloc(size);
88
+ let read = 0;
89
+ while (read < size) {
90
+ const n = readSync(fd, buf, read, size - read, null);
91
+ if (!n) break;
92
+ read += n;
93
+ }
94
+ const out = [];
95
+ for (const line of buf.toString('utf8').split('\n')) {
96
+ try { out.push(JSON.parse(line)); } catch { /* torn tail or junk */ }
97
+ }
98
+ return out;
99
+ } finally { closeSync(fd); }
100
+ } catch { return []; }
101
+ }
102
+
103
+ function textOfContent(content) {
104
+ if (typeof content === 'string') return content;
105
+ if (!Array.isArray(content)) return '';
106
+ return content.map(b => (typeof b?.text === 'string' ? b.text : '')).join(' ');
107
+ }
108
+
109
+ function transcriptText(file) {
110
+ const parts = [];
111
+ for (const e of readJsonl(file, TRANSCRIPT_CAP)) {
112
+ if (e?.type !== 'message') continue;
113
+ const role = e.message?.role;
114
+ if (role !== 'user' && role !== 'assistant') continue;
115
+ const text = textOfContent(e.message.content).trim();
116
+ if (text) parts.push(text);
117
+ }
118
+ return parts.join('\n');
119
+ }
120
+
121
+ /** Match a Pi session transcript by its id: <root>/<slug>/<ts>_<sessionId>.jsonl.
122
+ * Two roots hold transcripts: Pi's default storage for TUI sessions, and the
123
+ * worker base for SDK-created job sessions (they live outside Pi's storage —
124
+ * the same reason restore-by-file insists on --session <file>). */
125
+ export function sessionRoots(env = process.env) {
126
+ return [
127
+ join(env.PI_HOME ?? join(homedir(), '.pi'), 'agent', 'sessions'),
128
+ join(workerBase(env), 'sessions'),
129
+ ];
130
+ }
131
+
132
+ export function findSessionFile(sessionsRoots, sessionId) {
133
+ if (!sessionId) return null;
134
+ const roots = sessionsRoots === null || sessionsRoots === undefined ? []
135
+ : Array.isArray(sessionsRoots) ? sessionsRoots : [sessionsRoots];
136
+ for (const sessionsDir of roots) {
137
+ try {
138
+ const suffix = `_${sessionId}.jsonl`;
139
+ for (const name of readdirSync(sessionsDir)) {
140
+ // Two layouts: Pi's <root>/<cwd-slug>/<ts>_<id>.jsonl and the worker's
141
+ // flat <root>/<ts>_<id>.jsonl (SDK sessions carry no cwd slug).
142
+ if (name.endsWith(suffix)) return join(sessionsDir, name);
143
+ const dir = join(sessionsDir, name);
144
+ let names;
145
+ try { names = readdirSync(dir); } catch { continue; }
146
+ for (const inner of names) {
147
+ if (inner.endsWith(suffix)) return join(dir, inner);
148
+ }
149
+ }
150
+ } catch { /* root missing: fine */ }
151
+ }
152
+ return null;
153
+ }
154
+
155
+ /** Where Pi stores session transcripts on this host (PI_HOME wins, like the CLI). */
156
+ export function sessionsDir(env = process.env) {
157
+ return sessionRoots(env)[0];
158
+ }
159
+
160
+ function metaLine(meta) {
161
+ const bits = [meta.status, meta.reason, meta.paneId, meta.principal, meta.title];
162
+ if (meta.usage) bits.push(`${meta.usage.totalTokens ?? 0} tokens`, `$${meta.usage.costUsd ?? 0}`);
163
+ return bits.filter(Boolean).join(' ');
164
+ }
165
+
166
+ /** Every receipt in every workspace scope becomes one searchable document (host-local). */
167
+ export function collectDocs({ base, sessionsRoot, withTranscripts = true } = {}) {
168
+ const docs = [];
169
+ let scopes = [];
170
+ try { scopes = readdirSync(base).filter(n => SCOPE.test(n)); }
171
+ catch { return docs; }
172
+ for (const scope of scopes) {
173
+ const dir = join(base, scope);
174
+ for (const entry of readJsonl(join(dir, 'receipts.jsonl'), 4 * 1024 * 1024)) {
175
+ if (!entry?.v || !entry.id || !entry.sessionId) continue;
176
+ const meta = {
177
+ id: entry.id, sessionId: entry.sessionId, ts: entry.ts ?? 0,
178
+ status: entry.status, reason: entry.reason, paneId: entry.paneId, usage: entry.usage,
179
+ ...(entry.principal ? { principal: entry.principal } : {}),
180
+ ...(entry.title ? { title: entry.title } : {}),
181
+ };
182
+ let text = metaLine(meta);
183
+ let sessionFile = null;
184
+ if (withTranscripts) {
185
+ sessionFile = findSessionFile(sessionsRoot ?? sessionRoots(), entry.sessionId);
186
+ if (sessionFile) text += '\n' + transcriptText(sessionFile);
187
+ }
188
+ try { text += '\n' + readFileSync(join(dir, 'responses', `${entry.id}.md`), 'utf8').slice(0, BODY_CAP); }
189
+ catch { /* not retained: fine */ }
190
+ docs.push({ id: entry.id, text, meta, sessionFile });
191
+ }
192
+ }
193
+ return docs;
194
+ }
195
+
196
+ /**
197
+ * Device-safe search: full-text scoring host-side, publicReceipt-shaped hits.
198
+ * One hit per session by default (a long transcript owns many receipts; without
199
+ * collapsing it would flood the caller's result page). Never throws.
200
+ */
201
+ export function searchReceipts({ base, sessionsRoot, query, limit = 10, dedupe = true, all = false, withTitle = false } = {}) {
202
+ try {
203
+ const docs = collectDocs({ base, sessionsRoot });
204
+ const ranked = searchIndex(buildIndex(docs), query, docs.length);
205
+ const hits = [];
206
+ const seen = new Set();
207
+ for (const { doc, score } of ranked) {
208
+ if (dedupe && !all && doc.meta.sessionId && seen.has(doc.meta.sessionId)) continue;
209
+ if (doc.meta.sessionId) seen.add(doc.meta.sessionId);
210
+ hits.push({ id: doc.id, score: Math.round(score * 1000) / 1000, ...publicReceipt({ ...doc.meta, v: 1, ts: doc.meta.ts }, { withTitle }) });
211
+ if (hits.length >= Math.max(1, Math.min(50, limit))) break;
212
+ }
213
+ return hits;
214
+ } catch {
215
+ return []; // unreadable journal base: fail closed, no hits
216
+ }
217
+ }
@@ -32,6 +32,76 @@ export function scopeFor(cwd) {
32
32
  return createHash('sha256').update(real).digest('hex').slice(0, 16);
33
33
  }
34
34
 
35
+ // The actor behind a request, on every event trail it touches (herdr-sched §3.1):
36
+ // schedule:<id> | job:<id> | device:<id> | human:<free-tag> — absent means a
37
+ // human typed it locally in a pane and nothing programmatic claims the request.
38
+ export const PRINCIPAL = /^[a-z][a-z0-9-]{0,15}:[A-Za-z0-9._-]{1,64}$/;
39
+
40
+ // A receipt may carry an optional one-line title derived from the prompt
41
+ // (deriveTitle). It is prompt-derived content, so it lives under the strictest
42
+ // leak policy: stored in the host-local journal, never in publicReceipt unless
43
+ // the caller explicitly opts in with withTitle.
44
+ export const TITLE_MAX = 96;
45
+ const TITLE_CTRL = /[\u0000-\u001f\u007f]/; // no control characters (\n, \r, \t included)
46
+
47
+ function validTitle(value) {
48
+ return typeof value === 'string' && value.length >= 1 && value.length <= TITLE_MAX
49
+ && !TITLE_CTRL.test(value);
50
+ }
51
+
52
+ /**
53
+ * First meaningful line of a prompt: drop the first line when it is the request
54
+ * marker (`[herdr-request:…]`) or a scheduler wake frame (`[herdgate-schedule …]`),
55
+ * take the first non-empty line, drop control characters, trim, cap at
56
+ * TITLE_MAX. Returns '' when the prompt says nothing usable — title stays optional.
57
+ */
58
+ export function deriveTitle(promptText) {
59
+ const lines = String(promptText ?? '').split(/\r?\n/);
60
+ const start = /^\[(herdr-request|herdgate-schedule)[^\]]*\]$/.test(lines[0].trim()) ? 1 : 0;
61
+ for (let i = start; i < lines.length; i++) {
62
+ const line = lines[i].replace(TITLE_CTRL, ' ').replace(/\s+/g, ' ').trim();
63
+ if (line) return line.slice(0, TITLE_MAX);
64
+ }
65
+ return '';
66
+ }
67
+
68
+ // Send-path delivery (chat.md useDelivery.ts:120-220 — the transport-vs-app
69
+ // flag, seen from the host side): `delivered` = the host acknowledged the
70
+ // prompt, `stalled` = the transport reported a stall after the host saw it,
71
+ // `unverified` = sent with no acknowledgement. Only the sending transport can
72
+ // observe a stall; the journal writer records what IT observed.
73
+ export const DELIVERY = new Set(['delivered', 'stalled', 'unverified']);
74
+ // Failure phase (mobrel coordinator.go:884 + socket_api.go:157 — "how many
75
+ // bytes reached the socket" as the boundary): `failed_before_dispatch` = the
76
+ // fail happened before the request reached the provider (retry-safe
77
+ // knowledge), `dispatch` = dispatched with the outcome still unknown,
78
+ // `settled` = a final outcome (replied, failed, canceled).
79
+ export const PHASE = new Set(['dispatch', 'settled', 'failed_before_dispatch']);
80
+ // A machine-readable error is bounded like mobrel's ApiError (protocol.go:324):
81
+ // code ≤64 chars, ≤8 args, each string ≤256, total JSON ≤1024. Free-text
82
+ // diagnostics never qualify — without a mappable code there is no error field.
83
+ const ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
84
+ const ERROR_ARGS_MAX = 8;
85
+ const ERROR_STRING_MAX = 256;
86
+ const ERROR_JSON_MAX = 1024;
87
+
88
+ export function validError(error) {
89
+ if (!error || typeof error !== 'object' || Array.isArray(error)) return false;
90
+ if (Object.keys(error).some(key => key !== 'code' && key !== 'args')) return false;
91
+ if (typeof error.code !== 'string' || !ERROR_CODE.test(error.code)) return false;
92
+ if (error.args !== undefined) {
93
+ if (typeof error.args !== 'object' || error.args === null || Array.isArray(error.args)) return false;
94
+ const keys = Object.keys(error.args);
95
+ if (keys.length > ERROR_ARGS_MAX) return false;
96
+ if (!keys.every(key => {
97
+ const value = error.args[key];
98
+ return typeof value === 'string' ? value.length <= ERROR_STRING_MAX
99
+ : typeof value === 'number' ? Number.isFinite(value) : typeof value === 'boolean';
100
+ })) return false;
101
+ }
102
+ return JSON.stringify(error).length <= ERROR_JSON_MAX;
103
+ }
104
+
35
105
  export function validEntry(entry) {
36
106
  return validEntryShape(entry) ? entry : null;
37
107
  }
@@ -44,7 +114,14 @@ function validEntryShape(entry) {
44
114
  && (entry.usage === undefined || (typeof entry.usage === 'object' && entry.usage !== null
45
115
  && Object.keys(entry.usage).length > 0
46
116
  && Object.keys(entry.usage).every(key => ['totalTokens', 'costUsd', 'durationMs'].includes(key))
47
- && Object.values(entry.usage).every(value => Number.isFinite(value)))));
117
+ && Object.values(entry.usage).every(value => Number.isFinite(value)))
118
+ && (entry.principal === undefined || PRINCIPAL.test(entry.principal)))
119
+ && (entry.delivery === undefined || DELIVERY.has(entry.delivery))
120
+ && (entry.phase === undefined || PHASE.has(entry.phase))
121
+ && (entry.error === undefined || validError(entry.error))
122
+ && (entry.title === undefined || validTitle(entry.title))
123
+ && (entry.turns === undefined || (typeof entry.turns === 'number' && Number.isInteger(entry.turns) && entry.turns >= 0))
124
+ && (entry.lastActivityAt === undefined || (typeof entry.lastActivityAt === 'number' && Number.isFinite(entry.lastActivityAt))));
48
125
  }
49
126
 
50
127
  /** Parse a journal file; tolerate a torn tail and skip corrupt lines. */
@@ -85,11 +162,30 @@ export function findReceipt(base, id) {
85
162
  }
86
163
  }
87
164
 
88
- /** The public answer for a device: journal internals stay on the host. */
89
- export function publicReceipt(entry) {
165
+ /** The public answer for a device: journal internals stay on the host.
166
+ * Title is prompt-derived text, so it is withheld by default (fail-safe) and
167
+ * only included when the caller explicitly passes withTitle: true. Measured
168
+ * activity counters (`turns`, `lastActivityAt`) are a count and a timestamp —
169
+ * no conversation content — so they pass through whenever the entry has them. */
170
+ export function publicReceipt(entry, { withTitle = false } = {}) {
90
171
  if (!entry) return { status: 'unknown', reason: 'not_retained_in_runtime' };
91
- const { v, ts, sessionId, paneId, ...rest } = entry;
92
- return rest;
172
+ const { v, ts, sessionId, paneId, title, error, ...rest } = entry;
173
+ // `error` is host-side diagnostics and never leaves the host; devices get
174
+ // the delivery/phase metadata instead. Legacy journals predate both fields:
175
+ // a responseEntryId is itself a delivery proof, so it maps to `delivered` —
176
+ // anything else stays absent rather than guessed.
177
+ const shown = withTitle && title !== undefined ? { ...rest, title } : { ...rest };
178
+ if (shown.delivery === undefined && entry.responseEntryId !== undefined) shown.delivery = 'delivered';
179
+ return shown;
180
+ }
181
+
182
+ /** True when the receipt has not seen activity for longer than staleAfterMs.
183
+ * Only an observed `lastActivityAt` can say so: an entry without the field
184
+ * predates the counter (or was written without transcript access), and the
185
+ * difference is UNKNOWN, not stale — no guessing, fail closed to false. */
186
+ export function isStale(entry, now = Date.now(), staleAfterMs = 30 * 60e3) {
187
+ if (!entry || typeof entry.lastActivityAt !== 'number' || !Number.isFinite(entry.lastActivityAt)) return false;
188
+ return now - entry.lastActivityAt > staleAfterMs;
93
189
  }
94
190
 
95
191
  /**
@@ -132,8 +228,10 @@ export function findBody(base, id) {
132
228
 
133
229
  /**
134
230
  * Watch every workspace journal under base and hand each NEW settle to onEntry
135
- * (unseen id, or a newer ts for a known id). The first scan is a baseline and
136
- * emits nothing, so a restarting publisher does not replay old receipts.
231
+ * (unseen id, or a newer ts for a known id). Two copies of one id inside a
232
+ * single sweep collapse to its newest copy — one emit, never two. The first
233
+ * scan is a baseline and emits nothing, so a restarting publisher does not
234
+ * replay old receipts.
137
235
  * fs.watch (recursive where supported) gives low latency; a slow interval sweep
138
236
  * covers missed events and platforms without recursive watch. A missing base
139
237
  * directory just means the next sweep retries. Never throws to the caller.
@@ -149,15 +247,25 @@ export function watchReceipts(base, onEntry, { intervalMs = 4000 } = {}) {
149
247
  let scopes = [];
150
248
  try { scopes = readdirSync(base).filter(name => /^[0-9a-f]{16}$/.test(name)); }
151
249
  catch { /* base not created yet */ }
250
+ // Mailbox newer-of-two (usage.md refresh.rs:326-344 provider_snapshot_for_display):
251
+ // one sweep can observe two copies of the same id — an event writer and a
252
+ // poll writer racing on one mailbox. Gather everything from every scope,
253
+ // order by (id, ts), and keep only each id's newest copy, so a single sweep
254
+ // emits an id at most once and always the newest copy, never both.
255
+ const rows = [];
152
256
  for (const name of scopes) {
153
257
  let entries;
154
258
  try { entries = readJournal(join(base, name, RECEIPTS)); } catch { continue; }
155
- for (const entry of entries) {
156
- const prior = seen.get(entry.id);
157
- if (prior !== undefined && prior >= entry.ts) continue;
158
- seen.set(entry.id, entry.ts);
159
- if (emit) { try { onEntry(entry); } catch { /* listener errors must not kill the sweep */ } }
160
- }
259
+ rows.push(...entries);
260
+ }
261
+ rows.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : a.ts - b.ts));
262
+ const newest = rows.filter((entry, i) => i + 1 === rows.length || rows[i + 1].id !== entry.id);
263
+ newest.sort((a, b) => a.ts - b.ts || (a.id < b.id ? -1 : 1));
264
+ for (const entry of newest) {
265
+ const prior = seen.get(entry.id);
266
+ if (prior !== undefined && prior >= entry.ts) continue;
267
+ seen.set(entry.id, entry.ts);
268
+ if (emit) { try { onEntry(entry); } catch { /* listener errors must not kill the sweep */ } }
161
269
  }
162
270
  };
163
271
  const ensureWatcher = () => {