@vellumai/assistant 0.4.37 → 0.4.41

package/src/media/avatar-router.ts

@@ -0,0 +1,99 @@
+/**
+ * Strategy router for avatar generation.
+ * Selects managed platform or local Gemini path based on config.
+ */
+
+import { getConfig } from "../config/loader.js";
+import { ConfigError, ProviderError } from "../util/errors.js";
+import { getLogger } from "../util/logger.js";
+import type {
+  AvatarGenerationResult,
+  AvatarGenerationStrategy,
+} from "./avatar-types.js";
+import { generateImage } from "./gemini-image-service.js";
+import {
+  generateManagedAvatar,
+  isManagedAvailable,
+} from "./managed-avatar-client.js";
+
+const log = getLogger("avatar-router");
+
+export function getAvatarStrategy(): AvatarGenerationStrategy {
+  return getConfig().avatar.generationStrategy;
+}
+
+async function generateLocal(
+  prompt: string,
+  correlationId?: string,
+): Promise<AvatarGenerationResult> {
+  const config = getConfig();
+  const geminiKey = config.apiKeys.gemini ?? process.env.GEMINI_API_KEY;
+  if (!geminiKey) {
+    throw new ConfigError(
+      "Gemini API key is not configured. Set it via `config set apiKeys.gemini <key>` or the GEMINI_API_KEY environment variable.",
+    );
+  }
+
+  const result = await generateImage(geminiKey, {
+    prompt,
+    mode: "generate",
+    model: config.imageGenModel,
+  });
+
+  const image = result.images[0];
+  if (!image) {
+    throw new ProviderError(
+      "Local Gemini image generation returned no images.",
+      "gemini",
+    );
+  }
+
+  return {
+    imageBase64: image.dataBase64,
+    mimeType: image.mimeType,
+    pathUsed: "local",
+    correlationId,
+  };
+}
+
+export async function routedGenerateAvatar(
+  prompt: string,
+  options?: { correlationId?: string },
+): Promise<AvatarGenerationResult> {
+  const strategy = getAvatarStrategy();
+  const correlationId = options?.correlationId;
+
+  if (strategy === "managed_required") {
+    const managed = await generateManagedAvatar(prompt, { correlationId });
+    return {
+      imageBase64: managed.image.data_base64,
+      mimeType: managed.image.mime_type,
+      pathUsed: "managed",
+      correlationId: managed.correlation_id,
+    };
+  }
+
+  if (strategy === "local_only") {
+    return generateLocal(prompt, correlationId);
+  }
+
+  // managed_prefer: try managed first if available, fall back to local
+  if (isManagedAvailable()) {
+    try {
+      const managed = await generateManagedAvatar(prompt, { correlationId });
+      return {
+        imageBase64: managed.image.data_base64,
+        mimeType: managed.image.mime_type,
+        pathUsed: "managed",
+        correlationId: managed.correlation_id,
+      };
+    } catch (err) {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        "Managed avatar generation failed, falling back to local Gemini",
+      );
+    }
+  }
+
+  return generateLocal(prompt, correlationId);
+}

package/src/media/avatar-types.ts

@@ -0,0 +1,60 @@
+export type AvatarGenerationStrategy = "managed_required" | "managed_prefer" | "local_only";
+
+export interface ManagedAvatarImagePayload {
+  mime_type: string;
+  data_base64: string;
+  bytes: number;
+  sha256: string;
+}
+
+export interface ManagedAvatarResponse {
+  image: ManagedAvatarImagePayload;
+  usage: { billable: boolean; class_name: string };
+  generation_source: string;
+  profile: string;
+  correlation_id: string;
+}
+
+export interface ManagedAvatarErrorResponse {
+  code: string;
+  subcode: string;
+  detail: string;
+  retryable: boolean;
+  correlation_id: string;
+}
+
+export class ManagedAvatarError extends Error {
+  readonly code: string;
+  readonly subcode: string;
+  readonly retryable: boolean;
+  readonly correlationId: string;
+  readonly statusCode: number;
+
+  constructor(opts: {
+    code: string;
+    subcode: string;
+    detail: string;
+    retryable: boolean;
+    correlationId: string;
+    statusCode: number;
+  }) {
+    super(opts.detail);
+    this.name = "ManagedAvatarError";
+    this.code = opts.code;
+    this.subcode = opts.subcode;
+    this.retryable = opts.retryable;
+    this.correlationId = opts.correlationId;
+    this.statusCode = opts.statusCode;
+  }
+}
+
+export interface AvatarGenerationResult {
+  imageBase64: string;
+  mimeType: string;
+  pathUsed: "managed" | "local";
+  correlationId?: string;
+}
+
+export const AVATAR_MIME_ALLOWLIST = new Set(["image/png", "image/jpeg", "image/webp"]);
+export const AVATAR_MAX_DECODED_BYTES = 10 * 1024 * 1024;
+export const AVATAR_PROMPT_MAX_LENGTH = 2000;

package/src/media/managed-avatar-client.ts

@@ -0,0 +1,189 @@
+import { getPlatformBaseUrl } from "../config/env.js";
+import { getConfig } from "../config/loader.js";
+import { getSecureKey } from "../security/secure-keys.js";
+import { getLogger } from "../util/logger.js";
+import {
+  AVATAR_MAX_DECODED_BYTES,
+  AVATAR_MIME_ALLOWLIST,
+  AVATAR_PROMPT_MAX_LENGTH,
+  ManagedAvatarError,
+  type ManagedAvatarErrorResponse,
+  type ManagedAvatarResponse,
+} from "./avatar-types.js";
+
+const log = getLogger("managed-avatar-client");
+
+export function getAssistantApiKey(): string | undefined {
+  return getSecureKey("credential:vellum:assistant_api_key");
+}
+
+export function getManagedAvatarBaseUrl(): string {
+  const baseUrl = getConfig().platform.baseUrl || getPlatformBaseUrl();
+  return baseUrl.replace(/\/+$/, "");
+}
+
+export function isManagedAvailable(): boolean {
+  const apiKey = getAssistantApiKey();
+  const baseUrl = getManagedAvatarBaseUrl();
+  return !!apiKey && apiKey.length > 0 && !!baseUrl && baseUrl.length > 0;
+}
+
+export async function generateManagedAvatar(
+  prompt: string,
+  options?: { correlationId?: string; idempotencyKey?: string },
+): Promise<ManagedAvatarResponse> {
+  if (prompt.length > AVATAR_PROMPT_MAX_LENGTH) {
+    throw new ManagedAvatarError({
+      code: "validation_error",
+      subcode: "prompt_too_long",
+      detail: `Prompt exceeds maximum length of ${AVATAR_PROMPT_MAX_LENGTH} characters`,
+      retryable: false,
+      correlationId: options?.correlationId ?? crypto.randomUUID(),
+      statusCode: 0,
+    });
+  }
+
+  const apiKey = getAssistantApiKey();
+  if (!apiKey) {
+    throw new ManagedAvatarError({
+      code: "configuration_error",
+      subcode: "missing_api_key",
+      detail: "Assistant API key is not configured",
+      retryable: false,
+      correlationId: options?.correlationId ?? crypto.randomUUID(),
+      statusCode: 0,
+    });
+  }
+
+  const baseUrl = getManagedAvatarBaseUrl();
+  if (!baseUrl) {
+    throw new ManagedAvatarError({
+      code: "configuration_error",
+      subcode: "missing_base_url",
+      detail:
+        "Platform base URL is not configured. Set platform.baseUrl in config or PLATFORM_BASE_URL environment variable.",
+      retryable: false,
+      correlationId: options?.correlationId ?? crypto.randomUUID(),
+      statusCode: 0,
+    });
+  }
+
+  const url = `${baseUrl}/v1/assistants/avatar/generate/`;
+  const idempotencyKey = options?.idempotencyKey ?? crypto.randomUUID();
+  const correlationId = options?.correlationId ?? crypto.randomUUID();
+
+  const headers: Record<string, string> = {
+    Authorization: `Api-Key ${apiKey}`,
+    "Content-Type": "application/json",
+    "Idempotency-Key": idempotencyKey,
+    "X-Correlation-Id": correlationId,
+  };
+
+  log.debug({ url, correlationId }, "Requesting managed avatar generation");
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      body: JSON.stringify({ prompt }),
+      signal: AbortSignal.timeout(60_000),
+      headers,
+    });
+  } catch (err) {
+    const isTimeout =
+      err instanceof DOMException && err.name === "TimeoutError";
+    throw new ManagedAvatarError({
+      code: "avatar_generation_failed",
+      subcode: isTimeout ? "upstream_timeout" : "network_error",
+      detail: isTimeout
+        ? "Request to avatar generation service timed out"
+        : `Network error: ${err instanceof Error ? err.message : String(err)}`,
+      retryable: true,
+      correlationId,
+      statusCode: 0,
+    });
+  }
+
+  if (!response.ok) {
+    let errorBody: ManagedAvatarErrorResponse;
+    try {
+      errorBody = (await response.json()) as ManagedAvatarErrorResponse;
+    } catch {
+      throw new ManagedAvatarError({
+        code: "upstream_error",
+        subcode: "unparseable_response",
+        detail: `HTTP ${response.status}: unable to parse error response`,
+        retryable: response.status >= 500 || response.status === 429,
+        correlationId,
+        statusCode: response.status,
+      });
+    }
+
+    throw new ManagedAvatarError({
+      code: errorBody.code ?? "upstream_error",
+      subcode: errorBody.subcode ?? "unknown",
+      detail: errorBody.detail ?? `HTTP ${response.status}`,
+      retryable:
+        errorBody.retryable ??
+        (response.status >= 500 || response.status === 429),
+      correlationId: errorBody.correlation_id ?? correlationId,
+      statusCode: response.status,
+    });
+  }
+
+  let body: ManagedAvatarResponse;
+  try {
+    body = (await response.json()) as ManagedAvatarResponse;
+
+    if (!AVATAR_MIME_ALLOWLIST.has(body.image.mime_type)) {
+      throw new ManagedAvatarError({
+        code: "validation_error",
+        subcode: "disallowed_mime_type",
+        detail: `Response MIME type "${body.image.mime_type}" is not in the allowlist`,
+        retryable: false,
+        correlationId,
+        statusCode: 0,
+      });
+    }
+
+    const b64 = body.image.data_base64;
+    const padding = b64.endsWith("==") ? 2 : b64.endsWith("=") ? 1 : 0;
+    const estimatedDecodedBytes = Math.ceil((b64.length * 3) / 4) - padding;
+    if (
+      estimatedDecodedBytes > AVATAR_MAX_DECODED_BYTES ||
+      body.image.bytes > AVATAR_MAX_DECODED_BYTES
+    ) {
+      throw new ManagedAvatarError({
+        code: "validation_error",
+        subcode: "oversized_image",
+        detail: `Response image size ${Math.max(estimatedDecodedBytes, body.image.bytes)} exceeds maximum of ${AVATAR_MAX_DECODED_BYTES} bytes`,
+        retryable: false,
+        correlationId,
+        statusCode: 0,
+      });
+    }
+
+    log.debug(
+      {
+        correlationId,
+        mimeType: body.image.mime_type,
+        bytes: body.image.bytes,
+      },
+      "Managed avatar generation succeeded",
+    );
+
+    return body;
+  } catch (err) {
+    if (err instanceof ManagedAvatarError) {
+      throw err;
+    }
+    throw new ManagedAvatarError({
+      code: "upstream_error",
+      subcode: "unparseable_response",
+      detail: `Failed to parse avatar generation response: ${err instanceof Error ? err.message : String(err)}`,
+      retryable: false,
+      correlationId,
+      statusCode: 0,
+    });
+  }
+}

package/src/memory/app-migration.ts

@@ -0,0 +1,114 @@
+/**
+ * One-way migration helper: converts legacy single-HTML apps to the
+ * multi-file src/ layout (formatVersion 2).
+ *
+ * Non-destructive — the root index.html is preserved as a legacy fallback.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { getApp, getAppsDir, isMultifileApp } from "./app-store.js";
+
+export interface MigrationResult {
+  ok: boolean;
+  error?: string;
+}
+
+/**
+ * Extract inline `<style>` blocks from HTML, returning the extracted CSS
+ * and the HTML with those blocks replaced by a `<link>` tag.
+ */
+function extractInlineStyles(html: string): {
+  css: string;
+  html: string;
+} {
+  const styleRegex = /<style[^>]*>([\s\S]*?)<\/style>/gi;
+  const cssChunks: string[] = [];
+
+  for (const match of html.matchAll(styleRegex)) {
+    cssChunks.push(match[1].trim());
+  }
+
+  if (cssChunks.length === 0) {
+    return { css: "", html };
+  }
+
+  const css = cssChunks.join("\n\n");
+
+  // Replace the first <style> block with a <link> tag, remove the rest
+  let replaced = false;
+  const updatedHtml = html.replace(styleRegex, () => {
+    if (!replaced) {
+      replaced = true;
+      return `<link rel="stylesheet" href="styles.css">`;
+    }
+    return "";
+  });
+
+  return { css, html: updatedHtml };
+}
+
+/**
+ * Migrate a legacy single-HTML app to the multi-file src/ layout.
+ *
+ * Steps:
+ *   1. Read existing index.html
+ *   2. Create {appId}/src/ directory
+ *   3. Copy HTML content to src/index.html (with inline styles extracted)
+ *   4. Create src/main.tsx placeholder entry point
+ *   5. If inline styles found, write src/styles.css
+ *   6. Update app metadata to formatVersion: 2
+ *   7. Keep root index.html untouched (legacy fallback)
+ */
+export function migrateAppToMultifile(appId: string): MigrationResult {
+  const app = getApp(appId);
+  if (!app) {
+    return { ok: false, error: `App not found: ${appId}` };
+  }
+
+  // Already migrated — treat as no-op
+  if (isMultifileApp(app)) {
+    return { ok: true };
+  }
+
+  const appsDir = getAppsDir();
+  const appDir = join(appsDir, appId);
+  const rootIndex = join(appDir, "index.html");
+
+  if (!existsSync(rootIndex)) {
+    return { ok: false, error: `Root index.html not found for app ${appId}` };
+  }
+
+  const originalHtml = readFileSync(rootIndex, "utf-8");
+
+  // Create src/ directory
+  const srcDir = join(appDir, "src");
+  mkdirSync(srcDir, { recursive: true });
+
+  // Extract inline styles if present
+  const { css, html: processedHtml } = extractInlineStyles(originalHtml);
+
+  // Write src/index.html
+  writeFileSync(join(srcDir, "index.html"), processedHtml, "utf-8");
+
+  // Write src/main.tsx placeholder
+  const styleImport = css ? "import './styles.css';\n" : "";
+  const mainTsx = `// Entry point — migrated from legacy single-file app\n${styleImport}\nconsole.log('App loaded');\n`;
+  writeFileSync(join(srcDir, "main.tsx"), mainTsx, "utf-8");
+
+  // Write src/styles.css if styles were extracted
+  if (css) {
+    writeFileSync(join(srcDir, "styles.css"), css, "utf-8");
+  }
+
+  // Update metadata to formatVersion 2
+  const metadataPath = join(appsDir, `${appId}.json`);
+  const rawMeta = readFileSync(metadataPath, "utf-8");
+  const metadata = JSON.parse(rawMeta);
+  metadata.formatVersion = 2;
+  metadata.updatedAt = Date.now();
+  writeFileSync(metadataPath, JSON.stringify(metadata, null, 2));
+
+  return { ok: true };
+}

package/src/memory/app-store.ts

@@ -51,6 +51,15 @@ export interface AppDefinition {
   pages?: Record<string, string>;
   createdAt: number;
   updatedAt: number;
+  /** App format version. undefined or 1 = legacy single-HTML, 2 = multi-file TSX. */
+  formatVersion?: number;
+}
+
+/**
+ * Returns true if the app uses the multi-file TSX format (formatVersion 2).
+ */
+export function isMultifileApp(app: AppDefinition): boolean {
+  return app.formatVersion === 2;
 }
 
 export interface AppRecord {
@@ -195,6 +204,7 @@ export function createApp(params: {
   htmlDefinition: string;
   version?: string;
   pages?: Record<string, string>;
+  formatVersion?: number;
 }): AppDefinition {
   const dir = getAppsDir();
   const now = Date.now();
@@ -209,6 +219,7 @@ export function createApp(params: {
     version: params.version,
     createdAt: now,
     updatedAt: now,
+    formatVersion: params.formatVersion,
   };
 
   // Write htmlDefinition to {appId}/index.html on disk

package/src/memory/qdrant-client.ts

@@ -365,7 +365,7 @@ export class VellumQdrantClient {
   /**
    * Detect "collection not found" errors from Qdrant so callers can
    * reset collectionReady and retry after an external deletion
-   * (e.g. `vellum sessions clear`).
+   * (e.g. `assistant sessions clear`).
    */
   private isCollectionMissing(err: unknown): boolean {
     if (

package/src/messaging/providers/slack/client.ts

@@ -231,14 +231,24 @@ export async function userInfo(
   return request<SlackUserInfoResponse>(token, "users.info", { user: userId });
 }
 
+export interface PostMessageOptions {
+  threadTs?: string;
+  blocks?: unknown[];
+}
+
 export async function postMessage(
   token: string,
   channel: string,
   text: string,
-  threadTs?: string,
+  optionsOrThreadTs?: PostMessageOptions | string,
 ): Promise<SlackPostMessageResponse> {
+  const opts: PostMessageOptions =
+    typeof optionsOrThreadTs === "string"
+      ? { threadTs: optionsOrThreadTs }
+      : (optionsOrThreadTs ?? {});
   const body: Record<string, unknown> = { channel, text };
-  if (threadTs) body.thread_ts = threadTs;
+  if (opts.threadTs) body.thread_ts = opts.threadTs;
+  if (opts.blocks) body.blocks = opts.blocks;
   return request<SlackPostMessageResponse>(
     token,
     "chat.postMessage",

package/src/messaging/providers/sms/adapter.ts

@@ -14,6 +14,10 @@
  * a per-user OAuth token.
  */
 
+import {
+  getTwilioCredentials,
+  hasTwilioCredentials,
+} from "../../../calls/twilio-rest.js";
 import {
   getGatewayInternalBaseUrl,
   getTwilioPhoneNumberEnv,
@@ -48,14 +52,6 @@ function getBearerToken(): string {
   return mintDaemonDeliveryToken();
 }
 
-/** Check whether Twilio credentials are stored. */
-function hasTwilioCredentials(): boolean {
-  return (
-    !!getSecureKey("credential:twilio:account_sid") &&
-    !!getSecureKey("credential:twilio:auth_token")
-  );
-}
-
 /** Resolve the configured SMS phone number. */
 function getPhoneNumber(): string | undefined {
   const fromEnv = getTwilioPhoneNumberEnv();
@@ -118,7 +114,7 @@ export const smsMessagingProvider: MessagingProvider = {
           | Record<string, string>
           | undefined;
         if (mappings && Object.keys(mappings).length > 0) {
-          const accountSid = getSecureKey("credential:twilio:account_sid")!;
+          const accountSid = getTwilioCredentials().accountSid;
           return {
             connected: true,
             user: "assistant-scoped",
@@ -143,7 +139,7 @@ export const smsMessagingProvider: MessagingProvider = {
       };
     }
 
-    const accountSid = getSecureKey("credential:twilio:account_sid")!;
+    const accountSid = getTwilioCredentials().accountSid;
 
     return {
       connected: true,

package/src/migrations/data-layout.ts

@@ -51,7 +51,14 @@ export function migrateToDataLayout(): void {
   migrateItem(join(root, "qdrant.pid"), join(data, "qdrant", "qdrant.pid"));
 
   // Qdrant binary: ~/.vellum/bin/ → ~/.vellum/data/qdrant/bin/
-  migrateItem(join(root, "bin"), join(data, "qdrant", "bin"));
+  // Only migrate if the directory actually contains a qdrant binary.
+  // After the CLI-launcher feature landed, ~/.vellum/bin/ is used for
+  // launcher scripts (doordash, map, etc.), not qdrant, so moving it
+  // blindly would break CLI launchers on every fresh hatch.
+  const legacyBinDir = join(root, "bin");
+  if (existsSync(join(legacyBinDir, "qdrant"))) {
+    migrateItem(legacyBinDir, join(data, "qdrant", "bin"));
+  }
 
   // Logs: ~/.vellum/logs/ → ~/.vellum/data/logs/
   migrateItem(join(root, "logs"), join(data, "logs"));

package/src/oauth/token-persistence.ts

@@ -10,7 +10,10 @@ import type {
   OAuth2FlowResult,
   TokenEndpointAuthMethod,
 } from "../security/oauth2.js";
-import { deleteSecureKey, setSecureKey } from "../security/secure-keys.js";
+import {
+  deleteSecureKeyAsync,
+  setSecureKeyAsync,
+} from "../security/secure-keys.js";
 import {
   deleteCredentialMetadata,
   upsertCredentialMetadata,
@@ -67,7 +70,7 @@ export async function storeOAuth2Tokens(
     wellKnownInjectionTemplates,
   } = params;
 
-  const tokenStored = setSecureKey(
+  const tokenStored = await setSecureKeyAsync(
     `credential:${service}:access_token`,
     tokens.accessToken,
   );
@@ -95,7 +98,7 @@ export async function storeOAuth2Tokens(
   }
 
   // Persist client credentials in keychain for defense in depth
-  const clientIdStored = setSecureKey(
+  const clientIdStored = await setSecureKeyAsync(
     `credential:${service}:client_id`,
     clientId,
   );
@@ -103,7 +106,7 @@ export async function storeOAuth2Tokens(
     throw new Error("Failed to store client_id in secure storage");
   }
   if (clientSecret) {
-    const clientSecretStored = setSecureKey(
+    const clientSecretStored = await setSecureKeyAsync(
       `credential:${service}:client_secret`,
       clientSecret,
     );
@@ -129,7 +132,7 @@ export async function storeOAuth2Tokens(
   });
 
   if (tokens.refreshToken) {
-    const refreshStored = setSecureKey(
+    const refreshStored = await setSecureKeyAsync(
       `credential:${service}:refresh_token`,
       tokens.refreshToken,
     );
@@ -140,7 +143,7 @@ export async function storeOAuth2Tokens(
     // Re-auth grants that omit refresh_token must clear any stale stored
     // token — otherwise withValidToken() will attempt refresh with invalid
     // credentials.
-    deleteSecureKey(`credential:${service}:refresh_token`);
+    await deleteSecureKeyAsync(`credential:${service}:refresh_token`);
     deleteCredentialMetadata(service, "refresh_token");
   }
 

package/src/runtime/assistant-scope.ts

@@ -6,5 +6,10 @@
  * gateway and platform layers (hatch, invite links, etc.). Daemon code
  * should never derive scoping decisions from externally-provided assistant
  * IDs — use this constant instead.
+ *
+ * Multi-instance invariant: each daemon process is single-tenant within
+ * its own BASE_DATA_DIR. The fixed "self" value works across multiple
+ * local instances because each instance has isolated storage — there is
+ * no cross-instance data sharing that would require disambiguating IDs.
  */
 export const DAEMON_INTERNAL_ASSISTANT_ID = "self" as const;

package/src/runtime/auth/route-policy.ts

@@ -244,6 +244,10 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "integrations/twilio/sms/test", scopes: ["settings.write"] },
   { endpoint: "integrations/twilio/sms/doctor", scopes: ["settings.write"] },
 
+  // Slack share
+  { endpoint: "slack/channels", scopes: ["settings.read"] },
+  { endpoint: "slack/share", scopes: ["settings.write"] },
+
   // Channel readiness
   { endpoint: "channels/readiness", scopes: ["settings.read"] },
   { endpoint: "channels/readiness/refresh", scopes: ["settings.write"] },