@vellumai/assistant 0.12.2 → 0.12.3-staging.2

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/oauth/index.help.ts

@@ -258,6 +258,11 @@ Examples:
               description:
                 "Dot-notation path to a boolean field that must be truthy for the response to be valid",
             },
+            {
+              flags: "--response-ok-field <field>",
+              description:
+                "Dot-notation path to the boolean every response body carries to report success (Slack: ok); an explicit false under a 2xx fails the request",
+            },
             {
               flags: "--setup-notes <json>",
               description:
@@ -430,6 +435,11 @@ Examples:
               flags: "--identity-ok-field <field>",
               description: "Dot-notation path to a boolean ok field",
             },
+            {
+              flags: "--response-ok-field <field>",
+              description:
+                "Dot-notation path to the boolean every response body carries to report success",
+            },
             {
               flags: "--setup-notes <json>",
               description: "JSON array of setup instruction notes",

package/src/cli/commands/oauth/providers.ts

@@ -49,6 +49,7 @@ interface SerializedProvider {
   identityResponsePaths?: string[] | null;
   identityFormat?: string | null;
   identityOkField?: string | null;
+  responseOkField?: string | null;
   availableScopes?: unknown;
   setupNotes?: string[] | unknown;
   featureFlag?: string | null;
@@ -217,6 +218,9 @@ function formatProviderDetail(p: SerializedProvider): string {
   if (p.identityOkField) {
     lines.push(`  Identity ok field: ${p.identityOkField}`);
   }
+  if (p.responseOkField) {
+    lines.push(`  Response ok field: ${p.responseOkField}`);
+  }
   if (p.setupNotes) {
     if (Array.isArray(p.setupNotes)) {
       lines.push(
@@ -403,6 +407,7 @@ export function registerProviderCommands(oauth: Command): void {
         identityResponsePaths?: string;
         identityFormat?: string;
         identityOkField?: string;
+        responseOkField?: string;
         setupNotes?: string;
         availableScopes?: string;
       },
@@ -505,6 +510,9 @@ export function registerProviderCommands(oauth: Command): void {
         if (opts.identityOkField !== undefined) {
           body.identity_ok_field = opts.identityOkField;
         }
+        if (opts.responseOkField !== undefined) {
+          body.response_ok_field = opts.responseOkField;
+        }
         if (opts.setupNotes !== undefined) {
           body.setup_notes = JSON.parse(opts.setupNotes);
         }
@@ -578,6 +586,7 @@ export function registerProviderCommands(oauth: Command): void {
         identityResponsePaths?: string;
         identityFormat?: string;
         identityOkField?: string;
+        responseOkField?: string;
         setupNotes?: string;
         availableScopes?: string;
       },
@@ -686,6 +695,9 @@ export function registerProviderCommands(oauth: Command): void {
         if (opts.identityOkField !== undefined) {
           body.identity_ok_field = opts.identityOkField;
         }
+        if (opts.responseOkField !== undefined) {
+          body.response_ok_field = opts.responseOkField;
+        }
         if (opts.setupNotes !== undefined) {
           body.setup_notes = JSON.parse(opts.setupNotes);
         }

package/src/cli/commands/oauth/request.test.ts

@@ -17,6 +17,7 @@ let handleRequestResult: {
   body: unknown;
   bodyEncoding?: "base64";
   account?: string | null;
+  hint?: string;
 } = {
   ok: true,
   status: 200,
@@ -71,18 +72,71 @@ afterEach(() => {
   process.exitCode = 0;
 });
 
-async function runRequestCommand(args: string[]): Promise<{
+/**
+ * Runs the command with both streams captured and `process.exit` recorded.
+ * The stream stubs honour a write callback the way the real streams do, so an
+ * exit that rides the last write lands in `exitCalls`, and only after every
+ * chunk written before it has been captured. `holdStderr` keeps stderr
+ * callbacks back and returns them, for the case where stderr is still in
+ * flight when stdout has drained.
+ */
+async function runRequestCommand(
+  args: string[],
+  options: { holdStderr?: boolean } = {},
+): Promise<{
   stdout: Buffer;
+  stderr: string;
   exitCode: number;
+  exitCalls: number[];
+  heldStderrCallbacks: Array<() => void>;
 }> {
   const chunks: Buffer[] = [];
+  const stderrChunks: string[] = [];
+  const exitCalls: number[] = [];
+  const heldStderrCallbacks: Array<() => void> = [];
   const originalWrite = process.stdout.write;
-  process.stdout.write = ((chunk: string | Uint8Array) => {
+  const originalStderrWrite = process.stderr.write;
+  const originalExit = process.exit;
+  const callbackOf = (rest: unknown[]): (() => void) | undefined =>
+    rest.find((arg) => typeof arg === "function") as (() => void) | undefined;
+  process.stdout.write = ((chunk: string | Uint8Array, ...rest: unknown[]) => {
     chunks.push(
       typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk),
     );
+    callbackOf(rest)?.();
     return true;
   }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: string | Uint8Array, ...rest: unknown[]) => {
+    stderrChunks.push(String(chunk));
+    const callback = callbackOf(rest);
+    if (callback) {
+      if (options.holdStderr) {
+        heldStderrCallbacks.push(holdCallback(callback));
+      } else {
+        callback();
+      }
+    }
+    return true;
+  }) as typeof process.stderr.write;
+  const recordExit = ((code?: number) => {
+    exitCalls.push(code ?? Number(process.exitCode ?? 0));
+  }) as typeof process.exit;
+  process.exit = recordExit;
+  // A held callback runs after this function has restored the real
+  // `process.exit`, so it reinstalls the recorder for the duration of the
+  // call; the exit it triggers must land in `exitCalls`, never end the test
+  // process.
+  const holdCallback = (callback: () => void): (() => void) => {
+    return () => {
+      const current = process.exit;
+      process.exit = recordExit;
+      try {
+        callback();
+      } finally {
+        process.exit = current;
+      }
+    };
+  };
 
   try {
     const program = new Command();
@@ -101,11 +155,16 @@ async function runRequestCommand(args: string[]): Promise<{
     // Commander may throw under exitOverride for parse errors.
   } finally {
     process.stdout.write = originalWrite;
+    process.stderr.write = originalStderrWrite;
+    process.exit = originalExit;
   }
 
   return {
     stdout: Buffer.concat(chunks),
+    stderr: stderrChunks.join(""),
     exitCode: Number(process.exitCode ?? 0),
+    exitCalls,
+    heldStderrCallbacks,
   };
 }
 
@@ -308,6 +367,124 @@ describe("oauth request body output", () => {
     expect(parsed.bodyEncoding).toBe("base64");
   });
 
+  test("exits non-zero when the route reports failure inside a 2xx", async () => {
+    // The exit code follows the route's verdict, so a caller that only checks
+    // the exit code sees a refused call as a failure; the body still prints,
+    // since it carries the provider's own error code.
+    handleRequestResult = {
+      ok: false,
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: false, error: "not_in_channel" },
+      account: "user@example.com",
+    };
+    const { stdout, exitCode } = await runRequestCommand([
+      "--provider",
+      "slack_channel",
+      "-s",
+      "/chat.postMessage",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(stdout.toString("utf8")).toContain("not_in_channel");
+  });
+
+  test("exits itself once the whole body has drained", async () => {
+    // The in-process route leaves handles open, so the command has to exit;
+    // and it must do so on the write callback, because a bare exit after a
+    // large piped write drops everything past the first 64 KB.
+    const body = "x".repeat(200_000);
+    handleRequestResult = {
+      ok: true,
+      status: 200,
+      headers: { "content-type": "text/plain" },
+      body,
+      account: "user@example.com",
+    };
+    const { stdout, exitCode, exitCalls } = await runRequestCommand([
+      "--provider",
+      "google",
+      "-s",
+      "https://api.google.com/v1/big",
+    ]);
+
+    expect(stdout.toString("utf8")).toBe(body + "\n");
+    expect(exitCode).toBe(0);
+    expect(exitCalls).toEqual([0]);
+  });
+
+  test("exits after writing an empty body to a file", async () => {
+    const target = join(tempDir, "empty.bin");
+    handleRequestResult = {
+      ok: true,
+      status: 204,
+      headers: {},
+      body: null,
+      account: "user@example.com",
+    };
+    const { exitCalls } = await runRequestCommand([
+      "--provider",
+      "google",
+      "-s",
+      "-o",
+      target,
+      "https://api.google.com/v1/none",
+    ]);
+
+    expect(readFileSync(target)).toHaveLength(0);
+    expect(exitCalls).toEqual([0]);
+  });
+
+  test("waits for stderr to drain before exiting when stdout carried nothing", async () => {
+    // With `-o`, stdout carries nothing, so the exit cannot ride a stdout
+    // write, and the diagnostics on stderr (the account line, a hint) may
+    // still be in flight. The exit waits for the last of them.
+    const target = join(tempDir, "body.json");
+    handleRequestResult = {
+      ok: false,
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { ok: false, error: "not_in_channel" },
+      account: "user@example.com",
+      hint: "slack_channel answered HTTP 200 but reported ok: false",
+    };
+    const { stderr, exitCalls, heldStderrCallbacks } = await runRequestCommand(
+      ["--provider", "slack_channel", "-o", target, "/chat.postMessage"],
+      { holdStderr: true },
+    );
+
+    expect(stderr).toContain("Account: user@example.com");
+    expect(stderr).toContain("ok: false");
+    expect(heldStderrCallbacks).toHaveLength(2);
+    expect(exitCalls).toEqual([]);
+
+    heldStderrCallbacks[0]();
+    expect(exitCalls).toEqual([]);
+    heldStderrCallbacks[1]();
+    expect(exitCalls).toEqual([1]);
+  });
+
+  test("a stdout body waits for stderr diagnostics written before it", async () => {
+    handleRequestResult = {
+      ok: true,
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { hello: "world" },
+      account: "user@example.com",
+    };
+    const { stdout, exitCalls, heldStderrCallbacks } = await runRequestCommand(
+      ["--provider", "google", "https://api.google.com/v1/me"],
+      { holdStderr: true },
+    );
+
+    expect(stdout.toString("utf8")).toContain("hello");
+    expect(heldStderrCallbacks).toHaveLength(1);
+    expect(exitCalls).toEqual([]);
+
+    heldStderrCallbacks[0]();
+    expect(exitCalls).toEqual([0]);
+  });
+
   test("writes text bodies as UTF-8 and appends a newline on stdout", async () => {
     handleRequestResult = {
       ok: true,

package/src/cli/commands/oauth/request.ts

@@ -142,11 +142,38 @@ export async function runAuthenticatedRequest(params: {
   const { providerKey, url, opts, cmd } = params;
   const jsonMode = shouldOutputJson(cmd);
 
+  // The command exits itself, once its last write on either stream has
+  // drained. Running the route in-process leaves handles open that the event
+  // loop waits on (the lazy CES connection the credential resolves through is
+  // never closed by the CLI), so returning from the action would leave the
+  // process alive after a complete response. A bare `process.exit()` is not
+  // the answer either: with a pipe on the other end, Bun flushes what the
+  // pipe accepts and drops the rest, so the exit rides write callbacks, which
+  // fire when the bytes are out. Stdout's last write carries `exit` itself;
+  // stderr's writes are counted, so an exit requested while one is still in
+  // flight waits for it. The pipe's capacity is not a bound to lean on: a
+  // busy host can shrink an unprivileged pipe to a single page.
+  let stderrInFlight = 0;
+  let exitRequested = false;
+  const exit = (): void => {
+    exitRequested = true;
+    if (stderrInFlight === 0) {
+      process.exit(Number(process.exitCode ?? 0));
+    }
+  };
+
   // Helper: write info to stderr (respects -s)
   const writeInfo = (msg: string): void => {
-    if (!opts.silent) {
-      process.stderr.write(msg + "\n");
+    if (opts.silent) {
+      return;
     }
+    stderrInFlight += 1;
+    process.stderr.write(msg + "\n", () => {
+      stderrInFlight -= 1;
+      if (exitRequested) {
+        exit();
+      }
+    });
   };
 
   try {
@@ -232,17 +259,18 @@ export async function runAuthenticatedRequest(params: {
         // reported the way every other failure here is, so `--json` gets its
         // envelope and the caller's diagnostics hint is not lost; only the
         // exit code comes from the route's status.
-        writeError(cmd, `${err.message}\n\n${params.diagnosticsHint}`);
         process.exitCode = exitCodeFromIpcResult({
           statusCode: err.statusCode,
         });
+        writeError(cmd, `${err.message}\n\n${params.diagnosticsHint}`, exit);
         return;
       }
       throw err;
     }
 
-    // Non-2xx exit code
-    if (result.status < 200 || result.status >= 300) {
+    // The route's verdict, not the status code: a provider that reports
+    // failure inside a 2xx (Slack's `ok: false`) is a failed request.
+    if (!result.ok) {
       process.exitCode = 1;
     }
 
@@ -261,7 +289,7 @@ export async function runAuthenticatedRequest(params: {
 
     // JSON output mode
     if (jsonMode) {
-      writeOutput(cmd, result);
+      writeOutput(cmd, result, exit);
       return;
     }
 
@@ -282,20 +310,23 @@ export async function runAuthenticatedRequest(params: {
       if (output) {
         if (opts.output) {
           writeFileSync(opts.output, output.bytes);
+        } else if (output.isBinary) {
+          process.stdout.write(output.bytes, exit);
+          return;
         } else {
           process.stdout.write(output.bytes);
-          if (!output.isBinary) {
-            process.stdout.write("\n");
-          }
+          process.stdout.write("\n", exit);
+          return;
         }
       }
     } else if (opts.output) {
       writeFileSync(opts.output, Buffer.alloc(0));
     }
+    exit();
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    writeError(cmd, `${message}\n\n${params.diagnosticsHint}`);
     process.exitCode = 1;
+    writeError(cmd, `${message}\n\n${params.diagnosticsHint}`, exit);
   }
 }
 

package/src/cli/commands/plugins.ts

@@ -238,11 +238,18 @@ export function registerPluginsCommand(program: Command): void {
               const platformEnabled =
                 libs.catalogLocal.arePlatformFeaturesEnabled();
               if (platformEnabled) {
-                const match = (
-                  await libs.catalogCache.getPluginCatalog(DEFAULT_PLUGIN_REF, {
-                    fetch: globalThis.fetch.bind(globalThis),
-                  })
-                ).matches.find((candidate) => candidate.name === nameOrUrl);
+                let match;
+                try {
+                  match = (
+                    await libs.catalogCache.getPluginCatalog(
+                      DEFAULT_PLUGIN_REF,
+                      { fetch: globalThis.fetch.bind(globalThis) },
+                    )
+                  ).matches.find((candidate) => candidate.name === nameOrUrl);
+                } catch {
+                  // The install endpoint remains authoritative and can succeed
+                  // independently when catalog discovery is unavailable.
+                }
                 if (match?.source.kind === "local") {
                   result = await libs.installGitHub.installPlugin(
                     {

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",

package/src/cli/commands/roadmap.ts

@@ -14,7 +14,7 @@ import { stripAnsiAndControlChars as sanitize } from "../../util/ansi.js";
 import { applyCommandHelp, subcommand } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
-import { shouldOutputJson, writeError, writeOutput } from "../output.js";
+import { shouldOutputJson, writeOutput } from "../output.js";
 import { roadmapHelp } from "./roadmap.help.js";
 
 // ---------------------------------------------------------------------------
@@ -227,9 +227,6 @@ async function runCreate(cmd: Command, opts: CreateOpts): Promise<void> {
 interface UpdateOpts {
   title?: string;
   description?: string;
-  status?: string;
-  tag?: string[];
-  clearTags?: boolean;
 }
 
 async function runUpdate(
@@ -237,24 +234,11 @@ async function runUpdate(
   slug: string,
   opts: UpdateOpts,
 ): Promise<void> {
-  if (opts.clearTags && opts.tag) {
-    writeError(
-      cmd,
-      "--clear-tags and --tag conflict. Drop --clear-tags to set tags, or drop --tag to remove them all.",
-    );
-    process.exitCode = 1;
-    return;
-  }
-
   const item = await call<MutatedRoadmapItem>("roadmap_update", {
     pathParams: { slug },
     body: {
       title: opts.title,
       description: opts.description,
-      status: opts.status,
-      // `--tag` always carries a value, so an empty set is only reachable
-      // through `--clear-tags`.
-      tags: opts.clearTags ? [] : opts.tag,
     },
   });
 
@@ -334,10 +318,9 @@ export function registerRoadmapCommand(program: Command): void {
       makeTagRepeatable(create);
       create.action((opts: CreateOpts, cmd: Command) => runCreate(cmd, opts));
 
-      const update = subcommand(roadmap, "update");
-      makeTagRepeatable(update);
-      update.action((slug: string, opts: UpdateOpts, cmd: Command) =>
-        runUpdate(cmd, slug, opts),
+      subcommand(roadmap, "update").action(
+        (slug: string, opts: UpdateOpts, cmd: Command) =>
+          runUpdate(cmd, slug, opts),
       );
 
       subcommand(roadmap, "delete").action(

package/src/cli/commands/schedules.ts

@@ -35,6 +35,7 @@ interface ScheduleRecord {
   mode: string;
   status: string;
   routingIntent: string;
+  quiet: boolean;
   reuseConversation: boolean;
   wakeConversationId: string | null;
   sourceKey: string | null;
@@ -268,6 +269,7 @@ export function registerSchedulesCommand(program: Command): void {
               formatScheduleInferenceProfile(schedule.inferenceProfile),
             ],
             ["Routing intent", schedule.routingIntent],
+            ["Quiet", schedule.quiet ? "yes" : "no"],
             ["Reuse conversation", schedule.reuseConversation ? "yes" : "no"],
             ["Wake conversation", schedule.wakeConversationId ?? "—"],
             ["Retry count", String(schedule.retryCount)],