@vellumai/assistant 0.6.3 → 0.6.5

package/src/cli.ts

@@ -113,23 +113,6 @@ export function formatConfirmationCommandPreview(
   if (req.toolName === "web_fetch") {
     return `fetch ${sanitizeUrlForDisplay(req.input.url ?? "")}`;
   }
-  if (req.toolName === "browser_navigate") {
-    return `navigate ${sanitizeUrlForDisplay(req.input.url ?? "")}`;
-  }
-  if (req.toolName === "browser_close") {
-    return req.input.close_all_pages
-      ? "close all browser pages"
-      : "close browser page";
-  }
-  if (req.toolName === "browser_click") {
-    return `click ${req.input.element_id ?? req.input.selector ?? ""}`;
-  }
-  if (req.toolName === "browser_type") {
-    return `type into ${req.input.element_id ?? req.input.selector ?? ""}`;
-  }
-  if (req.toolName === "browser_press_key") {
-    return `press "${req.input.key ?? ""}"`;
-  }
   return req.toolName;
 }
 
@@ -174,26 +157,6 @@ export async function startCli(): Promise<void> {
         return `Editing ${input.path ?? ""}...`;
       case "web_fetch":
         return `Fetching ${sanitizeUrlForDisplay(input.url).slice(0, 80)}...`;
-      case "browser_navigate":
-        return `Navigating to ${sanitizeUrlForDisplay(input.url).slice(0, 80)}...`;
-      case "browser_snapshot":
-        return "Taking page snapshot...";
-      case "browser_close":
-        return "Closing browser...";
-      case "browser_click":
-        return `Clicking ${String(input.element_id ?? input.selector ?? "").slice(0, 60)}...`;
-      case "browser_type":
-        return `Typing into ${String(input.element_id ?? input.selector ?? "").slice(0, 60)}...`;
-      case "browser_press_key":
-        return `Pressing "${String(input.key ?? "")}"...`;
-      case "browser_wait_for":
-        if (input.selector)
-          return `Waiting for ${String(input.selector).slice(0, 60)}...`;
-        if (input.text)
-          return `Waiting for text "${String(input.text).slice(0, 40)}"...`;
-        return `Waiting ${input.duration ?? 0}ms...`;
-      case "browser_extract":
-        return "Extracting page content...";
       default:
         return `Running ${toolName}...`;
     }

package/src/config/__tests__/backup-schema.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  BackupConfigSchema,
+  BackupDestinationSchema,
+  BackupOffsiteConfigSchema,
+} from "../schemas/backup.js";
+
+describe("BackupConfigSchema", () => {
+  test("empty object parses to full defaults (disabled, sensible intervals, iCloud default)", () => {
+    const parsed = BackupConfigSchema.parse({});
+    expect(parsed).toEqual({
+      enabled: false,
+      intervalHours: 6,
+      retention: 7,
+      offsite: { enabled: true, destinations: null },
+      localDirectory: null,
+    });
+  });
+
+  test("rejects intervalHours: 0 (must be >= 1)", () => {
+    const result = BackupConfigSchema.safeParse({ intervalHours: 0 });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects intervalHours above max 168", () => {
+    const result = BackupConfigSchema.safeParse({ intervalHours: 169 });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects retention: 0 (must be >= 1)", () => {
+    const result = BackupConfigSchema.safeParse({ retention: 0 });
+    expect(result.success).toBe(false);
+  });
+
+  test("rejects retention above max 100", () => {
+    const result = BackupConfigSchema.safeParse({ retention: 101 });
+    expect(result.success).toBe(false);
+  });
+
+  test("valid custom values round-trip", () => {
+    const input = {
+      enabled: true,
+      intervalHours: 12,
+      retention: 30,
+      offsite: {
+        enabled: false,
+        destinations: [{ path: "/mnt/backups", encrypt: true }],
+      },
+      localDirectory: "/var/backups/vellum",
+    };
+    const parsed = BackupConfigSchema.parse(input);
+    expect(parsed).toEqual(input);
+  });
+
+  test("offsite.destinations with only path defaults encrypt to true", () => {
+    const parsed = BackupConfigSchema.parse({
+      offsite: {
+        destinations: [{ path: "/tmp/a" }, { path: "/tmp/b" }],
+      },
+    });
+    expect(parsed.offsite.destinations).toEqual([
+      { path: "/tmp/a", encrypt: true },
+      { path: "/tmp/b", encrypt: true },
+    ]);
+  });
+
+  test("offsite.destinations honors explicit encrypt: false (plaintext allowed)", () => {
+    const parsed = BackupConfigSchema.parse({
+      offsite: {
+        destinations: [{ path: "/tmp/a", encrypt: false }],
+      },
+    });
+    expect(parsed.offsite.destinations).toEqual([
+      { path: "/tmp/a", encrypt: false },
+    ]);
+  });
+
+  test("offsite.destinations allows mixed encryption across destinations", () => {
+    const parsed = BackupConfigSchema.parse({
+      offsite: {
+        destinations: [
+          { path: "/tmp/a", encrypt: true },
+          { path: "/tmp/b", encrypt: false },
+        ],
+      },
+    });
+    expect(parsed.offsite.destinations).toEqual([
+      { path: "/tmp/a", encrypt: true },
+      { path: "/tmp/b", encrypt: false },
+    ]);
+  });
+
+  test("offsite.destinations: [] parses as an explicit empty array (distinct from null)", () => {
+    const parsed = BackupConfigSchema.parse({
+      offsite: { destinations: [] },
+    });
+    expect(parsed.offsite.destinations).toEqual([]);
+    // Distinct from null (the iCloud-default sentinel).
+    expect(parsed.offsite.destinations).not.toBe(null);
+  });
+
+  test("partial config with only enabled: true fills in defaults", () => {
+    const parsed = BackupConfigSchema.parse({ enabled: true });
+    expect(parsed).toEqual({
+      enabled: true,
+      intervalHours: 6,
+      retention: 7,
+      offsite: { enabled: true, destinations: null },
+      localDirectory: null,
+    });
+  });
+});
+
+describe("BackupDestinationSchema", () => {
+  test("defaults encrypt to true when omitted", () => {
+    const parsed = BackupDestinationSchema.parse({ path: "/tmp/x" });
+    expect(parsed).toEqual({ path: "/tmp/x", encrypt: true });
+  });
+
+  test("requires path", () => {
+    const result = BackupDestinationSchema.safeParse({});
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("BackupOffsiteConfigSchema", () => {
+  test("empty object defaults to enabled=true, destinations=null", () => {
+    expect(BackupOffsiteConfigSchema.parse({})).toEqual({
+      enabled: true,
+      destinations: null,
+    });
+  });
+});

package/src/config/assistant-feature-flags.ts

@@ -5,7 +5,7 @@
  * `meta/feature-flags/feature-flag-registry.json` and resolves the effective
  * enabled/disabled state for each declared assistant-scope flag by consulting
  * (in priority order):
- *   1. Override values from the gateway HTTP API (or local file fallback)
+ *   1. Override values from the gateway IPC socket (or local file fallback)
  *   2. Remote values from `feature-flags-remote.json` (platform-pushed,
  *      cached locally; only used in local mode — containerized mode gets
  *      remote values via the gateway)
@@ -17,9 +17,10 @@
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
+import { ipcGetFeatureFlags } from "../ipc/gateway-client.js";
+import { getProtectedDir } from "../util/platform.js";
 import type { AssistantConfig } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -110,7 +111,7 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
 }
 
 // ---------------------------------------------------------------------------
-// Override loading — reads from gateway HTTP API or local file
+// Override loading — reads from gateway IPC socket or local file
 // ---------------------------------------------------------------------------
 
 /**
@@ -119,6 +120,14 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
  */
 let cachedOverrides: Record<string, boolean> | null = null;
 
+/**
+ * True when `cachedOverrides` was populated by the gateway IPC fetch (or
+ * preseeded by a test). False/unset when the cache was populated by the sync
+ * file fallback in `loadOverrides()`, which must not prevent a subsequent
+ * authoritative gateway fetch from running.
+ */
+let cachedOverridesFromGateway = false;
+
 /**
  * File format for the local feature-flags.json override file, matching the
  * gateway's feature-flag-store.ts schema.
@@ -132,14 +141,15 @@ interface FeatureFlagFileData {
  * Resolve the path to the feature flag overrides file.
  *
  * Docker: `GATEWAY_SECURITY_DIR/feature-flags.json`
- * Local:  `~/.vellum/` + gateway security subdir + `feature-flags.json`
+ * Local:  `<protectedDir>/feature-flags.json` — resolved via `getProtectedDir()`
+ *         so it honors `BASE_DATA_DIR` for per-instance setups.
  */
 function getFeatureFlagOverridesPath(): string {
   const securityDir = process.env.GATEWAY_SECURITY_DIR;
   if (securityDir) {
     return join(securityDir, "feature-flags.json");
   }
-  return join(homedir(), ".vellum", "protected", "feature-flags.json");
+  return join(getProtectedDir(), "feature-flags.json");
 }
 
 /**
@@ -172,60 +182,16 @@ function loadOverridesFromFile(): Record<string, boolean> {
 }
 
 /**
- * Fetch override values from the gateway via async HTTP.
+ * Fetch override values from the gateway via IPC (Unix domain socket).
  *
  * Returns the gateway's merged feature flag map (persisted > remote >
- * registry), or an empty record on any failure (network, auth, parse).
+ * registry), or an empty record on any failure (socket not found,
+ * timeout, parse error). No auth needed — the IPC socket is
+ * access-controlled by file-system permissions on the shared volume.
  */
 async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
   try {
-    // Lazy-import to avoid circular dependency and keep this module
-    // importable from bootstrap code when not in containerized mode.
-    const { getGatewayInternalBaseUrl } =
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      require("./env.js") as typeof import("./env.js");
-    const {
-      mintEdgeRelayToken,
-      isSigningKeyInitialized,
-      initAuthSigningKey,
-      resolveSigningKey,
-    } =
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      require("../runtime/auth/token-service.js") as typeof import("../runtime/auth/token-service.js");
-
-    // CLI subprocesses don't run daemon startup, so the signing key
-    // may not be initialized yet. Initialize it now so mintEdgeRelayToken
-    // can produce a valid JWT for the gateway request.
-    if (!isSigningKeyInitialized()) {
-      initAuthSigningKey(resolveSigningKey());
-    }
-
-    const url = `${getGatewayInternalBaseUrl()}/v1/feature-flags`;
-    const token = mintEdgeRelayToken();
-
-    const response = await fetch(url, {
-      method: "GET",
-      headers: {
-        Authorization: `Bearer ${token}`,
-        Accept: "application/json",
-      },
-      signal: AbortSignal.timeout(10_000),
-    });
-
-    if (!response.ok) return {};
-
-    const parsed = (await response.json()) as {
-      flags?: Array<{ key: string; enabled: boolean }>;
-    };
-    if (!Array.isArray(parsed.flags)) return {};
-
-    const result: Record<string, boolean> = {};
-    for (const entry of parsed.flags) {
-      if (typeof entry.key === "string" && typeof entry.enabled === "boolean") {
-        result[entry.key] = entry.enabled;
-      }
-    }
-    return result;
+    return await ipcGetFeatureFlags();
   } catch {
     return {};
   }
@@ -242,17 +208,25 @@ async function fetchOverridesFromGateway(): Promise<Record<string, boolean>> {
  * On failure, the cache is left unset so subsequent sync calls fall
  * through to the file-based fallback rather than caching an empty map
  * that masks all overrides for the process lifetime.
+ *
+ * No-ops when the cache is already populated — callers that want to
+ * refresh must call `clearFeatureFlagOverridesCache()` first. This lets
+ * tests preseed flag state via `_setOverridesForTesting()` without the
+ * gateway IPC call clobbering their setup.
  */
 export async function initFeatureFlagOverrides(): Promise<void> {
+  if (cachedOverridesFromGateway) return;
+
   const gatewayOverrides = await fetchOverridesFromGateway();
   if (Object.keys(gatewayOverrides).length > 0) {
     cachedOverrides = gatewayOverrides;
+    cachedOverridesFromGateway = true;
     return;
   }
 
-  // Gateway returned empty or failed. Leave the cache unset so
-  // loadOverrides() falls through to file on the next sync read,
-  // regardless of containerized vs local mode.
+  // Gateway returned empty or failed. If the cache was populated from the
+  // file fallback, leave it in place for the next sync read. Otherwise leave
+  // unset so `loadOverrides()` falls through to file on first sync read.
 }
 
 /**
@@ -265,9 +239,6 @@ export async function initFeatureFlagOverrides(): Promise<void> {
 function loadOverrides(): Record<string, boolean> {
   if (cachedOverrides != null) return cachedOverrides;
 
-  // Cache not yet populated (initFeatureFlagOverrides wasn't called or
-  // hasn't finished). Fall back to the local file so the resolver still
-  // works, just without gateway data.
   cachedOverrides = loadOverridesFromFile();
   return cachedOverrides;
 }
@@ -333,6 +304,7 @@ function loadRemoteValues(): Record<string, boolean> {
  */
 export function clearFeatureFlagOverridesCache(): void {
   cachedOverrides = null;
+  cachedOverridesFromGateway = false;
   cachedRemoteValues = null;
 }
 
@@ -343,12 +315,19 @@ export function clearFeatureFlagOverridesCache(): void {
  * flag state without writing to disk. Production code should never call this;
  * use `clearFeatureFlagOverridesCache()` instead and let the resolver
  * re-read from the appropriate source.
+ *
+ * Forces `cachedRemoteValues` to an empty record (not `null`) so the resolver
+ * does not fall through to reading `feature-flags-remote.json` from disk. This
+ * matters because a developer's local remote-cache file can leak platform-set
+ * values into the test environment (e.g. `email-channel: true`), defeating
+ * test isolation.
  */
 export function _setOverridesForTesting(
   overrides: Record<string, boolean>,
 ): void {
   cachedOverrides = { ...overrides };
-  cachedRemoteValues = null;
+  cachedOverridesFromGateway = true;
+  cachedRemoteValues = {};
 }
 
 // ---------------------------------------------------------------------------
@@ -359,7 +338,7 @@ export function _setOverridesForTesting(
  * Resolve whether an assistant feature flag is enabled.
  *
  * Resolution order:
- *   1. Override from gateway HTTP API (or local file fallback)
+ *   1. Override from gateway IPC socket (or local file fallback)
  *   2. Remote value from `feature-flags-remote.json` (platform-pushed,
  *      cached locally)
  *   3. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
@@ -395,3 +374,23 @@ export function isAssistantFeatureFlagEnabled(
 export function getAssistantFeatureFlagDefaults(): FeatureFlagDefaultsRegistry {
   return loadDefaultsRegistry();
 }
+
+// ---------------------------------------------------------------------------
+// Named flag helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical key for the `home-feed` flag — gates the activity feed section on
+ * the macOS Home page (nudges, digests, actions, threads). Requires the
+ * `home-tab` flag to also be enabled. Declared in
+ * `meta/feature-flags/feature-flag-registry.json` with scope `macos`.
+ */
+export const HOME_FEED_FLAG = "home-feed";
+
+/**
+ * Resolve whether the `home-feed` flag is enabled for the current assistant
+ * config. Wraps `isAssistantFeatureFlagEnabled` with the canonical key.
+ */
+export function isHomeFeedEnabled(config: AssistantConfig): boolean {
+  return isAssistantFeatureFlagEnabled(HOME_FEED_FLAG, config);
+}

package/src/config/bundled-skills/app-builder/references/CUSTOM_ROUTES.md

@@ -6,7 +6,7 @@ When the app needs server-side persistence, custom API logic, or workspace file
 
 ## Handler file convention
 
-Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers use the standard Web API `Request`/`Response` signature.
+Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers receive two arguments: the standard Web API `Request` and an optional `context` object with runtime singletons.
 
 ```
 {workspaceDir}/routes/
@@ -76,6 +76,42 @@ const createRes = await window.vellum.fetch("/v1/x/items", {
 if (!createRes.ok) throw new Error(`HTTP ${createRes.status}`);
 ```
 
+## Runtime context
+
+Every handler receives a frozen `context` object as its second argument. This provides access to daemon singletons that are otherwise unreachable from dynamically imported route modules.
+
+```typescript
+export async function POST(request: Request, context): Promise<Response> {
+  // context.assistantEventHub — publish events to connected SSE clients
+  // context.assistantId       — the daemon's logical assistant ID ("self")
+}
+```
+
+### Publishing events to the client
+
+Use `context.assistantEventHub` to push real-time events to connected desktop/mobile clients. This is how route handlers can trigger client-side navigation, update UI, or deliver notifications.
+
+```typescript
+// routes/open-conversation.ts
+export async function POST(request: Request, context): Promise<Response> {
+  const { conversationId } = await request.json();
+
+  await context.assistantEventHub.publish({
+    id: crypto.randomUUID(),
+    assistantId: context.assistantId,
+    conversationId,
+    emittedAt: new Date().toISOString(),
+    message: { type: "open_conversation", conversationId },
+  });
+
+  return Response.json({ ok: true });
+}
+```
+
+The context object is **immutable** — attempting to reassign its properties will throw in strict mode (ESM). This prevents user route handlers from accidentally corrupting shared state.
+
+Legacy handlers that only accept `(request)` continue to work — the context is passed positionally but ignored if the handler doesn't declare the parameter.
+
 ## Key rules
 
 - Always create the route handler files via `file_write` before calling `app_refresh`

package/src/config/bundled-skills/contacts/SKILL.md

@@ -308,7 +308,7 @@ The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInst
 
 - `inviteCode` is the 6-digit code the invitee must send to redeem the invite. It is only returned at creation time.
 - `guardianInstruction` is a generated instruction telling the guardian how to share the invite.
-- `channelHandle` is the assistant's email address (e.g. `hello@domain.agentmail.to`).
+- `channelHandle` is the assistant's email address (e.g. `hello@vellum.me`).
 
 **Presenting to the guardian**: Give the guardian the invite code and the assistant's email address:
 
@@ -320,7 +320,7 @@ The response contains `{ ok: true, invite: { id, token, inviteCode, guardianInst
 >
 > This code can be used <maxUses> time(s)<and expires in X hours/days if applicable>.
 
-If the assistant's email address is not available (AgentMail not configured), tell the guardian they need to set up email integration first.
+If the assistant's email address is not available, tell the guardian they need to register one with `assistant email register <username>`.
 
 ### Create a WhatsApp invite
 

package/src/config/bundled-skills/conversations/tools/rename-conversation.ts

@@ -39,7 +39,12 @@ export async function run(
   // Persist with isAutoTitle = 0 so auto-generation won't overwrite it
   updateConversationTitle(conversationId, trimmedTitle, 0);
 
-  // Notify connected clients so the UI updates immediately
+  // Notify the client currently viewing this conversation so the header
+  // updates in-place. Scoped to this conversation so foreign
+  // `conversationId` values don't leak to other subscribers' speculative
+  // ID-resolution paths. Other clients learn about the rename via the
+  // unscoped `conversation_list_invalidated` published below, which
+  // triggers their sidebars to refetch and pick up the new title.
   const assistantId = context.assistantId ?? DAEMON_INTERNAL_ASSISTANT_ID;
   assistantEventHub
     .publish(
@@ -57,6 +62,23 @@ export async function run(
       log.warn({ err }, "Failed to publish conversation_title_updated event");
     });
 
+  // Broadcast `conversation_list_invalidated` unscoped so every connected
+  // client's sidebar refetches and picks up the renamed title. Mirrors
+  // the HTTP rename route in `conversation-management-routes.ts`.
+  assistantEventHub
+    .publish(
+      buildAssistantEvent(assistantId, {
+        type: "conversation_list_invalidated",
+        reason: "renamed",
+      }),
+    )
+    .catch((err) => {
+      log.warn(
+        { err },
+        "Failed to publish conversation_list_invalidated for rename",
+      );
+    });
+
   log.info({ conversationId, title: trimmedTitle }, "Conversation renamed");
 
   return {

package/src/config/bundled-skills/media-processing/SKILL.md

@@ -45,8 +45,7 @@ Parameters:
 - `section_config` - Path to a JSON file with manual section boundaries.
 - `detect_dead_time` - Whether to detect and skip dead time (default: false). Dead-time detection can be too aggressive for continuous action video like sports - it may incorrectly skip live play. Enable only for content with clear idle periods (e.g., lectures, surveillance footage).
 - `short_edge` - Short edge resolution for downscaled frames in pixels (default: 480).
-- `include_audio` - Whether to extract and transcribe audio for each segment (default: false). When enabled, each segment's audio is transcribed and stored alongside visual frames.
-- `transcription_mode` - Transcription backend: `'api'` (OpenAI Whisper cloud) or `'local'` (whisper.cpp on-device). Default: `'local'`. The `'api'` mode requires an OpenAI API key configured in settings.
+- `include_audio` - Whether to extract and transcribe audio for each segment (default: false). When enabled, each segment's audio is transcribed using the configured STT service and stored alongside visual frames.
 
 ### analyze_keyframes
 
@@ -121,7 +120,7 @@ Tracks estimated API costs during pipeline execution.
 
 ## Audio + Vision Multimodal Analysis
 
-When `include_audio` is enabled on `extract_keyframes`, the pipeline transcribes each segment's audio track and attaches the transcript to the segment data. During the Map phase (`analyze_keyframes`), Gemini receives both the visual frames and the audio transcript for each segment, enabling multimodal analysis that combines what is seen with what is said.
+When `include_audio` is enabled on `extract_keyframes`, the pipeline transcribes each segment's audio track using the configured STT service and attaches the transcript to the segment data. During the Map phase (`analyze_keyframes`), Gemini receives both the visual frames and the audio transcript for each segment, enabling multimodal analysis that combines what is seen with what is said.
 
 This is useful for:
 
@@ -130,12 +129,7 @@ This is useful for:
 - **Meetings and interviews**: Pair facial expressions and gestures with spoken dialogue.
 - **Tutorials and demos**: Link on-screen actions with verbal instructions.
 
-Transcription modes:
-
-- **`local`** (default): Uses whisper.cpp for on-device transcription. Requires `whisper-cpp` to be installed (`brew install whisper-cpp`). No API costs, but slower.
-- **`api`**: Uses the OpenAI Whisper API for cloud-based transcription. Faster and more accurate, but requires an OpenAI API key and incurs per-minute costs.
-
-The audio transcription degrades gracefully - if transcription fails for a segment (missing tools, no audio track, API errors), the segment proceeds with visual-only analysis.
+Audio transcription uses the STT service configured in assistant settings. If no STT service is configured or transcription fails for a segment (no audio track, service errors), the segment gracefully degrades to visual-only analysis.
 
 ## Best Practices
 

package/src/config/bundled-skills/media-processing/TOOLS.json

@@ -99,12 +99,7 @@
           },
           "include_audio": {
             "type": "boolean",
-            "description": "Whether to extract and transcribe audio for each segment. Default: false."
-          },
-          "transcription_mode": {
-            "type": "string",
-            "enum": ["api", "local"],
-            "description": "Transcription backend: 'api' (OpenAI Whisper cloud) or 'local' (whisper.cpp). Default: 'local'."
+            "description": "Whether to extract and transcribe audio for each segment using the configured STT service. Default: false."
           },
           "activity": {
             "type": "string",