shieldcortex 4.16.0 → 4.18.0

package/dist/sessions/capture.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Session capture — write side.
+ *
+ * Hooks (`scripts/prompt-recall-hook.mjs`, `scripts/stop-hook.mjs`,
+ * `scripts/session-end-hook.mjs`, etc.) call `recordEvent()` or the
+ * batched `recordEvents()` to persist turn-by-turn events into the
+ * `session_events` table. The timeline reader in `./timeline.ts`
+ * then reassembles them into the replay stream.
+ *
+ * Distinct from the summary `sessions` table (one row per session)
+ * and from `defence_audit` (one row per scan). Captures every event
+ * with enough fidelity to scrub/replay.
+ */
+/**
+ * Six kinds the schema CHECK constraint enforces. Keeping these in
+ * sync with `schema.sql` is load-bearing — adding a new kind requires
+ * both a schema migration and a code update here.
+ */
+export type SessionEventKind = 'prompt' | 'response' | 'tool_call' | 'tool_result' | 'tool_error' | 'hook_fire';
+export interface SessionEventInput {
+    session_id: string;
+    /** ISO-8601 timestamp string. Caller-supplied so import order is preserved. */
+    ts: string;
+    kind: SessionEventKind;
+    /**
+     * Payload — object (auto-serialised to JSON) or string (stored as-is).
+     * Strings are kept verbatim so JSONL importers can pass through raw
+     * content without double-encoding.
+     */
+    payload: unknown;
+    project?: string | null;
+    actor?: string | null;
+    duration_ms?: number | null;
+    audit_id?: number | null;
+}
+/** Insert one event row. Returns the new row id. */
+export declare function recordEvent(input: SessionEventInput): number;
+/**
+ * Batched insert wrapped in a single transaction. Used when a hook
+ * fires and produces several events at once (e.g. stop-hook emitting
+ * a `response` plus N tool_call/tool_result pairs from the just-
+ * finished turn). All-or-nothing: a CHECK violation rolls back the
+ * lot, so the table never holds half a turn.
+ */
+export declare function recordEvents(inputs: readonly SessionEventInput[]): number[];

package/dist/sessions/capture.js

@@ -0,0 +1,59 @@
+/**
+ * Session capture — write side.
+ *
+ * Hooks (`scripts/prompt-recall-hook.mjs`, `scripts/stop-hook.mjs`,
+ * `scripts/session-end-hook.mjs`, etc.) call `recordEvent()` or the
+ * batched `recordEvents()` to persist turn-by-turn events into the
+ * `session_events` table. The timeline reader in `./timeline.ts`
+ * then reassembles them into the replay stream.
+ *
+ * Distinct from the summary `sessions` table (one row per session)
+ * and from `defence_audit` (one row per scan). Captures every event
+ * with enough fidelity to scrub/replay.
+ */
+import { getDatabase } from '../database/init.js';
+/**
+ * Serialise payload to text. Objects/arrays go through JSON.stringify;
+ * strings pass through. This keeps the column NOT NULL constraint
+ * satisfied even for empty-object payloads and matches the timeline
+ * reader's `JSON.parse` with raw-string fallback.
+ */
+function serialisePayload(payload) {
+    if (typeof payload === 'string')
+        return payload;
+    return JSON.stringify(payload ?? null);
+}
+const INSERT_SQL = `
+  INSERT INTO session_events
+    (session_id, project, ts, kind, actor, payload, duration_ms, audit_id)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+`;
+/** Insert one event row. Returns the new row id. */
+export function recordEvent(input) {
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_SQL);
+    const result = stmt.run(input.session_id, input.project ?? null, input.ts, input.kind, input.actor ?? null, serialisePayload(input.payload), input.duration_ms ?? null, input.audit_id ?? null);
+    return Number(result.lastInsertRowid);
+}
+/**
+ * Batched insert wrapped in a single transaction. Used when a hook
+ * fires and produces several events at once (e.g. stop-hook emitting
+ * a `response` plus N tool_call/tool_result pairs from the just-
+ * finished turn). All-or-nothing: a CHECK violation rolls back the
+ * lot, so the table never holds half a turn.
+ */
+export function recordEvents(inputs) {
+    if (inputs.length === 0)
+        return [];
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_SQL);
+    const ids = [];
+    const tx = db.transaction((rows) => {
+        for (const row of rows) {
+            const result = stmt.run(row.session_id, row.project ?? null, row.ts, row.kind, row.actor ?? null, serialisePayload(row.payload), row.duration_ms ?? null, row.audit_id ?? null);
+            ids.push(Number(result.lastInsertRowid));
+        }
+    });
+    tx(inputs);
+    return ids;
+}

package/dist/sessions/glob.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Minimal portable glob expansion for the session-capture import flow.
+ *
+ * Node 22 added `fs.promises.glob`, but ShieldCortex's `engines.node`
+ * still declares `>=18.0.0` — using fs/promises.glob would break the
+ * CI matrix (Node 20) and any production deployment running an LTS
+ * earlier than 22. This module implements the narrow subset of glob
+ * semantics the importer actually needs:
+ *
+ *   - Literal paths (no wildcards) — return as-is, caller checks existence.
+ *   - Shell wildcards `*` `?` `[]` within a single directory segment.
+ *   - `**` for any-depth recursion (only between `/`-separated segments;
+ *     `**` inside a filename is treated as a regular `*` `*`).
+ *
+ * No braces, no extglob, no negation. The JSONL importer doesn't need
+ * those and pulling in a full glob package would inflate the install
+ * footprint for a single feature.
+ */
+export interface ExpandGlobOptions {
+    /**
+     * Cap on the number of returned matches. Stops walking once hit so
+     * pathological globs against `/` don't lock up the API process.
+     */
+    maxMatches?: number;
+}
+/**
+ * Returns `true` when the pattern contains any glob metacharacter the
+ * walker treats specially. Used by callers to short-circuit literal
+ * paths and skip the walker entirely.
+ */
+export declare function isGlobPattern(pattern: string): boolean;
+/**
+ * Expand a glob pattern to absolute file paths. Synchronous because
+ * the importer's callsites are already synchronous and the result is
+ * always small enough that I/O is not the bottleneck (sessions live
+ * on local disk under `~/.claude/projects/`).
+ */
+export declare function expandGlob(pattern: string, options?: ExpandGlobOptions): string[];

package/dist/sessions/glob.js

@@ -0,0 +1,183 @@
+/**
+ * Minimal portable glob expansion for the session-capture import flow.
+ *
+ * Node 22 added `fs.promises.glob`, but ShieldCortex's `engines.node`
+ * still declares `>=18.0.0` — using fs/promises.glob would break the
+ * CI matrix (Node 20) and any production deployment running an LTS
+ * earlier than 22. This module implements the narrow subset of glob
+ * semantics the importer actually needs:
+ *
+ *   - Literal paths (no wildcards) — return as-is, caller checks existence.
+ *   - Shell wildcards `*` `?` `[]` within a single directory segment.
+ *   - `**` for any-depth recursion (only between `/`-separated segments;
+ *     `**` inside a filename is treated as a regular `*` `*`).
+ *
+ * No braces, no extglob, no negation. The JSONL importer doesn't need
+ * those and pulling in a full glob package would inflate the install
+ * footprint for a single feature.
+ */
+import { readdirSync, statSync } from 'fs';
+import { join, sep, isAbsolute } from 'path';
+import { homedir } from 'os';
+const DEFAULT_MAX_MATCHES = 10_000;
+/**
+ * Returns `true` when the pattern contains any glob metacharacter the
+ * walker treats specially. Used by callers to short-circuit literal
+ * paths and skip the walker entirely.
+ */
+export function isGlobPattern(pattern) {
+    return /[*?[\]]/.test(pattern);
+}
+/**
+ * Expand a glob pattern to absolute file paths. Synchronous because
+ * the importer's callsites are already synchronous and the result is
+ * always small enough that I/O is not the bottleneck (sessions live
+ * on local disk under `~/.claude/projects/`).
+ */
+export function expandGlob(pattern, options = {}) {
+    const max = options.maxMatches ?? DEFAULT_MAX_MATCHES;
+    const expanded = expandHome(pattern);
+    if (!isGlobPattern(expanded)) {
+        return [expanded];
+    }
+    const segments = expanded.split(/[\\/]+/);
+    // Determine the literal prefix — everything up to the first segment
+    // that has a wildcard. Walking starts from there.
+    let prefix = isAbsolute(expanded) ? sep : '';
+    let i = 0;
+    for (; i < segments.length; i++) {
+        if (isGlobPattern(segments[i]))
+            break;
+        prefix = prefix === sep ? sep + segments[i] : prefix ? join(prefix, segments[i]) : segments[i];
+    }
+    if (prefix === '')
+        prefix = '.';
+    const remaining = segments.slice(i);
+    const matches = [];
+    walk(prefix, remaining, matches, max);
+    return matches.sort();
+}
+/** Recursive matcher. */
+function walk(currentDir, segments, out, max) {
+    if (out.length >= max)
+        return;
+    if (segments.length === 0)
+        return;
+    const [head, ...rest] = segments;
+    // `**` — match any number of directory levels (including zero).
+    if (head === '**') {
+        // Zero levels: continue at currentDir with `rest`.
+        walk(currentDir, rest, out, max);
+        // One-or-more: recurse into every subdirectory with the same `**`.
+        let entries = [];
+        try {
+            entries = readdirSync(currentDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (out.length >= max)
+                return;
+            if (entry.isDirectory()) {
+                walk(join(currentDir, String(entry.name)), segments, out, max);
+            }
+        }
+        return;
+    }
+    const regex = segmentToRegex(head);
+    const isLastSegment = rest.length === 0;
+    let entries = [];
+    try {
+        entries = readdirSync(currentDir, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (out.length >= max)
+            return;
+        const name = String(entry.name);
+        if (!regex.test(name))
+            continue;
+        const full = join(currentDir, name);
+        if (isLastSegment) {
+            // Only files match a leaf glob — directories aren't useful for the importer.
+            if (entry.isFile())
+                out.push(full);
+            else if (entry.isSymbolicLink()) {
+                // Resolve symlinks lazily — a broken link just gets skipped.
+                try {
+                    if (statSync(full).isFile())
+                        out.push(full);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        else if (entry.isDirectory() || entry.isSymbolicLink()) {
+            walk(full, rest, out, max);
+        }
+    }
+}
+/** Convert a single shell-glob path segment to a regex. */
+function segmentToRegex(segment) {
+    let pattern = '^';
+    let inCharClass = false;
+    for (let i = 0; i < segment.length; i++) {
+        const c = segment[i];
+        if (inCharClass) {
+            if (c === ']') {
+                inCharClass = false;
+                pattern += ']';
+            }
+            else if (c === '\\') {
+                pattern += '\\\\';
+            }
+            else {
+                pattern += escapeForRegex(c);
+            }
+            continue;
+        }
+        switch (c) {
+            case '*':
+                pattern += '[^/\\\\]*';
+                break;
+            case '?':
+                pattern += '[^/\\\\]';
+                break;
+            case '[':
+                inCharClass = true;
+                pattern += '[';
+                break;
+            case '.':
+            case '+':
+            case '(':
+            case ')':
+            case '{':
+            case '}':
+            case '|':
+            case '^':
+            case '$':
+                pattern += '\\' + c;
+                break;
+            default:
+                pattern += c;
+        }
+    }
+    pattern += '$';
+    return new RegExp(pattern);
+}
+function escapeForRegex(c) {
+    return /[.*+?^${}()|[\]\\]/.test(c) ? '\\' + c : c;
+}
+/** Expand a leading `~` to the user's home directory. */
+function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\')) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}

package/dist/sessions/import-jsonl.d.ts

@@ -0,0 +1,85 @@
+/**
+ * JSONL transcript importer for Claude Code session files.
+ *
+ * Claude Code writes session transcripts to `~/.claude/projects/<slug>/
+ * <session-uuid>.jsonl`. Each line is a JSON object. Conversation lines
+ * have shape `{type, sessionId, timestamp, message: {role, content}}`
+ * where `content` is an Anthropic SDK content-block array
+ * (`text|thinking|tool_use|tool_result`).
+ *
+ * Mapping to `session_events.kind`:
+ *
+ *   user.text         → prompt
+ *   assistant.text    → response
+ *   assistant.tool_use → tool_call
+ *   user.tool_result  → tool_result
+ *   thinking          → (skipped — not user-replayable in v1)
+ *
+ * Non-conversation lines (`ai-title`, `attachment`, `system`,
+ * `queue-operation`, etc.) are skipped. Idempotent on re-import: each
+ * row carries a sha256 `content_hash` of `kind|payload`, and the
+ * `idx_session_events_dedupe` UNIQUE index drops collisions silently
+ * via `INSERT OR IGNORE`.
+ *
+ * Lossy by design — agentmemory documents the same scope:
+ *   - Anthropic-internal cache markers, partial-message frames, and
+ *     non-string tool_result encodings beyond plain text are not
+ *     preserved.
+ *   - Things we WILL preserve: prompts, assistant text, tool name +
+ *     args + result, and timestamps.
+ */
+import type { SessionEventInput } from './capture.js';
+export interface TranscriptLine {
+    type?: string;
+    sessionId?: string;
+    timestamp?: string;
+    message?: {
+        role?: 'user' | 'assistant';
+        content?: ContentBlock[];
+    };
+}
+type ContentBlock = {
+    type: 'text';
+    text?: string;
+} | {
+    type: 'thinking';
+    thinking?: string;
+} | {
+    type: 'tool_use';
+    id?: string;
+    name?: string;
+    input?: unknown;
+} | {
+    type: 'tool_result';
+    tool_use_id?: string;
+    content?: unknown;
+} | {
+    type: string;
+    [key: string]: unknown;
+};
+export interface ImportResult {
+    sessionId: string | null;
+    eventCount: number;
+    /** Lines that produced zero events — non-conversation types + parse errors. */
+    skipped: number;
+    /** Lines whose JSON parsed but were rejected (missing required fields, unknown block types). */
+    malformed: number;
+}
+/**
+ * Pure mapper: one transcript line → 0..N `SessionEventInput`s.
+ *
+ * Exported so unit tests can exercise the mapping in isolation without
+ * standing up a database. Returns `[]` for any line that doesn't yield
+ * replayable events (thinking blocks, ai-title, missing fields, etc.) —
+ * the caller treats an empty array as "skipped".
+ */
+export declare function parseTranscriptLine(line: unknown): SessionEventInput[];
+/**
+ * Import one JSONL file. Wraps the whole import in a single transaction
+ * so a mid-file error rolls back cleanly — better-sqlite3's transaction
+ * helper restores DB state if the callback throws. Malformed lines do
+ * NOT throw — they're counted and skipped so a single bad row never
+ * blocks the rest of the file.
+ */
+export declare function importJsonlTranscript(path: string): ImportResult;
+export {};

package/dist/sessions/import-jsonl.js

@@ -0,0 +1,193 @@
+/**
+ * JSONL transcript importer for Claude Code session files.
+ *
+ * Claude Code writes session transcripts to `~/.claude/projects/<slug>/
+ * <session-uuid>.jsonl`. Each line is a JSON object. Conversation lines
+ * have shape `{type, sessionId, timestamp, message: {role, content}}`
+ * where `content` is an Anthropic SDK content-block array
+ * (`text|thinking|tool_use|tool_result`).
+ *
+ * Mapping to `session_events.kind`:
+ *
+ *   user.text         → prompt
+ *   assistant.text    → response
+ *   assistant.tool_use → tool_call
+ *   user.tool_result  → tool_result
+ *   thinking          → (skipped — not user-replayable in v1)
+ *
+ * Non-conversation lines (`ai-title`, `attachment`, `system`,
+ * `queue-operation`, etc.) are skipped. Idempotent on re-import: each
+ * row carries a sha256 `content_hash` of `kind|payload`, and the
+ * `idx_session_events_dedupe` UNIQUE index drops collisions silently
+ * via `INSERT OR IGNORE`.
+ *
+ * Lossy by design — agentmemory documents the same scope:
+ *   - Anthropic-internal cache markers, partial-message frames, and
+ *     non-string tool_result encodings beyond plain text are not
+ *     preserved.
+ *   - Things we WILL preserve: prompts, assistant text, tool name +
+ *     args + result, and timestamps.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+import { getDatabase } from '../database/init.js';
+/**
+ * Pure mapper: one transcript line → 0..N `SessionEventInput`s.
+ *
+ * Exported so unit tests can exercise the mapping in isolation without
+ * standing up a database. Returns `[]` for any line that doesn't yield
+ * replayable events (thinking blocks, ai-title, missing fields, etc.) —
+ * the caller treats an empty array as "skipped".
+ */
+export function parseTranscriptLine(line) {
+    if (!line || typeof line !== 'object')
+        return [];
+    const l = line;
+    // Only conversation lines yield events.
+    if (l.type !== 'user' && l.type !== 'assistant')
+        return [];
+    if (typeof l.sessionId !== 'string' || l.sessionId.length === 0)
+        return [];
+    if (typeof l.timestamp !== 'string' || l.timestamp.length === 0)
+        return [];
+    const content = l.message?.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return [];
+    const events = [];
+    for (const block of content) {
+        const event = blockToEvent(block, l);
+        if (event)
+            events.push(event);
+    }
+    return events;
+}
+function blockToEvent(block, line) {
+    const session_id = line.sessionId;
+    const ts = line.timestamp;
+    if (block.type === 'thinking')
+        return null;
+    if (block.type === 'text' && line.type === 'user') {
+        const text = typeof block.text === 'string' ? block.text : '';
+        if (!text)
+            return null;
+        return { session_id, ts, kind: 'prompt', payload: { text } };
+    }
+    if (block.type === 'text' && line.type === 'assistant') {
+        const text = typeof block.text === 'string' ? block.text : '';
+        if (!text)
+            return null;
+        return {
+            session_id,
+            ts,
+            kind: 'response',
+            payload: { text },
+            actor: 'assistant',
+        };
+    }
+    if (block.type === 'tool_use' && line.type === 'assistant') {
+        const toolBlock = block;
+        return {
+            session_id,
+            ts,
+            kind: 'tool_call',
+            payload: {
+                tool_use_id: toolBlock.id ?? null,
+                name: toolBlock.name ?? null,
+                input: toolBlock.input ?? null,
+            },
+            actor: 'assistant',
+        };
+    }
+    if (block.type === 'tool_result' && line.type === 'user') {
+        const tr = block;
+        return {
+            session_id,
+            ts,
+            kind: 'tool_result',
+            payload: {
+                tool_use_id: tr.tool_use_id ?? null,
+                content: tr.content ?? null,
+            },
+        };
+    }
+    return null;
+}
+/** SHA-256 of `kind|payload-as-canonical-json`. 64-char hex string. */
+function hashEvent(kind, payload) {
+    const canonical = typeof payload === 'string' ? payload : JSON.stringify(payload ?? null);
+    return createHash('sha256').update(`${kind}|${canonical}`).digest('hex');
+}
+const INSERT_OR_IGNORE_SQL = `
+  INSERT OR IGNORE INTO session_events
+    (session_id, project, ts, kind, actor, payload, duration_ms, audit_id, content_hash)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+`;
+/**
+ * Import one JSONL file. Wraps the whole import in a single transaction
+ * so a mid-file error rolls back cleanly — better-sqlite3's transaction
+ * helper restores DB state if the callback throws. Malformed lines do
+ * NOT throw — they're counted and skipped so a single bad row never
+ * blocks the rest of the file.
+ */
+export function importJsonlTranscript(path) {
+    if (!existsSync(path)) {
+        throw new Error(`JSONL transcript not found: ${path}`);
+    }
+    const raw = readFileSync(path, 'utf-8');
+    const lines = raw.split(/\r?\n/);
+    const rows = [];
+    let sessionId = null;
+    let skipped = 0;
+    let malformed = 0;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0)
+            continue; // blank lines aren't skipped — they're just whitespace
+        let parsed;
+        try {
+            parsed = JSON.parse(trimmed);
+        }
+        catch {
+            malformed++;
+            skipped++;
+            continue;
+        }
+        const events = parseTranscriptLine(parsed);
+        if (events.length === 0) {
+            skipped++;
+            continue;
+        }
+        if (sessionId === null && events[0]?.session_id) {
+            sessionId = events[0].session_id;
+        }
+        for (const event of events) {
+            rows.push({
+                ...event,
+                content_hash: hashEvent(event.kind, event.payload),
+            });
+        }
+    }
+    if (rows.length === 0) {
+        return { sessionId, eventCount: 0, skipped, malformed };
+    }
+    const db = getDatabase();
+    const stmt = db.prepare(INSERT_OR_IGNORE_SQL);
+    const before = db.prepare('SELECT COUNT(*) AS c FROM session_events').get().c;
+    const tx = db.transaction((batch) => {
+        for (const row of batch) {
+            stmt.run(row.session_id, row.project ?? null, row.ts, row.kind, row.actor ?? null, typeof row.payload === 'string' ? row.payload : JSON.stringify(row.payload ?? null), row.duration_ms ?? null, row.audit_id ?? null, row.content_hash);
+        }
+    });
+    tx(rows);
+    const after = db.prepare('SELECT COUNT(*) AS c FROM session_events').get().c;
+    const inserted = after - before;
+    // `eventCount` reflects the total events parsed from this file regardless
+    // of whether the dedupe index dropped them. Caller can compare to
+    // `inserted` (via row count diff) to see how many were duplicates.
+    return {
+        sessionId,
+        eventCount: rows.length,
+        skipped: skipped + (rows.length - inserted),
+        malformed,
+    };
+}

package/dist/sessions/timeline.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Session capture — read side.
+ *
+ * `getTimeline(sessionId)` returns every event for a session, sorted
+ * by `ts` ascending, with payload JSON.parse'd back into a JS value
+ * (or surfaced as a raw string when the payload was deliberately
+ * stored as plain text). Powers the dashboard replay scrubber.
+ *
+ * Kept deliberately minimal — pagination, filtering by kind, and
+ * cross-session timelines belong on the API route (`./api/routes/
+ * sessions.ts`) above, not in this reader.
+ */
+import type { SessionEventKind } from './capture.js';
+export interface SessionEventRow {
+    id: number;
+    session_id: string;
+    project: string | null;
+    ts: string;
+    kind: SessionEventKind;
+    actor: string | null;
+    /** Parsed JSON (object/array/primitive) or raw string fall-through. */
+    payload: unknown;
+    duration_ms: number | null;
+    audit_id: number | null;
+    created_at: string;
+}
+/** All events for a session, in `ts` ascending order. */
+export declare function getTimeline(sessionId: string): SessionEventRow[];

package/dist/sessions/timeline.js

@@ -0,0 +1,52 @@
+/**
+ * Session capture — read side.
+ *
+ * `getTimeline(sessionId)` returns every event for a session, sorted
+ * by `ts` ascending, with payload JSON.parse'd back into a JS value
+ * (or surfaced as a raw string when the payload was deliberately
+ * stored as plain text). Powers the dashboard replay scrubber.
+ *
+ * Kept deliberately minimal — pagination, filtering by kind, and
+ * cross-session timelines belong on the API route (`./api/routes/
+ * sessions.ts`) above, not in this reader.
+ */
+import { getDatabase } from '../database/init.js';
+/**
+ * Reverse of `capture.serialisePayload`: try JSON.parse, fall back to
+ * the raw string if the payload was stored as plain text. We don't
+ * throw on un-parseable — the importer may legitimately ingest non-JSON
+ * tool output, and a replay viewer that crashes on bad data is useless.
+ */
+function deserialisePayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function hydrate(row) {
+    return {
+        id: row.id,
+        session_id: row.session_id,
+        project: row.project,
+        ts: row.ts,
+        kind: row.kind,
+        actor: row.actor,
+        payload: deserialisePayload(row.payload),
+        duration_ms: row.duration_ms,
+        audit_id: row.audit_id,
+        created_at: row.created_at,
+    };
+}
+/** All events for a session, in `ts` ascending order. */
+export function getTimeline(sessionId) {
+    const db = getDatabase();
+    const rows = db
+        .prepare(`SELECT id, session_id, project, ts, kind, actor, payload, duration_ms, audit_id, created_at
+       FROM session_events
+       WHERE session_id = ?
+       ORDER BY ts ASC, id ASC`)
+        .all(sessionId);
+    return rows.map(hydrate);
+}