@jobshimo/browser-link 0.27.1 → 0.28.0

package/dist/activity/db.d.ts

@@ -0,0 +1,27 @@
+import Database from 'better-sqlite3';
+/**
+ * Rows kept before the oldest are pruned.
+ *
+ * Sized so a heavy day of agent work never evicts the morning: a `repeat`
+ * flow can dispatch a few hundred actions in one call, so a 200-row ceiling
+ * like `BridgeEventLog`'s would make the trail useless for exactly the runs
+ * worth auditing. 50k rows is a few tens of MB at this row width — cheap for
+ * a file on disk, and unlike the in-memory event log nothing here competes
+ * with the process's working set.
+ */
+export declare const MAX_ACTIVITY_ROWS = 50000;
+export declare function getActivityDb(): Database.Database;
+/**
+ * AUTOINCREMENT on the primary key is deliberate, and it is the reason the
+ * `sinceId` cursor is safe.
+ *
+ * Without it SQLite reuses the rowids of deleted rows, so pruning the oldest
+ * rows could hand a NEW row an id a tailing panel had already seen and
+ * skipped past — the panel would silently never render it. AUTOINCREMENT
+ * costs one extra table (`sqlite_sequence`) and buys a monotonic cursor that
+ * survives pruning.
+ */
+export declare function pruneIfDue(db: Database.Database, force?: boolean): number;
+/** Close and forget the handle. Tests use this between temp data dirs; the
+ * CLI uses it so a `clear --vacuum` is not fighting its own open WAL. */
+export declare function closeActivityDb(): void;

package/dist/activity/db.js

@@ -0,0 +1,98 @@
+import Database from 'better-sqlite3';
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { getActivityDbPath } from './paths.js';
+let dbInstance = null;
+/**
+ * Rows kept before the oldest are pruned.
+ *
+ * Sized so a heavy day of agent work never evicts the morning: a `repeat`
+ * flow can dispatch a few hundred actions in one call, so a 200-row ceiling
+ * like `BridgeEventLog`'s would make the trail useless for exactly the runs
+ * worth auditing. 50k rows is a few tens of MB at this row width — cheap for
+ * a file on disk, and unlike the in-memory event log nothing here competes
+ * with the process's working set.
+ */
+export const MAX_ACTIVITY_ROWS = 50_000;
+/**
+ * How many inserts between prune sweeps.
+ *
+ * Pruning on every insert would run a DELETE with a subquery on the hot path
+ * of every single agent action. Pruning on a counter means the table can
+ * briefly exceed `MAX_ACTIVITY_ROWS` by at most this much, which costs
+ * nothing and keeps the write path a single INSERT.
+ */
+const PRUNE_INTERVAL = 500;
+let insertsSincePrune = 0;
+export function getActivityDb() {
+    if (dbInstance)
+        return dbInstance;
+    const path = getActivityDbPath();
+    mkdirSync(dirname(path), { recursive: true });
+    const db = new Database(path);
+    db.pragma('journal_mode = WAL');
+    runMigrations(db);
+    dbInstance = db;
+    return db;
+}
+function runMigrations(db) {
+    // Same idempotent CREATE-IF-NOT-EXISTS pattern as map/db.ts: an existing
+    // file from an earlier version picks up new tables on next open without
+    // touching a single stored row.
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS activity (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      at TEXT NOT NULL,
+      tool TEXT NOT NULL,
+      tab_id TEXT,
+      transport TEXT CHECK (transport IN ('extension', 'cdp')),
+      url TEXT,
+      title TEXT,
+      agent TEXT,
+      agent_pid INTEGER,
+      selector TEXT,
+      payload TEXT,
+      outcome TEXT NOT NULL CHECK (outcome IN ('ok', 'error')),
+      error TEXT,
+      duration_ms INTEGER NOT NULL,
+      flow_id TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_activity_at ON activity(at);
+    CREATE INDEX IF NOT EXISTS idx_activity_tab ON activity(tab_id);
+    CREATE INDEX IF NOT EXISTS idx_activity_flow ON activity(flow_id);
+    CREATE INDEX IF NOT EXISTS idx_activity_agent ON activity(agent);
+  `);
+}
+/**
+ * AUTOINCREMENT on the primary key is deliberate, and it is the reason the
+ * `sinceId` cursor is safe.
+ *
+ * Without it SQLite reuses the rowids of deleted rows, so pruning the oldest
+ * rows could hand a NEW row an id a tailing panel had already seen and
+ * skipped past — the panel would silently never render it. AUTOINCREMENT
+ * costs one extra table (`sqlite_sequence`) and buys a monotonic cursor that
+ * survives pruning.
+ */
+export function pruneIfDue(db, force = false) {
+    insertsSincePrune += 1;
+    if (!force && insertsSincePrune < PRUNE_INTERVAL)
+        return 0;
+    insertsSincePrune = 0;
+    const result = db
+        .prepare(`DELETE FROM activity WHERE id <= (
+         SELECT MAX(id) FROM activity
+       ) - ?`)
+        .run(MAX_ACTIVITY_ROWS);
+    return result.changes;
+}
+/** Close and forget the handle. Tests use this between temp data dirs; the
+ * CLI uses it so a `clear --vacuum` is not fighting its own open WAL. */
+export function closeActivityDb() {
+    if (!dbInstance)
+        return;
+    dbInstance.close();
+    dbInstance = null;
+    insertsSincePrune = 0;
+}
+//# sourceMappingURL=db.js.map

package/dist/activity/db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/activity/db.ts"],"names":[],"mappings":"AAAA,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AACtC,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/C,IAAI,UAAU,GAA6B,IAAI,CAAC;AAEhD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,cAAc,GAAG,GAAG,CAAC;AAE3B,IAAI,iBAAiB,GAAG,CAAC,CAAC;AAE1B,MAAM,UAAU,aAAa;IAC3B,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,EAAE,GAAG,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC9B,EAAE,CAAC,MAAM,CAAC,oBAAoB,CAAC,CAAC;IAChC,aAAa,CAAC,EAAE,CAAC,CAAC;IAClB,UAAU,GAAG,EAAE,CAAC;IAChB,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,SAAS,aAAa,CAAC,EAAqB;IAC1C,yEAAyE;IACzE,wEAAwE;IACxE,gCAAgC;IAChC,EAAE,CAAC,IAAI,CAAC;;;;;;;;;;;;;;;;;;;;;;;GAuBP,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,EAAqB,EAAE,KAAK,GAAG,KAAK;IAC7D,iBAAiB,IAAI,CAAC,CAAC;IACvB,IAAI,CAAC,KAAK,IAAI,iBAAiB,GAAG,cAAc;QAAE,OAAO,CAAC,CAAC;IAC3D,iBAAiB,GAAG,CAAC,CAAC;IACtB,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CACN;;aAEO,CACR;SACA,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,OAAO,CAAC;AACxB,CAAC;AAED;yEACyE;AACzE,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC,UAAU;QAAE,OAAO;IACxB,UAAU,CAAC,KAAK,EAAE,CAAC;IACnB,UAAU,GAAG,IAAI,CAAC;IAClB,iBAAiB,GAAG,CAAC,CAAC;AACxB,CAAC"}

package/dist/activity/extract.d.ts

@@ -0,0 +1,32 @@
+import type { ActivityInput, ActivityTransport } from './types.js';
+import type { AgentCaller } from '../tools/tab-claims.js';
+export declare function extractSelector(tool: string, args: unknown): string | null;
+export declare function extractPayload(tool: string, args: unknown): string | null;
+/** The browser-link tab id the call targeted, when it takes one. */
+export declare function extractTabId(args: unknown): string | null;
+/** Flow id, for the two tools that address an existing flow by id. Steps
+ * dispatched INSIDE a flow are stamped by the flow runner, not here. */
+export declare function extractFlowId(args: unknown): string | null;
+/** `cdp:`-prefixed ids are the cdp-direct transport; everything else reached
+ * the page through the extension. Mirrors `isCdpTabId` without importing it,
+ * so the trail keeps working if that predicate ever gains transport-selection
+ * side effects. */
+export declare function transportFor(tabId: string | null): ActivityTransport | null;
+/** Self-declared label first, binary as the fallback. `agent_id` alone is a
+ * uuid nobody can read; the point of this column is that a human scanning an
+ * exported trail can tell Claude Code from OpenCode at a glance. */
+export declare function agentNameFor(caller: AgentCaller | undefined): string | null;
+export interface BuildRowInput {
+    tool: string;
+    args: unknown;
+    caller?: AgentCaller;
+    durationMs: number;
+    error?: unknown;
+    /** False when `activity.record-payloads` is off: the row is still written,
+     * with its shape intact, minus the free text. */
+    recordPayloads: boolean;
+}
+/** Assemble the row. Deliberately total — every branch returns something
+ * storable, because a tool call that produced a row we could not describe is
+ * still a tool call that happened. */
+export declare function buildRow({ tool, args, caller, durationMs, error, recordPayloads, }: BuildRowInput): ActivityInput;

package/dist/activity/extract.js

@@ -0,0 +1,126 @@
+/**
+ * Turn one tool dispatch into a trail row.
+ *
+ * This module exists so the dispatcher wrapper stays four lines. Knowing that
+ * `type`'s interesting text is `args.text` while `evaluate`'s is
+ * `args.expression` is knowledge about the TOOL SURFACE, and it belongs next
+ * to the trail that consumes it — not smeared through a 30-arm switch whose
+ * job is routing.
+ */
+/** Which argument carries the CSS selector, per tool. Tools absent from the
+ * map simply record no selector. */
+const SELECTOR_ARG = {
+    'browser.click': 'selector',
+    'browser.type': 'selector',
+    'browser.press': 'selector',
+    'browser.wait_for': 'selector',
+    'browser.snapshot': 'within_selector',
+    'browser.canvas_screenshot': 'selector',
+};
+/**
+ * Which argument carries the free text worth keeping, per tool.
+ *
+ * Only tools whose payload actually reconstructs the action appear here. A
+ * `browser.snapshot`'s `max_interactive` is a knob, not a payload; recording
+ * knobs would bury the three fields that matter (what was typed, what was
+ * evaluated, where it navigated) under noise.
+ */
+const PAYLOAD_ARG = {
+    'browser.navigate': 'url',
+    'browser.type': 'text',
+    'browser.find': 'text',
+    'browser.evaluate': 'expression',
+    'browser.press': 'key',
+};
+function readString(args, key) {
+    if (typeof args !== 'object' || args === null)
+        return null;
+    const value = args[key];
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+/** `browser.flow` has no single payload argument — its substance is the step
+ * list. Summarising it as `"5 steps: find → click → type"` keeps one trail row
+ * readable where inlining the whole JSON would not, and the per-step detail is
+ * already recorded by the steps' own rows. */
+function summariseFlow(args) {
+    if (typeof args !== 'object' || args === null)
+        return null;
+    const steps = args.steps;
+    if (!Array.isArray(steps))
+        return null;
+    const kinds = steps
+        .map((step) => typeof step === 'object' && step !== null ? Object.keys(step)[0] : null)
+        .filter((k) => typeof k === 'string');
+    if (kinds.length === 0)
+        return `${steps.length} steps`;
+    return `${steps.length} steps: ${kinds.join(' → ')}`;
+}
+export function extractSelector(tool, args) {
+    const key = SELECTOR_ARG[tool];
+    return key === undefined ? null : readString(args, key);
+}
+export function extractPayload(tool, args) {
+    if (tool === 'browser.flow')
+        return summariseFlow(args);
+    const key = PAYLOAD_ARG[tool];
+    return key === undefined ? null : readString(args, key);
+}
+/** The browser-link tab id the call targeted, when it takes one. */
+export function extractTabId(args) {
+    return readString(args, 'tab_id');
+}
+/** Flow id, for the two tools that address an existing flow by id. Steps
+ * dispatched INSIDE a flow are stamped by the flow runner, not here. */
+export function extractFlowId(args) {
+    return readString(args, 'flow_id');
+}
+/** `cdp:`-prefixed ids are the cdp-direct transport; everything else reached
+ * the page through the extension. Mirrors `isCdpTabId` without importing it,
+ * so the trail keeps working if that predicate ever gains transport-selection
+ * side effects. */
+export function transportFor(tabId) {
+    if (tabId === null)
+        return null;
+    return tabId.startsWith('cdp:') ? 'cdp' : 'extension';
+}
+/** Self-declared label first, binary as the fallback. `agent_id` alone is a
+ * uuid nobody can read; the point of this column is that a human scanning an
+ * exported trail can tell Claude Code from OpenCode at a glance. */
+export function agentNameFor(caller) {
+    if (!caller)
+        return null;
+    if (caller.label && caller.label.length > 0)
+        return caller.label;
+    return caller.binary && caller.binary.length > 0 ? caller.binary : null;
+}
+/** Assemble the row. Deliberately total — every branch returns something
+ * storable, because a tool call that produced a row we could not describe is
+ * still a tool call that happened. */
+export function buildRow({ tool, args, caller, durationMs, error, recordPayloads, }) {
+    const tabId = extractTabId(args);
+    return {
+        tool,
+        tabId,
+        transport: transportFor(tabId),
+        // Filled in by the dispatcher wrapper, which is the only caller that can
+        // see the tab table. Null here keeps this module free of bridge deps.
+        url: null,
+        title: null,
+        agent: agentNameFor(caller),
+        agentPid: caller?.pid ?? null,
+        selector: extractSelector(tool, args),
+        payload: recordPayloads ? extractPayload(tool, args) : null,
+        outcome: error === undefined ? 'ok' : 'error',
+        error: error === undefined ? null : errorMessage(error),
+        durationMs,
+        flowId: extractFlowId(args),
+    };
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return String(error);
+}
+//# sourceMappingURL=extract.js.map

package/dist/activity/extract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract.js","sourceRoot":"","sources":["../../src/activity/extract.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH;oCACoC;AACpC,MAAM,YAAY,GAAiD;IACjE,eAAe,EAAE,UAAU;IAC3B,cAAc,EAAE,UAAU;IAC1B,eAAe,EAAE,UAAU;IAC3B,kBAAkB,EAAE,UAAU;IAC9B,kBAAkB,EAAE,iBAAiB;IACrC,2BAA2B,EAAE,UAAU;CACxC,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,WAAW,GAAiD;IAChE,kBAAkB,EAAE,KAAK;IACzB,cAAc,EAAE,MAAM;IACtB,cAAc,EAAE,MAAM;IACtB,kBAAkB,EAAE,YAAY;IAChC,eAAe,EAAE,KAAK;CACvB,CAAC;AAEF,SAAS,UAAU,CAAC,IAAa,EAAE,GAAW;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,KAAK,GAAI,IAAgC,CAAC,GAAG,CAAC,CAAC;IACrD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AACtE,CAAC;AAED;;;8CAG8C;AAC9C,SAAS,aAAa,CAAC,IAAa;IAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC3D,MAAM,KAAK,GAAI,IAA4B,CAAC,KAAK,CAAC;IAClD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,KAAK,GAAG,KAAK;SAChB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACZ,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,IAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAClF;SACA,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC;IACrD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,GAAG,KAAK,CAAC,MAAM,QAAQ,CAAC;IACvD,OAAO,GAAG,KAAK,CAAC,MAAM,WAAW,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAa;IACzD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAa;IACxD,IAAI,IAAI,KAAK,cAAc;QAAE,OAAO,aAAa,CAAC,IAAI,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9B,OAAO,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,YAAY,CAAC,IAAa;IACxC,OAAO,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;AACpC,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,OAAO,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;AACrC,CAAC;AAED;;;mBAGmB;AACnB,MAAM,UAAU,YAAY,CAAC,KAAoB;IAC/C,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC;AACxD,CAAC;AAED;;oEAEoE;AACpE,MAAM,UAAU,YAAY,CAAC,MAA+B;IAC1D,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC;IACjE,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC1E,CAAC;AAaD;;sCAEsC;AACtC,MAAM,UAAU,QAAQ,CAAC,EACvB,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,UAAU,EACV,KAAK,EACL,cAAc,GACA;IACd,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACjC,OAAO;QACL,IAAI;QACJ,KAAK;QACL,SAAS,EAAE,YAAY,CAAC,KAAK,CAAC;QAC9B,yEAAyE;QACzE,sEAAsE;QACtE,GAAG,EAAE,IAAI;QACT,KAAK,EAAE,IAAI;QACX,KAAK,EAAE,YAAY,CAAC,MAAM,CAAC;QAC3B,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,IAAI;QAC7B,QAAQ,EAAE,eAAe,CAAC,IAAI,EAAE,IAAI,CAAC;QACrC,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,cAAc,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;QAC3D,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;QAC7C,KAAK,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC;QACvD,UAAU;QACV,MAAM,EAAE,aAAa,CAAC,IAAI,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,KAAK,YAAY,KAAK;QAAE,OAAO,KAAK,CAAC,OAAO,CAAC;IACjD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC"}

package/dist/activity/paths.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The activity trail gets its OWN SQLite file, next to `map.db` rather than
+ * inside it.
+ *
+ * The two have opposite lifecycles. `map.db` is small, slow-growing and
+ * precious — it holds what the agent learned about the user's apps, and losing
+ * it means relearning every selector. The trail is append-only, high-churn and
+ * disposable: thousands of rows a session, cleared whenever the user feels like
+ * it.
+ *
+ * Putting them in one file would mean the trail's WAL growth and its
+ * `activity clear` VACUUM both operate on the file holding the map, and it
+ * would make "back up my map" ambiguous. Two files, two retention policies,
+ * no shared blast radius.
+ */
+export declare function getActivityDbPath(): string;

package/dist/activity/paths.js

@@ -0,0 +1,24 @@
+import { join } from 'node:path';
+// The data dir resolver is shared, not map-specific — it predates this module
+// and simply happens to live under map/. Imported rather than duplicated so
+// $BROWSER_LINK_DATA_DIR keeps meaning one thing for the whole process.
+import { getDataDir } from '../map/paths.js';
+/**
+ * The activity trail gets its OWN SQLite file, next to `map.db` rather than
+ * inside it.
+ *
+ * The two have opposite lifecycles. `map.db` is small, slow-growing and
+ * precious — it holds what the agent learned about the user's apps, and losing
+ * it means relearning every selector. The trail is append-only, high-churn and
+ * disposable: thousands of rows a session, cleared whenever the user feels like
+ * it.
+ *
+ * Putting them in one file would mean the trail's WAL growth and its
+ * `activity clear` VACUUM both operate on the file holding the map, and it
+ * would make "back up my map" ambiguous. Two files, two retention policies,
+ * no shared blast radius.
+ */
+export function getActivityDbPath() {
+    return join(getDataDir(), 'activity.db');
+}
+//# sourceMappingURL=paths.js.map

package/dist/activity/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/activity/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,8EAA8E;AAC9E,4EAA4E;AAC5E,wEAAwE;AACxE,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,UAAU,EAAE,EAAE,aAAa,CAAC,CAAC;AAC3C,CAAC"}

package/dist/activity/queries.d.ts

@@ -0,0 +1,100 @@
+import type Database from 'better-sqlite3';
+import type { ActivityInput, ActivityPage, ActivityQuery, ActivityRecord } from './types.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 declare const MAX_QUERY_LIMIT = 500;
+/** 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 declare const MAX_TEXT_LEN = 4000;
+export declare function truncate(value: string | null, max?: number): string | null;
+/**
+ * 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 declare function record(input: ActivityInput, db?: Database.Database): ActivityRecord | null;
+/**
+ * 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 declare function query(q?: ActivityQuery, db?: Database.Database): ActivityPage;
+/** 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 declare function listAgents(db?: Database.Database): {
+    agent: string;
+    count: number;
+}[];
+/** 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 declare function clear(before?: string, db?: Database.Database): number;
+/** An inclusive date window. Both ends optional: `{ from }` alone means
+ * "everything since", `{ to }` alone means "everything up to", `{}` means the
+ * whole trail. ISO-8601 strings, compared lexically — which is exactly right
+ * for the UTC ISO timestamps `record` writes. */
+export interface ActivityRange {
+    from?: string;
+    to?: string;
+}
+/**
+ * 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 declare function countInRange(range: ActivityRange, db?: Database.Database): number;
+/**
+ * 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 declare function purgeRange(range: ActivityRange, options?: {
+    vacuum?: boolean;
+}, db?: Database.Database): number;
+/** What the trail currently costs, for the panel that must always show it. */
+export interface ActivityStats {
+    rows: number;
+    /** Bytes on disk: the DB plus its WAL and shared-memory sidecars. Reporting
+     * only the .db file would understate a busy trail badly — WAL mode parks
+     * recent writes in `activity.db-wal` until a checkpoint folds them in. */
+    bytes: number;
+    /** ISO timestamps of the oldest and newest row, or null on an empty trail.
+     * Lets the UI say "since Aug 3" instead of a bare row count. */
+    oldestAt: string | null;
+    newestAt: string | null;
+    /** The ceiling from `db.ts`, so the UI can show how close the trail is to
+     * pruning itself rather than hardcoding a number that could drift. */
+    maxRows: number;
+}
+export declare function stats(db?: Database.Database): ActivityStats;
+/**
+ * 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 declare function exportAll(filter?: ActivityQuery, db?: Database.Database): Generator<ActivityRecord>;
+/** 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 declare function redact(record: ActivityRecord): ActivityRecord;