@aitne/daemon 0.1.7 → 0.1.9

package/dist/services/browser-history/pipeline/offer-rate-limit.js

@@ -0,0 +1,188 @@
+/**
+ * Global rate-limit gate for the seventh-pass two-option engagement
+ * offer flow (BROWSER_HISTORY_INTEGRATION_PLAN §5.F1 "Rate-limit
+ * policy"). Sits between `evaluateOfferTriggers` (per-cluster gates)
+ * and the poller's actual enqueue of a `routine.research_offer_dm`
+ * event.
+ *
+ * The policy:
+ *
+ * | Constraint               | Value                                     |
+ * |--------------------------|-------------------------------------------|
+ * | Global daily cap         | 2 offer DMs per agent-day (04:00→04:00)   |
+ * | Minimum interval         | 4 hours between any two offer DMs         |
+ * | Different topic          | Each offer must be for a different slug   |
+ * | Quiet hours              | Respect quietHoursStart / quietHoursEnd   |
+ * | Active conversation hold | Skip if the owner DM channel saw activity |
+ * |                          | within the last 30 minutes                |
+ * | Decline backoff          | Cluster cooldown extends to 30 days after |
+ * |                          | a decline reply                           |
+ *
+ * Pure-ish — reads SQLite, but does not write. Returns a discriminated
+ * union the poller logs and routes on:
+ *   `{decision: "fire"}` → enqueue routine.research_offer_dm
+ *   `{decision: "skip", reason: "..."}` → log and move on
+ *
+ * Quiet hours + decline backoff intentionally read from config /
+ * cluster rows rather than runtime_state — keep state in one place
+ * (clusters + config), reuse what already exists.
+ */
+export const DEFAULT_OFFER_RATE_LIMIT_CONFIG = {
+    globalDailyCap: 2,
+    minIntervalMs: 4 * 60 * 60 * 1000,
+    declineBackoffMs: 30 * 24 * 60 * 60 * 1000,
+    activeConversationWindowMs: 30 * 60 * 1000,
+    quietHoursStart: null,
+    quietHoursEnd: null,
+    timezone: "UTC",
+};
+/**
+ * Evaluate the gate. The poller calls this for each candidate slug
+ * before enqueueing. On `skip`, the poller logs an `agent_actions` row
+ * with `action_type='offer_dm_rate_limited'` so the operator can see
+ * *why* an offer was suppressed.
+ *
+ * The "decline backoff" gate looks for the cluster's own
+ * `lastResearchOfferAt`/`lastWikiOfferAt` being set within
+ * `declineBackoffMs` AND `researchOfferAcceptedAt`/`wikiSummaryWrittenAt`
+ * still null — i.e., we offered, the user did not accept (likely
+ * declined or ignored), so cool down longer.
+ */
+export function gateOfferRateLimit(db, candidateSlug, nowMs, config = DEFAULT_OFFER_RATE_LIMIT_CONFIG) {
+    // Quiet hours — cheapest check, do it first.
+    if (config.quietHoursStart
+        && config.quietHoursEnd
+        && isInQuietHours(nowMs, config.quietHoursStart, config.quietHoursEnd, config.timezone)) {
+        return { decision: "skip", reason: "quiet_hours" };
+    }
+    // Decline backoff per-cluster — query the candidate's own row.
+    const cluster = db
+        .prepare(`SELECT
+         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 = ?`)
+        .get(candidateSlug);
+    if (cluster) {
+        const isResearchDeclineActive = cluster.lastResearchOfferAt !== null
+            && cluster.researchOfferAcceptedAt === null
+            && nowMs - cluster.lastResearchOfferAt < config.declineBackoffMs;
+        const isWikiDeclineActive = cluster.lastWikiOfferAt !== null
+            && cluster.wikiSummaryWrittenAt === null
+            && nowMs - cluster.lastWikiOfferAt < config.declineBackoffMs;
+        if (isResearchDeclineActive && isWikiDeclineActive) {
+            return { decision: "skip", reason: "decline_backoff" };
+        }
+    }
+    // Global daily cap + interval + different topic — single SQL query
+    // against `last_dm_at` over the last 24h, ordered by recency. The
+    // index on `last_dm_at` keeps this O(log N + K) where K is the
+    // (small) number of recent fires.
+    const dayAgo = nowMs - 24 * 60 * 60 * 1000;
+    const recentFires = db
+        .prepare(`SELECT slug, last_dm_at AS lastDmAt
+       FROM browser_research_clusters
+       WHERE last_dm_at IS NOT NULL AND last_dm_at > ?
+       ORDER BY last_dm_at DESC`)
+        .all(dayAgo);
+    if (recentFires.length >= config.globalDailyCap) {
+        return { decision: "skip", reason: "daily_cap" };
+    }
+    if (recentFires.length > 0) {
+        const mostRecent = recentFires[0];
+        if (nowMs - mostRecent.lastDmAt < config.minIntervalMs) {
+            return { decision: "skip", reason: "interval" };
+        }
+        if (mostRecent.slug === candidateSlug) {
+            return { decision: "skip", reason: "same_topic" };
+        }
+        // Same-topic check also covers ANY of the recent fires having the
+        // same slug — not just the most recent — because the daily cap of
+        // 2 means we could have fired this same slug earlier in the day
+        // for a different signal. Don't double-DM the same cluster.
+        if (recentFires.some((row) => row.slug === candidateSlug)) {
+            return { decision: "skip", reason: "same_topic" };
+        }
+    }
+    // Active-conversation hold — look at the most recent message in the
+    // owner DM scope. The scope is determined by getConversationScope
+    // (`('owner_dm', 'owner')` for non-dashboard DMs), but the messages
+    // table query is simpler: any message in any of the owner DM
+    // sessions within the window counts as "active".
+    const activeWindowStart = nowMs - config.activeConversationWindowMs;
+    // SQLite stores message timestamps as ISO strings ('2026-05-20
+    // 14:30:00') via the default CURRENT_TIMESTAMP, so the comparison
+    // is lexicographic-safe — convert the threshold the same way.
+    const activeWindowIso = new Date(activeWindowStart)
+        .toISOString()
+        .slice(0, 19)
+        .replace("T", " ");
+    const recentDmActivity = db
+        .prepare(`SELECT 1
+       FROM messages m
+       JOIN conversation_sessions s ON m.session_id = s.id
+       WHERE s.scope = 'owner_dm' AND s.scope_key = 'owner'
+         AND m.timestamp > ?
+       LIMIT 1`)
+        .get(activeWindowIso);
+    if (recentDmActivity) {
+        return { decision: "skip", reason: "active_conversation" };
+    }
+    return { decision: "fire" };
+}
+/**
+ * Quiet hours arithmetic with timezone awareness. Supports both
+ * same-day windows ("09:00"–"22:00" = work-day-loud) and windows that
+ * cross midnight ("22:00"–"07:00" = sleep). Uses the JS Date API with
+ * Intl.DateTimeFormat to localise to the agent's timezone.
+ *
+ * Pure — no I/O. The caller passes a clock + config.
+ */
+export function isInQuietHours(nowMs, start, end, timezone) {
+    const startMinutes = parseHHMM(start);
+    const endMinutes = parseHHMM(end);
+    if (startMinutes === null || endMinutes === null)
+        return false;
+    if (startMinutes === endMinutes)
+        return false; // empty window
+    const tzNow = new Date(nowMs);
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        hour12: false,
+        hour: "2-digit",
+        minute: "2-digit",
+    }).formatToParts(tzNow);
+    let hour = 0;
+    let minute = 0;
+    for (const part of parts) {
+        if (part.type === "hour")
+            hour = Number(part.value) % 24;
+        if (part.type === "minute")
+            minute = Number(part.value);
+    }
+    const nowMinutes = hour * 60 + minute;
+    if (startMinutes < endMinutes) {
+        // Same-day window: [start, end).
+        return nowMinutes >= startMinutes && nowMinutes < endMinutes;
+    }
+    // Crosses midnight: in window if AFTER start OR BEFORE end.
+    return nowMinutes >= startMinutes || nowMinutes < endMinutes;
+}
+function parseHHMM(value) {
+    const match = /^(\d{1,2}):(\d{2})$/.exec(value);
+    if (!match)
+        return null;
+    const h = Number(match[1]);
+    const m = Number(match[2]);
+    // Defensive: the regex above only matches ASCII digits, so Number()
+    // always yields a finite integer here. Kept so a future regex tweak
+    // (e.g. accepting full-width digits) can't silently produce NaN.
+    /* c8 ignore next */
+    if (!Number.isFinite(h) || !Number.isFinite(m))
+        return null;
+    if (h < 0 || h > 23 || m < 0 || m > 59)
+        return null;
+    return h * 60 + m;
+}

package/dist/services/browser-history/pipeline/offer-triggers.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Offer-trigger evaluator — pure, deterministic qualification layer over
+ * a cluster's engagement-tracking state (last DM, last research/wiki
+ * offer wall-clocks, accept/decline flags). No LLM, no DB writes —
+ * caller (the browser-history poller) reads cluster rows + the latest
+ * aggregate, calls `evaluateOfferTriggers`, then (a) passes through
+ * the rate-limit gate (`offer-rate-limit.ts`), (b) inserts a
+ * `browser_pending_offers` row, and (c) enqueues a
+ * `routine.research_offer_dm` event with the returned OfferContext as
+ * event.data.
+ *
+ * Seventh-pass (BROWSER_HISTORY_INTEGRATION_PLAN.md §5.F1 — LLM-composed
+ * offer redesign). Previous passes returned a templated DM string;
+ * that is now composed by the `routine.research_offer_dm` agent
+ * directly from the OfferContext payload so the prose is natural-
+ * language-personalised. The qualification + rate-limit gates remain
+ * deterministic Node code.
+ *
+ * Signals exposed in the OfferContext:
+ *
+ *   - assist_eligible — cluster has ≥5 distinct meaningful eTLD+1
+ *     domains. The "research deeper" option is on the table.
+ *   - wiki_eligible — cluster has ≥10 long-read meaningful visits
+ *     (foreground ≥120s each) across ≥2 days. The "summarise" option
+ *     is on the table.
+ *   - day_3_first_mention — cluster has just crossed the 3-day / 20-
+ *     visit qualification threshold for the first time.
+ *   - stall_48h — ≥48h with no new meaningful visits in a cluster
+ *     that already had ≥3 active days.
+ *   - phase_shift — top-domain Jaccard distance vs. prior 7 days
+ *     exceeds 0.6 AND recent foreground ≥30min.
+ *
+ * Gating (returns null without further consideration):
+ *   - `status !== "active"` (muted / dormant / concluded).
+ *   - DM budget gate (≤1 DM per cluster per `dmBudgetMs`).
+ *   - Re-fire gate: the cluster has been offered the same option-set
+ *     within `offerRefireMs` (14 days) AND the user has not accepted
+ *     it yet (researchOfferAcceptedAt / wikiSummaryWrittenAt null).
+ *
+ * The poller's `offer-rate-limit.ts` adds GLOBAL gates (2/day cap,
+ * 4h interval, different topic per offer, quiet hours, active-
+ * conversation hold, decline backoff) on top of this per-cluster
+ * gate. Keep the two layers separate — per-cluster invariants are
+ * load-bearing for correctness; global rate limits are pacing.
+ */
+export interface ClusterEngagementSnapshot {
+    slug: string;
+    displayName: string;
+    status: "active" | "dormant" | "concluded" | "muted";
+    startedAt: number;
+    lastActivityAt: number;
+    meaningfulVisitsTotal: number;
+    meaningfulForegroundSecTotal: number;
+    distinctMeaningfulDomains: number;
+    distinctMeaningfulDays: number;
+    /** Count of meaningful visits with foreground_sec ≥ 120. Wiki gate. */
+    longReadVisits: number;
+    /** Distinct agent-days containing at least one long-read meaningful visit. */
+    longReadDays: number;
+    /** Foreground-sec sum over the most recent 7 agent-days. */
+    recentForegroundSec: number;
+    /** Set of distinct meaningful domains observed in the most recent 7 agent-days. */
+    recentDomains: ReadonlySet<string>;
+    /** Set of distinct meaningful domains observed in the prior 7 agent-days. */
+    priorDomains: ReadonlySet<string>;
+    /** Top eTLD+1 domains (≤5) ranked by meaningful-foreground time. */
+    topDomains: readonly string[];
+    lastDmAt: number | null;
+    lastResearchOfferAt: number | null;
+    lastWikiOfferAt: number | null;
+    researchOfferAcceptedAt: number | null;
+    wikiSummaryWrittenAt: number | null;
+}
+export interface OfferThresholds {
+    /** §5.F1 qualification. */
+    minDays: number;
+    minMeaningfulVisits: number;
+    minMeaningfulForegroundSec: number;
+    minDistinctDomains: number;
+    /** assist_eligible extra: ≥N distinct domains. */
+    researchAssistMinDomains: number;
+    /** wiki_eligible extras. */
+    wikiMinLongReadVisits: number;
+    wikiMinLongReadDays: number;
+    /** phase_shift extras. */
+    phaseShiftMinJaccardDistance: number;
+    phaseShiftMinForegroundSec: number;
+    /** stall_48h extra: minimum prior active-day count before stall is meaningful. */
+    stallMinActiveDays: number;
+    /** Cluster DM budget — 1 DM per `dmBudgetMs` per cluster. */
+    dmBudgetMs: number;
+    /** Per-offer re-fire window. */
+    offerRefireMs: number;
+    /** Stall trigger window. */
+    stallWindowMs: number;
+}
+export declare const DEFAULT_OFFER_THRESHOLDS: OfferThresholds;
+/**
+ * The payload the `routine.research_offer_dm` agent reads from
+ * `event.data`. Carries the cluster snapshot the LLM needs to compose
+ * the two-option offer DM. Pure data — no DM prose, no acceptance
+ * commands. The task-flow at
+ * `agent-assets/task-flows/routine.research_offer_dm.md` documents
+ * how this is consumed.
+ */
+export interface OfferContext {
+    slug: string;
+    displayName: string;
+    daysActive: number;
+    meaningfulVisits: number;
+    /** Total foreground reading time, rounded to 1 decimal place. */
+    foregroundHours: number;
+    /** eTLD+1 labels, regex-constrained at the schema layer. ≤5. */
+    topDomains: readonly string[];
+    distinctDomainsCount: number;
+    signals: {
+        assist_eligible: boolean;
+        wiki_eligible: boolean;
+        day_3_first_mention: boolean;
+        stall_48h: boolean;
+        phase_shift: boolean;
+    };
+}
+export interface OfferTriggerDecision {
+    /**
+     * The decision kind. Seventh-pass collapses the previous five
+     * trigger kinds into a single `engagement_candidate` — the LLM
+     * composes the framing from the `signals` payload, so the trigger
+     * kind no longer encodes the variation. Kept as a discriminated-
+     * union field so we can add additional kinds later without
+     * breaking the consumer.
+     */
+    kind: "engagement_candidate";
+    /** Cluster snapshot the offer DM agent reads from event.data. */
+    context: OfferContext;
+    /** Which offer-tracking columns to advance on the cluster row. */
+    stamp: {
+        dm: boolean;
+        researchOffer: boolean;
+        wikiOffer: boolean;
+    };
+    /**
+     * The kind to write into `browser_pending_offers`. Always
+     * `'offered'` for the two-option flow — the kind narrows to
+     * `'research_assist'` or `'wiki_summary'` only at accept time,
+     * inside the `/offers/<slug>/accept` endpoint.
+     */
+    pendingOfferKind: "offered";
+}
+export declare function evaluateOfferTriggers(snapshot: ClusterEngagementSnapshot, nowMs: number, thresholds?: OfferThresholds): OfferTriggerDecision | null;

package/dist/services/browser-history/pipeline/offer-triggers.js

@@ -0,0 +1,164 @@
+/**
+ * Offer-trigger evaluator — pure, deterministic qualification layer over
+ * a cluster's engagement-tracking state (last DM, last research/wiki
+ * offer wall-clocks, accept/decline flags). No LLM, no DB writes —
+ * caller (the browser-history poller) reads cluster rows + the latest
+ * aggregate, calls `evaluateOfferTriggers`, then (a) passes through
+ * the rate-limit gate (`offer-rate-limit.ts`), (b) inserts a
+ * `browser_pending_offers` row, and (c) enqueues a
+ * `routine.research_offer_dm` event with the returned OfferContext as
+ * event.data.
+ *
+ * Seventh-pass (BROWSER_HISTORY_INTEGRATION_PLAN.md §5.F1 — LLM-composed
+ * offer redesign). Previous passes returned a templated DM string;
+ * that is now composed by the `routine.research_offer_dm` agent
+ * directly from the OfferContext payload so the prose is natural-
+ * language-personalised. The qualification + rate-limit gates remain
+ * deterministic Node code.
+ *
+ * Signals exposed in the OfferContext:
+ *
+ *   - assist_eligible — cluster has ≥5 distinct meaningful eTLD+1
+ *     domains. The "research deeper" option is on the table.
+ *   - wiki_eligible — cluster has ≥10 long-read meaningful visits
+ *     (foreground ≥120s each) across ≥2 days. The "summarise" option
+ *     is on the table.
+ *   - day_3_first_mention — cluster has just crossed the 3-day / 20-
+ *     visit qualification threshold for the first time.
+ *   - stall_48h — ≥48h with no new meaningful visits in a cluster
+ *     that already had ≥3 active days.
+ *   - phase_shift — top-domain Jaccard distance vs. prior 7 days
+ *     exceeds 0.6 AND recent foreground ≥30min.
+ *
+ * Gating (returns null without further consideration):
+ *   - `status !== "active"` (muted / dormant / concluded).
+ *   - DM budget gate (≤1 DM per cluster per `dmBudgetMs`).
+ *   - Re-fire gate: the cluster has been offered the same option-set
+ *     within `offerRefireMs` (14 days) AND the user has not accepted
+ *     it yet (researchOfferAcceptedAt / wikiSummaryWrittenAt null).
+ *
+ * The poller's `offer-rate-limit.ts` adds GLOBAL gates (2/day cap,
+ * 4h interval, different topic per offer, quiet hours, active-
+ * conversation hold, decline backoff) on top of this per-cluster
+ * gate. Keep the two layers separate — per-cluster invariants are
+ * load-bearing for correctness; global rate limits are pacing.
+ */
+export const DEFAULT_OFFER_THRESHOLDS = {
+    minDays: 3,
+    minMeaningfulVisits: 20,
+    minMeaningfulForegroundSec: 3600,
+    minDistinctDomains: 3,
+    researchAssistMinDomains: 5,
+    wikiMinLongReadVisits: 10,
+    wikiMinLongReadDays: 2,
+    phaseShiftMinJaccardDistance: 0.6,
+    phaseShiftMinForegroundSec: 30 * 60,
+    stallMinActiveDays: 3,
+    dmBudgetMs: 7 * 24 * 60 * 60 * 1000,
+    offerRefireMs: 14 * 24 * 60 * 60 * 1000,
+    stallWindowMs: 48 * 60 * 60 * 1000,
+};
+function qualifies(snapshot, thresholds) {
+    return (snapshot.distinctMeaningfulDays >= thresholds.minDays
+        && snapshot.meaningfulVisitsTotal >= thresholds.minMeaningfulVisits
+        && snapshot.meaningfulForegroundSecTotal
+            >= thresholds.minMeaningfulForegroundSec
+        && snapshot.distinctMeaningfulDomains >= thresholds.minDistinctDomains);
+}
+function jaccardDistance(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    const intersect = new Set();
+    for (const item of a)
+        if (b.has(item))
+            intersect.add(item);
+    const union = new Set([...a, ...b]);
+    return 1 - intersect.size / union.size;
+}
+/**
+ * Build the OfferContext payload from the cluster snapshot. Pure —
+ * inputs in, payload out. Foreground time is rounded for human
+ * readability (the LLM presents "2.1h", not "7521.3 seconds").
+ */
+function buildOfferContext(snapshot, signals) {
+    return {
+        slug: snapshot.slug,
+        displayName: snapshot.displayName,
+        daysActive: snapshot.distinctMeaningfulDays,
+        meaningfulVisits: snapshot.meaningfulVisitsTotal,
+        foregroundHours: Math.round((snapshot.meaningfulForegroundSecTotal / 3600) * 10) / 10,
+        topDomains: snapshot.topDomains.slice(0, 5),
+        distinctDomainsCount: snapshot.distinctMeaningfulDomains,
+        signals,
+    };
+}
+export function evaluateOfferTriggers(snapshot, nowMs, thresholds = DEFAULT_OFFER_THRESHOLDS) {
+    // Hard skips — never fire for these statuses regardless of qualification.
+    if (snapshot.status !== "active")
+        return null;
+    // Per-cluster DM budget gate. The global `offer-rate-limit.ts`
+    // applies on top of this; both must say "go". The per-cluster
+    // budget exists to bound how often any single cluster can ping the
+    // user even if the global cap allows more total offers in the day.
+    if (snapshot.lastDmAt !== null
+        && nowMs - snapshot.lastDmAt < thresholds.dmBudgetMs) {
+        return null;
+    }
+    // Compute signals. None of these throw the decision away on its own;
+    // we collect them all and ask whether any "engagement option" is on
+    // the table. The LLM colours the offer DM from the signal flags.
+    const isQualified = qualifies(snapshot, thresholds);
+    const assistEligible = isQualified
+        && snapshot.distinctMeaningfulDomains >= thresholds.researchAssistMinDomains
+        && snapshot.researchOfferAcceptedAt === null
+        && (snapshot.lastResearchOfferAt === null
+            || nowMs - snapshot.lastResearchOfferAt >= thresholds.offerRefireMs);
+    const wikiEligible = isQualified
+        && snapshot.longReadVisits >= thresholds.wikiMinLongReadVisits
+        && snapshot.longReadDays >= thresholds.wikiMinLongReadDays
+        && snapshot.wikiSummaryWrittenAt === null
+        && (snapshot.lastWikiOfferAt === null
+            || nowMs - snapshot.lastWikiOfferAt >= thresholds.offerRefireMs);
+    const day3FirstMention = isQualified && snapshot.lastDmAt === null;
+    const stall48h = snapshot.lastDmAt !== null
+        && snapshot.distinctMeaningfulDays >= thresholds.stallMinActiveDays
+        && nowMs - snapshot.lastActivityAt >= thresholds.stallWindowMs;
+    const phaseShift = snapshot.lastDmAt !== null
+        && snapshot.recentForegroundSec >= thresholds.phaseShiftMinForegroundSec
+        && jaccardDistance(snapshot.recentDomains, snapshot.priorDomains)
+            >= thresholds.phaseShiftMinJaccardDistance;
+    // At least one path to engagement must be open. If neither assist
+    // nor wiki is eligible, day_3_first_mention alone DOES still
+    // qualify (it's "I notice you're researching X — what's the
+    // thread?" — no option offered, just an opener). Stall / phase_shift
+    // also fire bare reminders. Without any signal, no DM.
+    const anySignal = assistEligible
+        || wikiEligible
+        || day3FirstMention
+        || stall48h
+        || phaseShift;
+    if (!anySignal)
+        return null;
+    const signals = {
+        assist_eligible: assistEligible,
+        wiki_eligible: wikiEligible,
+        day_3_first_mention: day3FirstMention,
+        stall_48h: stall48h,
+        phase_shift: phaseShift,
+    };
+    return {
+        kind: "engagement_candidate",
+        context: buildOfferContext(snapshot, signals),
+        stamp: {
+            dm: true,
+            // Only stamp the per-option re-fire window when the option was
+            // actually on the table this fire. If only stall_48h fired
+            // (no assist / wiki options offered), neither stamp should
+            // advance — the option re-fire window must reflect "we asked
+            // you about this option", not "we sent any DM at all".
+            researchOffer: assistEligible,
+            wikiOffer: wikiEligible,
+        },
+        pendingOfferKind: "offered",
+    };
+}

package/dist/services/browser-history/pipeline/pre-morning-digest.d.ts

@@ -0,0 +1,118 @@
+import type Database from "better-sqlite3";
+import { type PreMorningDigest } from "@aitne/shared";
+/**
+ * BROWSER_HISTORY_INTEGRATION_PLAN §5.F2 Stage 1 — deterministic
+ * pre-morning digest builder. Runs at `day_boundary − 60min` (default
+ * 03:00 when `dayBoundaryHour=4`) and writes a static markdown file the
+ * morning Stage B journal session reads from disk.
+ *
+ * Two responsibilities, deliberately separated:
+ *
+ * 1. `buildPreMorningDigest` — pure Node aggregation over the daemon's
+ *    SQLite. No I/O outside the DB, no LLM, no network. Returns a
+ *    Zod-validated `PreMorningDigest` payload. Same payload is served
+ *    by `GET /api/browser-history/pre-morning-digest/{date}` as the
+ *    JSON fallback for §10.6 step 5 ("digest file missing → API").
+ *
+ * 2. `renderPreMorningDigestMarkdown` — pure templating from the typed
+ *    payload to markdown bytes. The journal Stage B task-flow reads
+ *    this rendered file; the structured payload is also exposed via
+ *    the API for any future caller that wants the typed shape.
+ *
+ * Layer 1 invariants preserved by both halves:
+ *   - The `topic` / `displayName` constraint matches the existing
+ *     `yesterdayResearchSummary.topic` regex (`[a-z0-9 /-]+`/i, ≤80
+ *     chars). Any cluster `display_name` outside that shape (e.g. a
+ *     user-renamed cluster carrying punctuation) is run through
+ *     `sanitizeTopic` so the schema parse cannot fail at digest time.
+ *   - `topDomains` are eTLD+1 labels read from
+ *     `pipeline/redactor.ts`-normalised `browser_visits.domain` —
+ *     never raw URLs.
+ *   - Reload `urlPattern` is `<domain>/<first-path-segment>` from
+ *     `pipeline/reload-detector.ts`. The `.max(180)` schema cap pins
+ *     the surface in case the upstream extractor ever drifts.
+ *   - No `search_query`, no `urls.title`, no full URL appears in the
+ *     output. This is the "prompt-injection blast radius" boundary
+ *     §6 calls Layer 1.
+ */
+/**
+ * Cluster activity inside the digest window — driven by a single SQL
+ * pass over `browser_visits` joined with `browser_research_clusters`.
+ * Bounded by `maxClusters` so an attacker-shaped cluster fan-out
+ * cannot balloon the morning context. Default 12 matches the schema's
+ * `clusters.max(12)`.
+ */
+interface BuildOptions {
+    /** Override "now" for deterministic tests. Defaults to `Date.now()`. */
+    readonly nowMs?: number;
+    readonly maxClusters?: number;
+    readonly maxShopping?: number;
+    readonly maxReloads?: number;
+    readonly maxPendingOffers?: number;
+}
+export interface DigestBoundary {
+    /** IANA timezone string, e.g. "Asia/Tokyo". `undefined` means UTC. */
+    readonly timezone: string | undefined;
+    /** Hour the agent-day starts (0–23). Default 4 across the project. */
+    readonly dayBoundaryHour: number;
+}
+/**
+ * Convert the agent-day date that the digest summarises ("yesterday's
+ * agent-day") into the UTC `[startMs, endMs)` window used to filter
+ * `browser_visits.ts`. Pure helper so the date math lives next to the
+ * builder rather than ad-hoc inside the SQL string.
+ */
+export declare function digestWindowMs(dateStr: string, boundary: DigestBoundary): {
+    startMs: number;
+    endMs: number;
+};
+/**
+ * Resolve "the agent-day this digest is being built for" from a wall
+ * clock. The cron fires at `dayBoundaryHour − 1` local time — still
+ * inside the agent-day that is *just about to roll over* — so the
+ * helper returns that current agent-day's date string.
+ */
+export declare function digestDateForNow(boundary: DigestBoundary, nowMs: number): string;
+/**
+ * Project a free-form cluster display-name onto the `[a-z0-9 /-]+`
+ * shape the schema demands. Already-conforming values pass through
+ * unchanged; punctuation / unicode / control characters collapse to
+ * single hyphens; trailing hyphens are trimmed; capped at 80 chars.
+ *
+ * Exported for tests and for the route layer's defensive re-projection
+ * (if a user-renamed cluster row ever drifts past validation, the
+ * digest builder still produces a coherent file).
+ */
+export declare function sanitizeTopic(displayName: string): string;
+export interface BuildPreMorningDigestArgs {
+    readonly db: Database.Database;
+    /** Agent-day the digest summarises (e.g. yesterday). YYYY-MM-DD. */
+    readonly date: string;
+    readonly boundary: DigestBoundary;
+    readonly options?: BuildOptions;
+}
+/**
+ * Build the typed `PreMorningDigest` payload for one agent-day. Pure
+ * over the DB handle and the supplied date/boundary/`nowMs`. The
+ * result is Zod-validated before return so a future schema tightening
+ * fails loud rather than producing a malformed file.
+ */
+export declare function buildPreMorningDigest(args: BuildPreMorningDigestArgs): PreMorningDigest;
+/**
+ * Render the typed digest to the markdown file the morning Stage B
+ * journal reads. The format mirrors the §5.F2 sample digest 1:1 — same
+ * frontmatter keys, same section ordering — and is intentionally
+ * minimal: structured data, neutral language, no LLM-style framing.
+ *
+ * The journal author re-frames this into prose; the file's job is to
+ * be a faithful snapshot, not to be readable on its own.
+ */
+export declare function renderPreMorningDigestMarkdown(digest: PreMorningDigest): string;
+/**
+ * The `context/...` relative path the morning journal task-flow reads.
+ * Lives under the new `browser/` subdirectory of the context root so
+ * the agent's existing `GET /api/context/<path>` chokepoint serves it
+ * with no new auth surface needed.
+ */
+export declare function preMorningDigestRelativePath(dateStr: string): string;
+export {};