@vellumai/assistant 0.11.2 → 0.11.3-staging.2

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";
@@ -1033,3 +1034,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");
+  });
+});

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

@@ -154,6 +154,20 @@ export interface InstallPluginOptions {
   readonly trustedSource?: PluginFetchSource;
 }
 
+/**
+ * Consent gate invoked after the plugin tree is fully staged and before it is
+ * finalized (dependencies installed, provenance recorded, swapped live). The
+ * caller inspects the staged tree to see what the plugin declares (e.g.
+ * schedules) and asks the user. Returning `false` aborts the install: the
+ * staging directory is removed, nothing is swapped, and
+ * {@link PluginInstallDeclinedError} is thrown.
+ */
+export type ConfirmStagedInstall = (staged: {
+  readonly name: string;
+  /** Absolute path of the fully materialized staging directory. */
+  readonly stagingDir: string;
+}) => Promise<boolean>;
+
 /** Dependencies injected by the caller. */
 export interface InstallPluginDeps {
   /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
@@ -168,6 +182,8 @@ export interface InstallPluginDeps {
   readonly runInstallDeps?: DependencyInstaller;
   /** Forwarded to {@link finalizeStagedInstall}; see {@link FinalizeStagedInstallParams.beforeSwap}. */
   readonly beforeSwap?: () => Promise<void>;
+  /** Consent gate between staging and finalize; see {@link ConfirmStagedInstall}. */
+  readonly confirmStaged?: ConfirmStagedInstall;
 }
 
 /** Successful install result. */
@@ -214,6 +230,19 @@ export class PluginPostinstallError extends Error {
   }
 }
 
+/**
+ * The caller's {@link ConfirmStagedInstall} gate declined the staged install.
+ * Nothing was installed and the staging directory was removed. The caller that
+ * supplied the gate owns the user-facing messaging, so this error signals the
+ * outcome rather than something to report as a failure.
+ */
+export class PluginInstallDeclinedError extends Error {
+  constructor(pluginName: string) {
+    super(`Install of "${pluginName}" was declined.`);
+    this.name = "PluginInstallDeclinedError";
+  }
+}
+
 /** A plugin with the same name is already installed and `--force` was not passed. */
 export class PluginAlreadyInstalledError extends Error {
   constructor(
@@ -503,6 +532,8 @@ export async function installPlugin(
     throw new PluginNotFoundError(name, ref, sourceLabel(effectiveSource));
   }
 
+  await confirmStagedOrAbort(name, stagingDir, deps.confirmStaged);
+
   await finalizeStagedInstall(stagingDir, {
     name,
     source: effectiveSource,
@@ -517,6 +548,36 @@ export async function installPlugin(
   return { name, target, fileCount, ref, commit, committedAt };
 }
 
+/**
+ * Run the caller's {@link ConfirmStagedInstall} gate over the staged tree. A
+ * decline (or a gate that throws) removes the staging directory so no partial
+ * install is left behind; a decline then surfaces as
+ * {@link PluginInstallDeclinedError}. A no-op when no gate was supplied.
+ *
+ * Shared by {@link installPlugin} and the platform-endpoint install so both
+ * abort a declined install the same way.
+ */
+export async function confirmStagedOrAbort(
+  name: string,
+  stagingDir: string,
+  confirmStaged: ConfirmStagedInstall | undefined,
+): Promise<void> {
+  if (!confirmStaged) {
+    return;
+  }
+  let confirmed = false;
+  try {
+    confirmed = await confirmStaged({ name, stagingDir });
+  } finally {
+    if (!confirmed) {
+      rmSync(stagingDir, { recursive: true, force: true });
+    }
+  }
+  if (!confirmed) {
+    throw new PluginInstallDeclinedError(name);
+  }
+}
+
 /** Inputs for {@link finalizeStagedInstall}. */
 export interface FinalizeStagedInstallParams {
   readonly name: string;

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

@@ -33,6 +33,8 @@ import { getWorkspacePluginsDir } from "../../util/platform.js";
 import { APP_VERSION } from "../../version.js";
 import type { FetchLike } from "./fetch-like.js";
 import {
+  type ConfirmStagedInstall,
+  confirmStagedOrAbort,
   finalizeStagedInstall,
   type InstallPluginResult,
   PluginAlreadyInstalledError,
@@ -123,6 +125,8 @@ export interface InstallFromPlatformDeps {
   readonly maxAttempts?: number;
   /** Sleep between retries. Injected so tests don't wait real time. */
   readonly sleep?: (ms: number) => Promise<void>;
+  /** Consent gate between staging and finalize; see {@link ConfirmStagedInstall}. */
+  readonly confirmStaged?: ConfirmStagedInstall;
 }
 
 /** Total attempts (initial + retries) for a transient upstream status. */
@@ -194,6 +198,8 @@ export async function installPluginFromPlatform(
     throw new PluginNotFoundError(name, meta.ref ?? "", meta.repo ?? name);
   }
 
+  await confirmStagedOrAbort(name, stagingDir, deps.confirmStaged);
+
   // Record provenance for future update/version UX. The endpoint re-roots the
   // tarball to the plugin root, so the recorded ref is the pinned commit and
   // the ETag documents exactly which bytes were verified.
@@ -223,7 +229,7 @@ export async function installPluginFromPlatform(
  */
 export async function installPluginViaPlatform(
   opts: { name: string; force?: boolean; conversationId?: string },
-  deps: { fetch: FetchLike },
+  deps: { fetch: FetchLike; confirmStaged?: ConfirmStagedInstall },
 ): Promise<InstallPluginResult> {
   const platformBaseUrl = getPlatformBaseUrl();
   const apiKey = await resolveAssistantApiKey();
@@ -237,7 +243,12 @@ export async function installPluginViaPlatform(
       ...(opts.conversationId ? { conversationId: opts.conversationId } : {}),
       assistantVersion: APP_VERSION,
     },
-    { fetch: deps.fetch, platformBaseUrl, ...(apiKey ? { apiKey } : {}) },
+    {
+      fetch: deps.fetch,
+      platformBaseUrl,
+      ...(apiKey ? { apiKey } : {}),
+      ...(deps.confirmStaged ? { confirmStaged: deps.confirmStaged } : {}),
+    },
   );
 }