@aitne/daemon 0.1.8 → 0.1.9

package/dist/services/browser-history/pipeline/interests-block.js

@@ -0,0 +1,333 @@
+/**
+ * WEEKLY_INTERESTS_REFLECTION_PLAN.md §8 + §10.3 — pure templating +
+ * delimited-block replacement for the four reflection target files.
+ *
+ * Two write modes (per §8):
+ *
+ * - **Mode A** — embed a `<!-- BEGIN aitne:browser-interests v1 … --> …
+ *   <!-- END … -->` block in a file that has user-authored content
+ *   (`identity/profile.md`, `identity/_index.md`, `projects/<slug>.md`). The
+ *   block is replaced in place on every refresh; if absent, it's
+ *   appended once with a leading blank line so it never welds onto the
+ *   prior section.
+ *
+ * - **Mode B** — wholly daemon-owned rewrite of `user/research-themes.md`.
+ *   The frontmatter declares `owner: aitne-browser-history`; the entire
+ *   file is regenerated each pass.
+ *
+ * All renderers are pure functions of typed inputs (`WeeklyInterestsSummary`
+ * + ancillary). No DB, no FS, no LLM. Markdown- and HTML-comment-significant
+ * characters in cluster `displayName`s are escaped by `escapeForMd` /
+ * `escapeForHtmlComment` so a poisoned cluster name cannot break the block
+ * delimiters or inject markdown structure.
+ */
+const BEGIN_MARKER = "<!-- BEGIN aitne:browser-interests v1";
+const END_MARKER = "<!-- END aitne:browser-interests v1";
+/**
+ * Escape characters that would otherwise (a) break markdown link
+ * brackets, (b) close the auto-block's HTML comment delimiter, or (c)
+ * inject markdown headings into a bullet body.
+ *
+ * The transform is one-way (lossy on `]`/backticks/`#`) — these are
+ * agent-visible substitutions, not data the user is meant to read out
+ * of the auto-block. Cluster display names are usually short
+ * lowercase-with-hyphens identifiers, so escaping is a no-op in
+ * practice; the transform is the safety net for renamed clusters that
+ * a user could push punctuation into.
+ */
+export function escapeForMd(value) {
+    const intermediate = value
+        // collapse the HTML-comment closer before anything else so a
+        // cluster name like "x --> oops" cannot pass through
+        .replace(/-->/g, "-→")
+        .replace(/`/g, "'")
+        .replace(/\]/g, ")")
+        .replace(/\[/g, "(")
+        // Heading characters at line start would inject H1-H6 inside a
+        // bullet. The transform of `#` → `＃` (fullwidth) preserves visual
+        // intent without giving markdown a syntax handle.
+        .replace(/(^|\n)#/g, "$1＃")
+        .replace(/[\r\n]+/g, " ")
+        .trim();
+    // The trim-then-collapse pipeline above misses one shape: when the
+    // input was `<non-newline whitespace>#…` (`" #x"`, `"\t#x"`, `"\r#x"`),
+    // `(^|\n)#` did not match (the leading char was neither `^` nor `\n`),
+    // `[\r\n]+` only consumed `\r`s, and `.trim()` then ate the remaining
+    // leading whitespace — leaving a literal `#` at byte 0 of the output.
+    // After the prior cleanup steps the result is a single trimmed line,
+    // so a final pass that defangs any surviving leading `#` is sufficient
+    // and preserves all prior defences (mid-line `#` stays plain text;
+    // headings post-collapse can only live at position 0).
+    return intermediate.startsWith("#")
+        ? `＃${intermediate.slice(1)}`
+        : intermediate;
+}
+/**
+ * Per the §8 invariant, BEGIN-line attributes must not contain `-->`.
+ * We're not embedding user content inside attributes today (only
+ * `weekStart`, `generatedAt`, etc. — daemon-controlled), but project
+ * disambiguators come from filenames and could in principle contain a
+ * `-`. Strip anything that would terminate the comment early.
+ *
+ * Exported so the writer (which independently computes the strip-time
+ * regex) can apply the identical transform — otherwise the strip path
+ * for a slug containing `-->` would never match the render path.
+ */
+export function escapeForHtmlComment(value) {
+    return value.replace(/-->/g, "-→");
+}
+/**
+ * Format a cluster's foreground seconds as a compact hour figure for
+ * the bullet body: `~3.2h` / `~38min` / `~12sec`.
+ */
+export function formatHoursCompact(sec) {
+    if (sec >= 3600)
+        return `~${(sec / 3600).toFixed(1)}h`;
+    if (sec >= 60)
+        return `~${Math.round(sec / 60)}min`;
+    if (sec > 0)
+        return `~${sec}sec`;
+    return "0sec";
+}
+/**
+ * Format a cluster's bullet line for `profile.md` / project files.
+ * Single line, ~10-15 tokens, links to the cluster journal at a
+ * compact relative path. Numeric fields come straight from
+ * `ClusterSnapshot`, so the bullet is the same byte-for-byte across
+ * runs.
+ */
+function renderClusterBullet(cluster) {
+    const name = escapeForMd(cluster.displayName);
+    const time = formatHoursCompact(cluster.meaningfulForegroundSec);
+    return (`- **${name}** — ${cluster.daysActive} day${cluster.daysActive === 1 ? "" : "s"}, `
+        + `${cluster.meaningfulVisits} source${cluster.meaningfulVisits === 1 ? "" : "s"}, `
+        + `${time} → \`${cluster.clusterJournalPath}\``);
+}
+/**
+ * Render the `## Current research themes (auto)` block bytes for
+ * `identity/profile.md`.
+ *
+ * Inputs:
+ * - `clusters`: the post-`selectProfileMdThemes` list (3-7 entries).
+ * - `weekStart` / `generatedAt`: attribute metadata for the BEGIN line.
+ *
+ * Output: full block text, including BEGIN/END markers. The caller
+ * pastes this directly into the file via `replaceAutoBlock`.
+ */
+export function renderProfileBlock(args) {
+    const bullets = args.clusters.map(renderClusterBullet).join("\n");
+    return [
+        `${BEGIN_MARKER} weekStart=${args.weekStart} generatedAt=${args.generatedAt} -->`,
+        `## Current research themes (auto)`,
+        ``,
+        `_Auto-refreshed each weekly review. Full snapshot in \`user/research-themes.md\`._`,
+        ``,
+        bullets,
+        ``,
+        `${END_MARKER} -->`,
+    ].join("\n");
+}
+/**
+ * Render the per-project annotation block for `projects/<slug>.md`.
+ * Returns `null` when there are no matched clusters — the caller
+ * removes any pre-existing block in that case rather than writing an
+ * empty "no matches this week" placeholder (noise, per §7.3).
+ */
+export function renderProjectBlock(args) {
+    if (args.clusters.length === 0)
+        return null;
+    const slug = escapeForHtmlComment(args.projectSlug);
+    const bullets = args.clusters
+        .map((cluster) => {
+        const name = escapeForMd(cluster.displayName);
+        const time = formatHoursCompact(cluster.meaningfulForegroundSec);
+        return (`- **${name}** (\`${cluster.slug}\`) — `
+            + `${cluster.daysActive} day${cluster.daysActive === 1 ? "" : "s"}, `
+            + `${cluster.meaningfulVisits} source${cluster.meaningfulVisits === 1 ? "" : "s"}, `
+            + `${time}. [Cluster journal](../research/${cluster.slug}.md)`);
+    })
+        .join("\n");
+    return [
+        `${BEGIN_MARKER} project=${slug} weekStart=${args.weekStart} generatedAt=${args.generatedAt} -->`,
+        `## Related browser research (auto, refreshed weekly)`,
+        ``,
+        `This week's browser activity related to **${escapeForMd(args.projectSlug)}**:`,
+        ``,
+        bullets,
+        ``,
+        `${END_MARKER} project=${slug} -->`,
+    ].join("\n");
+}
+/**
+ * Render the one-line `_index.md` entry pointing at
+ * `research-themes.md`. Same Mode-A delimited-block convention, with
+ * the disambiguator `target=research-themes`.
+ */
+export function renderIndexEntryBlock(args) {
+    const dateOnly = args.generatedAt.slice(0, 10);
+    return [
+        `${BEGIN_MARKER} target=research-themes -->`,
+        `- \`research-themes.md\` — Auto-generated weekly snapshot of current research themes from browser activity. Last refreshed: ${dateOnly}.`,
+        `${END_MARKER} target=research-themes -->`,
+    ].join("\n");
+}
+/**
+ * Render the wholly-owned `user/research-themes.md` file (Mode B).
+ * Includes frontmatter, full cluster list (up to 20 entries), and the
+ * "Dormant since last week" tail.
+ */
+export function renderResearchThemesFile(summary) {
+    const generatedDate = summary.generatedAt.slice(0, 10);
+    const lines = [];
+    lines.push(`---`);
+    lines.push(`type: user`);
+    lines.push(`owner: aitne-browser-history`);
+    lines.push(`updated: ${generatedDate}`);
+    lines.push(`generated_at: ${summary.generatedAt}`);
+    lines.push(`week_start: ${summary.weekStart}`);
+    lines.push(`week_end: ${summary.weekEnd}`);
+    lines.push(`clusters_active: ${summary.clusters.length}`);
+    lines.push(`clusters_dormant_since_last_week: ${summary.dormantSinceLastWeek.length}`);
+    lines.push(`---`);
+    lines.push(``);
+    lines.push(`# Research themes — week of ${summary.weekStart}`);
+    lines.push(``);
+    lines.push(`<!-- Daemon-owned. Manual edits are overwritten by the next weekly_review pass. -->`);
+    lines.push(``);
+    lines.push(`## Active themes`);
+    lines.push(``);
+    if (summary.clusters.length === 0) {
+        lines.push(`_No active research themes this week. The reflection will refresh once browser activity resumes._`);
+        lines.push(``);
+    }
+    else {
+        for (const cluster of summary.clusters) {
+            lines.push(renderActiveClusterSection(cluster));
+            lines.push(``);
+        }
+    }
+    lines.push(`## Dormant since last week`);
+    lines.push(``);
+    if (summary.dormantSinceLastWeek.length === 0) {
+        lines.push(`_No themes went dormant this week._`);
+        lines.push(``);
+    }
+    else {
+        lines.push(`These themes appeared in last week's snapshot but had no meaningful activity in the past 7 days:`);
+        lines.push(``);
+        for (const dormant of summary.dormantSinceLastWeek) {
+            lines.push(renderDormantBullet(dormant));
+        }
+        lines.push(``);
+    }
+    return lines.join("\n");
+}
+function renderActiveClusterSection(cluster) {
+    const name = escapeForMd(cluster.displayName);
+    const time = formatHoursCompact(cluster.meaningfulForegroundSec);
+    const topDomains = cluster.topDomains.length > 0
+        ? cluster.topDomains.map(escapeForMd).join(", ")
+        : "_(no domain data)_";
+    const statusLine = cluster.statusChange === "new"
+        ? "new this week"
+        : "active (continued)";
+    return [
+        `### ${name} (\`${cluster.slug}\`)`,
+        `- **Days active**: ${cluster.daysActive}`,
+        `- **Meaningful visits**: ${cluster.meaningfulVisits}`,
+        `- **Foreground time**: ${time}`,
+        `- **Top domains**: ${topDomains}`,
+        // Drop the `context/` prefix from the display text. The link target
+        // stays `../<clusterJournalPath>` (relative to
+        // `user/research-themes.md`, so it correctly resolves to
+        // `context/research/<slug>.md`); the visible text matches the
+        // path the user would actually navigate to in the vault root.
+        // Earlier drafts (§7.2 sample) had a redundant `context/` prefix
+        // in the display text that didn't match any real on-disk path.
+        `- **Cluster journal**: [${cluster.clusterJournalPath}](../${cluster.clusterJournalPath})`,
+        `- **Last week's status**: ${statusLine}`,
+    ].join("\n");
+}
+function renderDormantBullet(dormant) {
+    const name = escapeForMd(dormant.displayName);
+    return `- **${name}** (\`${dormant.slug}\`) — last activity ${dormant.lastActivity}`;
+}
+/**
+ * Match BEGIN/END markers, with optional disambiguator. The pattern is
+ * non-greedy across newlines (`[^]*?`) so back-to-back blocks in a
+ * pathological file don't get fused.
+ *
+ * **Prefix-collision guard**: the BEGIN side requires a literal space
+ * after the disambiguator, which is always present in the renderer
+ * output (`project=<slug> weekStart=...` or `target=research-themes
+ * -->`). Without the trailing space, searching for `project=aitne`
+ * would prefix-match a `project=aitne-foo` BEGIN line and — when a
+ * shorter-slug END appears later in the file — fuse multiple blocks
+ * into a single replacement.
+ */
+function buildBlockRegex(disambiguator) {
+    if (disambiguator !== null) {
+        const escaped = disambiguator.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        return new RegExp(`${escapeRegex(BEGIN_MARKER)} ${escaped} [^]*?${escapeRegex(END_MARKER)} ${escaped} -->`, "m");
+    }
+    // For the unscoped profile.md block, the disambiguator is `weekStart=…`
+    // — match BEGIN_MARKER through END_MARKER without a trailing
+    // disambiguator on the close.
+    return new RegExp(`${escapeRegex(BEGIN_MARKER)}[^]*?${escapeRegex(END_MARKER)} -->`, "m");
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Replace an existing `aitne:browser-interests v1` auto-block in
+ * `fileContent`, or append `newBlockContent` to the end of the file if
+ * no matching block exists.
+ *
+ * `disambiguator` is the `target=…` / `project=…` attribute that
+ * appears on both BEGIN and END lines, for `_index.md` and project
+ * files. Pass `null` for `profile.md` where the block is unique.
+ *
+ * On append, the helper ensures exactly one blank line between the
+ * prior file content and the new block, regardless of whether the file
+ * ended in `\n` or `\n\n`. This keeps the diff minimal across runs.
+ */
+export function replaceAutoBlock(fileContent, newBlockContent, disambiguator = null) {
+    const pattern = buildBlockRegex(disambiguator);
+    if (pattern.test(fileContent)) {
+        return fileContent.replace(pattern, newBlockContent);
+    }
+    // Append. Normalise the trailing whitespace so the inserted block
+    // always sits two newlines below the prior content.
+    const trimmedTail = fileContent.replace(/\s*$/, "");
+    const separator = trimmedTail.length === 0 ? "" : "\n\n";
+    return `${trimmedTail}${separator}${newBlockContent}\n`;
+}
+/**
+ * Strip every `aitne:browser-interests v1` auto-block from
+ * `fileContent`, including any disambiguator. Used by the cleanup
+ * endpoint.
+ *
+ * Returns `{ content, blocksRemoved }`. `blocksRemoved === 0` is
+ * idempotent — the caller can safely re-invoke without an error.
+ */
+export function stripAllAutoBlocks(fileContent) {
+    let blocksRemoved = 0;
+    let content = fileContent;
+    // Greedy strip — the `(?: \S+=\S+)*` BEGIN-attribute glob plus the
+    // optional END-disambiguator covers `target=…`, `project=…`, the
+    // weekStart/generatedAt attributes (which appear on BEGIN only), and
+    // any future attribute we add to the BEGIN line without an END
+    // counterpart.
+    const pattern = new RegExp(`${escapeRegex(BEGIN_MARKER)}[^]*?${escapeRegex(END_MARKER)}(?: [^>]*?)? -->\\s*`, "m");
+    while (pattern.test(content)) {
+        content = content.replace(pattern, "");
+        blocksRemoved += 1;
+    }
+    // Restore one trailing newline if the original had one and we ate it.
+    if (fileContent.length > 0
+        && fileContent.endsWith("\n")
+        && !content.endsWith("\n")) {
+        content += "\n";
+    }
+    return { content, blocksRemoved };
+}

package/dist/services/browser-history/pipeline/meaningful-filter.d.ts

@@ -0,0 +1,47 @@
+import type { BrowserHistoryCategory } from "@aitne/shared";
+export interface MeaningfulCandidate {
+    scheme: string;
+    host: string;
+    path: string;
+    category: BrowserHistoryCategory;
+    foregroundSeconds: number | null;
+}
+/**
+ * BROWSER_HISTORY_INTEGRATION_PLAN §5.F1.meaningful rule 6 — user-curated
+ * domain allowlist / denylist for the meaningful-research filter. Both
+ * default to an empty `Set`. When the allowlist is non-empty, the filter
+ * switches to "allowlist-only" mode: a visit is meaningful only if its
+ * eTLD+1 is in the allowlist AND it passes rules 1-5. The denylist is
+ * always-on and wins over the allowlist (defensive — explicit deny
+ * always denies). Entries must already be normalized to eTLD+1 by the
+ * caller; `normalizeResearchDomain` does that work for raw user input.
+ */
+export interface ResearchDomainLists {
+    allowlist: ReadonlySet<string>;
+    denylist: ReadonlySet<string>;
+}
+export declare const EMPTY_RESEARCH_DOMAIN_LISTS: ResearchDomainLists;
+export type MeaningfulReason = "scheme_blocked" | "category_blocked" | "path_denied" | "below_dwell_threshold" | "domain_noise" | "domain_denylisted" | "domain_outside_allowlist" | "meaningful";
+export interface MeaningfulVerdict {
+    meaningful: boolean;
+    reason: MeaningfulReason;
+}
+export declare function classifyMeaningful(input: MeaningfulCandidate, domainLists?: ResearchDomainLists): MeaningfulVerdict;
+export declare function isMeaningful(input: MeaningfulCandidate, domainLists?: ResearchDomainLists): boolean;
+/**
+ * Normalize a user-supplied research-domain entry to its eTLD+1 form.
+ * Accepts free-form input — `arxiv.org`, `https://arxiv.org`,
+ * `www.arxiv.org/abs/2402.06196`, ` ARXIV.ORG ` all resolve to
+ * `"arxiv.org"`. Returns the empty string when the input contains no
+ * extractable host (caller skips empty entries).
+ */
+export declare function normalizeResearchDomain(input: string): string;
+/**
+ * Build a `ResearchDomainLists` from raw config arrays. Filters empty /
+ * invalid entries, normalizes each entry to eTLD+1, and de-duplicates.
+ * The returned `Set`s are frozen-by-convention (Set is mutable but the
+ * caller treats them as read-only). The denylist wins over the
+ * allowlist when both contain the same domain — same precedence the
+ * classifier itself encodes.
+ */
+export declare function buildResearchDomainLists(allowlistInput: readonly string[] | undefined, denylistInput: readonly string[] | undefined): ResearchDomainLists;

package/dist/services/browser-history/pipeline/meaningful-filter.js

@@ -0,0 +1,228 @@
+export const EMPTY_RESEARCH_DOMAIN_LISTS = {
+    allowlist: new Set(),
+    denylist: new Set(),
+};
+const ALLOWED_CATEGORIES = new Set([
+    "research",
+    "news",
+    "dev",
+]);
+const PATH_DENYLIST_SEGMENTS = [
+    "settings",
+    "preferences",
+    "account",
+    "profile",
+    "admin",
+    "dashboard",
+    "billing",
+    "subscription",
+    "login",
+    "signin",
+    "auth",
+    "logout",
+    "oauth",
+];
+const PATH_DENYLIST_PREFIXES = ["api"];
+const MIN_FOREGROUND_SECONDS = 30;
+const DOMAIN_NOISE_RULES = [
+    {
+        host: "claude.ai",
+        noiseSegments: ["settings", "account", "billing", "usage", "organization"],
+        contentSegments: ["chat", "docs", "research"],
+    },
+    {
+        host: "chatgpt.com",
+        noiseSegments: ["settings", "account", "billing"],
+    },
+    {
+        host: "gemini.google.com",
+        noiseSegments: ["settings", "account", "billing"],
+    },
+    {
+        host: "chat.deepseek.com",
+        noiseSegments: ["settings", "account", "billing"],
+    },
+    {
+        host: "github.com",
+        noiseSegments: ["settings", "notifications", "account", "billing"],
+    },
+];
+function pathSegments(path) {
+    return path
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => segment.toLowerCase());
+}
+function pathContainsSegment(path, candidates) {
+    const segments = pathSegments(path);
+    return segments.some((segment) => candidates.includes(segment));
+}
+function pathStartsWithSegment(path, candidates) {
+    const segments = pathSegments(path);
+    if (segments.length === 0)
+        return false;
+    return candidates.includes(segments[0]);
+}
+function hostMatches(host, target) {
+    const cleaned = host.replace(/^www\./i, "").toLowerCase();
+    const t = target.toLowerCase();
+    return cleaned === t || cleaned.endsWith(`.${t}`);
+}
+function applyDomainNoiseRule(host, path) {
+    for (const rule of DOMAIN_NOISE_RULES) {
+        if (!hostMatches(host, rule.host))
+            continue;
+        const segments = pathSegments(path);
+        const first = segments[0];
+        if (rule.contentSegments && first && rule.contentSegments.includes(first)) {
+            return null;
+        }
+        if (rule.noiseSegments.includes(first ?? ""))
+            return "domain_noise";
+        // Default policy for `claude.ai`, `chatgpt.com`, etc.: if there are
+        // no content paths declared, treat anything outside the noise list
+        // as ambiguous and let other filters decide; if contentSegments are
+        // declared and the path is not in them, we still allow downstream
+        // checks (path-denylist, category) to rule on the visit. This keeps
+        // the rule narrow rather than aggressively blocking.
+    }
+    return null;
+}
+export function classifyMeaningful(input, domainLists = EMPTY_RESEARCH_DOMAIN_LISTS) {
+    // Rule 6 (denylist) runs first per §5.F1.meaningful precedence:
+    // "denylist > allowlist (if set) > per-domain noise > scheme > path
+    // > category > foreground threshold". Denylist always wins; an
+    // explicit "never count this domain" stamp shouldn't depend on the
+    // visit passing other gates first.
+    const etld1 = registeredDomain(input.host);
+    if (etld1 && domainLists.denylist.has(etld1)) {
+        return { meaningful: false, reason: "domain_denylisted" };
+    }
+    // Allowlist mode switch — only engaged when the set is non-empty.
+    // A visit outside the allowlist is non-meaningful even if it would
+    // otherwise have passed rules 1-5. This is what makes "I only want
+    // my serious research domains tracked" expressible without losing
+    // the row history (the visit is still inserted, just doesn't
+    // contribute to cluster meaningful_* totals).
+    if (domainLists.allowlist.size > 0) {
+        if (!etld1 || !domainLists.allowlist.has(etld1)) {
+            return { meaningful: false, reason: "domain_outside_allowlist" };
+        }
+    }
+    const scheme = (input.scheme || "").toLowerCase();
+    if (scheme !== "https:" && scheme !== "http:") {
+        return { meaningful: false, reason: "scheme_blocked" };
+    }
+    // Treat plain `http:` as suspicious for research signals — modern
+    // content is HTTPS and Layer 1 should not count plain-HTTP visits
+    // toward research clusters. This is in line with the design's
+    // "scheme allowlist: https:// only" rule.
+    if (scheme !== "https:") {
+        return { meaningful: false, reason: "scheme_blocked" };
+    }
+    if (!ALLOWED_CATEGORIES.has(input.category)) {
+        return { meaningful: false, reason: "category_blocked" };
+    }
+    if (pathStartsWithSegment(input.path, PATH_DENYLIST_PREFIXES)) {
+        return { meaningful: false, reason: "path_denied" };
+    }
+    if (pathContainsSegment(input.path, PATH_DENYLIST_SEGMENTS)) {
+        return { meaningful: false, reason: "path_denied" };
+    }
+    const noise = applyDomainNoiseRule(input.host, input.path);
+    if (noise) {
+        return { meaningful: false, reason: noise };
+    }
+    const foreground = input.foregroundSeconds ?? 0;
+    if (foreground < MIN_FOREGROUND_SECONDS) {
+        return { meaningful: false, reason: "below_dwell_threshold" };
+    }
+    return { meaningful: true, reason: "meaningful" };
+}
+export function isMeaningful(input, domainLists = EMPTY_RESEARCH_DOMAIN_LISTS) {
+    return classifyMeaningful(input, domainLists).meaningful;
+}
+const TWO_LEVEL_TLDS = new Set([
+    "co.jp",
+    "co.uk",
+    "com.au",
+    "com.br",
+    "co.kr",
+    "co.nz",
+    "ac.jp",
+    "ne.jp",
+    "or.jp",
+]);
+/**
+ * eTLD+1 extractor — strips `www.`, lowercases, and returns the
+ * registered-domain label (last two labels, or last three when the
+ * tail is a known two-level public suffix like `co.jp`). Mirrors the
+ * private helper in `sensitive-hosts.ts` (kept distinct because the
+ * sensitive-host module returns the bare registered label for keyword
+ * probing; here we need the full registered domain for set membership).
+ */
+function registeredDomain(host) {
+    if (!host)
+        return "";
+    const cleaned = host.replace(/^www\./i, "").toLowerCase();
+    const parts = cleaned.split(".").filter((segment) => segment.length > 0);
+    if (parts.length === 0)
+        return "";
+    if (parts.length < 3)
+        return parts.join(".");
+    const lastTwo = parts.slice(-2).join(".");
+    if (TWO_LEVEL_TLDS.has(lastTwo)) {
+        return parts.slice(-3).join(".");
+    }
+    return parts.slice(-2).join(".");
+}
+/**
+ * Normalize a user-supplied research-domain entry to its eTLD+1 form.
+ * Accepts free-form input — `arxiv.org`, `https://arxiv.org`,
+ * `www.arxiv.org/abs/2402.06196`, ` ARXIV.ORG ` all resolve to
+ * `"arxiv.org"`. Returns the empty string when the input contains no
+ * extractable host (caller skips empty entries).
+ */
+export function normalizeResearchDomain(input) {
+    if (!input)
+        return "";
+    let value = input.trim();
+    if (!value)
+        return "";
+    // Strip scheme + leading slashes if the user pasted a URL.
+    const schemeStripped = value.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "");
+    // Take the host portion (everything up to the first slash / question
+    // mark / colon for port — but leave the rest of the string intact
+    // for the lowercase + parse step below).
+    const hostPortion = schemeStripped.split(/[/?#]/, 1)[0];
+    // Drop any user@ prefix or :port suffix; we only care about the host.
+    const hostNoUser = hostPortion.includes("@")
+        ? hostPortion.slice(hostPortion.indexOf("@") + 1)
+        : hostPortion;
+    const hostNoPort = hostNoUser.split(":", 1)[0];
+    value = hostNoPort;
+    return registeredDomain(value);
+}
+/**
+ * Build a `ResearchDomainLists` from raw config arrays. Filters empty /
+ * invalid entries, normalizes each entry to eTLD+1, and de-duplicates.
+ * The returned `Set`s are frozen-by-convention (Set is mutable but the
+ * caller treats them as read-only). The denylist wins over the
+ * allowlist when both contain the same domain — same precedence the
+ * classifier itself encodes.
+ */
+export function buildResearchDomainLists(allowlistInput, denylistInput) {
+    const allowlist = new Set();
+    for (const raw of allowlistInput ?? []) {
+        const normalized = normalizeResearchDomain(raw);
+        if (normalized)
+            allowlist.add(normalized);
+    }
+    const denylist = new Set();
+    for (const raw of denylistInput ?? []) {
+        const normalized = normalizeResearchDomain(raw);
+        if (normalized)
+            denylist.add(normalized);
+    }
+    return { allowlist, denylist };
+}

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

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+import type Database from "better-sqlite3";
+export interface OfferRateLimitConfig {
+    /** Maximum offer DMs per 24h window (default 2). */
+    globalDailyCap: number;
+    /** Minimum gap between any two offer DMs (default 4h). */
+    minIntervalMs: number;
+    /** Decline backoff window — bump per-cluster cooldown after decline. */
+    declineBackoffMs: number;
+    /** Window during which owner DM activity counts as "in progress". */
+    activeConversationWindowMs: number;
+    /** Quiet hours window — "HH:MM" 24h strings, or null when unconfigured. */
+    quietHoursStart: string | null;
+    quietHoursEnd: string | null;
+    /** IANA timezone for quiet-hours evaluation. */
+    timezone: string;
+}
+export declare const DEFAULT_OFFER_RATE_LIMIT_CONFIG: OfferRateLimitConfig;
+export type OfferRateLimitSkipReason = "daily_cap" | "interval" | "same_topic" | "quiet_hours" | "active_conversation" | "decline_backoff";
+export type OfferRateLimitDecision = {
+    decision: "fire";
+} | {
+    decision: "skip";
+    reason: OfferRateLimitSkipReason;
+};
+/**
+ * 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 declare function gateOfferRateLimit(db: Database.Database, candidateSlug: string, nowMs: number, config?: OfferRateLimitConfig): OfferRateLimitDecision;
+/**
+ * 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 declare function isInQuietHours(nowMs: number, start: string, end: string, timezone: string): boolean;