@vellumai/assistant 0.8.11 → 0.8.12-staging.2

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;
   }
 }
 

package/src/ipc/routes/trust-rules.test.ts

@@ -1,123 +1,117 @@
 /**
  * Unit tests for the trust rule IPC proxy routes.
- *
- * Covers:
- * - trust_rules_list: no params, tool filter, include_all, origin filter
- * - error path: non-OK gateway response surfaces body .error message
  */
 
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
-// ---------------------------------------------------------------------------
-// Mocks — must be defined before importing the module under test
-// ---------------------------------------------------------------------------
-
-mock.module("../../config/env.js", () => ({
-  getGatewayInternalBaseUrl: () => "http://localhost:7822",
-}));
-
-type MockResponse = {
-  ok: boolean;
-  status: number;
-  json: () => Promise<unknown>;
+type IpcCall = {
+  method: string;
+  params?: Record<string, unknown>;
 };
 
-let mockFetchResponse: MockResponse = {
-  ok: true,
-  status: 200,
-  json: async () => ({ rules: [] }),
-};
-
-let capturedFetchCalls: Array<{ url: string; init?: RequestInit }> = [];
+let ipcCalls: IpcCall[] = [];
+let ipcResult: unknown = { rules: [] };
+let ipcError: Error | undefined;
 
-const mockFetch = mock(async (url: string, init?: RequestInit) => {
-  capturedFetchCalls.push({ url, init });
-  return mockFetchResponse;
-});
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcError) throw ipcError;
+    return ipcResult;
+  },
+);
 
-global.fetch = mockFetch as unknown as typeof fetch;
-
-// ---------------------------------------------------------------------------
-// Import module under test AFTER mocks are set up
-// ---------------------------------------------------------------------------
+mock.module("../gateway-client.js", () => ({
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
 
 import { ROUTES as trustRuleRoutes } from "../../runtime/routes/trust-rules-routes.js";
 
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
 function findRoute(method: string) {
   const route = trustRuleRoutes.find((r) => r.operationId === method);
   if (!route) throw new Error(`Route not found: ${method}`);
   return route;
 }
 
-// ---------------------------------------------------------------------------
-// Tests
-// ---------------------------------------------------------------------------
-
 describe("trustRuleRoutes", () => {
   beforeEach(() => {
-    capturedFetchCalls = [];
-    mockFetchResponse = {
-      ok: true,
-      status: 200,
-      json: async () => ({ rules: [] }),
-    };
-    mockFetch.mockClear();
+    ipcCalls = [];
+    ipcResult = { rules: [] };
+    ipcError = undefined;
+    ipcCallPersistentMock.mockClear();
   });
 
   describe("trust_rules_list", () => {
-    test("no params → GET /v1/trust-rules (no query string)", async () => {
+    test("no params calls trust_rules_list with empty params", async () => {
       const route = findRoute("trust_rules_list");
       await route.handler({ body: {} });
 
-      expect(capturedFetchCalls).toHaveLength(1);
-      expect(capturedFetchCalls[0].url).toBe(
-        "http://localhost:7822/v1/trust-rules",
-      );
-      expect(capturedFetchCalls[0].init).toBeUndefined();
+      expect(ipcCalls).toEqual([{ method: "trust_rules_list", params: {} }]);
     });
 
-    test("{ tool: 'bash' } → appends ?tool=bash", async () => {
+    test("{ tool: 'bash' } is forwarded", async () => {
       const route = findRoute("trust_rules_list");
       await route.handler({ body: { tool: "bash" } });
 
-      expect(capturedFetchCalls[0].url).toBe(
-        "http://localhost:7822/v1/trust-rules?tool=bash",
-      );
+      expect(ipcCalls).toEqual([
+        { method: "trust_rules_list", params: { tool: "bash" } },
+      ]);
     });
 
-    test("{ include_all: true } → appends ?include_all=true", async () => {
+    test("{ include_all: true } is forwarded", async () => {
       const route = findRoute("trust_rules_list");
       await route.handler({ body: { include_all: true } });
 
-      expect(capturedFetchCalls[0].url).toBe(
-        "http://localhost:7822/v1/trust-rules?include_all=true",
-      );
+      expect(ipcCalls).toEqual([
+        { method: "trust_rules_list", params: { include_all: true } },
+      ]);
     });
 
-    test("{ origin: 'user_defined' } → appends ?origin=user_defined", async () => {
+    test("{ origin: 'user_defined' } is forwarded", async () => {
       const route = findRoute("trust_rules_list");
       await route.handler({ body: { origin: "user_defined" } });
 
-      expect(capturedFetchCalls[0].url).toBe(
-        "http://localhost:7822/v1/trust-rules?origin=user_defined",
-      );
+      expect(ipcCalls).toEqual([
+        {
+          method: "trust_rules_list",
+          params: { origin: "user_defined" },
+        },
+      ]);
+    });
+
+    test("returns the parsed gateway IPC response", async () => {
+      ipcResult = {
+        rules: [
+          {
+            id: "rule-123",
+            tool: "bash",
+            pattern: "echo hello",
+            risk: "low",
+            description: "Allow echo hello",
+            origin: "user_defined",
+            userModified: false,
+            deleted: false,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            updatedAt: "2026-01-01T00:00:00.000Z",
+          },
+        ],
+      };
+
+      const route = findRoute("trust_rules_list");
+      const result = await route.handler({ body: {} });
+
+      expect(result).toEqual(ipcResult);
     });
   });
 
   describe("error path", () => {
-    test("non-OK response surfaces body .error message", async () => {
-      mockFetchResponse = {
-        ok: false,
-        status: 404,
-        json: async () => ({ error: "Not found" }),
-      };
+    test("gateway IPC error is propagated", async () => {
+      ipcError = new Error("Gateway IPC call timed out");
 
       const route = findRoute("trust_rules_list");
-      await expect(route.handler({ body: {} })).rejects.toThrow("Not found");
+      await expect(route.handler({ body: {} })).rejects.toThrow(
+        "Gateway IPC call timed out",
+      );
     });
   });
 });

package/src/media/image-credentials.ts

@@ -66,8 +66,8 @@ export async function resolveImageGenCredentials(opts: {
 function providerKeyHint(provider: ImageGenProvider): string {
   switch (provider) {
     case "gemini":
-      return "No Gemini API key configured. Please set your Gemini API key in Settings > Models & Services.";
+      return "No Gemini API key configured. Please set your Gemini API key in Settings → Models & Services.";
     case "openai":
-      return "No OpenAI API key configured. Please set your OpenAI API key in Settings > Models & Services.";
+      return "No OpenAI API key configured. Please set your OpenAI API key in Settings → Models & Services.";
   }
 }