@hienlh/ppm 0.23.11 → 0.23.12

package/src/services/remote-desktop/remote-desktop-session.ts

@@ -16,6 +16,9 @@ import { avc1CodecString } from "./avc1-codec-string.ts";
 import type { AccessUnit } from "./access-unit-assembler.ts";
 import { injectPointer, injectKey, injectWheel, injectText, releaseAllModifiers, isInputAvailable, releaseRemoteInput } from "./remote-desktop-input.ts";
 import { resolveDisplay, type RemoteDisplay } from "./remote-desktop-displays.ts";
+import { startRelay, type RelayHandle } from "./mediamtx-process.ts";
+import { findMediamtxBinary } from "./mediamtx-paths.ts";
+import { registerWhepTarget, releaseWhepTicket } from "./remote-desktop-whep-registry.ts";
 import {
   MAX_CLIPBOARD_CHARS, pasteComboCodes, readHostClipboard, writeHostClipboard,
 } from "./remote-desktop-clipboard.ts";
@@ -55,6 +58,11 @@ const FRAME_AUDIO = 2;
 
 export class RemoteDesktopSession {
   private capture: CaptureHandle | null = null;
+  /** The MediaMTX relay, when this session streams over WebRTC. Outlives individual ffmpeg
+   *  respawns (a quality change restarts the publisher, not the relay). */
+  private relay: RelayHandle | null = null;
+  /** What the client presents to `POST /api/remote-desktop/whep/:ticket`. */
+  private whepTicket: string | null = null;
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private lastPingAt = Date.now();
   private droppingUntilKey = false;
@@ -116,6 +124,9 @@ export class RemoteDesktopSession {
     private readonly display: RemoteDisplay | null,
     drawMouse = true,
     encoder: string | null = null,
+    /** Stream over WebRTC through the local relay instead of framing access units onto this
+     *  socket. Only honoured when the relay is actually installed; see `beginCapture`. */
+    private readonly preferWebrtc = false,
   ) {
     this.drawMouse = drawMouse;
     this.encoder = encoder;
@@ -162,12 +173,17 @@ export class RemoteDesktopSession {
     this.captureExited = new Promise<void>((resolve) => { resolveExit = resolve; });
     this.sentConfig = false;
     this.droppingUntilKey = false;
+    const publishUrl = await this.ensureRelay();
     this.capture = await startCapture({
       display: this.display,
       preset: this.effectivePreset(),
       drawMouse: this.drawMouse,
       ...(this.encoder ? { encoder: this.encoder } : {}),
-      onAccessUnit: (au) => this.handleAccessUnit(au, generation),
+      // Exactly one of these. With a relay the encoded stream leaves over RTSP and this socket
+      // carries only control, so there are no access units to frame.
+      ...(publishUrl
+        ? { publishUrl }
+        : { onAccessUnit: (au: AccessUnit) => this.handleAccessUnit(au, generation) }),
       // `reason` is only set when ffmpeg died on its own (crash, access denied, etc) — tell
       // the client *why* before closing instead of leaving it to guess from a bare
       // disconnect (this is exactly what happens today for e.g. gdigrab failing against a
@@ -184,6 +200,57 @@ export class RemoteDesktopSession {
         }
       },
     });
+    // Announced after the publisher is spawned, but the client still has to retry: MediaMTX
+    // answers 404 until ffmpeg's first packet arrives, and a quality change respawns the
+    // publisher under the same path, which drops the browser's reader and needs a fresh
+    // handshake. One message covers both, because the path never changes.
+    if (publishUrl) this.announceWebrtc();
+  }
+
+  /**
+   * Bring up this session's relay, or answer null to stay on the WebSocket path.
+   *
+   * Not installed is not an error: the relay is an optional download, and a host without it
+   * must keep working exactly as before rather than failing to connect. A relay that fails to
+   * *start* is logged and also falls back, for the same reason — a viewer that shows the
+   * desktop over WebSocket beats one that shows an error.
+   */
+  private async ensureRelay(): Promise<string | null> {
+    if (!this.preferWebrtc) return null;
+    if (this.relay && !this.relay.isStopped()) return this.relay.publishUrl;
+    if (!findMediamtxBinary()) return null;
+    try {
+      this.relay = await startRelay();
+      this.whepTicket = registerWhepTarget(this.relay.whepUrl);
+      return this.relay.publishUrl;
+    } catch (e) {
+      console.warn(`[remote-desktop] WebRTC relay unavailable, using the WebSocket path: ${(e as Error).message}`);
+      this.relay = null;
+      return null;
+    }
+  }
+
+  /**
+   * Tell the client where to run the WHEP handshake. Only ever a PPM path — never the relay's
+   * own loopback URL, which the browser could not reach and must not learn.
+   *
+   * This carries `preset` and `encoder` too, because it replaces the `config` message on this
+   * transport: `config` is sent from `handleAccessUnit`, which never runs when the stream
+   * leaves over RTSP — so without them the quality and codec menus would show their defaults
+   * rather than what this host is actually running. The codec *string* is deliberately absent:
+   * WebRTC learns it from the SDP answer, and PPM has no SPS to derive one from here.
+   */
+  private announceWebrtc(): void {
+    if (!this.whepTicket || this.closed) return;
+    try {
+      this.ws.send(JSON.stringify({
+        type: "webrtc",
+        whepPath: `/api/remote-desktop/whep/${this.whepTicket}`,
+        preset: this.presetId,
+        held: this.ratioScale,
+        encoder: this.encoder,
+      }));
+    } catch { /* socket closing; the session is going away anyway */ }
   }
 
   /** Apply a change that ffmpeg can only take at startup: stop the old process, wait for it to
@@ -566,6 +633,10 @@ export class RemoteDesktopSession {
     this.closed = true;
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
     this.capture?.stop();
+    // Relay after capture: the publisher should go first so MediaMTX sees a clean disconnect.
+    this.relay?.stop();
+    this.relay = null;
+    if (this.whepTicket) { releaseWhepTicket(this.whepTicket); this.whepTicket = null; }
     this.audio?.stop();
     this.audio = null;
     // Before anything that could throw: a held grab is the only piece of state here that
@@ -667,13 +738,16 @@ export interface CreateRemoteDesktopSessionOptions {
    *  first host's GPU encoder — and an encoder ffmpeg cannot open makes it exit at once, i.e. a
    *  viewer that never shows a frame and blames "Capture failed". */
   encoder?: string;
+  /** Ask for the WebRTC transport. Honoured only when the relay is installed and starts; the
+   *  session otherwise streams over this WebSocket exactly as before, with no error. */
+  webrtc?: boolean;
 }
 
 /** Evict any previous session (awaiting its ffmpeg exit, capped so a wedged process can't
  *  hang a reconnect) before starting the new one. */
 export async function createRemoteDesktopSession(
   ws: RemoteDesktopSocket,
-  { displayId, showCursor = true, encoder }: CreateRemoteDesktopSessionOptions = {},
+  { displayId, showCursor = true, encoder, webrtc = false }: CreateRemoteDesktopSessionOptions = {},
 ): Promise<RemoteDesktopSession> {
   for (const existing of [...activeSessions]) {
     existing.close();
@@ -681,7 +755,7 @@ export async function createRemoteDesktopSession(
   }
   const usable = encoder && (await workingEncoders()).includes(encoder) ? encoder : null;
   const session = new RemoteDesktopSession(
-    ws, await resolveDisplay(displayId), showCursor, usable,
+    ws, await resolveDisplay(displayId), showCursor, usable, webrtc,
   );
   await session.start();
   activeSessions.add(session);

package/src/services/remote-desktop/remote-desktop-whep-registry.ts

@@ -0,0 +1,36 @@
+/**
+ * Ticket → loopback WHEP endpoint, so the browser can negotiate WebRTC without the relay ever
+ * being reachable from outside this host.
+ *
+ * The rule this exists to enforce: **the client never names an upstream.** It presents a
+ * ticket PPM minted and handed it over the already-authenticated WebSocket, and the proxy
+ * looks the URL up here. A route that forwarded a client-supplied URL instead would be an
+ * open SSRF hole in a feature that already requires host control to reach.
+ *
+ * A ticket lives exactly as long as its session: registered when the relay comes up, dropped
+ * when the session closes, so a captured ticket stops working the moment the viewer does.
+ */
+import { randomBytes } from "node:crypto";
+
+const tickets = new Map<string, string>();
+
+/** Register a session's relay and return the ticket the client should present. */
+export function registerWhepTarget(loopbackWhepUrl: string): string {
+  const ticket = randomBytes(24).toString("base64url");
+  tickets.set(ticket, loopbackWhepUrl);
+  return ticket;
+}
+
+/** The endpoint a ticket stands for, or null when it is unknown or already released. */
+export function resolveWhepTarget(ticket: string): string | null {
+  return tickets.get(ticket) ?? null;
+}
+
+export function releaseWhepTicket(ticket: string): void {
+  tickets.delete(ticket);
+}
+
+/** Test seam. */
+export function clearWhepTickets(): void {
+  tickets.clear();
+}

package/src/services/scheduler-runner.ts

@@ -1,6 +1,5 @@
 /** Single-run execution for scheduled agents: session reuse, stream drain, bounded output. */
 import { chatService } from "./chat.service.ts";
-import { providerRegistry } from "../providers/registry.ts";
 import { setScheduleSessionId } from "./scheduler-db.service.ts";
 import type { Schedule, RunResult } from "../types/scheduler.ts";
 
@@ -62,16 +61,16 @@ export async function runScheduleOnce(schedule: Schedule, sessionId: string): Pr
   let resultSubtype: string | undefined;
   let timedOut = false;
 
-  const provider = providerRegistry.get(schedule.provider_id);
   const killer = setTimeout(() => {
     timedOut = true;
-    try { provider?.abortQuery?.(sessionId, "scheduler-timeout"); } catch { /* best-effort */ }
+    try { chatService.abortQuery(schedule.provider_id, sessionId, "scheduler-timeout", "scheduler"); } catch { /* best-effort */ }
   }, schedule.timeout_ms);
 
   try {
     const stream = chatService.sendMessage(schedule.provider_id, sessionId, schedule.prompt, {
       permissionMode: schedule.permission_mode,
       ...(schedule.max_turns != null && { maxTurns: schedule.max_turns }),
+      origin: "scheduler",
     });
     for await (const event of stream) {
       if (event.type === "text") {

package/src/services/session-trace/browser-trace-ingest.ts

@@ -0,0 +1,131 @@
+import {
+  BROWSER_TRACE_TYPES,
+  TRACE_DEVICE_ID_RE,
+  TRACE_INGEST_MAX_BATCH,
+  TRACE_INGEST_MAX_PAYLOAD_BYTES,
+  type BrowserTraceBatch,
+  type BrowserTraceEntry,
+} from "../../shared/session-trace.ts";
+import { redactSecrets } from "../redact-secrets.ts";
+import type { TraceRow } from "./session-trace-store.ts";
+
+/**
+ * The server half of browser logging: what `POST /api/trace` accepts, from whom, and how often.
+ *
+ * The body is hostile by default — it arrives from any tab holding the token, including one
+ * stuck in a render loop — so it is shape-checked here, entries that do not fit are dropped,
+ * and a whole batch that does not fit is refused.
+ */
+
+/** A body past this is refused before it is parsed: 50 entries at the 16 KB cap plus framing. */
+export const TRACE_INGEST_MAX_BODY_BYTES = TRACE_INGEST_MAX_BATCH * TRACE_INGEST_MAX_PAYLOAD_BYTES + 64 * 1024;
+
+const ALLOWED_TYPES: ReadonlySet<string> = new Set(BROWSER_TRACE_TYPES);
+const REF_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+/** How far back a corrected timestamp may land; older is a broken clock, not a buffered error. */
+const MAX_BACKDATE_MS = 30 * 24 * 60 * 60 * 1000;
+
+export type ParsedBatch =
+  | { ok: true; batch: BrowserTraceBatch; dropped: number }
+  | { ok: false; error: string };
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Validate a batch. Refuses the whole thing only when its envelope is wrong or it is too big. */
+export function parseBrowserBatch(raw: unknown): ParsedBatch {
+  if (!isPlainObject(raw)) return { ok: false, error: "body must be an object" };
+  const { deviceId, sentAt, entries } = raw;
+  if (typeof deviceId !== "string" || !TRACE_DEVICE_ID_RE.test(deviceId)) return { ok: false, error: "invalid deviceId" };
+  if (typeof sentAt !== "number" || !Number.isFinite(sentAt)) return { ok: false, error: "invalid sentAt" };
+  if (!Array.isArray(entries)) return { ok: false, error: "entries must be an array" };
+  if (entries.length > TRACE_INGEST_MAX_BATCH) return { ok: false, error: `at most ${TRACE_INGEST_MAX_BATCH} entries per batch` };
+
+  const kept: BrowserTraceEntry[] = [];
+  for (const entry of entries) {
+    if (!isPlainObject(entry)) continue;
+    const { ts, type, refId, payload } = entry;
+    if (typeof type !== "string" || !ALLOWED_TYPES.has(type)) continue;
+    if (typeof ts !== "number" || !Number.isFinite(ts)) continue;
+    if (refId !== null && refId !== undefined && (typeof refId !== "string" || !REF_ID_RE.test(refId))) continue;
+    if (!isPlainObject(payload)) continue;
+    let size: number;
+    try { size = Buffer.byteLength(JSON.stringify(payload)); } catch { continue; }
+    if (size > TRACE_INGEST_MAX_PAYLOAD_BYTES) continue;
+    kept.push({ ts, type: type as BrowserTraceEntry["type"], refId: (refId as string | null | undefined) ?? null, payload });
+  }
+  return { ok: true, batch: { deviceId, sentAt, entries: kept }, dropped: entries.length - kept.length };
+}
+
+/**
+ * Redact every string inside a value, one string at a time. Redacting the serialised JSON
+ * instead would let a rule like `password: <rest>` eat a closing quote and corrupt the row.
+ */
+function redactDeep(value: unknown, depth = 0): unknown {
+  if (typeof value === "string") return redactSecrets(value);
+  if (depth > 8 || value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((v) => redactDeep(v, depth + 1));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) out[k] = redactDeep(v, depth + 1);
+  return out;
+}
+
+/**
+ * Rows for a validated batch. Timestamps are moved onto the server's clock by the offset the
+ * batch itself reveals (`sentAt` against now), which keeps the delay of an error buffered
+ * offline while removing a skewed clock — so browser rows sort correctly against agent rows.
+ */
+export function browserRows(batch: BrowserTraceBatch, now = Date.now()): TraceRow[] {
+  const offset = now - batch.sentAt;
+  return batch.entries.map((entry) => ({
+    traceId: `browser:${batch.deviceId}`,
+    turnId: null,
+    ts: Math.round(Math.min(now, Math.max(now - MAX_BACKDATE_MS, entry.ts + offset))),
+    source: "browser",
+    origin: "browser",
+    providerId: null,
+    refId: entry.refId,
+    type: entry.type,
+    payloadJson: JSON.stringify({ type: entry.type, ...(redactDeep(entry.payload) as Record<string, unknown>) }),
+  }));
+}
+
+export interface RateLimits {
+  windowMs: number;
+  maxRequests: number;
+  maxEntries: number;
+}
+
+const DEFAULT_LIMITS: RateLimits = { windowMs: 60_000, maxRequests: 60, maxEntries: 1_000 };
+
+/**
+ * A fixed-window limit per device id. Never per IP: behind a Cloudflare tunnel every client is
+ * one IP, so a per-IP limit would let one machine in a render loop lock out all the others.
+ */
+export class DeviceRateLimiter {
+  private windows = new Map<string, { start: number; requests: number; entries: number }>();
+
+  constructor(private readonly limits: RateLimits = DEFAULT_LIMITS, private readonly now: () => number = Date.now) {}
+
+  /** Count a request, or say how long until this device may send again. */
+  take(deviceId: string, entries: number): { allowed: true } | { allowed: false; retryAfterMs: number } {
+    const now = this.now();
+    let w = this.windows.get(deviceId);
+    if (!w || now - w.start >= this.limits.windowMs) {
+      w = { start: now, requests: 0, entries: 0 };
+      this.windows.set(deviceId, w);
+      if (this.windows.size > 1_000) this.prune(now);
+    }
+    if (w.requests + 1 > this.limits.maxRequests || w.entries + entries > this.limits.maxEntries) {
+      return { allowed: false, retryAfterMs: Math.max(1, w.start + this.limits.windowMs - now) };
+    }
+    w.requests += 1;
+    w.entries += entries;
+    return { allowed: true };
+  }
+
+  private prune(now: number): void {
+    for (const [id, w] of this.windows) if (now - w.start >= this.limits.windowMs) this.windows.delete(id);
+  }
+}

package/src/services/session-trace/session-trace-cleanup.ts

@@ -0,0 +1,65 @@
+import { getTraceDb, getTraceDbSizeBytes } from "./session-trace-db.ts";
+
+/** Ceiling on rows removed per pass, so the write lock is never held for long. */
+const MAX_BATCH = 2_000;
+/** Stops a pathological loop if vacuuming somehow never reduces the file. */
+const MAX_PASSES = 40;
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * How many rows to drop to get back under the cap, sized from the actual excess so the log
+ * stays as full as the cap allows (same reasoning as `query-audit-cleanup.ts`).
+ */
+function rowsToDrop(currentBytes: number, maxBytes: number, rowCount: number): number {
+  if (rowCount <= 0) return 0;
+  const avgRowBytes = Math.max(1, currentBytes / rowCount);
+  const needed = Math.ceil((currentBytes - maxBytes) / avgRowBytes) + 1;
+  return Math.max(1, Math.min(needed, MAX_BATCH, rowCount));
+}
+
+export interface TraceCleanupResult {
+  deletedByAge: number;
+  deletedBySize: number;
+  freedBytes: number;
+}
+
+/**
+ * Prune the trace by age, then by size, oldest first — mirrors `cleanupQueryAudit`.
+ *
+ * Deleting alone never shrinks a SQLite file; `incremental_vacuum` returns the pages, and only
+ * because the database was created with `auto_vacuum = INCREMENTAL`. Size comes from page
+ * counts so an active WAL does not distort it.
+ */
+export function cleanupSessionTrace(retentionDays: number, maxSizeMb: number, now = Date.now()): TraceCleanupResult {
+  const db = getTraceDb();
+  const sizeBefore = getTraceDbSizeBytes();
+  const cutoff = now - Math.max(1, Math.floor(retentionDays)) * DAY_MS;
+
+  const deletedByAge = db.run("DELETE FROM session_events WHERE ts < ?", [cutoff]).changes;
+  db.exec("PRAGMA incremental_vacuum");
+
+  const maxBytes = Math.max(1, maxSizeMb) * 1024 * 1024;
+  let deletedBySize = 0;
+  for (let pass = 0; pass < MAX_PASSES; pass++) {
+    const currentBytes = getTraceDbSizeBytes();
+    if (currentBytes <= maxBytes) break;
+    const rowCount = (db.query("SELECT COUNT(*) AS count FROM session_events").get() as { count: number }).count;
+    const batch = rowsToDrop(currentBytes, maxBytes, rowCount);
+    // Nothing left to drop — what remains is schema overhead, not rows.
+    if (batch === 0) break;
+    const removed = db.run(
+      `DELETE FROM session_events WHERE rowid IN (
+         SELECT rowid FROM session_events ORDER BY ts ASC LIMIT ${batch}
+       )`,
+    ).changes;
+    if (removed === 0) break;
+    deletedBySize += removed;
+    db.exec("PRAGMA incremental_vacuum");
+  }
+
+  // An alias outlives nothing it points at: a conversation still being written keeps its alias
+  // however old, one whose rows are all gone loses it.
+  db.run("DELETE FROM trace_aliases WHERE NOT EXISTS (SELECT 1 FROM session_events e WHERE e.trace_id = trace_aliases.trace_id)");
+
+  return { deletedByAge, deletedBySize, freedBytes: Math.max(0, sizeBefore - getTraceDbSizeBytes()) };
+}

package/src/services/session-trace/session-trace-db.ts

@@ -0,0 +1,89 @@
+import { Database } from "bun:sqlite";
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { getPpmDir } from "../ppm-dir.ts";
+
+const SCHEMA_VERSION = 1;
+
+let cached: Database | undefined;
+
+export function getTraceDbPath(): string {
+  return join(getPpmDir(), "session-trace.db");
+}
+
+/**
+ * Open (or reuse) the trace database.
+ *
+ * A file of its own for the reason `query-audit.db` is one: event volume must not bloat config
+ * and workspace state in `ppm.db`. Deliberately outside `db-backup` — this is a log, not state.
+ */
+export function getTraceDb(): Database {
+  if (cached) return cached;
+
+  const dir = getPpmDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+
+  const db = new Database(getTraceDbPath());
+  // Server and CLI append from separate processes; without a wait a concurrent write
+  // surfaces as SQLITE_BUSY and the batch is dropped. First, because the pragmas below take
+  // locks too: set after them, a lock another process held for 300 ms failed this open.
+  db.exec("PRAGMA busy_timeout = 2000");
+  // Only takes effect when set before the first table exists. Without it DELETE never
+  // returns disk space, which would make the size cap in the cleanup job meaningless.
+  db.exec("PRAGMA auto_vacuum = INCREMENTAL");
+  db.exec("PRAGMA journal_mode = WAL");
+  // A log: losing the last few milliseconds on power loss is the right trade for not
+  // paying an fsync per commit. Per connection, so it is set on every open.
+  db.exec("PRAGMA synchronous = NORMAL");
+  migrate(db);
+
+  cached = db;
+  return db;
+}
+
+function migrate(db: Database): void {
+  const { user_version } = db.query("PRAGMA user_version").get() as { user_version: number };
+
+  if (user_version < 1) {
+    // `trace_id` is the id a run started under and never the one a provider swaps in
+    // mid-stream (`session_migrated`); `trace_aliases` maps those later ids back, so one
+    // conversation stays one trace. `seq` is ours, assigned at insert — timestamps order
+    // nothing across two processes.
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS session_events (
+        trace_id TEXT NOT NULL,
+        seq INTEGER NOT NULL,
+        turn_id TEXT,
+        ts INTEGER NOT NULL,
+        source TEXT NOT NULL,
+        origin TEXT NOT NULL,
+        provider_id TEXT,
+        ref_id TEXT,
+        type TEXT NOT NULL,
+        payload_json TEXT NOT NULL,
+        PRIMARY KEY (trace_id, seq)
+      );
+      CREATE INDEX IF NOT EXISTS idx_session_events_ref ON session_events(ref_id, ts) WHERE ref_id IS NOT NULL;
+      CREATE INDEX IF NOT EXISTS idx_session_events_ts ON session_events(ts);
+      CREATE TABLE IF NOT EXISTS trace_aliases (
+        alias_id TEXT PRIMARY KEY,
+        trace_id TEXT NOT NULL,
+        ts INTEGER NOT NULL
+      );
+      PRAGMA user_version = ${SCHEMA_VERSION};
+    `);
+  }
+}
+
+/** Current size on disk, derived from pages so it stays accurate while WAL is active. */
+export function getTraceDbSizeBytes(): number {
+  const db = getTraceDb();
+  const { page_count } = db.query("PRAGMA page_count").get() as { page_count: number };
+  const { page_size } = db.query("PRAGMA page_size").get() as { page_size: number };
+  return page_count * page_size;
+}
+
+export function closeTraceDb(): void {
+  cached?.close();
+  cached = undefined;
+}

package/src/services/session-trace/session-trace-store.ts

@@ -0,0 +1,132 @@
+import { getTraceDb } from "./session-trace-db.ts";
+import type { TraceOrigin, TraceSource } from "../../shared/session-trace.ts";
+
+/** One row as the writer hands it over. `seq` is not here: it is assigned at insert. */
+export interface TraceRow {
+  traceId: string;
+  turnId: string | null;
+  ts: number;
+  source: TraceSource;
+  origin: TraceOrigin;
+  providerId: string | null;
+  refId: string | null;
+  type: string;
+  payloadJson: string;
+}
+
+/** One row as read back. */
+export interface TraceEvent {
+  traceId: string;
+  seq: number;
+  turnId: string | null;
+  ts: number;
+  source: TraceSource;
+  origin: TraceOrigin;
+  providerId: string | null;
+  refId: string | null;
+  type: string;
+  payload: unknown;
+}
+
+interface DbRow {
+  trace_id: string;
+  seq: number;
+  turn_id: string | null;
+  ts: number;
+  source: TraceSource;
+  origin: TraceOrigin;
+  provider_id: string | null;
+  ref_id: string | null;
+  type: string;
+  payload_json: string;
+}
+
+// One statement, so the MAX and the insert cannot be split by another writer; the batch
+// runs under BEGIN IMMEDIATE, so the server and a CLI appending to one trace take turns.
+const INSERT_SQL = `
+  INSERT INTO session_events (trace_id, seq, turn_id, ts, source, origin, provider_id, ref_id, type, payload_json)
+  SELECT ?1, COALESCE(MAX(seq), 0) + 1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9
+  FROM session_events WHERE trace_id = ?1`;
+
+/** Append rows in one transaction. Throws on failure — the writer decides to drop. */
+export function appendBatch(rows: readonly TraceRow[]): void {
+  if (rows.length === 0) return;
+  const db = getTraceDb();
+  const insert = db.query(INSERT_SQL);
+  db.transaction((batch: readonly TraceRow[]) => {
+    for (const r of batch) {
+      insert.run(r.traceId, r.turnId, r.ts, r.source, r.origin, r.providerId, r.refId, r.type, r.payloadJson);
+    }
+  }).immediate(rows);
+}
+
+function toEvent(row: DbRow): TraceEvent {
+  let payload: unknown;
+  try { payload = JSON.parse(row.payload_json); } catch { payload = row.payload_json; }
+  return {
+    traceId: row.trace_id,
+    seq: row.seq,
+    turnId: row.turn_id,
+    ts: row.ts,
+    source: row.source,
+    origin: row.origin,
+    providerId: row.provider_id,
+    refId: row.ref_id,
+    type: row.type,
+    payload,
+  };
+}
+
+/** Every row of one trace, in the order it was written. */
+export function readEvents(traceId: string): TraceEvent[] {
+  const rows = getTraceDb()
+    .query("SELECT * FROM session_events WHERE trace_id = ? ORDER BY seq")
+    .all(traceId) as DbRow[];
+  return rows.map(toEvent);
+}
+
+/**
+ * The trace a session id belongs to: itself, unless a provider renamed the session
+ * mid-run (`session_migrated`), in which case the id the run started under.
+ */
+export function resolveTraceId(sessionId: string): string {
+  const row = getTraceDb()
+    .query("SELECT trace_id FROM trace_aliases WHERE alias_id = ?")
+    .get(sessionId) as { trace_id: string } | null;
+  return row?.trace_id ?? sessionId;
+}
+
+/** Record that `aliasId` now names the conversation traced under `traceId`. */
+export function recordTraceAlias(aliasId: string, traceId: string): void {
+  const root = resolveTraceId(traceId);
+  if (aliasId === root) return;
+  getTraceDb()
+    .query("INSERT OR IGNORE INTO trace_aliases (alias_id, trace_id, ts) VALUES (?, ?, ?)")
+    .run(aliasId, root, Date.now());
+}
+
+/**
+ * A session's whole story: its own trace plus every browser row filed against it, under
+ * any id the session has had. Browser rows carry `ref_id`, so this is the one query that
+ * answers "which turn was running when the tab broke".
+ */
+export function readSessionTimeline(sessionId: string, limit = 5000): TraceEvent[] {
+  const db = getTraceDb();
+  const traceId = resolveTraceId(sessionId);
+  const aliases = (db.query("SELECT alias_id FROM trace_aliases WHERE trace_id = ?").all(traceId) as { alias_id: string }[])
+    .map((r) => r.alias_id);
+  const ids = [traceId, ...aliases];
+  const placeholders = ids.map(() => "?").join(", ");
+  const rows = db
+    .query(`SELECT * FROM (
+      SELECT * FROM session_events
+      WHERE trace_id = ? OR ref_id IN (${placeholders})
+      ORDER BY ts DESC, seq DESC LIMIT ?
+    ) ORDER BY ts, seq`)
+    .all(traceId, ...ids, Math.max(1, Math.floor(limit))) as DbRow[];
+  return rows.map(toEvent);
+}
+
+export function countTraceEvents(): number {
+  return (getTraceDb().query("SELECT COUNT(*) AS count FROM session_events").get() as { count: number }).count;
+}