@vellumai/assistant 0.8.7 → 0.8.8

package/src/avatar/__tests__/avatar-store.test.ts

@@ -41,6 +41,7 @@ const IMAGE_FILENAME = "avatar-image.png";
 const TRAITS_FILENAME = "character-traits.json";
 const ASCII_FILENAME = "character-ascii.txt";
 const MANIFEST_FILENAME = "avatar.json";
+const NATIVE_RENDER_TEST_TIMEOUT_MS = 15_000;
 
 interface ManifestShape {
   kind: string;
@@ -84,35 +85,39 @@ describe("avatar-store", () => {
   };
 
   describe("setCharacter", () => {
-    test("writes traits + PNG and a character manifest when render succeeds", () => {
-      const result = setCharacter(VALID_TRAITS);
-
-      // The native @resvg/resvg-js binding may be absent in this environment.
-      // When it is, the store returns `native_unavailable` and writes nothing —
-      // we assert that contract instead of the success path so the suite is
-      // deterministic either way.
-      if (!result.ok) {
-        expect(result.reason).toBe("native_unavailable");
-        expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
-        expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
-        expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
-        return;
-      }
-
-      expect(existsSync(path(TRAITS_FILENAME))).toBe(true);
-      expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
-      expect(JSON.parse(readFileSync(path(TRAITS_FILENAME), "utf-8"))).toEqual(
-        VALID_TRAITS,
-      );
-
-      const manifest = readManifestFile();
-      expect(manifest).not.toBeNull();
-      expect(manifest!.kind).toBe("character");
-      expect(manifest!.traits).toEqual(VALID_TRAITS);
-      expect(manifest!.source).toBe("builder");
-      expect(manifest!.image).not.toBeNull();
-      expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
-    });
+    test(
+      "writes traits + PNG and a character manifest when render succeeds",
+      () => {
+        const result = setCharacter(VALID_TRAITS);
+
+        // The native @resvg/resvg-js binding may be absent in this environment.
+        // When it is, the store returns `native_unavailable` and writes nothing —
+        // we assert that contract instead of the success path so the suite is
+        // deterministic either way.
+        if (!result.ok) {
+          expect(result.reason).toBe("native_unavailable");
+          expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
+          expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
+          expect(existsSync(path(MANIFEST_FILENAME))).toBe(false);
+          return;
+        }
+
+        expect(existsSync(path(TRAITS_FILENAME))).toBe(true);
+        expect(existsSync(path(IMAGE_FILENAME))).toBe(true);
+        expect(
+          JSON.parse(readFileSync(path(TRAITS_FILENAME), "utf-8")),
+        ).toEqual(VALID_TRAITS);
+
+        const manifest = readManifestFile();
+        expect(manifest).not.toBeNull();
+        expect(manifest!.kind).toBe("character");
+        expect(manifest!.traits).toEqual(VALID_TRAITS);
+        expect(manifest!.source).toBe("builder");
+        expect(manifest!.image).not.toBeNull();
+        expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+      },
+      NATIVE_RENDER_TEST_TIMEOUT_MS,
+    );
 
     test("propagates invalid_traits without writing a manifest", () => {
       const result = setCharacter({ bodyShape: "", eyeStyle: "", color: "" });

package/src/cli/commands/__tests__/notifications.test.ts

@@ -66,6 +66,12 @@ interface CommandResult {
   exitCode: number;
 }
 
+interface RawCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
 /**
  * Run a notifications subcommand and capture the JSON output.
  * Always passes --json to get compact, single-line JSON output and suppress log messages.
@@ -74,6 +80,17 @@ interface CommandResult {
  * reset to 0, capture, then reset back to 0 so bun test exits cleanly.
  */
 async function runCommand(args: string[]): Promise<CommandResult> {
+  const raw = await runRawCommand(["notifications", "--json", ...args]);
+
+  const firstLine = raw.stdout.trim().split("\n")[0];
+  const parsed = firstLine
+    ? (JSON.parse(firstLine) as Record<string, unknown>)
+    : {};
+
+  return { parsed, stderr: raw.stderr, exitCode: raw.exitCode };
+}
+
+async function runRawCommand(args: string[]): Promise<RawCommandResult> {
   const chunks: string[] = [];
   const stderrChunks: string[] = [];
   const originalWrite = process.stdout.write;
@@ -95,13 +112,7 @@ async function runCommand(args: string[]): Promise<CommandResult> {
     const program = new Command();
     program.exitOverride();
     registerNotificationsCommand(program);
-    await program.parseAsync([
-      "node",
-      "test",
-      "notifications",
-      "--json",
-      ...args,
-    ]);
+    await program.parseAsync(["node", "test", ...args]);
   } catch {
     // Commander throws on .exitOverride() for --help/errors; ignore
   } finally {
@@ -112,13 +123,11 @@ async function runCommand(args: string[]): Promise<CommandResult> {
   const exitCode = process.exitCode ?? 0;
   process.exitCode = 0;
 
-  const output = chunks.join("");
-  const firstLine = output.trim().split("\n")[0];
-  const parsed = firstLine
-    ? (JSON.parse(firstLine) as Record<string, unknown>)
-    : {};
-
-  return { parsed, stderr: stderrChunks.join(""), exitCode };
+  return {
+    stdout: chunks.join(""),
+    stderr: stderrChunks.join(""),
+    exitCode,
+  };
 }
 
 function lastSendBody(): Record<string, unknown> {
@@ -244,6 +253,41 @@ describe("notifications send", () => {
     expect(ipcCalls).toHaveLength(0);
   });
 
+  test("send rejects invalid source-channel", async () => {
+    const { parsed, exitCode } = await runCommand([
+      "send",
+      "--source-channel",
+      "water_reminder",
+      "--source-event-name",
+      "user.send_notification",
+      "--message",
+      "Hello",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(parsed).toEqual({
+      ok: false,
+      error:
+        'Invalid source-channel "water_reminder". Must be one of: assistant_tool, vellum, phone, telegram, slack, scheduler, watcher',
+    });
+    expect(ipcCalls).toHaveLength(0);
+  });
+
+  test("send help lists source-channel values", async () => {
+    const { stdout, exitCode } = await runRawCommand([
+      "notifications",
+      "send",
+      "--help",
+    ]);
+
+    expect(exitCode).toBe(0);
+    const normalizedHelp = stdout.replace(/\s+/g, " ");
+    expect(normalizedHelp).toContain(
+      "One of: assistant_tool, vellum, phone, telegram, slack, scheduler, watcher",
+    );
+    expect(normalizedHelp).toContain("(default: assistant_tool)");
+  });
+
   test("send --conversation-id pins the vellum affinity hint", async () => {
     const { parsed, exitCode } = await runCommand([
       "send",

package/src/cli/commands/notifications.ts

@@ -23,6 +23,39 @@ interface ListHomeFeedPayload {
   updatedAt: string;
 }
 
+const NOTIFICATION_SOURCE_CHANNEL_VALUES = [
+  "assistant_tool",
+  "vellum",
+  "phone",
+  "telegram",
+  "slack",
+  "scheduler",
+  "watcher",
+] as const;
+
+const URGENCY_VALUES = ["low", "medium", "high", "critical"] as const;
+
+const NOTIFICATION_STATUS_VALUES = [
+  "new",
+  "seen",
+  "acted_on",
+  "dismissed",
+] as const;
+
+const NOTIFICATION_CATEGORY_VALUES = [
+  "security",
+  "scheduling",
+  "background",
+  "email",
+  "system",
+] as const;
+
+const DEFAULT_SOURCE_CHANNEL = "assistant_tool";
+const SOURCE_CHANNEL_HELP = NOTIFICATION_SOURCE_CHANNEL_VALUES.join(", ");
+const URGENCY_HELP = URGENCY_VALUES.join(", ");
+const STATUS_HELP = NOTIFICATION_STATUS_VALUES.join(", ");
+const CATEGORY_HELP = NOTIFICATION_CATEGORY_VALUES.join(", ");
+
 function parseBoundedInt(
   raw: string | undefined,
   label: string,
@@ -71,6 +104,30 @@ function renderFeedItemsHuman(payload: ListHomeFeedPayload): void {
   }
 }
 
+function validateEnumValue(
+  value: string | undefined,
+  label: string,
+  allowed: readonly string[],
+): { error?: string } {
+  if (value === undefined || allowed.includes(value)) return {};
+  return {
+    error: `Invalid ${label} "${value}". Must be one of: ${allowed.join(", ")}`,
+  };
+}
+
+function validateEnumFlag(
+  values: string[] | undefined,
+  label: string,
+  allowed: readonly string[],
+): { error?: string } {
+  if (!values) return {};
+  for (const v of values) {
+    const result = validateEnumValue(v, label, allowed);
+    if (result.error) return result;
+  }
+  return {};
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -122,7 +179,7 @@ Examples:
         )
         .option(
           "--source-channel <channel>",
-          "Source channel producing this notification (default: assistant_tool)",
+          `Source channel producing this notification. One of: ${SOURCE_CHANNEL_HELP} (default: ${DEFAULT_SOURCE_CHANNEL})`,
         )
         .option(
           "--source-event-name <name>",
@@ -134,7 +191,7 @@ Examples:
         )
         .option(
           "--urgency <urgency>",
-          "Urgency hint: low, medium, high, critical (default: low; use --urgent for critical)",
+          `Urgency hint. One of: ${URGENCY_HELP} (default: low; use --urgent for critical)`,
         )
         .option(
           "--requires-action",
@@ -233,9 +290,24 @@ Examples:
             try {
               // Apply defaults for optional source fields (minimal-surface
               // ergonomics; explicit values from the CLI still win).
-              const sourceChannel = opts.sourceChannel ?? "assistant_tool";
+              const sourceChannel =
+                opts.sourceChannel ?? DEFAULT_SOURCE_CHANNEL;
               const sourceEventName = opts.sourceEventName ?? "assistant.share";
 
+              const sourceChannelError = validateEnumValue(
+                sourceChannel,
+                "source-channel",
+                NOTIFICATION_SOURCE_CHANNEL_VALUES,
+              );
+              if (sourceChannelError.error) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error: sourceChannelError.error,
+                });
+                process.exitCode = 1;
+                return;
+              }
+
               // Validate --message (keep basic validation for immediate CLI feedback)
               const message = opts.message.trim();
               if (message.length === 0) {
@@ -256,15 +328,15 @@ Examples:
 
               // Validate --urgency
               const urgency = opts.urgency ?? urgentDefaults.urgency;
-              if (
-                urgency !== "low" &&
-                urgency !== "medium" &&
-                urgency !== "high" &&
-                urgency !== "critical"
-              ) {
+              const urgencyError = validateEnumValue(
+                urgency,
+                "urgency",
+                URGENCY_VALUES,
+              );
+              if (urgencyError.error) {
                 writeOutput(cmd, {
                   ok: false,
-                  error: `Invalid urgency "${opts.urgency}". Must be one of: low, medium, high, critical`,
+                  error: urgencyError.error,
                 });
                 process.exitCode = 1;
                 return;
@@ -425,22 +497,6 @@ Examples:
         prev: string[] | undefined,
       ): string[] => [...(prev ?? []), value];
 
-      function validateEnumFlag(
-        values: string[] | undefined,
-        label: string,
-        allowed: readonly string[],
-      ): { error?: string } {
-        if (!values) return {};
-        for (const v of values) {
-          if (!allowed.includes(v)) {
-            return {
-              error: `Invalid ${label} "${v}". Must be one of: ${allowed.join(", ")}`,
-            };
-          }
-        }
-        return {};
-      }
-
       notifications
         .command("list")
         .description(
@@ -453,7 +509,7 @@ Examples:
         )
         .option(
           "--status <status>",
-          "Filter by status (new|seen|acted_on|dismissed); repeatable. Overrides --all default behavior.",
+          `Filter by status. One of: ${STATUS_HELP}; repeatable. Overrides --all default behavior.`,
           collectFlag,
         )
         .option(
@@ -466,12 +522,12 @@ Examples:
         )
         .option(
           "--urgency <urgency>",
-          "Filter by urgency (low|medium|high|critical); repeatable",
+          `Filter by urgency. One of: ${URGENCY_HELP}; repeatable`,
           collectFlag,
         )
         .option(
           "--category <category>",
-          "Filter by category (security|scheduling|background|email|system); repeatable",
+          `Filter by category. One of: ${CATEGORY_HELP}; repeatable`,
           collectFlag,
         )
         .option(
@@ -525,25 +581,17 @@ Examples:
           ) => {
             try {
               const enumChecks: Array<{ error?: string }> = [
-                validateEnumFlag(opts.status, "status", [
-                  "new",
-                  "seen",
-                  "acted_on",
-                  "dismissed",
-                ]),
-                validateEnumFlag(opts.urgency, "urgency", [
-                  "low",
-                  "medium",
-                  "high",
-                  "critical",
-                ]),
-                validateEnumFlag(opts.category, "category", [
-                  "security",
-                  "scheduling",
-                  "background",
-                  "email",
-                  "system",
-                ]),
+                validateEnumFlag(
+                  opts.status,
+                  "status",
+                  NOTIFICATION_STATUS_VALUES,
+                ),
+                validateEnumFlag(opts.urgency, "urgency", URGENCY_VALUES),
+                validateEnumFlag(
+                  opts.category,
+                  "category",
+                  NOTIFICATION_CATEGORY_VALUES,
+                ),
               ];
               const enumError = enumChecks.find((c) => c.error);
               if (enumError) {
@@ -641,11 +689,11 @@ Examples:
         .option("--title <title>", "New short headline (≤ 8 words).")
         .option(
           "--urgency <urgency>",
-          "Set urgency (low|medium|high|critical). Feed-only — does not re-push channel messages.",
+          `Set urgency. One of: ${URGENCY_HELP}. Feed-only — does not re-push channel messages.`,
         )
         .option(
           "--status <status>",
-          "Set lifecycle status (new|seen|acted_on|dismissed). Feed-only.",
+          `Set lifecycle status. One of: ${STATUS_HELP}. Feed-only.`,
         )
         .addHelpText(
           "after",
@@ -701,24 +749,28 @@ Examples:
                 return;
               }
 
-              if (
-                opts.urgency != null &&
-                !["low", "medium", "high", "critical"].includes(opts.urgency)
-              ) {
+              const urgencyError = validateEnumValue(
+                opts.urgency,
+                "urgency",
+                URGENCY_VALUES,
+              );
+              if (urgencyError.error) {
                 writeOutput(cmd, {
                   ok: false,
-                  error: `Invalid urgency "${opts.urgency}". Must be one of: low, medium, high, critical`,
+                  error: urgencyError.error,
                 });
                 process.exitCode = 1;
                 return;
               }
-              if (
-                opts.status != null &&
-                !["new", "seen", "acted_on", "dismissed"].includes(opts.status)
-              ) {
+              const statusError = validateEnumValue(
+                opts.status,
+                "status",
+                NOTIFICATION_STATUS_VALUES,
+              );
+              if (statusError.error) {
                 writeOutput(cmd, {
                   ok: false,
-                  error: `Invalid status "${opts.status}". Must be one of: new, seen, acted_on, dismissed`,
+                  error: statusError.error,
                 });
                 process.exitCode = 1;
                 return;

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

@@ -33,7 +33,7 @@ const log = getLogger("assistant-feature-flags");
 // ---------------------------------------------------------------------------
 
 export interface FeatureFlagDefault {
-  defaultEnabled: boolean;
+  defaultEnabled: boolean | string;
   description: string;
   label: string;
 }
@@ -103,7 +103,7 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
     const entry = flag as Record<string, unknown>;
     if (entry.scope !== "assistant" && entry.scope !== "both") continue;
     if (typeof entry.key !== "string") continue;
-    if (typeof entry.defaultEnabled !== "boolean") continue;
+    if (typeof entry.defaultEnabled !== "boolean" && typeof entry.defaultEnabled !== "string") continue;
 
     result[entry.key as string] = {
       defaultEnabled: entry.defaultEnabled,
@@ -133,7 +133,7 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
  */
 async function fetchOverridesFromGateway(
   timeoutMs?: number,
-): Promise<Record<string, boolean>> {
+): Promise<Record<string, boolean | string>> {
   try {
     return await ipcGetFeatureFlags(timeoutMs);
   } catch {
@@ -238,7 +238,7 @@ export async function initFeatureFlagOverrides(options?: {
  * Returns the gateway-populated cache if `initFeatureFlagOverrides()` was
  * called at startup, or an empty record otherwise.
  */
-function loadOverrides(): Record<string, boolean> {
+function loadOverrides(): Record<string, boolean | string> {
   return getCachedOverrides() ?? {};
 }
 
@@ -273,7 +273,7 @@ export async function refreshOverridesFromGateway(): Promise<void> {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve whether an assistant feature flag is enabled.
+ * Resolve the raw value for an assistant feature flag.
  *
  * Resolution order:
  *   1. Override from the gateway IPC fetch (includes platform-pushed remote
@@ -282,21 +282,32 @@ export async function refreshOverridesFromGateway(): Promise<void> {
  *   2. Registry `defaultEnabled` (for declared assistant-scope keys)
  *   3. `false` (for undeclared keys with no override)
  */
-export function isAssistantFeatureFlagEnabled(
+export function getAssistantFeatureFlagValue(
   key: string,
   _config: AssistantConfig,
-): boolean {
+): boolean | string {
   const defaults = loadDefaultsRegistry();
   const declared = defaults[key];
   const overrides = loadOverrides();
 
-  // 1. Check overrides from the gateway IPC cache.
   const explicit = overrides[key];
-  if (typeof explicit === "boolean") return explicit;
+  if (explicit !== undefined) return explicit;
 
-  // 2. For declared keys, use the registry default.
   if (declared) return declared.defaultEnabled;
 
-  // 3. Undeclared keys with no override fail closed.
   return false;
 }
+
+/**
+ * Resolve whether an assistant feature flag is enabled (boolean coercion).
+ *
+ * For boolean flags, returns the resolved value directly.
+ * For string flags, returns true if the value is non-empty.
+ * Undeclared keys return `false` (fail closed).
+ */
+export function isAssistantFeatureFlagEnabled(
+  key: string,
+  config: AssistantConfig,
+): boolean {
+  return !!getAssistantFeatureFlagValue(key, config);
+}

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -18,7 +18,7 @@ You are an expert app builder and visual designer. When the user asks you to cre
 
 **Your default behavior:** Build immediately. The user types "build me a habit tracker" and you deliver a complete, polished app with a domain-matched color palette, atmospheric background, and thoughtful interactions. Don't ask what colors they want. Don't show wireframes. Just build something stunning and let them refine from there.
 
-**Design quality is delegated to the `frontend-design` skill, so you must also load/install that before proceeding.** That skill defines your aesthetic principles: typography, color strategy, motion, spatial composition, and visual detail. Follow it completely for every build. This skill (app-builder) handles the technical infrastructure: sandbox constraints, data bridge, widget API, app lifecycle, and interaction patterns.
+**Design quality is delegated to the `frontend-design` skill, so you must also load/install that before proceeding.** That skill defines your aesthetic principles: typography, color strategy, motion, spatial composition, and visual detail. Follow it completely for every build. This skill (app-builder) handles the technical infrastructure: sandbox constraints, data persistence, widget API, app lifecycle, and interaction patterns.
 
 ## Filesystem Layout
 
@@ -411,31 +411,14 @@ A CSS/JS widget library is auto-injected alongside the design system. Use `.v-*`
 
 For the full widget reference (class names, JS APIs, chart functions, formatting utilities), see **[Widget Component Library](references/WIDGETS.md)**.
 
-#### Data bridge API (deprecated)
-
-> **Prefer custom route handlers** for new apps. The data bridge (`window.vellum.data`) only works for assistants that run on the same machine as the desktop app, which will also be deprecated soon.
-
-The native WebView can read and write app records via `window.vellum.data`. All methods return Promises.
-
-- `window.vellum.data.query()` - Returns all records: `{ id, appId, data, createdAt, updatedAt }[]`
-- `window.vellum.data.create(data)` - Creates a record. Returns the created record.
-- `window.vellum.data.update(recordId, data)` - Updates a record by ID. Returns updated record.
-- `window.vellum.data.delete(recordId)` - Deletes a record by ID. Returns void.
-
-Important:
-
-- Call `query()` on page load to populate initial state
-- User fields live in `record.data` (e.g., `record.data.title`)
-- Record IDs are UUID strings
-- All operations are async - use `async/await`
-- Wrap all calls in `try/catch`
-
 #### Custom route handlers (user-defined routes)
 
 When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript/JavaScript files in the workspace `routes/` directory, served under `/v1/x/`. Call them from the frontend via `window.vellum.fetch("/v1/x/...")`. **Never use raw `fetch()` for `/v1/x/` routes** — it will fail in the sandboxed origin.
 
 For handler conventions, examples, key rules, and frontend usage patterns, see **[Custom Route Handlers](references/CUSTOM_ROUTES.md)**.
 
+For complete, copyable apps wiring this persistence pattern end-to-end (multi-file TSX frontend + `routes/*.ts` handler), see the **[example apps](references/examples/README.md)**: a [Focus Timer](references/examples/focus-timer.md) (append-only log), a [Habit Tracker](references/examples/habit-tracker.md) (full CRUD), and an [Expense Tracker](references/examples/expense-tracker.md) (create/read/delete + aggregation).
+
 #### Client-side state management
 
 `localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use custom routes for persistent app records, `localStorage` for UI preferences.

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

@@ -0,0 +1,17 @@
+# Example Apps
+
+Complete, copyable reference apps that demonstrate the recommended patterns from this skill:
+multi-file TSX (`formatVersion: 2`), web-compatible persistence via **custom route handlers**
+(`window.vellum.fetch("/v1/x/…")`), and disciplined error handling. Use them as starting
+points — match the structure, not the styling (give every new app its own visual identity per
+the `frontend-design` skill).
+
+| Example                                 | Persistence pattern                              | Route methods                    |
+| --------------------------------------- | ------------------------------------------------ | -------------------------------- |
+| [Focus Timer](./focus-timer.md)         | Append-only log + aggregate stats read on mount  | `GET`, `POST`                    |
+| [Habit Tracker](./habit-tracker.md)     | Full CRUD addressed by `id` query param          | `GET`, `POST`, `PATCH`, `DELETE` |
+| [Expense Tracker](./expense-tracker.md) | Create / read / delete + client-side aggregation | `GET`, `POST`, `DELETE`          |
+
+All three persist through a `routes/*.ts` handler — never through `window.vellum.data`, which
+is a desktop-only bridge that silently no-ops on web. See
+[CUSTOM_ROUTES.md](../CUSTOM_ROUTES.md) for the full route handler reference.