@vellumai/assistant 0.8.5 → 0.8.7-dev.202606052118.34cd356

package/src/runtime/routes/identity-intro-cache.ts

@@ -1,38 +1,35 @@
 /**
- * Caching layer for the LLM-generated identity intro text.
+ * Caching layer for identity greetings.
  *
- * The intro (a short identity tagline) is generated via the
- * /v1/btw endpoint and displayed on the Identity panel. To avoid redundant LLM
- * calls, we cache the result for 4 hours with content-hash-based invalidation:
- * when IDENTITY.md, SOUL.md, or the guardian's per-user persona file change,
- * the cache is busted.
+ * Greetings are sourced from (in priority order):
+ * 1. A `## Greetings` section in SOUL.md (user-defined bullet list)
+ * 2. A cached greetings array (populated by the empty-state greeting callsite)
+ * 3. A generic fallback when generation is unavailable
+ *
+ * Cache invalidation is intentionally TTL-only. User-authored SOUL.md
+ * greetings are read before cache, so manual overrides still take priority
+ * without coupling cache validity to prompt-file edits.
  *
  * Storage uses the existing `memory_checkpoints` table (simple key-value store).
  */
 
-import { createHash } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 
 import {
   getMemoryCheckpoint,
   setMemoryCheckpoint,
 } from "../../memory/checkpoints.js";
-import { resolveGuardianPersona } from "../../prompts/persona-resolver.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const CACHE_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+const CACHE_TTL_MS = 2 * 24 * 60 * 60 * 1000; // 2 days
 
-const CHECKPOINT_KEY_TEXT = "identity:intro:text";
-const CHECKPOINT_KEY_HASH = "identity:intro:content_hash";
+const CHECKPOINT_KEY_GREETINGS = "identity:intro:greetings";
 const CHECKPOINT_KEY_TIMESTAMP = "identity:intro:cached_at";
 
-/** Workspace files whose content influences the identity intro. */
-const IDENTITY_FILES = ["IDENTITY.md", "SOUL.md"] as const;
-
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -78,12 +75,49 @@ export function readWorkspaceIdentityIntro(): string | null {
   );
 }
 
-/** Compute a SHA-256 hex hash of the concatenated identity file contents. */
-export function computeIdentityContentHash(): string {
-  const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");
-  const guardianPersona = resolveGuardianPersona() ?? "";
-  const combined = staticFiles + "\n---\n" + guardianPersona;
-  return createHash("sha256").update(combined).digest("hex");
+/**
+ * Parse the `## Greetings` section from SOUL.md. Returns bullet items as an
+ * array of strings, or `null` if the section is missing or empty.
+ */
+export function parseGreetingsSection(content: string): string[] | null {
+  let inSection = false;
+  let sectionLevel: number | null = null;
+  const greetings: string[] = [];
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    const heading = /^(#{1,6})\s+(.+?)\s*#*$/.exec(trimmed);
+    if (heading) {
+      const level = heading[1]!.length;
+      const title = heading[2]!.trim();
+      if (inSection) {
+        if (sectionLevel !== null && level <= sectionLevel) break;
+        continue;
+      }
+      if (level === 2 && /^greetings$/i.test(title)) {
+        inSection = true;
+        sectionLevel = level;
+      }
+      continue;
+    }
+    if (!inSection) continue;
+    const bullet = /^(?:[-*+]\s+|\d+[.)]\s+)(.+)$/.exec(trimmed);
+    const greeting = bullet?.[1]?.trim();
+    if (greeting) {
+      greetings.push(greeting);
+    }
+  }
+
+  return greetings.length > 0 ? greetings : null;
+}
+
+/**
+ * Read user-defined greetings from the `## Greetings` section of SOUL.md.
+ */
+export function readWorkspaceGreetings(): string[] | null {
+  const soulContent = readWorkspaceFile("SOUL.md");
+  if (!soulContent) return null;
+  return parseGreetingsSection(soulContent);
 }
 
 // ---------------------------------------------------------------------------
@@ -91,47 +125,46 @@ export function computeIdentityContentHash(): string {
 // ---------------------------------------------------------------------------
 
 export interface CachedIntro {
-  text: string;
+  greetings: string[];
 }
 
 /**
- * Retrieve the cached identity intro if it exists, is within the TTL window,
- * and the identity files have not changed since it was generated.
+ * Retrieve the cached greetings array if it exists and is within the TTL
+ * window.
  *
- * Returns `null` when the cache is missing, expired, or invalidated.
+ * Returns `null` when the cache is missing or expired.
  */
 export function getCachedIntro(): CachedIntro | null {
   try {
-    const text = getMemoryCheckpoint(CHECKPOINT_KEY_TEXT);
-    const hash = getMemoryCheckpoint(CHECKPOINT_KEY_HASH);
+    const raw = getMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS);
     const timestampStr = getMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP);
 
-    if (!text || !hash || !timestampStr) return null;
+    if (!raw || !timestampStr) return null;
 
     // TTL check
     const cachedAt = Number(timestampStr);
     if (isNaN(cachedAt) || Date.now() - cachedAt > CACHE_TTL_MS) return null;
 
-    // Content-hash check — bust cache when identity files change
-    const currentHash = computeIdentityContentHash();
-    if (currentHash !== hash) return null;
+    // Parse stored value — handles both JSON array and legacy single string
+    let greetings: string[];
+    try {
+      const parsed = JSON.parse(raw);
+      greetings = Array.isArray(parsed) ? parsed : [raw];
+    } catch {
+      greetings = [raw];
+    }
 
-    return { text };
+    return { greetings };
   } catch {
     return null;
   }
 }
 
-/**
- * Store the generated identity intro text in the cache along with
- * the current content hash and timestamp.
- */
-export function setCachedIntro(text: string): void {
+/** Store a greetings array in the cache along with the current timestamp. */
+export function setCachedIntro(greetings: string[]): void {
   try {
-    const hash = computeIdentityContentHash();
     const now = String(Date.now());
-    setMemoryCheckpoint(CHECKPOINT_KEY_TEXT, text);
-    setMemoryCheckpoint(CHECKPOINT_KEY_HASH, hash);
+    setMemoryCheckpoint(CHECKPOINT_KEY_GREETINGS, JSON.stringify(greetings));
     setMemoryCheckpoint(CHECKPOINT_KEY_TIMESTAMP, now);
   } catch {
     // Cache write failure is non-fatal — next request will regenerate.

package/src/runtime/routes/identity-routes.ts

@@ -7,10 +7,15 @@ import { availableParallelism, cpus, totalmem } from "node:os";
 
 import { z } from "zod";
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
 import { getCpuLimit, getIsPlatform } from "../../config/env-registry.js";
+import { resolveCallSiteConfig } from "../../config/llm-resolver.js";
+import { getConfig } from "../../config/loader.js";
 import { parseIdentityFields } from "../../daemon/handlers/identity.js";
 import { getProfilerRuntimeStatus } from "../../daemon/profiler-run-store.js";
 import { getMaxMigrationVersion } from "../../memory/migrations/registry.js";
+import { buildSystemPrompt } from "../../prompts/system-prompt.js";
+import { getConfiguredProvider } from "../../providers/provider-send-message.js";
 import { getCesClient } from "../../security/secure-keys.js";
 import {
   getDiskUsageInfo,
@@ -22,8 +27,15 @@ import { APP_VERSION } from "../../version.js";
 import { resolveHatchedAtReadOnly } from "../../workspace/hatched-date.js";
 import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
 import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { runBtwSidechain } from "../btw-sidechain.js";
 import { NotFoundError } from "./errors.js";
-import { getCachedIntro } from "./identity-intro-cache.js";
+import {
+  getCachedIntro,
+  readWorkspaceGreetings,
+  readWorkspaceIdentityIntro,
+  setCachedIntro,
+} from "./identity-intro-cache.js";
 import type { RouteDefinition } from "./types.js";
 
 interface MemoryInfo {
@@ -391,21 +403,211 @@ function resolveIdentityCreatedAt(identityPath: string): string | undefined {
   return resolveHatchedAtReadOnly(identityPath);
 }
 
-function getIdentityIntro() {
-  const identityPath = getWorkspacePromptPath("IDENTITY.md");
-  if (existsSync(identityPath)) {
-    const content = readFileSync(identityPath, "utf-8");
-    const fields = parseIdentityFields(content);
-    if (fields.name) {
-      return { text: `Hi, I'm ${fields.name}!` };
-    }
+const FALLBACK_GREETINGS = [
+  "What are we working on?",
+  "I'm here whenever you need me.",
+  "What's on your mind?",
+  "Ready when you are.",
+];
+
+const GENERATED_GREETING_LIMIT = 4;
+const GREETING_GENERATION_TIMEOUT_MS = 10_000;
+const GREETING_GENERATION_FAILURE_COOLDOWN_MS = 60_000;
+const EMPTY_STATE_GREETING_CALLSITE = "emptyStateGreeting" as const;
+const EMPTY_STATE_DYNAMIC_GREETINGS_FLAG =
+  "empty-state-dynamic-greetings" as const;
+
+type IdentityIntroSource = "workspace" | "cache" | "fallback";
+
+interface IdentityIntroResponse {
+  greetings: string[];
+  text: string;
+  source: IdentityIntroSource;
+  refreshing: boolean;
+}
+
+let greetingGenerationInFlight: Promise<void> | null = null;
+let lastGreetingGenerationFailureAt = 0;
+
+function identityIntroResponse(
+  greetings: string[],
+  source: IdentityIntroSource,
+  refreshing = false,
+): IdentityIntroResponse {
+  return {
+    greetings,
+    text: greetings[0] ?? "",
+    source,
+    refreshing,
+  };
+}
+
+function getIdentityIntro(): IdentityIntroResponse {
+  // 1. User-defined greetings from SOUL.md `## Greetings`
+  const workspaceGreetings = readWorkspaceGreetings();
+  if (workspaceGreetings) {
+    return identityIntroResponse(workspaceGreetings, "workspace");
+  }
+
+  const config = getConfig();
+  if (
+    !isAssistantFeatureFlagEnabled(EMPTY_STATE_DYNAMIC_GREETINGS_FLAG, config)
+  ) {
+    return identityIntroResponse(FALLBACK_GREETINGS, "fallback");
   }
 
+  // 2. Cached LLM-generated greetings (populated by background refresh)
   const cached = getCachedIntro();
-  if (!cached) {
-    throw new NotFoundError("No cached identity intro available");
+  if (cached) {
+    return identityIntroResponse(cached.greetings, "cache");
   }
-  return { text: cached.text };
+
+  // 3. Identity intro tagline from `## Identity Intro` in IDENTITY.md
+  //    (written during onboarding by BOOTSTRAP.md instructions)
+  const identityIntro = readWorkspaceIdentityIntro();
+  if (identityIntro) {
+    // Still trigger background generation so the next request gets
+    // LLM-generated greetings instead of the static tagline.
+    const refreshing = triggerEmptyStateGreetingGeneration();
+    return identityIntroResponse(
+      [identityIntro, ...FALLBACK_GREETINGS],
+      "workspace",
+      refreshing,
+    );
+  }
+
+  // 4. Trigger fresh generation without blocking the empty-state UI.
+  const refreshing = triggerEmptyStateGreetingGeneration();
+
+  // 5. Generic fallback only when generation is unavailable.
+  return identityIntroResponse(FALLBACK_GREETINGS, "fallback", refreshing);
+}
+
+function triggerEmptyStateGreetingGeneration(): boolean {
+  if (greetingGenerationInFlight) {
+    return true;
+  }
+
+  if (
+    lastGreetingGenerationFailureAt > 0 &&
+    Date.now() - lastGreetingGenerationFailureAt <
+      GREETING_GENERATION_FAILURE_COOLDOWN_MS
+  ) {
+    return false;
+  }
+
+  greetingGenerationInFlight = new Promise<void>((resolve) => {
+    queueMicrotask(() => {
+      void generateEmptyStateGreetings()
+        .then((greetings) => {
+          lastGreetingGenerationFailureAt = greetings === null ? Date.now() : 0;
+        })
+        .finally(() => {
+          greetingGenerationInFlight = null;
+          resolve();
+        });
+    });
+  });
+
+  return true;
+}
+
+async function generateEmptyStateGreetings(): Promise<string[] | null> {
+  try {
+    const provider = await getConfiguredProvider(EMPTY_STATE_GREETING_CALLSITE);
+    if (!provider) {
+      return null;
+    }
+
+    const resolved = resolveCallSiteConfig(
+      EMPTY_STATE_GREETING_CALLSITE,
+      getConfig().llm,
+    );
+    const systemPrompt = buildSystemPrompt({
+      excludeBootstrap: true,
+      excludeCustomPrefix: true,
+    });
+    const result = await runBtwSidechain({
+      content:
+        `Generate ${GENERATED_GREETING_LIMIT} short first-person greeting options for the empty new-chat screen. ` +
+        "Use the assistant identity, voice, and relationship guidance from IDENTITY.md and SOUL.md. " +
+        "Each greeting should feel personal and inviting, not like a generic assistant introduction. " +
+        "Return only a JSON array of strings. No markdown, keys, or explanation.",
+      provider,
+      systemPrompt,
+      messages: [],
+      tools: [],
+      callSite: EMPTY_STATE_GREETING_CALLSITE,
+      maxTokens: resolved.maxTokens,
+      timeoutMs: GREETING_GENERATION_TIMEOUT_MS,
+    });
+
+    const greetings = parseGeneratedGreetings(result.text);
+    if (greetings.length === 0) {
+      return null;
+    }
+
+    setCachedIntro(greetings);
+    return greetings;
+  } catch (err) {
+    getLogger("identity").warn(
+      { err },
+      "Failed to generate empty-state greetings",
+    );
+    return null;
+  }
+}
+
+function parseGeneratedGreetings(text: string): string[] {
+  const cleaned = text
+    .trim()
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/i, "")
+    .trim();
+
+  try {
+    const parsed = JSON.parse(cleaned) as unknown;
+    if (Array.isArray(parsed)) {
+      return normalizeGeneratedGreetings(parsed);
+    }
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      Array.isArray((parsed as { greetings?: unknown }).greetings)
+    ) {
+      return normalizeGeneratedGreetings(
+        (parsed as { greetings: unknown[] }).greetings,
+      );
+    }
+  } catch {
+    // Fall through to line parsing for non-JSON model output.
+  }
+
+  return normalizeGeneratedGreetings(cleaned.split("\n"));
+}
+
+function normalizeGeneratedGreetings(values: unknown[]): string[] {
+  const greetings: string[] = [];
+  const seen = new Set<string>();
+
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const greeting = value
+      .trim()
+      .replace(/^(?:[-*+]\s+|\d+[.)]\s+)/, "")
+      .replace(/^["'`]+|["'`]+$/g, "")
+      .trim();
+    if (!greeting) continue;
+
+    const key = greeting.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    greetings.push(greeting);
+
+    if (greetings.length >= GENERATED_GREETING_LIMIT) break;
+  }
+
+  return greetings;
 }
 
 // ---------------------------------------------------------------------------
@@ -443,14 +645,37 @@ const cesHealthSchema = z.object({
   connected: z.boolean(),
 });
 
+const healthDiskSchema = z.object({
+  path: z.string(),
+  totalMb: z.number(),
+  usedMb: z.number(),
+  freeMb: z.number(),
+});
+
+const healthMemorySchema = z.object({
+  currentMb: z.number(),
+  maxMb: z.number(),
+});
+
+const healthCpuSchema = z.object({
+  currentPercent: z.number(),
+  maxCores: z.number(),
+});
+
+const healthMigrationsSchema = z.object({
+  dbVersion: z.number(),
+  lastWorkspaceMigrationId: z.string().nullable(),
+});
+
 const detailedHealthSchema = z.object({
   status: z.string(),
   timestamp: z.string(),
   version: z.string(),
-  disk: z.object({}).passthrough(),
-  memory: z.object({}).passthrough(),
-  cpu: z.object({}).passthrough(),
-  migrations: z.object({}).passthrough(),
+  // `getDiskUsageInfo()` returns null when usage can't be measured.
+  disk: healthDiskSchema.nullable(),
+  memory: healthMemorySchema,
+  cpu: healthCpuSchema,
+  migrations: healthMigrationsSchema,
   ces: cesHealthSchema,
   profiler: profilerStatusSchema.optional(),
 });
@@ -464,6 +689,7 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "health",
     endpoint: "health",
     method: "GET",
+    policy: null,
     handler: getDetailedHealth,
     summary: "Detailed health check",
     description:
@@ -479,8 +705,8 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "healthz",
     endpoint: "healthz",
     method: "GET",
+    policy: null,
     handler: getDetailedHealth,
-    policyKey: "health",
     summary: "Detailed health check (alias)",
     description:
       "Alias for /v1/health. Returns runtime health including version, disk, memory, CPU, and migration status.",
@@ -492,6 +718,10 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "identity",
     endpoint: "identity",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: getIdentity,
     summary: "Get assistant identity",
     description:
@@ -504,20 +734,27 @@ export const ROUTES: RouteDefinition[] = [
       emoji: z.string(),
       home: z.string(),
       version: z.string(),
-      createdAt: z.string(),
+      createdAt: z.string().optional(),
     }),
   },
   {
     operationId: "identity_intro",
     endpoint: "identity/intro",
     method: "GET",
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     handler: getIdentityIntro,
-    summary: "Get identity intro text",
+    summary: "Get identity greetings",
     description:
-      "Returns a deterministic greeting derived from the assistant name in IDENTITY.md, falling back to LLM-generated cache.",
+      "Returns greetings sourced from SOUL.md, the generated cache, or generic fallbacks while background generation refreshes the cache.",
     tags: ["identity"],
     responseBody: z.object({
+      greetings: z.array(z.string()),
       text: z.string(),
+      source: z.enum(["workspace", "cache", "fallback"]),
+      refreshing: z.boolean(),
     }),
   },
 ];

package/src/runtime/routes/image-generation-routes.ts

@@ -1,3 +1,5 @@
+import { z } from "zod";
+
 import { getConfig } from "../../config/loader.js";
 import { resolveImageGenCredentials } from "../../media/image-credentials.js";
 import {
@@ -5,16 +7,51 @@ import {
   mapImageGenError,
   providerForModel,
 } from "../../media/image-service.js";
-import { BadRequestError, InternalError, UnprocessableEntityError } from "./errors.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import {
+  BadRequestError,
+  InternalError,
+  UnprocessableEntityError,
+} from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const SourceImageSchema = z.object({
+  mimeType: z.string(),
+  dataBase64: z.string(),
+});
+
+const ImageGenerationRequestSchema = z.object({
+  prompt: z.string(),
+  mode: z.enum(["generate", "edit"]).optional(),
+  sourceImages: z.array(SourceImageSchema).optional(),
+  model: z.string().optional(),
+  variants: z.number().optional(),
+});
+
+const GeneratedImageSchema = z.object({
+  mimeType: z.string(),
+  dataBase64: z.string(),
+  title: z.string().optional(),
+});
+
+const ImageGenerationResponseSchema = z.object({
+  images: z.array(GeneratedImageSchema),
+  text: z.string().optional(),
+  resolvedModel: z.string(),
+});
+type ImageGenerationResponse = z.infer<typeof ImageGenerationResponseSchema>;
+
 // ---------------------------------------------------------------------------
 // Handler
 // ---------------------------------------------------------------------------
 
 async function handleImageGenerationGenerate(
   args: RouteHandlerArgs,
-): Promise<unknown> {
+): Promise<ImageGenerationResponse> {
   const { prompt, mode, sourceImages, model, variants } = args.body ?? {};
 
   // Validate prompt
@@ -90,10 +127,16 @@ export const ROUTES: RouteDefinition[] = [
     operationId: "image_generation_generate",
     endpoint: "image-generation/generate",
     method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
     summary: "Generate or edit images using AI",
     description:
       "Calls the configured image-generation provider (Gemini or OpenAI) to produce one or more images.",
     tags: ["image-generation"],
+    requestBody: ImageGenerationRequestSchema,
+    responseBody: ImageGenerationResponseSchema,
     handler: handleImageGenerationGenerate,
   },
 ];

package/src/runtime/routes/inbound-message-handler.ts

@@ -20,7 +20,7 @@ import {
   createApprovalConversationGenerator,
   createApprovalCopyGenerator,
 } from "../../daemon/approval-generators.js";
-import { findConversation } from "../../daemon/conversation-store.js";
+import { findConversation } from "../../daemon/conversation-registry.js";
 import {
   canonicalizeTimeZone,
   resolveTurnTimezoneContext,
@@ -1431,8 +1431,10 @@ async function persistSlackReactionAsMessage(params: {
     params.conversationId,
     "user",
     "[reaction]",
-    { slackMeta: writeSlackMetadata(slackMeta) },
-    { skipIndexing: true },
+    {
+      metadata: { slackMeta: writeSlackMetadata(slackMeta) },
+      skipIndexing: true,
+    },
   );
   linkMessage(params.eventId, persisted.id);
   markProcessed(params.eventId);
@@ -1668,15 +1670,17 @@ async function persistBackfilledSlackMessage(params: {
   const rawText = message.text ?? "";
 
   const persisted = await addMessage(params.conversationId, role, rawText, {
-    slackMeta: writeSlackMetadata(slackMeta),
-    provenanceTrustClass: isGuardian ? "guardian" : "unknown",
-    provenanceSourceChannel: "slack",
-    ...(params.guardianExternalUserId
-      ? { provenanceGuardianExternalUserId: params.guardianExternalUserId }
-      : {}),
-    ...(actorExternalUserId
-      ? { provenanceRequesterIdentifier: actorExternalUserId }
-      : {}),
+    metadata: {
+      slackMeta: writeSlackMetadata(slackMeta),
+      provenanceTrustClass: isGuardian ? "guardian" : "unknown",
+      provenanceSourceChannel: "slack",
+      ...(params.guardianExternalUserId
+        ? { provenanceGuardianExternalUserId: params.guardianExternalUserId }
+        : {}),
+      ...(actorExternalUserId
+        ? { provenanceRequesterIdentifier: actorExternalUserId }
+        : {}),
+    },
   });
 
   // Hydrate image attachments inline, then rewrite the saved row to include