@aitne/daemon 0.1.7 → 0.1.9

package/dist/db/browser-history-store.d.ts

@@ -0,0 +1,231 @@
+import type Database from "better-sqlite3";
+import { type BrowserHistoryBrowserKey, type BrowserHistoryCapabilities, type BrowserHistoryClusterDetail, type BrowserHistoryLifecycleState, type BrowserHistoryOfferKind, type BrowserHistoryPendingOffer, type BrowserHistoryResearchClustersResponse, type YesterdayResearchSummary } from "@aitne/shared";
+import type { SummarizedVisit } from "../services/browser-history/pipeline/summarizer.js";
+import type { ExtractedCluster } from "../services/browser-history/pipeline/cluster-extractor.js";
+export declare const BROWSER_HISTORY_CAPABILITIES_STATE_KEY = "browser_history_capabilities";
+export declare const BROWSER_LIFECYCLE_STATE_KEY = "browser_lifecycle_state";
+export declare const BROWSER_HISTORY_LAST_INGEST_AT_KEY = "browser_history_last_ingest_at";
+export declare const BROWSER_HISTORY_INGEST_CURSORS_KEY = "browser_history_ingest_cursors";
+export declare function readBrowserHistoryCapabilities(db: Database.Database): BrowserHistoryCapabilities | null;
+export declare function writeBrowserHistoryCapabilities(db: Database.Database, value: BrowserHistoryCapabilities): void;
+export declare function readBrowserLifecycleState(db: Database.Database): BrowserHistoryLifecycleState;
+export declare function writeBrowserLifecycleState(db: Database.Database, value: BrowserHistoryLifecycleState): void;
+export declare function readBrowserHistoryLastIngestAt(db: Database.Database): number | null;
+export declare function writeBrowserHistoryLastIngestAt(db: Database.Database, value: number): void;
+export declare function listBrowserResearchClusters(db: Database.Database): BrowserHistoryResearchClustersResponse;
+export declare function getYesterdayResearchSummary(date: string): YesterdayResearchSummary;
+interface IngestCursorMap {
+    [profileKey: string]: number;
+}
+export declare function browserHistoryProfileCursorKey(browser: BrowserHistoryBrowserKey, profile: string): string;
+export declare function readBrowserHistoryIngestCursors(db: Database.Database): IngestCursorMap;
+export declare function readBrowserHistoryIngestCursor(db: Database.Database, browser: BrowserHistoryBrowserKey, profile: string): number;
+export declare function writeBrowserHistoryIngestCursor(db: Database.Database, browser: BrowserHistoryBrowserKey, profile: string, cursorMs: number): void;
+export interface InsertVisitsResult {
+    inserted: number;
+    duplicates: number;
+}
+export declare function insertBrowserVisits(db: Database.Database, visits: readonly SummarizedVisit[]): InsertVisitsResult;
+export interface ReloadIncrement {
+    date: string;
+    urlPattern: string;
+    count: number;
+}
+export declare function incrementReloadSignals(db: Database.Database, increments: readonly ReloadIncrement[]): void;
+export declare function upsertResearchClusters(db: Database.Database, clusters: readonly ExtractedCluster[], nowMs?: number): void;
+export interface ShoppingSessionInput {
+    date: string;
+    vendor: "amazon";
+    asinSet: readonly string[];
+    comparisonMinutes: number;
+    locale: string | null;
+}
+export declare function replaceShoppingSessions(db: Database.Database, date: string, sessions: readonly ShoppingSessionInput[]): void;
+export interface RetentionConfig {
+    visitRetentionDays: number;
+    searchQueryRetentionDays: number;
+}
+export interface ShoppingDateRow {
+    date: string;
+    vendor: "amazon";
+    asins: string[];
+    comparisonMinutes: number;
+    locale: string | null;
+}
+export declare function listShoppingSessionsForDate(db: Database.Database, date: string): ShoppingDateRow[];
+export interface ReloadEntryRow {
+    urlPattern: string;
+    reloadCount: number;
+}
+export declare function listReloadsForDate(db: Database.Database, date: string, limit?: number): ReloadEntryRow[];
+export interface ReloadWeeklyEntryRow extends ReloadEntryRow {
+    days: number;
+}
+export declare function listReloadsForRange(db: Database.Database, rangeStart: string, rangeEnd: string, limit?: number): ReloadWeeklyEntryRow[];
+interface ClusterDetailRow {
+    slug: string;
+    rootTaskId: number;
+    displayName: string;
+    startedAt: number;
+    lastActivityAt: number;
+    visitsTotal: number;
+    meaningfulVisitsTotal: number;
+    meaningfulForegroundSecTotal: number;
+    distinctMeaningfulDomains: number;
+    status: BrowserHistoryClusterDetail["status"];
+    agentSummaryRevision: number;
+    lastDmAt: number | null;
+    lastResearchOfferAt: number | null;
+    lastWikiOfferAt: number | null;
+    researchOfferAcceptedAt: number | null;
+    wikiSummaryWrittenAt: number | null;
+}
+/**
+ * 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 declare function getResearchClusterDetail(db: Database.Database, slug: string): ClusterDetailRow | 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 declare function listTopDomainsForCluster(db: Database.Database, rootTaskId: number, limit?: number): string[];
+export interface ClusterDailyDeltaRow {
+    date: string;
+    meaningfulVisits: number;
+    meaningfulForegroundSec: number;
+    newDomains: string[];
+}
+/**
+ * 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 declare function listClusterDailyDeltas(db: Database.Database, rootTaskId: number, boundary: {
+    timezone: string | undefined;
+    dayBoundaryHour: number;
+}, options?: {
+    sinceMs?: number;
+    dayLimit?: number;
+}): ClusterDailyDeltaRow[];
+/**
+ * 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 declare function stampClusterDmFields(db: Database.Database, slug: string, fields: {
+    lastDmAt?: number | null;
+    lastResearchOfferAt?: number | null;
+    lastWikiOfferAt?: number | null;
+    researchOfferAcceptedAt?: number | null;
+    wikiSummaryWrittenAt?: number | null;
+    statusOverride?: BrowserHistoryClusterDetail["status"];
+}): void;
+/**
+ * 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 declare function clearClusterOfferStamps(db: Database.Database, slug: string, fields: {
+    lastResearchOfferAt?: boolean;
+    lastWikiOfferAt?: boolean;
+}): void;
+/**
+ * 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 declare function setResearchClusterStatus(db: Database.Database, slug: string, status: BrowserHistoryClusterDetail["status"]): boolean;
+/**
+ * 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 declare function renameResearchCluster(db: Database.Database, slug: string, displayName: string): boolean;
+/**
+ * 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 declare function bumpClusterAgentSummaryRevision(db: Database.Database, slug: string): number;
+/**
+ * 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 declare function listClustersNeedingUpdate(db: Database.Database, lookbackMs: number, nowMs?: number, limit?: number): Array<{
+    slug: string;
+    displayName: string;
+}>;
+export declare const OFFER_DEFAULT_TTL_MS: number;
+export interface PendingOfferInput {
+    slug: string;
+    kind: BrowserHistoryOfferKind;
+    offeredAt: number;
+    expiresAt: number;
+}
+/**
+ * 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 declare function upsertPendingOffer(db: Database.Database, input: PendingOfferInput): void;
+export declare function deletePendingOffer(db: Database.Database, slug: string, kind: BrowserHistoryOfferKind): boolean;
+export declare function deletePendingOffersForCluster(db: Database.Database, slug: string): number;
+/**
+ * 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 declare function listPendingOffersWithDisplay(db: Database.Database, nowMs?: number): BrowserHistoryPendingOffer[];
+export declare function listPendingOffersForCluster(db: Database.Database, slug: string, nowMs?: number): BrowserHistoryPendingOffer[];
+export declare function applyBrowserHistoryRetention(db: Database.Database, retention: RetentionConfig, nowMs?: number): {
+    visitsDeleted: number;
+    searchQueriesCleared: number;
+};
+export {};