@vellumai/assistant 0.8.2 → 0.8.4

package/src/heartbeat/heartbeat-service.ts

@@ -9,8 +9,6 @@ import {
   shouldLogDiskPressureBackgroundSkip,
 } from "../daemon/disk-pressure-background-gate.js";
 import type { HeartbeatAlert } from "../daemon/message-protocol.js";
-import { getConversation, getMessages } from "../memory/conversation-crud.js";
-import { GENERATING_TITLE } from "../memory/conversation-title-service.js";
 import { emitNotificationSignal } from "../notifications/emit-signal.js";
 import {
   GUARDIAN_PERSONA_TEMPLATE,
@@ -47,9 +45,6 @@ const DEFAULT_CHECKLIST = `- Check in with yourself. Read NOW.md. Is it still ac
 const EARLY_HEARTBEAT_THRESHOLD = 3;
 const REENGAGEMENT_COOLDOWN_MS = 18 * 60 * 60 * 1000; // 18 hours
 const HEARTBEAT_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
-const HEARTBEAT_ALERT_MARKER = "HEARTBEAT_ALERT";
-const HEARTBEAT_OK_MARKER = "HEARTBEAT_OK";
-const HEARTBEAT_ALERT_SUMMARY_MAX_CHARS = 700;
 
 // Stripped-comment form of the guardian persona scaffold. Computed
 // once at module load because stripping comment lines is deterministic
@@ -102,69 +97,6 @@ function recordReengagementTimestamp(): void {
   }
 }
 
-type HeartbeatDisposition = "alert" | "ok" | "unknown";
-
-function parseHeartbeatDisposition(text: string | null): HeartbeatDisposition {
-  if (!text) return "unknown";
-  const lines = text
-    .trim()
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter((line) => line.length > 0);
-  const lastLine = lines.at(-1);
-  if (lastLine === HEARTBEAT_ALERT_MARKER) return "alert";
-  if (lastLine === HEARTBEAT_OK_MARKER) return "ok";
-  return "unknown";
-}
-
-function stripHeartbeatDispositionMarkers(text: string): string {
-  return text
-    .replace(
-      new RegExp(
-        `(?:\\r?\\n)?\\s*(?:${HEARTBEAT_ALERT_MARKER}|${HEARTBEAT_OK_MARKER})\\s*$`,
-      ),
-      "",
-    )
-    .trim();
-}
-
-function truncateSummary(text: string, maxChars: number): string {
-  if (text.length <= maxChars) return text;
-  return `${text.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
-}
-
-function buildHeartbeatAlertSummary(text: string | null): string {
-  const summary = text ? stripHeartbeatDispositionMarkers(text) : "";
-  return truncateSummary(
-    summary || "Your assistant found something worth your attention.",
-    HEARTBEAT_ALERT_SUMMARY_MAX_CHARS,
-  );
-}
-
-function extractVisibleTextFromStoredMessageContent(raw: string): string {
-  try {
-    const parsed = JSON.parse(raw) as unknown;
-    if (typeof parsed === "string") return parsed;
-    if (!Array.isArray(parsed)) return "";
-    const texts: string[] = [];
-    for (const block of parsed) {
-      if (
-        block != null &&
-        typeof block === "object" &&
-        "type" in block &&
-        block.type === "text" &&
-        "text" in block &&
-        typeof block.text === "string"
-      ) {
-        texts.push(block.text);
-      }
-    }
-    return texts.join("\n").trim();
-  } catch {
-    return raw;
-  }
-}
-
 export interface HeartbeatDeps {
   alerter: (alert: HeartbeatAlert) => void;
   onConversationCreated?: (info: {
@@ -202,6 +134,9 @@ export class HeartbeatService {
   // Reset by resetTimer (guardian message), reconfigure, and stop. Force runs
   // bypass the cap and do not increment.
   private _consecutiveRuns = 0;
+  // Bumped every time the counter is reset so an in-flight run that finishes
+  // after a guardian message can detect the reset and skip its increment.
+  private _resetGeneration = 0;
 
   constructor(deps: HeartbeatDeps) {
     this.deps = deps;
@@ -360,6 +295,7 @@ export class HeartbeatService {
   /** Restart the timer with the latest config (e.g. after settings change). */
   reconfigure(): void {
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     this.configEpoch++;
     if (this._pendingRunId) {
       supersedePendingRun(this._pendingRunId);
@@ -384,6 +320,7 @@ export class HeartbeatService {
     // Counter resets even when the timer is null so a guardian message during
     // a stopped window still clears the count.
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     if (!this.timer) return;
     if (this.cronMode) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -404,6 +341,7 @@ export class HeartbeatService {
 
   async stop(): Promise<void> {
     this._consecutiveRuns = 0;
+    this._resetGeneration++;
     this.stopped = true;
     if (this.timer) {
       clearTimeout(this.timer as ReturnType<typeof setTimeout>);
@@ -552,6 +490,11 @@ export class HeartbeatService {
     }
     const run = this.executeRun(runId, scheduledFor);
     this.activeRun = run;
+    // Snapshot the reset generation so we can detect whether a reset (guardian
+    // message, reconfigure, stop) happened while this run was in flight. If it
+    // did, the counter was already zeroed and we must not undo that reset by
+    // incrementing in `finally`.
+    const startGeneration = this._resetGeneration;
     try {
       await run;
     } catch (err) {
@@ -561,7 +504,7 @@ export class HeartbeatService {
         this.activeRun = null;
       }
       this._lastRunAt = Date.now();
-      if (!force) {
+      if (!force && this._resetGeneration === startGeneration) {
         this._consecutiveRuns++;
       }
       if (!this.cronMode) {
@@ -699,66 +642,6 @@ export class HeartbeatService {
     }
   }
 
-  private getLatestAssistantMessage(
-    conversationId: string,
-  ): { id: string; text: string } | null {
-    try {
-      const messages = getMessages(conversationId);
-      for (let i = messages.length - 1; i >= 0; i--) {
-        const message = messages[i]!;
-        if (message.role !== "assistant") continue;
-        return {
-          id: message.id,
-          text: extractVisibleTextFromStoredMessageContent(message.content),
-        };
-      }
-    } catch (err) {
-      log.warn(
-        { err, conversationId },
-        "Failed to read heartbeat assistant message",
-      );
-    }
-    return null;
-  }
-
-  private async emitHeartbeatAlertNotification(params: {
-    runId: string;
-    conversationId: string;
-    messageId?: string;
-    conversationTitle: string;
-    summary: string;
-  }): Promise<void> {
-    const { emitNotificationSignal } =
-      await import("../notifications/emit-signal.js");
-
-    await emitNotificationSignal({
-      sourceEventName: "heartbeat.alert",
-      sourceChannel: "watcher",
-      sourceContextId: params.runId,
-      dedupeKey: `heartbeat:alert:${params.runId}`,
-      attentionHints: {
-        requiresAction: true,
-        urgency: "medium",
-        isAsyncBackground: true,
-        visibleInSourceNow: false,
-      },
-      contextPayload: {
-        title: "Heartbeat Alert",
-        summary: params.summary,
-        conversationTitle: params.conversationTitle,
-        conversationId: params.conversationId,
-        messageId: params.messageId,
-      },
-      routingIntent: "single_channel",
-      conversationAffinityHint: { vellum: params.conversationId },
-      conversationMetadata: {
-        source: "heartbeat",
-        groupId: "system:background",
-        conversationType: "background",
-      },
-    });
-  }
-
   private async executeRun(runId: string, scheduledFor: number): Promise<void> {
     log.info("Running heartbeat");
 
@@ -787,9 +670,9 @@ export class HeartbeatService {
     // The runner fires `onConversationCreated` synchronously after
     // bootstrap so the macOS sidebar gets the new conversation
     // immediately rather than waiting up to HEARTBEAT_TIMEOUT_MS for
-    // the LLM turn to finish. We forward to `deps.onConversationCreated`
-    // for every run; "silent OK" is enforced by NOT emitting any
-    // notification signal further down, not by hiding the conversation.
+    // the LLM turn to finish. If the model judges the run worth
+    // surfacing to the guardian, it calls the `notifications` skill
+    // directly — no in-band marker.
     let conversationId: string | undefined;
     const result = await runBackgroundJob({
       jobName: "heartbeat",
@@ -803,6 +686,7 @@ export class HeartbeatService {
       callSite: "heartbeatAgent",
       timeoutMs: HEARTBEAT_TIMEOUT_MS,
       origin: "heartbeat",
+      deferNotifications: true,
       onConversationCreated: (newConversationId) => {
         conversationId = newConversationId;
         this.deps.onConversationCreated?.({
@@ -821,62 +705,26 @@ export class HeartbeatService {
         "Heartbeat completed",
       );
 
-      // Mark the run record as ok and surface any disposition-driven
-      // alert the assistant decided to raise. The runner owns failure
-      // emission via `activity.failed`; success-side surfacing (alerts,
-      // late warnings) lives here so it can read the actual conversation
-      // contents.
+      // Mark the run record as ok. The runner owns failure emission via
+      // `activity.failed`; any user-facing alert the model decided to
+      // raise was emitted in-band via the `notifications` skill during
+      // the turn itself.
       const transitioned = completeHeartbeatRun(runId, {
         status: "ok",
         conversationId: result.conversationId,
       });
 
-      if (transitioned) {
-        let title = "Heartbeat";
-        try {
-          const row = getConversation(result.conversationId);
-          if (row?.title && row.title !== GENERATING_TITLE) {
-            title = row.title;
-          }
-        } catch {
-          // Best-effort; fall back to generic title.
-        }
-
-        const assistantMessage = this.getLatestAssistantMessage(
-          result.conversationId,
-        );
-        const disposition = parseHeartbeatDisposition(
-          assistantMessage?.text ?? null,
-        );
-        if (disposition === "alert") {
-          // Conversation was already surfaced via the runner's bootstrap
-          // callback above; alert just needs to emit the notification.
-          void this.emitHeartbeatAlertNotification({
+      if (transitioned && latenessMs > LATE_THRESHOLD_MS) {
+        const lateMinutes = Math.round(latenessMs / 60_000);
+        log.warn(
+          {
+            latenessMs,
+            lateMinutes,
+            scheduledFor,
             runId,
-            conversationId: result.conversationId,
-            messageId: assistantMessage?.id,
-            conversationTitle: title,
-            summary: buildHeartbeatAlertSummary(assistantMessage?.text ?? null),
-          }).catch((err) => {
-            log.warn(
-              { err, conversationId: result.conversationId },
-              "Failed to emit heartbeat alert notification",
-            );
-          });
-        }
-
-        if (latenessMs > LATE_THRESHOLD_MS) {
-          const lateMinutes = Math.round(latenessMs / 60_000);
-          log.warn(
-            {
-              latenessMs,
-              lateMinutes,
-              scheduledFor,
-              runId,
-            },
-            "Heartbeat ran late",
-          );
-        }
+          },
+          "Heartbeat ran late",
+        );
       }
       return;
     }
@@ -941,18 +789,14 @@ Do NOT attempt to use tools for these providers — they will fail. Skip any che
 </credential-status>`;
     }
 
-    prompt += `\n\n<heartbeat-disposition>
-This heartbeat runs frequently. Do not manufacture a report just because it ran.
-If there is nothing genuinely useful, actionable, or interesting to surface, keep the response brief and end with HEARTBEAT_OK.
-If there is something worth interrupting the guardian for, write a concise guardian-facing note first: what happened, why it matters, and the recommended next step. Address the guardian directly as "you"; do not write instructions to yourself or another intermediary. Then end with HEARTBEAT_ALERT. That note may be used as notification copy.
-After completing your review, end your response with one of:
-- HEARTBEAT_OK — if everything looks good, no action needed
-- HEARTBEAT_ALERT — if you found issues that need attention (describe them before this marker)
-</heartbeat-disposition>`;
+    const disposition = getConfig().heartbeat.disposition;
+    if (disposition) {
+      prompt += `\n\n<heartbeat-disposition>\n${disposition}\n</heartbeat-disposition>`;
+    }
 
     if (completedRunCount < EARLY_HEARTBEAT_THRESHOLD) {
       prompt += `\n\n<early-heartbeat>
-This is one of your first heartbeats. Your user hasn't heard from you yet and may not know you're here. Find something genuinely useful to share — a follow-up from a recent conversation, something you noticed, or a quick check-in. Lean toward HEARTBEAT_ALERT this time. First impressions matter.
+This is one of your first heartbeats. Your user hasn't heard from you yet and may not know you're here. Find something genuinely useful to share — a follow-up from a recent conversation, something you noticed, or a quick check-in. Lean toward surfacing it via the notifications skill this time. First impressions matter.
 </early-heartbeat>`;
     }
 

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

@@ -116,6 +116,28 @@ describe("feedItemSchema — valid minimal items", () => {
     expect(parsed.category).toBeUndefined();
     expect(parsed.metadata).toBeUndefined();
   });
+
+  test("noteworthy field passes through when present", () => {
+    const parsed = feedItemSchema.parse({
+      ...minimalNotification(),
+      noteworthy: true,
+    });
+    expect(parsed.noteworthy).toBe(true);
+  });
+
+  test("items without noteworthy field still parse (backward compat)", () => {
+    const parsed = feedItemSchema.parse(minimalNotification());
+    expect(parsed.noteworthy).toBeUndefined();
+  });
+
+  test("title is optional and may be omitted", () => {
+    const { title: _omitted, ...rest } = minimalNotification();
+    const parsed = feedItemSchema.parse(rest);
+    expect(parsed.title).toBeUndefined();
+    expect(parsed.summary).toBe(
+      "You mentioned wanting to review the onboarding designs.",
+    );
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -244,4 +266,22 @@ describe("parseFeedFile", () => {
       }),
     ).toThrow();
   });
+
+  test("accepts a file with a noteworthy item", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [{ ...minimalNotification(), noteworthy: true }],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items[0]?.noteworthy).toBe(true);
+  });
+
+  test("accepts a file whose items omit noteworthy (backward compat)", () => {
+    const parsed = parseFeedFile({
+      version: 2,
+      items: [minimalNotification()],
+      updatedAt: NOW_ISO,
+    });
+    expect(parsed.items[0]?.noteworthy).toBeUndefined();
+  });
 });

package/src/home/__tests__/suggested-prompts.test.ts

@@ -5,8 +5,6 @@ import { describe, expect, mock, test } from "bun:test";
 let mockConnectedProviders = new Set<string>();
 
 mock.module("../../oauth/oauth-store.js", () => ({
-  isProviderConnected: async (provider: string) =>
-    mockConnectedProviders.has(provider),
   listProviders: () => [
     { provider: "google" },
     { provider: "slack" },
@@ -16,6 +14,11 @@ mock.module("../../oauth/oauth-store.js", () => ({
   ],
 }));
 
+mock.module("../../schedule/integration-status.js", () => ({
+  isOAuthProviderConnected: async (provider: string) =>
+    mockConnectedProviders.has(provider),
+}));
+
 mock.module("../../util/logger.js", () => ({
   getLogger: () =>
     new Proxy({} as Record<string, unknown>, {
@@ -23,6 +26,34 @@ mock.module("../../util/logger.js", () => ({
     }),
 }));
 
+mock.module("../../config/loader.js", () => ({
+  getConfig: () => ({ llm: {} }),
+}));
+
+mock.module("../../config/llm-resolver.js", () => ({
+  resolveCallSiteConfig: () => ({ provider: "mock" }),
+}));
+
+mock.module("../../providers/provider-send-message.js", () => ({
+  getConfiguredProvider: async () => ({}),
+}));
+
+mock.module("../../prompts/persona-resolver.js", () => ({
+  resolvePersonaContext: () => ({
+    userPersona: null,
+    userSlug: null,
+    channelPersona: null,
+  }),
+}));
+
+mock.module("../../prompts/system-prompt.js", () => ({
+  buildSystemPrompt: () => "mock system prompt",
+}));
+
+mock.module("../../runtime/btw-sidechain.js", () => ({
+  runBtwSidechain: async () => ({ text: "" }),
+}));
+
 const { getSuggestedPrompts } = await import("../suggested-prompts.js");
 
 // ─── Tests ─────────────────────────────────────────────────────────────

package/src/home/feed-types.ts

@@ -89,7 +89,13 @@ export interface FeedItem {
   type: FeedItemType;
   /** Integer in [0, 100]; higher values sort earlier. */
   priority: number;
-  title: string;
+  /**
+   * Optional short header. Omit when the source did not supply one — the
+   * notification pipeline never manufactures a title from rendered copy
+   * (LLM-echoed bodies stutter against `summary`). Clients fall back to
+   * `summary` when rendering a row.
+   */
+  title?: string;
   summary: string;
   /** Event time (ISO-8601). */
   timestamp: string;
@@ -100,12 +106,21 @@ export interface FeedItem {
   actions?: FeedAction[];
   /** Visual urgency treatment — controls badge color independently of sort priority. */
   urgency?: FeedItemUrgency;
-  /** Optional conversation this feed item is associated with. */
+  /**
+   * Source conversation that emitted this notification, when known. Used by
+   * the "Go to Thread" affordance in the detail panel. Omitted when the
+   * source context is not a navigable conversation (scheduler job ids,
+   * watcher event ids, CLI tool-call ids).
+   */
   conversationId?: string;
   /** Server-driven detail panel descriptor; when present, the client opens this panel kind. */
   detailPanel?: FeedItemDetailPanel;
   /** Broad category for grouping and filtering feed items. */
   category?: FeedItemCategory;
+  /** True when this item represents an assistant-initiated share or a high-importance system event. Used by clients to split inbox vs activity surfaces. */
+  noteworthy?: boolean;
+  /** True when the assistant herself emitted this item (e.g. via the `notifications send` skill). Drives clients to swap the row's leading icon for the persona avatar; system-generated items keep the category icon. */
+  fromAssistant?: boolean;
   /** Arbitrary structured data the detail panel or other consumers can use. */
   metadata?: Record<string, unknown>;
   /** Internal: ISO-8601 writer-record time, used for ordering + TTL. */
@@ -198,7 +213,7 @@ export const feedItemSchema = z.object({
   id: z.string(),
   type: feedItemTypeSchema,
   priority: z.number().int().min(0).max(100),
-  title: z.string(),
+  title: z.string().optional(),
   summary: z.string(),
   timestamp: z.string(),
   status: feedItemStatusSchema.default("new"),
@@ -208,6 +223,8 @@ export const feedItemSchema = z.object({
   conversationId: z.string().optional(),
   detailPanel: feedItemDetailPanelSchema.optional(),
   category: feedItemCategorySchema.optional(),
+  noteworthy: z.boolean().optional(),
+  fromAssistant: z.boolean().optional(),
   metadata: z.record(z.string(), z.unknown()).optional(),
   createdAt: z.string(),
 });

package/src/home/home-content-refresh.ts

@@ -0,0 +1,52 @@
+/**
+ * Background refresh timer for LLM-generated home page content.
+ *
+ * Keeps the personalized greeting and assistant-generated suggestion
+ * prompts warm in their caches so the GET handler never triggers LLM
+ * calls or database writes (see `src/runtime/AGENTS.md` — GET handler
+ * idempotency rule).
+ *
+ * Call `startHomeContentRefresh()` once during daemon startup; the
+ * timer handles periodic re-generation automatically.
+ */
+
+import { getLogger } from "../util/logger.js";
+import { refreshPersonalizedGreeting } from "./home-greeting.js";
+import { refreshAssistantSuggestedPrompts } from "./suggested-prompts.js";
+
+const log = getLogger("home-content-refresh");
+
+const REFRESH_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+
+let refreshTimer: ReturnType<typeof setInterval> | null = null;
+
+async function refreshAll(): Promise<void> {
+  await Promise.all([
+    refreshPersonalizedGreeting(),
+    refreshAssistantSuggestedPrompts(),
+  ]);
+}
+
+/**
+ * Start periodic background refresh of home page LLM content.
+ * Runs an initial generation immediately (fire-and-forget) and
+ * schedules re-generation every 30 minutes.
+ */
+export function startHomeContentRefresh(): void {
+  void refreshAll().catch((err) =>
+    log.warn({ err }, "Initial home content refresh failed"),
+  );
+
+  refreshTimer = setInterval(() => {
+    void refreshAll().catch((err) =>
+      log.warn({ err }, "Periodic home content refresh failed"),
+    );
+  }, REFRESH_INTERVAL_MS);
+}
+
+export function stopHomeContentRefresh(): void {
+  if (refreshTimer) {
+    clearInterval(refreshTimer);
+    refreshTimer = null;
+  }
+}

package/src/home/home-greeting-cache.ts

@@ -0,0 +1,69 @@
+/**
+ * Caching layer for the LLM-generated personalized home greeting.
+ *
+ * The greeting (a short persona-flavored "here's what's been going on" line)
+ * is generated via `runBtwSidechain` and displayed at the top of the Home
+ * page. To avoid redundant LLM calls on every feed fetch, we cache the
+ * result for 4 hours with content-hash-based invalidation: when IDENTITY.md,
+ * SOUL.md, or the guardian persona change, the cache is busted.
+ *
+ * Storage uses the existing `memory_checkpoints` table (simple key-value store).
+ */
+
+import {
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../memory/checkpoints.js";
+import { computeIdentityContentHash } from "../runtime/routes/identity-intro-cache.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+const CHECKPOINT_KEY_TEXT = "home:greeting:text";
+const CHECKPOINT_KEY_HASH = "home:greeting:content_hash";
+const CHECKPOINT_KEY_TIMESTAMP = "home:greeting:cached_at";
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function getCachedHomeGreeting(): string | null {
+  try {
+    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
+    const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
+    const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+
+    if (!text || !hash || !timestampStr) {
+      return null;
+    }
+
+    const cachedAt = Number(timestampStr);
+    if (isNaN(cachedAt) || Date.now() - cachedAt > CACHE_TTL_MS) {
+      return null;
+    }
+
+    const currentHash = computeIdentityContentHash();
+    if (currentHash !== hash) {
+      return null;
+    }
+
+    return text;
+  } catch {
+    return null;
+  }
+}
+
+export function setCachedHomeGreeting(text: string): void {
+  try {
+    const hash = computeIdentityContentHash();
+    const now = String(Date.now());
+    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
+    setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
+    setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
+  } catch {
+    // Cache write failure is non-fatal — next request will regenerate.
+  }
+}