clementine-agent 1.18.84 → 1.18.86

package/dist/agent/run-agent.d.ts

@@ -117,6 +117,10 @@ export interface RunAgentResult {
         cache_read_input_tokens?: number;
         cache_creation_input_tokens?: number;
     };
+    /** PRD §6 / 1.18.85: stable run UUID. The Event store keys off this id;
+     *  callers (cron-scheduler, cron CLI) stamp it on CronRunEntry so the
+     *  Run detail page can join run row → events. */
+    runId: string;
 }
 /**
  * Run a single agent invocation via the canonical SDK pattern.

package/dist/agent/run-agent.js

@@ -22,8 +22,10 @@
  *    long-task preflight, NO mode=unleashed wrapper.
  */
 import path from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { query } from '@anthropic-ai/claude-agent-sdk';
 import pino from 'pino';
+import { EventLog } from '../gateway/event-log.js';
 /**
  * Module-level cache of MCP server statuses from the most recent SDK
  * init message. Populated by every runAgent / PersonalAssistant query
@@ -58,6 +60,27 @@ export function recordMcpStatusFromSystemInit(rawMcpServers) {
     }
     _lastMcpStatusSnapshot = { servers, updatedAt: new Date().toISOString() };
 }
+/**
+ * Truncate a value for the Event store so a single huge tool input/output
+ * doesn't blow out the JSONL line. Object/array shapes are JSON-stringified
+ * and capped; primitive strings are sliced; everything else is returned as-is.
+ */
+function truncateForLog(value, maxBytes) {
+    if (value == null)
+        return value;
+    if (typeof value === 'string') {
+        return value.length > maxBytes ? value.slice(0, maxBytes) + '...[truncated]' : value;
+    }
+    try {
+        const json = JSON.stringify(value);
+        if (json.length <= maxBytes)
+            return value;
+        return { _truncated: true, preview: json.slice(0, maxBytes) + '...[truncated]', _bytes: json.length };
+    }
+    catch {
+        return { _unstringifiable: true };
+    }
+}
 /** Drop one server from the cache so the next query repopulates it. */
 export function invalidateMcpStatusEntry(name) {
     const before = _lastMcpStatusSnapshot.servers.length;
@@ -261,6 +284,23 @@ export async function runAgent(prompt, opts) {
         agentCount: Object.keys(agents).length,
         allowedToolCount: allowedTools.length,
     }, 'runAgent: starting query');
+    // PRD §6 / 1.18.85: path A in-process tap. One Event row per significant
+    // SDK message, written to ~/.clementine/events/<runId>.jsonl. The Run
+    // detail page (Phase 4b) reads from this file. EventLog.append never
+    // throws back to the caller — telemetry is best-effort.
+    const runId = randomUUID();
+    const eventLog = new EventLog();
+    let eventSeq = 0;
+    const writeEvent = (e) => {
+        try {
+            eventLog.append({
+                ...e,
+                runId,
+                seq: eventSeq++,
+            });
+        }
+        catch { /* never block */ }
+    };
     let finalText = '';
     let sessionId = '';
     let totalCostUsd = 0;
@@ -283,15 +323,27 @@ export async function runAgent(prompt, opts) {
                     }
                     catch { /* non-fatal */ }
                 }
-                logger.debug({ sessionKey: opts.sessionKey, sdkSessionId: sessionId }, 'runAgent: SDK session initialized');
+                // PRD Phase 4a / 1.18.85: write the session_start Event row.
+                writeEvent({ kind: 'session_start', ts: new Date().toISOString(), sessionId });
+                logger.debug({ sessionKey: opts.sessionKey, sdkSessionId: sessionId, runId }, 'runAgent: SDK session initialized');
                 continue;
             }
             if (message.type === 'assistant') {
                 const am = message;
+                // SDK content blocks include text, tool_use, and (when extended-thinking
+                // is enabled) thinking. We tap each kind into the Event store.
                 const blocks = (am.message?.content ?? []);
                 for (const block of blocks) {
                     if (block.type === 'text' && typeof block.text === 'string') {
                         finalText += block.text;
+                        // PRD Phase 4a / 1.18.85: llm_text Event. Truncate at 8KB to keep
+                        // the JSONL light — full text is reachable via the SDK transcript.
+                        writeEvent({
+                            kind: 'llm_text',
+                            ts: new Date().toISOString(),
+                            sessionId,
+                            text: block.text.slice(0, 8000),
+                        });
                         if (opts.onText) {
                             try {
                                 await opts.onText(block.text);
@@ -299,7 +351,29 @@ export async function runAgent(prompt, opts) {
                             catch { /* streaming is best-effort */ }
                         }
                     }
+                    else if (block.type === 'thinking' && typeof block.thinking === 'string') {
+                        // Extended-thinking block — captured separately so the Run detail
+                        // page can render thinking distinctly from final text.
+                        writeEvent({
+                            kind: 'thinking',
+                            ts: new Date().toISOString(),
+                            sessionId,
+                            thinking: block.thinking.slice(0, 8000),
+                        });
+                    }
                     else if (block.type === 'tool_use' && typeof block.name === 'string') {
+                        // PRD Phase 4a: tool_call Event. The tool_use id pairs with the
+                        // tool_result Event written when the SDK reports back. Inputs
+                        // truncated at 8KB; the dashboard can fetch the full transcript
+                        // if a deeper drill-down is needed.
+                        writeEvent({
+                            kind: 'tool_call',
+                            ts: new Date().toISOString(),
+                            sessionId,
+                            toolName: block.name,
+                            toolUseId: block.id,
+                            toolInput: truncateForLog(block.input ?? {}, 8000),
+                        });
                         if (opts.onToolActivity) {
                             try {
                                 await opts.onToolActivity({ tool: block.name, input: block.input ?? {} });
@@ -310,6 +384,26 @@ export async function runAgent(prompt, opts) {
                 }
                 continue;
             }
+            // SDK user messages carry tool_result blocks back from tool execution.
+            // We pair them with the earlier tool_call Event via toolUseId so the
+            // Run detail waterfall renders call → result side by side.
+            if (message.type === 'user') {
+                const um = message;
+                const blocks = um.message?.content ?? [];
+                for (const block of blocks) {
+                    if (block.type === 'tool_result') {
+                        writeEvent({
+                            kind: 'tool_result',
+                            ts: new Date().toISOString(),
+                            sessionId,
+                            toolUseId: block.tool_use_id,
+                            toolResult: truncateForLog(block.content, 16000),
+                            ...(block.is_error ? { toolError: 'tool reported is_error' } : {}),
+                        });
+                    }
+                }
+                continue;
+            }
             if (message.type === 'result') {
                 const result = message;
                 sessionId = sessionId || (result.session_id ?? '');
@@ -325,6 +419,15 @@ export async function runAgent(prompt, opts) {
                     if (r)
                         finalText = r;
                 }
+                // PRD Phase 4a / 1.18.85: session_end Event — closes the run in the
+                // event store and stamps the cost + stop reason for the Run detail page.
+                writeEvent({
+                    kind: 'session_end',
+                    ts: new Date().toISOString(),
+                    sessionId,
+                    costUsd: totalCostUsd,
+                    stopReason: subtype,
+                });
                 // Mirror cost to usage_log. Same shape as the existing
                 // logQueryResult, but standalone so we don't depend on
                 // PersonalAssistant's instance state.
@@ -353,13 +456,22 @@ export async function runAgent(prompt, opts) {
         }
     }
     catch (err) {
+        // PRD Phase 4a / 1.18.85: error Event closes the run if the SDK throws.
+        // Lets the Run detail page render an explicit failure span instead of a
+        // run that just trails off after the last successful tool_call.
+        const errMsg = String(err?.message ?? err).slice(0, 1000);
+        writeEvent({
+            kind: 'error',
+            ts: new Date().toISOString(),
+            sessionId,
+            toolError: errMsg,
+        });
         // Translate the SDK's budget-exhaustion throw into a message that
         // tells the user (a) what cap tripped and (b) how to raise it.
         // The raw SDK string ("Claude Code returned an error result:
         // Reached maximum budget ($0.5)") leaks through the channel layer
         // as a generic "Something went wrong:" with no actionable hint.
-        const msg = String(err?.message ?? err);
-        if (/Reached maximum budget|error_max_budget_usd/i.test(msg)) {
+        if (/Reached maximum budget|error_max_budget_usd/i.test(errMsg)) {
             const cap = maxBudgetUsd?.toFixed(2) ?? '?';
             const envKey = `BUDGET_${source.toUpperCase().replace(/-/g, '_')}_USD`;
             throw new Error(`Hit the $${cap} ${source} budget cap before finishing. ` +
@@ -384,6 +496,7 @@ export async function runAgent(prompt, opts) {
         sessionId,
         subtype,
         ...(usage ? { usage } : {}),
+        runId,
     };
 }
 //# sourceMappingURL=run-agent.js.map

package/dist/cli/cron.js

@@ -144,6 +144,11 @@ export async function cmdCronRun(jobName) {
         // by the dashboard's manual-run endpoint. Defaults to 'scheduled' for
         // any other invocation path (CLI, daemon-internal callsites).
         const trigger = process.env.CRON_RUN_TRIGGER || 'scheduled';
+        // 1.18.85: pull the run UUID from the gateway's per-run metadata
+        // side-channel. runAgent stamps it; consume here to link CronRunEntry
+        // to the Event store.
+        const sideChannel = gateway.consumeLastCronRunMetadata?.();
+        const runIdFromGateway = sideChannel?.runId;
         const entry = {
             jobName: job.name,
             startedAt: startedAt.toISOString(),
@@ -153,6 +158,7 @@ export async function cmdCronRun(jobName) {
             attempt: 1,
             outputPreview: response ? response.slice(0, 200) : undefined,
             trigger,
+            ...(runIdFromGateway ? { id: runIdFromGateway } : {}),
         };
         // PRD Phase 1.1: goal-orientation evaluator (mirrors the daemon path).
         if (job.successSchema || (job.successCriteriaText && job.successCriteriaText.trim())) {

package/dist/cli/dashboard.js

@@ -5670,6 +5670,26 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // ── PRD Phase 4a / 1.18.85: per-run Event store reader ─────────
+    // Returns every event captured by path A (in-process tap in runAgent)
+    // for one run. Used by the new Run detail page (Phase 4b).
+    app.get('/api/runs/:runId/events', async (req, res) => {
+        try {
+            const rawId = req.params.runId;
+            const runId = Array.isArray(rawId) ? rawId[0] : rawId;
+            if (!runId || typeof runId !== 'string') {
+                res.status(400).json({ ok: false, error: 'runId required' });
+                return;
+            }
+            const { EventLog } = await import('../gateway/event-log.js');
+            const log = new EventLog();
+            const events = log.readByRun(runId);
+            res.json({ ok: true, runId, events });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     // ── Recent runs across ALL cron jobs ───────────────────────────
     // Powers the "Recent History" zone on the Tasks page. Returns the most
     // recent N CronRunEntry rows merged from every per-job .jsonl, sorted
@@ -6676,6 +6696,24 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             if (purge) {
                 const safe = bareJobName.replace(/[^a-zA-Z0-9_-]/g, '_');
                 const runLog = path.join(BASE_DIR, 'cron', 'runs', `${safe}.jsonl`);
+                // Read run UUIDs BEFORE we drop the run log — the Event store is
+                // keyed by run UUID, not by job name, so the only way to know which
+                // event files to delete is by reading the JSONL first.
+                const runIdsToPurge = [];
+                try {
+                    if (existsSync(runLog)) {
+                        const lines = readFileSync(runLog, 'utf-8').trim().split('\n').filter(Boolean);
+                        for (const l of lines) {
+                            try {
+                                const entry = JSON.parse(l);
+                                if (entry && typeof entry.id === 'string' && entry.id)
+                                    runIdsToPurge.push(entry.id);
+                            }
+                            catch { /* skip malformed */ }
+                        }
+                    }
+                }
+                catch { /* non-fatal */ }
                 try {
                     if (existsSync(runLog)) {
                         unlinkSync(runLog);
@@ -6698,6 +6736,30 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
                     }
                 }
                 catch { /* non-fatal */ }
+                // PRD Phase 4a / 1.18.85: drop the new Event store entries linked
+                // to this job's runs. One file per run UUID.
+                try {
+                    if (runIdsToPurge.length > 0) {
+                        const eventsDir = path.join(BASE_DIR, 'events');
+                        if (existsSync(eventsDir)) {
+                            let dropped = 0;
+                            for (const rid of runIdsToPurge) {
+                                const safeRid = String(rid).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+                                const evtFile = path.join(eventsDir, `${safeRid}.jsonl`);
+                                try {
+                                    if (existsSync(evtFile)) {
+                                        unlinkSync(evtFile);
+                                        dropped++;
+                                    }
+                                }
+                                catch { /* skip */ }
+                            }
+                            if (dropped > 0)
+                                purged.push(`${dropped} event log${dropped === 1 ? '' : 's'}`);
+                        }
+                    }
+                }
+                catch { /* non-fatal */ }
                 try {
                     const uploadsDir = path.join(BASE_DIR, 'uploads', `cron-${safe}`);
                     if (existsSync(uploadsDir)) {
@@ -23638,7 +23700,7 @@ function renderRecentHistoryList(runs) {
       + '</div>'
       + '<div style="font-size:12px;color:var(--text-secondary);line-height:18px">' + esc(startedLabel) + '</div>'
       + '<div style="font-size:12px;color:var(--text-muted);line-height:18px">' + esc(durationLabel) + '</div>'
-      + '<div style="display:flex;gap:6px;align-items:center"><button class="btn-sm" onclick="event.stopPropagation();openTraceViewer(\\x27' + safeName + '\\x27)" style="font-size:11px;padding:3px 8px">Trace</button></div>'
+      + '<div style="display:flex;gap:6px;align-items:center"><button class="btn-sm" onclick="event.stopPropagation();openRunOrTrace(\\x27' + safeName + '\\x27,' + (entry.id ? '\\x27' + jsStr(entry.id) + '\\x27' : 'null') + ')" style="font-size:11px;padding:3px 8px">' + (entry.id ? 'Open run' : 'Trace') + '</button></div>'
       + '</div>';
   }
   return '<div class="history-list" style="background:var(--bg-secondary);border:1px solid var(--border);border-radius:var(--radius)">'
@@ -23844,7 +23906,7 @@ function renderRunListBody(allRuns) {
       +    '<div style="font-size:11px;color:' + triggerColor + ';line-height:18px">' + esc(triggerLabel) + '</div>'
       +    '<div style="font-size:12px;color:var(--text-secondary);line-height:18px">' + esc(startedLabel) + '</div>'
       +    '<div style="font-size:12px;color:var(--text-muted);line-height:18px">' + esc(durationLabel) + '</div>'
-      +    '<div style="display:flex;gap:6px;align-items:center"><button class="btn-sm" onclick="event.stopPropagation();openTraceViewer(\\x27' + safeName + '\\x27)" style="font-size:11px;padding:3px 8px">Trace</button></div>'
+      +    '<div style="display:flex;gap:6px;align-items:center"><button class="btn-sm" onclick="event.stopPropagation();openRunOrTrace(\\x27' + safeName + '\\x27,' + (entry.id ? '\\x27' + jsStr(entry.id) + '\\x27' : 'null') + ')" style="font-size:11px;padding:3px 8px">' + (entry.id ? 'Open run' : 'Trace') + '</button></div>'
       + '</div>';
   }
   html += '</div>';
@@ -24322,6 +24384,162 @@ async function refreshCron() {
 
 var traceData = [];
 
+// PRD Phase 4b / 1.18.86: smart router. If the run entry has a stable
+// runId (1.18.85+ runs), open the new Run detail viewer reading from the
+// Event store; otherwise fall back to the legacy trace viewer (which now
+// just renders the friendly empty state explaining where to find the
+// real error). Both viewers share the same modal shell.
+function openRunOrTrace(jobName, runId) {
+  if (runId && typeof runId === 'string') {
+    return openRunDetail(runId, jobName);
+  }
+  return openTraceViewer(jobName);
+}
+
+// PRD Phase 4b / 1.18.86: Run detail viewer. Renders a waterfall of
+// RunEvent rows from /api/runs/:runId/events. Color-coded by kind, paired
+// tool_call→tool_result by toolUseId, with expandable per-span content.
+async function openRunDetail(runId, jobName) {
+  document.getElementById('trace-modal-title').textContent = 'Run detail · ' + (jobName || runId);
+  document.getElementById('trace-run-selector').innerHTML = '';
+  document.getElementById('trace-content').innerHTML = '<div style="padding:20px;color:var(--text-muted)">Loading run events…</div>';
+  document.getElementById('trace-modal').classList.add('show');
+  try {
+    var r = await apiFetch('/api/runs/' + encodeURIComponent(runId) + '/events');
+    var d = await r.json();
+    if (!r.ok || d.ok === false) {
+      document.getElementById('trace-content').innerHTML = '<div style="padding:20px;color:var(--red)">Failed to load run: ' + esc(d.error || 'unknown') + '</div>';
+      return;
+    }
+    var events = (d && d.events) || [];
+    if (events.length === 0) {
+      document.getElementById('trace-content').innerHTML = '<div style="padding:24px;color:var(--text-muted);line-height:1.6"><div style="font-weight:500;color:var(--text-secondary);margin-bottom:8px">No events captured for this run</div><div style="font-size:12px">Either the run pre-dates 1.18.85 (when the Event store was added) or the SDK errored before any message landed.<br/>The Recent history row carries the high-level status, error message, and goal verdict.</div></div>';
+      return;
+    }
+    document.getElementById('trace-content').innerHTML = renderRunDetailWaterfall(events, runId, jobName);
+  } catch (e) {
+    document.getElementById('trace-content').innerHTML = '<div style="padding:20px;color:var(--red)">Failed to load run: ' + esc(String(e)) + '</div>';
+  }
+}
+
+// Renders the waterfall. Each event becomes a row with:
+//   color border (by kind) · kind badge · time offset · brief preview · expand link
+// tool_call rows pair with their tool_result by toolUseId so the duration
+// is computed and shown alongside the call.
+function renderRunDetailWaterfall(events, runId, jobName) {
+  if (!events.length) return '';
+  var firstTs = events[0].ts ? new Date(events[0].ts).getTime() : Date.now();
+  var lastTs = events[events.length - 1].ts ? new Date(events[events.length - 1].ts).getTime() : firstTs;
+  var totalMs = Math.max(1, lastTs - firstTs);
+
+  // Pair tool_call with its tool_result for duration.
+  var resultByToolUseId = {};
+  for (var i = 0; i < events.length; i++) {
+    var e = events[i];
+    if (e.kind === 'tool_result' && e.toolUseId) {
+      resultByToolUseId[e.toolUseId] = e;
+    }
+  }
+
+  // Per-event color + label
+  function kindColor(k) {
+    if (k === 'session_start' || k === 'session_end') return 'var(--text-muted)';
+    if (k === 'llm_text') return 'var(--accent)';
+    if (k === 'thinking') return 'var(--purple)';
+    if (k === 'tool_call') return '#22c55e';
+    if (k === 'tool_result') return '#22c55e';
+    if (k === 'subagent_start' || k === 'subagent_stop') return '#a855f7';
+    if (k === 'rate_limit') return 'var(--yellow)';
+    if (k === 'hook') return 'var(--blue)';
+    if (k === 'error') return 'var(--red)';
+    return 'var(--text-muted)';
+  }
+  function kindLabel(k) {
+    return (k || 'event').toUpperCase().replace(/_/g, ' ');
+  }
+
+  // Header strip with summary
+  var startLabel = events[0].ts ? new Date(events[0].ts).toLocaleString() : '—';
+  var endEvent = events.find(function(e) { return e.kind === 'session_end'; });
+  var costStr = endEvent && endEvent.costUsd != null ? '$' + endEvent.costUsd.toFixed(4) : '—';
+  var stopReason = endEvent && endEvent.stopReason ? endEvent.stopReason : '—';
+  var html = '<div style="padding:16px 20px;border-bottom:1px solid var(--border);background:var(--bg-secondary);position:sticky;top:0;z-index:1">'
+    + '<div style="display:flex;align-items:center;gap:14px;font-size:11px;color:var(--text-muted);flex-wrap:wrap">'
+    +   '<span><strong style="color:var(--text-primary)">' + esc(events.length) + '</strong> events</span>'
+    +   '<span>·</span><span>started ' + esc(startLabel) + '</span>'
+    +   '<span>·</span><span>duration <strong style="color:var(--text-primary)">' + esc(formatDurationMs(totalMs)) + '</strong></span>'
+    +   '<span>·</span><span>cost <strong style="color:var(--text-primary)">' + esc(costStr) + '</strong></span>'
+    +   '<span>·</span><span>stop reason <strong style="color:var(--text-primary)">' + esc(stopReason) + '</strong></span>'
+    +   '<span style="flex:1"></span>'
+    +   '<code style="font-size:10px;color:var(--text-muted)">runId ' + esc(String(runId).slice(0, 12)) + '…</code>'
+    + '</div>'
+    + '</div>';
+
+  // Waterfall rows
+  html += '<div style="padding:0">';
+  for (var j = 0; j < events.length; j++) {
+    var ev = events[j];
+    var color = kindColor(ev.kind);
+    var label = kindLabel(ev.kind);
+    var tsMs = ev.ts ? new Date(ev.ts).getTime() : firstTs;
+    var offsetMs = tsMs - firstTs;
+    var offsetLabel = offsetMs === 0 ? '+0ms' : '+' + formatDurationMs(offsetMs);
+    var widthPct = Math.max(2, Math.min(100, (offsetMs / totalMs) * 100));
+    // For tool_call, compute duration to its paired tool_result.
+    var pairedDuration = '';
+    if (ev.kind === 'tool_call' && ev.toolUseId && resultByToolUseId[ev.toolUseId]) {
+      var resultTs = new Date(resultByToolUseId[ev.toolUseId].ts).getTime();
+      pairedDuration = ' · ran ' + formatDurationMs(Math.max(0, resultTs - tsMs));
+    }
+
+    // Brief preview: text for llm_text, thinking for thinking, tool name + first arg for tool_call/result, error for error.
+    var preview = '';
+    var fullContent = '';
+    if (ev.kind === 'llm_text' && ev.text) {
+      preview = String(ev.text).slice(0, 160).replace(/\\s+/g, ' ');
+      fullContent = String(ev.text);
+    } else if (ev.kind === 'thinking' && ev.thinking) {
+      preview = String(ev.thinking).slice(0, 160).replace(/\\s+/g, ' ');
+      fullContent = String(ev.thinking);
+    } else if (ev.kind === 'tool_call') {
+      preview = (ev.toolName || 'tool') + (ev.toolInput ? ' · ' + JSON.stringify(ev.toolInput).slice(0, 120) : '');
+      fullContent = ev.toolInput ? JSON.stringify(ev.toolInput, null, 2) : '';
+    } else if (ev.kind === 'tool_result') {
+      preview = ev.toolError ? '✗ ' + ev.toolError : (typeof ev.toolResult === 'string' ? ev.toolResult.slice(0, 160) : (ev.toolResult ? JSON.stringify(ev.toolResult).slice(0, 160) : ''));
+      fullContent = typeof ev.toolResult === 'string' ? ev.toolResult : JSON.stringify(ev.toolResult, null, 2);
+    } else if (ev.kind === 'error') {
+      preview = ev.toolError || '';
+      fullContent = ev.toolError || '';
+    } else if (ev.kind === 'session_start') {
+      preview = ev.sessionId ? 'session ' + String(ev.sessionId).slice(0, 8) + '…' : '';
+    } else if (ev.kind === 'session_end') {
+      preview = '$' + (ev.costUsd != null ? ev.costUsd.toFixed(4) : '?') + ' · ' + (ev.stopReason || '?');
+    }
+
+    var rowId = 'run-evt-' + j;
+    var canExpand = !!fullContent && fullContent.length > preview.length;
+    html += '<div style="display:grid;grid-template-columns:90px 110px 1fr;gap:14px;padding:10px 20px;border-bottom:1px solid var(--border);align-items:start">';
+    html += '<div style="font-size:10px;color:var(--text-muted);font-family:\\x27JetBrains Mono\\x27,monospace;line-height:18px">' + esc(offsetLabel) + '</div>';
+    html += '<div><span style="display:inline-block;background:' + color + '20;color:' + color + ';padding:2px 8px;border-radius:4px;font-size:10px;font-weight:600;letter-spacing:0.04em">' + esc(label) + '</span></div>';
+    html += '<div style="min-width:0">';
+    html +=   '<div style="font-size:12px;color:var(--text-primary);line-height:1.45;word-break:break-word">'
+      +     esc(preview)
+      +     (pairedDuration ? '<span style="color:var(--text-muted);font-size:11px"> ' + esc(pairedDuration) + '</span>' : '')
+      +   '</div>';
+    if (canExpand) {
+      html += '<button class="btn-sm" onclick="document.getElementById(\\x27' + rowId + '\\x27).style.display=document.getElementById(\\x27' + rowId + '\\x27).style.display===\\x27none\\x27?\\x27block\\x27:\\x27none\\x27" style="margin-top:6px;font-size:10px;padding:2px 8px">Expand</button>';
+      html += '<pre id="' + rowId + '" style="display:none;margin-top:8px;font-size:11px;font-family:\\x27JetBrains Mono\\x27,monospace;background:var(--bg-secondary);border:1px solid var(--border);padding:10px;border-radius:6px;white-space:pre-wrap;word-break:break-word;max-height:400px;overflow-y:auto">' + esc(fullContent) + '</pre>';
+    }
+    // Show toolUseId hint when present so user can correlate with logs.
+    if (ev.toolUseId) {
+      html += '<div style="font-size:10px;color:var(--text-muted);font-family:\\x27JetBrains Mono\\x27,monospace;margin-top:4px">use_id ' + esc(String(ev.toolUseId).slice(0, 12)) + '…</div>';
+    }
+    html += '</div></div>';
+  }
+  html += '</div>';
+  return html;
+}
+
 async function openTraceViewer(jobName) {
   document.getElementById('trace-modal-title').textContent = 'Trace: ' + jobName;
   document.getElementById('trace-content').innerHTML = '<div style="padding:20px;color:var(--text-muted)">Loading...</div>';
@@ -25646,7 +25864,7 @@ function renderCronRunDetails(lr) {
   if (Array.isArray(lr.mcpServersApplied) && lr.mcpServersApplied.length) {
     html += '<div style="font-size:11px;color:var(--text-muted);margin-bottom:6px">MCP servers: ' + esc(lr.mcpServersApplied.join(', ')) + '</div>';
   }
-  html += '<div style="margin-top:14px;display:flex;gap:8px"><button class="btn-sm" onclick="openTraceViewer(\\x27' + jsStr(lr.jobName || editingCronJob || '') + '\\x27)" style="font-size:11px">Open trace</button></div>';
+  html += '<div style="margin-top:14px;display:flex;gap:8px"><button class="btn-sm" onclick="openRunOrTrace(\\x27' + jsStr(lr.jobName || editingCronJob || '') + '\\x27,' + (lr.id ? '\\x27' + jsStr(lr.id) + '\\x27' : 'null') + ')" style="font-size:11px">' + (lr.id ? 'Open run' : 'Open trace') + '</button></div>';
   html += '</div>';
   return html;
 }

package/dist/gateway/cron-scheduler.js

@@ -1208,6 +1208,8 @@ export class CronScheduler {
                         terminalReason,
                         // 1.18.84: persist the actual trigger source for the Run list filter.
                         trigger,
+                        // 1.18.85: stable UUID linking this run to its Event store entries.
+                        ...(cronMetadata?.runId ? { id: cronMetadata.runId } : {}),
                         // Trick capability metadata — surfaced by the dashboard's
                         // "ran with: …" line. Omit empty arrays to keep the JSONL light.
                         ...(cronMetadata?.skillsApplied?.length ? { skillsApplied: cronMetadata.skillsApplied } : {}),

package/dist/gateway/event-log.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Per-run event log — PRD §6 / Phase 4a.
+ *
+ * Stores RunEvent rows as JSONL at ~/.clementine/events/<runId>.jsonl,
+ * mirroring the existing CronRunLog pattern (auto-prune at 2MB / 2000 lines).
+ * One file per run keeps reads cheap (no scanning unrelated runs) and lets
+ * the Run detail page tail a single file for live updates.
+ *
+ * Writers:
+ *   - In-process tap in runAgent (path A) writes session_start, llm_text,
+ *     thinking, tool_call, tool_result, session_end during the SDK stream.
+ *   - Hook side-channel (path B, Phase 4d) writes hook events.
+ *   - Subagent backfill (path C, Phase 4e) synthesizes tool_call/tool_result
+ *     for inner SDK calls that don't fire parent-level hooks.
+ *
+ * Reader: dashboard's Run detail page via /api/runs/:run_id/events.
+ */
+import type { RunEvent } from '../types.js';
+export declare class EventLog {
+    private readonly dir;
+    private static readonly MAX_BYTES;
+    private static readonly MAX_LINES;
+    constructor(baseDir?: string);
+    private logPath;
+    append(event: RunEvent): void;
+    /** Read every event for one run, in seq order. */
+    readByRun(runId: string): RunEvent[];
+    /** Returns true if any events were captured for the run. Cheap existence check. */
+    hasEventsForRun(runId: string): boolean;
+    /** Drop one run's entire log. Called from cron-delete cascade cleanup. */
+    removeRun(runId: string): boolean;
+    /** Total disk size of all event logs in bytes. For diagnostics. */
+    totalBytes(): number;
+    private maybePrune;
+}
+//# sourceMappingURL=event-log.d.ts.map

package/dist/gateway/event-log.js

@@ -0,0 +1,136 @@
+/**
+ * Per-run event log — PRD §6 / Phase 4a.
+ *
+ * Stores RunEvent rows as JSONL at ~/.clementine/events/<runId>.jsonl,
+ * mirroring the existing CronRunLog pattern (auto-prune at 2MB / 2000 lines).
+ * One file per run keeps reads cheap (no scanning unrelated runs) and lets
+ * the Run detail page tail a single file for live updates.
+ *
+ * Writers:
+ *   - In-process tap in runAgent (path A) writes session_start, llm_text,
+ *     thinking, tool_call, tool_result, session_end during the SDK stream.
+ *   - Hook side-channel (path B, Phase 4d) writes hook events.
+ *   - Subagent backfill (path C, Phase 4e) synthesizes tool_call/tool_result
+ *     for inner SDK calls that don't fire parent-level hooks.
+ *
+ * Reader: dashboard's Run detail page via /api/runs/:run_id/events.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import pino from 'pino';
+import { BASE_DIR } from '../config.js';
+const logger = pino({ name: 'clementine.event-log', level: process.env.LOG_LEVEL ?? 'info' });
+export class EventLog {
+    dir;
+    static MAX_BYTES = 2_000_000;
+    static MAX_LINES = 2000;
+    constructor(baseDir) {
+        this.dir = path.join(baseDir ?? BASE_DIR, 'events');
+        if (!existsSync(this.dir)) {
+            mkdirSync(this.dir, { recursive: true });
+        }
+    }
+    logPath(runId) {
+        // Sanitize runId for filesystem — UUIDs are safe but we defend against
+        // accidental non-UUID values flowing in from older callsites.
+        const safe = String(runId).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 128);
+        return path.join(this.dir, `${safe}.jsonl`);
+    }
+    append(event) {
+        if (!event.runId) {
+            logger.warn({ event: { kind: event.kind, ts: event.ts } }, 'Event missing runId — dropped');
+            return;
+        }
+        const filePath = this.logPath(event.runId);
+        const line = JSON.stringify(event) + '\n';
+        try {
+            appendFileSync(filePath, line);
+            // Prune asynchronously so the SDK stream loop never blocks on disk IO.
+            setImmediate(() => this.maybePrune(filePath));
+        }
+        catch (err) {
+            // Never throw to the caller — telemetry must not break runs.
+            logger.warn({ err, runId: event.runId }, 'Failed to write event log');
+        }
+    }
+    /** Read every event for one run, in seq order. */
+    readByRun(runId) {
+        const filePath = this.logPath(runId);
+        if (!existsSync(filePath))
+            return [];
+        try {
+            const lines = readFileSync(filePath, 'utf-8').trim().split('\n').filter(Boolean);
+            const events = lines
+                .map((l) => {
+                try {
+                    return JSON.parse(l);
+                }
+                catch {
+                    return null;
+                }
+            })
+                .filter((e) => e !== null);
+            // Sort by seq so events with the same ts (sub-millisecond bursts) order
+            // deterministically.
+            events.sort((a, b) => (a.seq ?? 0) - (b.seq ?? 0));
+            return events;
+        }
+        catch {
+            return [];
+        }
+    }
+    /** Returns true if any events were captured for the run. Cheap existence check. */
+    hasEventsForRun(runId) {
+        return existsSync(this.logPath(runId));
+    }
+    /** Drop one run's entire log. Called from cron-delete cascade cleanup. */
+    removeRun(runId) {
+        const filePath = this.logPath(runId);
+        if (!existsSync(filePath))
+            return false;
+        try {
+            writeFileSync(filePath, ''); // truncate, then unlink — symmetric with cron-runs delete pattern
+            const fs = require('node:fs');
+            fs.unlinkSync(filePath);
+            return true;
+        }
+        catch (err) {
+            logger.warn({ err, runId }, 'Failed to remove event log');
+            return false;
+        }
+    }
+    /** Total disk size of all event logs in bytes. For diagnostics. */
+    totalBytes() {
+        if (!existsSync(this.dir))
+            return 0;
+        let total = 0;
+        try {
+            for (const f of readdirSync(this.dir)) {
+                if (!f.endsWith('.jsonl'))
+                    continue;
+                try {
+                    total += statSync(path.join(this.dir, f)).size;
+                }
+                catch { /* skip */ }
+            }
+        }
+        catch { /* skip */ }
+        return total;
+    }
+    maybePrune(filePath) {
+        try {
+            const { size } = statSync(filePath);
+            if (size <= EventLog.MAX_BYTES)
+                return;
+            const lines = readFileSync(filePath, 'utf-8').trim().split('\n');
+            if (lines.length <= EventLog.MAX_LINES)
+                return;
+            const trimmed = lines.slice(-EventLog.MAX_LINES);
+            writeFileSync(filePath, trimmed.join('\n') + '\n');
+        }
+        catch {
+            // non-critical
+        }
+    }
+}
+//# sourceMappingURL=event-log.js.map

package/dist/gateway/router.d.ts

@@ -237,6 +237,8 @@ export declare class Gateway {
         skillsMissing: string[];
         allowedToolsApplied?: string[];
         mcpServersApplied: string[];
+        /** PRD §6 / 1.18.85: run UUID from runAgent. */
+        runId?: string;
     } | undefined;
     requestApproval(descriptionOrId: string, explicitId?: string): Promise<boolean | string>;
     resolveApproval(requestId: string, result: boolean | string): void;

package/dist/gateway/router.js

@@ -2023,6 +2023,7 @@ export class Gateway {
                     skillsMissing: cronResult.skillsMissing,
                     allowedToolsApplied: cronResult.allowedToolsApplied,
                     mcpServersApplied: cronResult.mcpServersApplied,
+                    runId: cronResult.runId,
                 };
                 logger.info({
                     jobName,

package/dist/types.d.ts

@@ -404,7 +404,55 @@ export interface LongTaskPreflightSnapshot {
     reasons: string[];
 }
 export type TerminalReason = 'blocking_limit' | 'rapid_refill_breaker' | 'prompt_too_long' | 'image_error' | 'model_error' | 'aborted_streaming' | 'aborted_tools' | 'stop_hook_prevented' | 'hook_stopped' | 'tool_deferred' | 'max_turns' | 'completed';
+/**
+ * PRD §6 Event entity — one row per significant SDK message during a Run.
+ * Stored as JSONL at ~/.clementine/events/<run_id>.jsonl. Powers the new
+ * Run detail waterfall (Phase 4b) and the metrics dashboards (Phase 6).
+ *
+ * Designed to fit the SDK's typed message stream + the 12 hook events. Most
+ * fields are optional because each event kind populates a different subset.
+ */
+export interface RunEvent {
+    /** Run this event belongs to — links back to CronRunEntry.id. */
+    runId: string;
+    /** SDK session id once known (system/init lands first; everything else carries it). */
+    sessionId?: string;
+    /** Monotonic sequence within the run. Used to order events that share a ts. */
+    seq: number;
+    /** ISO timestamp when the event was captured. */
+    ts: string;
+    /** Event kind — semantic grouping for the dashboard's span types. */
+    kind: 'session_start' | 'session_end' | 'llm_text' | 'thinking' | 'tool_call' | 'tool_result' | 'subagent_start' | 'subagent_stop' | 'rate_limit' | 'hook' | 'error';
+    /** Hook event name when kind='hook' (PreToolUse / PostToolUse / etc.). */
+    hookEventName?: string;
+    /** Tool name when kind='tool_call' or 'tool_result'. Includes mcp__ prefix. */
+    toolName?: string;
+    /** SDK-assigned tool_use id — pairs tool_call with its tool_result. */
+    toolUseId?: string;
+    /** For nested tool calls (parallel sub-spawning). */
+    parentToolUseId?: string;
+    /** Tool input as JSON, truncated at 8KB. */
+    toolInput?: unknown;
+    /** Tool result as JSON or string, truncated at 16KB. */
+    toolResult?: unknown;
+    /** Tool error message when result.is_error or PostToolUseFailure. */
+    toolError?: string;
+    /** Assistant text block content when kind='llm_text'. */
+    text?: string;
+    /** ThinkingBlock content when kind='thinking'. */
+    thinking?: string;
+    /** Cost so far for this run when kind='session_end'. */
+    costUsd?: number;
+    /** Stop reason from ResultMessage when kind='session_end'. */
+    stopReason?: string;
+    /** Subagent id when kind='subagent_*'. */
+    agentId?: string;
+}
 export interface CronRunEntry {
+    /** PRD §6 / 1.18.85: stable run UUID. Optional only because pre-1.18.85
+     *  entries don't have it; new entries always do. The Event store keys
+     *  off this id. */
+    id?: string;
     jobName: string;
     startedAt: string;
     /** Optional: in-progress runs are appended with status='running' before the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.84",
+  "version": "1.18.86",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",