@vellumai/assistant 0.8.8 → 0.8.9-dev.202606091926.ebb2d62

package/src/cli/lib/plugin-marketplace.ts

@@ -0,0 +1,215 @@
+/**
+ * Read the curated plugin marketplace manifest from the canonical repo.
+ *
+ * The manifest at `experimental/plugins/marketplace.json` whitelists external
+ * ecosystem plugins so they appear in `assistant plugins search` / the web
+ * catalog and become installable by name. Its shape is a subset of the
+ * Claude Code marketplace manifest
+ * (https://code.claude.com/docs/en/plugin-marketplaces) — `name` + `owner` +
+ * a `plugins` array where each entry carries a `name` and a `source`. Only
+ * `github` sources are resolved today.
+ *
+ * Like the first-party plugin listing, the manifest is fetched from the repo
+ * at a git ref (via the GitHub Contents API) rather than bundled into the
+ * assistant build — so the whitelist can grow without shipping a new release.
+ * Every external source pins an explicit `ref` that MUST be a full commit SHA:
+ * the fetched code is locked to an immutable revision. Tags and branches are
+ * rejected because they are mutable — an upstream owner could retag/repoint
+ * them to attacker code that the daemon would then `import()` (the install
+ * tree is dynamically loaded). A SHA cannot be repointed, so the reviewed
+ * manifest fully determines what gets executed.
+ *
+ * Designed for direct programmatic use with an injected `fetch`, mirroring
+ * {@link ./search-plugins} and {@link ./install-from-github}.
+ */
+
+import { z } from "zod";
+
+// Type-only import: keeps the dependency direction one-way at runtime
+// (install-from-github resolves sources *through* this module) while still
+// sharing the injected-`fetch` shape.
+import type { FetchLike } from "./install-from-github.js";
+
+/** Canonical location of the marketplace manifest. */
+const MARKETPLACE_SOURCE_OWNER = "vellum-ai";
+const MARKETPLACE_SOURCE_REPO = "vellum-assistant";
+const MARKETPLACE_FILE_PATH = "experimental/plugins/marketplace.json";
+
+// ---------------------------------------------------------------------------
+// Manifest schema (subset of the Claude Code marketplace schema)
+// ---------------------------------------------------------------------------
+
+/** `owner/repo`, kebab/underscore/dot segments — matches GitHub's slug rules. */
+const REPO_SLUG_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+/** Install name: a single kebab-case path segment (same rule as the CLI). */
+const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
+/**
+ * Full Git commit SHA — 40 hex chars (SHA-1) or 64 (SHA-256). External
+ * marketplace refs must be a complete object name so the install is pinned to
+ * an immutable revision; abbreviated SHAs, tags, and branches are all mutable
+ * or ambiguous and are rejected.
+ */
+const COMMIT_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
+
+const githubSourceSchema = z.object({
+  /** Discriminator. Only GitHub sources are resolved today. */
+  source: z.literal("github"),
+  /** `owner/repo` of the external plugin repository. */
+  repo: z.string().regex(REPO_SLUG_RE, "expected an `owner/repo` slug"),
+  /**
+   * Directory within the repo that holds the plugin root. Omitted / empty
+   * means the repository root. Must not escape the repo.
+   */
+  path: z
+    .string()
+    .refine(
+      (p) => !p.split(/[/\\]/).some((seg) => seg === ".." || seg === ""),
+      "path must be a clean repo-relative directory",
+    )
+    .optional(),
+  /**
+   * Immutable revision to fetch the plugin from. Must be a full commit SHA:
+   * tags and branches are mutable, so allowing them would let an upstream
+   * owner retarget a curated entry at code the daemon later `import()`s (RCE).
+   * A full SHA pins the install to exactly the reviewed bytes.
+   */
+  ref: z
+    .string()
+    .regex(
+      COMMIT_SHA_RE,
+      "expected a full commit SHA (40 or 64 hex chars); tags and branches are mutable and not allowed",
+    ),
+});
+
+const marketplaceEntrySchema = z.object({
+  /** Install name. `assistant plugins install <name>` resolves to this entry. */
+  name: z.string().regex(PLUGIN_NAME_RE, "expected a kebab-case install name"),
+  source: githubSourceSchema,
+  description: z.string().optional(),
+  /** Free-form grouping hint (e.g. `productivity`). Informational. */
+  category: z.string().optional(),
+  homepage: z.string().optional(),
+  license: z.string().optional(),
+});
+
+const marketplaceManifestSchema = z.object({
+  name: z.string(),
+  owner: z
+    .object({
+      name: z.string(),
+      url: z.string().optional(),
+      email: z.string().optional(),
+    })
+    .optional(),
+  plugins: z.array(marketplaceEntrySchema),
+});
+
+/** A single whitelisted external plugin entry. */
+export type MarketplaceEntry = z.infer<typeof marketplaceEntrySchema>;
+
+/** Concrete GitHub coordinates an entry resolves to for install. */
+export interface ResolvedPluginSource {
+  readonly owner: string;
+  readonly repo: string;
+  /** Directory within the repo holding the plugin root; `""` = repo root. */
+  readonly path: string;
+  /** Git ref to fetch from. */
+  readonly ref: string;
+}
+
+/** Options controlling which marketplace revision to read. */
+export interface FetchMarketplaceOptions {
+  /** Ref of the canonical repo to read the manifest from. */
+  readonly ref: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface FetchMarketplaceDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/**
+ * The manifest could not be read or did not validate. Distinct from "no
+ * manifest at this ref" (a missing file is a normal, empty result) — this
+ * signals an upstream/parse problem the caller may choose to surface or
+ * degrade past.
+ */
+export class MarketplaceFetchError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MarketplaceFetchError";
+  }
+}
+
+/**
+ * Fetch and validate the marketplace manifest, returning its plugin entries.
+ *
+ * A missing manifest (HTTP 404) is treated as an empty whitelist — the
+ * marketplace is supplementary to the first-party plugin listing, so its
+ * absence is not an error. Any other HTTP failure, a non-JSON body, or a
+ * schema violation throws {@link MarketplaceFetchError}.
+ */
+export async function fetchMarketplaceEntries(
+  deps: FetchMarketplaceDeps,
+  opts: FetchMarketplaceOptions,
+): Promise<readonly MarketplaceEntry[]> {
+  const { ref } = opts;
+  const url =
+    `https://api.github.com/repos/${MARKETPLACE_SOURCE_OWNER}/${MARKETPLACE_SOURCE_REPO}` +
+    `/contents/${MARKETPLACE_FILE_PATH}?ref=${encodeURIComponent(ref)}`;
+
+  const res = await deps.fetch(url, {
+    headers: {
+      // Ask for the raw file body rather than the base64-wrapped Contents
+      // envelope, so the response text is the manifest JSON directly.
+      Accept: "application/vnd.github.raw",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+
+  if (res.status === 404) return [];
+  if (!res.ok) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest fetch failed for ${MARKETPLACE_FILE_PATH} @ ${ref}: HTTP ${res.status}`,
+    );
+  }
+
+  let json: unknown;
+  try {
+    json = JSON.parse(await res.text());
+  } catch (err) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  const parsed = marketplaceManifestSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new MarketplaceFetchError(
+      `Marketplace manifest failed validation: ${parsed.error.message}`,
+    );
+  }
+
+  return parsed.data.plugins;
+}
+
+/**
+ * Resolve a plugin name to concrete GitHub coordinates using the supplied
+ * marketplace entries. Returns `null` when no entry claims the name (the
+ * caller then falls back to the first-party source convention).
+ */
+export function resolveMarketplaceSource(
+  name: string,
+  entries: readonly MarketplaceEntry[],
+): ResolvedPluginSource | null {
+  const entry = entries.find((e) => e.name === name);
+  if (!entry) return null;
+  const [owner, repo] = entry.source.repo.split("/", 2) as [string, string];
+  return {
+    owner,
+    repo,
+    path: entry.source.path ?? "",
+    ref: entry.source.ref,
+  };
+}

package/src/cli/lib/search-plugins.ts

@@ -1,10 +1,17 @@
 /**
- * Search for plugin directories in the canonical GitHub source.
+ * Search the installable plugin catalog in the canonical GitHub source.
  *
- * Lists `vellum-ai/vellum-assistant/experimental/plugins/` at the configured
- * git ref and filters the directory entries by case-insensitive ECMAScript
- * regex. A plain query like `"memory"` matches anywhere in the name; anchors
- * like `"^simple"` work without escaping.
+ * The catalog is the union of two sources, both fetched from the repo at the
+ * configured git ref:
+ *   1. First-party plugins — directories under
+ *      `vellum-ai/vellum-assistant/experimental/plugins/`.
+ *   2. Whitelisted external ecosystem plugins — entries in the curated
+ *      `experimental/plugins/marketplace.json` manifest (see
+ *      {@link ./plugin-marketplace}).
+ *
+ * Entries are filtered by case-insensitive ECMAScript regex against the
+ * plugin name. A plain query like `"memory"` matches anywhere in the name;
+ * anchors like `"^simple"` work without escaping.
  *
  * Designed for direct programmatic use. The CLI command
  * `assistant plugins search <query>` is a thin wrapper that supplies
@@ -15,6 +22,10 @@
 
 import type { FetchLike } from "./install-from-github.js";
 import { DEFAULT_PLUGIN_REF } from "./install-from-github.js";
+import {
+  fetchMarketplaceEntries,
+  type MarketplaceEntry,
+} from "./plugin-marketplace.js";
 
 // Re-export the dep-injection type so callers can grab everything they need
 // from one module rather than reaching into `install-from-github.js`.
@@ -50,12 +61,33 @@ export interface SearchPluginsDeps {
   readonly fetch: FetchLike;
 }
 
-/** One matching plugin directory. */
+/** Where a catalog match comes from. */
+export type PluginMatchSource =
+  | { readonly kind: "first-party" }
+  | {
+      readonly kind: "github";
+      /** `owner/repo` of the external plugin repository. */
+      readonly repo: string;
+      /** Directory within the repo, when the plugin is not at the root. */
+      readonly path?: string;
+      /** Pinned git ref the plugin is fetched from. */
+      readonly ref: string;
+    };
+
+/** One matching catalog entry. */
 export interface PluginSearchMatch {
-  /** Directory name under `experimental/plugins/`. */
+  /** Install name — `assistant plugins install <name>` resolves to it. */
   readonly name: string;
-  /** Path within the repo (e.g. `experimental/plugins/<name>`). */
+  /**
+   * Human-readable origin of the entry: the repo-relative path for
+   * first-party plugins (e.g. `experimental/plugins/<name>`) or a
+   * `github:owner/repo@ref` locator for external ones.
+   */
   readonly path: string;
+  /** Short description, when known (external entries only today). */
+  readonly description?: string;
+  /** Discriminated origin, so callers can render/install accordingly. */
+  readonly source: PluginMatchSource;
 }
 
 /** Search result envelope. */
@@ -75,12 +107,28 @@ export class InvalidSearchPatternError extends Error {
 }
 
 /**
- * List directories under `experimental/plugins/` at {@link opts.ref} and
- * filter by {@link opts.query}.
- *
- * Only `type === "dir"` entries are returned — `experimental/plugins/`
- * follows a convention where each plugin lives in its own directory, so
- * loose files at the prefix are not plugins.
+ * The catalog source (GitHub) was reachable but refused or could not serve
+ * the request right now — rate limiting (HTTP 403 with the rate-limit budget
+ * exhausted, or 429) or an upstream 5xx. Distinct from a hard 404 on the
+ * plugins prefix (a real "source gone" misconfiguration): a transient
+ * upstream failure should surface as a retryable "temporarily unavailable"
+ * rather than a generic internal error, and is a candidate for serving a
+ * stale cached catalog.
+ */
+export class PluginCatalogUnavailableError extends Error {
+  /** Upstream HTTP status that triggered the failure. */
+  readonly status: number;
+  constructor(message: string, status: number) {
+    super(message);
+    this.name = "PluginCatalogUnavailableError";
+    this.status = status;
+  }
+}
+
+/**
+ * Build the catalog at {@link opts.ref} and return the entries whose name
+ * matches {@link opts.query} (case-insensitive ECMAScript regex; an empty
+ * query matches everything).
  */
 export async function searchPlugins(
   opts: SearchPluginsOptions,
@@ -92,17 +140,125 @@ export async function searchPlugins(
   // the network — keeps "user typo" cheap to recover from.
   const matcher = buildMatcher(opts.query);
 
-  const entries = await listDir(PLUGIN_SOURCE_PATH_PREFIX, ref, deps.fetch);
+  const { matches: catalog } = await loadPluginCatalog({ ref }, deps);
+  const matches = catalog.filter((m) => matcher(m.name));
+
+  return { query: opts.query, ref, matches };
+}
+
+/**
+ * Validate that {@link query} compiles as a case-insensitive ECMAScript regex,
+ * throwing {@link InvalidSearchPatternError} if not. Lets a caching caller
+ * (the daemon) reject a malformed query before loading the catalog, so a typo
+ * is a cheap deterministic 400 rather than a wasted GitHub request.
+ */
+export function assertValidSearchPattern(query: string): void {
+  buildMatcher(query);
+}
+
+/**
+ * Filter a pre-loaded {@link PluginCatalog} by {@link query}, compiling it as
+ * a case-insensitive ECMAScript regex (an empty query matches everything).
+ * Lets a caching caller (the daemon) reuse one catalog load across many
+ * searches. Throws {@link InvalidSearchPatternError} on a malformed pattern.
+ */
+export function filterPluginCatalog(
+  catalog: PluginCatalog,
+  query: string,
+): PluginSearchMatch[] {
+  const matcher = buildMatcher(query);
+  return catalog.matches.filter((m) => matcher(m.name));
+}
+
+/** The full, unfiltered catalog at a given ref. */
+export interface PluginCatalog {
+  readonly ref: string;
+  /** Every catalog entry, deduped and sorted alphabetically by name. */
+  readonly matches: readonly PluginSearchMatch[];
+}
+
+/**
+ * Build the full catalog at {@link opts.ref}: every first-party plugin
+ * directory under `experimental/plugins/` merged with every whitelisted
+ * external entry in the marketplace manifest.
+ *
+ * The result is **query-independent** — `searchPlugins` applies the regex
+ * filter in memory afterwards. That separation is what lets a long-lived
+ * caller (the daemon) cache one catalog load and serve any number of
+ * searches from it without re-hitting GitHub (see {@link ./plugin-catalog-cache}).
+ */
+export async function loadPluginCatalog(
+  opts: { readonly ref?: string },
+  deps: SearchPluginsDeps,
+): Promise<PluginCatalog> {
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+
+  const [entries, marketplace] = await Promise.all([
+    listDir(PLUGIN_SOURCE_PATH_PREFIX, ref, deps.fetch),
+    fetchMarketplaceSafe(deps.fetch, ref),
+  ]);
 
   const matches: PluginSearchMatch[] = [];
+  const seen = new Set<string>();
+
+  // Whitelisted external entries own their name. A same-named
+  // `experimental/plugins/<name>/` directory is that plugin's curated adapter
+  // stub (overlaid onto the clone at install time), not a standalone
+  // first-party plugin — so it must surface once, as the external entry.
+  for (const entry of marketplace) {
+    if (seen.has(entry.name)) continue;
+    matches.push(marketplaceMatch(entry));
+    seen.add(entry.name);
+  }
+
+  // First-party plugins are the in-repo directories whose name the marketplace
+  // does not claim.
   for (const entry of entries) {
     if (entry.type !== "dir") continue;
-    if (!matcher(entry.name)) continue;
-    matches.push({ name: entry.name, path: entry.path });
+    if (seen.has(entry.name)) continue;
+    matches.push({
+      name: entry.name,
+      path: entry.path,
+      source: { kind: "first-party" },
+    });
+    seen.add(entry.name);
   }
+
   matches.sort((a, b) => a.name.localeCompare(b.name));
 
-  return { query: opts.query, ref, matches };
+  return { ref, matches };
+}
+
+/**
+ * Project a marketplace entry onto the catalog match shape, building a
+ * `github:owner/repo[/path]@ref` locator for display.
+ */
+function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
+  const { repo, path, ref } = entry.source;
+  const locator = `github:${repo}${path ? `/${path}` : ""}@${ref}`;
+  return {
+    name: entry.name,
+    path: locator,
+    description: entry.description,
+    source: { kind: "github", repo, path, ref },
+  };
+}
+
+/**
+ * Fetch the marketplace manifest, degrading to an empty whitelist on any
+ * failure. The manifest is supplementary to the first-party listing, so a
+ * missing or malformed manifest must never break the core catalog — mirroring
+ * the daemon's "never block over a subsystem failure" philosophy.
+ */
+async function fetchMarketplaceSafe(
+  fetchFn: FetchLike,
+  ref: string,
+): Promise<readonly MarketplaceEntry[]> {
+  try {
+    return await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
+  } catch {
+    return [];
+  }
 }
 
 function buildMatcher(query: string): (name: string) => boolean {
@@ -127,13 +283,17 @@ async function listDir(
 
   const res = await githubFetch(url, fetchFn);
   if (!res.ok) {
-    // Unlike `installPlugin`, where 404 on a specific plugin name is a
-    // legitimate "not found" outcome, 404 on the plugins prefix itself
-    // means the canonical source path is gone — surface it as an error
-    // rather than silently returning empty results.
-    throw new Error(
-      `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`,
-    );
+    const detail = `GitHub contents listing failed for ${apiPath} @ ${ref}: HTTP ${res.status}`;
+    // Rate limiting (403 with the budget exhausted, or 429) and upstream
+    // 5xx are transient — surface them as a retryable "temporarily
+    // unavailable" so the caller can serve a stale cache and the route can
+    // map to 503 instead of a misleading 500. A 404 on the plugins prefix
+    // itself means the canonical source path is gone (a real
+    // misconfiguration), so it stays a hard error.
+    if (isTransientUpstreamStatus(res)) {
+      throw new PluginCatalogUnavailableError(detail, res.status);
+    }
+    throw new Error(detail);
   }
 
   const body = (await res.json()) as unknown;
@@ -150,10 +310,22 @@ async function listDir(
  * request. Unauthenticated — the canonical source is a public repo, mirroring
  * `installPlugin` which uses the same envelope.
  */
-async function githubFetch(
-  url: string,
-  fetchFn: FetchLike,
-): Promise<Response> {
+/**
+ * Whether a non-OK GitHub response should be treated as a transient
+ * "temporarily unavailable" failure rather than a hard error. Covers
+ * rate limiting (429, or 403 once the rate-limit budget is exhausted) and
+ * upstream server errors (5xx). A bare 403 without the rate-limit signal
+ * (e.g. a genuine permissions problem) is not treated as transient.
+ */
+function isTransientUpstreamStatus(res: Response): boolean {
+  if (res.status === 429 || res.status >= 500) return true;
+  if (res.status === 403) {
+    return res.headers.get("x-ratelimit-remaining") === "0";
+  }
+  return false;
+}
+
+async function githubFetch(url: string, fetchFn: FetchLike): Promise<Response> {
   return fetchFn(url, {
     headers: {
       Accept: "application/vnd.github+json",

package/src/config/__tests__/feature-flag-registry-guard.test.ts

@@ -85,8 +85,8 @@ describe("unified feature flag registry guard", () => {
       ) {
         violations.push(`${prefix}: missing or non-string 'description'`);
       }
-      if (typeof flag.defaultEnabled !== "boolean") {
-        violations.push(`${prefix}: missing or non-boolean 'defaultEnabled'`);
+      if (typeof flag.defaultEnabled !== "boolean" && typeof flag.defaultEnabled !== "string") {
+        violations.push(`${prefix}: missing or invalid 'defaultEnabled' (expected boolean or string)`);
       }
     }
 

package/src/config/acp-defaults.test.ts

@@ -10,6 +10,7 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     expect(Object.keys(DEFAULT_ACP_AGENT_PROFILES).sort()).toEqual([
       "claude",
       "codex",
+      "gemini",
     ]);
   });
 
@@ -29,6 +30,14 @@ describe("DEFAULT_ACP_AGENT_PROFILES", () => {
     });
   });
 
+  test("gemini profile speaks native ACP via gemini --acp (no adapter binary)", () => {
+    expect(DEFAULT_ACP_AGENT_PROFILES.gemini).toEqual({
+      command: "gemini",
+      args: ["--acp"],
+      description: "Google Gemini CLI (native ACP via gemini --acp)",
+    });
+  });
+
   test("is deeply frozen so mutation throws in strict mode", () => {
     expect(Object.isFrozen(DEFAULT_ACP_AGENT_PROFILES)).toBe(true);
     for (const profile of Object.values(DEFAULT_ACP_AGENT_PROFILES)) {
@@ -46,6 +55,7 @@ describe("DEFAULT_AGENT_NPM_PACKAGES", () => {
     expect(DEFAULT_AGENT_NPM_PACKAGES).toEqual({
       "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
       "codex-acp": "@zed-industries/codex-acp",
+      gemini: "@google/gemini-cli",
     });
   });
 

package/src/config/acp-defaults.ts

@@ -9,9 +9,9 @@ const FROZEN_EMPTY_ARGS = Object.freeze([] as string[]) as unknown as string[];
 /**
  * Default ACP agent profiles that ship with the assistant.
  *
- * When `acp.enabled: true` and the user has not provided a config entry for an
- * agent id, the resolver falls back to this map so common agents like `claude`
- * and `codex` Just Work without requiring per-user config.
+ * When the user has not provided a config entry for an agent id, the resolver
+ * falls back to this map so common agents like `claude` and `codex` Just Work
+ * without requiring per-user config.
  *
  * Keyed by agent id. Deeply frozen — the outer object, each profile, and the
  * `args` arrays — so mutation throws in strict mode rather than silently
@@ -30,6 +30,11 @@ export const DEFAULT_ACP_AGENT_PROFILES: Readonly<
     args: FROZEN_EMPTY_ARGS,
     description: "OpenAI Codex CLI (via @zed-industries/codex-acp)",
   }),
+  gemini: Object.freeze({
+    command: "gemini",
+    args: Object.freeze(["--acp"]) as unknown as string[],
+    description: "Google Gemini CLI (native ACP via gemini --acp)",
+  }),
 });
 
 /**
@@ -44,4 +49,5 @@ export const DEFAULT_AGENT_NPM_PACKAGES: Readonly<Record<string, string>> =
   Object.freeze({
     "claude-agent-acp": "@agentclientprotocol/claude-agent-acp",
     "codex-acp": "@zed-industries/codex-acp",
+    gemini: "@google/gemini-cli",
   });

package/src/config/acp-schema.ts

@@ -20,12 +20,6 @@ const AcpAgentConfigSchema = z
 
 export const AcpConfigSchema = z
   .object({
-    enabled: z
-      .boolean()
-      .default(false)
-      .describe(
-        "Whether the Agent Communication Protocol (ACP) system is enabled",
-      ),
     maxConcurrentSessions: z
       .number()
       .int()
@@ -40,7 +34,7 @@ export const AcpConfigSchema = z
       .describe("Map of agent names to their configurations"),
   })
   .describe(
-    "Agent Communication Protocol (ACP) — enables inter-agent communication and delegation",
+    "Agent Communication Protocol (ACP) — inter-agent communication and delegation",
   );
 
 export type AcpConfig = z.infer<typeof AcpConfigSchema>;