@vellumai/assistant 0.8.2 → 0.8.4

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

@@ -0,0 +1,261 @@
+/**
+ * Tests for {@link searchPlugins}.
+ *
+ * Network is replaced with an in-memory fixture passed via the `fetch`
+ * dependency — no globals are monkey-patched and no `--test-hook` exports
+ * leak into production code.
+ */
+
+import { describe, expect, test } from "bun:test";
+
+import {
+  type FetchLike,
+  InvalidSearchPatternError,
+  searchPlugins,
+} from "../search-plugins.js";
+
+/**
+ * Build a GitHub Contents API fixture from an in-memory directory listing.
+ *
+ * `entries` maps each name under `experimental/plugins/` to its `type`. The
+ * fixture answers GET requests against
+ *  - `https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins...`
+ * and returns 500 for anything else (forces test bugs to surface loudly).
+ */
+function fixtureFetch(
+  entries: Record<string, "dir" | "file" | "symlink" | "submodule">,
+): FetchLike {
+  const PREFIX_API =
+    "https://api.github.com/repos/vellum-ai/vellum-assistant/contents/experimental/plugins";
+
+  return (async (input: RequestInfo | URL) => {
+    const url = typeof input === "string" ? input : input.toString();
+    if (!url.startsWith(PREFIX_API)) {
+      return new Response("unexpected url: " + url, { status: 500 });
+    }
+    const body = Object.entries(entries).map(([name, type]) => ({
+      name,
+      path: `experimental/plugins/${name}`,
+      type,
+      size: type === "file" ? 1 : 0,
+      download_url:
+        type === "file"
+          ? `https://raw.githubusercontent.com/vellum-ai/vellum-assistant/main/experimental/plugins/${name}`
+          : null,
+    }));
+    return new Response(JSON.stringify(body), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as FetchLike;
+}
+
+describe("searchPlugins", () => {
+  test("matches the query as a case-insensitive regex against directory names", async () => {
+    const result = await searchPlugins(
+      { query: "memory" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "memory-graph": "dir",
+          "git-tools": "dir",
+        }),
+      },
+    );
+
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "memory-graph",
+      "simple-memory",
+    ]);
+    expect(result.matches[0]!.path).toBe("experimental/plugins/memory-graph");
+    expect(result.query).toBe("memory");
+    expect(result.ref).toBe("main");
+  });
+
+  test("matches regardless of query casing (case-insensitive)", async () => {
+    const result = await searchPlugins(
+      { query: "MEMORY" },
+      { fetch: fixtureFetch({ "simple-memory": "dir" }) },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("anchored patterns work without escaping", async () => {
+    const result = await searchPlugins(
+      { query: "^memory-" },
+      {
+        fetch: fixtureFetch({
+          "memory-graph": "dir",
+          "simple-memory": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["memory-graph"]);
+  });
+
+  test("empty query matches all directories", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "memory-graph": "dir",
+          "git-tools": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "git-tools",
+      "memory-graph",
+      "simple-memory",
+    ]);
+  });
+
+  test("skips entries that are not directories", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "simple-memory": "dir",
+          "README.md": "file",
+          "broken-symlink": "symlink",
+          "old-plugin": "submodule",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("rejects invalid regex patterns up front (no network call)", async () => {
+    let fetchCalled = false;
+    const fetch: FetchLike = (async () => {
+      fetchCalled = true;
+      return new Response("", { status: 200 });
+    }) as FetchLike;
+
+    await expect(
+      searchPlugins({ query: "(unterminated" }, { fetch }),
+    ).rejects.toBeInstanceOf(InvalidSearchPatternError);
+    expect(fetchCalled).toBe(false);
+  });
+
+  test("empty result set on no matches", async () => {
+    const result = await searchPlugins(
+      { query: "nothing-matches" },
+      { fetch: fixtureFetch({ "simple-memory": "dir" }) },
+    );
+    expect(result.matches).toEqual([]);
+  });
+
+  test("respects `ref` option by forwarding to GitHub", async () => {
+    // The CLI does not surface a `--ref` flag (the source-path convention
+    // may change), but the underlying function keeps `ref` for test
+    // injection and future internal callers.
+    let seenRef: string | undefined;
+    const result = await searchPlugins(
+      { query: "memory", ref: "feat-branch" },
+      {
+        fetch: (async (input: RequestInfo | URL) => {
+          const url = typeof input === "string" ? input : input.toString();
+          const m = /[?&]ref=([^&]+)/.exec(url);
+          seenRef = m ? decodeURIComponent(m[1]!) : undefined;
+          return new Response(
+            JSON.stringify([
+              {
+                name: "simple-memory",
+                path: "experimental/plugins/simple-memory",
+                type: "dir",
+                size: 0,
+                download_url: null,
+              },
+            ]),
+            { status: 200, headers: { "content-type": "application/json" } },
+          );
+        }) as FetchLike,
+      },
+    );
+
+    expect(seenRef).toBe("feat-branch");
+    expect(result.ref).toBe("feat-branch");
+    expect(result.matches.map((m) => m.name)).toEqual(["simple-memory"]);
+  });
+
+  test("HTTP 5xx from GitHub propagates with the status code", async () => {
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("upstream broken", { status: 503 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 503/);
+  });
+
+  test("HTTP 403 (rate-limited / forbidden) surfaces as an error", async () => {
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("rate limit exceeded", { status: 403 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 403/);
+  });
+
+  test("404 on the plugins prefix surfaces as an error (not silently empty)", async () => {
+    // Distinct from `installPlugin`, where 404 on a specific plugin name is
+    // normal "not found". For the search, 404 on the prefix means the
+    // canonical source path itself is gone — that's an upstream problem
+    // worth surfacing, not a clean empty result.
+    await expect(
+      searchPlugins(
+        { query: "memory" },
+        {
+          fetch: (async () =>
+            new Response("not found", { status: 404 })) as FetchLike,
+        },
+      ),
+    ).rejects.toThrow(/HTTP 404/);
+  });
+
+  test("returns matches sorted by name", async () => {
+    const result = await searchPlugins(
+      { query: "" },
+      {
+        fetch: fixtureFetch({
+          "zeta-plugin": "dir",
+          "alpha-plugin": "dir",
+          "mu-plugin": "dir",
+        }),
+      },
+    );
+    expect(result.matches.map((m) => m.name)).toEqual([
+      "alpha-plugin",
+      "mu-plugin",
+      "zeta-plugin",
+    ]);
+  });
+
+  test("sends no Authorization header (canonical source is a public repo)", async () => {
+    let seenAuth: string | undefined;
+    let seenUserAgent: string | undefined;
+    await searchPlugins(
+      { query: "memory" },
+      {
+        fetch: (async (_input: RequestInfo | URL, init?: RequestInit) => {
+          const headers = init?.headers as Record<string, string> | undefined;
+          seenAuth = headers?.Authorization;
+          seenUserAgent = headers?.["User-Agent"];
+          return new Response("[]", {
+            status: 200,
+            headers: { "content-type": "application/json" },
+          });
+        }) as FetchLike,
+      },
+    );
+    expect(seenAuth).toBeUndefined();
+    expect(seenUserAgent).toBe("vellum-assistant-cli");
+  });
+});

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

@@ -286,19 +286,18 @@ async function copyFile(
 
 /**
  * Wraps `fetchFn` with the headers we want to send to GitHub for every
- * request. Honors `GITHUB_TOKEN` when present so users who hit the
- * unauthenticated rate limit can opt into a higher cap.
+ * request. Unauthenticated — the canonical source is a public repo, so
+ * there is nothing for an `Authorization` header to do.
  */
 async function githubFetch(
   url: string,
   accept: string,
   fetchFn: FetchLike,
 ): Promise<Response> {
-  const headers: Record<string, string> = {
-    Accept: accept,
-    "User-Agent": "vellum-assistant-cli",
-  };
-  const token = process.env.GITHUB_TOKEN?.trim();
-  if (token) headers.Authorization = `Bearer ${token}`;
-  return fetchFn(url, { headers });
+  return fetchFn(url, {
+    headers: {
+      Accept: accept,
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
 }

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

@@ -0,0 +1,163 @@
+/**
+ * Search for plugin directories 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.
+ *
+ * Designed for direct programmatic use. The CLI command
+ * `assistant plugins search <query>` is a thin wrapper that supplies
+ * production deps (`globalThis.fetch`) and formats the result for the
+ * terminal; downstream callers may supply their own `fetch` (e.g. a
+ * retry-decorated client, or a test fixture).
+ */
+
+import type { FetchLike } from "./install-from-github.js";
+import { DEFAULT_PLUGIN_REF } from "./install-from-github.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`.
+export type { FetchLike } from "./install-from-github.js";
+
+const PLUGIN_SOURCE_OWNER = "vellum-ai";
+const PLUGIN_SOURCE_REPO = "vellum-assistant";
+const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+
+/** Entry shape returned by the GitHub Contents API for a directory listing. */
+interface GitHubContentEntry {
+  readonly name: string;
+  readonly path: string;
+  readonly type: "file" | "dir" | "symlink" | "submodule";
+  readonly size: number;
+  readonly download_url: string | null;
+}
+
+/** Options that control the search. */
+export interface SearchPluginsOptions {
+  /**
+   * ECMAScript regex pattern. Matched case-insensitively against directory
+   * names. Empty string matches everything.
+   */
+  readonly query: string;
+  /** Git ref to list from. Defaults to {@link DEFAULT_PLUGIN_REF}. */
+  readonly ref?: string;
+}
+
+/** Dependencies injected by the caller. */
+export interface SearchPluginsDeps {
+  /** HTTP client. Production callers pass `globalThis.fetch.bind(globalThis)`. */
+  readonly fetch: FetchLike;
+}
+
+/** One matching plugin directory. */
+export interface PluginSearchMatch {
+  /** Directory name under `experimental/plugins/`. */
+  readonly name: string;
+  /** Path within the repo (e.g. `experimental/plugins/<name>`). */
+  readonly path: string;
+}
+
+/** Search result envelope. */
+export interface SearchPluginsResult {
+  readonly query: string;
+  readonly ref: string;
+  readonly matches: readonly PluginSearchMatch[];
+}
+
+/** Caller passed a query that doesn't compile as an ECMAScript regex. */
+export class InvalidSearchPatternError extends Error {
+  constructor(pattern: string, cause: unknown) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    super(`Invalid regex pattern ${JSON.stringify(pattern)}: ${detail}`);
+    this.name = "InvalidSearchPatternError";
+  }
+}
+
+/**
+ * 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.
+ */
+export async function searchPlugins(
+  opts: SearchPluginsOptions,
+  deps: SearchPluginsDeps,
+): Promise<SearchPluginsResult> {
+  const ref = opts.ref ?? DEFAULT_PLUGIN_REF;
+
+  // Compile the matcher up front so an invalid regex fails before we hit
+  // 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: PluginSearchMatch[] = [];
+  for (const entry of entries) {
+    if (entry.type !== "dir") continue;
+    if (!matcher(entry.name)) continue;
+    matches.push({ name: entry.name, path: entry.path });
+  }
+  matches.sort((a, b) => a.name.localeCompare(b.name));
+
+  return { query: opts.query, ref, matches };
+}
+
+function buildMatcher(query: string): (name: string) => boolean {
+  let re: RegExp;
+  try {
+    re = new RegExp(query, "i");
+  } catch (err) {
+    throw new InvalidSearchPatternError(query, err);
+  }
+  return (name) => re.test(name);
+}
+
+async function listDir(
+  apiPath: string,
+  ref: string,
+  fetchFn: FetchLike,
+): Promise<readonly GitHubContentEntry[]> {
+  const url =
+    `https://api.github.com/repos/${PLUGIN_SOURCE_OWNER}/${PLUGIN_SOURCE_REPO}` +
+    `/contents/${encodeURIComponent(apiPath).replaceAll("%2F", "/")}` +
+    `?ref=${encodeURIComponent(ref)}`;
+
+  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 body = (await res.json()) as unknown;
+  if (!Array.isArray(body)) {
+    // A non-array body for a /contents/<dir> path means the path is a
+    // file, not a directory — treat the prefix as empty rather than crash.
+    return [];
+  }
+  return body as readonly GitHubContentEntry[];
+}
+
+/**
+ * Wraps `fetchFn` with the headers we want to send to GitHub for every
+ * 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> {
+  return fetchFn(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      "User-Agent": "vellum-assistant-cli",
+    },
+  });
+}

package/src/cli/program.ts

@@ -62,6 +62,20 @@ import { log } from "./logger.js";
  */
 export async function buildCliProgram(): Promise<Command> {
   await initFeatureFlagOverrides({ retryBackoffsMs: [], callTimeoutMs: 200 });
+  return buildCliProgramTree();
+}
+
+/**
+ * Synchronously build the CLI program tree without pre-populating the
+ * feature-flag cache. Use this from inside the daemon, where flags are
+ * already initialized — calling `buildCliProgram` from there would round-trip
+ * to the gateway unnecessarily.
+ *
+ * Same shape as `buildCliProgram` minus the async feature-flag init: registers
+ * the full subcommand set (conditionally gated on email / external-plugins
+ * flags via `getConfigReadOnly()`) and installs the workspace-preAction hook.
+ */
+export function buildCliProgramTree(): Command {
   const program = new Command();
 
   program

package/src/cli/utils/conversation-id.ts

@@ -3,12 +3,11 @@
  *   1. Explicit value provided in `opts.explicit`
  *   2. `__SKILL_CONTEXT_JSON` env var (set by skill sandbox runner)
  *   3. `__CONVERSATION_ID` env var (set by bash tool subprocess)
- *   4. Throw with the provided `failureHelp` message
+ *   4. `undefined`
  */
-export function resolveConversationId(opts: {
-  explicit?: string;
-  failureHelp: string;
-}): string {
+export function tryResolveConversationId(
+  opts: { explicit?: string } = {},
+): string | undefined {
   if (opts.explicit) return opts.explicit;
 
   const contextJson = process.env.__SKILL_CONTEXT_JSON;
@@ -26,5 +25,18 @@ export function resolveConversationId(opts: {
   const envConvId = process.env.__CONVERSATION_ID;
   if (envConvId && typeof envConvId === "string") return envConvId;
 
+  return undefined;
+}
+
+/**
+ * Same precedence as `tryResolveConversationId` but throws with the
+ * provided `failureHelp` when no source produces a value.
+ */
+export function resolveConversationId(opts: {
+  explicit?: string;
+  failureHelp: string;
+}): string {
+  const resolved = tryResolveConversationId({ explicit: opts.explicit });
+  if (resolved) return resolved;
   throw new Error(opts.failureHelp);
 }

package/src/config/assistant-feature-flags.ts

@@ -110,20 +110,22 @@ function parseRegistryToDefaults(parsed: unknown): FeatureFlagDefaultsRegistry {
 }
 
 // ---------------------------------------------------------------------------
-// Override loading — reads from gateway IPC socket or local file
+// Override loading — reads from gateway IPC socket
 // ---------------------------------------------------------------------------
 
 /**
- * Module-level cache of feature flag override values. Populated lazily on
- * first access, invalidated by `clearFeatureFlagOverridesCache()`.
+ * Module-level cache of feature flag override values. Populated by
+ * `initFeatureFlagOverrides()` at startup, invalidated by
+ * `clearFeatureFlagOverridesCache()`.
  */
 let cachedOverrides: Record<string, boolean> | null = null;
 
 /**
- * True when `cachedOverrides` was populated by the gateway IPC fetch (or
- * preseeded by a test). False/unset when the cache was populated by the sync
- * file fallback in `loadOverrides()`, which must not prevent a subsequent
- * authoritative gateway fetch from running.
+ * True when `cachedOverrides` was populated by the gateway IPC fetch or
+ * preseeded by a test via `_setOverridesForTesting()`. Guards
+ * `initFeatureFlagOverrides()` from clobbering an existing populated cache
+ * when called a second time (e.g. by a CLI entry point after the daemon
+ * has already initialized).
  */
 let cachedOverridesFromGateway = false;
 
@@ -247,59 +249,30 @@ function loadOverrides(): Record<string, boolean> {
   return cachedOverrides ?? {};
 }
 
-// ---------------------------------------------------------------------------
-// Remote values — platform-pushed flags cached in a local JSON file
-// ---------------------------------------------------------------------------
-
 /**
- * Module-level cache of remote feature flag values. Populated lazily on
- * first access, invalidated by `clearFeatureFlagOverridesCache()`.
- */
-let cachedRemoteValues: Record<string, boolean> | null = null;
-
-/**
- * Load remote values with module-level caching.
+ * Invalidate the cached overrides so the next call to
+ * `isAssistantFeatureFlagEnabled` re-reads from the gateway.
  *
- * Remote values are now always included in the gateway IPC response (merged
- * server-side), so this only returns the injected test cache. In production,
- * remote values flow through the overrides cache.
- */
-function loadRemoteValues(): Record<string, boolean> {
-  return cachedRemoteValues ?? {};
-}
-
-/**
- * Invalidate the cached override and remote values so the next call to
- * `isAssistantFeatureFlagEnabled` re-reads from the source.
- *
- * Called by the config watcher when the feature-flags file changes.
+ * Used by tests between cases to reset module state.
  */
 export function clearFeatureFlagOverridesCache(): void {
   cachedOverrides = null;
   cachedOverridesFromGateway = false;
-  cachedRemoteValues = null;
 }
 
 /**
  * Directly inject override values into the module-level cache.
  *
- * **Test-only** — bypasses file/gateway loading so unit tests can control
- * flag state without writing to disk. Production code should never call this;
- * use `clearFeatureFlagOverridesCache()` instead and let the resolver
- * re-read from the appropriate source.
- *
- * Forces `cachedRemoteValues` to an empty record (not `null`) so the resolver
- * does not fall through to reading `feature-flags-remote.json` from disk. This
- * matters because a developer's local remote-cache file can leak platform-set
- * values into the test environment (e.g. `email-channel: true`), defeating
- * test isolation.
+ * **Test-only** — bypasses the gateway IPC fetch so unit tests can control
+ * flag state without standing up a real gateway. Production code should
+ * never call this; use `clearFeatureFlagOverridesCache()` instead and let
+ * the resolver re-read from the gateway.
  */
 export function _setOverridesForTesting(
   overrides: Record<string, boolean>,
 ): void {
   cachedOverrides = { ...overrides };
   cachedOverridesFromGateway = true;
-  cachedRemoteValues = {};
 }
 
 // ---------------------------------------------------------------------------
@@ -310,9 +283,11 @@ export function _setOverridesForTesting(
  * Resolve whether an assistant feature flag is enabled.
  *
  * Resolution order:
- *   1. Override from gateway IPC socket
- *   2. defaults registry `defaultEnabled`         (for declared assistant-scope keys)
- *   3. `true`                                     (for undeclared keys with no override)
+ *   1. Override from the gateway IPC fetch (includes platform-pushed remote
+ *      values, which the gateway merges server-side: persisted > remote >
+ *      registry)
+ *   2. Registry `defaultEnabled` (for declared assistant-scope keys)
+ *   3. `true` (for undeclared keys with no override)
  */
 export function isAssistantFeatureFlagEnabled(
   key: string,
@@ -322,18 +297,13 @@ export function isAssistantFeatureFlagEnabled(
   const declared = defaults[key];
   const overrides = loadOverrides();
 
-  // 1. Check overrides from gateway / local file
+  // 1. Check overrides from the gateway IPC cache.
   const explicit = overrides[key];
   if (typeof explicit === "boolean") return explicit;
 
-  // 2. Check remote values (platform-pushed, cached locally)
-  const remote = loadRemoteValues();
-  const remoteValue = remote[key];
-  if (typeof remoteValue === "boolean") return remoteValue;
-
-  // 3. For declared keys, use the registry default
+  // 2. For declared keys, use the registry default.
   if (declared) return declared.defaultEnabled;
 
-  // 4. Undeclared keys with no persisted override default to enabled
+  // 3. Undeclared keys with no override default to enabled.
   return true;
 }