@vellumai/assistant 0.8.2 → 0.8.4

package/src/home/home-greeting.ts

@@ -0,0 +1,94 @@
+/**
+ * Personalized home-page greeting generator.
+ *
+ * Produces a short greeting in the assistant's tone/persona for the
+ * Home page header. Uses the BTW side-chain for LLM generation and
+ * 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.
+ */
+
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { getConfig } from "../config/loader.js";
+import { resolvePersonaContext } from "../prompts/persona-resolver.js";
+import { buildSystemPrompt } from "../prompts/system-prompt.js";
+import { getConfiguredProvider } from "../providers/provider-send-message.js";
+import { runBtwSidechain } from "../runtime/btw-sidechain.js";
+import { getLogger } from "../util/logger.js";
+import {
+  getCachedHomeGreeting,
+  setCachedHomeGreeting,
+} from "./home-greeting-cache.js";
+
+const log = getLogger("home-greeting");
+
+const GENERATION_TIMEOUT_MS = 5_000;
+
+/**
+ * Return the cached personalized greeting, or `null` when none is
+ * available yet. This is a synchronous cache read — safe for GET
+ * handlers.
+ */
+export function getPersonalizedGreeting(): string | null {
+  return getCachedHomeGreeting();
+}
+
+/**
+ * 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.
+ */
+export async function refreshPersonalizedGreeting(): Promise<void> {
+  const cached = getCachedHomeGreeting();
+  if (cached) {
+    return;
+  }
+
+  try {
+    const config = getConfig();
+    const resolved = resolveCallSiteConfig("homeGreeting", config.llm);
+
+    const provider = await getConfiguredProvider("homeGreeting");
+    if (!provider) {
+      return;
+    }
+
+    const { userPersona, userSlug, channelPersona } = resolvePersonaContext(
+      undefined,
+      undefined,
+    );
+
+    const systemPrompt = buildSystemPrompt({
+      excludeBootstrap: true,
+      excludeCustomPrefix: true,
+      userPersona,
+      channelPersona,
+      userSlug,
+    });
+
+    const result = await runBtwSidechain({
+      content:
+        "Generate a short, casual greeting for the home page (max 10 words). " +
+        "It should convey the meaning of 'here's what's been going on' but in " +
+        "your unique tone and personality. Just output the greeting text, nothing else. " +
+        "No quotes, no preamble.",
+      provider,
+      systemPrompt,
+      messages: [],
+      tools: [],
+      callSite: "homeGreeting",
+      maxTokens: resolved.maxTokens,
+      timeoutMs: GENERATION_TIMEOUT_MS,
+    });
+
+    const text = result.text.trim();
+    if (text) {
+      setCachedHomeGreeting(text);
+    }
+  } catch (err) {
+    log.warn({ err }, "Failed to generate personalized home greeting");
+  }
+}

package/src/home/suggested-prompts.ts

@@ -6,11 +6,23 @@
  *
  * Two sources of prompts:
  *   - **Deterministic** — derived from missing OAuth connections.
+ *     Computed inline (read-only, safe for GET).
  *   - **Assistant-generated** — contextual suggestions from the LLM
- *     (placeholder; not yet implemented).
+ *     based on what's relevant to the user. Read from an in-memory
+ *     cache in the GET path; generation runs in the background via
+ *     `refreshAssistantSuggestedPrompts`.
  */
 
-import { isProviderConnected, listProviders } from "../oauth/oauth-store.js";
+import { resolveCallSiteConfig } from "../config/llm-resolver.js";
+import { getConfig } from "../config/loader.js";
+import { listProviders } from "../oauth/oauth-store.js";
+import { resolvePersonaContext } from "../prompts/persona-resolver.js";
+import { buildSystemPrompt } from "../prompts/system-prompt.js";
+import { getConfiguredProvider } from "../providers/provider-send-message.js";
+import { buildAssistantEvent } from "../runtime/assistant-event.js";
+import { assistantEventHub } from "../runtime/assistant-event-hub.js";
+import { runBtwSidechain } from "../runtime/btw-sidechain.js";
+import { isOAuthProviderConnected } from "../schedule/integration-status.js";
 import { getLogger } from "../util/logger.js";
 import type { SuggestedPrompt } from "./feed-types.js";
 
@@ -72,27 +84,88 @@ const CONNECT_PROMPT_META: Record<
   },
 };
 
+const LLM_SUGGESTIONS_TIMEOUT_MS = 5_000;
+const LLM_CACHE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+
+// ---------------------------------------------------------------------------
+// In-memory cache for LLM-generated suggestions
+// ---------------------------------------------------------------------------
+
+let cachedLLMPrompts: SuggestedPrompt[] = [];
+let cachedLLMPromptsAt = 0;
+
 /**
- * Produce deterministic suggested prompts based on missing OAuth
- * connections and (in the future) assistant-generated conversation
- * starters.
+ * Produce suggested prompts from both deterministic and cached LLM sources.
+ * Deterministic prompts always come first; cached LLM-generated prompts are
+ * appended when available. No LLM calls happen in this path — safe for GET.
  */
 export async function getSuggestedPrompts(): Promise<SuggestedPrompt[]> {
   const prompts: SuggestedPrompt[] = [];
 
+  let deterministicPrompts: SuggestedPrompt[] = [];
   try {
-    const deterministicPrompts = await getDeterministicPrompts();
+    deterministicPrompts = await getDeterministicPrompts();
     prompts.push(...deterministicPrompts);
   } catch (err) {
     log.warn({ err }, "Failed to compute deterministic suggested prompts");
   }
 
-  // Placeholder: assistant-generated prompts will be added here once
-  // the LLM producer is implemented.
+  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
+    prompts.push(...cachedLLMPrompts);
+  }
 
   return prompts;
 }
 
+/**
+ * Drops the in-memory LLM suggestion cache so the next call to
+ * `getSuggestedPrompts()` returns only the fresh deterministic list (and
+ * a follow-up background refresh repopulates the LLM half).
+ *
+ * Called from OAuth connect/disconnect paths so a freshly-connected
+ * provider stops surfacing as a "Connect X" pill within one reload — the
+ * 30-minute TTL would otherwise pin a stale suggestion until the next
+ * periodic refresh.
+ */
+export function invalidateAssistantSuggestedPromptsCache(): void {
+  cachedLLMPrompts = [];
+  cachedLLMPromptsAt = 0;
+  assistantEventHub
+    .publish(
+      buildAssistantEvent({
+        type: "home_feed_updated",
+        updatedAt: new Date().toISOString(),
+        newItemCount: 0,
+      }),
+    )
+    .catch((err) => {
+      log.warn(
+        { err },
+        "Failed to publish home_feed_updated after prompt cache invalidation",
+      );
+    });
+}
+
+/**
+ * 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.
+ */
+export async function refreshAssistantSuggestedPrompts(): Promise<void> {
+  if (Date.now() - cachedLLMPromptsAt < LLM_CACHE_TTL_MS) {
+    return;
+  }
+
+  try {
+    const deterministicPrompts = await getDeterministicPrompts();
+    const llmPrompts = await generateAssistantPrompts(deterministicPrompts);
+    cachedLLMPrompts = llmPrompts;
+    cachedLLMPromptsAt = Date.now();
+  } catch (err) {
+    log.warn({ err }, "Failed to refresh assistant suggested prompts");
+  }
+}
+
 /**
  * Check which well-known OAuth providers are not connected and return
  * a "Connect X" prompt for each. For connected providers that have
@@ -107,7 +180,7 @@ async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
     const meta = CONNECT_PROMPT_META[provider.provider];
     if (!meta) continue;
 
-    const connected = await isProviderConnected(provider.provider);
+    const connected = await isOAuthProviderConnected(provider.provider);
 
     if (!connected) {
       prompts.push({
@@ -135,3 +208,98 @@ async function getDeterministicPrompts(): Promise<SuggestedPrompt[]> {
 
   return prompts;
 }
+
+// ---------------------------------------------------------------------------
+// LLM-generated suggestions
+// ---------------------------------------------------------------------------
+
+interface LLMSuggestion {
+  label: string;
+  prompt: string;
+}
+
+/**
+ * Ask the LLM to generate contextual conversation-starter suggestions
+ * based on the assistant's persona and the user's connected services.
+ * Returns an empty array on failure so deterministic prompts still show.
+ */
+async function generateAssistantPrompts(
+  deterministicPrompts: SuggestedPrompt[],
+): Promise<SuggestedPrompt[]> {
+  const config = getConfig();
+  const resolved = resolveCallSiteConfig("homeSuggestedPrompts", config.llm);
+
+  const provider = await getConfiguredProvider("homeSuggestedPrompts");
+  if (!provider) {
+    return [];
+  }
+
+  const { userPersona, userSlug, channelPersona } = resolvePersonaContext(
+    undefined,
+    undefined,
+  );
+
+  const systemPrompt = buildSystemPrompt({
+    excludeBootstrap: true,
+    excludeCustomPrefix: true,
+    userPersona,
+    channelPersona,
+    userSlug,
+  });
+
+  const existingLabels = deterministicPrompts.map((p) => p.label).join(", ");
+  const contextNote = existingLabels
+    ? `The user already has these suggestions: ${existingLabels}. Do NOT duplicate them.`
+    : "";
+
+  const result = await runBtwSidechain({
+    content:
+      "Suggest 2-3 short, actionable conversation starters for the home page. " +
+      "Each should be something specific and helpful you can do for the user right now. " +
+      `${contextNote} ` +
+      'Return ONLY a JSON array of objects with "label" (max 5 words) and "prompt" (the full message to send). ' +
+      "No markdown fences, no explanation.",
+    provider,
+    systemPrompt,
+    messages: [],
+    tools: [],
+    callSite: "homeSuggestedPrompts",
+    maxTokens: resolved.maxTokens,
+    timeoutMs: LLM_SUGGESTIONS_TIMEOUT_MS,
+  });
+
+  const text = result.text.trim();
+  if (!text) {
+    return [];
+  }
+
+  const parsed = parseLLMSuggestions(text);
+  return parsed.map((s, i) => ({
+    id: `assistant-${i}-${s.label.toLowerCase().replace(/\s+/g, "-")}`,
+    label: s.label,
+    prompt: s.prompt,
+    source: "assistant" as const,
+  }));
+}
+
+function parseLLMSuggestions(text: string): LLMSuggestion[] {
+  try {
+    const cleaned = text
+      .replace(/^```(?:json)?\n?/m, "")
+      .replace(/\n?```$/m, "");
+    const parsed = JSON.parse(cleaned);
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed.filter(
+      (item): item is LLMSuggestion =>
+        typeof item === "object" &&
+        item !== null &&
+        typeof item.label === "string" &&
+        typeof item.prompt === "string",
+    );
+  } catch {
+    log.warn("Failed to parse LLM suggestions response");
+    return [];
+  }
+}

package/src/ipc/cli-client.ts

@@ -135,19 +135,26 @@ export async function cliIpcCall<T = unknown>(
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => {
-      finish({ ok: false, error: "Request aborted" });
-    }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        finish({ ok: false, error: "Request aborted" });
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope) => {
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
         if (msg.error) {
-          finish({ ok: false, error: msg.error,
+          finish({
+            ok: false,
+            error: msg.error,
             ...(msg.statusCode != null && { statusCode: msg.statusCode }),
             ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+          });
         } else {
           finish({ ok: true, result: msg.result as T });
         }
@@ -199,7 +206,13 @@ export async function cliIpcCallBinary(
   opts?: { timeoutMs?: number; signal?: AbortSignal },
 ): Promise<
   | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
-  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+  | {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }
 > {
   if (opts?.signal?.aborted) {
     throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
@@ -215,7 +228,13 @@ export async function cliIpcCallBinary(
     const finish = (
       result:
         | { ok: true; headers: Record<string, string>; bytes: Uint8Array }
-        | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
+        | {
+            ok: false;
+            error: string;
+            statusCode?: number;
+            errorCode?: string;
+            errorDetails?: unknown;
+          },
     ) => {
       if (settled) return;
       settled = true;
@@ -226,8 +245,14 @@ export async function cliIpcCallBinary(
     };
 
     const connectTimer = setTimeout(() => {
-      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC binary connect timed out");
-      finish({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+      log.debug(
+        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        "CLI IPC binary connect timed out",
+      );
+      finish({
+        ok: false,
+        error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`,
+      });
     }, CONNECT_TIMEOUT_MS);
 
     const socket = new Socket();
@@ -235,7 +260,10 @@ export async function cliIpcCallBinary(
 
     socket.on("error", (err) => {
       const code = (err as NodeJS.ErrnoException).code;
-      log.debug({ err, code, method, socketPath }, "CLI IPC binary socket error");
+      log.debug(
+        { err, code, method, socketPath },
+        "CLI IPC binary socket error",
+      );
       finish({
         ok: false,
         error:
@@ -258,23 +286,37 @@ export async function cliIpcCallBinary(
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => {
-      finish({ ok: false, error: "Request aborted" });
-    }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        finish({ ok: false, error: "Request aborted" });
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope, binary) => {
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
         if (msg.error) {
-          finish({ ok: false, error: msg.error,
+          finish({
+            ok: false,
+            error: msg.error,
             ...(msg.statusCode != null && { statusCode: msg.statusCode }),
             ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+            ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+          });
         } else if (binary === undefined) {
-          finish({ ok: false, error: "Expected binary frame but received JSON-only response" });
+          finish({
+            ok: false,
+            error: "Expected binary frame but received JSON-only response",
+          });
         } else {
-          finish({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, bytes: binary });
+          finish({
+            ok: true,
+            headers: (envelope.headers ?? {}) as Record<string, string>,
+            bytes: binary,
+          });
         }
       },
       (err) => finish({ ok: false, error: err.message }),
@@ -285,7 +327,10 @@ export async function cliIpcCallBinary(
       writeMessage(socket, { id: reqId, method, params });
 
       callTimer = setTimeout(() => {
-        log.debug({ method, socketPath, timeoutMs: callTimeoutMs }, "CLI IPC binary call timed out");
+        log.debug(
+          { method, socketPath, timeoutMs: callTimeoutMs },
+          "CLI IPC binary call timed out",
+        );
         finish({ ok: false, error: "Request timed out" });
       }, callTimeoutMs);
 
@@ -323,24 +368,42 @@ export async function cliIpcCallStream(
   params?: Record<string, unknown>,
   opts?: { firstByteTimeoutMs?: number; signal?: AbortSignal },
 ): Promise<
-  | { ok: true; headers: Record<string, string>; body: ReadableStream<Uint8Array>; abort: () => void }
-  | { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown }
+  | {
+      ok: true;
+      headers: Record<string, string>;
+      body: ReadableStream<Uint8Array>;
+      abort: () => void;
+    }
+  | {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }
 > {
   if (opts?.signal?.aborted) {
     throw opts.signal.reason ?? new DOMException("Aborted", "AbortError");
   }
 
   const socketPath = getAssistantSocketPath();
-  const firstByteTimeoutMs = opts?.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
+  const firstByteTimeoutMs =
+    opts?.firstByteTimeoutMs ?? DEFAULT_FIRST_BYTE_TIMEOUT_MS;
 
   return new Promise((resolve) => {
     let settled = false;
     let firstByteTimer: ReturnType<typeof setTimeout> | undefined;
-    let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
-
-    const finishError = (
-      result: { ok: false; error: string; statusCode?: number; errorCode?: string; errorDetails?: unknown },
-    ) => {
+    let streamController:
+      | ReadableStreamDefaultController<Uint8Array>
+      | undefined;
+
+    const finishError = (result: {
+      ok: false;
+      error: string;
+      statusCode?: number;
+      errorCode?: string;
+      errorDetails?: unknown;
+    }) => {
       if (settled) return;
       settled = true;
       clearTimeout(connectTimer);
@@ -366,8 +429,14 @@ export async function cliIpcCallStream(
     };
 
     const connectTimer = setTimeout(() => {
-      log.debug({ method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS }, "CLI IPC stream connect timed out");
-      finishError({ ok: false, error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.` });
+      log.debug(
+        { method, socketPath, timeoutMs: CONNECT_TIMEOUT_MS },
+        "CLI IPC stream connect timed out",
+      );
+      finishError({
+        ok: false,
+        error: `Could not connect to the assistant at ${socketPath}.\nRun \`assistant status\` to check, or \`assistant gateway start\` to start it.`,
+      });
     }, CONNECT_TIMEOUT_MS);
 
     const socket = new Socket();
@@ -375,7 +444,10 @@ export async function cliIpcCallStream(
 
     socket.on("error", (err) => {
       const code = (err as NodeJS.ErrnoException).code;
-      log.debug({ err, code, method, socketPath }, "CLI IPC stream socket error");
+      log.debug(
+        { err, code, method, socketPath },
+        "CLI IPC stream socket error",
+      );
       if (!settled) {
         finishError({
           ok: false,
@@ -399,24 +471,35 @@ export async function cliIpcCallStream(
             : "Connection closed before response",
         });
       } else if (streamController) {
-        streamController.error(new Error("Connection closed before stream ended"));
+        streamController.error(
+          new Error("Connection closed before stream ended"),
+        );
         streamController = undefined;
       }
     });
 
     const reqId = crypto.randomUUID();
 
-    opts?.signal?.addEventListener("abort", () => { abort(); }, { once: true });
+    opts?.signal?.addEventListener(
+      "abort",
+      () => {
+        abort();
+      },
+      { once: true },
+    );
 
     const reader = new IpcFrameReader(
       (envelope) => {
         // Non-streaming envelope with error (e.g. method not found, auth failure)
         if (envelope.id !== reqId) return;
         const msg = envelope as IpcResponse;
-        finishError({ ok: false, error: msg.error ?? "Unexpected non-streaming response",
+        finishError({
+          ok: false,
+          error: msg.error ?? "Unexpected non-streaming response",
           ...(msg.statusCode != null && { statusCode: msg.statusCode }),
           ...(msg.errorCode != null && { errorCode: msg.errorCode }),
-          ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }) });
+          ...(msg.errorDetails != null && { errorDetails: msg.errorDetails }),
+        });
       },
       (err) => finishError({ ok: false, error: err.message }),
       {
@@ -437,7 +520,12 @@ export async function cliIpcCallStream(
           });
           settled = true;
           clearTimeout(connectTimer);
-          resolve({ ok: true, headers: (envelope.headers ?? {}) as Record<string, string>, body, abort });
+          resolve({
+            ok: true,
+            headers: (envelope.headers ?? {}) as Record<string, string>,
+            body,
+            abort,
+          });
         },
         onStreamChunk: (chunk) => {
           streamController?.enqueue(chunk);
@@ -455,8 +543,14 @@ export async function cliIpcCallStream(
       writeMessage(socket, { id: reqId, method, params });
 
       firstByteTimer = setTimeout(() => {
-        log.debug({ method, socketPath, timeoutMs: firstByteTimeoutMs }, "CLI IPC stream first-byte timeout");
-        finishError({ ok: false, error: "Stream timed out waiting for first byte" });
+        log.debug(
+          { method, socketPath, timeoutMs: firstByteTimeoutMs },
+          "CLI IPC stream first-byte timeout",
+        );
+        finishError({
+          ok: false,
+          error: "Stream timed out waiting for first byte",
+        });
       }, firstByteTimeoutMs);
 
       socket.on("data", (chunk) => {
@@ -491,13 +585,21 @@ export function exitFromIpcResult(
   _cmd?: unknown,
 ): never {
   process.stderr.write((r.error ?? "Unknown error") + "\n");
-  if (r.statusCode === undefined) {
-    process.exit(10);
-  } else if (r.statusCode >= 500) {
-    process.exit(3);
-  } else if (r.statusCode >= 400) {
-    process.exit(2);
-  } else {
-    process.exit(1);
-  }
+  process.exit(exitCodeFromIpcResult(r));
+}
+
+/**
+ * Map an IPC error result to its CLI process exit code without exiting.
+ *
+ * Use this when callers want to emit a structured response (e.g. a JSON
+ * error envelope in `--json` mode) before terminating with the same status
+ * code that {@link exitFromIpcResult} would produce.
+ *
+ * Exit code matrix matches {@link exitFromIpcResult}.
+ */
+export function exitCodeFromIpcResult(r: { statusCode?: number }): number {
+  if (r.statusCode === undefined) return 10;
+  if (r.statusCode >= 500) return 3;
+  if (r.statusCode >= 400) return 2;
+  return 1;
 }