@vellumai/assistant 0.7.0 → 0.7.2

package/src/heartbeat/heartbeat-service.ts

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { getConfig } from "../config/loader.js";
+import type { HeartbeatConfig } from "../config/schemas/heartbeat.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
 import { processMessage } from "../daemon/process-message.js";
 import { emitFeedEvent } from "../home/emit-feed-event.js";
@@ -13,10 +14,20 @@ import {
   resolveGuardianPersona,
 } from "../prompts/persona-resolver.js";
 import { isTemplateContent } from "../prompts/system-prompt.js";
+import { computeNextRunAt } from "../schedule/recurrence-engine.js";
 import { readTextFileSync } from "../util/fs.js";
 import { getLogger } from "../util/logger.js";
 import { getWorkspaceDir, getWorkspacePromptPath } from "../util/platform.js";
 import { stripCommentLines } from "../util/strip-comment-lines.js";
+import {
+  completeHeartbeatRun,
+  insertPendingHeartbeatRun,
+  markStaleRunningAsError,
+  markStaleRunsAsMissed,
+  skipHeartbeatRun,
+  startHeartbeatRun,
+  supersedePendingRun,
+} from "./heartbeat-run-store.js";
 
 const log = getLogger("heartbeat-check");
 
@@ -100,10 +111,20 @@ export class HeartbeatService {
   }
 
   private readonly deps: HeartbeatDeps;
-  private timer: ReturnType<typeof setInterval> | null = null;
+  private timer:
+    | ReturnType<typeof setInterval>
+    | ReturnType<typeof setTimeout>
+    | null = null;
   private activeRun: Promise<void> | null = null;
   private _lastRunAt: number | null = null;
   private _nextRunAt: number | null = null;
+  private cronMode = false;
+  private stopped = false;
+  private configEpoch = 0;
+  private _pendingRunId: string | null = null;
+  private _startupMissedCount = 0;
+  private _startupCrashedCount = 0;
+  private _hasRunStartupRecovery = false;
 
   constructor(deps: HeartbeatDeps) {
     this.deps = deps;
@@ -121,6 +142,7 @@ export class HeartbeatService {
   }
 
   start(): void {
+    this.stopped = false;
     const config = getConfig().heartbeat;
     if (!config.enabled) {
       log.info("Heartbeat disabled by config");
@@ -129,7 +151,57 @@ export class HeartbeatService {
     }
     if (this.timer) return;
 
-    log.info({ intervalMs: config.intervalMs }, "Heartbeat service started");
+    if (!this._hasRunStartupRecovery) {
+      this._hasRunStartupRecovery = true;
+      try {
+        this._startupMissedCount = markStaleRunsAsMissed();
+        this._startupCrashedCount = markStaleRunningAsError();
+      } catch (err) {
+        log.error({ err }, "Failed to recover stale heartbeat runs on startup");
+      }
+      if (this._startupMissedCount > 0 || this._startupCrashedCount > 0) {
+        log.info(
+          {
+            missedCount: this._startupMissedCount,
+            crashedCount: this._startupCrashedCount,
+          },
+          "Recovered stale heartbeat runs on startup",
+        );
+
+        const total = this._startupMissedCount + this._startupCrashedCount;
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
+          title: "Heartbeat Runs Missed",
+          summary: `${total} heartbeat run${total > 1 ? "s were" : " was"} missed while the assistant was offline.`,
+          dedupKey: `heartbeat:missed:${today}`,
+          priority: 55,
+          urgency: "high",
+        }).catch((err) => {
+          log.warn({ err }, "Failed to emit missed heartbeat feed event");
+        });
+      }
+    }
+
+    if (config.cronExpression != null) {
+      this.cronMode = true;
+      this.scheduleNextCronRun(config);
+    } else {
+      this.startIntervalMode(config);
+    }
+  }
+
+  private startIntervalMode(config: HeartbeatConfig): void {
+    this.cronMode = false;
+    if (this.timer) {
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
+      this.timer = null;
+    }
+    log.info(
+      { intervalMs: config.intervalMs },
+      "Heartbeat service started (interval mode)",
+    );
     this.scheduleNextRun(config.intervalMs);
     this.timer = setInterval(() => {
       this.runOnce().catch((err) => {
@@ -138,13 +210,69 @@ export class HeartbeatService {
     }, config.intervalMs);
   }
 
+  private scheduleNextCronRun(config: HeartbeatConfig): void {
+    if (this.stopped) return;
+    try {
+      const nextRunAt = computeNextRunAt({
+        syntax: "cron",
+        expression: config.cronExpression!,
+        timezone: config.timezone,
+      });
+      this._nextRunAt = nextRunAt;
+      if (this.timer) {
+        clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+        clearInterval(this.timer as ReturnType<typeof setInterval>);
+        this.timer = null;
+      }
+      const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000; // 24 hours
+      const delayMs = Math.max(0, nextRunAt - Date.now());
+      const epoch = this.configEpoch;
+      if (delayMs > MAX_TIMEOUT_MS) {
+        // Re-evaluate after 24h — the actual cron time is still far away
+        this.timer = setTimeout(() => {
+          if (this.configEpoch === epoch) {
+            this.scheduleNextCronRun(getConfig().heartbeat);
+          }
+        }, MAX_TIMEOUT_MS);
+      } else {
+        this.timer = setTimeout(() => {
+          this.runOnce()
+            .catch((err) => log.error({ err }, "Cron heartbeat failed"))
+            .finally(() => {
+              if (this.configEpoch === epoch) {
+                this.scheduleNextCronRun(getConfig().heartbeat);
+              }
+            });
+        }, delayMs);
+      }
+      (this.timer as ReturnType<typeof setTimeout>).unref();
+      log.info(
+        { nextRunAt: new Date(nextRunAt).toISOString(), delayMs },
+        "Heartbeat cron run scheduled",
+      );
+    } catch (err) {
+      log.warn(
+        { err },
+        "Failed to compute next cron run, falling back to interval mode",
+      );
+      this.startIntervalMode(config);
+    }
+  }
+
   /** Restart the timer with the latest config (e.g. after settings change). */
   reconfigure(): void {
+    this.configEpoch++;
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+      this._pendingRunId = null;
+    }
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
       this.timer = null;
     }
     this._nextRunAt = null;
+    this.cronMode = false;
     this.start();
   }
 
@@ -155,8 +283,15 @@ export class HeartbeatService {
    */
   resetTimer(): void {
     if (!this.timer) return;
+    if (this.cronMode) {
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
+      this.timer = null;
+      this.scheduleNextCronRun(getConfig().heartbeat);
+      return;
+    }
     const config = getConfig().heartbeat;
-    clearInterval(this.timer);
+    clearInterval(this.timer as ReturnType<typeof setInterval>);
     this.scheduleNextRun(config.intervalMs);
     this.timer = setInterval(() => {
       this.runOnce().catch((err) => {
@@ -166,10 +301,16 @@ export class HeartbeatService {
   }
 
   async stop(): Promise<void> {
+    this.stopped = true;
     if (this.timer) {
-      clearInterval(this.timer);
+      clearTimeout(this.timer as ReturnType<typeof setTimeout>);
+      clearInterval(this.timer as ReturnType<typeof setInterval>);
       this.timer = null;
     }
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+      this._pendingRunId = null;
+    }
     this._nextRunAt = null;
     if (this.activeRun) {
       let timerId: ReturnType<typeof setTimeout>;
@@ -186,7 +327,22 @@ export class HeartbeatService {
    *  When `force` is true (e.g. manual "Run Now"), skip enabled & active-hours guards. */
   async runOnce({ force = false }: { force?: boolean } = {}): Promise<boolean> {
     const config = getConfig().heartbeat;
-    if (!force && !config.enabled) return false;
+
+    let runId: string | null;
+    let scheduledFor: number;
+    if (force) {
+      scheduledFor = Date.now();
+      runId = insertPendingHeartbeatRun(scheduledFor);
+    } else {
+      runId = this._pendingRunId;
+      scheduledFor = this._nextRunAt ?? Date.now();
+      this._pendingRunId = null;
+    }
+
+    if (!force && !config.enabled) {
+      if (runId) skipHeartbeatRun(runId, "disabled");
+      return false;
+    }
 
     // Active hours guard — only applied when both bounds are set.
     // The schema rejects configs where only one bound is provided.
@@ -195,7 +351,17 @@ export class HeartbeatService {
       config.activeHoursStart != null &&
       config.activeHoursEnd != null
     ) {
-      const hour = this.deps.getCurrentHour?.() ?? new Date().getHours();
+      let hour: number;
+      if (this.cronMode && config.timezone) {
+        const parts = new Intl.DateTimeFormat("en-US", {
+          timeZone: config.timezone,
+          hourCycle: "h23",
+          hour: "numeric",
+        }).formatToParts(new Date());
+        hour = Number(parts.find((p) => p.type === "hour")!.value);
+      } else {
+        hour = this.deps.getCurrentHour?.() ?? new Date().getHours();
+      }
       if (
         !isWithinActiveHours(
           hour,
@@ -211,7 +377,10 @@ export class HeartbeatService {
           },
           "Outside active hours, skipping",
         );
-        this.scheduleNextRun(config.intervalMs);
+        if (runId) skipHeartbeatRun(runId, "outside_active_hours");
+        if (!this.cronMode) {
+          this.scheduleNextRun(config.intervalMs);
+        }
         return false;
       }
     }
@@ -219,10 +388,14 @@ export class HeartbeatService {
     // Overlap prevention
     if (this.activeRun) {
       log.debug("Previous heartbeat run still active, skipping");
+      if (runId) skipHeartbeatRun(runId, "overlap");
       return false;
     }
 
-    const run = this.executeRun();
+    if (!runId) {
+      runId = insertPendingHeartbeatRun(scheduledFor);
+    }
+    const run = this.executeRun(runId, scheduledFor);
     this.activeRun = run;
     // Clear activeRun once executeRun finishes. On timeout, runOnce releases
     // activeRun separately (see catch block below) so future runs aren't
@@ -252,16 +425,39 @@ export class HeartbeatService {
       // Release activeRun so the overlap guard doesn't permanently block
       // future heartbeat runs when executeRun hangs past the timeout.
       this.activeRun = null;
+      const transitioned = runId
+        ? completeHeartbeatRun(runId, {
+            status: "timeout",
+            error: "Heartbeat execution exceeded the 30-minute timeout",
+          })
+        : false;
+      if (transitioned) {
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
+          title: "Heartbeat Timed Out",
+          summary: "Heartbeat execution exceeded the 30-minute timeout.",
+          dedupKey: `heartbeat:timeout:${today}`,
+          priority: 55,
+          urgency: "high",
+        }).catch(() => {});
+      }
     } finally {
       clearTimeout(timerId);
       this._lastRunAt = Date.now();
-      this.scheduleNextRun(getConfig().heartbeat.intervalMs);
+      if (!this.cronMode) {
+        this.scheduleNextRun(getConfig().heartbeat.intervalMs);
+      }
     }
     return true;
   }
 
   private scheduleNextRun(intervalMs: number): void {
+    if (this._pendingRunId) {
+      supersedePendingRun(this._pendingRunId);
+    }
     this._nextRunAt = Date.now() + intervalMs;
+    this._pendingRunId = insertPendingHeartbeatRun(this._nextRunAt);
   }
 
   /**
@@ -274,11 +470,25 @@ export class HeartbeatService {
         await import("../credential-health/credential-health-service.js");
       const report = await checkAllCredentials();
       if (report.unhealthy.length > 0) {
-        await this.notifyUnhealthyCredentials(report.unhealthy);
-        // Only block providers for hard-failure statuses — expiring and ping_failed
-        // are transient/still-usable and should not disable provider tools.
-        // missing_scopes is a hard failure because required scopes are absent and
-        // provider tools will predictably fail.
+        // Filter out unreachable results — CES wake/startup blips should not
+        // produce user-facing credential alerts. Only actionable failures notify.
+        const notifiable = report.unhealthy.filter(
+          (r) => r.status !== "unreachable",
+        );
+        const unreachableCount = report.unhealthy.length - notifiable.length;
+        if (unreachableCount > 0) {
+          log.warn(
+            { unreachableCount },
+            "Credential backend unreachable — skipping health alerts for affected providers",
+          );
+        }
+        if (notifiable.length > 0) {
+          await this.notifyUnhealthyCredentials(notifiable);
+        }
+        // Only block providers for hard-failure statuses — expiring, ping_failed,
+        // and unreachable are transient/still-usable and should not disable
+        // provider tools. missing_scopes is a hard failure because required
+        // scopes are absent and provider tools will predictably fail.
         const hardFailureStatuses = new Set([
           "revoked",
           "missing_token",
@@ -355,6 +565,10 @@ export class HeartbeatService {
             missingScopes: result.missingScopes,
           },
           routingIntent: "single_channel",
+          conversationMetadata: {
+            source: "heartbeat",
+            groupId: "system:background",
+          },
         });
       } catch (err) {
         log.error(
@@ -365,14 +579,20 @@ export class HeartbeatService {
     }
   }
 
-  private async executeRun(): Promise<void> {
+  private async executeRun(runId: string, scheduledFor: number): Promise<void> {
     log.info("Running heartbeat");
 
+    startHeartbeatRun(runId);
+
+    const latenessMs = Date.now() - scheduledFor;
+    const LATE_THRESHOLD_MS = 5 * 60 * 1000;
+
     // Credential health check — surface broken credentials proactively
     // before the LLM heartbeat prompt runs. Returns unhealthy provider
     // names so the prompt can instruct the LLM to skip those providers.
     const unhealthyProviders = await this.runCredentialHealthCheck();
 
+    let conversationId: string | undefined;
     try {
       const checklist = this.readChecklist();
       const { prompt, includedReengagement } = this.buildPrompt(
@@ -387,6 +607,7 @@ export class HeartbeatService {
         origin: "heartbeat",
         systemHint: "Heartbeat",
       });
+      conversationId = conversation.id;
 
       this.deps.onConversationCreated?.({
         conversationId: conversation.id,
@@ -407,50 +628,78 @@ export class HeartbeatService {
 
       log.info({ conversationId: conversation.id }, "Heartbeat completed");
 
-      let title = "Heartbeat";
-      try {
-        const row = getConversation(conversation.id);
-        if (row?.title && row.title !== GENERATING_TITLE) {
-          title = row.title;
+      const transitioned = completeHeartbeatRun(runId, {
+        status: "ok",
+        conversationId,
+      });
+
+      if (transitioned) {
+        let title = "Heartbeat";
+        try {
+          const row = getConversation(conversation.id);
+          if (row?.title && row.title !== GENERATING_TITLE) {
+            title = row.title;
+          }
+        } catch {
+          // Best-effort; fall back to generic title.
         }
-      } catch {
-        // Best-effort; fall back to generic title.
-      }
 
-      const today = new Date().toISOString().split("T")[0];
-      void emitFeedEvent({
-        source: "assistant",
-        title,
-        summary: "Periodic check completed. Tap to see details.",
-        dedupKey: `heartbeat:ok:${today}`,
-        priority: 30,
-      }).catch((err) => {
-        log.warn(
-          { err, conversationId: conversation.id },
-          "Failed to emit heartbeat feed event",
-        );
-      });
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
+          title,
+          summary: "Periodic check completed. Tap to see details.",
+          dedupKey: `heartbeat:ok:${today}`,
+          priority: 30,
+        }).catch((err) => {
+          log.warn(
+            { err, conversationId: conversation.id },
+            "Failed to emit heartbeat feed event",
+          );
+        });
+
+        if (latenessMs > LATE_THRESHOLD_MS) {
+          const lateMinutes = Math.round(latenessMs / 60_000);
+          void emitFeedEvent({
+            source: "assistant",
+            title: "Heartbeat Ran Late",
+            summary: `Heartbeat ran ${lateMinutes} minutes late (scheduled for ${new Date(scheduledFor).toLocaleTimeString()}).`,
+            dedupKey: `heartbeat:late:${today}`,
+            priority: 45,
+            urgency: "medium",
+          }).catch(() => {});
+        }
+      }
     } catch (err) {
       log.error({ err }, "Heartbeat failed");
-      try {
-        this.deps.alerter({
-          type: "heartbeat_alert",
+
+      const transitioned = completeHeartbeatRun(runId, {
+        status: "error",
+        conversationId,
+        error: err instanceof Error ? err.message : String(err),
+      });
+
+      if (transitioned) {
+        try {
+          this.deps.alerter({
+            type: "heartbeat_alert",
+            title: "Heartbeat Failed",
+            body: err instanceof Error ? err.message : String(err),
+          });
+        } catch (alertErr) {
+          log.error({ alertErr }, "Failed to broadcast heartbeat alert");
+        }
+
+        const today = new Date().toISOString().split("T")[0];
+        void emitFeedEvent({
+          source: "assistant",
           title: "Heartbeat Failed",
-          body: err instanceof Error ? err.message : String(err),
-        });
-      } catch (alertErr) {
-        log.error({ alertErr }, "Failed to broadcast heartbeat alert");
+          summary: `Heartbeat check failed: ${(err instanceof Error ? err.message : String(err)).slice(0, 200)}`,
+          dedupKey: `heartbeat:fail:${today}`,
+          priority: 55,
+          urgency: "high",
+        }).catch(() => {});
       }
-
-      const today = new Date().toISOString().split("T")[0];
-      void emitFeedEvent({
-        source: "assistant",
-        title: "Heartbeat",
-        summary: "Heartbeat check failed. Check logs for details.",
-        dedupKey: `heartbeat:fail:${today}`,
-        priority: 55,
-        urgency: "medium",
-      }).catch(() => {});
     }
   }
 

package/src/home/__tests__/feed-writer.test.ts

@@ -18,8 +18,6 @@ import {
   test,
 } from "bun:test";
 
-import { DAEMON_INTERNAL_ASSISTANT_ID } from "../../runtime/assistant-scope.js";
-
 // ─── assistantEventHub mock ────────────────────────────────────────────
 // We spy on `publish` so the SSE-publish test can assert the writer
 // fires a `home_feed_updated` event with the correct `newItemCount`.
@@ -651,14 +649,12 @@ describe("feed-writer", () => {
       // Inspect the LAST publish — it reflects the final on-disk state.
       const lastCall = publishSpy.mock.calls[publishSpy.mock.calls.length - 1]!;
       const event = lastCall[0] as {
-        assistantId: string;
         message: {
           type: string;
           updatedAt: string;
           newItemCount: number;
         };
       };
-      expect(event.assistantId).toBe(DAEMON_INTERNAL_ASSISTANT_ID);
       expect(event.message.type).toBe("home_feed_updated");
       expect(event.message.newItemCount).toBe(2);
       expect(Number.isNaN(Date.parse(event.message.updatedAt))).toBe(false);

package/src/home/__tests__/post-connect-feed.test.ts

@@ -0,0 +1,99 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ─── assistantEventHub mock ────────────────────────────────────────────
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: {
+    publish: publishSpy,
+    subscribe: () => () => {},
+  },
+}));
+
+const { emitPostConnectNudge } = await import("../post-connect-feed.js");
+const { readHomeFeed } = await import("../feed-writer.js");
+
+// ─── tmpdir workspace lifecycle ────────────────────────────────────────
+
+let workspaceDir: string;
+let origWorkspaceDir: string | undefined;
+
+beforeEach(() => {
+  workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pcf-"));
+  origWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+  publishSpy.mockClear();
+});
+
+afterEach(() => {
+  if (origWorkspaceDir === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = origWorkspaceDir;
+  }
+  try {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  } catch {
+    // best-effort
+  }
+});
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe("emitPostConnectNudge", () => {
+  test("emits a nudge feed item for google", async () => {
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(1);
+
+    const item = feed.items[0]!;
+    expect(item.id).toBe("connect-nudge:google");
+    expect(item.type).toBe("nudge");
+    expect(item.source).toBe("gmail");
+    expect(item.title).toContain("Gmail connected");
+    expect(item.actions).toHaveLength(2);
+    expect(item.actions![0]!.label).toBe("Triage my inbox");
+    expect(item.actions![1]!.label).toBe("Set up daily digest");
+    expect(item.expiresAt).toBeDefined();
+    expect(item.author).toBe("platform");
+  });
+
+  test("no-ops for non-email services", async () => {
+    await emitPostConnectNudge("slack");
+    await emitPostConnectNudge("notion");
+    await emitPostConnectNudge("linear");
+
+    const feed = readHomeFeed();
+    expect(feed.items).toHaveLength(0);
+  });
+
+  test("reconnecting appends a second nudge (same-author nudges don't deduplicate)", async () => {
+    await emitPostConnectNudge("google");
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    // Same-author (platform) same-source nudges both persist —
+    // the feed writer's author-resolution only handles cross-author
+    // replacement. In practice, reconnects are rare and the 7-day
+    // expiry prevents buildup.
+    expect(feed.items).toHaveLength(2);
+    expect(feed.items.every((i) => i.id === "connect-nudge:google")).toBe(true);
+  });
+
+  test("nudge expires after 7 days", async () => {
+    await emitPostConnectNudge("google");
+
+    const feed = readHomeFeed();
+    const item = feed.items[0]!;
+    const created = new Date(item.createdAt).getTime();
+    const expires = new Date(item.expiresAt!).getTime();
+    const sevenDaysMs = 7 * 24 * 60 * 60 * 1000;
+
+    // Allow 1 second tolerance for test execution time
+    expect(Math.abs(expires - created - sevenDaysMs)).toBeLessThan(1000);
+  });
+});