@vellumai/assistant 0.8.12 → 0.9.0-staging.2

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

@@ -98,8 +98,10 @@ describe("schedules command", () => {
     expect(schedules).toBeDefined();
     expect(schedules!.commands.map((command) => command.name())).toEqual([
       "list",
+      "get",
       "runs",
       "create",
+      "update",
       "enable",
       "disable",
       "cancel",
@@ -252,6 +254,125 @@ describe("schedules list", () => {
   });
 });
 
+describe("schedules get", () => {
+  const scheduleFixture = {
+    id: "schedule-1",
+    name: "Heartbeat",
+    enabled: true,
+    syntax: "cron",
+    expression: "*/30 * * * *",
+    cronExpression: "*/30 * * * *",
+    timezone: "UTC",
+    message: "run heartbeat",
+    script: null,
+    nextRunAt: 1_778_800_000_000,
+    lastRunAt: 1_778_799_000_000,
+    lastStatus: "ok",
+    retryCount: 0,
+    maxRetries: 3,
+    retryBackoffMs: 60_000,
+    timeoutMs: null,
+    createdFromConversationId: "conv-abc",
+    description: "Authored heartbeat check",
+    cadenceDescription: "Every 30 minutes",
+    mode: "execute",
+    status: "active",
+    routingIntent: "all_channels",
+    reuseConversation: false,
+    wakeConversationId: null,
+    isOneShot: false,
+  };
+
+  test("calls getSchedule with the schedule ID path param", async () => {
+    mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
+
+    const { exitCode } = await runCommand(["schedules", "get", "schedule-1"]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "getSchedule",
+        params: { pathParams: { id: "schedule-1" } },
+      },
+    ]);
+  });
+
+  test("inspect alias resolves to the same getSchedule handler", async () => {
+    // GIVEN the daemon returns a schedule for the requested ID
+    mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
+
+    // WHEN the user invokes the `inspect` alias instead of `get`
+    const { exitCode } = await runCommand([
+      "schedules",
+      "inspect",
+      "schedule-1",
+    ]);
+
+    // THEN it calls the same getSchedule IPC method with the ID path param
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "getSchedule",
+        params: { pathParams: { id: "schedule-1" } },
+      },
+    ]);
+    // AND it renders the same human-readable detail view
+    expect(logLines.join("\n")).toContain("run heartbeat");
+  });
+
+  test("renders a detail view for human output", async () => {
+    mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
+
+    const { exitCode } = await runCommand(["schedules", "get", "schedule-1"]);
+
+    expect(exitCode).toBe(0);
+    const output = logLines.join("\n");
+    expect(output).toContain("ID:");
+    expect(output).toContain("schedule-1");
+    expect(output).toContain("Heartbeat");
+    expect(output).toContain("Authored heartbeat check");
+    expect(output).toContain("Every 30 minutes (UTC)");
+    expect(output).toContain("run heartbeat");
+    expect(output).toContain("all_channels");
+    expect(output).toContain("conv-abc");
+  });
+
+  test("emits JSON result when --json is set", async () => {
+    mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
+
+    const { stdout, exitCode } = await runCommand([
+      "schedules",
+      "get",
+      "schedule-1",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(JSON.parse(stdout)).toEqual({
+      schedule: expect.objectContaining({
+        id: "schedule-1",
+        name: "Heartbeat",
+        description: "Authored heartbeat check",
+      }),
+    });
+    expect(logLines).toEqual([]);
+  });
+
+  test("routes IPC failure through exitFromIpcResult", async () => {
+    mockIpcResult = { ok: false, error: "Schedule not found" };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "get",
+      "missing-schedule",
+    ]);
+
+    expect(exitCode).toBe(10);
+    expect(exitFromIpcResultCalls).toEqual([mockIpcResult]);
+    expect(errorLines).toEqual([]);
+  });
+});
+
 describe("schedules runs", () => {
   test("calls listScheduleRuns with the schedule ID path param", async () => {
     mockIpcResult = { ok: true, result: { runs: [] } };
@@ -343,10 +464,49 @@ describe("schedules runs", () => {
     expect(exitCode).toBe(0);
     expect(logLines.join("\n")).toContain("STATUS");
     expect(logLines.join("\n")).toContain("run-1");
-    expect(logLines.join("\n")).toContain("2500ms");
+    expect(logLines.join("\n")).toContain("2.5s");
     expect(logLines.join("\n")).toContain("conversation-1");
   });
 
+  test("formats run durations into human-friendly units", async () => {
+    const durations = [
+      { ms: 450, expected: "450ms" },
+      { ms: 29_854, expected: "29.9s" },
+      { ms: 30_000, expected: "30s" },
+      { ms: 90_000, expected: "1m 30s" },
+      { ms: 300_000, expected: "5m" },
+      { ms: 3_600_000, expected: "1h" },
+      { ms: 8_100_000, expected: "2h 15m" },
+      { ms: 93_600_000, expected: "1d 2h" },
+    ];
+
+    mockIpcResult = {
+      ok: true,
+      result: {
+        runs: durations.map((d, i) => ({
+          id: `run-${i}`,
+          jobId: "schedule-1",
+          status: "ok",
+          startedAt: 1_778_799_000_000,
+          finishedAt: 1_778_799_000_000 + d.ms,
+          durationMs: d.ms,
+          output: "done",
+          error: null,
+          conversationId: `conversation-${i}`,
+          createdAt: 1_778_799_000_000,
+        })),
+      },
+    };
+
+    const { exitCode } = await runCommand(["schedules", "runs", "schedule-1"]);
+
+    expect(exitCode).toBe(0);
+    const output = logLines.join("\n");
+    for (const { expected } of durations) {
+      expect(output).toContain(expected);
+    }
+  });
+
   test("prints an empty message when no runs are found", async () => {
     mockIpcResult = { ok: true, result: { runs: [] } };
 
@@ -590,6 +750,275 @@ describe("schedules create", () => {
   });
 });
 
+describe("schedules update", () => {
+  test("calls updateSchedule with only the provided flags", async () => {
+    mockIpcResult = { ok: true, result: { schedules: [] } };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--name",
+      "Renamed",
+      "--expression",
+      "0 9 * * MON-FRI",
+      "--timezone",
+      "America/New_York",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "updateSchedule",
+        params: {
+          pathParams: { id: "schedule-1" },
+          body: {
+            name: "Renamed",
+            expression: "0 9 * * MON-FRI",
+            timezone: "America/New_York",
+          },
+        },
+      },
+    ]);
+    expect(logLines).toEqual(["Updated schedule: schedule-1"]);
+  });
+
+  test("errors when no update flags are provided", async () => {
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(ipcCalls).toEqual([]);
+    expect(errorLines.join("\n")).toContain(
+      "At least one update flag is required",
+    );
+  });
+
+  test("parses numeric retry and timeout flags into numbers", async () => {
+    mockIpcResult = { ok: true, result: { schedules: [] } };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--max-retries",
+      "5",
+      "--retry-backoff-ms",
+      "30000",
+      "--timeout-ms",
+      "5000",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "updateSchedule",
+        params: {
+          pathParams: { id: "schedule-1" },
+          body: { maxRetries: 5, retryBackoffMs: 30_000, timeoutMs: 5000 },
+        },
+      },
+    ]);
+  });
+
+  test("rejects a non-integer --max-retries", async () => {
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--max-retries",
+      "lots",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(ipcCalls).toEqual([]);
+    expect(errorLines.join("\n")).toContain("--max-retries must be an integer");
+  });
+
+  test("sends timeoutMs null with --clear-timeout", async () => {
+    mockIpcResult = { ok: true, result: { schedules: [] } };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--clear-timeout",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "updateSchedule",
+        params: {
+          pathParams: { id: "schedule-1" },
+          body: { timeoutMs: null },
+        },
+      },
+    ]);
+  });
+
+  test("rejects --timeout-ms combined with --clear-timeout", async () => {
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--timeout-ms",
+      "5000",
+      "--clear-timeout",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(ipcCalls).toEqual([]);
+    expect(errorLines.join("\n")).toContain("mutually exclusive");
+  });
+
+  test("rejects --mode wake when the schedule has no wake conversation target", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: { schedule: { wakeConversationId: null } },
+    };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--mode",
+      "wake",
+    ]);
+
+    expect(exitCode).toBe(1);
+    expect(ipcCalls).toEqual([
+      { method: "getSchedule", params: { pathParams: { id: "schedule-1" } } },
+    ]);
+    expect(errorLines.join("\n")).toContain("wake conversation target");
+  });
+
+  test("allows --mode wake when the schedule already has a wake target", async () => {
+    // The shared mock returns one shape for both IPC calls; satisfy the
+    // getSchedule guard and the update response renderer simultaneously.
+    mockIpcResult = {
+      ok: true,
+      result: {
+        schedule: { wakeConversationId: "conv-1" },
+        schedules: [],
+      },
+    };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--mode",
+      "wake",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toHaveLength(2);
+    expect(ipcCalls[0].method).toBe("getSchedule");
+    expect(ipcCalls[1]).toEqual({
+      method: "updateSchedule",
+      params: {
+        pathParams: { id: "schedule-1" },
+        body: { mode: "wake" },
+      },
+    });
+  });
+
+  test("sends boolean false for negated flags", async () => {
+    mockIpcResult = { ok: true, result: { schedules: [] } };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--no-quiet",
+      "--no-reuse-conversation",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(ipcCalls).toEqual([
+      {
+        method: "updateSchedule",
+        params: {
+          pathParams: { id: "schedule-1" },
+          body: { quiet: false, reuseConversation: false },
+        },
+      },
+    ]);
+  });
+
+  test("emits JSON result when --json is set", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: {
+        schedules: [
+          {
+            id: "schedule-1",
+            name: "Renamed",
+            enabled: true,
+            syntax: "cron",
+            expression: "0 9 * * MON-FRI",
+            cronExpression: "0 9 * * MON-FRI",
+            timezone: "America/New_York",
+            message: "run heartbeat",
+            script: null,
+            nextRunAt: 1_778_800_000_000,
+            lastRunAt: null,
+            lastStatus: "ok",
+            retryCount: 0,
+            maxRetries: 3,
+            retryBackoffMs: 60_000,
+            description: "Authored heartbeat check",
+            cadenceDescription: "At 9:00 AM, Monday through Friday",
+            mode: "execute",
+            status: "active",
+            routingIntent: "all_channels",
+            reuseConversation: false,
+            wakeConversationId: null,
+            isOneShot: false,
+          },
+        ],
+      },
+    };
+
+    const { stdout, exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "schedule-1",
+      "--name",
+      "Renamed",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(JSON.parse(stdout)).toEqual({
+      schedules: [
+        expect.objectContaining({ id: "schedule-1", name: "Renamed" }),
+      ],
+    });
+    expect(logLines).toEqual([]);
+  });
+
+  test("routes IPC failure through exitFromIpcResult", async () => {
+    mockIpcResult = { ok: false, error: "Schedule not found" };
+
+    const { exitCode } = await runCommand([
+      "schedules",
+      "update",
+      "missing-schedule",
+      "--name",
+      "Renamed",
+    ]);
+
+    expect(exitCode).toBe(10);
+    expect(exitFromIpcResultCalls).toEqual([mockIpcResult]);
+    expect(errorLines).toEqual([]);
+  });
+});
+
 describe("schedules enable/disable", () => {
   test("enable calls toggleSchedule with enabled true", async () => {
     mockIpcResult = { ok: true, result: { schedules: [] } };

package/src/cli/commands/credentials.ts

@@ -5,6 +5,7 @@ import type { CredentialPromptResult } from "../../runtime/routes/credential-pro
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { shouldOutputJson, writeOutput } from "../output.js";
+import { tryResolveConversationId } from "../utils/conversation-id.js";
 
 // ---------------------------------------------------------------------------
 // Format-aware error output
@@ -114,8 +115,7 @@ export function registerCredentialsCommand(program: Command): void {
     description:
       "Manage credentials in the encrypted vault (API keys, tokens, passwords)",
     build: (credential) => {
-      credential
-        .option("--json", "Machine-readable compact JSON output");
+      credential.option("--json", "Machine-readable compact JSON output");
 
       credential.addHelpText(
         "after",
@@ -224,9 +224,7 @@ Examples:
 
       credential
         .command("status")
-        .description(
-          "Show the active credential backend and its configuration",
-        )
+        .description("Show the active credential backend and its configuration")
         .addHelpText(
           "after",
           `
@@ -248,9 +246,8 @@ Examples:
   $ assistant credentials status --json`,
         )
         .action(async (_opts: Record<string, unknown>, cmd: Command) => {
-          const r = await cliIpcCall<CredentialsStatusResponse>(
-            "credentials_status",
-          );
+          const r =
+            await cliIpcCall<CredentialsStatusResponse>("credentials_status");
           if (!r.ok) {
             return exitFromIpcResult(
               r as { ok: false; error?: string; statusCode?: number },
@@ -286,7 +283,10 @@ Examples:
       credential
         .command("set <value>")
         .description("Store a secret and create or update its metadata")
-        .requiredOption("--service <service>", "Service namespace (e.g. google)")
+        .requiredOption(
+          "--service <service>",
+          "Service namespace (e.g. google)",
+        )
         .requiredOption("--field <field>", "Field name (e.g. client_secret)")
         .option("--label <label>", 'Human-friendly label (e.g. "prod", "work")')
         .option(
@@ -345,7 +345,8 @@ Examples:
             if (!r.ok) {
               writeError(
                 cmd,
-                r.error ?? `Failed to store credential ${opts.service}:${opts.field}`,
+                r.error ??
+                  `Failed to store credential ${opts.service}:${opts.field}`,
               );
               process.exitCode = 1;
               return;
@@ -397,7 +398,8 @@ Examples:
             if (!r.ok) {
               writeError(
                 cmd,
-                r.error ?? `Failed to delete credential ${opts.service}:${opts.field}`,
+                r.error ??
+                  `Failed to delete credential ${opts.service}:${opts.field}`,
               );
               process.exitCode = 1;
               return;
@@ -410,9 +412,7 @@ Examples:
                 field: opts.field,
               });
             } else {
-              log.info(
-                `Deleted credential ${opts.service}:${opts.field}`,
-              );
+              log.info(`Deleted credential ${opts.service}:${opts.field}`);
             }
           },
         );
@@ -588,6 +588,10 @@ Examples:
         .requiredOption("--label <label>", "Display label for the prompt UI")
         .option("--description <description>", "Context shown in the prompt UI")
         .option("--placeholder <placeholder>", "Placeholder text for the input")
+        .option(
+          "--usage-description <description>",
+          "Human-readable description of intended usage, stored in credential metadata and shown as the prompt's purpose",
+        )
         .option(
           "--allowed-domains <domains>",
           "Comma-separated domains where this credential may be used",
@@ -613,6 +617,7 @@ Requires the assistant to be running with at least one connected client.
 Examples:
   $ assistant credentials prompt --service sentry --field auth_token \\
       --label "Sentry Auth Token" --placeholder "sntrys_..." \\
+      --usage-description "Read Sentry issues and events" \\
       --allowed-domains "sentry.io" \\
       --injection-templates '[{"hostPattern":"sentry.io","injectionType":"header","headerName":"Authorization","valuePrefix":"Bearer "}]'`,
         )
@@ -624,6 +629,7 @@ Examples:
               label: string;
               description?: string;
               placeholder?: string;
+              usageDescription?: string;
               allowedDomains?: string;
               allowedTools?: string;
               injectionTemplates?: string;
@@ -663,9 +669,11 @@ Examples:
                   label: opts.label,
                   description: opts.description,
                   placeholder: opts.placeholder,
+                  usageDescription: opts.usageDescription,
                   allowedDomains,
                   allowedTools,
                   injectionTemplates,
+                  conversationId: tryResolveConversationId(),
                 },
               },
               { timeoutMs: PROMPT_TIMEOUT_MS },
@@ -681,22 +689,18 @@ Examples:
             }
 
             if (!ipc.result?.ok) {
-              writeError(
-                cmd,
-                ipc.result?.error ?? "Credential prompt failed",
-              );
+              writeError(cmd, ipc.result?.error ?? "Credential prompt failed");
               process.exitCode = 1;
               return;
             }
 
             if (shouldOutputJson(cmd)) {
-              writeOutput(cmd, {
-                ok: true,
-                service: opts.service,
-                field: opts.field,
-              });
+              writeOutput(cmd, ipc.result);
             } else {
-              log.info(`Stored credential ${opts.service}:${opts.field}`);
+              log.info(
+                ipc.result.message ??
+                  `Stored credential ${opts.service}:${opts.field}`,
+              );
             }
           },
         );

package/src/cli/commands/image-generation.ts

@@ -66,10 +66,13 @@ Modes:
   managed    — Uses platform-managed credentials (requires login to Vellum).
   your-own   — Uses your own Gemini or OpenAI API key depending on the configured model.
 
-Supported models:
-  gemini-3.1-flash-image-preview (default)
-  gemini-3-pro-image-preview
-  gpt-image-2
+Supported models: pass a tier alias, the assistant resolves it to the
+current model for that tier.
+  fast     (default) quickest, good quality
+  quality  higher fidelity, slower
+  openai   OpenAI's model
+A concrete model ID is also accepted; unknown values return an error
+listing the currently available models.
 
 Examples:
   $ assistant image-generation generate --prompt "A sunset over the ocean"
@@ -113,8 +116,8 @@ Examples:
   $ assistant image-generation generate --prompt "A mountain landscape at dawn"
   $ assistant image-generation generate --prompt "Make it darker" --mode edit --source input.png
   $ assistant image-generation generate --prompt "Logo variations" --variants 4 --output-dir ./logos
-  $ assistant image-generation generate --prompt "A robot" --model gemini-3-pro-image-preview --json
-  $ assistant image-generation generate --prompt "A robot" --model gpt-image-2 --json`,
+  $ assistant image-generation generate --prompt "A robot" --model quality --json
+  $ assistant image-generation generate --prompt "A robot" --model openai --json`,
       );
 
       generate.action(async (opts) => {
@@ -166,7 +169,10 @@ Examples:
                 file.type !== "application/octet-stream"
                   ? file.type
                   : mimeForExtension(filePath);
-              validImages.push({ mimeType, dataBase64: buffer.toString("base64") });
+              validImages.push({
+                mimeType,
+                dataBase64: buffer.toString("base64"),
+              });
             } catch (err) {
               errors.push(
                 `Could not read ${filePath}: ${(err as Error).message}`,
@@ -191,7 +197,11 @@ Examples:
 
         // Call daemon via IPC
         const r = await cliIpcCall<{
-          images: Array<{ mimeType: string; dataBase64: string; title?: string }>;
+          images: Array<{
+            mimeType: string;
+            dataBase64: string;
+            title?: string;
+          }>;
           text?: string;
           resolvedModel: string;
         }>("image_generation_generate", {
@@ -204,7 +214,11 @@ Examples:
           },
         });
 
-        if (!r.ok) return exitFromIpcResult({ ok: false, error: r.error, statusCode: r.statusCode }, generate);
+        if (!r.ok)
+          return exitFromIpcResult(
+            { ok: false, error: r.error, statusCode: r.statusCode },
+            generate,
+          );
 
         // Write images to disk (stays in CLI)
         if (!existsSync(outputDir)) {

package/src/cli/commands/notifications.ts

@@ -548,7 +548,7 @@ Examples:
         .addHelpText(
           "after",
           `
-Reads the home feed at ~/.vellum/workspace/data/home-feed.json — the
+Reads the home feed at $VELLUM_WORKSPACE_DIR/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;