@aitne/daemon 0.1.7 → 0.1.9

package/dist/services/browser-history/pipeline/summarizer.js

@@ -0,0 +1,97 @@
+import { createHash } from "node:crypto";
+import { getAgentDayDateStr } from "@aitne/shared";
+import { classifyVisit } from "./classifier.js";
+import { redactVisit } from "./redactor.js";
+import { classifyMeaningful, EMPTY_RESEARCH_DOMAIN_LISTS, } from "./meaningful-filter.js";
+import { extractAmazonReference } from "./amazon-extractor.js";
+import { isReloadTransition, reloadPatternKey } from "./reload-detector.js";
+const DEFAULT_BOUNDARY = {
+    timezone: undefined,
+    dayBoundaryHour: 4,
+};
+function agentDayKey(tsMs, boundary) {
+    return getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(tsMs));
+}
+const HASH_DOMAIN = "browser-visit";
+function hashUrl(url) {
+    return createHash("sha256").update(`${HASH_DOMAIN}:${url}`).digest("hex");
+}
+function strippedHost(host) {
+    return host.replace(/^www\./i, "").toLowerCase();
+}
+export function summarizeVisits(input) {
+    const boundary = input.boundary ?? DEFAULT_BOUNDARY;
+    const researchDomainLists = input.researchDomainLists ?? EMPTY_RESEARCH_DOMAIN_LISTS;
+    const visits = [];
+    let highestTimestampMs = 0;
+    let dropped = 0;
+    const reloadCounter = new Map();
+    for (const row of input.rows) {
+        if (row.visitTimeMs > highestTimestampMs) {
+            highestTimestampMs = row.visitTimeMs;
+        }
+        const redacted = redactVisit({
+            url: row.url,
+            title: row.title,
+            searchQuery: row.searchTerm,
+        });
+        if (redacted.drop || !redacted.scheme || !redacted.host) {
+            dropped += 1;
+            continue;
+        }
+        const category = classifyVisit({
+            scheme: redacted.scheme,
+            host: redacted.host,
+            path: redacted.path,
+        });
+        const meaningfulVerdict = classifyMeaningful({
+            scheme: redacted.scheme,
+            host: redacted.host,
+            path: redacted.path,
+            category,
+            foregroundSeconds: row.foregroundSec,
+        }, researchDomainLists);
+        const amazon = category === "shopping"
+            ? extractAmazonReference({
+                scheme: redacted.scheme,
+                host: redacted.host,
+                path: redacted.path,
+                url: redacted.url,
+            })
+            : null;
+        const reload = isReloadTransition(row.transition);
+        if (reload) {
+            const pattern = reloadPatternKey({
+                host: strippedHost(redacted.host),
+                path: redacted.path,
+            });
+            const key = `${agentDayKey(row.visitTimeMs, boundary)}::${pattern}`;
+            reloadCounter.set(key, (reloadCounter.get(key) ?? 0) + 1);
+        }
+        visits.push({
+            ts: row.visitTimeMs,
+            browser: input.browser,
+            profile: input.profile,
+            urlHash: hashUrl(redacted.url),
+            domain: strippedHost(redacted.host),
+            category,
+            meaningful: meaningfulVerdict.meaningful ? 1 : 0,
+            dwellSec: row.durationSinceLastVisitSec,
+            foregroundSec: row.foregroundSec,
+            transition: row.transition,
+            isReload: reload ? 1 : 0,
+            rootTaskId: row.rootTaskId,
+            httpStatus: row.httpStatus,
+            title: redacted.title,
+            searchQuery: redacted.searchQuery,
+            amazonAsin: amazon?.asin ?? null,
+            amazonLocale: amazon?.locale ?? null,
+        });
+    }
+    const reloadIncrements = [];
+    for (const [key, count] of reloadCounter) {
+        const [date, urlPattern] = key.split("::");
+        reloadIncrements.push({ date, urlPattern, count });
+    }
+    return { visits, reloadIncrements, highestTimestampMs, dropped };
+}

package/dist/services/browser-history/pipeline/weekly-interests-summary.d.ts

@@ -0,0 +1,139 @@
+import type Database from "better-sqlite3";
+/**
+ * WEEKLY_INTERESTS_REFLECTION_PLAN.md §10.1 — deterministic Layer-1
+ * builder for the weekly interest reflection.
+ *
+ * Pure aggregation over `browser_research_clusters` joined with
+ * `browser_visits` for the 7-day window ending at the weekly_review
+ * trigger time, agent-day-aligned (default 04:00 boundary). No LLM, no
+ * network, no filesystem; SQLite is the only I/O.
+ *
+ * Two responsibilities split deliberately:
+ *
+ * 1. `buildWeeklyInterestsSummary` — the production entry. Reads the
+ *    cluster rows + per-visit history, ranks the active set by
+ *    meaningful foreground seconds in the window, and diffs against the
+ *    prior 7-day window to surface "dormant since last week" entries.
+ *    Optionally accepts `projectKeywords` (from `project-matcher.ts`)
+ *    so the caller doesn't need a second pass.
+ *
+ * 2. The exported pure helpers `pickTopClusters`, `weekWindowMs`, and
+ *    `weekStartFromDate` exist so the same date math and ranking are
+ *    available to tests and to the `GET /api/browser-history/
+ *    weekly-interests-summary` route without rebuilding them.
+ *
+ * Invariants the caller can rely on:
+ *   - `clusters` is sorted by `meaningfulForegroundSec` desc, ties
+ *     broken by `distinctMeaningfulDomains` desc, then by `slug`. Capped
+ *     at `options.maxClusters` (default 20).
+ *   - Every cluster in `clusters` has at least one meaningful visit
+ *     inside `[weekStartMs, weekEndMs)` AND status='active'.
+ *   - `dormantSinceLastWeek` contains rows that had meaningful visits
+ *     in the prior 7-day window but NONE in the current window. Sorted
+ *     by `lastActivity` desc.
+ *   - `projectMatches` is computed only when `options.projectKeywords`
+ *     is supplied; matchers operate on `clusters` (the post-cap set).
+ */
+export type ClusterStatusChange = "new" | "active_continued" | "newly_dormant" | "muted_this_week";
+export interface ClusterSnapshot {
+    slug: string;
+    displayName: string;
+    /** Distinct agent-day buckets the cluster had meaningful visits in. */
+    daysActive: number;
+    /** Meaningful visit count inside the 7-day window. */
+    meaningfulVisits: number;
+    /** Meaningful foreground seconds inside the 7-day window. */
+    meaningfulForegroundSec: number;
+    /** Distinct meaningful domains inside the 7-day window. */
+    distinctMeaningfulDomains: number;
+    /** Top-5 meaningful domains inside the window, ranked by foreground sec. */
+    topDomains: string[];
+    /** Cluster row `status` at read time. */
+    status: "active" | "dormant" | "concluded" | "muted";
+    /**
+     * Change since last week. `"new"` = no meaningful visits in the prior
+     * window but ≥1 in the current; `"active_continued"` = present in
+     * both windows.
+     *
+     * Clusters that became dormant this week never appear in the active
+     * `clusters` set — they surface in `dormantSinceLastWeek` instead, so
+     * `"newly_dormant"` and `"muted_this_week"` are reserved for the
+     * dormant-list use case and are present here only for shape parity
+     * with `WeeklyInterestsSummary`.
+     */
+    statusChange: ClusterStatusChange;
+    /** Path under `contextDir` to the cluster journal (no leading slash). */
+    clusterJournalPath: string;
+    hasOpenOffer: boolean;
+    hasAcceptedResearch: boolean;
+    hasWikiSummary: boolean;
+    /** Agent-day date string of `lastActivityAt`, for downstream display. */
+    lastActivityDate: string;
+    /** Raw ms timestamp of the cluster's last meaningful activity. */
+    lastActivityMs: number;
+}
+export interface DormantClusterEntry {
+    slug: string;
+    displayName: string;
+    /** Agent-day date string of the most recent activity (now outside window). */
+    lastActivity: string;
+    lastActivityMs: number;
+}
+export interface ProjectMatch {
+    projectSlug: string;
+    projectPath: string;
+    clusters: {
+        slug: string;
+        reason: "filename_match" | "jaccard";
+    }[];
+}
+export interface ProjectKeywords {
+    projectSlug: string;
+    projectPath: string;
+    keywords: Set<string>;
+    source: "explicit" | "frontmatter" | "filename";
+}
+export interface WeeklyInterestsSummary {
+    /** Agent-day YYYY-MM-DD start (inclusive). */
+    weekStart: string;
+    /** Agent-day YYYY-MM-DD end (inclusive — the last day in the window). */
+    weekEnd: string;
+    /** ISO timestamp of when this summary was built. */
+    generatedAt: string;
+    clusters: ClusterSnapshot[];
+    dormantSinceLastWeek: DormantClusterEntry[];
+    projectMatches: ProjectMatch[];
+}
+export interface AgentDayBoundary {
+    readonly timezone: string | undefined;
+    readonly dayBoundaryHour: number;
+}
+export interface BuildSummaryOptions {
+    readonly maxClusters?: number;
+    readonly maxProjectClusters?: number;
+    readonly boundary?: AgentDayBoundary;
+    readonly projectKeywords?: readonly ProjectKeywords[];
+    /** Override for deterministic tests; defaults to `Date.now()`. */
+    readonly nowMs?: number;
+}
+/**
+ * Anchor a YYYY-MM-DD agent-day-aligned `weekStart` to the UTC ms range
+ * the SQL filter consumes. Exported so the API route can validate that
+ * the caller's `weekStart` is genuinely a Monday before recomputing.
+ */
+export declare function weekWindowMs(weekStart: string, boundary: AgentDayBoundary): {
+    startMs: number;
+    endMs: number;
+};
+/**
+ * Return the agent-day date string for `nowMs`. Useful for the
+ * scheduler / dashboard helpers that need "today's agent-day" without
+ * importing the shared helper directly.
+ */
+export declare function weekStartFromDate(nowMs: number, boundary?: AgentDayBoundary): string;
+/**
+ * Sort the `clusters` array deterministically. Exported so the renderer
+ * tests can reuse the same ordering rule.
+ */
+export declare function pickTopClusters(clusters: readonly ClusterSnapshot[], maxClusters: number): ClusterSnapshot[];
+export declare function buildWeeklyInterestsSummary(db: Database.Database, weekStart: string, options?: BuildSummaryOptions): WeeklyInterestsSummary;

package/dist/services/browser-history/pipeline/weekly-interests-summary.js

@@ -0,0 +1,227 @@
+import { getAgentDayBoundsUtc, getAgentDayDateStr, parseSqliteUtcMs, } from "@aitne/shared";
+import { matchClustersToProject } from "./project-matcher.js";
+const DEFAULT_BOUNDARY = {
+    timezone: undefined,
+    dayBoundaryHour: 4,
+};
+const DEFAULT_MAX_CLUSTERS = 20;
+const DEFAULT_MAX_PROJECT_CLUSTERS = 5;
+const WINDOW_DAYS = 7;
+const WEEK_MS = WINDOW_DAYS * 24 * 60 * 60 * 1000;
+const TOP_DOMAINS_CAP = 5;
+/**
+ * Anchor a YYYY-MM-DD agent-day-aligned `weekStart` to the UTC ms range
+ * the SQL filter consumes. Exported so the API route can validate that
+ * the caller's `weekStart` is genuinely a Monday before recomputing.
+ */
+export function weekWindowMs(weekStart, boundary) {
+    // Anchor at noon UTC on the requested date so DST transitions don't
+    // shift us into the previous agent-day. `getAgentDayBoundsUtc`
+    // resolves the local-time 04:00 boundary anchored on the noon-UTC
+    // input.
+    const anchor = new Date(`${weekStart}T12:00:00Z`);
+    const bounds = getAgentDayBoundsUtc(boundary.timezone, boundary.dayBoundaryHour, anchor);
+    const startMs = parseSqliteUtcMs(bounds.start);
+    return { startMs, endMs: startMs + WEEK_MS };
+}
+/**
+ * Return the agent-day date string for `nowMs`. Useful for the
+ * scheduler / dashboard helpers that need "today's agent-day" without
+ * importing the shared helper directly.
+ */
+export function weekStartFromDate(nowMs, boundary = DEFAULT_BOUNDARY) {
+    return getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(nowMs));
+}
+const ACTIVE_CLUSTERS_QUERY = `
+  SELECT
+    slug,
+    root_task_id AS rootTaskId,
+    display_name AS displayName,
+    status,
+    started_at AS startedAt,
+    last_activity_at AS lastActivityAt,
+    meaningful_visits_total AS meaningfulVisitsTotal,
+    meaningful_foreground_sec_total AS meaningfulForegroundSecTotal,
+    distinct_meaningful_domains AS distinctMeaningfulDomains,
+    research_offer_accepted_at AS researchOfferAcceptedAt,
+    wiki_summary_written_at AS wikiSummaryWrittenAt
+  FROM browser_research_clusters
+  WHERE status = 'active'
+`;
+const ALL_CLUSTERS_QUERY = `
+  SELECT
+    slug,
+    root_task_id AS rootTaskId,
+    display_name AS displayName,
+    status,
+    last_activity_at AS lastActivityAt
+  FROM browser_research_clusters
+`;
+const VISITS_FOR_ROOT_QUERY = `
+  SELECT
+    root_task_id AS rootTaskId,
+    ts,
+    domain,
+    foreground_sec AS foregroundSec
+  FROM browser_visits
+  WHERE root_task_id = ? AND meaningful = 1 AND ts >= ? AND ts < ?
+`;
+const PENDING_OFFERS_QUERY = `
+  SELECT slug FROM browser_pending_offers WHERE expires_at > ?
+`;
+function emptyAggregate() {
+    return {
+        visits: 0,
+        foregroundSec: 0,
+        distinctDomains: new Set(),
+        domainForeground: new Map(),
+        daySet: new Set(),
+        lastTsInWindow: 0,
+    };
+}
+/**
+ * Sort the `clusters` array deterministically. Exported so the renderer
+ * tests can reuse the same ordering rule.
+ */
+export function pickTopClusters(clusters, maxClusters) {
+    // `sort` mutates, so copy first; production callers also pass the
+    // same array around between routes and tests.
+    const copy = [...clusters];
+    copy.sort((a, b) => {
+        if (b.meaningfulForegroundSec !== a.meaningfulForegroundSec) {
+            return b.meaningfulForegroundSec - a.meaningfulForegroundSec;
+        }
+        if (b.distinctMeaningfulDomains !== a.distinctMeaningfulDomains) {
+            return b.distinctMeaningfulDomains - a.distinctMeaningfulDomains;
+        }
+        return a.slug.localeCompare(b.slug);
+    });
+    return copy.slice(0, Math.max(0, maxClusters));
+}
+function aggregateClusterWindow(db, rootTaskId, startMs, endMs, boundary) {
+    const rows = db
+        .prepare(VISITS_FOR_ROOT_QUERY)
+        .all(rootTaskId, startMs, endMs);
+    const agg = emptyAggregate();
+    for (const row of rows) {
+        agg.visits += 1;
+        const fg = row.foregroundSec ?? 0;
+        agg.foregroundSec += fg;
+        agg.distinctDomains.add(row.domain);
+        agg.domainForeground.set(row.domain, (agg.domainForeground.get(row.domain) ?? 0) + fg);
+        agg.daySet.add(getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(row.ts)));
+        if (row.ts > agg.lastTsInWindow) {
+            agg.lastTsInWindow = row.ts;
+        }
+    }
+    return agg;
+}
+function topDomainsFromAggregate(agg) {
+    return [...agg.domainForeground.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, TOP_DOMAINS_CAP)
+        .map(([domain]) => domain);
+}
+export function buildWeeklyInterestsSummary(db, weekStart, options = {}) {
+    const boundary = options.boundary ?? DEFAULT_BOUNDARY;
+    const maxClusters = options.maxClusters ?? DEFAULT_MAX_CLUSTERS;
+    const maxProjectClusters = options.maxProjectClusters ?? DEFAULT_MAX_PROJECT_CLUSTERS;
+    const nowMs = options.nowMs ?? Date.now();
+    const { startMs: weekStartMs, endMs: weekEndMs } = weekWindowMs(weekStart, boundary);
+    const priorStartMs = weekStartMs - WEEK_MS;
+    const priorEndMs = weekStartMs;
+    const activeRows = db.prepare(ACTIVE_CLUSTERS_QUERY).all();
+    const openOfferSlugs = new Set(db.prepare(PENDING_OFFERS_QUERY).all(nowMs)
+        .map((r) => r.slug));
+    const builtClusters = [];
+    for (const row of activeRows) {
+        const windowAgg = aggregateClusterWindow(db, row.rootTaskId, weekStartMs, weekEndMs, boundary);
+        if (windowAgg.visits === 0)
+            continue;
+        const priorAgg = aggregateClusterWindow(db, row.rootTaskId, priorStartMs, priorEndMs, boundary);
+        const statusChange = priorAgg.visits === 0 ? "new" : "active_continued";
+        builtClusters.push({
+            slug: row.slug,
+            displayName: row.displayName,
+            daysActive: windowAgg.daySet.size,
+            meaningfulVisits: windowAgg.visits,
+            meaningfulForegroundSec: windowAgg.foregroundSec,
+            distinctMeaningfulDomains: windowAgg.distinctDomains.size,
+            topDomains: topDomainsFromAggregate(windowAgg),
+            status: row.status,
+            statusChange,
+            clusterJournalPath: `research/${row.slug}.md`,
+            hasOpenOffer: openOfferSlugs.has(row.slug),
+            hasAcceptedResearch: row.researchOfferAcceptedAt !== null,
+            hasWikiSummary: row.wikiSummaryWrittenAt !== null,
+            lastActivityDate: getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(windowAgg.lastTsInWindow)),
+            lastActivityMs: windowAgg.lastTsInWindow,
+        });
+    }
+    const clusters = pickTopClusters(builtClusters, maxClusters);
+    const currentSlugSet = new Set(clusters.map((c) => c.slug));
+    const dormantSinceLastWeek = [];
+    const allRows = db.prepare(ALL_CLUSTERS_QUERY).all();
+    for (const row of allRows) {
+        if (currentSlugSet.has(row.slug))
+            continue;
+        // Dormant means: had meaningful visits in [-2 wk, -1 wk) but none
+        // in the current window. Read the prior aggregate first as the
+        // cheaper gate, then short-circuit.
+        const priorAgg = aggregateClusterWindow(db, row.rootTaskId, priorStartMs, priorEndMs, boundary);
+        if (priorAgg.visits === 0)
+            continue;
+        // Defensive — the active path above already excluded clusters with
+        // window visits, but a non-active status (concluded, muted) could
+        // still have window visits while being absent from `currentSlugSet`
+        // (the active query filtered them out). Suppress those: a muted
+        // cluster shouldn't surface as "dormant" — it was deliberately
+        // silenced, not abandoned.
+        if (row.status !== "active" && row.status !== "dormant")
+            continue;
+        // Final check: zero visits in the CURRENT window. For a status
+        // that's still 'active' this is the dormancy definition; for a row
+        // already flipped to 'dormant' the prior-week presence is enough
+        // to surface it once.
+        const currentAgg = aggregateClusterWindow(db, row.rootTaskId, weekStartMs, weekEndMs, boundary);
+        if (currentAgg.visits > 0)
+            continue;
+        dormantSinceLastWeek.push({
+            slug: row.slug,
+            displayName: row.displayName,
+            // Use the agent-day label (boundary-aware) — `localDateStr` alone
+            // would mis-label a visit at 02:00 local as "today" when the
+            // 04:00 boundary places it in the previous agent-day.
+            lastActivity: getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(row.lastActivityAt)),
+            lastActivityMs: row.lastActivityAt,
+        });
+    }
+    dormantSinceLastWeek.sort((a, b) => b.lastActivityMs - a.lastActivityMs);
+    const projectMatches = [];
+    if (options.projectKeywords) {
+        for (const project of options.projectKeywords) {
+            const matched = matchClustersToProject(project, clusters, maxProjectClusters);
+            if (matched.length === 0)
+                continue;
+            projectMatches.push({
+                projectSlug: project.projectSlug,
+                projectPath: project.projectPath,
+                clusters: matched,
+            });
+        }
+        projectMatches.sort((a, b) => a.projectSlug.localeCompare(b.projectSlug));
+    }
+    // `weekEnd` is the agent-day label of the last day in the window.
+    // The window is half-open `[weekStartMs, weekEndMs)`; subtract a
+    // single minute (well inside the day) and round to the agent-day so
+    // the label is the same on both DST and non-DST zones.
+    const weekEnd = getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(weekEndMs - 60_000));
+    return {
+        weekStart,
+        weekEnd,
+        generatedAt: new Date(nowMs).toISOString(),
+        clusters,
+        dormantSinceLastWeek,
+        projectMatches,
+    };
+}

package/dist/services/browser-history/readers/chromium-reader.d.ts

@@ -0,0 +1,30 @@
+export interface ChromiumHistorySummary {
+    visitCount: number;
+    latestVisitTime: number | null;
+    hasContextAnnotations: boolean;
+}
+export interface ChromiumVisitRow {
+    visitId: number;
+    url: string;
+    title: string | null;
+    visitTimeMs: number;
+    transition: number;
+    rootTaskId: number | null;
+    foregroundSec: number | null;
+    durationSinceLastVisitSec: number | null;
+    httpStatus: number | null;
+    searchTerm: string | null;
+}
+export declare function assertChromiumHistorySchema(dbPath: string): ChromiumHistorySummary;
+export interface ReadChromiumVisitsOptions {
+    sinceMs: number;
+    limit: number;
+}
+/**
+ * Read Chromium visits newer than `sinceMs` from a previously snapshotted
+ * History database. Joins `urls`, `visits`, `context_annotations`, and
+ * `keyword_search_terms` so the caller receives a single denormalized row
+ * per visit. The reader gracefully degrades when `context_annotations`
+ * is absent (older Chromium builds and some forks).
+ */
+export declare function readChromiumVisits(dbPath: string, options: ReadChromiumVisitsOptions): ChromiumVisitRow[];

package/dist/services/browser-history/readers/chromium-reader.js

@@ -0,0 +1,139 @@
+import Database from "better-sqlite3";
+/**
+ * Chromium stores timestamps as microseconds since 1601-01-01 UTC.
+ * Convert to standard UNIX epoch milliseconds. Chromium-epoch zero is
+ * `11644473600000` ms before the UNIX epoch.
+ */
+const CHROMIUM_EPOCH_MS_OFFSET = 11_644_473_600_000;
+function chromiumTimeToMs(value) {
+    if (value === null || value === undefined)
+        return 0;
+    const numeric = typeof value === "bigint" ? Number(value) : value;
+    return Math.floor(numeric / 1000) - CHROMIUM_EPOCH_MS_OFFSET;
+}
+function msToChromiumTime(ms) {
+    return (ms + CHROMIUM_EPOCH_MS_OFFSET) * 1000;
+}
+function tableExists(db, name) {
+    const row = db
+        .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1")
+        .get(name);
+    return !!row;
+}
+function hasColumn(db, table, column) {
+    const rows = db.prepare(`PRAGMA table_info(${table})`).all();
+    return rows.some((row) => row.name === column);
+}
+export function assertChromiumHistorySchema(dbPath) {
+    const db = new Database(dbPath, {
+        readonly: true,
+        fileMustExist: true,
+    });
+    try {
+        if (!tableExists(db, "urls") || !tableExists(db, "visits")) {
+            throw new Error("missing required urls/visits tables");
+        }
+        for (const [table, column] of [
+            ["urls", "id"],
+            ["urls", "url"],
+            ["urls", "title"],
+            ["visits", "id"],
+            ["visits", "url"],
+            ["visits", "visit_time"],
+            ["visits", "transition"],
+        ]) {
+            if (!hasColumn(db, table, column)) {
+                throw new Error(`missing required column ${table}.${column}`);
+            }
+        }
+        const visitCountRow = db
+            .prepare("SELECT COUNT(*) AS count, MAX(visit_time) AS latest FROM visits")
+            .get();
+        const hasContextAnnotations = tableExists(db, "context_annotations")
+            && hasColumn(db, "context_annotations", "visit_id");
+        return {
+            visitCount: visitCountRow.count,
+            latestVisitTime: visitCountRow.latest,
+            hasContextAnnotations,
+        };
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Read Chromium visits newer than `sinceMs` from a previously snapshotted
+ * History database. Joins `urls`, `visits`, `context_annotations`, and
+ * `keyword_search_terms` so the caller receives a single denormalized row
+ * per visit. The reader gracefully degrades when `context_annotations`
+ * is absent (older Chromium builds and some forks).
+ */
+export function readChromiumVisits(dbPath, options) {
+    const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+    try {
+        const sinceChromiumTime = msToChromiumTime(Math.max(0, options.sinceMs));
+        const hasContextAnnotations = tableExists(db, "context_annotations")
+            && hasColumn(db, "context_annotations", "visit_id");
+        const hasKeywordSearch = tableExists(db, "keyword_search_terms");
+        const select = hasContextAnnotations
+            ? `
+          SELECT
+            v.id AS visit_id,
+            u.url AS url,
+            u.title AS title,
+            v.visit_time AS visit_time,
+            v.transition AS transition,
+            ca.root_task_id AS root_task_id,
+            ca.total_foreground_duration AS total_foreground_duration,
+            ca.duration_since_last_visit AS duration_since_last_visit,
+            ca.response_code AS response_code,
+            ${hasKeywordSearch ? "kst.term" : "NULL"} AS search_term
+          FROM visits v
+          INNER JOIN urls u ON u.id = v.url
+          LEFT JOIN context_annotations ca ON ca.visit_id = v.id
+          ${hasKeywordSearch ? "LEFT JOIN keyword_search_terms kst ON kst.url_id = u.id" : ""}
+          WHERE v.visit_time > ?
+          ORDER BY v.visit_time ASC
+          LIMIT ?
+        `
+            : `
+          SELECT
+            v.id AS visit_id,
+            u.url AS url,
+            u.title AS title,
+            v.visit_time AS visit_time,
+            v.transition AS transition,
+            NULL AS root_task_id,
+            NULL AS total_foreground_duration,
+            NULL AS duration_since_last_visit,
+            NULL AS response_code,
+            ${hasKeywordSearch ? "kst.term" : "NULL"} AS search_term
+          FROM visits v
+          INNER JOIN urls u ON u.id = v.url
+          ${hasKeywordSearch ? "LEFT JOIN keyword_search_terms kst ON kst.url_id = u.id" : ""}
+          WHERE v.visit_time > ?
+          ORDER BY v.visit_time ASC
+          LIMIT ?
+        `;
+        const rows = db.prepare(select).all(sinceChromiumTime, options.limit);
+        return rows.map((row) => ({
+            visitId: row.visit_id,
+            url: row.url,
+            title: row.title,
+            visitTimeMs: chromiumTimeToMs(row.visit_time),
+            transition: row.transition,
+            rootTaskId: row.root_task_id ?? null,
+            foregroundSec: row.total_foreground_duration === null || row.total_foreground_duration === undefined
+                ? null
+                : Math.max(0, Math.floor(Number(row.total_foreground_duration) / 1_000_000)),
+            durationSinceLastVisitSec: row.duration_since_last_visit === null || row.duration_since_last_visit === undefined
+                ? null
+                : Math.max(0, Math.floor(Number(row.duration_since_last_visit) / 1_000_000)),
+            httpStatus: row.response_code ?? null,
+            searchTerm: row.search_term ?? null,
+        }));
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/services/browser-history/readers/snapshot.d.ts

@@ -0,0 +1,19 @@
+export interface BrowserHistorySnapshot {
+    dir: string;
+    mainPath: string;
+    copiedWal: boolean;
+    copiedShm: boolean;
+    cleanup(): Promise<void>;
+}
+export declare function createBrowserHistorySnapshot(historyPath: string, cacheRoot: string): Promise<BrowserHistorySnapshot>;
+/**
+ * Best-effort boot-time cleanup of stale `history-*` snapshot directories
+ * left over from a previous daemon process that crashed before `cleanup()`
+ * could run. The directories are owner-only and contain only copies of
+ * browser SQLite files (themselves regenerated from the live profile on
+ * the next snapshot), so deleting them is safe.
+ *
+ * Returns the number of directories removed. Silently swallows fs errors
+ * — a write-failure here should never block daemon startup.
+ */
+export declare function cleanupStaleBrowserHistorySnapshots(cacheRoot: string): Promise<number>;