@vellumai/assistant 0.9.0-dev.202606191950.a2e5513 → 0.9.0-dev.202606192132.caa886f

package/openapi.yaml

@@ -20359,6 +20359,67 @@ paths:
             install-time baseline cannot be reconstructed.
         "503":
           description: The plugin source (GitHub) was temporarily unavailable; the upgrade is retryable.
+  /v1/plugins/{name}/versions:
+    get:
+      operationId: plugins_by_name_versions_get
+      summary: List a plugin's reviewed marketplace pins
+      description:
+        Report the distinct marketplace pins a plugin has been promoted to over time, newest first (the first entry
+        is the current pin), capped at `limit` (default 5). The curated `marketplace.json` stores only the current pin,
+        so this is reconstructed from the manifest's own commit history on the default branch — every entry is therefore
+        a reviewed, known-good revision. Pair with `POST /v1/plugins/install`'s `pin` field to roll a plugin back to an
+        older reviewed version. An unknown name (never in the manifest) returns an empty array, not 404.
+      tags:
+        - plugins
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Maximum number of pins to return (positive integer; default 5).
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    pin:
+                      type: string
+                      description: Plugin commit SHA pinned at this point in marketplace history.
+                    marketplaceCommit:
+                      type: string
+                      description: Marketplace-manifest commit to install this pin from (the newest commit carrying it).
+                    promotedAt:
+                      anyOf:
+                        - type: string
+                        - type: "null"
+                      description: ISO-8601 committer date (UTC) of the marketplace commit that promoted this pin; null when unreadable.
+                    current:
+                      type: boolean
+                      description: True for the pin currently active on the default branch.
+                  required:
+                    - pin
+                    - marketplaceCommit
+                    - promotedAt
+                    - current
+                  additionalProperties: false
+                description:
+                  Distinct marketplace pins a plugin has been promoted to, newest first; the first entry is the current pin.
+                  Empty when the plugin has no resolvable history.
+        "400":
+          description: The plugin name failed sanitization, or `limit` was not a positive integer.
+        "503":
+          description: The marketplace pin history could not be read from GitHub (rate-limited or upstream error); retryable.
   /v1/plugins/install:
     post:
       operationId: plugins_install_post
@@ -20385,6 +20446,13 @@ paths:
                 force:
                   description: Overwrite an existing install in place. Defaults to false.
                   type: boolean
+                pin:
+                  description:
+                    Install a specific reviewed marketplace pin (full commit SHA) instead of the current one. The pin is
+                    validated against the plugin's marketplace pin history (`GET /v1/plugins/:name/versions`) and
+                    installed from the marketplace revision that introduced it; an unreviewed SHA is rejected. Use this
+                    to roll a plugin back to an older reviewed version.
+                  type: string
               required:
                 - name
       responses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606191950.a2e5513",
+  "version": "0.9.0-dev.202606192132.caa886f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-skill-tools.test.ts

@@ -372,9 +372,7 @@ describe("projectSkillTools", () => {
       previouslyActiveSkillIds: sessionState,
     });
 
-    // Tool definitions are not sent to the LLM here — tools are invoked via
-    // skill_execute dispatch; weak-open-model first-class exposure resolves
-    // defs from the registry by name in createResolveToolsCallback.
+    // Tool definitions are no longer sent to the LLM — tools are invoked via skill_execute dispatch.
     expect(result.toolDefinitions).toEqual([]);
     expect(result.allowedToolNames).toEqual(
       new Set(["deploy_run", "deploy_status"]),

package/src/__tests__/secret-routes-platform-proxy.test.ts

@@ -12,7 +12,12 @@ let providerRefreshCalls = 0;
 const PLATFORM_BASE_URL = "https://platform.example.com";
 const ASSISTANT_API_KEY_PATH = credentialKey("vellum", "assistant_api_key");
 const PLATFORM_BASE_URL_PATH = credentialKey("vellum", "platform_base_url");
-const MANAGED_PROVIDERS = ["anthropic", "openai", "gemini", "fireworks"] as const;
+const MANAGED_PROVIDERS = [
+  "anthropic",
+  "openai",
+  "gemini",
+  "fireworks",
+] as const;
 
 let platformBaseUrlOverride: string | undefined;
 
@@ -116,6 +121,13 @@ mock.module("../util/logger.js", () => ({
     }),
 }));
 
+// `handleAddSecret` fires this detached when a managed-proxy credential lands —
+// a v2-memory side effect outside this suite's provider-registry scope. Stub it
+// to a no-op; its behavior is covered by memory-v2-startup.test.ts.
+mock.module("../daemon/memory-v2-startup.js", () => ({
+  maybeReseedCapabilitiesAfterManagedCredential: async () => {},
+}));
+
 import {
   getProviderRoutingSource,
   initializeProviders,
@@ -199,7 +211,9 @@ describe("secret routes managed proxy registry sync", () => {
   test("provider API key writes notify live-conversation refresh listeners", async () => {
     await addApiKey("fireworks", "fw-key");
 
-    expect(secureKeyStore[credentialKey("fireworks", "api_key")]).toBe("fw-key");
+    expect(secureKeyStore[credentialKey("fireworks", "api_key")]).toBe(
+      "fw-key",
+    );
     expect(providerRefreshCalls).toBe(1);
 
     await deleteApiKey("fireworks");

package/src/__tests__/skill-tool-factory.test.ts

@@ -255,24 +255,6 @@ describe("createSkillTool — unknown parameter validation", () => {
     expect(result.isError).toBe(false);
   });
 
-  test("strips the harness `activity` field before validation", async () => {
-    const hash = computeSkillVersionHash(tempDir);
-    const tool = createSkillTool(
-      makeEntry({ executor: "echo.ts" }),
-      tempDir,
-      hash,
-    );
-
-    // A first-class skill-tool call may carry `activity` (the harness progress
-    // field). It must not be rejected as an unknown parameter.
-    const result = await tool.execute(
-      { query: "hello", activity: "Doing the thing" },
-      makeContext(),
-    );
-
-    expect(result.isError).toBe(false);
-  });
-
   test("allows empty input when schema has no required fields", async () => {
     const hash = computeSkillVersionHash(tempDir);
     const tool = createSkillTool(

package/src/cli/commands/plugins.ts

@@ -24,12 +24,20 @@ import {
 import {
   DEFAULT_PLUGIN_REF,
   installPlugin,
+  type InstallPluginOptions,
   InvalidPluginNameError,
   PluginAlreadyInstalledError,
   PluginNotFoundError,
 } from "../lib/install-from-github.js";
 import { listInstalledPlugins } from "../lib/list-installed-plugins.js";
 import type { FingerprintComparison } from "../lib/plugin-fingerprint.js";
+import {
+  DEFAULT_PIN_HISTORY_LIMIT,
+  listPinHistory,
+  type PluginPinHistoryEntry,
+  PluginPinHistoryError,
+  resolvePinToMarketplaceCommit,
+} from "../lib/plugin-pin-history.js";
 import { registerCommand } from "../lib/register-command.js";
 import {
   InvalidSearchPatternError,
@@ -65,6 +73,9 @@ Examples:
   $ assistant plugins install example
   $ assistant plugins install example --force
   $ assistant plugins install example --ref my-feature-branch
+  $ assistant plugins versions example
+  $ assistant plugins versions example --json
+  $ assistant plugins install example --pin <sha> --force
   $ assistant plugins list
   $ assistant plugins list --json
   $ assistant plugins inspect example
@@ -90,19 +101,35 @@ Examples:
         .option("--force", "Overwrite an existing install")
         .option(
           "--ref <ref>",
-          `Git ref to fetch from (default: ${DEFAULT_PLUGIN_REF})`,
+          `Marketplace manifest revision to read the pin from (default: ${DEFAULT_PLUGIN_REF})`,
+        )
+        .option(
+          "--pin <sha>",
+          "Install a specific reviewed marketplace pin (full commit SHA); run `plugins versions <name>` to list them",
+        )
+        .option(
+          "--allow-unreviewed",
+          "With --pin, install a SHA that is not in the reviewed marketplace history (advanced; the curated adapter may not match)",
         )
         .action(
-          async (name: string, opts: { force?: boolean; ref?: string }) => {
+          async (
+            name: string,
+            opts: {
+              force?: boolean;
+              ref?: string;
+              pin?: string;
+              allowUnreviewed?: boolean;
+            },
+          ) => {
             try {
-              const result = await installPlugin(
-                {
-                  name,
-                  force: opts.force ?? false,
-                  ref: opts.ref ?? DEFAULT_PLUGIN_REF,
-                },
-                { fetch: globalThis.fetch.bind(globalThis) },
-              );
+              const installOpts = await resolveInstallOptions(name, opts);
+              if (installOpts === null) {
+                process.exitCode = 1;
+                return;
+              }
+              const result = await installPlugin(installOpts, {
+                fetch: globalThis.fetch.bind(globalThis),
+              });
               log.info(
                 {
                   name: result.name,
@@ -131,6 +158,14 @@ Examples:
                 process.exitCode = 1;
                 return;
               }
+              if (
+                err instanceof InvalidPluginNameError ||
+                err instanceof PluginPinHistoryError
+              ) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
               const message = err instanceof Error ? err.message : String(err);
               console.error(`Plugin install failed: ${message}`);
               process.exitCode = 1;
@@ -138,6 +173,61 @@ Examples:
           },
         );
 
+      plugins
+        .command("versions <name>")
+        .description(
+          "List the recent reviewed marketplace pins for a plugin, newest first. Install an older one with `plugins install <name> --pin <sha>`",
+        )
+        .option("--json", "Emit machine-readable JSON instead of a table")
+        .option(
+          "--limit <n>",
+          `Maximum number of pins to show (default: ${DEFAULT_PIN_HISTORY_LIMIT})`,
+        )
+        .action(
+          async (name: string, opts: { json?: boolean; limit?: string }) => {
+            let limit: number | undefined;
+            if (opts.limit !== undefined) {
+              limit = Number.parseInt(opts.limit, 10);
+              if (!Number.isInteger(limit) || limit < 1) {
+                console.error("--limit must be a positive integer.");
+                process.exitCode = 1;
+                return;
+              }
+            }
+            try {
+              const history = await listPinHistory(
+                name,
+                { fetch: globalThis.fetch.bind(globalThis) },
+                limit !== undefined ? { limit } : {},
+              );
+
+              if (opts.json) {
+                process.stdout.write(JSON.stringify(history, null, 2) + "\n");
+                return;
+              }
+
+              // Logged after the JSON early-return so the logger's stdout
+              // writes never corrupt --json output.
+              log.info({ name, count: history.length }, "plugin versions");
+              for (const line of formatVersions(name, history)) {
+                console.log(line);
+              }
+            } catch (err) {
+              if (
+                err instanceof InvalidPluginNameError ||
+                err instanceof PluginPinHistoryError
+              ) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
+              const message = err instanceof Error ? err.message : String(err);
+              console.error(`Plugin versions failed: ${message}`);
+              process.exitCode = 1;
+            }
+          },
+        );
+
       plugins
         .command("list")
         .description("List plugins installed under <workspaceDir>/plugins/")
@@ -483,6 +573,109 @@ Examples:
 }
 
 /** Abbreviate a commit SHA for display; passes through non-SHA / null values. */
+/** Full Git commit SHA — 40 hex (SHA-1) or 64 (SHA-256). */
+const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+
+/**
+ * Resolve `plugins install` flags into {@link InstallPluginOptions}, or `null`
+ * when the flag combination is invalid (a message is printed in that case, and
+ * the caller exits non-zero). Network / marketplace failures raised while
+ * resolving a `--pin` propagate to the caller's catch.
+ *
+ * `--pin <sha>` installs a specific reviewed marketplace pin: the SHA is looked
+ * up in the plugin's pin history and installed from the marketplace commit that
+ * introduced it, so the curated adapter stub of that era comes along. With
+ * `--allow-unreviewed` the SHA is materialized directly (adapter from `main`),
+ * bypassing the history check — the advanced escape hatch.
+ */
+async function resolveInstallOptions(
+  name: string,
+  opts: {
+    force?: boolean;
+    ref?: string;
+    pin?: string;
+    allowUnreviewed?: boolean;
+  },
+): Promise<InstallPluginOptions | null> {
+  const force = opts.force ?? false;
+
+  if (!opts.pin) {
+    if (opts.allowUnreviewed) {
+      console.error("--allow-unreviewed only applies together with --pin.");
+      return null;
+    }
+    return { name, force, ref: opts.ref ?? DEFAULT_PLUGIN_REF };
+  }
+
+  const pin = opts.pin.trim();
+  if (!FULL_SHA_RE.test(pin)) {
+    console.error(
+      `--pin must be a full commit SHA (40 or 64 hex chars); got ${JSON.stringify(opts.pin)}.`,
+    );
+    return null;
+  }
+  if (opts.ref) {
+    console.error(
+      "--ref and --pin cannot be combined; --pin already selects the revision.",
+    );
+    return null;
+  }
+
+  if (opts.allowUnreviewed) {
+    // Materialize the exact SHA from the plugin's current-manifest repo,
+    // bypassing the reviewed-history check. The adapter stub still comes from
+    // the default ref, so an adapted plugin may not reproduce faithfully.
+    return { name, force, ref: DEFAULT_PLUGIN_REF, commitOverride: pin };
+  }
+
+  const entry = await resolvePinToMarketplaceCommit(name, pin, {
+    fetch: globalThis.fetch.bind(globalThis),
+  });
+  if (!entry) {
+    console.error(
+      `"${pin}" is not a reviewed marketplace pin for "${name}".\n` +
+        `Run \`assistant plugins versions ${name}\` to see available pins, ` +
+        "or pass --allow-unreviewed to install it anyway.",
+    );
+    return null;
+  }
+  return { name, force, ref: entry.marketplaceCommit };
+}
+
+/**
+ * Render a plugin's marketplace-pin history as a table: the pinned commit (short
+ * SHA), when it was promoted, and a marker for the pin currently active. An
+ * empty history reports that none was found.
+ */
+function formatVersions(
+  name: string,
+  history: readonly PluginPinHistoryEntry[],
+): string[] {
+  if (history.length === 0) {
+    return [`No marketplace pin history found for "${name}".`];
+  }
+  const rows = history.map((entry) => ({
+    pin: shortSha(entry.pin),
+    promoted: formatTimestamp(entry.promotedAt),
+    marker: entry.current ? "(current)" : "",
+  }));
+  const pinW = Math.max(3, ...rows.map((r) => r.pin.length));
+  const promotedW = Math.max(8, ...rows.map((r) => r.promoted.length));
+  const pad = (s: string, w: number) => s + " ".repeat(w - s.length);
+  const lines = [
+    `${pad("PIN", pinW)}  ${pad("PROMOTED", promotedW)}  `.trimEnd(),
+  ];
+  for (const r of rows) {
+    lines.push(
+      `${pad(r.pin, pinW)}  ${pad(r.promoted, promotedW)}  ${r.marker}`.trimEnd(),
+    );
+  }
+  lines.push("");
+  lines.push("Install an older pin with:");
+  lines.push(`  assistant plugins install ${name} --pin <sha> --force`);
+  return lines;
+}
+
 function shortSha(sha: string | null): string {
   return sha ? sha.slice(0, 7) : "—";
 }

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

@@ -32,6 +32,7 @@ import {
   PluginPostinstallError,
   PluginSourceUnavailableError,
   type PostinstallRunner,
+  readInstallMeta,
   sanitizePluginName,
 } from "../install-from-github.js";
 
@@ -292,6 +293,36 @@ describe("installPlugin — install lifecycle", () => {
     expect(existsSync(join(target, "README.md"))).toBe(true);
   });
 
+  test("commitOverride materializes a specific commit, keeping repo from the manifest", async () => {
+    // GIVEN a manifest pinning the current SHA, but an override to an older one
+    const OLD_SHA = "1".repeat(40);
+    const fetch = makeContentsFetch({ tree: {}, manifest: CAVEMAN_MANIFEST });
+    const calls: string[][] = [];
+    const runGit = fakeGitRunner({
+      tree: { "package.json": '{"name":"caveman"}' },
+      commit: OLD_SHA,
+      calls,
+    });
+
+    // WHEN we install with the commit override
+    const result = await installPlugin(
+      { name: "caveman", force: false, ref: "main", commitOverride: OLD_SHA },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN the clone fetched the override commit, not the manifest's pin
+    expect(calls.find((c) => c[0] === "fetch")?.at(-1)).toBe(OLD_SHA);
+    expect(result.commit).toBe(OLD_SHA);
+    expect(result.ref).toBe(OLD_SHA);
+
+    // AND provenance records the override as the installed ref while still
+    // resolving owner/repo from the manifest entry
+    const meta = readInstallMeta(join(pluginsDir, "caveman"));
+    expect(meta?.source.ref).toBe(OLD_SHA);
+    expect(meta?.source.repo).toBe("caveman");
+    expect(meta?.source.owner).toBe("JuliusBrussee");
+  });
+
   test("--force preserves the existing install when the clone fails", async () => {
     // GIVEN a working copy already on disk
     const target = join(pluginsDir, "caveman");

package/src/cli/lib/__tests__/plugin-pin-history.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Tests for {@link listPinHistory} and {@link resolvePinToMarketplaceCommit}.
+ *
+ * The marketplace manifest stores only the current pin, so pin history is
+ * reconstructed by walking the manifest's commit history and reading the
+ * plugin's pin at each commit. The fixtures model that timeline with an
+ * in-memory `fetch`: a commits-list endpoint plus a manifest-at-ref endpoint
+ * keyed by commit SHA.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import type { FetchLike } from "../install-from-github.js";
+import {
+  listPinHistory,
+  resolvePinToMarketplaceCommit,
+} from "../plugin-pin-history.js";
+
+const PIN_A = "a".repeat(40);
+const PIN_B = "b".repeat(40);
+const PIN_C = "c".repeat(40);
+
+// Marketplace-manifest commits, newest → oldest. `C2B` touches the manifest
+// without changing this plugin's pin (a bump for some other plugin), so it must
+// collapse into the same distinct pin as `C3`.
+const C3 = "3".repeat(40);
+const C2B = "d".repeat(40);
+const C2 = "2".repeat(40);
+const C1 = "1".repeat(40);
+
+const COMMIT_DATES: Record<string, string> = {
+  [C3]: "2026-06-10T00:00:00.000Z",
+  [C2B]: "2026-06-08T00:00:00.000Z",
+  [C2]: "2026-06-05T00:00:00.000Z",
+  [C1]: "2026-06-01T00:00:00.000Z",
+};
+
+/** Plugin pin resolved from the manifest at each ref (`main` = current tip). */
+const PIN_BY_REF: Record<string, string> = {
+  main: PIN_C,
+  [C3]: PIN_C,
+  [C2B]: PIN_C,
+  [C2]: PIN_B,
+  [C1]: PIN_A,
+};
+
+function manifest(pin: string): string {
+  return JSON.stringify({
+    name: "vellum",
+    plugins: [
+      {
+        name: "level-up",
+        source: { source: "github", repo: "example-org/level-up", ref: pin },
+      },
+    ],
+  });
+}
+
+/**
+ * Build a `fetch` serving the commits list and the manifest at each ref.
+ * `commits` is the newest-first commit list the API returns.
+ */
+function makeFetch(commits: string[] = [C3, C2B, C2, C1]): FetchLike {
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (url.includes("/commits?")) {
+      const body = commits.map((sha) => ({
+        sha,
+        commit: { committer: { date: COMMIT_DATES[sha] } },
+      }));
+      return new Response(JSON.stringify(body), { status: 200 });
+    }
+    const m = url.match(/contents\/plugins\/marketplace\.json\?ref=([^&]+)/);
+    if (m) {
+      const ref = decodeURIComponent(m[1]!);
+      const pin = PIN_BY_REF[ref];
+      if (!pin) return new Response("not found", { status: 404 });
+      return new Response(manifest(pin), { status: 200 });
+    }
+    return new Response("unexpected url: " + url, { status: 500 });
+  }) as FetchLike;
+}
+
+describe("listPinHistory", () => {
+  test("lists distinct pins newest-first, collapsing unchanged revisions", async () => {
+    // GIVEN a manifest history with three distinct pins (one commit left the
+    // plugin's pin unchanged)
+    const history = await listPinHistory("level-up", { fetch: makeFetch() });
+
+    // THEN one entry per distinct pin, newest first, each tagged with the
+    // newest marketplace commit that carries it
+    expect(history).toEqual([
+      {
+        pin: PIN_C,
+        marketplaceCommit: C3,
+        promotedAt: COMMIT_DATES[C3]!,
+        current: true,
+      },
+      {
+        pin: PIN_B,
+        marketplaceCommit: C2,
+        promotedAt: COMMIT_DATES[C2]!,
+        current: false,
+      },
+      {
+        pin: PIN_A,
+        marketplaceCommit: C1,
+        promotedAt: COMMIT_DATES[C1]!,
+        current: false,
+      },
+    ]);
+  });
+
+  test("honors the limit (newest pins win)", async () => {
+    const history = await listPinHistory(
+      "level-up",
+      { fetch: makeFetch() },
+      { limit: 2 },
+    );
+    expect(history.map((e) => e.pin)).toEqual([PIN_C, PIN_B]);
+  });
+
+  test("returns an empty list for a plugin absent from every revision", async () => {
+    const history = await listPinHistory("ghost", { fetch: makeFetch() });
+    expect(history).toEqual([]);
+  });
+
+  test("returns an empty list when the manifest has no commit history", async () => {
+    const history = await listPinHistory("level-up", {
+      fetch: makeFetch([]),
+    });
+    expect(history).toEqual([]);
+  });
+});
+
+describe("resolvePinToMarketplaceCommit", () => {
+  test("maps a reviewed pin to the marketplace commit that introduced it", async () => {
+    const entry = await resolvePinToMarketplaceCommit("level-up", PIN_B, {
+      fetch: makeFetch(),
+    });
+    expect(entry?.marketplaceCommit).toBe(C2);
+    expect(entry?.pin).toBe(PIN_B);
+  });
+
+  test("is case-insensitive on the pin SHA", async () => {
+    const entry = await resolvePinToMarketplaceCommit(
+      "level-up",
+      PIN_B.toUpperCase(),
+      { fetch: makeFetch() },
+    );
+    expect(entry?.marketplaceCommit).toBe(C2);
+  });
+
+  test("returns null for a pin not in the reviewed history", async () => {
+    const entry = await resolvePinToMarketplaceCommit(
+      "level-up",
+      "f".repeat(40),
+      { fetch: makeFetch() },
+    );
+    expect(entry).toBeNull();
+  });
+});