@bom0792/herdgate 0.9.37 → 0.9.38

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,217 @@
1
+ // Pi session transcript parser (see docs/research/2026-11-21-marketplace/deep/
2
+ // usage.md — ported from herdr-agent-usage src/pi.rs, MIT): tail-window read of
3
+ // at most `maxBytes` (default 8MB), opened on exact line boundaries — the line
4
+ // cut by the window start is dropped, not parsed; the window is measured from
5
+ // the length at read time so a line appended mid-read waits for the next pass.
6
+ // A file larger than the window also keeps a 64KB header read so the `session`
7
+ // header (id + version) is always available.
8
+ // The active branch is walked newest→root by id/parentId (a windowed
9
+ // transcript accepts a parent that lives before the window). Model comes from
10
+ // the last `model_change` on the branch (assistant message model as fallback),
11
+ // contextTokens from the newest assistant usage AFTER the last `compaction`
12
+ // (contextTokens || totalTokens || Σ of the four counters), and usageTotal
13
+ // sums usage of assistant/toolResult messages plus `branch_summary` and
14
+ // `compaction` entries — Pi's own session-stat aggregation. Entry schema is
15
+ // exactly what the herdgate receipt observer reads (experiments/pi-receipt/
16
+ // observer.js) and what Pi 1.5.2 writes. A broken or absent transcript yields
17
+ // {error: 'unreadable', file} — never a throw, never a guess.
18
+
19
+ import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
20
+ import { basename } from 'node:path';
21
+ import { StringDecoder } from 'node:string_decoder';
22
+
23
+ const DEFAULT_MAX_BYTES = 8 * 1024 * 1024; // MAX_SESSION_BYTES
24
+ const HEADER_BYTES = 64 * 1024;
25
+ const MAX_BRANCH = 65_536; // branch walk cap; the seen-set guards cycles
26
+
27
+ /** stem == sessionId or `*_<sessionId>` (pi.rs filename_matches_session_id). */
28
+ export function filenameMatchesSessionId(name, sessionId) {
29
+ const stem = String(name).replace(/\.jsonl$/, '');
30
+ return stem === sessionId || stem.endsWith(`_${sessionId}`);
31
+ }
32
+
33
+ function readRange(fd, start, end, decoder) {
34
+ const chunks = [];
35
+ let pos = start;
36
+ while (pos < end) {
37
+ const buf = Buffer.alloc(Math.min(64 * 1024, end - pos));
38
+ const n = readSync(fd, buf, 0, buf.length, pos);
39
+ if (!n) break; // file shrank mid-read — take what is there
40
+ chunks.push(decoder.write(buf.subarray(0, n)));
41
+ pos += n;
42
+ }
43
+ chunks.push(decoder.end());
44
+ return chunks.join('');
45
+ }
46
+
47
+ /**
48
+ * Read the header window (first 64KB) and the newest `maxBytes` of the file on
49
+ * line boundaries. Whole file when it fits; otherwise the header line cut at
50
+ * 64KB and the tail line cut by the window start are both dropped.
51
+ */
52
+ function readWindows(filePath, maxBytes) {
53
+ const fd = openSync(filePath, constants.O_RDONLY | (constants.O_NONBLOCK ?? 0));
54
+ try {
55
+ const size = fstatSync(fd).size;
56
+ if (size <= maxBytes) {
57
+ const lines = readRange(fd, 0, size, new StringDecoder('utf8')).split('\n');
58
+ if (lines.length && lines[lines.length - 1] === '') lines.pop(); // trailing newline
59
+ return { header: lines, tail: lines, windowed: false };
60
+ }
61
+ const header = readRange(fd, 0, Math.min(HEADER_BYTES, size), new StringDecoder('utf8')).split('\n');
62
+ header.pop(); // the line the header window cuts is not parsed
63
+ const tail = readRange(fd, size - maxBytes, size, new StringDecoder('utf8')).split('\n');
64
+ tail.shift(); // the line the window start cuts is dropped, not parsed
65
+ if (tail.length && tail[tail.length - 1] === '') tail.pop();
66
+ return { header, tail, windowed: true };
67
+ } finally {
68
+ try { closeSync(fd); } catch { /* already closed */ }
69
+ }
70
+ }
71
+
72
+ function parseJsonObjects(lines) {
73
+ const entries = [];
74
+ for (const line of lines) {
75
+ if (!line.trim()) continue;
76
+ try {
77
+ const entry = JSON.parse(line);
78
+ if (entry && typeof entry === 'object' && !Array.isArray(entry)) entries.push(entry);
79
+ } catch {
80
+ continue; // corrupt or torn line — skipped, never fatal
81
+ }
82
+ }
83
+ return entries;
84
+ }
85
+
86
+ const finite = value => (Number.isFinite(value) ? value : 0);
87
+
88
+ /** contextTokens || totalTokens || Σ of the four counters (saturating). */
89
+ function contextTokensOf(usage) {
90
+ if (!usage) return null;
91
+ if (Number.isFinite(usage.contextTokens)) return usage.contextTokens;
92
+ if (Number.isFinite(usage.totalTokens)) return usage.totalTokens;
93
+ const sum = finite(usage.input) + finite(usage.output) + finite(usage.cacheRead) + finite(usage.cacheWrite);
94
+ return sum;
95
+ }
96
+
97
+ /**
98
+ * Parse a Pi session JSONL transcript.
99
+ * Returns {sessionId, model, modelProvider, contextTokens, usageTotal:
100
+ * {totalTokens, costUsd}, usageCoversSession, turns, lastTs} — `model` from
101
+ * the last model_change on the active branch, `contextTokens` after the last
102
+ * compaction, `turns` counts assistant messages on the branch, `lastTs` is
103
+ * the newest message timestamp (message ms first, entry ISO as fallback,
104
+ * session header as last resort, null when nothing carries one).
105
+ * usageCoversSession is false when the tail window dropped older lines (a
106
+ * windowed sum is a lower bound, not the session total).
107
+ * Unreadable/absent/invalid → {error: 'unreadable', file}. Never throws.
108
+ */
109
+ export function parsePiTranscript(filePath, maxBytes = DEFAULT_MAX_BYTES) {
110
+ let windows;
111
+ try {
112
+ windows = readWindows(filePath, Number.isFinite(maxBytes) && maxBytes > 0 ? maxBytes : DEFAULT_MAX_BYTES);
113
+ } catch {
114
+ return { error: 'unreadable', file: filePath };
115
+ }
116
+ const session = parseJsonObjects(windows.header).find(entry => entry.type === 'session');
117
+ const sessionId = session?.id;
118
+ if (!session || Number(session.version) !== 3 || typeof sessionId !== 'string'
119
+ || sessionId.length === 0 || !filenameMatchesSessionId(basename(String(filePath)), sessionId)) {
120
+ return { error: 'unreadable', file: filePath };
121
+ }
122
+
123
+ const entries = parseJsonObjects(windows.tail).filter(entry => entry.type !== 'session' && typeof entry.id === 'string');
124
+ const byId = new Map(entries.map(entry => [entry.id, entry]));
125
+
126
+ // Active branch: newest entry → root by parentId. A parent that lives before
127
+ // the window is simply not in byId — the walk stops there (accepted).
128
+ const branch = [];
129
+ const seen = new Set();
130
+ let cursor = entries.length ? entries[entries.length - 1] : undefined;
131
+ while (cursor && !seen.has(cursor.id) && branch.length < MAX_BRANCH) {
132
+ seen.add(cursor.id);
133
+ branch.push(cursor);
134
+ const parentId = cursor.parentId;
135
+ cursor = typeof parentId === 'string' ? byId.get(parentId) : undefined;
136
+ }
137
+ branch.reverse(); // root → leaf
138
+
139
+ let model = null;
140
+ let modelProvider = null;
141
+ let lastCompaction = -1;
142
+ let turns = 0;
143
+ let lastTs = null;
144
+ let newestAssistant = null; // whole branch
145
+ for (let i = 0; i < branch.length; i++) {
146
+ const entry = branch[i];
147
+ if (entry.type === 'model_change') {
148
+ if (typeof entry.modelId === 'string') model = entry.modelId;
149
+ if (typeof entry.provider === 'string') modelProvider = entry.provider;
150
+ }
151
+ if (entry.type === 'compaction') lastCompaction = i;
152
+ if (entry.type === 'message' && entry.message) {
153
+ const message = entry.message;
154
+ if (message.role === 'assistant') {
155
+ turns++;
156
+ newestAssistant = message; // branch runs root→leaf, so the last wins
157
+ }
158
+ const ms = Number(message.timestamp);
159
+ if (Number.isFinite(ms) && ms > lastTs) lastTs = ms;
160
+ else {
161
+ const iso = Date.parse(entry.timestamp);
162
+ if (Number.isFinite(iso) && iso > lastTs) lastTs = iso;
163
+ }
164
+ }
165
+ }
166
+ if (model === null && typeof newestAssistant?.model === 'string') model = newestAssistant.model;
167
+ if (modelProvider === null && typeof newestAssistant?.provider === 'string') modelProvider = newestAssistant.provider;
168
+
169
+ // Context is measured after the last compaction — the newest assistant
170
+ // message from there on; with no compaction the newest assistant overall.
171
+ let contextUsage = null;
172
+ if (lastCompaction >= 0) {
173
+ for (let i = branch.length - 1; i > lastCompaction; i--) {
174
+ const message = branch[i].message;
175
+ if (branch[i].type === 'message' && message?.role === 'assistant' && message.usage) {
176
+ contextUsage = message.usage;
177
+ break;
178
+ }
179
+ }
180
+ } else if (newestAssistant?.usage) contextUsage = newestAssistant.usage;
181
+ const contextTokens = contextUsage ? contextTokensOf(contextUsage) : null;
182
+
183
+ // Session totals over the window: assistant and toolResult message usage,
184
+ // plus `usage`, `branch_summary` and `compaction` entry usage (Pi's own
185
+ // getSessionStats aggregation). A windowed sum is a lower bound.
186
+ let totalTokens = 0;
187
+ let costUsd = 0;
188
+ for (const entry of entries) {
189
+ let usage = null;
190
+ if (entry.type === 'usage') usage = entry.usage;
191
+ else if (entry.type === 'branch_summary' || entry.type === 'compaction') usage = entry.usage;
192
+ else if (entry.type === 'message') {
193
+ const role = entry.message?.role;
194
+ if (role === 'assistant' || role === 'toolResult') usage = entry.message.usage;
195
+ }
196
+ if (!usage) continue;
197
+ totalTokens += Number.isFinite(usage.totalTokens)
198
+ ? usage.totalTokens
199
+ : finite(usage.input) + finite(usage.output) + finite(usage.cacheRead) + finite(usage.cacheWrite);
200
+ costUsd += finite(usage.cost?.total);
201
+ }
202
+ if (lastTs === null) {
203
+ const headerTs = Date.parse(session.timestamp);
204
+ if (Number.isFinite(headerTs)) lastTs = headerTs;
205
+ }
206
+
207
+ return {
208
+ sessionId,
209
+ ...(model !== null ? { model } : {}),
210
+ ...(modelProvider !== null ? { modelProvider } : {}),
211
+ ...(contextTokens !== null ? { contextTokens } : {}),
212
+ usageTotal: { totalTokens, costUsd },
213
+ usageCoversSession: !windows.windowed,
214
+ turns,
215
+ lastTs,
216
+ };
217
+ }
@@ -0,0 +1,84 @@
1
+ // Usage roll-up over the experimental Pi receipt journal (see experiments/pi-receipt).
2
+ // Aggregates every workspace scope into daily buckets and per-principal spend —
3
+ // the host-local twin of receipt search: no bodies, no session files, just counts.
4
+ // Fail-closed like the other journal readers: an unreadable base yields a zeroed
5
+ // roll-up, never a throw; corrupt entries are already filtered by readJournal.
6
+
7
+ import { readdirSync } from 'node:fs';
8
+ import { join } from 'node:path';
9
+ import { readJournal } from './pi-receipts.mjs';
10
+
11
+ const SCOPE = /^[0-9a-f]{16}$/; // one hashed dir per Pi workspace
12
+ const RECEIPTS = 'receipts.jsonl';
13
+ const HUMAN = '(human)'; // principal absent → a human typed it in a pane
14
+
15
+ const newTotal = () => ({ requests: 0, replied: 0, failed: 0, canceled: 0, unknown: 0, tokens: 0, costUsd: 0 });
16
+ const newBucket = extra => ({ ...extra, requests: 0, replied: 0, failed: 0, tokens: 0, costUsd: 0 });
17
+
18
+ /** Fold one receipt into a bucket; status keys exist only where the shape has them. */
19
+ function fold(bucket, entry) {
20
+ bucket.requests += 1;
21
+ if (bucket[entry.status] !== undefined) bucket[entry.status] += 1;
22
+ bucket.tokens += entry.usage?.totalTokens ?? 0; // missing usage counts as zero
23
+ bucket.costUsd += entry.usage?.costUsd ?? 0;
24
+ }
25
+
26
+ const pad2 = n => String(n).padStart(2, '0');
27
+ const localDate = ts => {
28
+ const d = new Date(ts);
29
+ return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
30
+ };
31
+
32
+ /**
33
+ * Roll receipts from every workspace scope under base into one summary: totals,
34
+ * `days` daily buckets (newest first, local dates) and per-principal totals
35
+ * sorted by spend. Duplicate receipt ids collapse to the newest ts — compaction
36
+ * already dedupes within one scope, but two scopes may have seen the same
37
+ * request. Never throws; an unreadable base returns the zeroed shape.
38
+ */
39
+ export function usageRollup({ base, days = 7, now = Date.now() } = {}) {
40
+ const at = Number.isFinite(now) ? now : Date.now();
41
+ const span = Number.isFinite(days) ? Math.max(0, Math.floor(days)) : 7;
42
+
43
+ // Local-day keys, newest first; stepping through the Date constructor so a
44
+ // DST shift inside the window cannot split or duplicate a calendar day.
45
+ const anchor = new Date(at);
46
+ const dayBuckets = new Map();
47
+ for (let back = 0; back < span; back++) {
48
+ const key = localDate(new Date(anchor.getFullYear(), anchor.getMonth(), anchor.getDate() - back).getTime());
49
+ dayBuckets.set(key, newBucket({ date: key }));
50
+ }
51
+
52
+ const latest = new Map(); // id -> entry; newest ts wins, ties keep the last seen
53
+ try {
54
+ for (const name of readdirSync(base)) {
55
+ if (!SCOPE.test(name)) continue;
56
+ let entries;
57
+ try { entries = readJournal(join(base, name, RECEIPTS)); } catch { continue; }
58
+ for (const entry of entries) {
59
+ const prior = latest.get(entry.id);
60
+ if (prior === undefined || prior.ts <= entry.ts) latest.set(entry.id, entry);
61
+ }
62
+ }
63
+ } catch { /* unreadable base: fall through to the zeroed shape */ }
64
+
65
+ const total = newTotal();
66
+ const principals = new Map();
67
+ for (const entry of latest.values()) {
68
+ fold(total, entry);
69
+ const day = dayBuckets.get(localDate(entry.ts)); // outside the window: totals only
70
+ if (day) fold(day, entry);
71
+ const key = entry.principal ?? HUMAN;
72
+ let bucket = principals.get(key);
73
+ if (!bucket) { bucket = newBucket({ principal: key, lastTs: entry.ts }); principals.set(key, bucket); }
74
+ fold(bucket, entry);
75
+ if (entry.ts > bucket.lastTs) bucket.lastTs = entry.ts;
76
+ }
77
+
78
+ return {
79
+ generatedAt: at,
80
+ total,
81
+ days: [...dayBuckets.values()], // insertion order == newest first
82
+ byPrincipal: [...principals.values()].sort((a, b) => b.costUsd - a.costUsd),
83
+ };
84
+ }
@@ -0,0 +1,319 @@
1
+ // Wake-on-settle: when a spawned child's receipt settles, wake the PARENT
2
+ // agent's pane with a one-line frame — the controller never polls, never holds
3
+ // a watch process; the alert arrives as its next input (the same pattern as
4
+ // scheduler wake frames). Spawn registry supplies the parent edge; herdr pane
5
+ // run delivers. The live path is the herdr [[events]] hook (server/wake-event.mjs):
6
+ // herdr observes the child, so wake survives a child that never arms or dies
7
+ // with its pane. Failures (blocked parent, gone pane, herdr down) log and drop
8
+ // — a missed wake is recoverable from the journal, a crash is not.
9
+ import { execFileSync } from 'node:child_process';
10
+ import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
11
+ import { dirname, join } from 'node:path';
12
+ import { readSpawns } from '../../experiments/pi-spawn/registry.mjs';
13
+ import { findReceipt } from './pi-receipts.mjs';
14
+
15
+ const note = (line) => console.error(`herdgate pi-wake: ${line}`);
16
+
17
+ const SCOPE = /^[0-9a-f]{16}$/;
18
+ /** A receipt that proves the child finished speaking — anything else is silence.
19
+ * Final settles (replied/failed/canceled) wake a parent; invalidated/expired
20
+ * intents (unknown) carry no result to act on, and a vanished child belongs
21
+ * to the death watch below. */
22
+ export const SETTLED = new Set(['replied', 'failed', 'canceled']);
23
+
24
+ /** The handling directive that rides IN every settle frame, on purpose: the
25
+ * protocol must survive context compaction in the parent — a bare status line
26
+ * gets a bare ack (observed live); the instruction makes every wake
27
+ * self-describing. Shared by the journal-watch frame and the herdr-event
28
+ * frame (server/wake-event.mjs) so the wording never forks. */
29
+ export const SETTLE_DIRECTIVE = ' → việc con đã settle. LÀM TRỌN TRONG TURN NÀY: chạy test mục tiêu, review diff, commit nếu đạt, rồi báo user ngắn gọn — không chỉ ack.';
30
+
31
+ /** Every spawn record across workspace scopes (spawn + self declarations). */
32
+ export function readAllSpawns(base) {
33
+ const out = [];
34
+ let scopes = [];
35
+ try { scopes = readdirSync(base).filter(n => SCOPE.test(n)); }
36
+ catch { return out; }
37
+ for (const scope of scopes) {
38
+ for (const entry of readSpawns(join(base, scope, 'spawns.jsonl'))) out.push(entry);
39
+ }
40
+ return out;
41
+ }
42
+
43
+ /** The spawn edge for a child session: controller records win over self-declared. */
44
+ export function parentOf(spawns, childSessionId) {
45
+ return spawns.find(s => s.sessionId === childSessionId && s.parentSessionId && !s.self)
46
+ ?? spawns.find(s => s.sessionId === childSessionId && s.parentSessionId)
47
+ ?? null;
48
+ }
49
+
50
+ /** The pane currently showing a session (its agent_session file ends _<id>.jsonl). */
51
+ export function paneForSession(panes, sessionId) {
52
+ const suffix = `_${sessionId}.jsonl`;
53
+ const pane = (panes ?? []).find(p => typeof p?.agent_session?.value === 'string'
54
+ && p.agent_session.value.endsWith(suffix));
55
+ return pane?.pane_id ?? null;
56
+ }
57
+
58
+ /** One terse line: enough for the parent to act, never the reply text. */
59
+ export function wakeFrame(entry, spawn) {
60
+ const bits = [`[herdgate-wake child=${spawn.name ?? 'child'}`, `id=${entry.id}`, `status=${entry.status}`];
61
+ if (entry.reason) bits.push(`reason=${entry.reason}`);
62
+ if (entry.title) bits.push(`title="${String(entry.title).replace(/\s+/g, ' ').slice(0, 60)}"`);
63
+ if (entry.usage && Number.isFinite(entry.usage.totalTokens)) bits.push(`tokens=${entry.usage.totalTokens}`);
64
+ bits.push(`ts=${new Date(entry.ts).toISOString()}]`);
65
+ const line = bits.join(' ') + SETTLE_DIRECTIVE;
66
+ return line.length <= 480 ? line : `${bits.join(' ').slice(0, 300)}…]${SETTLE_DIRECTIVE}`;
67
+ }
68
+
69
+ /** Resolve the parent's pane and deliver one frame once the parent is quietly
70
+ * between turns. Shared by settle wakes, death wakes AND the herdr event hook
71
+ * (server/wake-event.mjs) — the quiet-wait protocol below is the load-bearing
72
+ * part and must never fork the tree.
73
+ *
74
+ * Delivery waits for the parent to be BETWEEN TURNS, stably. Two live
75
+ * incidents (wtest2, wfork1) showed why "idle" alone is not enough: herdr
76
+ * flips the agent idle milliseconds BEFORE the turn's final message lands, so
77
+ * a wake injected at that instant becomes a PENDING message, and Pi's pending
78
+ * queue then forks the session tree from a stale leaf — the handling turn runs
79
+ * in full on an orphan branch that neither the human's view nor the parent's
80
+ * context ever adopts, and everyone swears nothing arrived. Waiting for the
81
+ * agent revision to hold steady across two probes proves the turn truly
82
+ * closed; the injected text then submits against the live leaf. */
83
+ export function deliverToParent({ spawn, line, label, run, listPanes, agentState, agentProbe, onDelivered, generation,
84
+ log = () => {}, retryDelayMs = () => new Promise(r => setTimeout(r, 3000)), settleDelayMs = () => new Promise(r => setTimeout(r, 2000)), maxWaitMs = 15 * 60 * 1000 }) {
85
+ const deliver = (pane, waited, seenRevision) => {
86
+ // Generation drift (herdr-sesh requestID, adapted): the caller captured the
87
+ // parent's revision at fire time; if the parent turned while we waited for
88
+ // a quiet moment the token no longer matches — but a wake is NOT a UI
89
+ // refresh, dropping it is unrecoverable, so the frame still goes and the
90
+ // drift is logged for the trail.
91
+ if (generation != null && seenRevision != null && seenRevision !== generation) {
92
+ log(`wake: parent pane ${pane} revision drifted ${generation}->${seenRevision} while waiting — delivering anyway (child ${spawn.name} ${label})`);
93
+ }
94
+ try {
95
+ // pane run TYPES into the parent's terminal — the same live-branch path
96
+ // as /herdgate-arm markers. herdr agent prompt submits through the
97
+ // agent/RPC handle whose leaf pointer stagnates after one fork: every
98
+ // wake then extends an orphan branch no one ever sees (three live
99
+ // incidents, each parented to the previous orphan's leaf).
100
+ run('pane', 'run', pane, line);
101
+ log(`wake: child ${spawn.name} ${label} -> parent pane ${pane}${waited ? ` (waited ${(waited / 1000) | 0}s for a quiet parent)` : ''}`);
102
+ // Bookkeeping AFTER the frame landed (episode dedupe sidecars etc.) — a
103
+ // failure here must never undo or retry a delivered wake.
104
+ try { onDelivered?.(); } catch { /* never fatal */ }
105
+ } catch (error) {
106
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`); // agent_blocked etc: never fatal
107
+ }
108
+ };
109
+ const panes = listPanes();
110
+ // The parent's REAL pane, recorded at spawn time. Session-file lookup alone
111
+ // is ambiguous: a second pi bound to the same session (a restore leftover)
112
+ // makes every wake land in the ghost — observed live, four times.
113
+ let pane = spawn.parentPaneId && panes.some(p => p?.pane_id === spawn.parentPaneId)
114
+ ? spawn.parentPaneId
115
+ : paneForSession(panes, spawn.parentSessionId);
116
+ if (!pane) {
117
+ log(`wake: parent ${String(spawn.parentSessionId).slice(0, 8)} pane gone — child ${spawn.name} ${label}`);
118
+ return;
119
+ }
120
+ if (!agentProbe) {
121
+ // Legacy single-state probe: idle means deliver (kept for callers
122
+ // without a revision; the rich probe above is the safe path).
123
+ if (!agentState) return deliver(pane, 0);
124
+ const started = Date.now();
125
+ const attemptState = () => {
126
+ let state = 'unknown';
127
+ try { state = agentState(pane) ?? 'unknown'; }
128
+ catch { state = 'unknown'; }
129
+ if (state === 'idle') return deliver(pane, Date.now() - started);
130
+ if (Date.now() - started >= maxWaitMs) {
131
+ return log(`wake: parent pane ${pane} stayed ${state} for ${(maxWaitMs / 60000) | 0}min — dropped wake for ${spawn.name} (journal keeps the settle)`);
132
+ }
133
+ void retryDelayMs().then(attemptState);
134
+ };
135
+ return attemptState();
136
+ }
137
+ const started = Date.now();
138
+ const attempt = () => {
139
+ let probe = null;
140
+ try { probe = agentProbe(pane); } catch { probe = null; }
141
+ const state = probe?.status ?? 'unknown';
142
+ if (state === 'working' || state === 'blocked' || !probe) {
143
+ if (Date.now() - started >= maxWaitMs) {
144
+ return log(`wake: parent pane ${pane} stayed ${state} for ${(maxWaitMs / 60000) | 0}min — dropped wake for ${spawn.name} (journal keeps the settle)`);
145
+ }
146
+ return void retryDelayMs().then(attempt);
147
+ }
148
+ // Idle-ish: prove the turn CLOSED — the revision must hold across a settle delay.
149
+ void settleDelayMs().then(() => {
150
+ let again = null;
151
+ try { again = agentProbe(pane); } catch { again = null; }
152
+ if (again && again.status !== 'working' && again.status !== 'blocked' && again.revision === probe.revision) {
153
+ return deliver(pane, Date.now() - started, again.revision);
154
+ }
155
+ if (Date.now() - started >= maxWaitMs) {
156
+ return log(`wake: parent pane ${pane} never quieted (${state}→${again?.status ?? '?'}, rev ${probe.revision}→${again?.revision ?? '?'}) — dropped wake for ${spawn.name}`);
157
+ }
158
+ void retryDelayMs().then(attempt);
159
+ });
160
+ };
161
+ attempt();
162
+ }
163
+
164
+ /** Build the onSettle callback for watchReceipts. */
165
+ export function wakeParentOnSettle({ spawnBase, run, listPanes, agentState, agentProbe, log = () => {}, retryDelayMs, settleDelayMs, maxWaitMs }) {
166
+ return (entry) => {
167
+ try {
168
+ if (!entry?.sessionId || !entry?.id) return;
169
+ if (!SETTLED.has(entry.status)) {
170
+ return log(`wake: ${entry.id} settled ${entry.status} — not a final settle, no parent wake`);
171
+ }
172
+ const spawn = parentOf(readAllSpawns(spawnBase), entry.sessionId);
173
+ if (!spawn) return; // not a spawned child: nothing to wake
174
+ deliverToParent({ spawn, line: wakeFrame(entry, spawn), label: entry.status,
175
+ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs });
176
+ } catch (error) {
177
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`); // agent_blocked etc: never fatal
178
+ }
179
+ };
180
+ }
181
+
182
+ /** The herdr-pings lesson: a child that dies with its pane (bridge crash) never
183
+ * settles, so no journal event can ever fire a wake — the silence IS the
184
+ * failure. The banner follows the wake-skill format so the parent's handling
185
+ * protocol recognizes the frame and acts inside its turn. */
186
+ export function deathFrame(spawn) {
187
+ return `🔔 WAKE — agent ${spawn?.name ?? 'child'} DIED: pane biến mất chưa kịp settle — kiểm tra registry, restore nếu cần`;
188
+ }
189
+
190
+ /** Wake a parent about a lost child (pane vanished before any final settle). */
191
+ export function wakeParentOnDeath({ run, listPanes, agentState, agentProbe, log = () => {}, retryDelayMs, settleDelayMs, maxWaitMs }) {
192
+ return (spawn) => {
193
+ try {
194
+ if (!spawn?.parentSessionId) return;
195
+ deliverToParent({ spawn, line: deathFrame(spawn), label: 'DIED',
196
+ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs });
197
+ } catch (error) {
198
+ log(`wake failed: ${error instanceof Error ? error.message : String(error)}`);
199
+ }
200
+ };
201
+ }
202
+
203
+ /** Stamp+byte-verified persistence — herdcats follower.rs:483-488 applied to
204
+ * writes instead of tailing: tmp+rename, then read the file BACK and compare
205
+ * every byte, taking a stat stamp before AND after the read so a read racing
206
+ * another rewrite is detected rather than trusted (mtime/size alone lie — a
207
+ * same-length rewrite is invisible to them). A miss rewrites exactly ONCE;
208
+ * a second miss logs and gives up — never throws: bookkeeping must not kill
209
+ * a wake. `readback` is the host-trait seam (herdr-sidebar FakeRefresh
210
+ * style): tests inject lying reads to prove the retry; production always
211
+ * reads the real file. */
212
+ export function writeFileVerified(file, bytes, { log = note, readback = null } = {}) {
213
+ const data = Buffer.isBuffer(bytes) ? bytes : Buffer.from(String(bytes), 'utf8');
214
+ const stampOf = (st) => (st ? `${st.dev ?? 0}:${st.ino ?? 0}:${st.size}:${st.mtimeMs}` : null);
215
+ const realReadback = (path) => {
216
+ try {
217
+ const before = stampOf(statSync(path));
218
+ const back = readFileSync(path);
219
+ const after = stampOf(statSync(path));
220
+ return before && after && before === after ? back : null; // moved under us: not trustworthy
221
+ } catch { return null; }
222
+ };
223
+ const verify = (path, attempt) => (readback ? readback(path, attempt) : realReadback(path));
224
+ const attempt = (n) => {
225
+ try {
226
+ mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
227
+ const tmp = `${file}.tmp`;
228
+ writeFileSync(tmp, data, { mode: 0o600 });
229
+ rmSync(file, { force: true });
230
+ renameSync(tmp, file);
231
+ } catch (error) {
232
+ log(`verified write #${n} failed for ${file}: ${error instanceof Error ? error.message : String(error)}`);
233
+ return false;
234
+ }
235
+ const back = verify(file, n);
236
+ return back !== null && back.length === data.length && back.equals(data);
237
+ };
238
+ if (attempt(1)) return true;
239
+ if (attempt(2)) return true; // hụt → ghi lại đúng một lần, rồi đọc lại lần nữa
240
+ log(`verified write still mismatches for ${file} after one retry — giving up (not fatal)`);
241
+ return false;
242
+ }
243
+
244
+ /** Patch one spawn record inside the scope file that actually holds it. The
245
+ * registry's own updateSpawn patches only the caller's cwd scope — the
246
+ * publisher daemon sits elsewhere, so deaths are marked wherever the record
247
+ * lives. Returns the updated record, or null when no scope holds the id. */
248
+ export function patchSpawn(base, id, patch) {
249
+ let scopes = [];
250
+ try { scopes = readdirSync(base).filter(name => SCOPE.test(name)); }
251
+ catch { return null; }
252
+ for (const scope of scopes) {
253
+ const file = join(base, scope, 'spawns.jsonl');
254
+ const entries = readSpawns(file);
255
+ if (!entries.some(entry => entry.id === id)) continue;
256
+ let updated = null;
257
+ const next = entries.map(entry => entry.id === id ? (updated = { ...entry, ...patch }) : entry);
258
+ // Stamp+byte-verified: the mark (died/closedBy) is what keeps ONE frame per
259
+ // child — a write that silently misses would re-fire wakes forever.
260
+ if (!writeFileVerified(file, `${next.map(entry => JSON.stringify(entry)).join('\n')}\n`)) return null;
261
+ return updated;
262
+ }
263
+ return null;
264
+ }
265
+
266
+ /** Children whose pane vanished before any final settle — the death-watch
267
+ * candidates. ONLY records with a parent-pane edge qualify: human panes and
268
+ * self-declared worker sessions are never watched. An empty pane list means
269
+ * herdr itself is unreachable/restarting — that is not six deaths, it is zero
270
+ * answers; fail silent instead of spamming DIED frames. */
271
+ export function scanSpawnDeaths({ spawnBase, listPanes }) {
272
+ let panes = [];
273
+ try { panes = listPanes() ?? []; }
274
+ catch { return []; }
275
+ if (!panes.length) return [];
276
+ const alive = new Set(panes.map(p => p?.pane_id).filter(Boolean));
277
+ const dead = [];
278
+ for (const spawn of readAllSpawns(spawnBase)) {
279
+ if (!spawn.parentPaneId || !spawn.paneId) continue; // no parent edge: not ours to watch
280
+ if (spawn.died === true || spawn.closedBy === 'parent') continue; // already reported / closed on purpose
281
+ if (alive.has(spawn.paneId)) continue; // pane still there
282
+ const receipt = findReceipt(spawnBase, spawn.id);
283
+ if (receipt && SETTLED.has(receipt.status)) continue; // settled in time; the close was earned
284
+ dead.push(spawn);
285
+ }
286
+ return dead;
287
+ }
288
+
289
+ /** The publisher's 30s death watch (a script poll, never the journal watcher):
290
+ * scan → mark died:true in the registry FIRST (one DIED per child, never a
291
+ * spam loop) → wake the parent through the same quiet-delivery path. */
292
+ export function watchSpawnDeaths({ spawnBase, run, listPanes, agentState, agentProbe, log = () => {}, intervalMs = 30_000, retryDelayMs, settleDelayMs, maxWatchMs }) {
293
+ const wakeOne = wakeParentOnDeath({ run, listPanes, agentState, agentProbe, log, retryDelayMs, settleDelayMs, maxWaitMs: maxWatchMs });
294
+ const tick = () => {
295
+ let dead = [];
296
+ try { dead = scanSpawnDeaths({ spawnBase, listPanes }); }
297
+ catch (error) {
298
+ return log(`death scan failed: ${error instanceof Error ? error.message : String(error)}`);
299
+ }
300
+ for (const spawn of dead) {
301
+ const marked = patchSpawn(spawnBase, spawn.id, { died: true, diedAt: Date.now() });
302
+ if (!marked) continue; // record vanished mid-scan: nothing to wake about
303
+ log(`death: child ${spawn.name} pane ${spawn.paneId} vanished before settling — waking the parent`);
304
+ wakeOne(marked);
305
+ }
306
+ };
307
+ const timer = setInterval(tick, intervalMs);
308
+ timer.unref?.();
309
+ return () => clearInterval(timer);
310
+ }
311
+
312
+ /** Default herdr runner for the publisher process (tolerates plain-text output). */
313
+ export function herdrRunner() {
314
+ const bin = process.env.HERDR_BIN_PATH ?? 'herdr';
315
+ return (...args) => {
316
+ const out = execFileSync(bin, args, { encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 });
317
+ try { return JSON.parse(out); } catch { return { raw: out }; }
318
+ };
319
+ }
@@ -6,9 +6,13 @@ import { createHash } from 'node:crypto';
6
6
  import { homedir } from 'node:os';
7
7
  import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
8
8
  import { dirname, isAbsolute, join } from 'node:path';
9
+ // Same contract as receipts: the actor that caused this job (schedule:<id>,
10
+ // device:<id>…) rides along to the journal when the worker settles it.
11
+ import { PRINCIPAL } from './pi-receipts.mjs';
9
12
 
10
13
  export const JOB_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
11
14
  export const MAX_PROMPT = 16 * 1024; // admission bound for one prompt
15
+ export const MAX_RUN = 2048; // admission bound for one shell command (run jobs)
12
16
  export const MAX_PENDING = 100; // queued + running jobs admitted at once
13
17
  export const JOB_STATES = new Set(['queued', 'running', 'replied', 'failed', 'canceled', 'unknown']);
14
18
  /** Routing key a device may reference — resolved against the host's allowlist. */
@@ -74,12 +78,21 @@ export function validJob(job) {
74
78
  return validJobShape(job) ? job : null;
75
79
  }
76
80
 
81
+ const validPrompt = value => typeof value === 'string' && value.length <= MAX_PROMPT;
82
+ const validRun = value => typeof value === 'string' && value.length >= 1
83
+ && value.length <= MAX_RUN && !value.includes('\0');
84
+
77
85
  function validJobShape(job) {
78
86
  return Boolean(job && job.v === 1 && JOB_ID.test(job.id ?? '')
79
87
  && JOB_STATES.has(job.state)
80
- && typeof job.prompt === 'string' && job.prompt.length <= MAX_PROMPT
88
+ // Payload: a model prompt, a shell command (run job), or both (the worker
89
+ // takes run). Whichever fields are present must each be well-formed.
90
+ && (validPrompt(job.prompt) || validRun(job.run))
91
+ && (job.prompt === undefined || validPrompt(job.prompt))
92
+ && (job.run === undefined || validRun(job.run))
81
93
  && typeof job.ts === 'number'
82
94
  && (job.workspace === undefined || WORKSPACE_NAME.test(job.workspace))
95
+ && (job.principal === undefined || PRINCIPAL.test(job.principal))
83
96
  && ['sessionId', 'reason', 'requestEntryId', 'responseEntryId'].every(key =>
84
97
  job[key] === undefined || typeof job[key] === 'string'));
85
98
  }
@@ -107,10 +120,10 @@ export function appendJob(file, job) {
107
120
  appendFileSync(file, `${JSON.stringify(job)}\n`, { mode: 0o600 });
108
121
  }
109
122
 
110
- /** The public answer for a device: the prompt never leaves the host. */
123
+ /** The public answer for a device: neither the prompt nor the command leaves the host. */
111
124
  export function publicJob(job) {
112
125
  if (!job) return { state: 'unknown', reason: 'not_admitted' };
113
- const { v, prompt, ...rest } = job;
126
+ const { v, prompt, run, ...rest } = job;
114
127
  return rest;
115
128
  }
116
129