@reefclaw/openclaw-plugin 0.1.25 → 0.1.27

package/bridge/heartbeat-transcript.js

@@ -0,0 +1,688 @@
+// Heartbeat flight recorder — TRANSCRIPT READER (network-free).
+//
+// Every heartbeat runs as an ISOLATED OpenClaw cron session: the gateway
+// mints a fresh session id per beat and writes its transcript to
+//   ~/.openclaw/agents/main/sessions/<sessionId>.jsonl
+// with a `.trajectory.jsonl` sidecar beside it. This module turns one such
+// pair into a compact, size-capped, token-redacted `HeartbeatRunRecord`:
+// which tools the agent called (with truncated args + results), what it
+// reported, which model answered, how many tokens it burned (raw counts —
+// deliberately NO currency translation), and any model-level trouble
+// (fallback / thinking-level / error events). The dashboard renders these as
+// the per-beat "what did it actually do" record that the journal never had
+// (tool calls were only ever visible by reading the box's transcript).
+//
+// Shapes verified against a live 2026.8.1 box (codex harness) on 2026-09-06
+// and the vendored 2026.6.11 source (`openclaw-main/`):
+//   line 1        {type:"session", version, id, timestamp, cwd}
+//   then          {type:"message", id, parentId, timestamp, message:{...}}
+//                 {type:"model_change", provider, modelId}
+//                 {type:"thinking_level_change", thinkingLevel}
+//                 (compaction / branch_summary / custom / label / leaf …)
+//   message.role  "user" | "assistant" | "toolResult"
+//   assistant     content[] of {type:"text"|"thinking"|"toolCall"},
+//                 api / provider / model / usage / stopReason / errorMessage
+//   toolResult    toolCallId / toolName / isError / content[] (the codex
+//                 harness nests {type:"toolResult", text, content} items —
+//                 the vendored shape is {type:"text", text}; both handled)
+//   ★ Under the codex harness every per-message `usage` is ZERO — token
+//     counts come from the cron run log (`cron.runs`) first, the trajectory's
+//     `model.completed` event second, and the transcript sum last.
+//   ★ The first user message starts with `[cron:<jobId> <jobName>] …` — that
+//     marker (or a `:cron:` trajectory sessionKey) is how a heartbeat session
+//     is told apart from the main chat session in the same directory.
+//
+// ★ THIS MODULE MUST NEVER IMPORT NETWORK CODE (no fetch, no ws, no relay, no
+// provider). ClawHub's static analyzer flags a sensitive-looking file read
+// paired with a network send IN THE SAME FILE as potential exfiltration (see
+// utils/skills-snapshot-invalidation.ts). The POST lives in heartbeat-runs.ts.
+import { existsSync, readdirSync, readFileSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { redactTokens } from '@reefclaw/shared';
+// ---- Size caps (keep a record well under the relay/webapp body limits) -----
+/** Max tool calls kept per record (the census still counts every call). */
+export const TOOL_CALLS_MAX = 250;
+/** Max chars of a tool call's JSON arguments. */
+export const ARGS_MAX = 300;
+/** Max chars of a tool result's text. */
+export const RESULT_MAX = 400;
+/** Max chars of the agent's final report text. */
+export const SUMMARY_MAX = 4000;
+/** Max model events kept. */
+export const MODEL_EVENTS_MAX = 50;
+/** Target upper bound for a serialized record (bytes). */
+export const RECORD_MAX_BYTES = 200_000;
+/** Tools whose arguments must never be captured (credentials in flight). */
+const SENSITIVE_TOOL_RE = /credential|secret|private|password|api_?key|token|wallet|passphrase/i;
+// ---- Paths ---------------------------------------------------------------
+/** OpenClaw's state dir — `OPENCLAW_STATE_DIR` is the real override (the
+ *  bridge historically read a non-existent OPENCLAW_HOME; honour both). */
+export function resolveOpenClawStateDir(env = process.env) {
+    const explicit = env.OPENCLAW_STATE_DIR?.trim() || env.OPENCLAW_HOME?.trim();
+    if (explicit)
+        return explicit;
+    return join(homedir(), '.openclaw');
+}
+export function resolveSessionsDir(agentId = 'main', env = process.env) {
+    return join(resolveOpenClawStateDir(env), 'agents', agentId, 'sessions');
+}
+const SESSION_FILE_RE = /^([a-z0-9][a-z0-9._-]{0,127})\.jsonl$/i;
+/** Every `<sessionId>.jsonl` transcript in `dir` (not sidecars, checkpoints,
+ *  topic files or retired copies) modified at/after `minMtimeMs`, excluding
+ *  `exclude`d session ids. Never throws — a missing dir yields []. */
+export function listSessionCandidates(dir, opts = {}) {
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        const m = SESSION_FILE_RE.exec(name);
+        if (!m)
+            continue;
+        const sessionId = m[1];
+        if (sessionId === 'sessions')
+            continue; // sessions.json is not .jsonl, but be explicit
+        if (/\.(trajectory|checkpoint\.[^.]+)$/i.test(sessionId))
+            continue;
+        if (/-topic-/i.test(sessionId))
+            continue;
+        if (opts.exclude?.has(sessionId))
+            continue;
+        const file = join(dir, name);
+        let st;
+        try {
+            st = statSync(file);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        if (opts.minMtimeMs !== undefined && st.mtimeMs < opts.minMtimeMs)
+            continue;
+        const traj = join(dir, `${sessionId}.trajectory.jsonl`);
+        out.push({
+            sessionId,
+            file,
+            trajectoryFile: existsSync(traj) ? traj : null,
+            mtimeMs: st.mtimeMs,
+            sizeBytes: st.size,
+        });
+    }
+    return out;
+}
+// ---- Cron marker (cheap head read) ----------------------------------------
+const CRON_MARKER_RE = /^\s*\[cron:([^\s\]]+)\s*([^\]]*)\]/;
+export function parseCronMarker(text) {
+    if (typeof text !== 'string')
+        return null;
+    const m = CRON_MARKER_RE.exec(text);
+    if (!m)
+        return null;
+    const jobName = m[2]?.trim();
+    return { jobId: m[1], jobName: jobName ? jobName : null };
+}
+/** Read only the head of a transcript and report whether its first user
+ *  message carries the `[cron:…]` marker. `null` = inconclusive (no user
+ *  message within the head) — callers then fall back to the trajectory key. */
+export function readCronMarker(file, headBytes = 32 * 1024) {
+    let head;
+    let readAll = false;
+    try {
+        const fd = openSync(file, 'r');
+        try {
+            const buf = Buffer.alloc(headBytes);
+            const n = readSync(fd, buf, 0, headBytes, 0);
+            head = buf.subarray(0, n).toString('utf8');
+            readAll = n < headBytes; // the whole file fit — no line can be torn
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return undefined;
+    }
+    const lines = head.split('\n');
+    // The last line may be cut mid-record when the file exceeds the head; only
+    // parse complete lines in that case.
+    const complete = readAll || head.endsWith('\n') ? lines : lines.slice(0, -1);
+    for (const line of complete) {
+        if (!line.trim())
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const r = rec;
+        if (r?.type !== 'message' || r.message?.role !== 'user')
+            continue;
+        return parseCronMarker(firstText(r.message.content));
+    }
+    return undefined;
+}
+function num(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : null;
+}
+function epochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v) && v > 0)
+        return v;
+    if (typeof v === 'string') {
+        const t = Date.parse(v);
+        return Number.isFinite(t) ? t : null;
+    }
+    return null;
+}
+function clip(s, max) {
+    if (s.length <= max)
+        return { text: s, clipped: false };
+    return { text: `${s.slice(0, max)}…(+${s.length - max})`, clipped: true };
+}
+/** Text of a content block / content array in every shape OpenClaw writes. */
+export function textOf(content, depth = 0) {
+    if (content == null || depth > 4)
+        return '';
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content))
+        return content.map((c) => textOf(c, depth + 1)).filter(Boolean).join('\n');
+    if (typeof content === 'object') {
+        const o = content;
+        if (typeof o.text === 'string')
+            return o.text;
+        if (typeof o.content === 'string')
+            return o.content;
+        if (Array.isArray(o.content))
+            return textOf(o.content, depth + 1);
+        if (o.type === 'image')
+            return '[image]';
+        if (o.type === 'thinking')
+            return '';
+        try {
+            return JSON.stringify(o);
+        }
+        catch {
+            return '';
+        }
+    }
+    return String(content);
+}
+/** The first text of a user message (string or [{type:'text',text}]). */
+function firstText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        for (const c of content) {
+            const t = textOf(c);
+            if (t)
+                return t;
+        }
+    }
+    return null;
+}
+function providerModel(provider, model) {
+    const m = typeof model === 'string' && model.trim() ? model.trim() : null;
+    if (!m)
+        return null;
+    const p = typeof provider === 'string' && provider.trim() ? provider.trim() : null;
+    return p && !m.includes('/') ? `${p}/${m}` : m;
+}
+export function parseSessionTranscript(text) {
+    const out = {
+        sessionId: null,
+        headerAtMs: null,
+        cron: null,
+        firstUserAtMs: null,
+        lastAtMs: null,
+        toolCalls: [],
+        toolCallTotal: 0,
+        toolErrorCount: 0,
+        toolCensus: {},
+        assistantCount: 0,
+        finalText: null,
+        models: [],
+        api: null,
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        usageNonZero: false,
+        lastStopReason: null,
+        lastErrorMessage: null,
+        modelEvents: [],
+        thinkingLevel: null,
+        complete: false,
+        truncated: false,
+        bytes: Buffer.byteLength(text, 'utf8'),
+    };
+    const byCallId = new Map();
+    const seenIds = new Set();
+    let lastAssistantText = null;
+    let lastAnyText = null;
+    let firstUserSeen = false;
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let rec;
+        try {
+            rec = JSON.parse(line);
+        }
+        catch {
+            continue; // a torn tail line while the gateway is still writing
+        }
+        if (!rec || typeof rec !== 'object')
+            continue;
+        // Dedup by record id (a tree can carry the same entry via `leaf` replays).
+        if (typeof rec.id === 'string') {
+            if (seenIds.has(rec.id))
+                continue;
+            seenIds.add(rec.id);
+        }
+        const at = epochMs(rec.timestamp);
+        if (at !== null)
+            out.lastAtMs = out.lastAtMs === null ? at : Math.max(out.lastAtMs, at);
+        switch (rec.type) {
+            case 'session': {
+                out.sessionId = typeof rec.id === 'string' ? rec.id : null;
+                out.headerAtMs = at;
+                break;
+            }
+            case 'model_change': {
+                const pm = providerModel(rec.provider, rec.modelId);
+                pushEvent(out, { kind: 'model_change', at, detail: pm ?? 'model changed' });
+                break;
+            }
+            case 'thinking_level_change': {
+                const lvl = typeof rec.thinkingLevel === 'string' ? rec.thinkingLevel : null;
+                out.thinkingLevel = lvl;
+                pushEvent(out, { kind: 'thinking_level_change', at, detail: lvl ?? 'thinking level changed' });
+                break;
+            }
+            case 'message': {
+                const m = rec.message;
+                if (!m || typeof m !== 'object')
+                    break;
+                const mAt = epochMs(m.timestamp) ?? at;
+                if (mAt !== null)
+                    out.lastAtMs = out.lastAtMs === null ? mAt : Math.max(out.lastAtMs, mAt);
+                const role = m.role;
+                if (role === 'user') {
+                    if (!firstUserSeen) {
+                        firstUserSeen = true;
+                        out.firstUserAtMs = mAt;
+                        out.cron = parseCronMarker(firstText(m.content));
+                    }
+                }
+                else if (role === 'assistant') {
+                    out.assistantCount++;
+                    const pm = providerModel(m.provider, m.responseModel ?? m.model);
+                    if (pm && !out.models.includes(pm))
+                        out.models.push(pm);
+                    if (typeof m.api === 'string' && !out.api)
+                        out.api = m.api;
+                    const u = m.usage;
+                    if (u && typeof u === 'object') {
+                        out.usage.input += num(u.input) ?? 0;
+                        out.usage.output += num(u.output) ?? 0;
+                        out.usage.cacheRead += num(u.cacheRead) ?? 0;
+                        out.usage.cacheWrite += num(u.cacheWrite) ?? 0;
+                        out.usage.total += num(u.totalTokens) ?? num(u.total) ?? 0;
+                    }
+                    const stop = typeof m.stopReason === 'string' ? m.stopReason : null;
+                    out.lastStopReason = stop;
+                    if (stop === 'error' || typeof m.errorMessage === 'string') {
+                        const msg = typeof m.errorMessage === 'string' ? m.errorMessage : 'assistant error';
+                        out.lastErrorMessage = msg;
+                        pushEvent(out, { kind: 'error', at: mAt, detail: clip(msg, 300).text });
+                    }
+                    const texts = [];
+                    if (Array.isArray(m.content)) {
+                        for (const b of m.content) {
+                            if (!b || typeof b !== 'object')
+                                continue;
+                            if (b.type === 'text' && typeof b.text === 'string' && b.text.trim())
+                                texts.push(b.text);
+                            if (b.type === 'toolCall') {
+                                out.toolCallTotal++;
+                                const name = typeof b.name === 'string' ? b.name : 'unknown';
+                                out.toolCensus[name] = (out.toolCensus[name] ?? 0) + 1;
+                                if (out.toolCalls.length >= TOOL_CALLS_MAX) {
+                                    out.truncated = true;
+                                    continue;
+                                }
+                                const id = typeof b.id === 'string' ? b.id : `${name}#${out.toolCallTotal}`;
+                                let args = '';
+                                if (SENSITIVE_TOOL_RE.test(name))
+                                    args = '[redacted]';
+                                else {
+                                    const rawArgs = b.arguments ?? b.input;
+                                    let s = '';
+                                    try {
+                                        s = typeof rawArgs === 'string' ? rawArgs : rawArgs == null ? '' : JSON.stringify(rawArgs);
+                                    }
+                                    catch {
+                                        s = '[unserializable]';
+                                    }
+                                    const c = clip(s, ARGS_MAX);
+                                    if (c.clipped)
+                                        out.truncated = true;
+                                    args = c.text;
+                                }
+                                const call = { id, name, at: mAt, ok: null, args, result: '', durationMs: null };
+                                out.toolCalls.push(call);
+                                byCallId.set(id, call);
+                            }
+                        }
+                    }
+                    else if (typeof m.content === 'string' && m.content.trim()) {
+                        texts.push(m.content);
+                    }
+                    if (texts.length) {
+                        lastAssistantText = texts.join('\n');
+                        lastAnyText = lastAssistantText;
+                    }
+                }
+                else if (role === 'toolResult') {
+                    const id = typeof m.toolCallId === 'string' ? m.toolCallId : null;
+                    const call = id ? byCallId.get(id) : undefined;
+                    const isErr = m.isError === true;
+                    if (isErr)
+                        out.toolErrorCount++;
+                    if (call) {
+                        call.ok = !isErr;
+                        const c = clip(textOf(m.content), RESULT_MAX);
+                        if (c.clipped)
+                            out.truncated = true;
+                        call.result = c.text;
+                        if (mAt !== null && call.at !== null && mAt >= call.at)
+                            call.durationMs = mAt - call.at;
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    out.finalText = lastAssistantText ?? lastAnyText;
+    out.usageNonZero = out.usage.input > 0 || out.usage.output > 0 || out.usage.total > 0;
+    // A turn that ended on a tool call is still mid-chain; anything else
+    // ("stop", "error", "aborted", "length") is terminal.
+    out.complete = out.assistantCount > 0 && out.lastStopReason !== null && out.lastStopReason !== 'toolUse';
+    return out;
+}
+function pushEvent(out, ev) {
+    if (out.modelEvents.length >= MODEL_EVENTS_MAX) {
+        out.truncated = true;
+        return;
+    }
+    out.modelEvents.push(ev);
+}
+export function parseTrajectory(text) {
+    const out = {
+        sessionKey: null,
+        runId: null,
+        provider: null,
+        modelId: null,
+        modelApi: null,
+        toolCount: null,
+        trigger: null,
+        thinkLevel: null,
+        ended: null,
+        usage: null,
+        fallbackSteps: [],
+        toolCallEvents: 0,
+        firstTs: null,
+        lastTs: null,
+        bytes: Buffer.byteLength(text, 'utf8'),
+    };
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let ev;
+        try {
+            ev = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!ev || typeof ev !== 'object')
+            continue;
+        const ts = epochMs(ev.ts);
+        if (ts !== null) {
+            out.firstTs = out.firstTs === null ? ts : Math.min(out.firstTs, ts);
+            out.lastTs = out.lastTs === null ? ts : Math.max(out.lastTs, ts);
+        }
+        if (typeof ev.sessionKey === 'string' && !out.sessionKey)
+            out.sessionKey = ev.sessionKey;
+        if (typeof ev.runId === 'string' && !out.runId)
+            out.runId = ev.runId;
+        if (typeof ev.provider === 'string' && !out.provider)
+            out.provider = ev.provider;
+        if (typeof ev.modelId === 'string' && !out.modelId)
+            out.modelId = ev.modelId;
+        if (typeof ev.modelApi === 'string' && !out.modelApi)
+            out.modelApi = ev.modelApi;
+        const data = (ev.data && typeof ev.data === 'object' ? ev.data : {});
+        switch (ev.type) {
+            case 'session.started':
+                out.toolCount = num(data.toolCount);
+                if (typeof data.trigger === 'string')
+                    out.trigger = data.trigger;
+                break;
+            case 'trace.metadata':
+                if (typeof data.trigger === 'string' && !out.trigger)
+                    out.trigger = data.trigger;
+                if (typeof data.thinkLevel === 'string')
+                    out.thinkLevel = data.thinkLevel;
+                break;
+            case 'tool.call':
+                out.toolCallEvents++;
+                break;
+            case 'model.completed': {
+                // A truncated event is {truncated, originalBytes, limitBytes, reason}
+                // with no usage — the run log / transcript sum cover that case.
+                const u = data.usage;
+                if (u && typeof u === 'object' && data.truncated !== true) {
+                    out.usage = {
+                        input: num(u.input) ?? 0,
+                        output: num(u.output) ?? 0,
+                        cacheRead: num(u.cacheRead) ?? 0,
+                        cacheWrite: num(u.cacheWrite) ?? 0,
+                        total: num(u.total) ?? num(u.totalTokens) ?? 0,
+                    };
+                }
+                break;
+            }
+            case 'session.ended':
+                out.ended = {
+                    status: typeof data.status === 'string' ? data.status : null,
+                    timedOut: data.timedOut === true,
+                    promptError: typeof data.promptError === 'string' && data.promptError ? data.promptError : null,
+                };
+                break;
+            case 'model.fallback_step': {
+                if (out.fallbackSteps.length >= MODEL_EVENTS_MAX)
+                    break;
+                out.fallbackSteps.push({ kind: 'fallback_step', at: ts, detail: describeFallbackStep(data) });
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return out;
+}
+/** Compact one-line description of a model.fallback_step payload whose exact
+ *  shape is not pinned by the vendored source — pick the fields that matter
+ *  when present, else a clipped JSON dump. */
+function describeFallbackStep(d) {
+    const parts = [];
+    const from = providerModel(d.fromProvider ?? d.provider, d.fromModel ?? d.model);
+    const to = providerModel(d.toProvider ?? d.nextProvider, d.toModel ?? d.nextModel ?? d.next);
+    if (from)
+        parts.push(from);
+    if (to)
+        parts.push(`→ ${to}`);
+    if (typeof d.reason === 'string')
+        parts.push(`reason=${d.reason}`);
+    else if (typeof d.errorReason === 'string')
+        parts.push(`reason=${d.errorReason}`);
+    if (typeof d.error === 'string')
+        parts.push(clip(d.error, 120).text);
+    if (parts.length)
+        return parts.join(' ');
+    try {
+        return clip(JSON.stringify(d), 200).text;
+    }
+    catch {
+        return 'fallback step';
+    }
+}
+export function isCronSessionKey(key) {
+    return typeof key === 'string' && /(^|:)cron:/i.test(key);
+}
+function clean(s) {
+    if (typeof s !== 'string')
+        return null;
+    const t = s.trim();
+    return t ? redactTokens(t) : null;
+}
+export function buildHeartbeatRunRecord(i) {
+    const t = i.transcript;
+    const tj = i.trajectory;
+    const rl = i.runLog;
+    const cronFromKey = tj?.sessionKey && isCronSessionKey(tj.sessionKey)
+        ? /(?:^|:)cron:([^:]+)/i.exec(tj.sessionKey)?.[1] ?? null
+        : null;
+    const cronJobId = t.cron?.jobId ?? cronFromKey;
+    const trigger = cronJobId ? 'cron' : 'unknown';
+    // Status: the run log is authoritative, then the trajectory's terminal
+    // event, then what the transcript itself shows.
+    let status;
+    if (rl?.status === 'ok')
+        status = 'ok';
+    else if (rl?.status === 'error' || rl?.status === 'skipped')
+        status = 'error';
+    else if (tj?.ended)
+        status = tj.ended.status === 'success' || tj.ended.status === 'ok' ? 'ok' : 'error';
+    else if (t.lastStopReason === 'error' || t.lastErrorMessage)
+        status = 'error';
+    else if (t.complete)
+        status = 'ok';
+    else
+        status = t.assistantCount > 0 ? 'incomplete' : 'unknown';
+    const startedAtMs = rl?.runAtMs ?? t.headerAtMs ?? t.firstUserAtMs ?? tj?.firstTs ?? i.fallbackStartedAtMs;
+    const endedAtMs = tj?.lastTs != null && t.lastAtMs != null ? Math.max(tj.lastTs, t.lastAtMs) : (tj?.lastTs ?? t.lastAtMs);
+    const durationMs = rl?.durationMs ?? (endedAtMs != null && endedAtMs >= startedAtMs ? endedAtMs - startedAtMs : null);
+    let tokens;
+    if (rl?.usage && (rl.usage.total != null || rl.usage.input != null || rl.usage.output != null)) {
+        tokens = { ...rl.usage, source: 'run_log' };
+    }
+    else if (tj?.usage) {
+        tokens = { ...tj.usage, source: 'trajectory' };
+    }
+    else if (t.usageNonZero) {
+        tokens = { ...t.usage, source: 'transcript' };
+    }
+    else {
+        tokens = { input: null, output: null, cacheRead: null, cacheWrite: null, total: null, source: 'none' };
+    }
+    if (tokens.total == null && tokens.input != null && tokens.output != null) {
+        tokens.total = tokens.input + tokens.output + (tokens.cacheRead ?? 0);
+    }
+    const model = providerModel(rl?.provider, rl?.model) ??
+        (tj ? providerModel(tj.provider, tj.modelId) : null) ??
+        (t.models.length ? t.models[t.models.length - 1] : null);
+    const modelEvents = [...t.modelEvents, ...(tj?.fallbackSteps ?? [])]
+        .map((e) => ({ ...e, detail: redactTokens(e.detail) }))
+        .sort((a, b) => (a.at ?? 0) - (b.at ?? 0))
+        .slice(0, MODEL_EVENTS_MAX);
+    const errorText = clean(rl?.error) ?? clean(tj?.ended?.promptError) ?? clean(t.lastErrorMessage);
+    const summaryClip = t.finalText ? clip(redactTokens(t.finalText), SUMMARY_MAX) : null;
+    const toolCalls = t.toolCalls.map((c) => ({
+        ...c,
+        args: redactTokens(c.args),
+        result: redactTokens(c.result),
+    }));
+    return {
+        runId: i.sessionId,
+        cronJobId,
+        cronJobName: t.cron?.jobName ?? null,
+        trigger,
+        status,
+        startedAtMs,
+        endedAtMs: endedAtMs ?? null,
+        durationMs,
+        model,
+        tokens,
+        toolCallCount: t.toolCallTotal,
+        toolErrorCount: t.toolErrorCount,
+        toolCensus: t.toolCensus,
+        toolCalls,
+        summary: summaryClip?.text ?? null,
+        modelEvents,
+        error: errorText,
+        errorReason: clean(rl?.errorReason),
+        mode: i.mode,
+        meta: {
+            transcriptBytes: t.bytes,
+            trajectoryBytes: tj?.bytes ?? null,
+            assistantMessages: t.assistantCount,
+            truncated: t.truncated || (summaryClip?.clipped ?? false),
+            toolCount: tj?.toolCount ?? null,
+            api: t.api ?? tj?.modelApi ?? null,
+            thinkingLevel: t.thinkingLevel ?? tj?.thinkLevel ?? null,
+        },
+    };
+}
+/** Shrink a record until its JSON fits `maxBytes`: first shorter tool
+ *  results, then no results, then fewer tool calls. Pure; returns a copy. */
+export function shrinkRecord(record, maxBytes = RECORD_MAX_BYTES) {
+    const size = (r) => Buffer.byteLength(JSON.stringify(r), 'utf8');
+    if (size(record) <= maxBytes)
+        return record;
+    let r = {
+        ...record,
+        toolCalls: record.toolCalls.map((c) => ({ ...c, result: clip(c.result, 120).text, args: clip(c.args, 120).text })),
+        meta: { ...record.meta, truncated: true },
+    };
+    if (size(r) <= maxBytes)
+        return r;
+    r = { ...r, toolCalls: r.toolCalls.map((c) => ({ ...c, result: '' })) };
+    if (size(r) <= maxBytes)
+        return r;
+    let keep = r.toolCalls.length;
+    while (keep > 0 && size({ ...r, toolCalls: r.toolCalls.slice(0, keep) }) > maxBytes)
+        keep = Math.floor(keep / 2);
+    return { ...r, toolCalls: r.toolCalls.slice(0, keep), summary: r.summary ? clip(r.summary, 1000).text : null };
+}
+/** Read + parse a candidate's transcript and (when present) its trajectory.
+ *  Never throws on a missing/torn file — a missing transcript yields null. */
+export function readSession(c) {
+    let text;
+    try {
+        text = readFileSync(c.file, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    const transcript = parseSessionTranscript(text);
+    let trajectory = null;
+    if (c.trajectoryFile) {
+        try {
+            trajectory = parseTrajectory(readFileSync(c.trajectoryFile, 'utf8'));
+        }
+        catch {
+            trajectory = null;
+        }
+    }
+    return { transcript, trajectory };
+}