@vellumai/assistant 0.8.4 → 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";
@@ -34,6 +35,7 @@ import { registerInferenceCommand } from "./commands/inference.js";
 import { registerKeysCommand } from "./commands/keys.js";
 import { registerMcpCommand } from "./commands/mcp.js";
 import { registerMemoryV2Command } from "./commands/memory-v2.js";
+import { registerMemoryV3Command } from "./commands/memory-v3.js";
 import { registerNotificationsCommand } from "./commands/notifications.js";
 import { registerOAuthCommand } from "./commands/oauth/index.js";
 import { registerPendingCommand } from "./commands/pending.js";
@@ -112,6 +114,7 @@ Examples:
   registerCacheCommand(program);
   registerChangelogCommand(program);
   registerChannelVerificationSessionsCommand(program);
+  registerChannelsCommand(program);
   registerClientsCommand(program);
   registerCompletionsCommand(program);
   registerConfigCommand(program);
@@ -129,6 +132,7 @@ Examples:
   registerKeysCommand(program);
   registerMcpCommand(program);
   registerMemoryV2Command(program);
+  registerMemoryV3Command(program);
   registerNotificationsCommand(program);
   registerOAuthCommand(program);
   registerPendingCommand(program);