clementine-agent 1.18.99 → 1.18.101

package/dist/agent/hook-session-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * PRD §6 Phase 4d / 1.18.101 — Path B (hook side-channel) session registry.
+ *
+ * The Claude Agent SDK's hook mechanism (PreToolUse, PostToolUse, SubagentStart,
+ * SubagentStop, Stop, Notification, etc.) lets command-type hooks defined in
+ * `.claude/settings.json` POST event JSON to an external endpoint. Path B is
+ * how the dashboard receives those events and merges them into the per-run
+ * event log so the Run detail viewer + Latency dashboard see real per-tool
+ * durations (not the path A heuristic).
+ *
+ * The challenge: hook events arrive with the SDK `session_id`, but the
+ * dashboard's RunEvent rows key off the dashboard-assigned `runId` UUID. This
+ * registry bridges the two — `runAgent` registers a `(sessionId, runId,
+ * eventLog)` tuple on the SystemMessage init, the hook ingest endpoint looks
+ * up by sessionId, and the entry clears on session_end so memory doesn't leak.
+ *
+ * Design notes:
+ * - In-memory only (Map). Reboot clears all sessions; that's correct because
+ *   any in-flight runs are abandoned by the daemon restart sweep anyway.
+ * - Multiple concurrent runs are supported (one entry per active SDK session).
+ * - Best-effort: if a hook arrives after session_end (race), we silently drop
+ *   the event rather than replay onto a closed run. The dashboard's run
+ *   detail can show a "stale hook event" diagnostic if this becomes common.
+ */
+import type { EventLog } from '../gateway/event-log.js';
+export interface HookSessionEntry {
+    /** Dashboard-assigned UUID linking back to CronRunEntry.id. */
+    runId: string;
+    /** EventLog instance owning the run's JSONL file. Reused so path B writes
+     *  go to the same file as path A live events. */
+    eventLog: EventLog;
+    /** Wall-clock when the registration happened. Used for janitor cleanup
+     *  if a session_end never fires (SDK crash / network blip). */
+    registeredAt: number;
+    /** Atomic counter used so path B writes get monotonically increasing seqs
+     *  even when interleaved with path A. The registry hands out seq numbers
+     *  via `nextSeq()` below; path A uses its own closure-local counter and
+     *  the EventLog dedupes on disk via append-only ordering. */
+    seqCounter: number;
+}
+export declare function registerRunSession(sessionId: string, runId: string, eventLog: EventLog, seqStart?: number): void;
+export declare function unregisterRunSession(sessionId: string): void;
+export declare function getRunSession(sessionId: string): HookSessionEntry | null;
+/** Hand out the next monotonic seq for path B writes on this session. The
+ *  caller is responsible for actually appending the event; this function
+ *  just bumps the counter and returns the prior value so writes are stable
+ *  under concurrent calls. */
+export declare function nextSeqForSession(sessionId: string): number | null;
+/** Best-effort sweep — call from a periodic timer or before each lookup
+ *  to keep stale entries from accumulating. Currently called from the
+ *  ingest endpoint on every POST so we don't need a dedicated timer. */
+export declare function sweepStaleSessions(): number;
+/** Test-only: snapshot of the live map size + age distribution. Useful for
+ *  janitor diagnostics in the dashboard. */
+export declare function getRegistryStats(): {
+    count: number;
+    oldestAgeMs: number | null;
+};
+/** Test-only: clear the registry between tests. Never call from production. */
+export declare function _resetRegistryForTests(): void;
+//# sourceMappingURL=hook-session-registry.d.ts.map

package/dist/agent/hook-session-registry.js

@@ -0,0 +1,92 @@
+/**
+ * PRD §6 Phase 4d / 1.18.101 — Path B (hook side-channel) session registry.
+ *
+ * The Claude Agent SDK's hook mechanism (PreToolUse, PostToolUse, SubagentStart,
+ * SubagentStop, Stop, Notification, etc.) lets command-type hooks defined in
+ * `.claude/settings.json` POST event JSON to an external endpoint. Path B is
+ * how the dashboard receives those events and merges them into the per-run
+ * event log so the Run detail viewer + Latency dashboard see real per-tool
+ * durations (not the path A heuristic).
+ *
+ * The challenge: hook events arrive with the SDK `session_id`, but the
+ * dashboard's RunEvent rows key off the dashboard-assigned `runId` UUID. This
+ * registry bridges the two — `runAgent` registers a `(sessionId, runId,
+ * eventLog)` tuple on the SystemMessage init, the hook ingest endpoint looks
+ * up by sessionId, and the entry clears on session_end so memory doesn't leak.
+ *
+ * Design notes:
+ * - In-memory only (Map). Reboot clears all sessions; that's correct because
+ *   any in-flight runs are abandoned by the daemon restart sweep anyway.
+ * - Multiple concurrent runs are supported (one entry per active SDK session).
+ * - Best-effort: if a hook arrives after session_end (race), we silently drop
+ *   the event rather than replay onto a closed run. The dashboard's run
+ *   detail can show a "stale hook event" diagnostic if this becomes common.
+ */
+const sessions = new Map();
+/** Janitor sweep: clear sessions that have been registered for more than this
+ *  many ms without a session_end. Keeps the map bounded if the daemon stays
+ *  up but a run dies in a way that bypasses our session_end handler. */
+const STALE_SESSION_MS = 6 * 60 * 60 * 1000; // 6h — matches longest cron wall cap
+export function registerRunSession(sessionId, runId, eventLog, seqStart = 0) {
+    if (!sessionId || !runId)
+        return;
+    sessions.set(sessionId, { runId, eventLog, registeredAt: Date.now(), seqCounter: seqStart });
+}
+export function unregisterRunSession(sessionId) {
+    if (!sessionId)
+        return;
+    sessions.delete(sessionId);
+}
+export function getRunSession(sessionId) {
+    return sessions.get(sessionId) ?? null;
+}
+/** Hand out the next monotonic seq for path B writes on this session. The
+ *  caller is responsible for actually appending the event; this function
+ *  just bumps the counter and returns the prior value so writes are stable
+ *  under concurrent calls. */
+export function nextSeqForSession(sessionId) {
+    const entry = sessions.get(sessionId);
+    if (!entry)
+        return null;
+    // Path B seqs start at 1_000_000 to keep them visually distinct from
+    // path A in the event log + so a sort by seq groups them after path A
+    // writes that share the same timestamp. Multi-million seq numbers are
+    // fine — the field is plain JSON number, no overflow risk for the
+    // forseeable future.
+    const seq = 1_000_000 + entry.seqCounter;
+    entry.seqCounter += 1;
+    return seq;
+}
+/** Best-effort sweep — call from a periodic timer or before each lookup
+ *  to keep stale entries from accumulating. Currently called from the
+ *  ingest endpoint on every POST so we don't need a dedicated timer. */
+export function sweepStaleSessions() {
+    const now = Date.now();
+    let removed = 0;
+    for (const [sid, entry] of sessions.entries()) {
+        if (now - entry.registeredAt > STALE_SESSION_MS) {
+            sessions.delete(sid);
+            removed += 1;
+        }
+    }
+    return removed;
+}
+/** Test-only: snapshot of the live map size + age distribution. Useful for
+ *  janitor diagnostics in the dashboard. */
+export function getRegistryStats() {
+    if (sessions.size === 0)
+        return { count: 0, oldestAgeMs: null };
+    const now = Date.now();
+    let oldest = 0;
+    for (const entry of sessions.values()) {
+        const age = now - entry.registeredAt;
+        if (age > oldest)
+            oldest = age;
+    }
+    return { count: sessions.size, oldestAgeMs: oldest };
+}
+/** Test-only: clear the registry between tests. Never call from production. */
+export function _resetRegistryForTests() {
+    sessions.clear();
+}
+//# sourceMappingURL=hook-session-registry.js.map

package/dist/agent/run-agent.js

@@ -325,6 +325,17 @@ export async function runAgent(prompt, opts) {
                 }
                 // PRD Phase 4a / 1.18.85: write the session_start Event row.
                 writeEvent({ kind: 'session_start', ts: new Date().toISOString(), sessionId });
+                // PRD Phase 4d / 1.18.101: register this session in the path B
+                // hook-session registry so /api/hooks/event POSTs from the SDK can
+                // resolve sessionId → runId/eventLog and write into the same JSONL.
+                // Best-effort — telemetry must never block the run from progressing.
+                try {
+                    const { registerRunSession } = await import('./hook-session-registry.js');
+                    registerRunSession(sessionId, runId, eventLog, eventSeq);
+                }
+                catch (regErr) {
+                    logger.debug({ regErr }, 'runAgent: hook-session registry register failed (non-fatal)');
+                }
                 logger.debug({ sessionKey: opts.sessionKey, sdkSessionId: sessionId, runId }, 'runAgent: SDK session initialized');
                 continue;
             }
@@ -428,6 +439,13 @@ export async function runAgent(prompt, opts) {
                     costUsd: totalCostUsd,
                     stopReason: subtype,
                 });
+                // PRD Phase 4d / 1.18.101: unregister from the hook-session registry.
+                // Late-arriving hook events for this sessionId silently drop after this.
+                try {
+                    const { unregisterRunSession } = await import('./hook-session-registry.js');
+                    unregisterRunSession(sessionId);
+                }
+                catch { /* non-fatal */ }
                 // Mirror cost to usage_log. Same shape as the existing
                 // logQueryResult, but standalone so we don't depend on
                 // PersonalAssistant's instance state.
@@ -466,6 +484,14 @@ export async function runAgent(prompt, opts) {
             sessionId,
             toolError: errMsg,
         });
+        // PRD Phase 4d / 1.18.101: also clear path B registry on error path so
+        // the map doesn't leak entries when runs fail before session_end fires.
+        try {
+            const { unregisterRunSession } = await import('./hook-session-registry.js');
+            if (sessionId)
+                unregisterRunSession(sessionId);
+        }
+        catch { /* non-fatal */ }
         // 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:

package/dist/cli/dashboard.js

@@ -5720,6 +5720,87 @@ If the tool returns nothing or errors, return an empty array \`[]\`.`,
             res.status(500).json({ error: String(err) });
         }
     });
+    // ── PRD Phase 4d / 1.18.101: Path B hook event ingest ──────────
+    // The Claude Agent SDK supports `.claude/settings.json`-registered command
+    // hooks (PreToolUse, PostToolUse, SubagentStart, SubagentStop, Stop,
+    // Notification, etc.). When a hook fires the SDK pipes JSON to the
+    // command's stdin; the command can POST that JSON to this endpoint to
+    // get the event recorded in the same per-run JSONL the in-process tap
+    // (path A) writes to. The result: real per-tool-call durations,
+    // approval-required events, and stop-reason hooks land in the Run detail
+    // viewer's waterfall + the Latency dashboard's split bar.
+    //
+    // Auth: dashboard token via X-Dashboard-Token header. The daemon
+    // exposes the token via CLEMENTINE_DASHBOARD_TOKEN env var, which the
+    // SDK subprocess inherits — settings.json hook commands curl this
+    // endpoint with that header.
+    app.post('/api/hooks/event', express.json({ limit: '256kb' }), async (req, res) => {
+        try {
+            const headerToken = String(req.header('x-dashboard-token') || '');
+            if (!dashboardToken || headerToken !== dashboardToken) {
+                res.status(401).json({ ok: false, error: 'invalid dashboard token' });
+                return;
+            }
+            const body = (req.body ?? {});
+            const sessionId = String(body.session_id || body.sessionId || '');
+            const hookEventName = String(body.hook_event_name || body.hookEventName || 'unknown');
+            if (!sessionId) {
+                res.status(400).json({ ok: false, error: 'session_id required in payload' });
+                return;
+            }
+            const { getRunSession, nextSeqForSession, sweepStaleSessions } = await import('../agent/hook-session-registry.js');
+            // Best-effort sweep on every POST — keeps the map bounded without a timer.
+            sweepStaleSessions();
+            const entry = getRunSession(sessionId);
+            if (!entry) {
+                // Late-arriving hook for a session we already closed (or never
+                // saw because path A registration didn't complete). Drop and tell
+                // the caller — the curl exits 0 either way so it doesn't fail
+                // the SDK's run.
+                res.status(202).json({ ok: false, dropped: true, reason: 'session not registered (race or post-end)' });
+                return;
+            }
+            const seq = nextSeqForSession(sessionId);
+            // Synthesize a RunEvent. The hook payload's shape varies by event
+            // kind; we extract the fields the dashboard waterfall renders and
+            // stash the full payload for advanced filtering later.
+            const ev = {
+                runId: entry.runId,
+                seq: seq ?? 1_000_000,
+                kind: 'hook',
+                ts: new Date().toISOString(),
+                sessionId,
+                hookEventName,
+            };
+            // Tool fields if present (PreToolUse / PostToolUse).
+            if (typeof body.tool_name === 'string')
+                ev.toolName = body.tool_name;
+            if (typeof body.tool_use_id === 'string')
+                ev.toolUseId = body.tool_use_id;
+            if (body.tool_input !== undefined)
+                ev.toolInput = body.tool_input;
+            if (body.tool_response !== undefined)
+                ev.toolResult = body.tool_response;
+            // PostToolUse can carry an explicit duration_ms (the SDK's stopwatch
+            // wraps the tool call). When present we surface it onto the event so
+            // the latency dashboard sums real numbers instead of the heuristic.
+            if (typeof body.duration_ms === 'number')
+                ev.durationMs = body.duration_ms;
+            if (typeof body.parent_tool_use_id === 'string')
+                ev.parentToolUseId = body.parent_tool_use_id;
+            // Errors: PostToolUse can flag a non-zero result; surface as toolError.
+            if (body.is_error === true) {
+                ev.toolError = typeof body.tool_response === 'string'
+                    ? body.tool_response.slice(0, 500)
+                    : 'tool returned is_error=true';
+            }
+            entry.eventLog.append(ev);
+            res.json({ ok: true, runId: entry.runId, seq });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, 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).
@@ -34325,7 +34406,7 @@ function buildAgentToolRow(cat, tool) {
   var pathHint = (type === 'project' && tool.path) ? ' <span style="color:var(--text-muted);font-size:10px">' + esc(tool.path) + '</span>' : '';
   var statusEl;
   if (setupTarget) {
-    statusEl = '<a class="tt-status ' + statusClass + '" href="#" onclick="event.preventDefault();event.stopPropagation();navigateTo(\'' + setupTarget + '\');hideAgentModal();" style="text-decoration:none"><span class="tt-dot"></span>' + esc(statusLabel) + ' →</a>';
+    statusEl = '<a class="tt-status ' + statusClass + '" href="#" onclick="event.preventDefault();event.stopPropagation();navigateTo(\\x27' + setupTarget + '\\x27);hideAgentModal();" style="text-decoration:none"><span class="tt-dot"></span>' + esc(statusLabel) + ' →</a>';
   } else {
     statusEl = '<span class="tt-status ' + statusClass + '"><span class="tt-dot"></span>' + esc(statusLabel) + '</span>';
   }

package/package.json

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