@vellumai/assistant 0.8.11 → 0.8.12-staging.1

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

@@ -0,0 +1,114 @@
+import { describe, expect, mock, test } from "bun:test";
+
+// ─── Mocks ─────────────────────────────────────────────────────────────
+
+let greetingRefreshed = false;
+let promptsRefreshed = false;
+let greetingCalls = 0;
+let promptsCalls = 0;
+let greetingGate: Promise<void> = Promise.resolve();
+
+mock.module("../home-greeting.js", () => ({
+  refreshPersonalizedGreeting: async () => {
+    greetingCalls++;
+    await greetingGate;
+    return greetingRefreshed;
+  },
+}));
+
+mock.module("../suggested-prompts.js", () => ({
+  refreshAssistantSuggestedPrompts: async () => {
+    promptsCalls++;
+    return promptsRefreshed;
+  },
+}));
+
+const publishSpy = mock<(event: unknown) => Promise<void>>(async () => {});
+mock.module("../../runtime/assistant-event-hub.js", () => ({
+  assistantEventHub: { publish: publishSpy },
+}));
+
+mock.module("../../runtime/assistant-event.js", () => ({
+  buildAssistantEvent: (e: unknown) => e,
+}));
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+const { revalidateHomeContentInBackground } =
+  await import("../home-content-refresh.js");
+
+async function settle(): Promise<void> {
+  // Let the fire-and-forget revalidation chain run to completion.
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+// ─── Tests ─────────────────────────────────────────────────────────────
+
+describe("revalidateHomeContentInBackground", () => {
+  test("publishes home_feed_updated when content was refreshed", async () => {
+    publishSpy.mockClear();
+    greetingRefreshed = true;
+    promptsRefreshed = false;
+
+    revalidateHomeContentInBackground();
+    await settle();
+
+    expect(publishSpy).toHaveBeenCalledTimes(1);
+    expect(publishSpy.mock.calls[0]?.[0]).toMatchObject({
+      type: "home_feed_updated",
+    });
+  });
+
+  test("does not publish when both caches were fresh", async () => {
+    publishSpy.mockClear();
+    greetingRefreshed = false;
+    promptsRefreshed = false;
+
+    revalidateHomeContentInBackground();
+    await settle();
+
+    expect(publishSpy).not.toHaveBeenCalled();
+  });
+
+  test("concurrent calls share a single in-flight revalidation", async () => {
+    greetingCalls = 0;
+    promptsCalls = 0;
+    greetingRefreshed = false;
+    promptsRefreshed = false;
+
+    let release!: () => void;
+    greetingGate = new Promise((resolve) => {
+      release = resolve;
+    });
+
+    revalidateHomeContentInBackground();
+    revalidateHomeContentInBackground();
+    revalidateHomeContentInBackground();
+
+    release();
+    greetingGate = Promise.resolve();
+    await settle();
+
+    expect(greetingCalls).toBe(1);
+    expect(promptsCalls).toBe(1);
+  });
+
+  test("a completed run allows a later revalidation", async () => {
+    greetingCalls = 0;
+    greetingRefreshed = false;
+    promptsRefreshed = false;
+
+    revalidateHomeContentInBackground();
+    await settle();
+    revalidateHomeContentInBackground();
+    await settle();
+
+    expect(greetingCalls).toBe(2);
+  });
+});

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

@@ -4,6 +4,25 @@ import { afterEach, describe, expect, mock, test } from "bun:test";
 
 const mockIntegrationSummary = "Gmail ✓ | Slack ✓ | Twilio ✗ | Telegram ✗";
 let mockSidechainText = "";
+let sidechainCalls = 0;
+
+// In-memory stand-in for the memory_checkpoints table so the cache
+// round-trips without a real database.
+const checkpointStore = new Map<string, string>();
+let checkpointWritesShouldThrow = false;
+
+mock.module("../../memory/checkpoints.js", () => ({
+  getMemoryCheckpoint: (key: string) => checkpointStore.get(key) ?? null,
+  setMemoryCheckpoint: (key: string, value: string) => {
+    if (checkpointWritesShouldThrow) {
+      throw new Error("synthetic checkpoint write failure");
+    }
+    checkpointStore.set(key, value);
+  },
+  deleteMemoryCheckpoint: (key: string) => {
+    checkpointStore.delete(key);
+  },
+}));
 
 mock.module("../../schedule/integration-status.js", () => ({
   formatIntegrationSummary: async () => mockIntegrationSummary,
@@ -41,7 +60,10 @@ mock.module("../../prompts/system-prompt.js", () => ({
 }));
 
 mock.module("../../runtime/btw-sidechain.js", () => ({
-  runBtwSidechain: async () => ({ text: mockSidechainText }),
+  runBtwSidechain: async () => {
+    sidechainCalls++;
+    return { text: mockSidechainText };
+  },
 }));
 
 mock.module("../../runtime/assistant-event.js", () => ({
@@ -62,8 +84,10 @@ const {
 
 describe("getSuggestedPrompts", () => {
   afterEach(() => {
+    checkpointWritesShouldThrow = false;
     invalidateAssistantSuggestedPromptsCache();
     mockSidechainText = "";
+    sidechainCalls = 0;
   });
 
   test("returns empty array before cache is populated", async () => {
@@ -98,12 +122,17 @@ describe("getSuggestedPrompts", () => {
     expect(await getSuggestedPrompts()).toEqual([]);
   });
 
-  test("handles empty LLM response gracefully", async () => {
+  test("handles empty LLM response gracefully and caches the empty result", async () => {
     mockSidechainText = "";
 
-    await refreshAssistantSuggestedPrompts();
-    const prompts = await getSuggestedPrompts();
-    expect(prompts).toEqual([]);
+    expect(await refreshAssistantSuggestedPrompts()).toBe(false);
+    expect(await getSuggestedPrompts()).toEqual([]);
+
+    // The empty result is cached: the next refresh within the TTL must
+    // not hit the LLM again (prevents a generation loop on every Home
+    // feed GET while the model returns nothing usable).
+    expect(await refreshAssistantSuggestedPrompts()).toBe(false);
+    expect(sidechainCalls).toBe(1);
   });
 
   test("handles malformed LLM response gracefully", async () => {
@@ -113,4 +142,56 @@ describe("getSuggestedPrompts", () => {
     const prompts = await getSuggestedPrompts();
     expect(prompts).toEqual([]);
   });
+
+  test("refresh reports whether new content was generated", async () => {
+    mockSidechainText = JSON.stringify([
+      { label: "Do stuff", prompt: "Do stuff for me" },
+    ]);
+
+    expect(await refreshAssistantSuggestedPrompts()).toBe(true);
+    // Cache is fresh — second refresh must not hit the LLM again.
+    expect(await refreshAssistantSuggestedPrompts()).toBe(false);
+    expect(sidechainCalls).toBe(1);
+  });
+
+  test("refresh reports false when the cache write fails", async () => {
+    mockSidechainText = JSON.stringify([
+      { label: "Do stuff", prompt: "Do stuff for me" },
+    ]);
+    checkpointWritesShouldThrow = true;
+
+    // The generation succeeded but nothing was cached, so the caller must
+    // not announce fresh content (clients would refetch into a cache miss
+    // and re-trigger generation on every Home load).
+    expect(await refreshAssistantSuggestedPrompts()).toBe(false);
+    expect(await getSuggestedPrompts()).toEqual([]);
+  });
+
+  test("refresh regenerates after invalidation", async () => {
+    mockSidechainText = JSON.stringify([
+      { label: "Do stuff", prompt: "Do stuff for me" },
+    ]);
+
+    await refreshAssistantSuggestedPrompts();
+    invalidateAssistantSuggestedPromptsCache();
+
+    expect(await refreshAssistantSuggestedPrompts()).toBe(true);
+    expect(sidechainCalls).toBe(2);
+  });
+
+  test("cache survives across module state (checkpoint-backed)", async () => {
+    mockSidechainText = JSON.stringify([
+      { label: "Persisted", prompt: "I came from the checkpoint store" },
+    ]);
+
+    await refreshAssistantSuggestedPrompts();
+    // Simulate the read path a fresh daemon would take: the prompts come
+    // back from the checkpoint store, not module-local memory.
+    expect(checkpointStore.get("home:suggested_prompts:json")).toContain(
+      "Persisted",
+    );
+    const prompts = await getSuggestedPrompts();
+    expect(prompts).toHaveLength(1);
+    expect(prompts[0]!.label).toBe("Persisted");
+  });
 });

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

@@ -1,52 +1,64 @@
 /**
- * Background refresh timer for LLM-generated home page content.
+ * On-demand revalidation 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).
+ * The personalized greeting and assistant-generated suggestion prompts
+ * are served from caches (see `home-greeting-cache.ts` and
+ * `suggested-prompts.ts`). The GET handler stays read-only; when a
+ * client fetches the home feed it calls `revalidateHomeContentInBackground()`
+ * fire-and-forget, which regenerates whichever caches are stale and
+ * publishes a `home_feed_updated` event when fresh content lands so
+ * connected clients refetch and the personalized content swaps in.
  *
- * Call `startHomeContentRefresh()` once during daemon startup; the
- * timer handles periodic re-generation automatically.
+ * This keeps LLM cost proportional to actual Home usage: nothing
+ * generates at daemon startup or on a timer, and the per-cache TTLs
+ * (4 hours each) bound how often a regeneration can happen.
  */
 
+import { buildAssistantEvent } from "../runtime/assistant-event.js";
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
 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 inFlight: Promise<void> | null = null;
 
-let refreshTimer: ReturnType<typeof setInterval> | null = null;
-
-async function refreshAll(): Promise<void> {
-  await Promise.all([
+async function revalidateAll(): Promise<void> {
+  const [greetingRefreshed, promptsRefreshed] = 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"),
-  );
+  if (!greetingRefreshed && !promptsRefreshed) {
+    return;
+  }
 
-  refreshTimer = setInterval(() => {
-    void refreshAll().catch((err) =>
-      log.warn({ err }, "Periodic home content refresh failed"),
-    );
-  }, REFRESH_INTERVAL_MS);
+  await assistantEventHub.publish(
+    buildAssistantEvent({
+      type: "home_feed_updated",
+      updatedAt: new Date().toISOString(),
+      newItemCount: 0,
+    }),
+  );
 }
 
-export function stopHomeContentRefresh(): void {
-  if (refreshTimer) {
-    clearInterval(refreshTimer);
-    refreshTimer = null;
+/**
+ * Regenerate stale home content in the background. Returns immediately;
+ * callers (the home feed GET handler) must not await generation. Both
+ * refreshers no-op when their cache is fresh, so calling this on every
+ * feed fetch is cheap — at most one generation per cache TTL window.
+ * Concurrent calls share a single in-flight revalidation.
+ */
+export function revalidateHomeContentInBackground(): void {
+  if (inFlight) {
+    return;
   }
+  inFlight = revalidateAll()
+    .catch((err) => {
+      log.warn({ err }, "Home content revalidation failed");
+    })
+    .finally(() => {
+      inFlight = null;
+    });
 }

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

@@ -79,14 +79,21 @@ export function getCachedHomeGreeting(): string | null {
   }
 }
 
-export function setCachedHomeGreeting(text: string): void {
+/**
+ * Persist a freshly generated greeting. Returns `true` when the cache
+ * write landed; `false` on failure so callers don't report fresh content
+ * that the next read cannot serve.
+ */
+export function setCachedHomeGreeting(text: string): boolean {
   try {
     const hash = computeIdentityContentHash();
     const now = String(Date.now());
     setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
     setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
     setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
+    return true;
   } catch {
     // Cache write failure is non-fatal — next request will regenerate.
+    return false;
   }
 }

package/src/home/home-greeting.ts

@@ -6,9 +6,11 @@
  * caches the result for 4 hours (busted when identity files change).
  *
  * The GET handler reads only from cache (`getPersonalizedGreeting`).
- * Generation runs in the background via `refreshPersonalizedGreeting`,
- * called at daemon startup and periodically by the home-content
- * refresh timer.
+ * Generation runs on demand via `refreshPersonalizedGreeting`, invoked
+ * fire-and-forget by the home-content revalidation coordinator when a
+ * client fetches the home feed and the cache is stale (see
+ * `home-content-refresh.ts`). Nothing generates at daemon startup or on
+ * a timer — LLM cost is only incurred when a user actually views Home.
  */
 
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
@@ -37,13 +39,14 @@ export function getPersonalizedGreeting(): string | null {
 
 /**
  * Generate a personalized greeting via LLM and write it to cache.
- * No-ops when the cache is still fresh. Intended for background
- * invocation (daemon startup / periodic refresh), not the GET path.
+ * No-ops when the cache is still fresh. Intended for fire-and-forget
+ * background invocation, not the GET path. Returns `true` when a new
+ * greeting was generated and cached.
  */
-export async function refreshPersonalizedGreeting(): Promise<void> {
+export async function refreshPersonalizedGreeting(): Promise<boolean> {
   const cached = getCachedHomeGreeting();
   if (cached) {
-    return;
+    return false;
   }
 
   try {
@@ -52,7 +55,7 @@ export async function refreshPersonalizedGreeting(): Promise<void> {
 
     const provider = await getConfiguredProvider("homeGreeting");
     if (!provider) {
-      return;
+      return false;
     }
 
     const systemPrompt = buildSystemPrompt({
@@ -77,9 +80,10 @@ export async function refreshPersonalizedGreeting(): Promise<void> {
 
     const text = result.text.trim();
     if (text) {
-      setCachedHomeGreeting(text);
+      return setCachedHomeGreeting(text);
     }
   } catch (err) {
     log.warn({ err }, "Failed to generate personalized home greeting");
   }
+  return false;
 }

package/src/home/suggested-prompts.ts

@@ -3,13 +3,25 @@
  *
  * Returns an array of `SuggestedPrompt` items shown at the top of the
  * Home page as conversation starters. All prompts are generated by the
- * assistant based on the user's connected services and context —
- * read from an in-memory cache in the GET path; generation runs in
- * the background via `refreshAssistantSuggestedPrompts`.
+ * assistant based on the user's connected services and context — read
+ * from a checkpoint-backed cache in the GET path. Generation runs on
+ * demand via `refreshAssistantSuggestedPrompts`, invoked fire-and-forget
+ * by the home-content revalidation coordinator when a client fetches the
+ * home feed and the cache is stale (see `home-content-refresh.ts`).
+ * Nothing generates at daemon startup or on a timer.
+ *
+ * The cache persists in the `memory_checkpoints` table so a daemon
+ * restart does not force a regeneration. OAuth connect/disconnect paths
+ * invalidate it explicitly so suggestions track integration state.
  */
 
 import { resolveCallSiteConfig } from "../config/llm-resolver.js";
 import { getConfig } from "../config/loader.js";
+import {
+  deleteMemoryCheckpoint,
+  getMemoryCheckpoint,
+  setMemoryCheckpoint,
+} from "../memory/checkpoints.js";
 import { buildSystemPrompt } from "../prompts/system-prompt.js";
 import { getConfiguredProvider } from "../providers/provider-send-message.js";
 import { buildAssistantEvent } from "../runtime/assistant-event.js";
@@ -22,14 +34,46 @@ import type { SuggestedPrompt } from "./feed-types.js";
 const log = getLogger("suggested-prompts");
 
 const LLM_SUGGESTIONS_TIMEOUT_MS = 5_000;
-const LLM_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const LLM_CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+
+const CHECKPOINT_KEY_JSON = "home:suggested_prompts:json";
+const CHECKPOINT_KEY_TIMESTAMP = "home:suggested_prompts:cached_at";
 
 // ---------------------------------------------------------------------------
-// In-memory cache for LLM-generated suggestions
+// Checkpoint-backed cache for LLM-generated suggestions
 // ---------------------------------------------------------------------------
 
-let cachedLLMPrompts: SuggestedPrompt[] = [];
-let cachedLLMPromptsAt = 0;
+function readCachedPrompts(): SuggestedPrompt[] | null {
+  try {
+    const json = getMemoryCheckpoint(CHECKPOINT_KEY_JSON);
+    const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+    if (!json || !timestampStr) {
+      return null;
+    }
+    const cachedAt = Number(timestampStr);
+    if (isNaN(cachedAt) || Date.now() - cachedAt > LLM_CACHE_TTL_MS) {
+      return null;
+    }
+    const parsed = JSON.parse(json);
+    if (!Array.isArray(parsed)) {
+      return null;
+    }
+    return parsed as SuggestedPrompt[];
+  } catch {
+    return null;
+  }
+}
+
+function writeCachedPrompts(prompts: SuggestedPrompt[]): boolean {
+  try {
+    setMemoryCheckpoint(CHECKPOINT_KEY_JSON, JSON.stringify(prompts));
+    setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, String(Date.now()));
+    return true;
+  } catch {
+    // Cache write failure is non-fatal — the next refresh regenerates.
+    return false;
+  }
+}
 
 /**
  * Return cached assistant-generated prompts. No LLM calls happen in
@@ -37,22 +81,23 @@ let cachedLLMPromptsAt = 0;
  * background refresh populates the cache.
  */
 export async function getSuggestedPrompts(): Promise<SuggestedPrompt[]> {
-  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
-    return [...cachedLLMPrompts];
-  }
-  return [];
+  return readCachedPrompts() ?? [];
 }
 
 /**
- * Drops the in-memory suggestion cache so the next background refresh
- * regenerates prompts with current integration state.
+ * Drops the suggestion cache so the next on-demand refresh regenerates
+ * prompts with current integration state.
  *
  * Called from OAuth connect/disconnect paths so suggestions reflect the
- * new state within one reload instead of waiting for the 30-minute TTL.
+ * new state within one reload instead of waiting for the TTL.
  */
 export function invalidateAssistantSuggestedPromptsCache(): void {
-  cachedLLMPrompts = [];
-  cachedLLMPromptsAt = 0;
+  try {
+    deleteMemoryCheckpoint(CHECKPOINT_KEY_JSON);
+    deleteMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
+  } catch {
+    // Invalidation failure is non-fatal — the TTL still bounds staleness.
+  }
   assistantEventHub
     .publish(
       buildAssistantEvent({
@@ -70,21 +115,29 @@ export function invalidateAssistantSuggestedPromptsCache(): void {
 }
 
 /**
- * Generate LLM-based suggestion prompts and write them to the in-memory
- * cache. No-ops when the cache is still fresh. Intended for background
- * invocation (daemon startup / periodic refresh), not the GET path.
+ * Generate LLM-based suggestion prompts and write them to the cache.
+ * No-ops when the cache is still fresh. Intended for fire-and-forget
+ * background invocation, not the GET path. Returns `true` when a new
+ * batch was generated and cached.
  */
-export async function refreshAssistantSuggestedPrompts(): Promise<void> {
-  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
-    return;
+export async function refreshAssistantSuggestedPrompts(): Promise<boolean> {
+  if (readCachedPrompts() !== null) {
+    return false;
   }
 
   try {
     const llmPrompts = await generateAssistantPrompts();
-    cachedLLMPrompts = llmPrompts;
-    cachedLLMPromptsAt = Date.now();
+    // Cache empty results too — an empty or unparseable LLM response
+    // would otherwise leave the cache unpopulated and every Home feed
+    // GET would re-trigger generation until the TTL window closed.
+    // Only report success when the cache write landed AND there is new
+    // content — otherwise the coordinator would publish
+    // home_feed_updated for content the next GET cannot serve.
+    const wrote = writeCachedPrompts(llmPrompts);
+    return wrote && llmPrompts.length > 0;
   } catch (err) {
     log.warn({ err }, "Failed to refresh assistant suggested prompts");
+    return false;
   }
 }