@vellumai/assistant 0.7.1 → 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);
   }
 
   /**
@@ -383,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(
@@ -405,6 +607,7 @@ export class HeartbeatService {
         origin: "heartbeat",
         systemHint: "Heartbeat",
       });
+      conversationId = conversation.id;
 
       this.deps.onConversationCreated?.({
         conversationId: conversation.id,
@@ -425,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__/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);
+  });
+});

package/src/home/__tests__/relationship-state-writer.test.ts

@@ -432,6 +432,12 @@ describe("relationship-state-writer", () => {
       // Also sanity: it must be a real, recent date (not the epoch
       // sentinel we emit when stat fails).
       expect(Date.parse(first.hatchedDate)).toBeGreaterThan(0);
+      const sidecarPath = join(workspaceDir, "data", "hatched.json");
+      expect(existsSync(sidecarPath)).toBe(true);
+      const sidecar = JSON.parse(readFileSync(sidecarPath, "utf-8")) as {
+        hatchedAt: string;
+      };
+      expect(sidecar.hatchedAt).toBe(first.hatchedDate);
     });
 
     test("honors an explicit Hatched bullet in IDENTITY.md over file birthtime", async () => {
@@ -488,9 +494,10 @@ describe("relationship-state-writer", () => {
       expect(state.hatchedDate).toBe("2025-01-15T00:00:00.000Z");
     });
 
-    test("IDENTITY.md birthtime takes precedence over the sidecar", async () => {
-      // Seed a stale sidecar and then an IDENTITY.md without an
-      // explicit Hatched bullet — birthtime wins over the sidecar.
+    test("sidecar takes precedence over IDENTITY.md metadata", async () => {
+      // Seed an existing sidecar and then an IDENTITY.md without an
+      // explicit Hatched bullet — the persisted sidecar wins so the
+      // date remains stable across later identity edits.
       mkdirSync(join(workspaceDir, "data"), { recursive: true });
       writeFileSync(
         join(workspaceDir, "data", "hatched.json"),
@@ -500,12 +507,7 @@ describe("relationship-state-writer", () => {
       writeFile("IDENTITY.md", "- **Name:** Sage\n- **Role:** Assistant\n");
 
       const state = (await computeRelationshipState()) as RelationshipStateLike;
-      // The sidecar value is 2020-06-01 but IDENTITY.md was just
-      // written, so birthtime will be a much more recent date.
-      expect(state.hatchedDate).not.toBe("2020-06-01T00:00:00.000Z");
-      expect(Date.parse(state.hatchedDate)).toBeGreaterThan(
-        Date.parse("2020-06-01T00:00:00.000Z"),
-      );
+      expect(state.hatchedDate).toBe("2020-06-01T00:00:00.000Z");
     });
   });