@vellumai/assistant 0.8.5 → 0.8.6

package/src/cli/commands/notifications.ts

@@ -1,5 +1,6 @@
 import type { Command } from "commander";
 
+import type { FeedItem } from "../../home/feed-types.js";
 import {
   cliIpcCall,
   exitCodeFromIpcResult,
@@ -10,6 +11,66 @@ import { log } from "../logger.js";
 import { shouldOutputJson, writeOutput } from "../output.js";
 import { tryResolveConversationId } from "../utils/conversation-id.js";
 
+// ---------------------------------------------------------------------------
+// Local types & helpers
+// ---------------------------------------------------------------------------
+
+interface ListHomeFeedPayload {
+  items: FeedItem[];
+  total: number;
+  returned: number;
+  hasMore: boolean;
+  updatedAt: string;
+}
+
+function parseBoundedInt(
+  raw: string | undefined,
+  label: string,
+  bounds: { min: number; max?: number },
+): { value?: number; error?: string } {
+  if (raw === undefined) return {};
+  const n = Number(raw);
+  const upper = bounds.max ?? Infinity;
+  if (
+    !Number.isFinite(n) ||
+    !Number.isInteger(n) ||
+    n < bounds.min ||
+    n > upper
+  ) {
+    const range =
+      bounds.max !== undefined
+        ? `[${bounds.min}, ${bounds.max}]`
+        : `>= ${bounds.min}`;
+    return {
+      error: `Invalid ${label} "${raw}". Must be an integer ${range}`,
+    };
+  }
+  return { value: n };
+}
+
+function renderFeedItemsHuman(payload: ListHomeFeedPayload): void {
+  if (payload.items.length === 0) {
+    log.info("No notifications match the filters.");
+    return;
+  }
+  log.info(`${payload.returned} of ${payload.total} notifications:\n`);
+  for (const item of payload.items) {
+    const idShort = item.id.slice(0, 8);
+    const status = item.status.toUpperCase().padEnd(10);
+    const urgency = (item.urgency ?? "").padEnd(8);
+    const headline = item.title ?? item.summary;
+    const convoTag = item.conversationId
+      ? `  (conv: ${item.conversationId.slice(0, 8)})`
+      : "";
+    log.info(
+      `  ${idShort}  ${item.createdAt}  ${status} ${urgency} ${headline}${convoTag}`,
+    );
+  }
+  if (payload.hasMore) {
+    log.info("\n(more results available; bump --offset to paginate)");
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -52,7 +113,7 @@ Examples:
         )
         .requiredOption(
           "--message <message>",
-          "Notification message the user should receive",
+          "Notification body. Markdown (GFM) renders in the detail panel; the OS banner shows plain text.",
         )
         .option(
           "--urgent",
@@ -67,7 +128,10 @@ Examples:
           "--source-event-name <name>",
           "Event name for audit, routing, and dedupe grouping (default: assistant.share)",
         )
-        .option("--title <title>", "Optional notification title")
+        .option(
+          "--title <title>",
+          "Short headline (≤ 8 words). Always provide one — the auto-derived fallback just truncates --message.",
+        )
         .option(
           "--urgency <urgency>",
           "Urgency hint: low, medium, high, critical (default: low; use --urgent for critical)",
@@ -353,84 +417,189 @@ Examples:
       // list
       // -------------------------------------------------------------------------
 
+      // Commander's `.exitOverride()` (used in tests) swallows thrown errors
+      // from collector functions, so we append values here and validate the
+      // accumulated array inside the action handler instead.
+      const collectFlag = (
+        value: string,
+        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(
-          "List recent notification events from the local event store",
+          "List notifications surfaced to the user via the home feed. Excludes dismissed items by default.",
+        )
+        .option(
+          "--all",
+          "Include dismissed items (default: only new/seen/acted_on)",
+          false,
+        )
+        .option(
+          "--status <status>",
+          "Filter by status (new|seen|acted_on|dismissed); repeatable. Overrides --all default behavior.",
+          collectFlag,
         )
+        .option(
+          "--before <iso>",
+          "Only items with createdAt strictly before this ISO-8601 timestamp",
+        )
+        .option(
+          "--after <iso>",
+          "Only items with createdAt strictly after this ISO-8601 timestamp",
+        )
+        .option(
+          "--urgency <urgency>",
+          "Filter by urgency (low|medium|high|critical); repeatable",
+          collectFlag,
+        )
+        .option(
+          "--category <category>",
+          "Filter by category (security|scheduling|background|email|system); repeatable",
+          collectFlag,
+        )
+        .option(
+          "--conversation-id <id>",
+          "Only items tied to this conversation id",
+        )
+        .option(
+          "--from-assistant",
+          "Only items emitted by the assistant",
+          false,
+        )
+        .option("--noteworthy", "Only items flagged as noteworthy", false)
         .option(
           "--limit <n>",
-          "Maximum number of events to return (default: 20)",
+          "Maximum number of items to return (default: 20, max: 200)",
         )
-        .option("--source-event-name <name>", "Filter by source event name")
+        .option("--offset <n>", "Pagination offset (default: 0)")
         .addHelpText(
           "after",
           `
-Reads from the local notification events store, ordered by creation time
-(newest first). Each event represents a signal that was emitted through the
-notification pipeline.
+Reads the home feed at ~/.vellum/workspace/data/home-feed.json — the
+user's notification inbox. Items are ordered by priority then recency,
+matching what the user sees in the macOS Home page. The home feed covers
+background/async notifications mirrored from the unified pipeline;
+real-time chat pushes that did not mirror to the feed will not appear.
 
 Examples:
   $ assistant notifications list
-  $ assistant notifications list --limit 5
-  $ assistant notifications list --source-event-name schedule.notify
-  $ assistant notifications list --source-event-name schedule.notify --limit 10 --json`,
+  $ assistant notifications list --all
+  $ assistant notifications list --status new --status seen
+  $ assistant notifications list --after 2026-05-28T00:00:00Z --urgency high
+  $ assistant notifications list --conversation-id 7fab234c --json
+  $ assistant notifications list --limit 5 --offset 5`,
         )
         .action(
           async (
             opts: {
+              all?: boolean;
+              status?: string[];
+              before?: string;
+              after?: string;
+              urgency?: string[];
+              category?: string[];
+              conversationId?: string;
+              fromAssistant?: boolean;
+              noteworthy?: boolean;
               limit?: string;
-              sourceEventName?: string;
+              offset?: string;
             },
             cmd: Command,
           ) => {
             try {
-              // Validate --source-event-name (accept any non-empty string; custom
-              // event names are valid since skills can emit arbitrary names)
-              if (
-                opts.sourceEventName != null &&
-                opts.sourceEventName.trim().length === 0
-              ) {
-                writeOutput(cmd, {
-                  ok: false,
-                  error: "Source event name must be a non-empty string",
-                });
+              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",
+                ]),
+              ];
+              const enumError = enumChecks.find((c) => c.error);
+              if (enumError) {
+                writeOutput(cmd, { ok: false, error: enumError.error });
                 process.exitCode = 1;
                 return;
               }
 
-              // Parse and validate --limit
-              let limit = 20;
-              if (opts.limit != null) {
-                const parsed = Number(opts.limit);
-                if (
-                  !Number.isFinite(parsed) ||
-                  !Number.isInteger(parsed) ||
-                  parsed < 1
-                ) {
+              const limit = parseBoundedInt(opts.limit, "limit", {
+                min: 1,
+                max: 200,
+              });
+              if (limit.error) {
+                writeOutput(cmd, { ok: false, error: limit.error });
+                process.exitCode = 1;
+                return;
+              }
+              const offset = parseBoundedInt(opts.offset, "offset", {
+                min: 0,
+              });
+              if (offset.error) {
+                writeOutput(cmd, { ok: false, error: offset.error });
+                process.exitCode = 1;
+                return;
+              }
+
+              if (opts.conversationId != null) {
+                const trimmed = opts.conversationId.trim();
+                if (trimmed.length === 0) {
                   writeOutput(cmd, {
                     ok: false,
-                    error: `Invalid limit "${opts.limit}". Must be a positive integer`,
+                    error: "Conversation ID must be a non-empty string",
                   });
                   process.exitCode = 1;
                   return;
                 }
-                limit = parsed;
               }
 
-              const result = await cliIpcCall<
-                Array<{
-                  id: string;
-                  sourceEventName: string;
-                  sourceChannel: string;
-                  sourceContextId: string;
-                  urgency: string;
-                  dedupeKey: string | null;
-                  createdAt: string;
-                }>
-              >("list_notification_events", {
-                body: { limit, sourceEventName: opts.sourceEventName },
-              });
+              const body: Record<string, unknown> = {};
+              if (opts.all) body.includeDismissed = true;
+              if (opts.status?.length) body.statuses = opts.status;
+              if (opts.before) body.before = opts.before;
+              if (opts.after) body.after = opts.after;
+              if (opts.urgency?.length) body.urgencies = opts.urgency;
+              if (opts.category?.length) body.categories = opts.category;
+              if (opts.conversationId)
+                body.conversationId = opts.conversationId.trim();
+              if (opts.fromAssistant) body.fromAssistant = true;
+              if (opts.noteworthy) body.noteworthy = true;
+              if (limit.value !== undefined) body.limit = limit.value;
+              if (offset.value !== undefined) body.offset = offset.value;
+
+              const result = await cliIpcCall<ListHomeFeedPayload>(
+                "list_home_feed",
+                { body },
+              );
 
               if (!result.ok) {
                 writeOutput(cmd, { ok: false, error: result.error });
@@ -438,19 +607,160 @@ Examples:
                 return;
               }
 
-              const events = result.result!;
+              const payload = result.result!;
+              writeOutput(cmd, { ok: true, ...payload });
+
+              if (!shouldOutputJson(cmd)) {
+                renderFeedItemsHuman(payload);
+              }
+            } catch (err) {
+              const message = err instanceof Error ? err.message : String(err);
+              writeOutput(cmd, { ok: false, error: message });
+              process.exitCode = 1;
+            }
+          },
+        );
+
+      // -------------------------------------------------------------------------
+      // edit
+      // -------------------------------------------------------------------------
+
+      notifications
+        .command("edit")
+        .description(
+          "Edit an already-sent notification. Patches the home-feed entry and updates the delivered channel message in place where supported (Slack today).",
+        )
+        .requiredOption(
+          "--id <id>",
+          "Feed item id (notif:<uuid>) from `notifications list --json`. Bare uuids without the `notif:` prefix are also accepted.",
+        )
+        .option(
+          "--message <message>",
+          "New notification body. Updates the home-feed summary and the delivered channel message text where supported.",
+        )
+        .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.",
+        )
+        .option(
+          "--status <status>",
+          "Set lifecycle status (new|seen|acted_on|dismissed). Feed-only.",
+        )
+        .addHelpText(
+          "after",
+          `
+At least one of --message, --title, --urgency, or --status must be
+supplied. --urgency and --status only update the home-feed entry —
+they never re-push channel messages.
+
+Channel updates are best-effort: Slack messages get updated via
+chat.update; other channels (push, email, SMS) cannot be edited and
+are reported as "unsupported".
+
+Examples:
+  $ assistant notifications edit --id notif:abc12345-... --message "Fixed body"
+  $ assistant notifications edit --id abc12345-... --title "Backup complete"
+  $ assistant notifications edit --id notif:abc12345-... --urgency low
+  $ assistant notifications edit --id notif:abc12345-... --status dismissed`,
+        )
+        .action(
+          async (
+            opts: {
+              id: string;
+              message?: string;
+              title?: string;
+              urgency?: string;
+              status?: string;
+            },
+            cmd: Command,
+          ) => {
+            try {
+              const id = opts.id.trim();
+              if (!id) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error: "--id must be a non-empty string",
+                });
+                process.exitCode = 1;
+                return;
+              }
+
+              if (
+                opts.message === undefined &&
+                opts.title === undefined &&
+                opts.urgency === undefined &&
+                opts.status === undefined
+              ) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error:
+                    "At least one of --message, --title, --urgency, or --status must be supplied",
+                });
+                process.exitCode = 1;
+                return;
+              }
+
+              if (
+                opts.urgency != null &&
+                !["low", "medium", "high", "critical"].includes(opts.urgency)
+              ) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error: `Invalid urgency "${opts.urgency}". Must be one of: low, medium, high, critical`,
+                });
+                process.exitCode = 1;
+                return;
+              }
+              if (
+                opts.status != null &&
+                !["new", "seen", "acted_on", "dismissed"].includes(opts.status)
+              ) {
+                writeOutput(cmd, {
+                  ok: false,
+                  error: `Invalid status "${opts.status}". Must be one of: new, seen, acted_on, dismissed`,
+                });
+                process.exitCode = 1;
+                return;
+              }
+
+              const body: Record<string, unknown> = { id };
+              if (opts.message !== undefined) body.body = opts.message;
+              if (opts.title !== undefined) body.title = opts.title;
+              if (opts.urgency !== undefined) body.urgency = opts.urgency;
+              if (opts.status !== undefined) body.status = opts.status;
+
+              const result = await cliIpcCall<{
+                feedItem: FeedItem;
+                channels: Array<{
+                  channel: string;
+                  deliveryId: string;
+                  outcome: "updated" | "unsupported" | "skipped" | "failed";
+                  reason?: string;
+                }>;
+              }>("edit_notification", { body });
+
+              if (!result.ok) {
+                writeOutput(cmd, { ok: false, error: result.error });
+                process.exitCode = exitCodeFromIpcResult(result);
+                return;
+              }
 
-              writeOutput(cmd, { ok: true, events });
+              const payload = result.result!;
+              writeOutput(cmd, { ok: true, ...payload });
 
               if (!shouldOutputJson(cmd)) {
-                if (events.length === 0) {
-                  log.info("No notification events found");
+                const item = payload.feedItem;
+                log.info(`Updated ${item.id}`);
+                const headline = item.title ?? item.summary;
+                log.info(`  ${headline}`);
+                if (payload.channels.length === 0) {
+                  log.info("  No channel deliveries to update.");
                 } else {
-                  log.info(`${events.length} event(s):\n`);
-                  for (const event of events) {
-                    log.info(
-                      `  ${event.createdAt}  ${event.sourceEventName}  ${event.urgency}  ${event.sourceChannel}`,
-                    );
+                  log.info("  Channels:");
+                  for (const ch of payload.channels) {
+                    const reason = ch.reason ? ` — ${ch.reason}` : "";
+                    log.info(`    ${ch.channel}: ${ch.outcome}${reason}`);
                   }
                 }
               }

package/src/cli/lib/open-browser.ts

@@ -2,8 +2,13 @@
  * CLI-side helper that opens a URL on the user's host machine.
  *
  * Writes an `open_url` event to the `signals/emit-event` file so that the
- * daemon's ConfigWatcher picks it up and publishes it to connected clients
- * (e.g. the Swift macOS app) via the assistant event hub.
+ * assistant's ConfigWatcher picks it up and publishes it to connected
+ * clients (e.g. the Swift macOS app) via the assistant event hub.
+ *
+ * CLI-initiated emit — no conversation context available, so the inner
+ * message has no `conversationId`. That's fine: `OpenUrlEventSchema`
+ * declares `conversationId` as optional, so this payload parses
+ * cleanly on the web side as well as in the Swift macOS app.
  *
  * Uses only `node:` imports so it's safe for `ipc`-tagged CLI commands.
  */

package/src/cli/program.ts

@@ -18,6 +18,7 @@ import { registerBrowserCommand } from "./commands/browser.js";
 import { registerCacheCommand } from "./commands/cache.js";
 import { registerChangelogCommand } from "./commands/changelog.js";
 import { registerChannelVerificationSessionsCommand } from "./commands/channel-verification-sessions.js";
+import { registerChannelsCommand } from "./commands/channels/index.js";
 import { registerClientsCommand } from "./commands/clients.js";
 import { registerCompletionsCommand } from "./commands/completions.js";
 import { registerConfigCommand } from "./commands/config.js";
@@ -113,6 +114,7 @@ Examples:
   registerCacheCommand(program);
   registerChangelogCommand(program);
   registerChannelVerificationSessionsCommand(program);
+  registerChannelsCommand(program);
   registerClientsCommand(program);
   registerCompletionsCommand(program);
   registerConfigCommand(program);

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

@@ -18,6 +18,12 @@ import { dirname, join } from "node:path";
 
 import { ipcGetFeatureFlags } from "../ipc/gateway-client.js";
 import { getLogger } from "../util/logger.js";
+import {
+  clearCachedOverrides,
+  getCachedOverrides,
+  isCachedFromGateway,
+  setCachedOverrides,
+} from "./feature-flag-cache.js";
 import type { AssistantConfig } from "./schema.js";
 
 const log = getLogger("assistant-feature-flags");
@@ -112,22 +118,10 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
 // ---------------------------------------------------------------------------
 // Override loading — reads from gateway IPC socket
 // ---------------------------------------------------------------------------
-
-/**
- * Module-level cache of feature flag override values. Populated by
- * `initFeatureFlagOverrides()` at startup, invalidated by
- * `clearFeatureFlagOverridesCache()`.
- */
-let cachedOverrides: Record<string, boolean> | null = null;
-
-/**
- * True when `cachedOverrides` was populated by the gateway IPC fetch or
- * preseeded by a test via `_setOverridesForTesting()`. Guards
- * `initFeatureFlagOverrides()` from clobbering an existing populated cache
- * when called a second time (e.g. by a CLI entry point after the daemon
- * has already initialized).
- */
-let cachedOverridesFromGateway = false;
+//
+// The override cache lives in `feature-flag-cache.ts` (stdlib-only) so test
+// helpers can seed it without dragging the pino logger + gateway IPC client
+// transitively through their import chain. See that file's block comment.
 
 /**
  * Fetch override values from the gateway via IPC (Unix domain socket).
@@ -181,8 +175,9 @@ const DEFAULT_INIT_RETRY_BACKOFFS_MS: readonly number[] = [
  *
  * 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.
+ * tests preseed flag state via `setOverridesForTesting()` (in
+ * `__tests__/feature-flag-test-helpers.ts`) without the gateway IPC call
+ * clobbering their setup.
  */
 export async function initFeatureFlagOverrides(options?: {
   retryBackoffsMs?: readonly number[];
@@ -194,7 +189,7 @@ export async function initFeatureFlagOverrides(options?: {
    */
   callTimeoutMs?: number;
 }): Promise<void> {
-  if (cachedOverridesFromGateway) return;
+  if (isCachedFromGateway()) return;
 
   const backoffs = options?.retryBackoffsMs ?? DEFAULT_INIT_RETRY_BACKOFFS_MS;
   const callTimeoutMs = options?.callTimeoutMs;
@@ -208,15 +203,14 @@ export async function initFeatureFlagOverrides(options?: {
       const delay = backoffs[attempt - 1]!;
       await new Promise((resolve) => setTimeout(resolve, delay));
       // Re-check after the wait: a concurrent caller (e.g. a test using
-      // `_setOverridesForTesting`) may have populated the cache while we
+      // `setOverridesForTesting`) may have populated the cache while we
       // were sleeping. Bail out so we don't clobber their setup.
-      if (cachedOverridesFromGateway) return;
+      if (isCachedFromGateway()) return;
     }
 
     const gatewayOverrides = await fetchOverridesFromGateway(callTimeoutMs);
     if (Object.keys(gatewayOverrides).length > 0) {
-      cachedOverrides = gatewayOverrides;
-      cachedOverridesFromGateway = true;
+      setCachedOverrides(gatewayOverrides, { fromGateway: true });
       if (attempt > 0) {
         log.info(
           { attempt: attempt + 1 },
@@ -245,18 +239,20 @@ export async function initFeatureFlagOverrides(options?: {
  * called at startup, or an empty record otherwise.
  */
 function loadOverrides(): Record<string, boolean> {
-  return cachedOverrides ?? {};
+  return getCachedOverrides() ?? {};
 }
 
 /**
  * Invalidate the cached overrides so the next call to
  * `isAssistantFeatureFlagEnabled` re-reads from the gateway.
  *
- * Used by tests between cases to reset module state.
+ * Called by `refreshOverridesFromGateway()` when the gateway pushes a
+ * `feature_flags_changed` event, and by tests between cases to reset
+ * module state. (Tests typically call `setOverridesForTesting()` from
+ * `__tests__/feature-flag-test-helpers.ts`, which combines clear + seed.)
  */
 export function clearFeatureFlagOverridesCache(): void {
-  cachedOverrides = null;
-  cachedOverridesFromGateway = false;
+  clearCachedOverrides();
 }
 
 /**
@@ -272,21 +268,6 @@ export async function refreshOverridesFromGateway(): Promise<void> {
   await initFeatureFlagOverrides({ retryBackoffsMs: [] });
 }
 
-/**
- * Directly inject override values into the module-level cache.
- *
- * **Test-only** — bypasses the gateway IPC fetch so unit tests can control
- * flag state without standing up a real gateway. Production code should
- * never call this; use `clearFeatureFlagOverridesCache()` instead and let
- * the resolver re-read from the gateway.
- */
-export function _setOverridesForTesting(
-  overrides: Record<string, boolean>,
-): void {
-  cachedOverrides = { ...overrides };
-  cachedOverridesFromGateway = true;
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/src/config/bundled-skills/document-editor/SKILL.md

@@ -39,10 +39,14 @@ When the user asks to see, open, or pull up a document:
 
 ## Creating a new document
 
-1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble.
+1. **Create the document**: Call `document_create` with a title (inferred from the request). Call the tool immediately, not after conversational preamble. Capture the `surface_id` from the response — every subsequent `document_update` call must reference it.
 2. **Write content in Markdown**: Use proper structure (`#` for titles, `##` for sections), **bold**, _italic_, code blocks, tables, lists, blockquotes as appropriate.
 3. **CRITICAL - Stream content in chunks**: Call `document_update` MULTIPLE times, not just once. Break content into logical chunks (paragraphs, sections, or every 200-300 words). Call `document_update` with `mode: "append"` for EACH chunk separately. The user experiences real-time content appearing as you write.
 
+### Recovering from a failed update
+
+If a `document_update` call fails with an `Invalid input` error (for example because `surface_id` was missing), do NOT call `document_create` again. The `surface_id` you need is in the tool result of the most recent `document_create` call in this turn. Retry `document_update` with that `surface_id` and the same content. Creating a second document with the same title produces a duplicate for the user.
+
 ## Editing an existing document
 
 When the user requests changes to a document: