@vellumai/assistant 0.11.2 → 0.11.3-dev.202608080427.92f668a

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

@@ -1,7 +1,31 @@
-/** Declarative help for the `assistant stt` command. */
+/**
+ * Declarative help for the `assistant stt` command.
+ *
+ * The advertised provider list is derived from the STT provider catalog, the
+ * single source of truth for which providers exist and which boundaries they
+ * serve, so the help cannot drift from what the daemon actually accepts.
+ */
 
+// provider-catalog is an execution-free data leaf (a literal map behind
+// type-only imports, no adapter or credential graph), consumed synchronously
+// to derive this module's constant. Pure data from pure data, so a lazy
+// `import()` has nothing to defer.
+// eslint-disable-next-line cli/no-daemon-internals
+import {
+  listProviderIds,
+  supportsBoundary,
+} from "../../providers/speech-to-text/provider-catalog.js";
 import type { CliCommandHelp } from "../lib/cli-command-help.js";
 
+/**
+ * `stt transcribe` runs the `daemon-batch` boundary, so streaming-only
+ * providers are omitted: naming one would advertise a configuration that
+ * fails on every file.
+ */
+const batchProviders = listProviderIds()
+  .filter((id) => supportsBoundary(id, "daemon-batch"))
+  .join(", ");
+
 export const sttHelp: CliCommandHelp = {
   name: "stt",
   description: "Speech-to-text operations",
@@ -11,7 +35,8 @@ audio and video files. The provider is set via:
 
   $ assistant config set services.stt.provider <provider>
 
-Supported providers: openai-whisper, deepgram, google-gemini, xai.
+Supported providers: ${batchProviders}.
+Streaming-only providers serve live speech and cannot transcribe files.
 
 Examples:
   $ assistant stt transcribe --file /path/to/meeting.wav

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

@@ -28,6 +28,7 @@ Examples:
   $ assistant tools list --json
   $ assistant tools list --conversation conv_abc123
   $ assistant tools list --agent researcher
+  $ assistant tools list --agent "a staff security engineer"
   $ assistant tools list --agent subagent_abc123 --json
   $ assistant tools run web_fetch --input '{"url":"https://example.com"}'
   $ assistant tools run file_read --input-file args.json
@@ -39,7 +40,8 @@ Examples:
       options: [
         {
           flags: "--json",
-          description: "Emit machine-readable JSON instead of a table",
+          description:
+            "Emit the tool array as machine-readable JSON instead of a table; a note about how --agent resolved goes to stderr so stdout stays pipeable",
         },
         {
           flags: "--conversation <id>",
@@ -49,7 +51,7 @@ Examples:
         {
           flags: "--agent <role|subagent-id>",
           description:
-            "Show tools available to a subagent role (general, researcher, coder, planner, investigator, advisor) or a live subagent by its id. Simulates the subagent tool projection: role allowlist + subagent-only gating.",
+            "Show tools available to a subagent role (researcher, builder, advisor) or a live subagent by its id. Reads the value the way a spawn reads its role: an older name (planner, investigator, coder, general) lists its successor's toolset, and any other text is a persona that lists the researcher toolset. The output names what the value resolved to. Simulates the subagent tool projection: role allowlist + subagent-only gating.",
         },
       ],
     },

package/src/cli/commands/tools.ts

@@ -24,10 +24,40 @@ interface ToolListEntry {
   source: string;
 }
 
+/** How the daemon read an `--agent` value, when it read one as a role string. */
+interface ResolvedAgentInfo {
+  requested: string;
+  role: string;
+  alias?: string;
+  persona?: string;
+}
+
 interface ToolsGetResponse {
   names: string[];
   schemas: Record<string, unknown>;
   tools: ToolListEntry[];
+  agent?: ResolvedAgentInfo;
+}
+
+/**
+ * What to report when `--agent` landed on a different subagent type than the
+ * value asked for, or `undefined` when it named a type outright (or resolved a
+ * live subagent id, which carries no resolution block).
+ *
+ * A listing that came from an older name or from a persona fallback looks
+ * exactly like one asked for by name, so without this line a typo reads as a
+ * researcher's tool surface with nothing saying the value was not a type. It
+ * goes to stderr so it reaches a person without entering the `--json` stream,
+ * whose stdout contract is the tool array on its own.
+ */
+function agentResolutionLine(agent?: ResolvedAgentInfo): string | undefined {
+  if (agent?.alias) {
+    return `"${agent.requested}" is an older name for "${agent.role}"; listing the ${agent.role} toolset.`;
+  }
+  if (agent?.persona) {
+    return `"${agent.requested}" is not a subagent type, so it is carried as a persona and runs as a researcher; listing the researcher toolset.`;
+  }
+  return undefined;
 }
 
 export function registerToolsCommand(program: Command): void {
@@ -61,12 +91,20 @@ export function registerToolsCommand(program: Command): void {
             }
 
             const tools = response.result?.tools ?? [];
+            const resolutionLine = agentResolutionLine(response.result?.agent);
 
             if (opts.json) {
+              if (resolutionLine) {
+                console.error(resolutionLine);
+              }
               console.log(JSON.stringify(tools, null, 2));
               return;
             }
 
+            if (resolutionLine) {
+              console.log(`${resolutionLine}\n`);
+            }
+
             if (tools.length === 0) {
               console.log("No tools registered.");
               return;

package/src/cli/lib/__tests__/inspect-plugin.test.ts

@@ -405,6 +405,7 @@ describe("inspectPlugin", () => {
       skills: ["first-skill", "second-skill"],
       hooks: ["init", "post-model-call"],
       tools: [],
+      schedules: [],
     });
   });
 

package/src/cli/lib/__tests__/install-from-github.test.ts

@@ -28,6 +28,7 @@ import {
   installPlugin,
   InvalidPluginNameError,
   PluginAlreadyInstalledError,
+  PluginInstallDeclinedError,
   PluginNotFoundError,
   PluginPostinstallError,
   PluginSourceUnavailableError,
@@ -362,6 +363,84 @@ describe("installPlugin — install lifecycle", () => {
   });
 });
 
+describe("installPlugin - staged-install consent", () => {
+  let ws: string;
+  let pluginsDir: string;
+
+  beforeEach(() => {
+    ws = mkdtempSync(join(tmpdir(), "vellum-plugins-consent-"));
+    pluginsDir = join(ws, "plugins");
+    mkdirSync(pluginsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    rmSync(ws, { recursive: true, force: true });
+  });
+
+  const CLONE_TREE = {
+    "package.json": '{"name":"caveman"}',
+    "schedules/daily/config.json": '{"expression": "0 9 * * *"}',
+    "schedules/daily/index.md": "Do it.\n",
+  };
+
+  test("confirmStaged sees the staged tree before anything is finalized", async () => {
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({ tree: CLONE_TREE, commit: CAVEMAN_SHA });
+    const observed: Array<{ name: string; stagingDir: string }> = [];
+
+    const result = await installPlugin(
+      { name: "caveman", ref: "main" },
+      {
+        fetch,
+        runGit,
+        workspacePluginsDir: pluginsDir,
+        confirmStaged: async (staged) => {
+          observed.push(staged);
+          // The staged tree is fully materialized, but nothing has been
+          // swapped into the served plugins dir yet.
+          expect(
+            existsSync(join(staged.stagingDir, "schedules/daily/index.md")),
+          ).toBe(true);
+          expect(existsSync(join(pluginsDir, "caveman"))).toBe(false);
+          return true;
+        },
+      },
+    );
+
+    expect(observed.length).toBe(1);
+    expect(observed[0]!.name).toBe("caveman");
+    expect(result.target).toBe(join(pluginsDir, "caveman"));
+    expect(existsSync(join(result.target, "schedules/daily/index.md"))).toBe(
+      true,
+    );
+  });
+
+  test("declining aborts cleanly: no target, staging removed", async () => {
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const runGit = fakeGitRunner({ tree: CLONE_TREE, commit: CAVEMAN_SHA });
+    const stagingDirs: string[] = [];
+
+    await expect(
+      installPlugin(
+        { name: "caveman", ref: "main" },
+        {
+          fetch,
+          runGit,
+          workspacePluginsDir: pluginsDir,
+          confirmStaged: async (staged) => {
+            stagingDirs.push(staged.stagingDir);
+            return false;
+          },
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginInstallDeclinedError);
+
+    expect(existsSync(join(pluginsDir, "caveman"))).toBe(false);
+    expect(stagingDirs.length).toBe(1);
+    expect(existsSync(stagingDirs[0]!)).toBe(false);
+  });
+});
+
 describe("installPlugin — marketplace resolution", () => {
   let ws: string;
   let pluginsDir: string;

package/src/cli/lib/__tests__/install-from-platform.test.ts

@@ -15,7 +15,10 @@ import { gzipSync } from "node:zlib";
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 
 import type { FetchLike } from "../fetch-like.js";
-import { readInstallMeta } from "../install-from-github.js";
+import {
+  PluginInstallDeclinedError,
+  readInstallMeta,
+} from "../install-from-github.js";
 import {
   extractPluginTarball,
   installPluginFromPlatform,
@@ -306,6 +309,49 @@ describe("installPluginFromPlatform — integrity", () => {
   });
 });
 
+// ─── Staged-install consent ──────────────────────────────────────────────────
+
+describe("installPluginFromPlatform - staged-install consent", () => {
+  test("confirmStaged runs over the staged tree; declining leaves nothing behind", async () => {
+    const fetchFn = makeInstallFetch({
+      entries: [
+        { name: "plugin.json", content: '{"name":"reading-pal"}' },
+        {
+          name: "schedules/daily/config.json",
+          content: '{"expression": "0 9 * * *"}',
+        },
+        { name: "schedules/daily/index.md", content: "Do it.\n" },
+      ],
+    });
+    const stagingDirs: string[] = [];
+
+    await expect(
+      installPluginFromPlatform(
+        { name: "reading-pal" },
+        {
+          fetch: fetchFn,
+          platformBaseUrl: PLATFORM,
+          workspacePluginsDir: pluginsDir,
+          confirmStaged: async (staged) => {
+            stagingDirs.push(staged.stagingDir);
+            expect(
+              existsSync(
+                join(staged.stagingDir, "schedules", "daily", "index.md"),
+              ),
+            ).toBe(true);
+            expect(existsSync(join(pluginsDir, "reading-pal"))).toBe(false);
+            return false;
+          },
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginInstallDeclinedError);
+
+    expect(existsSync(join(pluginsDir, "reading-pal"))).toBe(false);
+    expect(stagingDirs.length).toBe(1);
+    expect(existsSync(stagingDirs[0]!)).toBe(false);
+  });
+});
+
 // ─── Path traversal ──────────────────────────────────────────────────────────
 
 describe("extractPluginTarball — path traversal", () => {

package/src/cli/lib/__tests__/plugin-surfaces.test.ts

@@ -2,9 +2,14 @@
  * Tests for {@link detectPluginSurfaces}.
  *
  * Surface detection is a pure walk of an installed plugin's on-disk tree, so
- * the fixtures materialize the `hooks/`, `tools/`, and `skills/` directory
- * conventions in a real temp dir and assert the derived listing matches what
- * the runtime loader / skills catalog would discover.
+ * the fixtures materialize the `hooks/`, `tools/`, `skills/`, and `schedules/`
+ * directory conventions in a real temp dir and assert the derived listing
+ * matches what the runtime loader / skills catalog would discover.
+ *
+ * The schedules walk only mirrors the daemon parser's structural refusals;
+ * it stays permissive beyond structure. In particular, `expression` validity
+ * is not checked CLI-side, so a schedule whose expression the daemon rejects
+ * is still listed.
  */
 
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
@@ -24,11 +29,16 @@ afterEach(() => {
   rmSync(pluginDir, { recursive: true, force: true });
 });
 
-/** Create `<pluginDir>/<rel>` with empty contents, making parents as needed. */
-function touch(rel: string): void {
+/** Create `<pluginDir>/<rel>` with the given contents, making parents as needed. */
+function touch(rel: string, content = ""): void {
   const path = join(pluginDir, rel);
   mkdirSync(join(path, ".."), { recursive: true });
-  writeFileSync(path, "");
+  writeFileSync(path, content);
+}
+
+/** A prompt body carrying YAML frontmatter, which `index.md` must not have. */
+function withFrontmatter(expression: string): string {
+  return `---\nexpression: "${expression}"\n---\nDo the thing.\n`;
 }
 
 describe("detectPluginSurfaces", () => {
@@ -106,6 +116,75 @@ describe("detectPluginSurfaces", () => {
     const surfaces = detectPluginSurfaces(pluginDir);
 
     // THEN every surface type is empty
-    expect(surfaces).toEqual({ skills: [], hooks: [], tools: [] });
+    expect(surfaces).toEqual({
+      skills: [],
+      hooks: [],
+      tools: [],
+      schedules: [],
+    });
+  });
+
+  test("lists declared schedules with cadence and mode for both entrypoints", () => {
+    // GIVEN two declaration directories, one per entrypoint kind
+    touch(
+      "schedules/cleanup/config.json",
+      '{"expression": "0 0 * * 0", "timezone": "UTC"}',
+    );
+    touch("schedules/cleanup/index.sh", "#!/bin/sh\necho hi\n");
+    touch("schedules/digest/config.json", '{"expression": "0 8 * * 1"}');
+    touch("schedules/digest/index.md", "Summarize the week.\n");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN each declaration reports its raw expression and entrypoint mode
+    expect(surfaces.schedules).toEqual([
+      { name: "cleanup", cadence: "0 0 * * 0", mode: "script" },
+      { name: "digest", cadence: "0 8 * * 1", mode: "execute" },
+    ]);
+  });
+
+  test("skips a markdown file sitting directly under schedules/", () => {
+    // GIVEN a flat declaration file, which is not a declaration form
+    touch("schedules/dupe.md", withFrontmatter("0 9 * * *"));
+    touch("schedules/keeper/config.json", '{"expression": "30 7 * * *"}');
+    touch("schedules/keeper/index.md", "body\n");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN only the declaration directory is listed
+    expect(surfaces.schedules).toEqual([
+      { name: "keeper", cadence: "30 7 * * *", mode: "execute" },
+    ]);
+  });
+
+  test("skips structurally malformed schedule declarations (frontmatter, entrypoint, config, body)", () => {
+    // GIVEN a directory with both entrypoints
+    touch("schedules/two-entries/config.json", '{"expression": "0 9 * * *"}');
+    touch("schedules/two-entries/index.md", "body\n");
+    touch("schedules/two-entries/index.sh", "#!/bin/sh\n");
+    // AND a directory with an unsupported entrypoint
+    touch("schedules/bad-entry/config.json", '{"expression": "0 9 * * *"}');
+    touch("schedules/bad-entry/index.py", "print()\n");
+    // AND a directory whose index.md carries frontmatter (config belongs in
+    // config.json)
+    touch(
+      "schedules/md-frontmatter/config.json",
+      '{"expression": "0 9 * * *"}',
+    );
+    touch("schedules/md-frontmatter/index.md", withFrontmatter("0 9 * * *"));
+    // AND a directory whose index.md prompt body is empty
+    touch("schedules/md-empty/config.json", '{"expression": "0 9 * * *"}');
+    touch("schedules/md-empty/index.md", "\n  \n");
+    // AND a directory missing its config.json
+    touch("schedules/no-config/index.md", "body\n");
+    // AND a directory whose config declares no expression
+    touch("schedules/no-expression/config.json", '{"timezone": "UTC"}');
+    touch("schedules/no-expression/index.md", "body\n");
+
+    // WHEN its surfaces are detected
+    // THEN none of them are listed
+    expect(detectPluginSurfaces(pluginDir).schedules).toEqual([]);
   });
 });

package/src/cli/lib/__tests__/upgrade-plugin.test.ts

@@ -24,6 +24,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import type { FetchLike } from "../fetch-like.js";
 import {
   type GitRunner,
+  PluginInstallDeclinedError,
   PluginNotFoundError,
   PluginSourceUnavailableError,
 } from "../install-from-github.js";
@@ -31,6 +32,7 @@ import { computeFingerprint } from "../plugin-fingerprint.js";
 import { PluginNotInstalledError } from "../uninstall-plugin.js";
 import {
   PluginMergeBaselineError,
+  PluginNotCuratedError,
   PluginNotUpgradableError,
   upgradePlugin,
 } from "../upgrade-plugin.js";
@@ -573,6 +575,44 @@ describe("upgradePlugin — direct GitHub-URL installs", () => {
     expect(calls[0]?.[0]).toBe("ls-remote");
   });
 
+  test("marketplaceOnly refuses the direct path instead of following the ref", async () => {
+    // GIVEN a direct install tracking `main` at SHA_A, absent from the
+    // marketplace, whose branch has advanced to SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A, ref: "main" });
+    const fetch = makeFetch({ manifest: undefined });
+    const calls: string[][] = [];
+    const runGit = directGitRunner({ main: SHA_B }, SHA_B, { calls });
+
+    // WHEN a caller that only accepts a curated pin asks for the upgrade
+    const upgrade = upgradePlugin(
+      { name: "level-up", marketplaceOnly: true },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it is refused, and the mutable ref is never even resolved
+    await expect(upgrade).rejects.toThrow(PluginNotCuratedError);
+    expect(calls).toEqual([]);
+    // AND the install stays exactly where it was
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("marketplaceOnly still upgrades a plugin the catalog claims", async () => {
+    // GIVEN an install the marketplace pins at SHA_B
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    // WHEN the same curated-only caller asks for the upgrade
+    const result = await upgradePlugin(
+      { name: "level-up", marketplaceOnly: true },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the flag is inert: the curated pin is taken as usual
+    expect(result.outcome).toBe("upgraded");
+    expect(result.toCommit).toBe(SHA_B);
+  });
+
   test("is a no-op when the recorded branch still points at the installed commit", async () => {
     // GIVEN a direct install tracking `main` at SHA_A
     installCopy(pluginsDir, "level-up", { commit: SHA_A, ref: "main" });
@@ -1033,3 +1073,124 @@ describe("upgradePlugin --strategy", () => {
     expect(installedFile("level-up", "conflict.txt")).toBe("ours\n");
   });
 });
+
+describe("upgradePlugin confirmStaged consent gate", () => {
+  test("overwrite: declining aborts and preserves the existing install", async () => {
+    // GIVEN an installed copy pinned to SHA_A with a newer marketplace pin
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+    const seen: Array<{ name: string; staged: boolean }> = [];
+
+    // WHEN the consent gate declines the staged upgrade
+    await expect(
+      upgradePlugin(
+        { name: "level-up" },
+        {
+          fetch,
+          runGit,
+          workspacePluginsDir: pluginsDir,
+          confirmStaged: async ({ name, stagingDir }) => {
+            seen.push({
+              name,
+              staged: existsSync(join(stagingDir, "package.json")),
+            });
+            return false;
+          },
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginInstallDeclinedError);
+
+    // THEN the gate saw the fully staged tree exactly once
+    expect(seen).toEqual([{ name: "level-up", staged: true }]);
+    // AND the live install still carries the old pin
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("overwrite: an accepting gate lets the upgrade proceed", async () => {
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = fakeGitRunner(SHA_B);
+
+    const result = await upgradePlugin(
+      { name: "level-up" },
+      {
+        fetch,
+        runGit,
+        workspacePluginsDir: pluginsDir,
+        confirmStaged: async () => true,
+      },
+    );
+
+    expect(result.outcome).toBe("upgraded");
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_B);
+  });
+
+  test("merge: the gate sees the merged tree; declining keeps the local install", async () => {
+    const PKG = '{"name":"level-up"}\n';
+    const base: Tree = { "package.json": PKG, "note.txt": "base\n" };
+    const ours: Tree = {
+      "package.json": PKG,
+      "note.txt": "base\n",
+      "local.txt": "mine\n",
+    };
+    const theirs: Tree = { "package.json": PKG, "note.txt": "upstream\n" };
+    installMergeCopy("level-up", ours, SHA_A, base);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: base, [SHA_B]: theirs });
+    let sawMerged = false;
+
+    await expect(
+      upgradePlugin(
+        { name: "level-up", strategy: "ours" },
+        {
+          fetch,
+          runGit,
+          workspacePluginsDir: pluginsDir,
+          confirmStaged: async ({ stagingDir }) => {
+            // The staged tree is the merged result: the upstream edit plus
+            // the surviving local addition.
+            sawMerged =
+              readFileSync(join(stagingDir, "note.txt"), "utf-8") ===
+                "upstream\n" && existsSync(join(stagingDir, "local.txt"));
+            return false;
+          },
+        },
+      ),
+    ).rejects.toBeInstanceOf(PluginInstallDeclinedError);
+
+    expect(sawMerged).toBe(true);
+    // The live install is untouched by the declined merge.
+    expect(installedFile("level-up", "note.txt")).toBe("base\n");
+    expect(sidecarCommit(pluginsDir, "level-up")).toBe(SHA_A);
+  });
+
+  test("dry runs and no-ops never invoke the gate", async () => {
+    installCopy(pluginsDir, "level-up", { commit: SHA_A });
+    const gate = async () => {
+      throw new Error("confirmStaged must not run without staging");
+    };
+
+    const dry = await upgradePlugin(
+      { name: "level-up", dryRun: true },
+      {
+        fetch: makeFetch({ manifest: manifestWith("level-up", SHA_B) }),
+        runGit: unusedGitRunner,
+        workspacePluginsDir: pluginsDir,
+        confirmStaged: gate,
+      },
+    );
+    expect(dry.outcome).toBe("would-upgrade");
+
+    const noop = await upgradePlugin(
+      { name: "level-up" },
+      {
+        fetch: makeFetch({ manifest: manifestWith("level-up", SHA_A) }),
+        runGit: unusedGitRunner,
+        workspacePluginsDir: pluginsDir,
+        confirmStaged: gate,
+      },
+    );
+    expect(noop.outcome).toBe("already-up-to-date");
+  });
+});