@vellumai/assistant 0.12.3-staging.1 → 0.12.3-staging.2

package/src/cli/__tests__/roadmap-cli.test.ts

@@ -219,15 +219,15 @@ describe("roadmap writes", () => {
     });
   });
 
-  test("update sends only the fields that were passed", async () => {
+  test("update forwards only the title and description it was given", async () => {
     nextResult = ITEM;
 
     await runAssistantCommandFull(
       "roadmap",
       "update",
       "dark-mode",
-      "--status",
-      "planned",
+      "--description",
+      "Follow the OS setting",
     );
 
     expect(calls[0]).toEqual({
@@ -236,49 +236,12 @@ describe("roadmap writes", () => {
         pathParams: { slug: "dark-mode" },
         body: {
           title: undefined,
-          description: undefined,
-          status: "planned",
-          tags: undefined,
+          description: "Follow the OS setting",
         },
       },
     });
   });
 
-  test("--clear-tags sends the empty set that --tag cannot express", async () => {
-    nextResult = ITEM;
-
-    await runAssistantCommandFull(
-      "roadmap",
-      "update",
-      "dark-mode",
-      "--clear-tags",
-    );
-
-    expect((calls[0].params as { body: { tags: string[] } }).body.tags).toEqual(
-      [],
-    );
-  });
-
-  test("--clear-tags with --tag is refused rather than silently picking one", async () => {
-    nextResult = ITEM;
-    process.exitCode = 0;
-
-    // The complaint itself goes straight to stderr, which this harness does
-    // not capture; what matters is that no update was forwarded.
-    await runAssistantCommandFull(
-      "roadmap",
-      "update",
-      "dark-mode",
-      "--clear-tags",
-      "--tag",
-      "ui",
-    );
-
-    expect(calls).toHaveLength(0);
-    expect(process.exitCode).toBe(1);
-    process.exitCode = 0;
-  });
-
   test("delete names the item it removed", async () => {
     nextResult = { slug: "dark-mode", deleted: true };
 

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

@@ -175,7 +175,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -186,7 +186,7 @@ describe("notifications send", () => {
 
     const body = lastSendBody();
     expect(body.sourceChannel).toBe("assistant_tool");
-    expect(body.sourceEventName).toBe("user.send_notification");
+    expect(body.sourceEventName).toBe("schedule.notify");
     const payload = body.contextPayload as Record<string, unknown>;
     expect(payload.requestedMessage).toBe("Hello");
   });
@@ -221,7 +221,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
       "--preferred-channels",
@@ -235,7 +235,7 @@ describe("notifications send", () => {
     expect(payload.preferredChannels).toEqual(["telegram", "slack"]);
   });
 
-  test("send rejects invalid urgency", async () => {
+  test("send passes exclusive channel allowlist", async () => {
     const { parsed, exitCode } = await runCommand([
       "send",
       "--source-channel",
@@ -243,6 +243,31 @@ describe("notifications send", () => {
       "--source-event-name",
       "user.send_notification",
       "--message",
+      "Alarm",
+      "--channels",
+      "telegram",
+      "--urgent",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(parsed.ok).toBe(true);
+    expect(parsed.selectedChannels).toEqual([]);
+    expect(parsed.deliveryResults).toEqual([]);
+    expect(parsed.receiptClass).toBe("unknown");
+
+    const payload = lastSendBody().contextPayload as Record<string, unknown>;
+    expect(payload.channelAllowlist).toEqual(["telegram"]);
+    expect(payload.preferredChannels).toBeUndefined();
+  });
+
+  test("send rejects invalid urgency", async () => {
+    const { parsed, exitCode } = await runCommand([
+      "send",
+      "--source-channel",
+      "assistant_tool",
+      "--source-event-name",
+      "schedule.notify",
+      "--message",
       "Hello",
       "--urgency",
       "invalid",
@@ -265,7 +290,7 @@ describe("notifications send", () => {
       "--source-channel",
       "water_reminder",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -300,7 +325,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -320,7 +345,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
     ]);
@@ -335,7 +360,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hi",
       "--conversation-id",
@@ -359,7 +384,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);
@@ -384,7 +409,7 @@ describe("notifications send", () => {
       "--source-channel",
       "assistant_tool",
       "--source-event-name",
-      "user.send_notification",
+      "schedule.notify",
       "--message",
       "Hello",
     ]);

package/src/cli/commands/browser.help.ts

@@ -138,11 +138,10 @@ Existing sessions and explicit backend/client choices take priority.
 not the user's Chrome. --desktop remains an alias for --virtual-desktop.
 Use --virtual-desktop for Chrome in the Desktop panel.
 Run navigate --url <url> directly to open a page.
-The assistant-desktop feature flag and completed installation are required.
-The first browser command installs missing components, starts Chrome, and completes
-the requested action in one call. Allow up to 600 seconds for this command when
-using bash (timeout_seconds: 600). Opening the Desktop panel also starts
-the same installation and shows progress. No separate setup command is needed.
+The assistant-desktop feature flag and a desktop-enabled assistant image are required.
+Chrome and desktop components are included in the image. The first browser command
+starts Chrome and completes the requested action without downloading or installing
+anything. Missing components require an assistant image update.
 Report other availability errors without switching to a personal computer.
 The assistant manages Chrome startup. Do not launch a separate desktop stack,
 install desktop packages, or drive webpages with shell-level xdotool.

package/src/cli/commands/browser.ts

@@ -168,7 +168,6 @@ function attachOperationAction(
       }
     }
 
-    // First use can include virtual desktop installation and Chrome startup.
     const ipcResult = await cliIpcCall<BrowserExecuteResult>(
       "browser_execute",
       {

package/src/cli/commands/clients.help.ts

@@ -58,6 +58,7 @@ Examples:
   $ assistant clients list                             List all connected clients
   $ assistant clients list --json                      Machine-readable JSON output
   $ assistant clients list --capability host_bash      Show only clients that can run host commands
+  $ assistant clients history                          Recent connection sessions and flaps
   $ assistant clients disconnect <clientId>            Force-disconnect a client`,
   subcommands: [
     {
@@ -87,6 +88,51 @@ Examples:
   $ assistant clients list
   $ assistant clients list --capability host_bash
   $ assistant clients list --json | jq '.clients[0].capabilities'`,
+    },
+    {
+      name: "history",
+      description: "Show persisted client connection sessions",
+      options: [
+        {
+          flags: "--json",
+          description: "Machine-readable compact JSON output",
+        },
+        {
+          flags: "--client-id <id>",
+          description: "Restrict history to one client UUID",
+        },
+        {
+          flags: "--interface-id <id>",
+          description:
+            "Restrict history to one interface (e.g. chrome-extension)",
+        },
+        {
+          flags: "--since <when>",
+          description:
+            "ISO-8601 or epoch-ms lower bound. Sessions already open at this time are included.",
+        },
+        {
+          flags: "--limit <n>",
+          description: "Max coalesced sessions to return (1-500, default 50)",
+        },
+      ],
+      helpText: `
+Options:
+  --json                 Output as compact JSON instead of a table.
+  --client-id <id>       Only show history for this client UUID.
+  --interface-id <id>    Only show history for this interface.
+  --since <when>         Lower bound as ISO-8601 or epoch milliseconds.
+                         Sessions already open at this time are included.
+  --limit <n>            Max sessions after flap coalescing. Default 50.
+
+Reconnects shorter than 60 seconds are flaps on the same session, not
+separate outages. History starts when this assistant version first
+records connections. It does not backfill earlier uptime.
+
+Examples:
+  $ assistant clients history
+  $ assistant clients history --interface-id chrome-extension
+  $ assistant clients history --client-id client-123 --since 2026-09-01 --json`,
     },
     {
       name: "disconnect",

package/src/cli/commands/clients.ts

@@ -26,6 +26,23 @@ interface DisconnectClientResponse {
   disconnected: number;
 }
 
+interface ClientHistorySessionJSON {
+  clientId: string;
+  interfaceId: string;
+  startedAt: string;
+  endedAt: string | null;
+  durationMs: number | null;
+  flapCount: number;
+  closeReason: string | null;
+  clientVersion: string | null;
+  sseWatchdog: boolean | null;
+}
+
+interface ListClientHistoryResponse {
+  sessions: ClientHistorySessionJSON[];
+  events: unknown[];
+}
+
 export function registerClientsCommand(program: Command): void {
   registerCommand(program, {
     name: clientsHelp.name,
@@ -108,6 +125,85 @@ export function registerClientsCommand(program: Command): void {
         },
       );
 
+      subcommand(clients, "history").action(
+        async (
+          opts: {
+            json?: boolean;
+            clientId?: string;
+            interfaceId?: string;
+            since?: string;
+            limit?: string;
+          },
+          cmd: Command,
+        ) => {
+          const result = await cliIpcCall<ListClientHistoryResponse>(
+            "list_client_history",
+            optsToQueryParams(opts),
+          );
+
+          if (!result.ok) {
+            log.error(result.error ?? "Failed to load client history");
+            process.exitCode = 1;
+            return;
+          }
+
+          const response = result.result!;
+          if (opts.json) {
+            writeOutput(cmd, response);
+            return;
+          }
+
+          const sessions = response.sessions;
+          if (sessions.length === 0) {
+            log.info("No client connection history.");
+            return;
+          }
+
+          const header = [
+            "CLIENT ID",
+            "INTERFACE",
+            "STARTED",
+            "ENDED",
+            "DURATION",
+            "FLAPS",
+            "CLOSE",
+            "VERSION",
+            "WATCHDOG",
+          ];
+          const rows: string[][] = sessions.map((session) => [
+            session.clientId,
+            session.interfaceId,
+            formatRelativeTime(session.startedAt),
+            session.endedAt ? formatRelativeTime(session.endedAt) : "connected",
+            formatDuration(session.durationMs),
+            String(session.flapCount),
+            session.closeReason ?? "-",
+            session.clientVersion ?? "-",
+            session.sseWatchdog == null
+              ? "-"
+              : session.sseWatchdog
+                ? "yes"
+                : "no",
+          ]);
+
+          const colWidths = header.map((h: string, i: number) =>
+            Math.max(h.length, ...rows.map((r: string[]) => r[i].length)),
+          );
+          const pad = (s: string, w: number) => s.padEnd(w);
+          log.info(
+            header.map((h: string, i: number) => pad(h, colWidths[i])).join("  "),
+          );
+          log.info(colWidths.map((w: number) => "─".repeat(w)).join("  "));
+          for (const row of rows) {
+            log.info(
+              row
+                .map((c: string, i: number) => pad(c, colWidths[i]))
+                .join("  "),
+            );
+          }
+        },
+      );
+
       subcommand(clients, "disconnect").action(
         async (clientId: string, opts: { json?: boolean }, cmd: Command) => {
           const result = await cliIpcCall<DisconnectClientResponse>(
@@ -155,3 +251,23 @@ function formatRelativeTime(iso: string): string {
   const days = Math.floor(hr / 24);
   return `${days}d ago`;
 }
+
+function formatDuration(ms: number | null): string {
+  if (ms == null || ms < 0) {
+    return "-";
+  }
+  const sec = Math.floor(ms / 1000);
+  if (sec < 60) {
+    return `${sec}s`;
+  }
+  const min = Math.floor(sec / 60);
+  if (min < 60) {
+    return `${min}m`;
+  }
+  const hr = Math.floor(min / 60);
+  if (hr < 24) {
+    return `${hr}h ${min % 60}m`;
+  }
+  const days = Math.floor(hr / 24);
+  return `${days}d ${hr % 24}h`;
+}

package/src/cli/commands/credentials.help.ts

@@ -294,7 +294,12 @@ web, etc.). The user enters the secret through the UI — it never passes throug
 the conversation or CLI output. On success the credential is stored in the
 encrypted vault with the specified metadata.
 
-Requires the assistant to be running with at least one connected client.
+Requires the assistant to be running. The prompt renders in the conversation
+this command runs from (the bash tool sets __CONVERSATION_ID). With no
+conversation attached (a headless shell, Doctor's run_assistant_cli), no client
+can show the card, so the command returns at once with a one-time collection
+link (exit 75) to relay to the user, or an error when no link can be minted.
+Never fall back to asking the user for the value in chat.
 
 This command BLOCKS until the user answers the prompt, so it returns only once
 the prompt has already closed. Tell the user what to paste BEFORE running it.

package/src/cli/commands/notifications.help.ts

@@ -127,7 +127,12 @@ Examples:
         {
           flags: "--preferred-channels <channels>",
           description:
-            "Comma-separated channel hints (e.g. vellum,telegram,slack)",
+            "Comma-separated channel hints (e.g. vellum,telegram,slack). Additive: vellum stays selected.",
+        },
+        {
+          flags: "--channels <channels>",
+          description:
+            "Exclusive channel allowlist (e.g. telegram). Replaces the default set. Urgent delivery does not add vellum or platform. Wins over --preferred-channels.",
         },
         {
           flags: "--session-id <id>",
@@ -162,7 +167,15 @@ Behavioral notes:
     is treated as critical and requires user action. Explicit --urgency /
     --requires-action flags still win for back-compat.
   - Without --urgent, --urgency defaults to low and --requires-action to false.
-  - --preferred-channels are hints only; the decision engine may override them.
+  - --preferred-channels are additive hints; vellum stays in the selected set.
+  - --channels is an exclusive allowlist. Only those connected channels are
+    selected. Urgent delivery does not force vellum or platform, and Home
+    does not mirror unless vellum is in the list. When both flags are set,
+    --channels wins.
+  - --json includes selectedChannels, deliveryResults, and receiptClass.
+    receiptClass is the strongest delivery proof (provider_accepted,
+    gateway_accepted, client_os_posted, or unknown), not a promise the
+    user saw a banner.
   - --dedupe-key suppresses duplicate signals with the same key.
   - --conversation-id pins delivery to an existing vellum conversation
     deterministically. Other channels (telegram, slack) continue to use
@@ -171,6 +184,7 @@ Behavioral notes:
 Examples:
   $ assistant notifications send --message "Task complete"
   $ assistant notifications send --message "Pager: prod is down" --urgent
+  $ assistant notifications send --message "Alarm" --channels telegram --urgent
   $ assistant notifications send --message "Build green" --conversation-id 649c4645-3a6f-4ded-a713-504f02ca806b`,
     },
     {

package/src/cli/commands/notifications.ts

@@ -32,6 +32,16 @@ interface ListHomeFeedPayload {
   updatedAt: string;
 }
 
+function parseCommaSeparatedList(raw: string): string[] | undefined {
+  const items = raw
+    .split(",")
+    .map((item) => item.trim())
+    .filter((item) => {
+      return item.length > 0;
+    });
+  return items.length > 0 ? items : undefined;
+}
+
 function parseBoundedInt(
   raw: string | undefined,
   label: string,
@@ -142,6 +152,7 @@ export function registerNotificationsCommand(program: Command): void {
             visibleInSourceNow: boolean;
             deadlineAt?: string;
             preferredChannels?: string;
+            channels?: string;
             sessionId?: string;
             dedupeKey?: string;
             deepLinkMetadata?: string;
@@ -220,14 +231,12 @@ export function registerNotificationsCommand(program: Command): void {
               deadlineAt = parsed;
             }
 
-            // Parse --preferred-channels
-            let preferredChannels: string[] | undefined;
-            if (opts.preferredChannels) {
-              preferredChannels = opts.preferredChannels
-                .split(",")
-                .map((ch) => ch.trim())
-                .filter((ch) => ch.length > 0);
-            }
+            const preferredChannels = opts.preferredChannels
+              ? parseCommaSeparatedList(opts.preferredChannels)
+              : undefined;
+            const channelAllowlist = opts.channels
+              ? parseCommaSeparatedList(opts.channels)
+              : undefined;
 
             // Parse --deep-link-metadata
             let deepLinkMetadata: Record<string, unknown> | undefined;
@@ -283,6 +292,9 @@ export function registerNotificationsCommand(program: Command): void {
               dispatched: boolean;
               deduplicated: boolean;
               reason: string;
+              selectedChannels?: string[];
+              deliveryResults?: unknown[];
+              receiptClass?: string;
             }>("emit_notification_signal", {
               body: {
                 sourceChannel,
@@ -300,6 +312,7 @@ export function registerNotificationsCommand(program: Command): void {
                   requestedBySource: sourceChannel,
                   ...(opts.title ? { requestedTitle: opts.title } : {}),
                   ...(preferredChannels?.length ? { preferredChannels } : {}),
+                  ...(channelAllowlist?.length ? { channelAllowlist } : {}),
                   ...(deepLinkMetadata ? { deepLinkMetadata } : {}),
                 },
                 ...(opts.dedupeKey ? { dedupeKey: opts.dedupeKey } : {}),
@@ -326,6 +339,9 @@ export function registerNotificationsCommand(program: Command): void {
               signalId: signal.signalId,
               dispatched: signal.dispatched,
               reason: signal.reason,
+              selectedChannels: signal.selectedChannels ?? [],
+              deliveryResults: signal.deliveryResults ?? [],
+              receiptClass: signal.receiptClass ?? "unknown",
             });
 
             if (!shouldOutputJson(cmd)) {
@@ -335,6 +351,12 @@ export function registerNotificationsCommand(program: Command): void {
               if (signal.reason) {
                 log.info(`  Reason: ${signal.reason}`);
               }
+              if (signal.selectedChannels && signal.selectedChannels.length > 0) {
+                log.info(`  Channels: ${signal.selectedChannels.join(", ")}`);
+              }
+              if (signal.receiptClass) {
+                log.info(`  Receipt: ${signal.receiptClass}`);
+              }
             }
           } catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/src/cli/commands/roadmap.help.ts

@@ -25,7 +25,7 @@ no verb to post one.
 Examples:
   $ assistant roadmap list --sort upvotes --limit 10
   $ assistant roadmap get scheduled-messages
-  $ assistant roadmap create --title "Add dark mode" --tag ui
+  $ assistant roadmap create --title "Add dark mode" --tag area-interface
   $ assistant roadmap upvote scheduled-messages`,
   subcommands: [
     {
@@ -79,10 +79,13 @@ Examples:
       options: [
         {
           flags: "--title <title>",
-          description: "Item title (required)",
+          description: "Item title, 1 to 200 characters (required)",
           required: true,
         },
-        { flags: "--description <desc>", description: "Item description" },
+        {
+          flags: "--description <desc>",
+          description: "Item description, up to 5000 characters",
+        },
         {
           flags: "--tag <slug>",
           description:
@@ -97,41 +100,35 @@ accepted, since status is assigned by Vellum.
 Examples:
   $ assistant roadmap create --title "Add dark mode"
   $ assistant roadmap create --title "Recurring reminders" \\
-      --description "Repeat a scheduled message weekly" --tag scheduling`,
+      --description "Repeat a scheduled message weekly" --tag area-assistant`,
     },
     {
       name: "update",
       args: "<slug>",
-      description: "Update a roadmap item",
+      description:
+        "Edit the title or description of an item the assistant filed",
       options: [
-        { flags: "--title <title>", description: "New title" },
-        { flags: "--description <desc>", description: "New description" },
         {
-          flags: "--status <status>",
-          description: "New status (e.g. open, planned, in_progress, someday)",
-        },
-        {
-          flags: "--tag <slug>",
-          description: "Replacement tag slug, repeatable",
+          flags: "--title <title>",
+          description: "New title, 1 to 200 characters",
         },
         {
-          flags: "--clear-tags",
-          description: "Remove every tag (cannot be combined with --tag)",
+          flags: "--description <desc>",
+          description: "New description, up to 5000 characters",
         },
       ],
       helpText: `
 Arguments:
   <slug>  Item slug, as printed in the URL by 'assistant roadmap list'
 
-At least one field is required. Passing --tag replaces the whole tag set
-rather than adding to it, so list every tag the item should end up with.
-Vellum decides which items an assistant may edit, so this fails for items the
-assistant does not own.
+At least one of --title or --description is required. Only items this
+assistant filed can be edited, and only while their status is still open.
+Status and tags are set by Vellum staff, so an item's tags are chosen once,
+on 'roadmap create'.
 
 Examples:
   $ assistant roadmap update dark-mode --description "Follow the OS setting"
-  $ assistant roadmap update dark-mode --tag ui --tag theming
-  $ assistant roadmap update dark-mode --clear-tags`,
+  $ assistant roadmap update dark-mode --title "Dark mode that follows the OS"`,
     },
     {
       name: "delete",