@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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

@@ -2,6 +2,9 @@ import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { Command } from "commander";
 
+import type { CliCommandRunResult } from "./cli-test-harness.js";
+import { runCliCommand } from "./cli-test-harness.js";
+
 let ipcCalls: Array<{ method: string; params?: Record<string, unknown> }> = [];
 let mockIpcResult: {
   ok: boolean;
@@ -41,43 +44,8 @@ mock.module("../../../util/logger.js", () => ({
 
 const { registerSchedulesCommand } = await import("../schedules.js");
 
-async function runCommand(
-  args: string[],
-): Promise<{ stdout: string; exitCode: number }> {
-  const originalStdoutWrite = process.stdout.write.bind(process.stdout);
-  const stdoutChunks: string[] = [];
-
-  process.stdout.write = ((chunk: unknown) => {
-    stdoutChunks.push(typeof chunk === "string" ? chunk : String(chunk));
-    return true;
-  }) as typeof process.stdout.write;
-
-  process.exitCode = 0;
-
-  try {
-    const program = new Command();
-    program.exitOverride();
-    program.configureOutput({
-      writeErr: () => {},
-      writeOut: (str: string) => stdoutChunks.push(str),
-    });
-    registerSchedulesCommand(program);
-    await program.parseAsync(["node", "assistant", ...args]);
-  } catch {
-    if (process.exitCode === 0) {
-      process.exitCode = 1;
-    }
-  } finally {
-    process.stdout.write = originalStdoutWrite;
-  }
-
-  const exitCode = process.exitCode ?? 0;
-  process.exitCode = 0;
-
-  return {
-    exitCode,
-    stdout: stdoutChunks.join(""),
-  };
+function runCommand(args: string[]): Promise<CliCommandRunResult> {
+  return runCliCommand(registerSchedulesCommand, args);
 }
 
 beforeEach(() => {
@@ -231,6 +199,137 @@ describe("schedules list", () => {
     expect(logLines.join("\n")).not.toContain("Authored heartbeat check");
   });
 
+  test("renders a SOURCE column with the owning plugin's name", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: {
+        schedules: [
+          {
+            id: "schedule-plugin",
+            name: "Inbox poll",
+            enabled: true,
+            syntax: "cron",
+            expression: "*/15 * * * *",
+            cronExpression: "*/15 * * * *",
+            timezone: null,
+            message: "poll the inbox",
+            script: null,
+            nextRunAt: 1_778_800_000_000,
+            lastRunAt: null,
+            lastStatus: "ok",
+            retryCount: 0,
+            maxRetries: 3,
+            retryBackoffMs: 60_000,
+            description: "Polls the inbox",
+            cadenceDescription: "Every 15 minutes",
+            mode: "execute",
+            status: "active",
+            routingIntent: "all_channels",
+            reuseConversation: false,
+            wakeConversationId: null,
+            sourceKey: "plugin:gmail/poll-inbox",
+            userEnabled: null,
+            isOneShot: false,
+          },
+          {
+            id: "schedule-imperative",
+            name: "Heartbeat",
+            enabled: true,
+            syntax: "cron",
+            expression: "*/30 * * * *",
+            cronExpression: "*/30 * * * *",
+            timezone: null,
+            message: "run heartbeat",
+            script: null,
+            nextRunAt: 1_778_800_100_000,
+            lastRunAt: null,
+            lastStatus: "ok",
+            retryCount: 0,
+            maxRetries: 3,
+            retryBackoffMs: 60_000,
+            description: "Checks the heartbeat",
+            cadenceDescription: "Every 30 minutes",
+            mode: "execute",
+            status: "active",
+            routingIntent: "all_channels",
+            reuseConversation: false,
+            wakeConversationId: null,
+            sourceKey: null,
+            userEnabled: null,
+            isOneShot: false,
+          },
+        ],
+      },
+    };
+
+    const { exitCode } = await runCommand(["schedules", "list"]);
+
+    expect(exitCode).toBe(0);
+    expect(logLines.join("\n")).toContain("SOURCE");
+    const pluginLine = logLines.find((line) =>
+      line.includes("schedule-plugin"),
+    );
+    const imperativeLine = logLines.find((line) =>
+      line.includes("schedule-imperative"),
+    );
+    expect(pluginLine).toContain("gmail");
+    expect(imperativeLine).not.toContain("gmail");
+  });
+
+  test("--json passes sourceKey and userEnabled through untouched", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: {
+        schedules: [
+          {
+            id: "schedule-plugin",
+            name: "Inbox poll",
+            enabled: false,
+            syntax: "cron",
+            expression: "*/15 * * * *",
+            cronExpression: "*/15 * * * *",
+            timezone: null,
+            message: "poll the inbox",
+            script: null,
+            nextRunAt: 1_778_800_000_000,
+            lastRunAt: null,
+            lastStatus: "ok",
+            retryCount: 0,
+            maxRetries: 3,
+            retryBackoffMs: 60_000,
+            description: "Polls the inbox",
+            cadenceDescription: "Every 15 minutes",
+            mode: "execute",
+            status: "active",
+            routingIntent: "all_channels",
+            reuseConversation: false,
+            wakeConversationId: null,
+            sourceKey: "plugin:gmail/poll-inbox",
+            userEnabled: false,
+            isOneShot: false,
+          },
+        ],
+      },
+    };
+
+    const { stdout, exitCode } = await runCommand([
+      "schedules",
+      "list",
+      "--json",
+    ]);
+
+    expect(exitCode).toBe(0);
+    expect(JSON.parse(stdout)).toEqual({
+      schedules: [
+        expect.objectContaining({
+          id: "schedule-plugin",
+          sourceKey: "plugin:gmail/poll-inbox",
+          userEnabled: false,
+        }),
+      ],
+    });
+  });
+
   test("sets exit code on IPC failure", async () => {
     mockIpcResult = { ok: false, error: "daemon unavailable" };
 

package/src/cli/commands/conversations.ts

@@ -422,10 +422,13 @@ export function registerConversationsCommand(program: Command): void {
             json?: boolean;
           },
         ) => {
-          // A script-mode schedule injects __SCHEDULE_RUN_ID into its env
-          // (see schedule/run-script.ts). When set, thread it through so the
-          // woken turn's usage is attributed to the firing.
+          // A script-mode schedule injects __SCHEDULE_RUN_ID and __SCHEDULE_ID
+          // into its env (see schedule/run-script.ts). The run id attributes the
+          // woken turn's usage to the firing; the schedule id lets the turn run
+          // on the schedule's pinned inference profile, the same profile
+          // execute-mode and wake-mode runs of that schedule use.
           const cronRunId = process.env.__SCHEDULE_RUN_ID;
+          const scheduleId = process.env.__SCHEDULE_ID;
 
           // Fencing only exists on the persisted-event path, so
           // --external-content implies --persist.
@@ -442,6 +445,7 @@ export function registerConversationsCommand(program: Command): void {
               hint: opts.hint,
               source: opts.source,
               ...(cronRunId ? { cronRunId } : {}),
+              ...(scheduleId ? { scheduleId } : {}),
               ...(persist ? { persist: true } : {}),
               ...(externalContent !== undefined ? { externalContent } : {}),
             },

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

@@ -292,6 +292,13 @@ encrypted vault with the specified metadata.
 
 Requires the assistant to be running with at least one connected client.
 
+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 —
+anything said afterwards reaches them after the input is gone, and pointing
+them at a closed prompt makes them re-submit a value that was already received.
+The --label and --description text renders inside the prompt itself, so put the
+instructions there rather than in a follow-up message.
+
 Examples:
   $ assistant credentials prompt --service sentry --field auth_token \\
       --label "Sentry Auth Token" --placeholder "sntrys_..." \\

package/src/cli/commands/inference-profiles.ts

@@ -35,6 +35,8 @@ interface ProfileWriteResult {
   name: string;
   entry: Record<string, unknown>;
   warnings: string[];
+  /** Live-call command the daemon suggests for verifying the written profile. */
+  verify?: string;
 }
 
 type WriteFlags = {
@@ -48,6 +50,7 @@ type WriteFlags = {
   thinking?: string;
   description?: string;
   allowUnlisted?: boolean;
+  allowUnavailable?: boolean;
   json?: boolean;
 };
 
@@ -80,6 +83,9 @@ function buildWriteBody(
   if (opts.allowUnlisted) {
     body.allowUnlisted = true;
   }
+  if (opts.allowUnavailable) {
+    body.allowUnavailable = true;
+  }
 
   if (opts.maxTokens !== undefined) {
     if (!/^\d+$/.test(opts.maxTokens.trim())) {
@@ -118,9 +124,9 @@ function printWriteResult(
     writeLine(`warning: ${warning}`);
   }
   writeLine(`profile ${result.name} ${verb}`);
-  writeLine(
-    `Verify it works: assistant inference send --profile ${result.name} "Reply with OK"`,
-  );
+  if (result.verify) {
+    writeLine(`Verify it works: ${result.verify}`);
+  }
 }
 
 export function attachProfilesSubcommand(inference: Command): void {

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

@@ -36,6 +36,11 @@ const profileWriteOptions: CliOptionHelp[] = [
     flags: "--allow-unlisted",
     description: "Allow a model not in the catalog (warns)",
   },
+  {
+    flags: "--allow-unavailable",
+    description:
+      "Allow a profile that cannot dispatch yet (no connection/API key) — for pre-staging config (warns)",
+  },
   { flags: "--json", description: "Output as machine-readable JSON" },
 ];
 
@@ -223,6 +228,7 @@ a profile that uses it:
       subcommands: [
         {
           name: "list",
+          isDefault: true,
           description: "List configured providers",
           options: [
             { flags: "--provider <p>", description: "Filter by provider" },
@@ -409,6 +415,7 @@ Examples:
       subcommands: [
         {
           name: "list",
+          isDefault: true,
           description: "List catalog models (optionally filtered by provider)",
           options: [
             { flags: "--provider <p>", description: "Filter by provider id" },
@@ -436,16 +443,21 @@ Profiles are named model configurations. Managed defaults (balanced,
 quality-optimized, cost-optimized) are read-only; create your own to
 customize provider, model, and tuning.
 
+Create, then verify with a live call, then activate. Activation is refused
+for a profile that cannot dispatch (no provider connection or API key), so
+verify before you switch the chat model over.
+
 Examples:
   $ assistant inference profiles list
   $ assistant inference profiles create my-fast --provider anthropic \\
       --model claude-haiku-4-5 --connection anthropic-personal --effort low
-  $ assistant inference profiles update my-fast --effort high
+  $ assistant inference send --profile my-fast "Reply with OK"
   $ assistant inference profiles active my-fast
   $ assistant inference profiles delete my-fast`,
       subcommands: [
         {
           name: "list",
+          isDefault: true,
           description: "List the effective profile catalog",
           options: [
             {
@@ -500,7 +512,9 @@ Examples:
           ],
           helpText: `
 With no argument, prints the active profile. With a name, sets it — the
-same deep-merge write the model picker performs.
+same deep-merge write the model picker performs. Setting is refused when
+the named profile cannot dispatch; verify it first with
+'assistant inference send --profile <name> "Reply with OK"'.
 
 Examples:
   $ assistant inference profiles active

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

@@ -128,8 +128,10 @@ Arguments:
   name   Name of a configured MCP server to authenticate with
 
 Only works with sse or streamable-http transports (stdio servers do not use
-OAuth). Opens a browser for OAuth authorization with the remote server. The
-running assistant handles the OAuth callback and token exchange.
+OAuth). On desktop, opens a browser for OAuth authorization with the remote
+server. On web, prints the OAuth URL to the terminal — copy and open it in a
+new browser tab manually. The running assistant handles the OAuth callback
+and token exchange in both cases.
 
 The command waits up to 2.5 minutes for the user to complete the browser-based
 OAuth flow. If the server already has valid cached tokens, the command succeeds

package/src/cli/commands/memory/memory-retrospective.ts

@@ -135,6 +135,11 @@ function renderOutcome(outcome: MemoryRetrospectiveOutcome): void {
     case "no_new_messages":
       log.info("No new messages to review since the last retrospective.");
       break;
+    case "no_user_activity":
+      log.info(
+        "No user activity in the window since the last retrospective; skipping.",
+      );
+      break;
     case "source_dormant":
       log.info(
         "Source conversation is dormant beyond the sweep lookback; skipping.",
@@ -152,6 +157,15 @@ function renderOutcome(outcome: MemoryRetrospectiveOutcome): void {
       );
       process.exitCode = 1;
       break;
+    case "no_usable_output":
+      log.error(
+        `Run produced no usable output` +
+          `${outcome.reason ? `: ${outcome.reason}` : ""}` +
+          (outcome.conversationId ? ` (fork: ${outcome.conversationId})` : "") +
+          `. The window stays retryable.`,
+      );
+      process.exitCode = 1;
+      break;
     case "invoked":
       log.info(
         `Retrospective invoked.\n` +
@@ -163,5 +177,9 @@ function renderOutcome(outcome: MemoryRetrospectiveOutcome): void {
             : ""),
       );
       break;
+    default: {
+      const _exhaustive: never = outcome;
+      break;
+    }
   }
 }

package/src/cli/commands/notifications.ts

@@ -258,9 +258,9 @@ export function registerNotificationsCommand(program: Command): void {
               return;
             }
 
-            // Picks up __CONVERSATION_ID / __SKILL_CONTEXT_JSON env vars
-            // so deferred-emit can buffer notifications when called from a
-            // background job that hasn't confirmed success yet.
+            // Picks up __CONVERSATION_ID / __SKILL_CONTEXT_JSON env vars so
+            // a send invoked from inside an agent turn resolves the
+            // conversation it originated from.
             const originatingConversationId = tryResolveConversationId();
 
             // The signal's `sourceContextId` doubles as the home-feed's
@@ -306,9 +306,6 @@ export function registerNotificationsCommand(program: Command): void {
                 ...(conversationId
                   ? { conversationAffinityHint: { vellum: conversationId } }
                   : {}),
-                ...(originatingConversationId
-                  ? { originatingConversationId }
-                  : {}),
                 throwOnError: true,
               },
             });

package/src/cli/commands/oauth/connect-surface-guidance.test.ts

@@ -36,5 +36,21 @@ describe("OAuth connect surface guidance", () => {
     expect(hint).toContain('surface_type "oauth_connect"');
     expect(hint).toContain('data.providerKey "google"');
     expect(hint).toContain("paste an OAuth URL");
+    expect(hint).not.toContain("requestedScopes");
+  });
+
+  test("hint with scopes teaches the full replacement set semantics", () => {
+    const hint = oauthConnectSurfaceHint("google", ["a", "b"]);
+    expect(hint).toContain("data.requestedScopes");
+    expect(hint).toContain("full replacement set");
+  });
+
+  test("redirect with scopes carries requestedScopes in the next action", () => {
+    const redirect = buildOAuthConnectSurfaceRedirect("google", ["a", "b"]);
+    expect(redirect.nextAction.data).toEqual({
+      providerKey: "google",
+      requestedScopes: ["a", "b"],
+    });
+    expect(redirect.hint).toBe(oauthConnectSurfaceHint("google", ["a", "b"]));
   });
 });

package/src/cli/commands/oauth/connect-surface-guidance.ts

@@ -1,7 +1,9 @@
+import type { OAuthConnectSurfaceData } from "../../../api/surfaces.js";
+
 export interface OAuthConnectSurfaceNextAction {
   type: "ui_show";
   surfaceType: "oauth_connect";
-  data: { providerKey: string };
+  data: Pick<OAuthConnectSurfaceData, "providerKey" | "requestedScopes">;
 }
 
 export interface OAuthConnectSurfaceRedirect {
@@ -12,35 +14,51 @@ export interface OAuthConnectSurfaceRedirect {
   nextAction: OAuthConnectSurfaceNextAction;
 }
 
-export function oauthConnectSurfaceHint(provider: string): string {
-  return (
+export function oauthConnectSurfaceHint(
+  provider: string,
+  requestedScopes?: string[],
+): string {
+  const base =
     `To let the user connect, render the connect button: call ` +
     `\`ui_show\` with surface_type "oauth_connect" and ` +
     `data.providerKey "${provider}". That surface is always available — do ` +
     `not run further \`oauth\`/\`channels\` commands, paste an OAuth URL, or ` +
-    `load a setup skill just to display it.`
+    `load a setup skill just to display it.`;
+  if (!requestedScopes?.length) {
+    return base;
+  }
+  return (
+    base +
+    ` Include data.requestedScopes verbatim from nextAction.data in the ` +
+    `\`ui_show\` call: it is a full replacement set, so list every default ` +
+    `scope you want to keep, not just the new ones.`
   );
 }
 
 export function buildOAuthConnectSurfaceNextAction(
   provider: string,
+  requestedScopes?: string[],
 ): OAuthConnectSurfaceNextAction {
   return {
     type: "ui_show",
     surfaceType: "oauth_connect",
-    data: { providerKey: provider },
+    data: {
+      providerKey: provider,
+      ...(requestedScopes?.length ? { requestedScopes } : {}),
+    },
   };
 }
 
 export function buildOAuthConnectSurfaceRedirect(
   provider: string,
+  requestedScopes?: string[],
 ): OAuthConnectSurfaceRedirect {
   return {
     ok: false,
     code: "use_oauth_connect_surface",
     provider,
-    hint: oauthConnectSurfaceHint(provider),
-    nextAction: buildOAuthConnectSurfaceNextAction(provider),
+    hint: oauthConnectSurfaceHint(provider, requestedScopes),
+    nextAction: buildOAuthConnectSurfaceNextAction(provider, requestedScopes),
   };
 }
 

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

@@ -70,7 +70,7 @@ afterEach(() => {
   process.exitCode = 0;
 });
 
-async function runConnectCommand(): Promise<{
+async function runConnectCommand(extraArgs: string[] = []): Promise<{
   stdout: string;
   exitCode: number;
 }> {
@@ -94,6 +94,7 @@ async function runConnectCommand(): Promise<{
       "--json",
       "connect",
       "google",
+      ...extraArgs,
     ]);
   } catch {
     // Commander may throw under exitOverride for parse errors; the assertions
@@ -123,4 +124,28 @@ describe("oauth connect", () => {
       "oauth_mode_get",
     ]);
   });
+
+  test("managed provider in a conversation shell includes requested scopes in the oauth_connect guidance", async () => {
+    const { stdout, exitCode } = await runConnectCommand([
+      "--scopes",
+      "https://www.googleapis.com/auth/tasks",
+      "https://www.googleapis.com/auth/calendar",
+    ]);
+
+    expect(exitCode).toBe(1);
+    const parsed = JSON.parse(stdout) as Record<string, unknown>;
+    expect(parsed.code).toBe("use_oauth_connect_surface");
+    expect(parsed.nextAction).toEqual({
+      type: "ui_show",
+      surfaceType: "oauth_connect",
+      data: {
+        providerKey: "google",
+        requestedScopes: [
+          "https://www.googleapis.com/auth/tasks",
+          "https://www.googleapis.com/auth/calendar",
+        ],
+      },
+    });
+    expect(openedUrls).toEqual([]);
+  });
 });

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

@@ -141,7 +141,10 @@ export function registerConnectCommand(oauth: Command): void {
             // =============================================================
 
             if (isModelSpawnedConversationShell()) {
-              const redirect = buildOAuthConnectSurfaceRedirect(provider);
+              const redirect = buildOAuthConnectSurfaceRedirect(
+                provider,
+                opts.scopes,
+              );
               writeOutput(cmd, redirect);
               process.exitCode = 1;
               return;

package/src/cli/commands/oauth/index.help.ts

@@ -691,7 +691,9 @@ Important for chat/UI turns: do not run this command just to let the user
 connect a managed provider. Render the first-class connect surface instead:
 call \`ui_show\` with surface_type "oauth_connect" and data.providerKey set to
 the provider (for example, "google"). That surface starts the managed OAuth UI
-and avoids pasting raw authorization links into the conversation.
+and avoids pasting raw authorization links into the conversation. If the user
+needs non-default scopes, also pass data.requestedScopes as a full replacement
+set (list every scope the connection should keep, not just the new ones).
 
 Examples:
   $ assistant oauth connect google

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

@@ -13,6 +13,8 @@ const log = getCliLogger("cli");
 
 interface SerializedProvider {
   providerKey: string;
+  /** Which sense of connected: a grant to act as the user, or a bot. */
+  actsAs?: "user" | "assistant";
   displayName?: string | null;
   description?: string | null;
   supportsManagedMode?: boolean;
@@ -301,6 +303,7 @@ export function registerProviderCommands(oauth: Command): void {
         dashboardUrl: p.dashboard_url as string | null,
         clientIdPlaceholder: p.client_id_placeholder as string | null,
         featureFlag: p.feature_flag as string | null,
+        actsAs: p.acts_as as "user" | "assistant" | undefined,
       }));
 
       if (opts.providerKey) {

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

@@ -48,7 +48,11 @@ Examples:
       description:
         "Install a plugin by name from the Vellum platform (content is served as a verified tarball from the plugin's pinned commit), or directly from a GitHub URL (untrusted)",
       options: [
-        { flags: "--force", description: "Overwrite an existing install" },
+        {
+          flags: "--force",
+          description:
+            "Overwrite an existing install and skip the declared-schedules confirmation prompt",
+        },
         {
           flags: "--ref <ref>",
           description: `For a marketplace install, the manifest revision to read the pin from (default: ${DEFAULT_PLUGIN_REF}). For a GitHub URL, the git ref (branch/tag/SHA) to clone — states a slash-containing branch (e.g. feature/x) explicitly and skips the remote ref lookup a bare /tree/ URL otherwise does`,
@@ -70,6 +74,11 @@ Examples:
         },
       ],
       helpText: `
+A plugin that declares schedules (a schedules/ directory) has them listed
+during the install, and the install asks for confirmation before finalizing:
+schedules run automatically in the background once the plugin is installed.
+Pass --force to skip the prompt (required for non-interactive installs).
+
 A GitHub URL (anything containing a slash) installs directly from that repo,
 bypassing the marketplace whitelist. Such a plugin is UNTRUSTED — it has not
 been reviewed and its hooks/tools run with full assistant access — so the
@@ -121,7 +130,7 @@ Examples:
       name: "inspect",
       args: "<name>",
       description:
-        "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools) it contributes",
+        "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools, schedules) it contributes",
       options: [
         {
           flags: "--json",
@@ -245,6 +254,11 @@ $ assistant plugins publish --json`,
           flags: "--json",
           description: "Emit machine-readable JSON instead of a summary",
         },
+        {
+          flags: "--force",
+          description:
+            "Skip the declared-schedules confirmation prompt of a local upgrade (the assistant-applied path never prompts)",
+        },
       ],
       helpText: `
 A marketplace plugin upgrades to the curated pin. A plugin installed directly
@@ -253,6 +267,15 @@ whatever its recorded ref resolves to now — a pinned commit SHA is immutable (
 no-op), while a branch/tag/HEAD advances as upstream does — and re-materializes
 it verbatim, with no curated adapter overlay.
 
+With the assistant running, the upgrade is applied by it immediately, with no
+confirmation prompt: a schedule the new revision declares is armed by the
+assistant and surfaced as a notification, and the upgrade output lists the
+revision's declared schedules with any new ones marked. Only when the
+assistant is unreachable does the upgrade run locally instead; that path
+stages the new revision first, and a revision that declares schedules lists
+them and asks for confirmation before going live (--force skips that prompt,
+as for install).
+
 Examples:
   $ assistant plugins upgrade example
   $ assistant plugins upgrade example --dry-run