@aitne/daemon 0.1.8 → 0.1.10

package/dist/db/browser-history-store.js

@@ -0,0 +1,601 @@
+import { browserHistoryCapabilitiesSchema, browserHistoryLifecycleStateSchema, browserHistoryResearchClustersResponseSchema, getAgentDayDateStr, yesterdayResearchSummarySchema, } from "@aitne/shared";
+import { readRuntimeState, writeRuntimeState, } from "./runtime-state.js";
+export const BROWSER_HISTORY_CAPABILITIES_STATE_KEY = "browser_history_capabilities";
+export const BROWSER_LIFECYCLE_STATE_KEY = "browser_lifecycle_state";
+export const BROWSER_HISTORY_LAST_INGEST_AT_KEY = "browser_history_last_ingest_at";
+export const BROWSER_HISTORY_INGEST_CURSORS_KEY = "browser_history_ingest_cursors";
+export function readBrowserHistoryCapabilities(db) {
+    const value = readRuntimeState(db, BROWSER_HISTORY_CAPABILITIES_STATE_KEY);
+    if (!value)
+        return null;
+    const parsed = browserHistoryCapabilitiesSchema.safeParse(value);
+    return parsed.success ? parsed.data : null;
+}
+export function writeBrowserHistoryCapabilities(db, value) {
+    writeRuntimeState(db, BROWSER_HISTORY_CAPABILITIES_STATE_KEY, value);
+}
+export function readBrowserLifecycleState(db) {
+    const value = readRuntimeState(db, BROWSER_LIFECYCLE_STATE_KEY);
+    if (!value)
+        return {};
+    const parsed = browserHistoryLifecycleStateSchema.safeParse(value);
+    return parsed.success ? parsed.data : {};
+}
+export function writeBrowserLifecycleState(db, value) {
+    writeRuntimeState(db, BROWSER_LIFECYCLE_STATE_KEY, value);
+}
+export function readBrowserHistoryLastIngestAt(db) {
+    const value = readRuntimeState(db, BROWSER_HISTORY_LAST_INGEST_AT_KEY);
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+export function writeBrowserHistoryLastIngestAt(db, value) {
+    writeRuntimeState(db, BROWSER_HISTORY_LAST_INGEST_AT_KEY, value);
+}
+export function listBrowserResearchClusters(db) {
+    const rows = db
+        .prepare(`SELECT
+         slug,
+         display_name AS displayName,
+         started_at AS startedAt,
+         last_activity_at AS lastActivityAt,
+         visits_total AS visitsTotal,
+         meaningful_visits_total AS meaningfulVisitsTotal,
+         meaningful_foreground_sec_total AS meaningfulForegroundSecTotal,
+         distinct_meaningful_domains AS distinctMeaningfulDomains,
+         status,
+         COALESCE(agent_summary_revision, 0) AS agentSummaryRevision
+       FROM browser_research_clusters
+       WHERE status IN ('active', 'dormant')
+       ORDER BY last_activity_at DESC`)
+        .all();
+    return browserHistoryResearchClustersResponseSchema.parse({
+        clusters: rows,
+        generatedAt: new Date().toISOString(),
+    });
+}
+export function getYesterdayResearchSummary(date) {
+    return yesterdayResearchSummarySchema.parse({
+        date,
+        sessions: [],
+    });
+}
+export function browserHistoryProfileCursorKey(browser, profile) {
+    return `${browser}::${profile}`;
+}
+export function readBrowserHistoryIngestCursors(db) {
+    const value = readRuntimeState(db, BROWSER_HISTORY_INGEST_CURSORS_KEY);
+    if (!value || typeof value !== "object")
+        return {};
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (typeof raw === "number" && Number.isFinite(raw)) {
+            out[key] = raw;
+        }
+    }
+    return out;
+}
+export function readBrowserHistoryIngestCursor(db, browser, profile) {
+    return (readBrowserHistoryIngestCursors(db)[browserHistoryProfileCursorKey(browser, profile)] ?? 0);
+}
+export function writeBrowserHistoryIngestCursor(db, browser, profile, cursorMs) {
+    const cursors = readBrowserHistoryIngestCursors(db);
+    cursors[browserHistoryProfileCursorKey(browser, profile)] = cursorMs;
+    writeRuntimeState(db, BROWSER_HISTORY_INGEST_CURSORS_KEY, cursors);
+}
+const INSERT_VISIT_SQL = `
+  INSERT OR IGNORE INTO browser_visits (
+    ts, browser, profile, url_hash, domain, category, meaningful,
+    dwell_sec, foreground_sec, transition, is_reload, root_task_id,
+    http_status, title, search_query, amazon_asin, amazon_locale
+  )
+  VALUES (
+    @ts, @browser, @profile, @urlHash, @domain, @category, @meaningful,
+    @dwellSec, @foregroundSec, @transition, @isReload, @rootTaskId,
+    @httpStatus, @title, @searchQuery, @amazonAsin, @amazonLocale
+  )
+`;
+export function insertBrowserVisits(db, visits) {
+    if (visits.length === 0)
+        return { inserted: 0, duplicates: 0 };
+    const stmt = db.prepare(INSERT_VISIT_SQL);
+    let inserted = 0;
+    let duplicates = 0;
+    const tx = db.transaction((rows) => {
+        for (const row of rows) {
+            const info = stmt.run(row);
+            if (info.changes > 0) {
+                inserted += 1;
+            }
+            else {
+                duplicates += 1;
+            }
+        }
+    });
+    tx(visits);
+    return { inserted, duplicates };
+}
+const RELOAD_UPSERT_SQL = `
+  INSERT INTO browser_reload_signals (date, url_pattern, reload_count)
+  VALUES (?, ?, ?)
+  ON CONFLICT (date, url_pattern) DO UPDATE SET
+    reload_count = reload_count + excluded.reload_count
+`;
+export function incrementReloadSignals(db, increments) {
+    if (increments.length === 0)
+        return;
+    const stmt = db.prepare(RELOAD_UPSERT_SQL);
+    const tx = db.transaction((rows) => {
+        for (const row of rows) {
+            stmt.run(row.date, row.urlPattern, row.count);
+        }
+    });
+    tx(increments);
+}
+const CLUSTER_INSERT_SQL = `
+  INSERT INTO browser_research_clusters (
+    slug, root_task_id, display_name, started_at, last_activity_at,
+    visits_total, meaningful_visits_total, meaningful_foreground_sec_total,
+    distinct_meaningful_domains, status, agent_summary_revision
+  ) VALUES (
+    @slug, @rootTaskId, @displayName, @startedAt, @lastActivityAt,
+    @visitsTotal, @meaningfulVisitsTotal, @meaningfulForegroundSecTotal,
+    @distinctMeaningfulDomains, @status, 0
+  )
+`;
+// The cluster's stable identity is `root_task_id`, not `slug`. The slug is a
+// label composed from the cluster's currently-dominant domain + search term
+// (deriveClusterSlug), so as more visits accumulate for the same root task the
+// dominant term can shift and the next ingest tick derives a *different* slug.
+// The old `ON CONFLICT (slug)` upsert then missed the conflict and the INSERT
+// collided with the row's existing `root_task_id` UNIQUE constraint, throwing
+// SqliteError and aborting the whole ingest transaction (no clusters written
+// that tick). We update by root_task_id and leave the persisted slug untouched
+// so browser_pending_offers rows — which reference clusters by slug — stay
+// joined.
+const CLUSTER_UPDATE_BY_ROOT_SQL = `
+  UPDATE browser_research_clusters SET
+    last_activity_at = @lastActivityAt,
+    visits_total = @visitsTotal,
+    meaningful_visits_total = @meaningfulVisitsTotal,
+    meaningful_foreground_sec_total = @meaningfulForegroundSecTotal,
+    distinct_meaningful_domains = @distinctMeaningfulDomains,
+    display_name = CASE
+      WHEN agent_summary_revision = 0 THEN @displayName
+      ELSE display_name
+    END,
+    status = CASE
+      WHEN status IN ('muted', 'concluded') THEN status
+      ELSE @status
+    END
+  WHERE root_task_id = @rootTaskId
+`;
+const DORMANT_AFTER_MS = 10 * 24 * 60 * 60 * 1000;
+function chooseClusterStatus(lastActivityAt, qualifies, nowMs) {
+    if (!qualifies)
+        return "dormant";
+    return nowMs - lastActivityAt > DORMANT_AFTER_MS ? "dormant" : "active";
+}
+export function upsertResearchClusters(db, clusters, nowMs = Date.now()) {
+    if (clusters.length === 0)
+        return;
+    const insertStmt = db.prepare(CLUSTER_INSERT_SQL);
+    const updateStmt = db.prepare(CLUSTER_UPDATE_BY_ROOT_SQL);
+    const existingForRoot = db.prepare("SELECT slug FROM browser_research_clusters WHERE root_task_id = ?");
+    const slugHeldByOtherRoot = db.prepare("SELECT 1 FROM browser_research_clusters WHERE slug = ? AND root_task_id <> ?");
+    const tx = db.transaction((rows) => {
+        for (const cluster of rows) {
+            const rootTaskId = cluster.aggregate.rootTaskId;
+            // Fields shared by both paths. `started_at` and `slug` are INSERT-only
+            // (started_at is set once and preserved across ticks; slug is keyed on
+            // separately below), so they are excluded here and added to the INSERT
+            // params — keeping each statement's bound object to exactly its `@`
+            // placeholders.
+            const shared = {
+                rootTaskId,
+                displayName: cluster.displayName,
+                lastActivityAt: cluster.aggregate.lastActivityAt,
+                visitsTotal: cluster.aggregate.visitsTotal,
+                meaningfulVisitsTotal: cluster.aggregate.meaningfulVisitsTotal,
+                meaningfulForegroundSecTotal: cluster.aggregate.meaningfulForegroundSecTotal,
+                distinctMeaningfulDomains: cluster.aggregate.distinctMeaningfulDomains,
+                status: chooseClusterStatus(cluster.aggregate.lastActivityAt, cluster.qualifies, nowMs),
+            };
+            if (existingForRoot.get(rootTaskId)) {
+                updateStmt.run(shared);
+                continue;
+            }
+            // New root task. Guard the slug PRIMARY KEY against a value already held
+            // by a different root_task_id: two roots can derive the same base slug in
+            // separate ingest ticks, where the in-run usedSlugs disambiguator
+            // (cluster-extractor) cannot see previously-persisted rows.
+            let slug = cluster.slug;
+            if (slugHeldByOtherRoot.get(slug, rootTaskId)) {
+                slug = `${slug}-${rootTaskId}`;
+            }
+            insertStmt.run({
+                ...shared,
+                startedAt: cluster.aggregate.startedAt,
+                slug,
+            });
+        }
+    });
+    tx(clusters);
+}
+export function replaceShoppingSessions(db, date, sessions) {
+    const tx = db.transaction(() => {
+        db.prepare("DELETE FROM browser_shopping_sessions WHERE date = ?").run(date);
+        if (sessions.length === 0)
+            return;
+        const stmt = db.prepare(`INSERT INTO browser_shopping_sessions
+         (date, vendor, asin_set, comparison_minutes, locale)
+       VALUES (?, ?, ?, ?, ?)`);
+        for (const session of sessions) {
+            stmt.run(session.date, session.vendor, JSON.stringify([...session.asinSet]), session.comparisonMinutes, session.locale);
+        }
+    });
+    tx();
+}
+export function listShoppingSessionsForDate(db, date) {
+    const rows = db
+        .prepare(`SELECT date, vendor, asin_set, comparison_minutes, locale
+       FROM browser_shopping_sessions
+       WHERE date = ?
+       ORDER BY id ASC`)
+        .all(date);
+    return rows.map((row) => {
+        let asins = [];
+        try {
+            const parsed = JSON.parse(row.asin_set);
+            if (Array.isArray(parsed)) {
+                asins = parsed.filter((value) => typeof value === "string");
+            }
+        }
+        catch {
+            // Corrupt JSON in the database — surface zero ASINs rather than
+            // throw; the API endpoint Zod-validates and a 0-ASIN row will be
+            // filtered out at the response boundary.
+        }
+        return {
+            date: row.date,
+            vendor: "amazon",
+            asins,
+            comparisonMinutes: row.comparison_minutes,
+            locale: row.locale,
+        };
+    });
+}
+export function listReloadsForDate(db, date, limit = 50) {
+    const rows = db
+        .prepare(`SELECT url_pattern AS urlPattern, reload_count AS reloadCount
+       FROM browser_reload_signals
+       WHERE date = ?
+       ORDER BY reload_count DESC, url_pattern ASC
+       LIMIT ?`)
+        .all(date, limit);
+    return rows;
+}
+export function listReloadsForRange(db, rangeStart, rangeEnd, limit = 50) {
+    return db
+        .prepare(`SELECT
+         url_pattern AS urlPattern,
+         SUM(reload_count) AS reloadCount,
+         COUNT(DISTINCT date) AS days
+       FROM browser_reload_signals
+       WHERE date >= ? AND date <= ?
+       GROUP BY url_pattern
+       ORDER BY reloadCount DESC, url_pattern ASC
+       LIMIT ?`)
+        .all(rangeStart, rangeEnd, limit);
+}
+// ── P3 — cluster engagement (DM budget, offers, delta) ──
+const CLUSTER_DETAIL_QUERY = `
+  SELECT
+    slug,
+    root_task_id AS rootTaskId,
+    display_name AS displayName,
+    started_at AS startedAt,
+    last_activity_at AS lastActivityAt,
+    visits_total AS visitsTotal,
+    meaningful_visits_total AS meaningfulVisitsTotal,
+    meaningful_foreground_sec_total AS meaningfulForegroundSecTotal,
+    distinct_meaningful_domains AS distinctMeaningfulDomains,
+    status,
+    COALESCE(agent_summary_revision, 0) AS agentSummaryRevision,
+    last_dm_at AS lastDmAt,
+    last_research_offer_at AS lastResearchOfferAt,
+    last_wiki_offer_at AS lastWikiOfferAt,
+    research_offer_accepted_at AS researchOfferAcceptedAt,
+    wiki_summary_written_at AS wikiSummaryWrittenAt
+  FROM browser_research_clusters
+  WHERE slug = ?
+`;
+/**
+ * Read a cluster row with the full P3 engagement field set. Returns null
+ * when the slug does not exist. The result is the *raw* DB shape; the
+ * route layer assembles `topDomains` via a separate query and Zod-parses
+ * the union before returning to the agent / dashboard.
+ */
+export function getResearchClusterDetail(db, slug) {
+    const row = db.prepare(CLUSTER_DETAIL_QUERY).get(slug);
+    return row ?? null;
+}
+/**
+ * Top eTLD+1 labels (regex-constrained domain shape) observed inside the
+ * cluster, ordered by visit count. Capped at `limit` so the cluster
+ * detail payload stays bounded. The label is never a raw URL — visits
+ * already store `domain` as the eTLD+1, written by `redactor.ts`.
+ */
+export function listTopDomainsForCluster(db, rootTaskId, limit = 10) {
+    const rows = db
+        .prepare(`SELECT domain, COUNT(*) AS visits
+       FROM browser_visits
+       WHERE root_task_id = ? AND meaningful = 1
+       GROUP BY domain
+       ORDER BY visits DESC, domain ASC
+       LIMIT ?`)
+        .all(rootTaskId, limit);
+    return rows.map((row) => row.domain);
+}
+/**
+ * Per-day delta over the cluster's meaningful visits, bucketed by the
+ * agent-day calendar (so a visit at 03:30 lands in the prior day's
+ * bucket when `dayBoundaryHour=4`). `newDomains` is the set of eTLD+1
+ * labels that appear in this day's bucket but did not appear in any
+ * earlier bucket of the same cluster — the "what changed yesterday"
+ * surface the F2 digest pulls into the morning journal.
+ *
+ * Pure aggregation over `browser_visits`. Bounded at the API layer by
+ * `dayLimit` (default 31 days back from today) to keep payloads small.
+ */
+export function listClusterDailyDeltas(db, rootTaskId, boundary, options = {}) {
+    const rows = db
+        .prepare(`SELECT ts, domain, foreground_sec AS foregroundSec
+       FROM browser_visits
+       WHERE root_task_id = ? AND meaningful = 1
+         AND (? IS NULL OR ts >= ?)
+       ORDER BY ts ASC`)
+        .all(rootTaskId, options.sinceMs ?? null, options.sinceMs ?? null);
+    const buckets = new Map();
+    const seenDomains = new Set();
+    const orderedDays = [];
+    for (const row of rows) {
+        const day = getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(row.ts));
+        let bucket = buckets.get(day);
+        if (!bucket) {
+            bucket = { visits: 0, foregroundSec: 0, domains: new Set() };
+            buckets.set(day, bucket);
+            orderedDays.push(day);
+        }
+        bucket.visits += 1;
+        bucket.foregroundSec += row.foregroundSec ?? 0;
+        bucket.domains.add(row.domain);
+    }
+    const out = [];
+    for (const day of orderedDays) {
+        // `orderedDays` is only appended to when a fresh bucket is inserted
+        // above, so the lookup here is guaranteed to hit.
+        const bucket = buckets.get(day);
+        const newDomains = [];
+        for (const domain of bucket.domains) {
+            if (!seenDomains.has(domain)) {
+                newDomains.push(domain);
+            }
+        }
+        for (const domain of bucket.domains)
+            seenDomains.add(domain);
+        out.push({
+            date: day,
+            meaningfulVisits: bucket.visits,
+            meaningfulForegroundSec: bucket.foregroundSec,
+            newDomains: newDomains.sort(),
+        });
+    }
+    if (options.dayLimit && out.length > options.dayLimit) {
+        return out.slice(out.length - options.dayLimit);
+    }
+    return out;
+}
+/**
+ * Stamp the DM dispatch wall-clock + offer-tracking columns after a
+ * templated DM has been queued through the notification path. All
+ * three columns are optional — pass null to leave a column untouched.
+ *
+ * Idempotent under concurrent writers: every column either retains
+ * its prior value or moves forward (UPDATE … SET col = COALESCE(?, col))
+ * so a double-fire from a poller race cannot regress an earlier
+ * stamp.
+ */
+export function stampClusterDmFields(db, slug, fields) {
+    const stmt = db.prepare(`UPDATE browser_research_clusters
+     SET
+       last_dm_at = COALESCE(?, last_dm_at),
+       last_research_offer_at = COALESCE(?, last_research_offer_at),
+       last_wiki_offer_at = COALESCE(?, last_wiki_offer_at),
+       research_offer_accepted_at = COALESCE(?, research_offer_accepted_at),
+       wiki_summary_written_at = COALESCE(?, wiki_summary_written_at),
+       status = COALESCE(?, status)
+     WHERE slug = ?`);
+    stmt.run(fields.lastDmAt ?? null, fields.lastResearchOfferAt ?? null, fields.lastWikiOfferAt ?? null, fields.researchOfferAcceptedAt ?? null, fields.wikiSummaryWrittenAt ?? null, fields.statusOverride ?? null, slug);
+}
+/**
+ * Explicitly NULL out one or more `last_*_offer_at` stamps. Sibling of
+ * `stampClusterDmFields` for the wiki-summary acceptance path: that
+ * path needs to break the rate-limit gate's `decline_backoff` condition
+ * (which trips when `lastWikiOfferAt !== null AND
+ * wikiSummaryWrittenAt === null`), and the gate's bookkeeping has no
+ * separate "user accepted wiki" stamp. `stampClusterDmFields` uses
+ * `COALESCE(?, col)` so passing `null` there is a no-op — it preserves
+ * the prior value to keep concurrent writers idempotent. This function
+ * is the explicit-clear branch.
+ *
+ * Pass `true` for the column(s) to clear. Calling with no flags is a
+ * no-op (skips the UPDATE) so the function is safe to invoke
+ * unconditionally from a switch branch.
+ */
+export function clearClusterOfferStamps(db, slug, fields) {
+    const sets = [];
+    if (fields.lastResearchOfferAt)
+        sets.push("last_research_offer_at = NULL");
+    if (fields.lastWikiOfferAt)
+        sets.push("last_wiki_offer_at = NULL");
+    if (sets.length === 0)
+        return;
+    db.prepare(`UPDATE browser_research_clusters SET ${sets.join(", ")} WHERE slug = ?`).run(slug);
+}
+/**
+ * Set the cluster's status with a hard override (rename / conclude /
+ * mute / unmute paths). Differs from `stampClusterDmFields` in that
+ * it always writes — never COALESCE — and from the poller's upsert in
+ * that the upsert preserves `muted` / `concluded` against newly
+ * arriving visits, while this path is the source of truth for the
+ * user / bang-command-driven transition.
+ */
+export function setResearchClusterStatus(db, slug, status) {
+    const info = db
+        .prepare(`UPDATE browser_research_clusters SET status = ? WHERE slug = ?`)
+        .run(status, slug);
+    return info.changes > 0;
+}
+/**
+ * Rename a cluster — only the operator-facing `display_name` changes.
+ * The slug is the PK and is held stable (the user types `!research <slug>`
+ * after rename, but the URL-friendly slug remains the same — a new
+ * slug would orphan the existing context/research/<slug>.md note and
+ * any in-flight DM offer references). `agent_summary_revision` is
+ * bumped so the next cluster_update sees a non-zero revision and
+ * stops re-deriving the display name from top domain + top search
+ * term (preserving the operator's pick).
+ */
+export function renameResearchCluster(db, slug, displayName) {
+    const info = db
+        .prepare(`UPDATE browser_research_clusters
+       SET display_name = ?,
+           agent_summary_revision = MAX(agent_summary_revision, 1)
+       WHERE slug = ?`)
+        .run(displayName, slug);
+    return info.changes > 0;
+}
+/**
+ * Bump `agent_summary_revision` after a `routine.research_cluster_update`
+ * session writes the day entry to `context/research/<slug>.md`. The
+ * poller-side upsert reads this column to decide whether the operator
+ * has invested in a custom display name yet; the cluster_update
+ * routine reads it to decide whether to skip a no-op run.
+ */
+export function bumpClusterAgentSummaryRevision(db, slug) {
+    const info = db
+        .prepare(`UPDATE browser_research_clusters
+       SET agent_summary_revision = agent_summary_revision + 1
+       WHERE slug = ?`)
+        .run(slug);
+    if (info.changes === 0)
+        return 0;
+    // The UPDATE just succeeded on this slug, so the SELECT below is
+    // guaranteed to find it (single-writer SQLite, same db handle).
+    const row = db
+        .prepare(`SELECT agent_summary_revision AS rev FROM browser_research_clusters WHERE slug = ?`)
+        .get(slug);
+    return row.rev;
+}
+/**
+ * Clusters whose `last_activity_at` is newer than the row's most recent
+ * cluster_update session — i.e. the agent has new visits to journal.
+ * Surfaces only `active` rows: muted / concluded / dormant clusters do
+ * not get nightly journal appends. Capped by `limit` so a backlog never
+ * floods the schedule fan-out.
+ */
+export function listClustersNeedingUpdate(db, lookbackMs, nowMs = Date.now(), limit = 25) {
+    const since = nowMs - lookbackMs;
+    return db
+        .prepare(`SELECT slug, display_name AS displayName
+       FROM browser_research_clusters
+       WHERE status = 'active'
+         AND last_activity_at >= ?
+       ORDER BY last_activity_at DESC
+       LIMIT ?`)
+        .all(since, limit);
+}
+// ── browser_pending_offers — materialised view of open offer state ──
+export const OFFER_DEFAULT_TTL_MS = 14 * 24 * 60 * 60 * 1000;
+/**
+ * INSERT-OR-REPLACE the open-offer row for (slug, kind). REPLACE keeps the
+ * row idempotent under a poller re-emit: a cluster that re-qualifies after
+ * an expired offer cleanup gets its `expires_at` extended without first
+ * deleting; a cluster that already has an open row keeps its offered_at /
+ * expires_at as-is (the poller's `shouldEmitOffer` check filters before
+ * this path is called).
+ */
+export function upsertPendingOffer(db, input) {
+    db.prepare(`INSERT INTO browser_pending_offers (slug, kind, offered_at, expires_at)
+     VALUES (?, ?, ?, ?)
+     ON CONFLICT (slug, kind) DO UPDATE SET
+       offered_at = excluded.offered_at,
+       expires_at = excluded.expires_at`).run(input.slug, input.kind, input.offeredAt, input.expiresAt);
+}
+export function deletePendingOffer(db, slug, kind) {
+    const info = db
+        .prepare(`DELETE FROM browser_pending_offers WHERE slug = ? AND kind = ?`)
+        .run(slug, kind);
+    return info.changes > 0;
+}
+export function deletePendingOffersForCluster(db, slug) {
+    const info = db
+        .prepare(`DELETE FROM browser_pending_offers WHERE slug = ?`)
+        .run(slug);
+    return info.changes;
+}
+/**
+ * List open offers joined to their cluster display name. The route layer
+ * returns this verbatim (after Zod parse) for `/api/browser-history/offers/pending`
+ * and the pre-morning digest surfaces it in `pending-offers.md`.
+ *
+ * Expired offers (now > expires_at) are filtered out and lazily purged
+ * — purge runs inline so the next `!research` list does not show a
+ * dangling row. Lazy purge avoids a dedicated cron entry; the table is
+ * small (≤1 row per cluster per kind, capped by the 14-day TTL).
+ */
+export function listPendingOffersWithDisplay(db, nowMs = Date.now()) {
+    db.prepare(`DELETE FROM browser_pending_offers WHERE expires_at < ?`).run(nowMs);
+    return db
+        .prepare(`SELECT
+         po.slug,
+         c.display_name AS displayName,
+         po.kind,
+         po.offered_at AS offeredAt,
+         po.expires_at AS expiresAt
+       FROM browser_pending_offers po
+       JOIN browser_research_clusters c ON c.slug = po.slug
+       ORDER BY po.offered_at DESC`)
+        .all();
+}
+export function listPendingOffersForCluster(db, slug, nowMs = Date.now()) {
+    return db
+        .prepare(`SELECT
+         po.slug,
+         c.display_name AS displayName,
+         po.kind,
+         po.offered_at AS offeredAt,
+         po.expires_at AS expiresAt
+       FROM browser_pending_offers po
+       JOIN browser_research_clusters c ON c.slug = po.slug
+       WHERE po.slug = ? AND po.expires_at >= ?
+       ORDER BY po.offered_at DESC`)
+        .all(slug, nowMs);
+}
+export function applyBrowserHistoryRetention(db, retention, nowMs = Date.now()) {
+    const visitCutoff = nowMs - retention.visitRetentionDays * 86_400_000;
+    const queryCutoff = nowMs - retention.searchQueryRetentionDays * 86_400_000;
+    const tx = db.transaction(() => {
+        const cleared = db
+            .prepare("UPDATE browser_visits SET search_query = NULL WHERE search_query IS NOT NULL AND ts < ?")
+            .run(queryCutoff);
+        const deleted = db
+            .prepare("DELETE FROM browser_visits WHERE ts < ?")
+            .run(visitCutoff);
+        return {
+            visitsDeleted: deleted.changes,
+            searchQueriesCleared: cleared.changes,
+        };
+    });
+    return tx();
+}

package/dist/db/browser-task-action-log-store.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Browser-task action log — BROWSER_TASK_REDESIGN_PLAN.md §6.6.
+ *
+ * One row per tool call (and per defence-in-depth event: popup close,
+ * dialog dismiss, file-chooser cancel, download block — emitted with
+ * tool_name='browser_internal' per §14.3 / §14.4).
+ *
+ * I/O-bound — the dashboard reads via paginated list, the runner only
+ * appends. Excluded from the coverage gate per the same `db/*` exclusion
+ * rationale as the B-4 stores.
+ */
+import type Database from "better-sqlite3";
+export type BrowserTaskActionOutcome = "ok" | "denied" | "error" | "allowlist_block" | "payment_block" | "timeout" | "popup_blocked" | "dialog_dismissed" | "filechooser_cancelled" | "download_blocked" | "extract_cap_exceeded" | "tool_loop_detected";
+export interface BrowserTaskActionLogRow {
+    id: number;
+    taskId: string;
+    stepIndex: number;
+    toolName: string;
+    args: unknown;
+    outcome: BrowserTaskActionOutcome;
+    blockedReason: string | null;
+    screenshotKey: string | null;
+    durationMs: number;
+    at: number;
+}
+export interface InsertBrowserTaskActionLogInput {
+    taskId: string;
+    stepIndex: number;
+    toolName: string;
+    args: unknown;
+    outcome: BrowserTaskActionOutcome;
+    blockedReason?: string | null;
+    screenshotKey?: string | null;
+    durationMs: number;
+    at: number;
+}
+export declare function insertBrowserTaskActionLog(db: Database.Database, input: InsertBrowserTaskActionLogInput): BrowserTaskActionLogRow;
+/** Highest existing step_index for this task, or -1 if none yet. The
+ *  runner increments from here to assign the next step's index. */
+export declare function nextStepIndexFor(db: Database.Database, taskId: string): number;
+export declare function listBrowserTaskActionLog(db: Database.Database, taskId: string): readonly BrowserTaskActionLogRow[];