@vellumai/assistant 0.6.4 → 0.6.6

package/src/media/avatar-router.ts

@@ -1,60 +1,45 @@
 import { getConfig } from "../config/loader.js";
-import {
-  buildManagedBaseUrl,
-  resolveManagedProxyContext,
-} from "../providers/managed-proxy/context.js";
-import { getProviderKeyAsync } from "../security/secure-keys.js";
 import { ConfigError, ProviderError } from "../util/errors.js";
-import {
-  generateImage,
-  type ImageGenCredentials,
-} from "./gemini-image-service.js";
+import { resolveImageGenCredentials } from "./image-credentials.js";
+import { generateImage, mapImageGenError } from "./image-service.js";
 
 export async function generateAvatar(
   prompt: string,
 ): Promise<{ imageBase64: string; mimeType: string }> {
   const config = getConfig();
-  const imageGenMode = config.services["image-generation"].mode;
+  const svc = config.services["image-generation"];
 
-  // Resolve credentials strictly based on mode — no cross-mode fallbacks
-  let credentials: ImageGenCredentials | undefined;
-
-  if (imageGenMode === "managed") {
-    const managedBaseUrl = await buildManagedBaseUrl("gemini");
-    if (managedBaseUrl) {
-      const ctx = await resolveManagedProxyContext();
-      credentials = {
-        type: "managed-proxy",
-        assistantApiKey: ctx.assistantApiKey,
-        baseUrl: managedBaseUrl,
-      };
-    }
-  } else {
-    const geminiKey = await getProviderKeyAsync("gemini");
-    if (geminiKey) {
-      credentials = { type: "direct", apiKey: geminiKey };
-    }
-  }
+  const { credentials, errorHint } = await resolveImageGenCredentials({
+    provider: svc.provider,
+    mode: svc.mode,
+  });
 
   if (!credentials) {
-    const hint =
-      imageGenMode === "managed"
-        ? "Managed proxy is not available. Please log in to Vellum or switch to Your Own mode."
-        : "Gemini API key is not configured. Please set your Gemini API key in Settings > Models & Services.";
-    throw new ConfigError(hint);
+    throw new ConfigError(errorHint ?? "Image generation is not configured.");
   }
 
-  const result = await generateImage(credentials, {
-    prompt,
-    mode: "generate",
-    model: config.services["image-generation"].model,
-  });
+  let result;
+  try {
+    result = await generateImage(svc.provider, credentials, {
+      prompt,
+      mode: "generate",
+      model: svc.model,
+    });
+  } catch (error) {
+    // Re-throw with a provider-aware, user-friendly message so callers
+    // (e.g. avatar-generator) don't need provider context to surface a
+    // useful error.
+    throw new ProviderError(
+      mapImageGenError(svc.provider, error),
+      svc.provider,
+    );
+  }
 
   const image = result.images[0];
   if (!image) {
     throw new ProviderError(
-      "Gemini image generation returned no images.",
-      "gemini",
+      "Image generation returned no images.",
+      svc.provider,
     );
   }
 

package/src/media/gemini-image-service.ts

@@ -1,45 +1,13 @@
 import { ApiError, GoogleGenAI } from "@google/genai";
 
-// --- Request / Response types ---
-
-interface ImageGenerationRequest {
-  prompt: string;
-  mode: "generate" | "edit";
-  /** Base64-encoded source images for edit mode */
-  sourceImages?: Array<{ mimeType: string; dataBase64: string }>;
-  /** Model override; defaults to 'gemini-3.1-flash-image-preview' */
-  model?: string;
-  /** Number of output variants (1-4, default 1) */
-  variants?: number;
-}
-
-/** Credentials for direct Gemini API access. */
-interface DirectCredentials {
-  type: "direct";
-  apiKey: string;
-}
-
-/** Credentials for managed proxy access (platform translates to Vertex AI). */
-interface ManagedProxyCredentials {
-  type: "managed-proxy";
-  assistantApiKey: string;
-  baseUrl: string;
-}
-
-export type ImageGenCredentials = DirectCredentials | ManagedProxyCredentials;
-
-interface GeneratedImage {
-  mimeType: string;
-  dataBase64: string;
-  /** Short title derived from the model's text response, if available. */
-  title?: string;
-}
-
-interface ImageGenerationResult {
-  images: GeneratedImage[];
-  text?: string;
-  resolvedModel: string;
-}
+import {
+  type GeneratedImage,
+  type ImageGenCredentials,
+  type ImageGenerationRequest,
+  type ImageGenerationResult,
+  type ManagedProxyCredentials,
+  MAX_VARIANTS,
+} from "./types.js";
 
 // --- Constants ---
 
@@ -48,7 +16,6 @@ const ALLOWED_MODELS = new Set([
   "gemini-3.1-flash-image-preview",
   "gemini-3-pro-image-preview",
 ]);
-const MAX_VARIANTS = 4;
 
 // --- Error mapping ---
 

package/src/media/image-credentials.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared credential resolver for image-generation call sites (image-studio
+ * tool, CLI `image-generation` command, app-icon generator).
+ *
+ * Each call site picks between the managed-proxy path (routes through the
+ * platform) and the "your own" path (direct provider API key). This module
+ * resolves either path and returns a provider-aware error hint when
+ * credentials are unavailable.
+ */
+
+import { MANAGED_PROVIDER_META } from "../providers/managed-proxy/constants.js";
+import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { getProviderKeyAsync } from "../security/secure-keys.js";
+import type { ImageGenCredentials, ImageGenProvider } from "./types.js";
+
+/**
+ * Resolve credentials for an image-generation request.
+ *
+ * - `mode === "managed"`: returns managed-proxy credentials when the
+ *   platform URL and assistant API key are both configured, otherwise
+ *   returns a hint telling the user to log in or switch modes.
+ * - `mode === "your-own"`: returns direct credentials when the provider
+ *   API key is present in secure storage (or the env-var fallback),
+ *   otherwise returns a provider-aware hint pointing at Settings.
+ */
+export async function resolveImageGenCredentials(opts: {
+  provider: ImageGenProvider;
+  mode: "managed" | "your-own";
+}): Promise<{ credentials?: ImageGenCredentials; errorHint?: string }> {
+  const { provider, mode } = opts;
+
+  if (mode === "managed") {
+    // Resolve platform URL + assistant API key from a single snapshot so
+    // baseUrl and assistantApiKey can't diverge if the credential is cleared
+    // between lookups.
+    const meta = MANAGED_PROVIDER_META[provider];
+    const ctx = await resolveManagedProxyContext();
+    if (
+      !meta?.managed ||
+      !meta.proxyPath ||
+      !ctx.enabled ||
+      !ctx.assistantApiKey
+    ) {
+      return {
+        errorHint:
+          "Managed proxy is not available. Please log in to Vellum or switch to Your Own mode.",
+      };
+    }
+    return {
+      credentials: {
+        type: "managed-proxy",
+        assistantApiKey: ctx.assistantApiKey,
+        baseUrl: `${ctx.platformBaseUrl}${meta.proxyPath}`,
+      },
+    };
+  }
+
+  // mode === "your-own"
+  const apiKey = await getProviderKeyAsync(provider);
+  if (apiKey) {
+    return { credentials: { type: "direct", apiKey } };
+  }
+  return { errorHint: providerKeyHint(provider) };
+}
+
+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.";
+    case "openai":
+      return "No OpenAI API key configured. Please set your OpenAI API key in Settings > Models & Services.";
+  }
+}

package/src/media/image-service.ts

@@ -0,0 +1,85 @@
+import {
+  generateImage as generateImageGemini,
+  mapGeminiError,
+} from "./gemini-image-service.js";
+import { generateImageOpenAI, mapOpenAIError } from "./openai-image-service.js";
+import type {
+  ImageGenCredentials,
+  ImageGenerationRequest,
+  ImageGenerationResult,
+  ImageGenProvider,
+} from "./types.js";
+
+/**
+ * Dispatch image generation to the provider-specific implementation.
+ */
+export function generateImage(
+  provider: ImageGenProvider,
+  credentials: ImageGenCredentials,
+  request: ImageGenerationRequest,
+): Promise<ImageGenerationResult> {
+  switch (provider) {
+    case "openai":
+      return generateImageOpenAI(credentials, request);
+    case "gemini":
+      return generateImageGemini(credentials, request);
+    default: {
+      const _exhaustive: never = provider;
+      throw new Error(`Unknown image generation provider: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Dispatch error mapping to the provider-specific implementation.
+ */
+export function mapImageGenError(
+  provider: ImageGenProvider,
+  error: unknown,
+): string {
+  switch (provider) {
+    case "openai":
+      return mapOpenAIError(error);
+    case "gemini":
+      return mapGeminiError(error);
+    default: {
+      const _exhaustive: never = provider;
+      throw new Error(`Unknown image generation provider: ${_exhaustive}`);
+    }
+  }
+}
+
+/**
+ * Derive the owning provider from an explicit model ID.
+ *
+ * When a caller (LLM tool invocation, CLI `--model` flag) passes an explicit
+ * `model` argument, the request should dispatch to the provider that owns
+ * that model — not to the user's configured Settings provider. Without this,
+ * asking for `gpt-image-2` while `services["image-generation"].provider` is
+ * `gemini` silently falls back to the Gemini default model.
+ *
+ * Model prefix mapping:
+ *   - `gpt-*` or `dall-e-*` → `openai`
+ *   - `gemini-*`            → `gemini`
+ *   - anything else (or `undefined`) → the provided `fallback`
+ */
+export function providerForModel(
+  model: unknown,
+  fallback: ImageGenProvider,
+): ImageGenProvider {
+  // `model` originates from an LLM tool call's `input.model`, which is a
+  // `Record<string, unknown>` without runtime validation — so a non-string
+  // value (e.g. `{"model": 123}`) must not crash `.startsWith`.
+  if (typeof model !== "string" || !model) return fallback;
+  if (model.startsWith("gpt-") || model.startsWith("dall-e-")) return "openai";
+  if (model.startsWith("gemini-")) return "gemini";
+  return fallback;
+}
+
+export type {
+  GeneratedImage,
+  ImageGenCredentials,
+  ImageGenerationRequest,
+  ImageGenerationResult,
+  ImageGenProvider,
+} from "./types.js";

package/src/media/openai-image-service.ts

@@ -0,0 +1,131 @@
+import OpenAI from "openai";
+import { toFile } from "openai/uploads";
+
+import {
+  type GeneratedImage,
+  type ImageGenCredentials,
+  type ImageGenerationRequest,
+  type ImageGenerationResult,
+  MAX_VARIANTS,
+} from "./types.js";
+
+// --- Constants ---
+
+const DEFAULT_MODEL = "gpt-image-2";
+const ALLOWED_MODELS = new Set(["gpt-image-2"]);
+
+// --- Error mapping ---
+
+/**
+ * Map an error raised by the OpenAI Images API to a user-friendly string.
+ * Mirrors the status-code branches of `mapGeminiError` in
+ * `./gemini-image-service.ts`.
+ */
+export function mapOpenAIError(error: unknown): string {
+  if (error instanceof OpenAI.APIError) {
+    const status = error.status;
+    if (status === 400) {
+      return "The image request was invalid. Please check your prompt and try again.";
+    }
+    if (status === 401 || status === 403) {
+      return "Authentication failed. Please check your OpenAI API key.";
+    }
+    if (status === 429) {
+      return "Rate limit exceeded. Please wait a moment and try again.";
+    }
+    if (status !== undefined && status >= 500) {
+      return "The OpenAI service is temporarily unavailable. Please try again later.";
+    }
+    return `OpenAI API error (status ${status}). Please try again.`;
+  }
+  if (error instanceof Error) {
+    return `Image generation failed: ${error.message}`;
+  }
+  return "An unexpected error occurred during image generation.";
+}
+
+// --- Title derivation ---
+
+/**
+ * Derive a short filename-safe title from the first 6 words of the prompt.
+ * Uses the same sanitization regex as `extractTitle` in
+ * `./gemini-image-service.ts`.
+ */
+function deriveTitleFromPrompt(prompt: string): string | undefined {
+  const firstWords = prompt.trim().split(/\s+/).slice(0, 6).join(" ");
+  if (!firstWords) return undefined;
+  const sanitized = firstWords
+    .replace(/[^\w\s-]/g, "")
+    .replace(/\s+/g, "-")
+    .toLowerCase()
+    .slice(0, 60);
+  return sanitized.length > 0 ? sanitized : undefined;
+}
+
+// --- Core function ---
+
+/**
+ * Generate or edit an image via the OpenAI Images API (`gpt-image-2`).
+ *
+ * The OpenAI Images API does not return commentary text, so the returned
+ * `text` field is always `undefined`. A title is derived from the prompt
+ * instead and attached to every returned image.
+ */
+export async function generateImageOpenAI(
+  credentials: ImageGenCredentials,
+  request: ImageGenerationRequest,
+): Promise<ImageGenerationResult> {
+  const model =
+    request.model && ALLOWED_MODELS.has(request.model)
+      ? request.model
+      : DEFAULT_MODEL;
+
+  const variants = Math.max(1, Math.min(request.variants ?? 1, MAX_VARIANTS));
+
+  const client =
+    credentials.type === "managed-proxy"
+      ? new OpenAI({
+          apiKey: credentials.assistantApiKey,
+          baseURL: credentials.baseUrl,
+        })
+      : new OpenAI({ apiKey: credentials.apiKey });
+
+  const title = deriveTitleFromPrompt(request.prompt);
+
+  let response: { data?: Array<{ b64_json?: string }> };
+
+  if (request.mode === "edit" && request.sourceImages) {
+    const files = await Promise.all(
+      request.sourceImages.map((img) =>
+        toFile(Buffer.from(img.dataBase64, "base64"), "input.png", {
+          type: img.mimeType,
+        }),
+      ),
+    );
+    response = (await client.images.edit({
+      model,
+      prompt: request.prompt,
+      image: files,
+      n: variants,
+    })) as { data?: Array<{ b64_json?: string }> };
+  } else {
+    response = (await client.images.generate({
+      model,
+      prompt: request.prompt,
+      n: variants,
+    })) as { data?: Array<{ b64_json?: string }> };
+  }
+
+  const images: GeneratedImage[] = [];
+  for (const entry of response.data ?? []) {
+    if (!entry.b64_json) continue;
+    const img: GeneratedImage = {
+      mimeType: "image/png",
+      dataBase64: entry.b64_json,
+    };
+    if (title) img.title = title;
+    images.push(img);
+  }
+
+  return { images, text: undefined, resolvedModel: model };
+}

package/src/media/types.ts

@@ -0,0 +1,46 @@
+export type ImageGenProvider = "gemini" | "openai";
+
+export interface DirectCredentials {
+  type: "direct";
+  apiKey: string;
+}
+export interface ManagedProxyCredentials {
+  type: "managed-proxy";
+  assistantApiKey: string;
+  baseUrl: string;
+}
+export type ImageGenCredentials = DirectCredentials | ManagedProxyCredentials;
+
+export interface ImageGenerationRequest {
+  prompt: string;
+  mode: "generate" | "edit";
+  sourceImages?: Array<{ mimeType: string; dataBase64: string }>;
+  model?: string;
+  variants?: number;
+}
+
+export interface GeneratedImage {
+  mimeType: string;
+  dataBase64: string;
+  title?: string;
+}
+export interface ImageGenerationResult {
+  images: GeneratedImage[];
+  text?: string;
+  resolvedModel: string;
+}
+
+export const MAX_VARIANTS = 4;
+
+/**
+ * Derive the image-generation provider from a model identifier by prefix.
+ * Canonical mapping shared between the runtime model setter
+ * (`setImageGenModel`) and workspace migration 006-services-config so the
+ * two cannot drift. Unknown models fall through to "gemini".
+ */
+export function providerForImageModelPrefix(model: string): ImageGenProvider {
+  if (model.startsWith("gpt") || model.startsWith("dall-e")) {
+    return "openai";
+  }
+  return "gemini";
+}

package/src/memory/__tests__/conversation-analyze-job.test.ts

@@ -64,6 +64,7 @@ mock.module("../auto-analysis-enqueue.js", () => ({
 
 import { DEFAULT_CONFIG } from "../../config/defaults.js";
 import type { AssistantConfig } from "../../config/types.js";
+import { BackendUnavailableError } from "../../util/errors.js";
 import { conversationAnalyzeJob } from "../conversation-analyze-job.js";
 import type { MemoryJob } from "../jobs-store.js";
 
@@ -121,20 +122,20 @@ describe("conversationAnalyzeJob", () => {
     expect(mockGetAnalysisDeps).not.toHaveBeenCalled();
   });
 
-  test("returns without calling the service when deps singleton is not yet initialized", async () => {
-    // Deps singleton is unset during slow daemon startup. The handler must
-    // NOT throw — a plain Error here is classified as fatal by
-    // classifyError() and the worker would mark the job permanently failed
-    // (failMemoryJob with maxAttempts: 1). Returning lets the next batch /
-    // idle / lifecycle trigger from enqueueAutoAnalysisIfEnabled() produce
-    // a fresh job once the daemon has fully started.
+  test("throws BackendUnavailableError when deps singleton is not yet initialized", async () => {
+    // Deps singleton is unset during slow daemon startup. The handler throws
+    // BackendUnavailableError so handleJobError() in the worker defers the
+    // job with exponential backoff (via deferMemoryJob) instead of completing
+    // it. Returning success here would permanently drop the job via
+    // completeMemoryJob — conversations with a pre-existing queued job
+    // during startup and no subsequent activity would never be analyzed.
     mockGetAnalysisDeps.mockImplementation(() => null);
     await expect(
       conversationAnalyzeJob(
         makeJob({ conversationId: "conv-1" }),
         TEST_CONFIG,
       ),
-    ).resolves.toBeUndefined();
+    ).rejects.toBeInstanceOf(BackendUnavailableError);
     expect(analyzeCalls).toHaveLength(0);
     expect(mockGetAnalysisDeps).toHaveBeenCalled();
   });

package/src/memory/__tests__/conversation-group-migration.test.ts

@@ -0,0 +1,99 @@
+import { beforeAll, describe, expect, mock, test } from "bun:test";
+
+mock.module("../../util/logger.js", () => ({
+  getLogger: () =>
+    new Proxy({} as Record<string, unknown>, {
+      get: () => () => {},
+    }),
+}));
+
+import { ensureGroupMigration } from "../conversation-group-migration.js";
+import { initializeDb, rawAll, rawExec, rawGet, rawRun } from "../db.js";
+
+initializeDb();
+
+// Simulate a legacy install that has the `system:reflections` system group
+// plus a conversation pointing at it. The migration must:
+//   1. Seed the current system groups (without `system:reflections`).
+//   2. Move the legacy conversation to `system:background` (step 6).
+//   3. Delete the orphaned `system:reflections` row (step 7).
+//
+// We pre-create the `conversation_groups` table and `group_id` column directly
+// because the migration's own CREATE TABLE IF NOT EXISTS / ALTER TABLE steps
+// would otherwise be the first to introduce them — there's no way to seed the
+// "legacy" row until they exist.
+describe("ensureGroupMigration — reflections cleanup", () => {
+  beforeAll(() => {
+    rawExec(`
+      CREATE TABLE IF NOT EXISTS conversation_groups (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        sort_position REAL NOT NULL DEFAULT 0,
+        is_system_group BOOLEAN NOT NULL DEFAULT FALSE,
+        created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
+        updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+      )
+    `);
+    try {
+      rawRun(
+        "ALTER TABLE conversations ADD COLUMN group_id TEXT REFERENCES conversation_groups(id) ON DELETE SET NULL",
+      );
+    } catch {
+      // column already present — ok
+    }
+    rawRun(
+      "INSERT OR IGNORE INTO conversation_groups (id, name, sort_position, is_system_group) VALUES ('system:reflections', 'Reflections', 100, TRUE)",
+    );
+    const now = Math.floor(Date.now() / 1000);
+    rawRun(
+      "INSERT INTO conversations (id, created_at, updated_at, group_id) VALUES (?, ?, ?, ?)",
+      "legacy-refl-1",
+      now,
+      now,
+      "system:reflections",
+    );
+
+    ensureGroupMigration();
+  });
+
+  test("moves legacy system:reflections conversations to system:background", () => {
+    const legacy = rawGet<{ group_id: string | null }>(
+      "SELECT group_id FROM conversations WHERE id = 'legacy-refl-1'",
+    );
+    expect(legacy?.group_id).toBe("system:background");
+  });
+
+  test("deletes the orphaned system:reflections group row", () => {
+    const refl = rawGet<{ id: string }>(
+      "SELECT id FROM conversation_groups WHERE id = 'system:reflections'",
+    );
+    expect(refl).toBeNull();
+  });
+
+  test("seeds the current system groups without system:reflections", () => {
+    const systemIds = rawAll<{ id: string }>(
+      "SELECT id FROM conversation_groups WHERE id LIKE 'system:%' ORDER BY id",
+    ).map((r) => r.id);
+    expect(systemIds).toEqual([
+      "system:all",
+      "system:background",
+      "system:pinned",
+      "system:scheduled",
+    ]);
+  });
+
+  test("records the cleanup sentinel so the step is idempotent", () => {
+    const sentinel = rawGet<{ id: string }>(
+      "SELECT id FROM conversation_groups WHERE id = '_reflections_group_deleted_complete'",
+    );
+    expect(sentinel?.id).toBe("_reflections_group_deleted_complete");
+  });
+
+  test("re-running ensureGroupMigration does not recreate the stale group", () => {
+    expect(() => ensureGroupMigration()).not.toThrow();
+    const refl = rawGet<{ id: string }>(
+      "SELECT id FROM conversation_groups WHERE id = 'system:reflections'",
+    );
+    expect(refl).toBeNull();
+  });
+});

package/src/memory/admin.ts

@@ -6,6 +6,11 @@ import { deleteMemoryCheckpoint } from "./checkpoints.js";
 import { getConversationMemoryScopeId } from "./conversation-crud.js";
 import { getDb, rawGet } from "./db.js";
 import { getMemoryBackendStatus } from "./embedding-backend.js";
+import {
+  type CompactionOptions,
+  type CompactionResult,
+  compactLongMemories,
+} from "./graph/compaction.js";
 import { handleRecall, type RecallResult } from "./graph/tool-handlers.js";
 import {
   enqueueBackfillJob,
@@ -138,6 +143,19 @@ export async function cleanupShortSegments(opts?: {
   return { removed, failed };
 }
 
+// ── Long-memory compaction ────────────────────────────────────────────
+
+/**
+ * One-off backfill that rewrites over-long memory node content to fit the
+ * extraction prompt's 1-3 sentence / ~300 character length cap. Preview
+ * mode (opts.apply=false) lists candidates without calling the LLM.
+ */
+export async function compactLongMemoryNodes(
+  opts: CompactionOptions = {},
+): Promise<CompactionResult> {
+  return compactLongMemories(opts);
+}
+
 // ── Re-extraction ──────────────────────────────────────────────────────
 
 export interface ReextractTarget {