@aitne/daemon 0.1.8 → 0.1.10

package/dist/services/browser-history/pipeline/cluster-extractor.js

@@ -0,0 +1,271 @@
+import { getAgentDayDateStr } from "@aitne/shared";
+const DEFAULT_BOUNDARY = {
+    timezone: undefined,
+    dayBoundaryHour: 4,
+};
+function agentDayKey(tsMs, boundary) {
+    // Use the shared helper so the bucket respects the user's local
+    // timezone. Reinventing this with `new Date(ms - 4h)` produces wrong
+    // dates for any non-UTC user (CLAUDE.md: "do not reinvent date math").
+    return getAgentDayDateStr(boundary.timezone, boundary.dayBoundaryHour, new Date(tsMs));
+}
+export function aggregateCluster(rows, boundary = DEFAULT_BOUNDARY) {
+    if (rows.length === 0)
+        return null;
+    const rootTaskId = rows[0].rootTaskId;
+    const startedAt = Math.min(...rows.map((row) => row.ts));
+    const lastActivityAt = Math.max(...rows.map((row) => row.ts));
+    const meaningfulRows = rows.filter((row) => row.meaningful === 1);
+    const meaningfulVisitsTotal = meaningfulRows.length;
+    const meaningfulForegroundSecTotal = meaningfulRows.reduce((acc, row) => acc + (row.meaningfulForegroundSec ?? 0), 0);
+    const distinctDomains = new Set(meaningfulRows.map((row) => row.domain));
+    const distinctDays = new Set(meaningfulRows.map((row) => agentDayKey(row.ts, boundary)));
+    const domainCounts = new Map();
+    for (const row of meaningfulRows) {
+        domainCounts.set(row.domain, (domainCounts.get(row.domain) ?? 0) + 1);
+    }
+    const sortedDomains = [...domainCounts.entries()].sort((a, b) => b[1] - a[1]);
+    const topNonSearchDomain = sortedDomains.find(([domain]) => !/(google|bing|duckduckgo|yahoo)\./.test(domain))?.[0]
+        ?? sortedDomains[0]?.[0]
+        ?? null;
+    const termCounts = new Map();
+    for (const row of meaningfulRows) {
+        if (!row.searchQuery)
+            continue;
+        const normalised = row.searchQuery.toLowerCase().trim();
+        if (!normalised)
+            continue;
+        termCounts.set(normalised, (termCounts.get(normalised) ?? 0) + 1);
+    }
+    const sortedTerms = [...termCounts.entries()].sort((a, b) => b[1] - a[1]);
+    const topSearchTerm = sortedTerms[0]?.[0] ?? null;
+    return {
+        rootTaskId,
+        startedAt,
+        lastActivityAt,
+        visitsTotal: rows.length,
+        meaningfulVisitsTotal,
+        meaningfulForegroundSecTotal,
+        distinctMeaningfulDomains: distinctDomains.size,
+        distinctMeaningfulDays: distinctDays.size,
+        topNonSearchDomain,
+        topSearchTerm,
+    };
+}
+export const DEFAULT_QUALIFICATION_THRESHOLDS = {
+    minDays: 3,
+    minMeaningfulVisits: 20,
+    minMeaningfulForegroundSec: 3600,
+    minDistinctDomains: 3,
+};
+export function qualifiesAsActiveResearch(aggregate, thresholds = DEFAULT_QUALIFICATION_THRESHOLDS) {
+    return (aggregate.distinctMeaningfulDays >= thresholds.minDays
+        && aggregate.meaningfulVisitsTotal >= thresholds.minMeaningfulVisits
+        && aggregate.meaningfulForegroundSecTotal >= thresholds.minMeaningfulForegroundSec
+        && aggregate.distinctMeaningfulDomains >= thresholds.minDistinctDomains);
+}
+const SLUG_MAX_LENGTH = 60;
+function slugifyToken(value) {
+    if (!value)
+        return "";
+    return value
+        .toLowerCase()
+        .normalize("NFKD")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, SLUG_MAX_LENGTH);
+}
+function trimSlug(slug) {
+    return slug.replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+}
+export function deriveClusterSlug(aggregate) {
+    const domainPart = slugifyToken(aggregate.topNonSearchDomain?.replace(/^www\./, "")
+        .split(".")[0] ?? null);
+    const termPart = slugifyToken(aggregate.topSearchTerm);
+    const composed = [domainPart, termPart].filter((part) => part.length > 0).join("-");
+    const fallback = `cluster-${aggregate.rootTaskId}`;
+    const slug = trimSlug(composed) || fallback;
+    return slug.length >= 2 ? slug.slice(0, SLUG_MAX_LENGTH * 2) : fallback;
+}
+export function deriveClusterDisplayName(aggregate) {
+    const domain = aggregate.topNonSearchDomain ?? "research";
+    const term = aggregate.topSearchTerm;
+    if (term) {
+        const titleCased = term
+            .split(/\s+/)
+            .filter((part) => part.length > 0)
+            .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+            .join(" ");
+        return titleCased.length > 0 ? titleCased : domain;
+    }
+    return domain;
+}
+const CLUSTER_QUERY = `
+  SELECT
+    root_task_id AS rootTaskId,
+    ts,
+    domain,
+    category,
+    meaningful,
+    foreground_sec AS meaningfulForegroundSec,
+    title,
+    search_query AS searchQuery
+  FROM browser_visits
+  WHERE root_task_id IS NOT NULL
+  ORDER BY root_task_id ASC, ts ASC
+`;
+function disambiguateSlug(base, rootTaskId, used) {
+    if (!used.has(base))
+        return base;
+    // Two clusters that would derive the same slug (same top-domain + top
+    // search term) collide on the `slug` PK in browser_research_clusters
+    // and silently merge under the first-inserted root_task_id. Append a
+    // stable suffix so each root_task_id keeps its own row.
+    //
+    // `rootTaskId` is the unique grouping key from the caller's `byRoot`
+    // map, so the resulting `<truncated>-<rootTaskId>` is guaranteed
+    // unique across every iteration of `extractClustersFromDb`.
+    const suffix = `-${rootTaskId}`;
+    const truncated = base.slice(0, Math.max(2, SLUG_MAX_LENGTH * 2 - suffix.length));
+    return `${truncated}${suffix}`;
+}
+export function extractClustersFromDb(db, boundary = DEFAULT_BOUNDARY) {
+    const rows = db.prepare(CLUSTER_QUERY).all();
+    if (rows.length === 0)
+        return [];
+    const byRoot = new Map();
+    for (const row of rows) {
+        const list = byRoot.get(row.rootTaskId) ?? [];
+        list.push(row);
+        byRoot.set(row.rootTaskId, list);
+    }
+    const out = [];
+    const usedSlugs = new Set();
+    for (const [, group] of byRoot) {
+        // `byRoot` only holds non-empty groups (rows are pushed before the
+        // map is updated), so aggregateCluster never returns null here.
+        const aggregate = aggregateCluster(group, boundary);
+        const baseSlug = deriveClusterSlug(aggregate);
+        const slug = disambiguateSlug(baseSlug, aggregate.rootTaskId, usedSlugs);
+        usedSlugs.add(slug);
+        out.push({
+            slug,
+            displayName: deriveClusterDisplayName(aggregate),
+            aggregate,
+            qualifies: qualifiesAsActiveResearch(aggregate),
+        });
+    }
+    return out;
+}
+const ENGAGEMENT_QUERY = `
+  SELECT
+    root_task_id AS rootTaskId,
+    ts,
+    domain,
+    foreground_sec AS foregroundSec
+  FROM browser_visits
+  WHERE root_task_id = ? AND meaningful = 1
+  ORDER BY ts ASC
+`;
+const LONG_READ_FOREGROUND_SEC = 120;
+const RECENT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Build the offer-trigger evaluator's input snapshot from a stored
+ * cluster row + the cluster's meaningful-visit history. Returns
+ * `null` when the cluster has no meaningful rows (defensive — the
+ * poller's upsert should have filtered such clusters to dormant, but
+ * a stale row can survive between upserts).
+ *
+ * Pure aggregation over `browser_visits`. The expensive paths (window
+ * scan, day-bucket dedup, long-read counting) are bounded by the per-
+ * cluster row count, which the qualification thresholds keep ≤ a few
+ * hundred for the lifetime of a real research thread.
+ */
+export function buildEngagementSnapshot(db, row, boundary, nowMs) {
+    const visits = db.prepare(ENGAGEMENT_QUERY).all(row.rootTaskId);
+    if (visits.length === 0)
+        return null;
+    const daySet = new Set();
+    const longReadDaySet = new Set();
+    let longReadVisits = 0;
+    const recentWindowStart = nowMs - RECENT_WINDOW_MS;
+    const priorWindowStart = nowMs - 2 * RECENT_WINDOW_MS;
+    let recentForegroundSec = 0;
+    const recentDomains = new Set();
+    const priorDomains = new Set();
+    // BROWSER_HISTORY_INTEGRATION_PLAN §5.F1 (seventh-pass) — the offer
+    // DM agent reads `topDomains` from event.data to colour its prose
+    // ("you've been deep on the CaMeL paper across arxiv.org,
+    // simonwillison.net, anthropic.com"). Rank by per-domain foreground
+    // time so the labels match what the user actually spent time on,
+    // not raw visit count.
+    const domainForeground = new Map();
+    for (const visit of visits) {
+        const day = agentDayKey(visit.ts, boundary);
+        daySet.add(day);
+        const fg = visit.foregroundSec ?? 0;
+        if (fg >= LONG_READ_FOREGROUND_SEC) {
+            longReadVisits += 1;
+            longReadDaySet.add(day);
+        }
+        if (visit.ts >= recentWindowStart) {
+            recentForegroundSec += fg;
+            recentDomains.add(visit.domain);
+        }
+        else if (visit.ts >= priorWindowStart) {
+            priorDomains.add(visit.domain);
+        }
+        domainForeground.set(visit.domain, (domainForeground.get(visit.domain) ?? 0) + fg);
+    }
+    const topDomains = [...domainForeground.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 5)
+        .map(([domain]) => domain);
+    return {
+        slug: row.slug,
+        displayName: row.displayName,
+        status: row.status,
+        startedAt: row.startedAt,
+        lastActivityAt: row.lastActivityAt,
+        meaningfulVisitsTotal: row.meaningfulVisitsTotal,
+        meaningfulForegroundSecTotal: row.meaningfulForegroundSecTotal,
+        distinctMeaningfulDomains: row.distinctMeaningfulDomains,
+        distinctMeaningfulDays: daySet.size,
+        longReadVisits,
+        longReadDays: longReadDaySet.size,
+        recentForegroundSec,
+        recentDomains,
+        priorDomains,
+        topDomains,
+        lastDmAt: row.lastDmAt,
+        lastResearchOfferAt: row.lastResearchOfferAt,
+        lastWikiOfferAt: row.lastWikiOfferAt,
+        researchOfferAcceptedAt: row.researchOfferAcceptedAt,
+        wikiSummaryWrittenAt: row.wikiSummaryWrittenAt,
+    };
+}
+const CLUSTERS_FOR_ENGAGEMENT_QUERY = `
+  SELECT
+    slug,
+    display_name AS displayName,
+    root_task_id AS rootTaskId,
+    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,
+    last_dm_at AS lastDmAt,
+    last_research_offer_at AS lastResearchOfferAt,
+    last_wiki_offer_at AS lastWikiOfferAt,
+    research_offer_accepted_at AS researchOfferAcceptedAt,
+    wiki_summary_written_at AS wikiSummaryWrittenAt
+  FROM browser_research_clusters
+  WHERE status = 'active'
+  ORDER BY last_activity_at DESC
+`;
+export function listActiveClustersForEngagement(db) {
+    return db
+        .prepare(CLUSTERS_FOR_ENGAGEMENT_QUERY)
+        .all();
+}

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

@@ -0,0 +1,99 @@
+import type { ClusterSnapshot, WeeklyInterestsSummary } from "./weekly-interests-summary.js";
+/**
+ * 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 declare function escapeForMd(value: string): string;
+/**
+ * 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 declare function escapeForHtmlComment(value: string): string;
+/**
+ * Format a cluster's foreground seconds as a compact hour figure for
+ * the bullet body: `~3.2h` / `~38min` / `~12sec`.
+ */
+export declare function formatHoursCompact(sec: number): string;
+/**
+ * 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 declare function renderProfileBlock(args: {
+    clusters: readonly ClusterSnapshot[];
+    weekStart: string;
+    generatedAt: string;
+}): string;
+/**
+ * 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 declare function renderProjectBlock(args: {
+    projectSlug: string;
+    clusters: readonly ClusterSnapshot[];
+    weekStart: string;
+    generatedAt: string;
+}): string | null;
+/**
+ * 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 declare function renderIndexEntryBlock(args: {
+    generatedAt: string;
+}): string;
+/**
+ * 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 declare function renderResearchThemesFile(summary: WeeklyInterestsSummary): string;
+/**
+ * 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 declare function replaceAutoBlock(fileContent: string, newBlockContent: string, disambiguator?: string | null): string;
+/**
+ * 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 declare function stripAllAutoBlocks(fileContent: string): {
+    content: string;
+    blocksRemoved: number;
+};