@vellumai/assistant 0.12.1 → 0.12.2-staging.1

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,19 @@ 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. Vault
+bearers such as CES_SERVICE_TOKEN are stripped; CES_LOCAL_SOCKET and workspace
+paths are 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"`,
 };

package/src/cli/commands/bash.ts

@@ -1,28 +1,19 @@
 /**
- * `assistant bash` — run a shell command in the assistant's process
- * environment (debug tool, requires VELLUM_DEBUG=1 on the daemon).
+ * `assistant bash` runs a shell command with the same sanitized environment
+ * the bash tool forwards to tool-call subprocesses.
  */
 
 import type { Command } from "commander";
 
-import { cliIpcCall } from "../../ipc/cli-client.js";
 import { applyCommandHelp, commandSpec } from "../lib/cli-command-help.js";
 import { registerCommand } from "../lib/register-command.js";
 import { log } from "../logger.js";
 import { bashHelp } from "./bash.help.js";
 
-interface DebugBashResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number | null;
-  timedOut: boolean;
-  error?: string;
-}
-
 export function registerBashCommand(program: Command): void {
   registerCommand(program, {
     name: commandSpec(bashHelp),
-    transport: "ipc",
+    transport: "local",
     description: bashHelp.description,
     build: (cmd) => {
       applyCommandHelp(cmd, bashHelp);
@@ -34,19 +25,10 @@ export function registerBashCommand(program: Command): void {
           return;
         }
 
-        const result = await cliIpcCall<DebugBashResult>(
-          "debug_bash",
-          { body: { command, timeoutMs } },
-          { timeoutMs: timeoutMs + 10_000 },
+        const { runSanitizedBash } = await import(
+          "../../tools/terminal/sanitized-bash.js"
         );
-
-        if (!result.ok) {
-          log.error(result.error ?? "Failed to reach the assistant.");
-          process.exitCode = 1;
-          return;
-        }
-
-        const data = result.result!;
+        const data = await runSanitizedBash(command, timeoutMs);
 
         if (data.error) {
           log.error(data.error);
@@ -69,7 +51,7 @@ export function registerBashCommand(program: Command): void {
         }
 
         if (data.timedOut) {
-          log.info(`Command timed out in assistant.`);
+          log.info("Command timed out.");
         }
 
         if (data.exitCode != null && data.exitCode !== 0) {

package/src/cli/commands/channels/__tests__/send.test.ts

@@ -0,0 +1,218 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// The command is a door onto the daemon's one send implementation, so what
+// matters is the request it hands the route and what it does with the
+// answer. IPC is stubbed to capture that request; the exit-code helper
+// stays real, so the tests assert the mapping that ships.
+
+const ipcCalls: Array<{
+  method: string;
+  params: Record<string, unknown>;
+  opts?: Record<string, unknown>;
+}> = [];
+let ipcResult: Record<string, unknown> = {
+  ok: true,
+  result: {
+    channel: "slack",
+    chatId: "C0123456789",
+    messageIds: ["1700000000.000100"],
+    lastMessageId: "1700000000.000100",
+    recordedIn: "conv-home",
+  },
+};
+
+const actualCliClient = await import("../../../../ipc/cli-client.js");
+mock.module("../../../../ipc/cli-client.js", () => ({
+  ...actualCliClient,
+  cliIpcCall: async (
+    method: string,
+    params: Record<string, unknown>,
+    opts?: Record<string, unknown>,
+  ) => {
+    ipcCalls.push({ method, params, ...(opts ? { opts } : {}) });
+    return ipcResult;
+  },
+}));
+
+// Imported after the mock is installed, so the command module under test
+// binds the stubbed IPC call rather than the real one.
+const { runCliCommand } = await import("../../__tests__/cli-test-harness.js");
+const { registerChannelsCommand } = await import("../index.js");
+
+beforeEach(() => {
+  ipcCalls.length = 0;
+  ipcResult = {
+    ok: true,
+    result: {
+      channel: "slack",
+      chatId: "C0123456789",
+      messageIds: ["1700000000.000100"],
+      lastMessageId: "1700000000.000100",
+      recordedIn: "conv-home",
+    },
+  };
+});
+
+// The shipped registration as-is: `send` declares its own `--json`, which is
+// why the program's global leaf-option pass skips it.
+function runSend(args: string[]) {
+  return runCliCommand(registerChannelsCommand, ["channels", "send", ...args]);
+}
+
+/** The body the command handed the route on its one call. */
+function sentBody(): Record<string, unknown> {
+  expect(ipcCalls).toHaveLength(1);
+  expect(ipcCalls[0]!.method).toBe("channels_send_post");
+  return ipcCalls[0]!.params.body as Record<string, unknown>;
+}
+
+describe("the request the command makes", () => {
+  test("names the chat and asks for the channel's rich rendering", async () => {
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "deploy is green",
+    ]);
+    expect(r.exitCode).toBe(0);
+    expect(sentBody()).toEqual({
+      channel: "slack",
+      target: { kind: "chat", chatId: "C0123456789" },
+      text: "deploy is green",
+      renderRichly: true,
+    });
+  });
+
+  test("carries a named thread as the target's thread", async () => {
+    await runSend([
+      "slack",
+      "C0123456789",
+      "--thread",
+      "1700000000.000001",
+      "--text",
+      "and the smoke tests passed",
+    ]);
+    expect(sentBody().target).toEqual({
+      kind: "chat",
+      chatId: "C0123456789",
+      threadId: "1700000000.000001",
+    });
+  });
+
+  test("--plain asks for the text verbatim", async () => {
+    await runSend(["telegram", "123456789", "--text", "morning", "--plain"]);
+    const body = sentBody();
+    expect(body.renderRichly).toBeUndefined();
+    expect(body.channel).toBe("telegram");
+  });
+
+  test("sends the text as the caller wrote it, whitespace included", async () => {
+    await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "  indented  ",
+      "--plain",
+    ]);
+    expect(sentBody().text).toBe("  indented  ");
+  });
+
+  test("waits longer than the IPC default, since the send itself retries", async () => {
+    await runSend(["slack", "C0123456789", "--text", "hi"]);
+    expect(ipcCalls[0]!.opts).toMatchObject({ timeoutMs: 120_000 });
+  });
+
+  test("refuses an empty text before it sends anything", async () => {
+    for (const args of [
+      ["slack", "C0123456789"],
+      ["slack", "C0123456789", "--text", "   "],
+    ]) {
+      ipcCalls.length = 0;
+      const r = await runSend(args);
+      expect(r.exitCode).toBe(1);
+      expect(r.stderr).toContain("--text is required");
+      expect(ipcCalls).toEqual([]);
+    }
+  });
+});
+
+describe("what the command reports", () => {
+  test("names where the post landed and the conversation it was recorded in", async () => {
+    const r = await runSend(["slack", "C0123456789", "--text", "hello"]);
+    expect(r.stdout).toContain("C0123456789");
+    expect(r.stdout).toContain("1700000000.000100");
+    expect(r.stdout).toContain("conv-home");
+  });
+
+  test("says so when the channel split the text", async () => {
+    ipcResult = {
+      ok: true,
+      result: {
+        channel: "telegram",
+        chatId: "123456789",
+        messageIds: ["10", "11", "12"],
+        lastMessageId: "12",
+      },
+    };
+    const r = await runSend(["telegram", "123456789", "--text", "a long one"]);
+    expect(r.stdout).toContain("3 posts");
+  });
+
+  test("--json answers with the route's own result", async () => {
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "hello",
+      "--json",
+    ]);
+    expect(JSON.parse(r.stdout)).toEqual({
+      channel: "slack",
+      chatId: "C0123456789",
+      messageIds: ["1700000000.000100"],
+      lastMessageId: "1700000000.000100",
+      recordedIn: "conv-home",
+    });
+  });
+
+  test("a refused send reports the route's reason and its exit code", async () => {
+    ipcResult = {
+      ok: false,
+      error: 'Channel "email" is not addressable',
+      statusCode: 400,
+    };
+    const r = await runSend(["email", "someone", "--text", "hello"]);
+    expect(r.exitCode).toBe(
+      actualCliClient.exitCodeFromIpcResult({ statusCode: 400 }),
+    );
+    expect(r.stderr).toContain("not addressable");
+  });
+
+  test("a timeout is reported as an unknown outcome, not a failure to retry", async () => {
+    ipcResult = { ok: false, error: "Request timed out", timedOut: true };
+    const r = await runSend(["slack", "C0123456789", "--text", "hello"]);
+    expect(r.stderr).toContain("may still be in flight");
+    expect(r.stderr).toContain("before sending again");
+    expect(r.stderr).not.toContain("The send failed");
+  });
+
+  test("a refusal in --json mode is a JSON error envelope", async () => {
+    ipcResult = {
+      ok: false,
+      error: 'Channel "slack" did not acknowledge the send',
+      statusCode: 502,
+    };
+    const r = await runSend([
+      "slack",
+      "C0123456789",
+      "--text",
+      "hello",
+      "--json",
+    ]);
+    expect(JSON.parse(r.stdout)).toEqual({
+      ok: false,
+      error: 'Channel "slack" did not acknowledge the send',
+    });
+    expect(r.exitCode).toBe(3);
+  });
+});