@vellumai/assistant 0.6.3 → 0.6.5

package/src/home/emit-feed-event.ts

@@ -0,0 +1,162 @@
+/**
+ * Background-job → home feed event helper.
+ *
+ * The "force-write, not taught-write" entry point for the activity
+ * log. Every background job that wants to surface something on the
+ * Home page calls `emitFeedEvent({ source, title, summary, ... })`
+ * at the end of its completion path — no LLM involved, no prompt
+ * instruction, just a deterministic side effect. This keeps the
+ * "what got surfaced" question grep-able to a single symbol.
+ *
+ * Opinionated defaults for action items:
+ *
+ *   - `type` is hard-coded to `"action"` — this helper is specifically
+ *     for the activity log. Nudges / digests / threads continue to
+ *     go through `writeAssistantFeedItem` or platform baseline
+ *     generators.
+ *   - `author` is hard-coded to `"assistant"` so hybrid authoring
+ *     resolution treats these as assistant-produced (platform
+ *     defaults can never overwrite them).
+ *   - `source` is REQUIRED — actions always have an origin (gmail,
+ *     slack, calendar, assistant). The per-source volume cap in
+ *     `feed-writer.ts` depends on this.
+ *   - No default `expiresAt`. Action items persist until the user
+ *     dismisses them. Callers that want auto-expiry pass `expiresAt`
+ *     explicitly.
+ *   - Optional `dedupKey` — when set, the helper derives a
+ *     deterministic id so a second emit for the same logical event
+ *     (e.g. the same background job running twice on the same
+ *     signal) updates the existing entry in place instead of
+ *     appending a duplicate. When absent, a fresh `randomUUID` is
+ *     used and every call produces a new entry.
+ *
+ * Persistence goes through `appendFeedItem`, inheriting its
+ * warn-log-on-failure contract — callers never need a try/catch.
+ * Schema validation runs at build time so a malformed call throws
+ * loudly at the source rather than silently corrupting the file.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import {
+  type FeedAction,
+  type FeedItem,
+  feedItemSchema,
+  type FeedItemSource,
+  type FeedItemUrgency,
+} from "./feed-types.js";
+import { appendFeedItem } from "./feed-writer.js";
+
+/**
+ * Default priority for background-job action items. Sits below the
+ * assistant nudge default (60) so an explicit nudge from
+ * `writeAssistantFeedItem` surfaces above routine activity log
+ * entries, but above the platform baseline (40) so background job
+ * traces outrank same-source platform defaults.
+ */
+const DEFAULT_EMIT_PRIORITY = 50;
+
+/**
+ * Parameters accepted by {@link emitFeedEvent}.
+ *
+ * All action items emitted by background jobs have an origin, so
+ * `source` is required. Everything else is optional — callers supply
+ * only the fields that describe the specific event.
+ */
+export interface EmitFeedEventParams {
+  /** Origin of the underlying event (gmail, slack, calendar, assistant). */
+  source: FeedItemSource;
+  /** Short headline rendered in the feed row. */
+  title: string;
+  /** Body copy rendered below the title. */
+  summary: string;
+  /**
+   * Stable key used to derive a deterministic id so a second emit
+   * for the same logical event updates the existing feed entry in
+   * place. Should include enough structure to identify the event
+   * uniquely (e.g. `"gmail-unread:msg-<messageId>"`,
+   * `"task-runner:<taskId>"`). When omitted, every call produces a
+   * fresh id and appends a new entry.
+   */
+  dedupKey?: string;
+  /**
+   * Priority in [0, 100]. Defaults to {@link DEFAULT_EMIT_PRIORITY}
+   * (50) — above the platform baseline of 40, below the assistant
+   * nudge default of 60.
+   */
+  priority?: number;
+  /** Action buttons surfaced on the feed row. */
+  actions?: FeedAction[];
+  /** Minimum seconds the user must be away before the item is shown. */
+  minTimeAway?: number;
+  /**
+   * Absolute ISO-8601 expiry timestamp. Omit to let the item persist
+   * until the user dismisses it (default for activity-log actions).
+   */
+  expiresAt?: string;
+  /** Visual urgency treatment — controls badge color independently of sort priority. */
+  urgency?: FeedItemUrgency;
+}
+
+/**
+ * Build a deterministic feed item id from a source + dedup key.
+ *
+ * The id is intentionally human-readable: `emit:<source>:<dedupKey>`.
+ * This makes debugging easier than a hash (you can eyeball the file
+ * and immediately see which background job produced which entry)
+ * and `FeedItem.id` is a free-form string so there is no length or
+ * charset constraint to worry about.
+ */
+function deterministicId(source: FeedItemSource, dedupKey: string): string {
+  return `emit:${source}:${dedupKey}`;
+}
+
+/**
+ * Emit a background-job activity-log entry onto the home feed.
+ *
+ * Builds a fully-formed assistant-authored `action` {@link FeedItem},
+ * validates it against the canonical schema, and persists it via
+ * {@link appendFeedItem}. Returns the constructed item so the caller
+ * can log / reference it downstream.
+ *
+ * Throws a `ZodError` if the constructed item fails validation
+ * (e.g. a `priority` outside `[0, 100]`) — a programming error in
+ * the caller that must not be silently swallowed. Persistence-layer
+ * failures are absorbed by `appendFeedItem` per its warn-log
+ * contract.
+ */
+export async function emitFeedEvent(
+  params: EmitFeedEventParams,
+): Promise<FeedItem> {
+  const now = new Date().toISOString();
+
+  const id =
+    params.dedupKey !== undefined
+      ? deterministicId(params.source, params.dedupKey)
+      : randomUUID();
+
+  const item: FeedItem = {
+    id,
+    type: "action",
+    source: params.source,
+    title: params.title,
+    summary: params.summary,
+    priority: params.priority ?? DEFAULT_EMIT_PRIORITY,
+    status: "new",
+    author: "assistant",
+    timestamp: now,
+    createdAt: now,
+    actions: params.actions,
+    urgency: params.urgency,
+    minTimeAway: params.minTimeAway,
+    expiresAt: params.expiresAt,
+  };
+
+  // Programming-error guardrail: invalid input throws at the source
+  // instead of corrupting the on-disk snapshot via the writer.
+  feedItemSchema.parse(item);
+
+  await appendFeedItem(item);
+
+  return item;
+}

package/src/home/feed-scheduler.ts

@@ -0,0 +1,263 @@
+/**
+ * Home activity feed scheduler.
+ *
+ * Periodic tick loop that drives the feed producers — the assistant
+ * roll-up loop and the platform-baseline Gmail digest generator. This
+ * is the layer that turns the Phase-5 scaffolding into a live feed: the
+ * producers exist as standalone functions, the writer knows how to
+ * persist their output, and the HTTP route + SSE pipeline surface it
+ * to the macOS client; this scheduler is what actually calls them.
+ *
+ * Design notes:
+ *
+ *   - Mirrors `schedule/scheduler.ts`: `setInterval` + coalescing flag
+ *     so two ticks never run in parallel, `timer.unref()` so the timer
+ *     never blocks daemon exit, stop() clears the interval on shutdown.
+ *
+ *   - Each producer tracks its own "last ran at" timestamp and decides
+ *     whether to run on each tick. This keeps the tick cadence short
+ *     (so cheap producers refresh often) while expensive producers
+ *     (LLM roll-up) self-throttle independently.
+ *
+ *   - Fire-and-forget: every producer failure is logged and swallowed.
+ *     A broken producer must never break the tick loop or the daemon.
+ *
+ *   - `writeAssistantFeedItem` / `generateGmailDigest` both invoke the
+ *     feed writer directly, which publishes `home_feed_updated` on every
+ *     successful write, so the macOS store auto-refreshes without this
+ *     scheduler needing to touch the event hub.
+ */
+
+import { getLogger } from "../util/logger.js";
+import type { FeedItem } from "./feed-types.js";
+import {
+  generateGmailDigest,
+  type GmailCountSource,
+} from "./platform-gmail-digest.js";
+import { type RollupResult, runRollupProducer } from "./rollup-producer.js";
+
+const log = getLogger("home-feed-scheduler");
+
+/** Tick cadence — fast enough for a Gmail digest to feel fresh. */
+const TICK_INTERVAL_MS = 5 * 60 * 1000;
+
+/** Per-producer minimum gap between runs. */
+const GMAIL_DIGEST_INTERVAL_MS = 5 * 60 * 1000;
+/**
+ * Roll-up cadence is deliberately long — 120 minutes — because the
+ * scheduler is the *safety net*, not the primary trigger. Opening the
+ * Home page fires a debounced on-visit refresh in the HTTP route (see
+ * `runtime/routes/home-feed-routes.ts`), which is the path most users
+ * actually hit. The scheduler exists so the feed still stays fresh
+ * for long idle stretches where nobody opens the Home page.
+ */
+const ROLLUP_INTERVAL_MS = 2 * 60 * 60 * 1000;
+
+export interface FeedSchedulerHandle {
+  /** Stops the interval. Safe to call multiple times. */
+  stop(): void;
+  /**
+   * Run a single tick synchronously for tests. Returns a summary of
+   * which producers ran during this tick.
+   */
+  runOnce(now?: Date): Promise<FeedTickSummary>;
+}
+
+export interface FeedTickSummary {
+  gmailDigestRan: boolean;
+  rollupRan: boolean;
+}
+
+export interface FeedSchedulerOptions {
+  /**
+   * Optional count source for the Gmail digest. Defaults to
+   * {@link defaultGmailCountSource}, which reads the active OAuth
+   * connection and issues one `messages.list?q=is:unread&maxResults=1`
+   * call to read the `resultSizeEstimate` field (no body fetches).
+   */
+  gmailCountSource?: GmailCountSource;
+  /**
+   * When true (the default), the scheduler fires one tick synchronously
+   * after startup so the feed is populated on the first app open after
+   * daemon boot. Set to false in tests so the only ticks that run are
+   * the ones the test drives via `runOnce()`.
+   */
+  runOnStart?: boolean;
+  /**
+   * Dependency seams for tests. Production callers pass `undefined` so
+   * the scheduler uses the real producer implementations. Tests pass
+   * spies to avoid `mock.module`, which leaks across files in Bun's
+   * test runner.
+   */
+  gmailDigestRunner?: (
+    now: Date,
+    countSource: GmailCountSource,
+  ) => Promise<FeedItem | null>;
+  rollupRunner?: (now: Date) => Promise<RollupResult>;
+}
+
+/**
+ * Start the home feed scheduler. Returns a handle whose `stop()` is
+ * wired into the daemon shutdown sequence via `ShutdownDeps`.
+ */
+export function startFeedScheduler(
+  options: FeedSchedulerOptions = {},
+): FeedSchedulerHandle {
+  let stopped = false;
+  let tickRunning = false;
+  let lastGmailDigestAt = 0;
+  let lastRollupAt = 0;
+
+  const gmailCountSource = options.gmailCountSource ?? defaultGmailCountSource;
+  const gmailDigestRunner = options.gmailDigestRunner ?? generateGmailDigest;
+  const rollupRunner =
+    options.rollupRunner ?? ((now: Date) => runRollupProducer(now));
+
+  const tick = async (now: Date = new Date()): Promise<FeedTickSummary> => {
+    const summary: FeedTickSummary = {
+      gmailDigestRan: false,
+      rollupRan: false,
+    };
+    if (stopped || tickRunning) return summary;
+    tickRunning = true;
+    const nowMs = now.getTime();
+    try {
+      if (nowMs - lastGmailDigestAt >= GMAIL_DIGEST_INTERVAL_MS) {
+        lastGmailDigestAt = nowMs;
+        summary.gmailDigestRan = true;
+        const startedAt = Date.now();
+        try {
+          const item = await gmailDigestRunner(now, gmailCountSource);
+          log.info(
+            { wroteItem: item !== null, durationMs: Date.now() - startedAt },
+            "Gmail digest producer ran",
+          );
+        } catch (err) {
+          log.warn(
+            { err, durationMs: Date.now() - startedAt },
+            "Gmail digest producer threw",
+          );
+        }
+      }
+
+      if (nowMs - lastRollupAt >= ROLLUP_INTERVAL_MS) {
+        summary.rollupRan = true;
+        const startedAt = Date.now();
+        try {
+          const result = await rollupRunner(now);
+          log.info(
+            {
+              wroteCount: result.wroteCount,
+              skippedReason: result.skippedReason,
+              durationMs: Date.now() - startedAt,
+            },
+            "Rollup producer ran",
+          );
+          // Only advance the cooldown gate when the producer actually
+          // had a chance to run the LLM. Three skip reasons short-
+          // circuit before any provider call and should NOT burn the
+          // window:
+          //   - `no_provider`: the provider registry wasn't ready yet
+          //     (happens on the startup tick because the feed scheduler
+          //     boots before the provider init pass in
+          //     `daemon/lifecycle.ts`).
+          //   - `no_actions`: there was nothing to roll up. A subsequent
+          //     tick should retry as soon as new actions land, not wait
+          //     the full window.
+          //   - `in_flight`: another caller (usually the on-visit
+          //     refresh trigger in `home-feed-routes.ts`) is already
+          //     running the rollup. That caller's result effectively
+          //     counts as this scheduler tick's real run; bumping the
+          //     gate here would force the NEXT tick to also wait out
+          //     the full window even though nothing broken happened.
+          // Every other outcome — success, empty items, malformed
+          // output, provider error — is a real LLM attempt and does
+          // advance the gate so a broken producer doesn't hammer us.
+          if (
+            result.skippedReason !== "no_provider" &&
+            result.skippedReason !== "no_actions" &&
+            result.skippedReason !== "in_flight"
+          ) {
+            lastRollupAt = nowMs;
+          }
+        } catch (err) {
+          lastRollupAt = nowMs;
+          log.warn(
+            { err, durationMs: Date.now() - startedAt },
+            "Rollup producer threw",
+          );
+        }
+      }
+    } finally {
+      tickRunning = false;
+    }
+    return summary;
+  };
+
+  const timer = setInterval(() => {
+    void tick();
+  }, TICK_INTERVAL_MS);
+  timer.unref();
+  if (options.runOnStart !== false) {
+    // Fire once on startup so the feed is populated on the first app
+    // open after daemon boot. Runs in the background — startup does
+    // not await it.
+    void tick();
+  }
+
+  log.info(
+    {
+      tickIntervalMs: TICK_INTERVAL_MS,
+      gmailDigestIntervalMs: GMAIL_DIGEST_INTERVAL_MS,
+      rollupIntervalMs: ROLLUP_INTERVAL_MS,
+    },
+    "Home feed scheduler started",
+  );
+
+  return {
+    stop(): void {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      log.info("Home feed scheduler stopped");
+    },
+    runOnce: tick,
+  };
+}
+
+/**
+ * Default Gmail count source — resolves the active `google` OAuth
+ * connection via {@link resolveOAuthConnection}, issues one cheap
+ * `messages.list` call with `q=is:unread&maxResults=1`, and returns
+ * the `resultSizeEstimate` field. Returns 0 when no Gmail connection
+ * exists or the call fails so the digest generator no-ops without
+ * throwing.
+ *
+ * Deliberately does NOT pre-check `isProviderConnected("google")` —
+ * that helper only reports local oauth-store rows, which are absent
+ * in managed-OAuth mode even when `resolveOAuthConnection("google")`
+ * would still resolve via the platform path. Letting the resolver
+ * make the decision is the only way to cover both modes.
+ */
+async function defaultGmailCountSource(): Promise<number> {
+  // Lazy import — the oauth resolver + gmail client drag in a fair
+  // bit of transitive state, and we only want to pay that cost when a
+  // tick actually runs (not at module load time).
+  const [{ resolveOAuthConnection }, { listMessages }] = await Promise.all([
+    import("../oauth/connection-resolver.js"),
+    import("../messaging/providers/gmail/client.js"),
+  ]);
+
+  try {
+    const connection = await resolveOAuthConnection("google");
+    const response = await listMessages(connection, "is:unread", 1);
+    const estimate = response.resultSizeEstimate;
+    return typeof estimate === "number" && estimate >= 0 ? estimate : 0;
+  } catch (err) {
+    // Either no Gmail connection exists (managed or direct) or the
+    // API call itself failed. Both paths degrade to zero so the
+    // digest generator no-ops without writing a stale item.
+    log.warn({ err }, "Gmail count source failed; treating as zero");
+    return 0;
+  }
+}

package/src/home/feed-types.ts

@@ -0,0 +1,235 @@
+/**
+ * Home activity feed data contract.
+ *
+ * Defines the shape of `FeedItem`s shown in the macOS Home page feed
+ * section (nudges, digests, actions, threads) plus the on-disk file
+ * format written by the daemon feed writer (PR 5) and served by the
+ * daemon HTTP route (PR 6).
+ *
+ * The TDD contract field originally named `ttl` is renamed internally
+ * to `expiresAt` — it is an absolute ISO-8601 timestamp, not a
+ * duration. Absolute timestamps match the `timestamp` and `createdAt`
+ * fields and make stateless read-time expiry filtering trivial. If we
+ * ever need to expose `ttl` on a public wire format again we can add
+ * a translation layer at the route boundary; within the daemon, all
+ * internal types use `expiresAt`.
+ *
+ * A structurally compatible Swift mirror lives at
+ * `clients/shared/Network/FeedItem.swift` (PR 3). Any change here
+ * must be mirrored there.
+ */
+
+import { z } from "zod";
+
+/** High-level kind of feed item — drives which Swift view renders it. */
+export type FeedItemType = "nudge" | "digest" | "action" | "thread";
+
+/** User-facing lifecycle of a feed item. */
+export type FeedItemStatus = "new" | "seen" | "acted_on" | "dismissed";
+
+/**
+ * Origin of the underlying event.
+ *
+ * In v1 this is constrained to a closed set so the Swift icon mapping
+ * stays exhaustive. Future sources will be added explicitly rather
+ * than letting arbitrary strings slip through.
+ */
+export type FeedItemSource = "gmail" | "slack" | "calendar" | "assistant";
+
+/**
+ * Internal field used by the hybrid authoring resolver (PR 5 writer).
+ *
+ * Not part of the TDD public interface — it distinguishes items the
+ * assistant produced on its own from items the platform baseline
+ * generators (e.g. Gmail digest in PR 12) produced, so assistant
+ * overrides can win over platform defaults for the same source.
+ */
+export type FeedItemAuthor = "assistant" | "platform";
+
+/** Visual urgency treatment — controls badge color independently of sort priority. */
+export type FeedItemUrgency = "low" | "medium" | "high" | "critical";
+
+/**
+ * A single action button attached to a feed item.
+ *
+ * `prompt` is the pre-seeded user message the action sends to the
+ * assistant when triggered — the HTTP route (PR 6) creates a new
+ * conversation with this prompt as the first user turn.
+ */
+export interface FeedAction {
+  id: string;
+  label: string;
+  prompt: string;
+}
+
+/**
+ * A single item rendered in the Home feed.
+ *
+ * Mirrors the TDD contract plus two internal-only fields:
+ *   - `author`  — hybrid-authoring resolver discriminator
+ *   - `createdAt` — when the writer recorded the item (distinct from
+ *                   `timestamp`, which is the event time). Used for
+ *                   TTL sweeps and stable ordering.
+ *
+ * The TDD's `ttl` field is renamed to `expiresAt` here; see the
+ * module comment above for the rationale.
+ */
+export interface FeedItem {
+  id: string;
+  type: FeedItemType;
+  /** Integer in [0, 100]; higher values sort earlier. */
+  priority: number;
+  title: string;
+  summary: string;
+  /** Optional; when present must be one of the four v1 sources. */
+  source?: FeedItemSource;
+  /** Event time (ISO-8601). */
+  timestamp: string;
+  /** Defaults to `"new"` at parse time. */
+  status: FeedItemStatus;
+  /** Absolute ISO-8601 expiry timestamp (renamed from TDD `ttl`). */
+  expiresAt?: string;
+  /** Minimum seconds the user must be away before the item is shown. */
+  minTimeAway?: number;
+  actions?: FeedAction[];
+  /** Visual urgency treatment — controls badge color independently of sort priority. */
+  urgency?: FeedItemUrgency;
+  /** Internal: who authored this item. */
+  author: FeedItemAuthor;
+  /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
+  createdAt: string;
+}
+
+/**
+ * Summary of low-priority items that were collapsed out of the main
+ * feed list. The client renders this as a single "N low priority
+ * updates" line instead of showing each item individually.
+ */
+export interface LowPriorityCollapsed {
+  count: number;
+  itemIds: string[];
+}
+
+/**
+ * On-disk file format for `~/.vellum/workspace/data/home-feed.json`.
+ *
+ * Written by the PR 5 writer, read by the PR 6 HTTP route and
+ * `parseFeedFile` below. `version` is pinned to `1`; future format
+ * changes bump this and live behind a workspace migration.
+ */
+export interface HomeFeedFile {
+  version: 1;
+  items: FeedItem[];
+  updatedAt: string;
+}
+
+/**
+ * Origin of a suggested prompt — whether it was deterministically derived
+ * (e.g. from a missing OAuth connection) or generated by the assistant.
+ */
+export type SuggestedPromptSource = "deterministic" | "assistant";
+
+/**
+ * A prompt suggestion shown at the top of the Home page.
+ *
+ * Deterministic prompts are derived from workspace state (e.g. missing
+ * OAuth connections). Assistant-generated prompts are contextual
+ * conversation starters produced by the LLM.
+ */
+export interface SuggestedPrompt {
+  id: string;
+  label: string;
+  icon?: string;
+  prompt: string;
+  source: SuggestedPromptSource;
+}
+
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+
+const feedItemTypeSchema = z.enum(["nudge", "digest", "action", "thread"]);
+
+const feedItemStatusSchema = z.enum(["new", "seen", "acted_on", "dismissed"]);
+
+const feedItemSourceSchema = z.enum([
+  "gmail",
+  "slack",
+  "calendar",
+  "assistant",
+]);
+
+const feedItemAuthorSchema = z.enum(["assistant", "platform"]);
+
+const feedItemUrgencySchema = z.enum(["low", "medium", "high", "critical"]);
+
+const feedActionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  prompt: z.string(),
+});
+
+/**
+ * Schema for a single `FeedItem`.
+ *
+ * Notes:
+ *   - `priority` must be an integer in [0, 100]; string numerics
+ *     (e.g. `"5"`) are rejected — we want deterministic ordering and
+ *     silent coercion tends to mask writer bugs.
+ *   - `status` defaults to `"new"` so the writer does not need to
+ *     set it on every append.
+ *   - `source` is optional but, when present, must be one of the
+ *     four v1 sources — unknown values (e.g. `"facebook"`) are
+ *     rejected rather than silently passed through.
+ *   - `minTimeAway` is a non-negative integer number of seconds.
+ */
+export const feedItemSchema = z.object({
+  id: z.string(),
+  type: feedItemTypeSchema,
+  priority: z.number().int().min(0).max(100),
+  title: z.string(),
+  summary: z.string(),
+  source: feedItemSourceSchema.optional(),
+  timestamp: z.string(),
+  status: feedItemStatusSchema.default("new"),
+  expiresAt: z.string().optional(),
+  minTimeAway: z.number().int().min(0).optional(),
+  actions: z.array(feedActionSchema).optional(),
+  urgency: feedItemUrgencySchema.optional(),
+  author: feedItemAuthorSchema,
+  createdAt: z.string(),
+});
+
+const suggestedPromptSourceSchema = z.enum(["deterministic", "assistant"]);
+
+export const suggestedPromptSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  icon: z.string().optional(),
+  prompt: z.string(),
+  source: suggestedPromptSourceSchema,
+});
+
+export const lowPriorityCollapsedSchema = z.object({
+  count: z.number().int().min(0),
+  itemIds: z.array(z.string()),
+});
+
+/** Schema for the on-disk `home-feed.json` file. */
+export const homeFeedFileSchema = z.object({
+  version: z.literal(1),
+  items: z.array(feedItemSchema),
+  updatedAt: z.string(),
+});
+
+/**
+ * Parse and validate a raw value read from `home-feed.json`.
+ *
+ * Used by the PR 5 writer on read-back and by the PR 6 HTTP route
+ * when serving the feed. Throws a `ZodError` on any validation
+ * failure — callers are expected to log + recover (e.g. treat the
+ * file as empty).
+ */
+export function parseFeedFile(raw: unknown): HomeFeedFile {
+  return homeFeedFileSchema.parse(raw) as HomeFeedFile;
+}