@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

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

@@ -67,9 +67,8 @@ mock.module("../../../util/logger.js", () => ({
 // Import module under test (after mocks)
 // ---------------------------------------------------------------------------
 
-const { formatBrowserStatusLines, registerBrowserCommand } = await import(
-  "../browser.js"
-);
+const { formatBrowserStatusLines, registerBrowserCommand } =
+  await import("../browser.js");
 
 // ---------------------------------------------------------------------------
 // Test helper
@@ -641,3 +640,85 @@ describe("error exit codes", () => {
     expect(exitCode).toBe(0);
   });
 });
+
+for (const desktopFlag of ["--virtual-desktop", "--desktop"]) {
+  describe(`virtual desktop routing via ${desktopFlag}`, () => {
+    test("routes semantic actions through IPC with conversation and element identity", async () => {
+      process.env.__CONVERSATION_ID = "conv-desktop";
+      const result = await runCommand([
+        "browser",
+        desktopFlag,
+        "--json",
+        "click",
+        "--element-id",
+        "e7",
+      ]);
+      expect(result.exitCode).toBe(0);
+      expect(lastIpcCall?.method).toBe("browser_execute");
+      expect(lastBody()).toMatchObject({
+        desktop: true,
+        conversationId: "conv-desktop",
+        operation: "click",
+        input: { element_id: "e7" },
+      });
+      expect(
+        (lastBody().input as Record<string, unknown>).desktop,
+      ).toBeUndefined();
+    });
+
+    test.each([
+      { args: ["list"] },
+      { args: ["select", "--tab-id", "7"] },
+      { args: ["new"] },
+      { args: ["close", "--tab-id", "7"] },
+    ])("routes desktop tabs $args through IPC", async ({ args }) => {
+      mockIpcResult = { ok: true, result: { ok: true, tabs: [] } };
+      const result = await runCommand([
+        "browser",
+        desktopFlag,
+        "--json",
+        "tabs",
+        ...args,
+      ]);
+      expect(result.exitCode).toBe(0);
+      expect(lastIpcCall?.method).toBe("browser_tabs");
+      expect(lastBody()).toMatchObject({ desktop: true, command: args[0] });
+    });
+
+    test.each([
+      { flags: ["--browser-mode", "extension"] },
+      { flags: ["--target-client-id", "client-123"] },
+    ])("rejects conflicting desktop targets before IPC", async ({ flags }) => {
+      const result = await runCommand([
+        "browser",
+        desktopFlag,
+        ...flags,
+        "tabs",
+        "list",
+      ]);
+      expect(result.exitCode).not.toBe(0);
+      expect(lastIpcCall).toBeNull();
+    });
+  });
+}
+
+test.each([
+  { args: ["list"] },
+  { args: ["select", "--tab-id", "1"] },
+  { args: ["new", "--url", "https://example.com"] },
+  { args: ["close", "--tab-id", "1"] },
+])(
+  "tab command $args forwards an explicit backend override",
+  async ({ args }) => {
+    mockIpcResult = { ok: true, result: { ok: true, tabs: [] } };
+    await runCommand([
+      "browser",
+      "--browser-mode",
+      "extension",
+      "tabs",
+      ...args,
+    ]);
+    expect(lastIpcCall?.method).toBe("browser_tabs");
+    expect(lastBody().browserMode).toBe("extension");
+  },
+);

package/src/cli/commands/__tests__/cli-test-harness.ts

@@ -6,7 +6,10 @@
  * `process.stdout.write`, `process.stderr.write`, `console.log`, and
  * `console.error` are captured for the duration of the run, so command output
  * lands in the result regardless of which sink the command writes to;
- * `process.exitCode` is reset afterwards.
+ * `process.exitCode` is reset afterwards. A write callback is honoured the
+ * way the real stream honours it, and `process.exit` records its code as the
+ * run's exit code instead of ending the test process, so a command that exits
+ * itself once its output has drained is observed rather than fatal.
  * The caller passes its own (possibly mock-backed) registration function, so
  * this helper imports nothing from `src/` beyond what any test file may
  * import itself (see the test-machinery isolation rules in assistant/CLAUDE.md).
@@ -34,18 +37,32 @@ export async function runCliCommand(
   const stderrChunks: string[] = [];
   const events: string[] = [];
 
-  process.stdout.write = ((chunk: unknown) => {
+  const originalExit = process.exit;
+  const invokeCallback = (rest: unknown[]): void => {
+    const callback = rest.find((arg) => typeof arg === "function");
+    if (callback) {
+      (callback as () => void)();
+    }
+  };
+  process.stdout.write = ((chunk: unknown, ...rest: unknown[]) => {
     const text = typeof chunk === "string" ? chunk : String(chunk);
     stdoutChunks.push(text);
     events.push(text);
+    invokeCallback(rest);
     return true;
   }) as typeof process.stdout.write;
-  process.stderr.write = ((chunk: unknown) => {
+  process.stderr.write = ((chunk: unknown, ...rest: unknown[]) => {
     const text = typeof chunk === "string" ? chunk : String(chunk);
     stderrChunks.push(text);
     events.push(text);
+    invokeCallback(rest);
     return true;
   }) as typeof process.stderr.write;
+  process.exit = ((code?: number) => {
+    if (code !== undefined) {
+      process.exitCode = code;
+    }
+  }) as typeof process.exit;
   console.log = (...logArgs: unknown[]) => {
     const text = logArgs.map(String).join(" ") + "\n";
     stdoutChunks.push(text);
@@ -75,6 +92,7 @@ export async function runCliCommand(
   } finally {
     process.stdout.write = originalStdoutWrite;
     process.stderr.write = originalStderrWrite;
+    process.exit = originalExit;
     console.log = originalConsoleLog;
     console.error = originalConsoleError;
   }

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

@@ -37,6 +37,7 @@ import type {
   InstallPluginOptions,
   InstallPluginResult,
 } from "../../lib/install-from-github.js";
+import type { PluginSearchMatch } from "../../lib/search-plugins.js";
 import type {
   PluginUpgradeResult,
   UpgradePluginDeps,
@@ -63,6 +64,8 @@ let stageFixture: ((stagingDir: string) => void) | null = null;
 let installPluginCalls: InstallPluginOptions[] = [];
 let platformInstallCalls: Array<{ name: string; force?: boolean }> = [];
 let upgradePluginCalls: UpgradePluginOptions[] = [];
+let catalogMatches: PluginSearchMatch[] = [];
+let catalogError: Error | null = null;
 
 /**
  * Queued daemon IPC responses. The default (empty queue) is a transport
@@ -159,6 +162,15 @@ mock.module("../../lib/install-from-platform.js", () => ({
   },
 }));
 
+mock.module("../../lib/plugin-catalog-cache.js", () => ({
+  getPluginCatalog: async () => {
+    if (catalogError) {
+      throw catalogError;
+    }
+    return { ref: "main", matches: catalogMatches };
+  },
+}));
+
 mock.module("../../lib/inspect-plugin.js", () => ({
   ...realInspect,
   inspectPlugin: async () => {
@@ -257,6 +269,8 @@ beforeEach(() => {
   installPluginCalls = [];
   platformInstallCalls = [];
   upgradePluginCalls = [];
+  catalogMatches = [];
+  catalogError = null;
   ipcResults = [];
   inspectResult = null;
   installTarget = null;
@@ -433,6 +447,44 @@ describe("plugins install - declared-schedules consent", () => {
     expect(r.stdout).toContain('Plugin "caveman" declares 2 schedules:');
     expect(r.exitCode).toBe(0);
   });
+
+  test("a local catalog source bypasses the platform installer", async () => {
+    catalogMatches = [
+      {
+        name: "fathom",
+        path: "local:plugins/mcp-catalog/fathom@1.0.0",
+        category: "productivity",
+        source: {
+          kind: "local",
+          path: "plugins/mcp-catalog/fathom",
+          version: "1.0.0",
+        },
+      },
+    ];
+
+    const r = await runCommand(["plugins", "install", "fathom"]);
+
+    expect(platformInstallCalls).toHaveLength(0);
+    expect(installPluginCalls).toHaveLength(1);
+    expect(installPluginCalls[0]?.trustedSource).toEqual({
+      kind: "local",
+      path: "plugins/mcp-catalog/fathom",
+      version: "1.0.0",
+    });
+    expect(r.exitCode).toBe(0);
+  });
+
+  test("falls back to the platform installer when catalog discovery fails", async () => {
+    catalogError = new Error("catalog unavailable");
+
+    const r = await runCommand(["plugins", "install", "example"]);
+
+    expect(installPluginCalls).toHaveLength(0);
+    expect(platformInstallCalls).toEqual([
+      { name: "example", force: undefined },
+    ]);
+    expect(r.exitCode).toBe(0);
+  });
 });
 
 describe("plugins upgrade - declared-schedules consent (local fallback)", () => {
@@ -701,6 +753,39 @@ describe("plugins inspect - schedules surface", () => {
     expect(r.stdout).toContain("weekly  RRULE:FREQ=WEEKLY;BYDAY=MO  (execute)");
     expect(r.exitCode).toBe(0);
   });
+
+  test("renders a bundled package location without a GitHub URL", async () => {
+    inspectResult = {
+      ...inspectionWithSurfaces({
+        skills: [],
+        hooks: [],
+        tools: [],
+        schedules: [],
+      }),
+      installed: false,
+      status: "not-installed",
+      local: null,
+      remote: {
+        kind: "local",
+        repo: "",
+        path: "plugins/mcp-catalog/fathom",
+        commit: "1.0.0",
+        committedAt: null,
+        description: null,
+        homepage: null,
+        license: null,
+        category: "productivity",
+        marketplaceRef: "main",
+        version: "1.0.0",
+      },
+    };
+
+    const r = await runCommand(["plugins", "inspect", "fathom"]);
+
+    expect(r.stdout).toContain("bundled:plugins/mcp-catalog/fathom");
+    expect(r.stdout).not.toContain("https://github.com//");
+    expect(r.exitCode).toBe(0);
+  });
 });
 
 describe("plugins install - setup skill hint", () => {

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

@@ -0,0 +1,19 @@
+import { describe, expect, test } from "bun:test";
+
+import { roadmapHelp } from "../roadmap.help.js";
+
+const DISCORD_URL = "https://vellum.ai/community";
+
+describe("roadmap help is feature-proposal-only", () => {
+  test("top-level help describes feature proposals and routes bugs to Discord", () => {
+    const description = roadmapHelp.description;
+    const helpText = roadmapHelp.helpText ?? "";
+    const combined = `${description}\n${helpText}`.toLowerCase();
+
+    expect(combined).toMatch(/feature proposals?/);
+    expect(description.split(DISCORD_URL)).toHaveLength(2);
+    expect(helpText).toContain(DISCORD_URL);
+    expect(combined).toContain("instruct the user");
+    expect(combined).not.toMatch(/support@|github\.com|share feedback/);
+  });
+});

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

@@ -380,6 +380,7 @@ describe("schedules get", () => {
     mode: "execute",
     status: "active",
     routingIntent: "all_channels",
+    quiet: false,
     reuseConversation: false,
     wakeConversationId: null,
     isOneShot: false,
@@ -436,9 +437,22 @@ describe("schedules get", () => {
     expect(output).toContain("Every 30 minutes (UTC)");
     expect(output).toContain("run heartbeat");
     expect(output).toContain("all_channels");
+    expect(output).toMatch(/Quiet:\s+no/);
     expect(output).toContain("conv-abc");
   });
 
+  test("prints Quiet: yes when the schedule suppresses completion notifications", async () => {
+    mockIpcResult = {
+      ok: true,
+      result: { schedule: { ...scheduleFixture, quiet: true } },
+    };
+
+    const { exitCode } = await runCommand(["schedules", "get", "schedule-1"]);
+
+    expect(exitCode).toBe(0);
+    expect(logLines.join("\n")).toMatch(/Quiet:\s+yes/);
+  });
+
   test("emits JSON result when --json is set", async () => {
     mockIpcResult = { ok: true, result: { schedule: scheduleFixture } };
 

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

@@ -4,25 +4,30 @@ import type { CliCommandHelp } from "../lib/cli-command-help.js";
 
 export const appsHelp: CliCommandHelp = {
   name: "apps",
-  description: "Inspect apps and their on-disk source",
+  description: "List, inspect, and compile apps",
   helpText: `
 Apps are mini-applications the assistant can surface. Each has a name and a
 source directory holding its HTML/TSX definition, pages, and records.
 
 Apps come from two places, distinguished by their source path:
-  workspace   User-created apps under the workspace apps directory
-              (~/.vellum/apps/<slug>/).
+  workspace   User-created apps under the workspace apps directory.
   plugin      Apps bundled by an installed plugin, each a directory under
-              ~/.vellum/plugins/<name>/apps/<app>/. Stray directories without
-              a plugin package.json, and disabled plugins, contribute nothing.
+              the plugin's apps/ folder. Stray directories without a plugin
+              package.json, and disabled plugins, contribute nothing.
 
-This surface is read-only. Workspace apps are created, edited, and deleted
-through the app-builder skill and its tools (app-create, app-update,
-app-delete); plugin apps are owned by their plugin.
+Create and delete workspace apps through the app-builder skill and its tools
+(app_create, app_delete). This command lists apps, inspects whether source
+has changed since the last compile, and compiles an app once you are done
+editing. File edits do not compile on their own.
+
+list and inspect read the workspace directly (the assistant does not need to
+be running). refresh compiles inside the running assistant so open surfaces
+pick up the new build, including plugin apps with local source changes.
 
 Examples:
   $ assistant apps list
-  $ assistant apps list --json`,
+  $ assistant apps inspect Budget
+  $ assistant apps refresh Budget`,
   subcommands: [
     {
       name: "list",
@@ -31,10 +36,10 @@ Examples:
         { flags: "--json", description: "Machine-readable JSON output" },
       ],
       helpText: `
-Lists every app with its name and the absolute path to its source directory —
-the path itself shows whether the app is a workspace app or bundled by a plugin
-(~/.vellum/plugins/<name>/apps/...). Workspace apps are listed first, then
-plugin-bundled apps; both are sorted by name.
+Lists every app with its name and the absolute path to its source directory.
+The path itself shows whether the app is a workspace app or bundled by a
+plugin. Workspace apps are listed first, then plugin-bundled apps; both are
+sorted by name.
 
 Pass --json for machine-readable output.
 
@@ -42,5 +47,54 @@ Examples:
   $ assistant apps list
   $ assistant apps list --json`,
     },
+    {
+      name: "inspect",
+      args: "<app_name>",
+      description:
+        "Show whether an app's source has changed since the last compile",
+      options: [
+        { flags: "--json", description: "Machine-readable JSON output" },
+      ],
+      helpText: `
+Arguments:
+  app_name   App display name, directory slug, or id. Run 'assistant apps list'
+             to see available apps.
+
+Compares the on-disk source against the fingerprint recorded in dist/ at the
+last successful compile. Reports clean (no changes), stale (source drifted),
+never compiled, or unknown baseline (compiled before fingerprints existed).
+
+Does not compile. Use 'assistant apps refresh <app_name>' after inspect when
+source has changed.
+
+Examples:
+  $ assistant apps inspect Budget
+  $ assistant apps inspect Budget --json`,
+    },
+    {
+      name: "refresh",
+      args: "<app_name>",
+      description:
+        "Compile an app and refresh open surfaces. Requires a running assistant",
+      options: [
+        { flags: "--json", description: "Machine-readable JSON output" },
+      ],
+      helpText: `
+Arguments:
+  app_name   App display name, directory slug, or id. Run 'assistant apps list'
+             to see available apps.
+
+Compiles src/ into dist/ inside the running assistant, then refreshes any
+open surfaces and published deployments. Call this once after a batch of
+edits, not after every file write. Workspace and plugin apps are both
+accepted so local plugin source changes can be compiled without waiting
+for the plugin watcher.
+
+The assistant must be running.
+
+Examples:
+  $ assistant apps refresh Budget
+  $ assistant apps refresh Budget --json`,
+    },
   ],
 };

package/src/cli/commands/apps.ts

@@ -1,8 +1,13 @@
 import type { Command } from "commander";
 
+import {
+  cliIpcCall,
+  exitCodeFromIpcResult,
+} from "../../ipc/cli-client.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 { appsHelp } from "./apps.help.js";
 
 interface AppListEntry {
@@ -10,6 +15,36 @@ interface AppListEntry {
   source: string;
 }
 
+interface AppsRefreshResponse {
+  ok: true;
+  appId: string;
+  name: string;
+  compiled: boolean;
+  compile_duration_ms: number;
+  compile_errors?: Array<{
+    text: string;
+    location?: { file: string; line: number; column: number };
+  }>;
+  compile_warnings?: Array<{
+    text: string;
+    location?: { file: string; line: number; column: number };
+  }>;
+}
+
+function refreshHint(appId: string): string {
+  return `Run 'assistant apps refresh ${appId}' to compile.`;
+}
+
+function formatDiagnostic(diag: {
+  text: string;
+  location?: { file: string; line: number; column: number };
+}): string {
+  if (!diag.location) {
+    return diag.text;
+  }
+  return `${diag.location.file}:${diag.location.line}: ${diag.text}`;
+}
+
 export function registerAppsCommand(program: Command): void {
   registerCommand(program, {
     name: appsHelp.name,
@@ -46,6 +81,154 @@ export function registerAppsCommand(program: Command): void {
           log.info(`  ${e.name.padEnd(nameWidth)}  ${e.source}`);
         }
       });
+
+      subcommand(apps, "inspect").action(
+        async (appName: string, opts: { json?: boolean }, cmd: Command) => {
+          const { resolveAppQuery, appNotFoundMessage, appAmbiguousMessage } =
+            await import("../../apps/resolve-app.js");
+          const { inspectAppSource } = await import(
+            "../../apps/source-fingerprint.js"
+          );
+
+          const resolved = resolveAppQuery(appName);
+          if (!resolved.ok) {
+            const message =
+              resolved.reason === "ambiguous"
+                ? appAmbiguousMessage(resolved.query, resolved.matches)
+                : appNotFoundMessage(resolved.query);
+            writeError(cmd, message);
+            process.exitCode = 1;
+            return;
+          }
+
+          const { app } = resolved;
+          const inspect = inspectAppSource(app.sourcePath);
+          const origin =
+            app.origin.kind === "plugin"
+              ? { kind: "plugin" as const, plugin: app.origin.pluginName }
+              : { kind: "workspace" as const };
+
+          if (opts.json || shouldOutputJson(cmd)) {
+            writeOutput(cmd, {
+              ok: true,
+              app: {
+                id: app.id,
+                name: app.name,
+                source: app.sourcePath,
+                origin,
+              },
+              compile: inspect,
+            });
+            return;
+          }
+
+          const originLabel =
+            origin.kind === "plugin"
+              ? `plugin ${origin.plugin}`
+              : "workspace";
+          log.info(`App: ${app.name} (${originLabel})`);
+          log.info(`Id: ${app.id}`);
+          log.info(`Source: ${app.sourcePath}`);
+
+          if (inspect.status === "clean") {
+            const when = inspect.compiledAt
+              ? ` (compiled ${inspect.compiledAt})`
+              : "";
+            log.info(`Compile: up to date${when}`);
+            return;
+          }
+          if (inspect.status === "never_compiled") {
+            log.info("Compile: never compiled");
+            log.info(refreshHint(app.id));
+            return;
+          }
+          if (inspect.status === "unknown_baseline") {
+            log.info(
+              "Compile: compiled, but no source fingerprint is recorded.",
+            );
+            log.info(
+              `Run 'assistant apps refresh ${app.id}' to record one and rebuild.`,
+            );
+            return;
+          }
+
+          const when = inspect.compiledAt
+            ? ` (last compiled ${inspect.compiledAt})`
+            : "";
+          log.info(`Compile: source changed since last compile${when}`);
+          if (inspect.modified.length > 0) {
+            log.info("Modified:");
+            for (const path of inspect.modified) {
+              log.info(`  ${path}`);
+            }
+          }
+          if (inspect.added.length > 0) {
+            log.info("Added:");
+            for (const path of inspect.added) {
+              log.info(`  ${path}`);
+            }
+          }
+          if (inspect.removed.length > 0) {
+            log.info("Removed:");
+            for (const path of inspect.removed) {
+              log.info(`  ${path}`);
+            }
+          }
+          log.info(refreshHint(app.id));
+        },
+      );
+
+      subcommand(apps, "refresh").action(
+        async (appName: string, opts: { json?: boolean }, cmd: Command) => {
+          const { resolveAppQuery, appNotFoundMessage, appAmbiguousMessage } =
+            await import("../../apps/resolve-app.js");
+
+          const resolved = resolveAppQuery(appName);
+          if (!resolved.ok) {
+            const message =
+              resolved.reason === "ambiguous"
+                ? appAmbiguousMessage(resolved.query, resolved.matches)
+                : appNotFoundMessage(resolved.query);
+            writeError(cmd, message);
+            process.exitCode = 1;
+            return;
+          }
+
+          const result = await cliIpcCall<AppsRefreshResponse>("apps_refresh", {
+            pathParams: { id: resolved.app.id },
+          });
+
+          if (!result.ok || !result.result) {
+            writeError(cmd, result.error ?? "Refresh failed");
+            process.exitCode = exitCodeFromIpcResult(result);
+            return;
+          }
+
+          const payload = result.result;
+          if (opts.json || shouldOutputJson(cmd)) {
+            writeOutput(cmd, payload);
+            if (!payload.compiled) {
+              process.exitCode = 1;
+            }
+            return;
+          }
+
+          if (!payload.compiled) {
+            log.error(
+              `Compile failed for "${payload.name}" (${payload.compile_duration_ms}ms).`,
+            );
+            for (const diag of payload.compile_errors ?? []) {
+              log.error(`  ${formatDiagnostic(diag)}`);
+            }
+            process.exitCode = 1;
+            return;
+          }
+
+          log.info(
+            `Compiled "${payload.name}" in ${payload.compile_duration_ms}ms.`,
+          );
+        },
+      );
     },
   });
 }

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

@@ -6,7 +6,7 @@ export const bashHelp: CliCommandHelp = {
   name: "bash",
   args: "<command>",
   description:
-    "Execute a shell command through the assistant process for debugging",
+    "Execute a shell command with the same sanitized environment as the bash tool",
   options: [
     {
       flags: "-t, --timeout <ms>",
@@ -15,24 +15,20 @@ export const bashHelp: CliCommandHelp = {
     },
   ],
   helpText: `
-Sends a shell command to the running assistant for execution via the IPC
-socket. The assistant spawns the command in its own process environment and
-returns stdout, stderr, and the exit code.
-
-This is a developer debugging tool for inspecting how the assistant invokes and
-observes shell commands. The command runs with the assistant's environment, working
-directory, and process context — not the caller's shell.
-
-Requires the assistant to be running with VELLUM_DEBUG=1. When debug mode is off
-(the default), the assistant returns an error immediately.
+Spawns the command with the same sanitized environment, working directory,
+and platform shell the bash tool uses for tool-call subprocesses. CES
+bootstrap and workspace paths are forwarded so children can reach CES over
+IPC. CES HTTP credentials are also forwarded. The command does not go through
+the assistant HTTP or IPC
+API, and does not require a running assistant process.
 
 Arguments:
   command   The shell command string to execute (e.g. "echo hello", "ls -la").
-            Runs in bash via \`bash -c\` in the assistant's process environment.
+            Runs via the same platform shell invocation the bash tool uses.
 
 Examples:
   $ assistant bash "echo hello"
   $ assistant bash "which node"
   $ assistant bash "env | grep PATH" --timeout 10000
-  $ assistant bash "ls -la"`,
+  $ assistant bash "assistant oauth request --provider outlook --json https://graph.microsoft.com/v1.0/me"`,
 };