@jobshimo/browser-link 0.27.0 → 0.28.0

package/dist/activity/queries.js

@@ -0,0 +1,286 @@
+import { statSync } from 'node:fs';
+import { getActivityDb, MAX_ACTIVITY_ROWS, pruneIfDue } from './db.js';
+import { getActivityDbPath } from './paths.js';
+/** Hard ceiling on rows a single read can return, whatever `limit` asks for.
+ * The panel pages; nothing needs ten thousand rows in one response, and an
+ * unbounded read is how a renderer freezes a browser. */
+export const MAX_QUERY_LIMIT = 500;
+const DEFAULT_QUERY_LIMIT = 200;
+/** Longest stored `payload` / `error`. A `browser.evaluate` expression can be
+ * arbitrarily long and an error can carry a page's worth of text; neither is
+ * more legible at 40 KB than at 4 KB, and the trail is meant to stay
+ * greppable. Truncation is marked so a reader never mistakes a cut string for
+ * the whole thing. */
+export const MAX_TEXT_LEN = 4_000;
+const TRUNCATION_MARK = '…[truncated]';
+export function truncate(value, max = MAX_TEXT_LEN) {
+    if (value === null)
+        return null;
+    if (value.length <= max)
+        return value;
+    return value.slice(0, max - TRUNCATION_MARK.length) + TRUNCATION_MARK;
+}
+function toRecord(row) {
+    return {
+        id: row.id,
+        at: row.at,
+        tool: row.tool,
+        tabId: row.tab_id,
+        transport: row.transport ?? null,
+        url: row.url,
+        title: row.title,
+        agent: row.agent,
+        agentPid: row.agent_pid,
+        selector: row.selector,
+        payload: row.payload,
+        outcome: row.outcome === 'error' ? 'error' : 'ok',
+        error: row.error,
+        durationMs: row.duration_ms,
+        flowId: row.flow_id,
+    };
+}
+/**
+ * Append one dispatched call to the trail.
+ *
+ * NEVER THROWS. Recording is observation, not the work: an agent's click must
+ * not fail because the disk is full or the DB is locked. The caller
+ * (`browser-dispatch.ts`) treats this as fire-and-forget, and a lost row is
+ * strictly better than a lost action.
+ */
+export function record(input, db) {
+    try {
+        const handle = db ?? getActivityDb();
+        const at = new Date().toISOString();
+        const result = handle
+            .prepare(`INSERT INTO activity
+           (at, tool, tab_id, transport, url, title, agent, agent_pid,
+            selector, payload, outcome, error, duration_ms, flow_id)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(at, input.tool, input.tabId, input.transport, truncate(input.url), truncate(input.title, 300), input.agent, input.agentPid, truncate(input.selector), truncate(input.payload), input.outcome, truncate(input.error), Math.max(0, Math.round(input.durationMs)), input.flowId);
+        pruneIfDue(handle);
+        return { ...input, id: Number(result.lastInsertRowid), at };
+    }
+    catch {
+        return null;
+    }
+}
+/** Build the shared WHERE clause + bindings for a filter. Kept in one place
+ * so `query` and its COUNT can never drift apart and report a total that does
+ * not match the rows beside it. */
+function buildFilter(q) {
+    const clauses = [];
+    const params = [];
+    if (q.sinceId !== undefined) {
+        clauses.push('id > ?');
+        params.push(q.sinceId);
+    }
+    if (q.beforeId !== undefined) {
+        clauses.push('id < ?');
+        params.push(q.beforeId);
+    }
+    if (q.tabId !== undefined) {
+        clauses.push('tab_id = ?');
+        params.push(q.tabId);
+    }
+    if (q.agent !== undefined) {
+        clauses.push('agent = ?');
+        params.push(q.agent);
+    }
+    if (q.tool !== undefined) {
+        clauses.push('tool = ?');
+        params.push(q.tool);
+    }
+    if (q.flowId !== undefined) {
+        clauses.push('flow_id = ?');
+        params.push(q.flowId);
+    }
+    if (q.outcome !== undefined) {
+        clauses.push('outcome = ?');
+        params.push(q.outcome);
+    }
+    if (q.since !== undefined) {
+        clauses.push('at >= ?');
+        params.push(q.since);
+    }
+    return { where: clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '', params };
+}
+/**
+ * Read a page of the trail, NEWEST FIRST.
+ *
+ * Newest-first is what both readers want and it is the only ordering that
+ * makes `limit` honest: with oldest-first, "the last 200" would require
+ * counting the whole table before choosing an offset. The window reverses the
+ * page for display; the CLI prints it as-is.
+ */
+export function query(q = {}, db) {
+    const handle = db ?? getActivityDb();
+    const limit = Math.min(Math.max(1, q.limit ?? DEFAULT_QUERY_LIMIT), MAX_QUERY_LIMIT);
+    const { where, params } = buildFilter(q);
+    const rows = handle
+        .prepare(`SELECT * FROM activity ${where} ORDER BY id DESC LIMIT ?`)
+        .all(...params, limit);
+    const { total } = handle
+        .prepare(`SELECT COUNT(*) AS total FROM activity ${where}`)
+        .get(...params);
+    const records = rows.map(toRecord);
+    // `latestId` is the highest id in the page — rows come back DESC, so that is
+    // the first one. Falls back to the request's cursor (not 0) when the page is
+    // empty, so a tailing caller that polls an idle bridge does not rewind and
+    // re-read everything on the next tick.
+    const latestId = records.length > 0 ? records[0].id : (q.sinceId ?? 0);
+    return { records, latestId, total };
+}
+/** Every distinct agent that appears in the trail, most recently seen first.
+ * Feeds the window's filter chips — a hardcoded list would go stale the
+ * moment someone wires up a new MCP client. */
+export function listAgents(db) {
+    const handle = db ?? getActivityDb();
+    return handle
+        .prepare(`SELECT agent, COUNT(*) AS count FROM activity
+       WHERE agent IS NOT NULL
+       GROUP BY agent ORDER BY MAX(id) DESC`)
+        .all();
+}
+/** Delete the trail, or the part of it older than `before`. Returns rows
+ * removed. VACUUM is the caller's call (the CLI offers it) — it rewrites the
+ * whole file and has no business running inside a tool dispatch. */
+export function clear(before, db) {
+    const handle = db ?? getActivityDb();
+    if (before === undefined) {
+        return handle.prepare('DELETE FROM activity').run().changes;
+    }
+    return handle.prepare('DELETE FROM activity WHERE at < ?').run(before).changes;
+}
+function rangeFilter(range) {
+    const clauses = [];
+    const params = [];
+    if (range.from !== undefined) {
+        clauses.push('at >= ?');
+        params.push(range.from);
+    }
+    if (range.to !== undefined) {
+        clauses.push('at <= ?');
+        params.push(range.to);
+    }
+    return { where: clauses.length > 0 ? `WHERE ${clauses.join(' AND ')}` : '', params };
+}
+/**
+ * How many rows a purge of this range WOULD remove.
+ *
+ * Exists so the UI can tell the user the number before they confirm, not
+ * after. "Delete 4,812 of 12,483 actions" is a decision; "Delete?" is a
+ * gamble, and this delete is permanent.
+ */
+export function countInRange(range, db) {
+    const handle = db ?? getActivityDb();
+    const { where, params } = rangeFilter(range);
+    const row = handle.prepare(`SELECT COUNT(*) AS n FROM activity ${where}`).get(...params);
+    return row.n;
+}
+/**
+ * Delete every row inside an inclusive date range. Returns rows removed.
+ *
+ * `vacuum` defaults ON here, unlike `clear`. The whole point of purging from
+ * the UI is that the file got big, and a DELETE alone leaves the pages
+ * allocated — the user would purge half the trail, watch the reported size not
+ * move, and reasonably conclude it did nothing. VACUUM rewrites the file so
+ * the number they are watching actually drops.
+ */
+export function purgeRange(range, options = {}, db) {
+    const handle = db ?? getActivityDb();
+    const { where, params } = rangeFilter(range);
+    const removed = handle.prepare(`DELETE FROM activity ${where}`).run(...params).changes;
+    if (removed > 0 && options.vacuum !== false) {
+        try {
+            // VACUUM ALONE IS NOT ENOUGH IN WAL MODE, and getting this wrong is
+            // invisible in the worst way: the rows go, the reported size does not
+            // move, and the user reasonably concludes the purge did nothing.
+            //
+            // In WAL mode the freed pages land in `activity.db-wal` rather than
+            // being handed back to the filesystem, so the file set stays exactly as
+            // large as before. TRUNCATE checkpoints fold the WAL back into the main
+            // DB and then truncate the sidecar to zero — once before, so VACUUM
+            // rewrites a DB that already contains everything, and once after, so the
+            // pages VACUUM itself freed are actually released.
+            handle.pragma('wal_checkpoint(TRUNCATE)');
+            handle.exec('VACUUM');
+            handle.pragma('wal_checkpoint(TRUNCATE)');
+        }
+        catch {
+            // A checkpoint or VACUUM can fail while another connection holds the
+            // file. The rows are already gone, which is what was asked for; the
+            // space comes back on the next successful purge.
+        }
+    }
+    return removed;
+}
+export function stats(db) {
+    const handle = db ?? getActivityDb();
+    const row = handle
+        .prepare('SELECT COUNT(*) AS rows, MIN(at) AS oldest, MAX(at) AS newest FROM activity')
+        .get();
+    return {
+        rows: row.rows,
+        bytes: activityBytesOnDisk(),
+        oldestAt: row.oldest,
+        newestAt: row.newest,
+        maxRows: MAX_ACTIVITY_ROWS,
+    };
+}
+/** Sum the SQLite file set. Missing sidecars are simply 0 — a freshly
+ * checkpointed DB has no -wal, and that is not an error. */
+function activityBytesOnDisk() {
+    const base = getActivityDbPath();
+    let total = 0;
+    for (const suffix of ['', '-wal', '-shm']) {
+        try {
+            total += statSync(`${base}${suffix}`).size;
+        }
+        catch {
+            // Not present — nothing to add.
+        }
+    }
+    return total;
+}
+/**
+ * Stream the whole trail for export, oldest first, in batches.
+ *
+ * A generator rather than an array on purpose: an export of 50k rows must not
+ * materialise 50k objects to hand to a JSON serializer. Oldest-first because
+ * an exported file is read top-to-bottom as a story, which is the opposite of
+ * how a live panel is read.
+ */
+export function* exportAll(filter = {}, db) {
+    const handle = db ?? getActivityDb();
+    const { where, params } = buildFilter(filter);
+    const stmt = handle.prepare(`SELECT * FROM activity ${where} ORDER BY id ASC`);
+    for (const row of stmt.iterate(...params)) {
+        yield toRecord(row);
+    }
+}
+/** Strip the free-text columns from a record on its way out of the machine.
+ * Applied at EXPORT time, never at record time — see the PRIVACY CONTRACT in
+ * `types.ts`. The row keeps its shape so a redacted export is still a valid,
+ * diffable trail; only what was typed or evaluated goes. */
+export function redact(record) {
+    return {
+        ...record,
+        payload: record.payload === null ? null : '[redacted]',
+        title: record.title === null ? null : '[redacted]',
+        url: record.url === null ? null : redactUrl(record.url),
+    };
+}
+/** Keep origin + pathname, drop query string and fragment — that is where
+ * tokens, search terms and session ids live. A trail that says
+ * `https://app.example.com/orders` is still useful; one that says
+ * `?token=abc123` is a leak. */
+function redactUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return `${parsed.origin}${parsed.pathname}`;
+    }
+    catch {
+        return '[redacted]';
+    }
+}
+//# sourceMappingURL=queries.js.map

package/dist/activity/queries.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queries.js","sourceRoot":"","sources":["../../src/activity/queries.ts"],"names":[],"mappings":"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"}

package/dist/activity/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The activity trail: one row per browser tool an agent dispatched.
+ *
+ * WHY THIS LIVES ON THE SERVER, NOT IN THE EXTENSION
+ * --------------------------------------------------
+ * The extension's flow history (`flow-registry.ts`) is a "what just happened
+ * on this tab" panel: `chrome.storage.session`, 20 entries per tab, gone when
+ * the browser closes. That is the right shape for the 320px popup and the
+ * wrong shape for an audit trail.
+ *
+ * The server already sees EVERY action — `handleBrowserTool` is the single
+ * funnel both transports pass through, extension and cdp-direct alike — and
+ * it has a real filesystem. Recording here means one hook instead of one per
+ * transport, no `chrome.storage` quota, and a trail that outlives the
+ * browser AND the server process.
+ *
+ * PRIVACY CONTRACT
+ * ----------------
+ * This is deliberately a DIFFERENT contract from the popup's.
+ *
+ * `flow-registry.ts` keeps counts and fixed enums only, because it renders
+ * into a UI the user did not ask for and cannot clear. This trail is the
+ * opposite: the user asked for it explicitly, it is theirs, it lives in
+ * their own data dir, and it is worthless for auditing an agent if it omits
+ * what the agent actually typed or evaluated.
+ *
+ * So `payload` DOES carry page-derived and agent-supplied text — the string
+ * that was typed, the expression that was evaluated, the URL navigated to.
+ * Three properties keep that honest:
+ *
+ *   1. It never leaves the machine on its own. Nothing uploads it.
+ *   2. Recording it is a config switch (`activity.record-payloads`), so a
+ *      user who wants the shape of the trail without its contents can have
+ *      exactly that.
+ *   3. Redaction happens on the way OUT (`activity export --redact`), not on
+ *      the way in. The owner keeps the full trail; what they hand to someone
+ *      else is a decision made at export time, once, deliberately — rather
+ *      than a decision made silently at record time and impossible to undo.
+ */
+/** Outcome of a dispatched tool. `error` is the failure branch of the same
+ * call, not a separate kind of event: an agent's failed click is exactly as
+ * interesting as a successful one when you are reconstructing what happened. */
+export type ActivityOutcome = 'ok' | 'error';
+/** Which wire the call travelled over. `null` for tools that never touch a
+ * tab (`browser.list_tabs`, `browser.my_tabs`), so the column can be read as
+ * "how this reached the page" rather than being forced to lie. */
+export type ActivityTransport = 'extension' | 'cdp';
+/** One dispatched tool call, as stored. Field order mirrors the table. */
+export interface ActivityRecord {
+    /** Monotonic rowid. Also the pagination cursor — see `queries.ts`. */
+    id: number;
+    /** ISO-8601, UTC. */
+    at: string;
+    /** Full MCP tool name, e.g. `browser.click`. Never abbreviated: the trail
+     * is read by humans and by other agents, and `click` alone is ambiguous
+     * once flows and map tools are in the same list. */
+    tool: string;
+    /** browser-link tab id (`tab_1`, `cdp:TARGET-1`), or null for tabless tools. */
+    tabId: string | null;
+    transport: ActivityTransport | null;
+    /** Tab URL at dispatch time. The single most useful column when reading
+     * the trail back weeks later — a selector without a page is noise. */
+    url: string | null;
+    title: string | null;
+    /** Self-declared agent label from the claim layer ("claude-code",
+     * "opencode"), falling back to the caller's binary. What makes an exported
+     * trail useful across agents: it answers "which of them did this". */
+    agent: string | null;
+    /** The agent's process id. Disambiguates two runs of the same binary. */
+    agentPid: number | null;
+    /** CSS selector the call targeted, when the tool takes one. */
+    selector: string | null;
+    /** Agent-supplied or page-derived text: typed string, evaluate expression,
+     * navigate URL. Null when the tool has none, or when payload recording is
+     * off. See the PRIVACY CONTRACT above. */
+    payload: string | null;
+    outcome: ActivityOutcome;
+    /** Error message when `outcome` is `error`. Truncated, never a stack. */
+    error: string | null;
+    /** Wall-clock duration of the dispatch, milliseconds. */
+    durationMs: number;
+    /** Set when this call was a step inside a `browser.flow`, so the window can
+     * group a 40-step flow under one heading instead of flooding the timeline. */
+    flowId: string | null;
+}
+/** What the recorder is handed. `id` and `at` are assigned on write — a
+ * caller that could choose its own id could also rewrite history. */
+export type ActivityInput = Omit<ActivityRecord, 'id' | 'at'>;
+/** Filters for reading the trail back. Every field is optional and ANDed;
+ * the default is "the most recent page of everything". */
+export interface ActivityQuery {
+    /** Return rows with `id` strictly greater than this. The cursor for the
+     * live-tailing panel: it keeps the last id it rendered and asks for more,
+     * exactly like `browser.events`' `since_id`. */
+    sinceId?: number;
+    /** Return rows with `id` strictly less than this — paging BACKWARDS through
+     * history, which is what the window's "load older" does. */
+    beforeId?: number;
+    tabId?: string;
+    agent?: string;
+    tool?: string;
+    flowId?: string;
+    outcome?: ActivityOutcome;
+    /** Rows at or after this ISO timestamp. */
+    since?: string;
+    /** Hard cap on rows returned. Clamped by the query layer — an unbounded
+     * read of a table with no ceiling is how a panel freezes a browser. */
+    limit?: number;
+}
+/** A page of the trail plus the cursor needed to ask for the next one. */
+export interface ActivityPage {
+    records: ActivityRecord[];
+    /** Highest id in this page, or the request's `sinceId` when empty. Feed it
+     * back as `sinceId` to tail without re-reading what you already have. */
+    latestId: number;
+    /** Total rows matching the filter, ignoring `limit`. Lets the window say
+     * "showing 200 of 4813" instead of silently truncating. */
+    total: number;
+}

package/dist/activity/types.js

@@ -0,0 +1,41 @@
+/**
+ * The activity trail: one row per browser tool an agent dispatched.
+ *
+ * WHY THIS LIVES ON THE SERVER, NOT IN THE EXTENSION
+ * --------------------------------------------------
+ * The extension's flow history (`flow-registry.ts`) is a "what just happened
+ * on this tab" panel: `chrome.storage.session`, 20 entries per tab, gone when
+ * the browser closes. That is the right shape for the 320px popup and the
+ * wrong shape for an audit trail.
+ *
+ * The server already sees EVERY action — `handleBrowserTool` is the single
+ * funnel both transports pass through, extension and cdp-direct alike — and
+ * it has a real filesystem. Recording here means one hook instead of one per
+ * transport, no `chrome.storage` quota, and a trail that outlives the
+ * browser AND the server process.
+ *
+ * PRIVACY CONTRACT
+ * ----------------
+ * This is deliberately a DIFFERENT contract from the popup's.
+ *
+ * `flow-registry.ts` keeps counts and fixed enums only, because it renders
+ * into a UI the user did not ask for and cannot clear. This trail is the
+ * opposite: the user asked for it explicitly, it is theirs, it lives in
+ * their own data dir, and it is worthless for auditing an agent if it omits
+ * what the agent actually typed or evaluated.
+ *
+ * So `payload` DOES carry page-derived and agent-supplied text — the string
+ * that was typed, the expression that was evaluated, the URL navigated to.
+ * Three properties keep that honest:
+ *
+ *   1. It never leaves the machine on its own. Nothing uploads it.
+ *   2. Recording it is a config switch (`activity.record-payloads`), so a
+ *      user who wants the shape of the trail without its contents can have
+ *      exactly that.
+ *   3. Redaction happens on the way OUT (`activity export --redact`), not on
+ *      the way in. The owner keeps the full trail; what they hand to someone
+ *      else is a decision made at export time, once, deliberately — rather
+ *      than a decision made silently at record time and impossible to undo.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/activity/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/activity/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG"}

package/dist/bridge/ws-bridge.d.ts

@@ -1,5 +1,5 @@
 import { WebSocket, WebSocketServer } from 'ws';
-import type { FlowRecordedPayload, ServerToExtension, SettingsUpdateMessage } from '../messages.js';
+import type { ActivityPurgeMessage, ActivityQueryMessage, FlowRecordedPayload, ServerToExtension, SettingsUpdateMessage } from '../messages.js';
 import { type BridgeEventLog } from './events.js';
 export declare const WS_HOST = "127.0.0.1";
 export declare const WS_PORT = 17529;
@@ -103,6 +103,23 @@ export declare function handleFlowRecordedMessage(payload: FlowRecordedPayload,
  * connected — the caller surfaces the standard not-connected error from
  * the status call that follows, rather than two competing diagnoses.
  */
+/**
+ * Answer one `activity.query` frame.
+ *
+ * Exported so it is unit-testable directly, same as
+ * `handleFlowRecordedMessage`. Never throws: a trail read that fails comes
+ * back as `ok: false` with a message the window can render, because a broken
+ * audit panel must not take the bridge connection down with it.
+ */
+export declare function handleActivityQueryMessage(msg: ActivityQueryMessage): ServerToExtension;
+/**
+ * Answer one `activity.purge` frame.
+ *
+ * `dry_run` is not a courtesy — it is how the window can promise the user a
+ * real number before an irreversible delete. Both paths return fresh stats so
+ * the panel's size readout updates from the same round trip that changed it.
+ */
+export declare function handleActivityPurgeMessage(msg: ActivityPurgeMessage): ServerToExtension;
 export declare function sendToolCancel(tabs: Map<string, TabSession>, tabId: string, flowId: string): boolean;
 /** Build the callback that sends a tool.request frame to a specific tab and
  * resolves with the matching tool.response (or rejects on timeout). Kept here

package/dist/bridge/ws-bridge.js

@@ -1,4 +1,5 @@
 import { WebSocket, WebSocketServer } from 'ws';
+import { countInRange as countActivityInRange, listAgents as listActivityAgents, purgeRange as purgeActivityRange, query as queryActivity, stats as activityStats, } from '../activity/queries.js';
 import { isAllowedBrowser } from '../auth/allowlist.js';
 import { lookupPeerProcess } from '../auth/process-identity.js';
 import { VERSION } from '../version.js';
@@ -221,6 +222,27 @@ export function startWsBridge(tabs, pendingRequests, events) {
                     send(ws, result);
                     return;
                 }
+                if (msg.kind === 'activity.purge') {
+                    // The one DESTRUCTIVE frame the extension can send, and irreversible.
+                    // The window resolves a count with `dry_run` first and puts that
+                    // number in front of the user before this ever arrives for real.
+                    send(ws, handleActivityPurgeMessage(msg));
+                    return;
+                }
+                if (msg.kind === 'activity.query') {
+                    // Read-only and deliberately NOT scoped to `assignedTabId`, unlike
+                    // `flow.recorded` above. The Activity window's whole job is showing
+                    // what happened across every tab and every agent, and it reaches the
+                    // bridge through whichever tab's socket happens to be open. A
+                    // per-connection scope here would silently hide most of the trail.
+                    //
+                    // The connection is already authenticated (browser allowlist + peer
+                    // process identity at handshake), and the trail never leaves the
+                    // machine, so "any authenticated extension connection may read the
+                    // local trail" is the intended boundary.
+                    send(ws, handleActivityQueryMessage(msg));
+                    return;
+                }
             });
             ws.on('close', () => {
                 if (assignedTabId) {
@@ -397,6 +419,91 @@ export function handleFlowRecordedMessage(payload, events) {
  * connected — the caller surfaces the standard not-connected error from
  * the status call that follows, rather than two competing diagnoses.
  */
+/**
+ * Answer one `activity.query` frame.
+ *
+ * Exported so it is unit-testable directly, same as
+ * `handleFlowRecordedMessage`. Never throws: a trail read that fails comes
+ * back as `ok: false` with a message the window can render, because a broken
+ * audit panel must not take the bridge connection down with it.
+ */
+export function handleActivityQueryMessage(msg) {
+    try {
+        const q = msg.query ?? {};
+        const page = queryActivity({
+            ...(typeof q.since_id === 'number' ? { sinceId: q.since_id } : {}),
+            ...(typeof q.before_id === 'number' ? { beforeId: q.before_id } : {}),
+            ...(typeof q.tab_id === 'string' ? { tabId: q.tab_id } : {}),
+            ...(typeof q.agent === 'string' ? { agent: q.agent } : {}),
+            ...(typeof q.tool === 'string' ? { tool: q.tool } : {}),
+            ...(typeof q.flow_id === 'string' ? { flowId: q.flow_id } : {}),
+            ...(q.outcome === 'ok' || q.outcome === 'error' ? { outcome: q.outcome } : {}),
+            ...(typeof q.limit === 'number' ? { limit: q.limit } : {}),
+        });
+        return {
+            kind: 'activity.result',
+            request_id: msg.request_id,
+            ok: true,
+            records: page.records,
+            latest_id: page.latestId,
+            total: page.total,
+            agents: listActivityAgents(),
+            stats: toStatsPayload(activityStats()),
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'activity.result',
+            request_id: msg.request_id,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+/** camelCase store shape → snake_case wire shape. One mapper so the two can
+ * never drift into reporting different numbers under the same name. */
+function toStatsPayload(s) {
+    return {
+        rows: s.rows,
+        bytes: s.bytes,
+        oldest_at: s.oldestAt,
+        newest_at: s.newestAt,
+        max_rows: s.maxRows,
+    };
+}
+/**
+ * Answer one `activity.purge` frame.
+ *
+ * `dry_run` is not a courtesy — it is how the window can promise the user a
+ * real number before an irreversible delete. Both paths return fresh stats so
+ * the panel's size readout updates from the same round trip that changed it.
+ */
+export function handleActivityPurgeMessage(msg) {
+    try {
+        const range = {
+            ...(typeof msg.from === 'string' ? { from: msg.from } : {}),
+            ...(typeof msg.to === 'string' ? { to: msg.to } : {}),
+        };
+        const dryRun = msg.dry_run === true;
+        const removed = dryRun ? countActivityInRange(range) : purgeActivityRange(range);
+        return {
+            kind: 'activity.purge.result',
+            request_id: msg.request_id,
+            ok: true,
+            removed,
+            dry_run: dryRun,
+            stats: toStatsPayload(activityStats()),
+        };
+    }
+    catch (error) {
+        return {
+            kind: 'activity.purge.result',
+            request_id: msg.request_id,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 export function sendToolCancel(tabs, tabId, flowId) {
     const session = tabs.get(tabId);
     if (!session || session.ws.readyState !== WebSocket.OPEN)