@vellumai/assistant 0.6.3 → 0.6.4

package/src/home/feed-scheduler.ts

@@ -0,0 +1,247 @@
+/**
+ * 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;
+const ROLLUP_INTERVAL_MS = 30 * 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. Two 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.
+          // 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"
+          ) {
+            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,181 @@
+/**
+ * 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";
+
+/**
+ * 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";
+
+/**
+ * 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[];
+  /** Internal: who authored this item. */
+  author: FeedItemAuthor;
+  /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
+  createdAt: 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;
+}
+
+// ---------------------------------------------------------------------------
+// Zod schemas
+// ---------------------------------------------------------------------------
+
+const feedItemTypeSchema = z.enum(["nudge", "digest", "action", "thread"]);
+
+const feedItemStatusSchema = z.enum(["new", "seen", "acted_on"]);
+
+const feedItemSourceSchema = z.enum([
+  "gmail",
+  "slack",
+  "calendar",
+  "assistant",
+]);
+
+const feedItemAuthorSchema = z.enum(["assistant", "platform"]);
+
+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(),
+  author: feedItemAuthorSchema,
+  createdAt: 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;
+}