@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -1,7 +1,7 @@
 /**
  * Read the curated plugin marketplace manifest from the canonical repo.
  *
- * The manifest at `experimental/plugins/marketplace.json` whitelists external
+ * The manifest at `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
@@ -9,9 +9,9 @@
  * 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.
+ * 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
@@ -33,7 +33,7 @@ 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";
+const MARKETPLACE_FILE_PATH = "plugins/marketplace.json";
 
 // ---------------------------------------------------------------------------
 // Manifest schema (subset of the Claude Code marketplace schema)
@@ -132,23 +132,51 @@ export interface FetchMarketplaceDeps {
 /**
  * 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.
+ * signals an upstream/parse problem the caller must surface.
+ *
+ * `transient` distinguishes a retryable upstream hiccup (GitHub rate-limited
+ * us or returned a 5xx) from a hard failure (a malformed or invalid manifest).
+ * The catalog is the source of truth for installable plugins, so a transient
+ * fetch failure should map to a retryable 503 and serve a stale cache, while a
+ * hard failure surfaces as a real error.
  */
 export class MarketplaceFetchError extends Error {
-  constructor(message: string) {
+  /** Whether the failure is a retryable upstream hiccup vs a hard error. */
+  readonly transient: boolean;
+  /** Upstream HTTP status, when the failure originated from a response. */
+  readonly status?: number;
+  constructor(
+    message: string,
+    opts?: { transient?: boolean; status?: number },
+  ) {
     super(message);
     this.name = "MarketplaceFetchError";
+    this.transient = opts?.transient ?? false;
+    if (opts?.status !== undefined) this.status = opts.status;
+  }
+}
+
+/**
+ * Classify an upstream GitHub status as transient (worth retrying) vs hard.
+ * A 429 or 5xx is always transient. A 403 is GitHub's unauthenticated
+ * rate-limit signal only when the remaining-quota header is exhausted — a 403
+ * without it is a genuine authorization failure and stays hard.
+ */
+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;
 }
 
 /**
  * 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}.
+ * A missing manifest (HTTP 404) is treated as an empty whitelist — an empty
+ * catalog is a valid state, not an error. Any other HTTP failure, a non-JSON
+ * body, or a schema violation throws {@link MarketplaceFetchError}; a
+ * rate-limit or 5xx is flagged `transient` so the caller can retry.
  */
 export async function fetchMarketplaceEntries(
   deps: FetchMarketplaceDeps,
@@ -172,6 +200,7 @@ export async function fetchMarketplaceEntries(
   if (!res.ok) {
     throw new MarketplaceFetchError(
       `Marketplace manifest fetch failed for ${MARKETPLACE_FILE_PATH} @ ${ref}: HTTP ${res.status}`,
+      { transient: isTransientUpstreamStatus(res), status: res.status },
     );
   }
 
@@ -196,8 +225,7 @@ export async function fetchMarketplaceEntries(
 
 /**
  * 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).
+ * marketplace entries. Returns `null` when no entry claims the name.
  */
 export function resolveMarketplaceSource(
   name: string,

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

@@ -1,13 +1,9 @@
 /**
  * Search the installable plugin catalog in the canonical GitHub source.
  *
- * 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}).
+ * The catalog is the set of whitelisted external ecosystem plugins listed in
+ * the curated `plugins/marketplace.json` manifest, fetched from the repo at
+ * the configured git ref (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;
@@ -25,25 +21,13 @@ import { DEFAULT_PLUGIN_REF } from "./install-from-github.js";
 import {
   fetchMarketplaceEntries,
   type MarketplaceEntry,
+  MarketplaceFetchError,
 } 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`.
 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 {
   /**
@@ -62,26 +46,23 @@ export interface SearchPluginsDeps {
 }
 
 /** 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;
-    };
+export type PluginMatchSource = {
+  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 {
   /** Install name — `assistant plugins install <name>` resolves to it. */
   readonly name: string;
   /**
-   * 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.
+   * Human-readable origin of the entry: a `github:owner/repo[/path]@ref`
+   * locator for the external plugin source.
    */
   readonly path: string;
   /** Short description, when known (external entries only today). */
@@ -178,9 +159,8 @@ export interface PluginCatalog {
 }
 
 /**
- * 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.
+ * Build the full catalog at {@link opts.ref}: every whitelisted external
+ * entry in the marketplace manifest, deduped by name.
  *
  * The result is **query-independent** — `searchPlugins` applies the regex
  * filter in memory afterwards. That separation is what lets a long-lived
@@ -193,37 +173,16 @@ export async function loadPluginCatalog(
 ): 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 marketplace = await fetchMarketplaceCatalog(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 (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 { ref, matches };
@@ -245,19 +204,23 @@ function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
 }
 
 /**
- * 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.
+ * Fetch the marketplace entries, mapping a transient upstream failure to
+ * {@link PluginCatalogUnavailableError} so the cache can serve a stale catalog
+ * and the route can surface a retryable 503. A missing manifest is a normal
+ * empty catalog; a hard failure (malformed or invalid manifest) propagates
+ * as-is, since the catalog is the source of truth for installable plugins.
  */
-async function fetchMarketplaceSafe(
+async function fetchMarketplaceCatalog(
   fetchFn: FetchLike,
   ref: string,
 ): Promise<readonly MarketplaceEntry[]> {
   try {
     return await fetchMarketplaceEntries({ fetch: fetchFn }, { ref });
-  } catch {
-    return [];
+  } catch (err) {
+    if (err instanceof MarketplaceFetchError && err.transient) {
+      throw new PluginCatalogUnavailableError(err.message, err.status ?? 503);
+    }
+    throw err;
   }
 }
 
@@ -270,66 +233,3 @@ function buildMatcher(query: string): (name: string) => boolean {
   }
   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) {
-    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;
-  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.
- */
-/**
- * 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",
-      "User-Agent": "vellum-assistant-cli",
-    },
-  });
-}

package/src/cli/program.ts

@@ -49,6 +49,7 @@ import { registerStatusCommand } from "./commands/status.js";
 import { registerSttCommand } from "./commands/stt.js";
 import { registerTaskCommand } from "./commands/task.js";
 import { registerTelemetryCommand } from "./commands/telemetry.js";
+import { registerToolsCommand } from "./commands/tools.js";
 import { registerTrustCommand } from "./commands/trust.js";
 import { registerTtsCommand } from "./commands/tts.js";
 import { registerUiCommand } from "./commands/ui.js";
@@ -147,6 +148,7 @@ Examples:
   registerSttCommand(program);
   registerTaskCommand(program);
   registerTelemetryCommand(program);
+  registerToolsCommand(program);
   registerTrustCommand(program);
   registerTtsCommand(program);
   registerUiCommand(program);

package/src/config/bundled-skills/acp/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "🔗"
   vellum:
     display-name: "ACP"
+    category: "development"
     activation-hints:
       - "User asks to use Claude Code, Codex, or Gemini to do something"
       - "User wants to delegate a coding task to Claude Code, Codex, Gemini, or another ACP agent"

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -5,6 +5,7 @@ metadata:
   emoji: "🛠️"
   vellum:
     display-name: "App Builder"
+    category: "development"
     activation-hints:
       - "User asks to build a dashboard, tracker, calculator, data visualization, chart, simple landing page, or slide deck for their own use"
       - "User asks to visualize something, make a chart, or build an artifact — build a real persistent app here, never a ui_show dynamic_page"

package/src/config/bundled-skills/app-control/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "🎯"
   vellum:
     display-name: "App Control"
+    category: "system"
     feature-flag: "app-control"
     activation-hints:
       - "User explicitly directs the assistant to drive a specific named app via raw input (emulator, game, OpenGL canvas, custom-rendered Electron app)"

package/src/config/bundled-skills/computer-use/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "🖥️"
   vellum:
     display-name: "Computer Use"
+    category: "system"
     activation-hints:
       - "User asks the assistant to click, type, drag, or interact with the macOS GUI directly"
       - "User wants control of a desktop app with no CLI or API alternative (games, design tools, visual workflows)"

package/src/config/bundled-skills/contacts/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "👥"
   vellum:
     display-name: "Contacts"
+    category: "productivity"
     activation-hints:
       - "Look up contact info before asking the user for email addresses or phone numbers"
       - "User wants to manage who can message the assistant, or create/revoke invite links"

package/src/config/bundled-skills/document-editor/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "✍️"
   vellum:
     display-name: "Document Writer"
+    category: "content"
     activation-hints:
       - "User asks to write, draft, or compose an article, blog post, essay, report, story, or any long-form content — always create it in the document editor, not as a chat reply"
       - "User wants written content they will iterate on, review, or export — use the editor instead of inline markdown"

package/src/config/bundled-skills/followups/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "📨"
   vellum:
     display-name: "Followups"
+    category: "messaging"
 ---
 
 Track messages sent on external channels (email, Slack, WhatsApp, etc.) that are awaiting a response.

package/src/config/bundled-skills/image-studio/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "🎨"
   vellum:
     display-name: "Image Studio"
+    category: "content"
     activation-hints:
       - "User asks to generate, draw, or create an image from a text prompt"
       - "User wants to edit an existing image — background removal, in-painting, style change, retouching"

package/src/config/bundled-skills/media-processing/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "🎬"
   vellum:
     display-name: "Media Processing"
+    category: "content"
     activation-hints:
       - "User wants to ingest, process, or analyze a local video, audio, or image file"
       - "User wants to ask natural-language questions about a video's content (e.g. 'what happens at 3:14', 'find all the goals', 'who appears in this footage')"

package/src/config/bundled-skills/messaging/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "\U0001F4AC"
   vellum:
     display-name: "Messaging"
+    category: "messaging"
     activation-hints:
       - "Email, messaging, inbox management, read/send/search on any platform"
       - "Handles credential flows -- do not improvise setup instructions"

package/src/config/bundled-skills/phone-calls/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "📞"
   vellum:
     display-name: "Phone Calls"
+    category: "voice"
     includes:
       - "twilio-setup"
       - "public-ingress"

package/src/config/bundled-skills/playbooks/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "📖"
   vellum:
     display-name: "Playbooks"
+    category: "productivity"
 ---
 
 Playbooks are trigger-action automation rules that tell the assistant how to handle incoming messages matching a pattern.

package/src/config/bundled-skills/schedule/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "📅"
   vellum:
     display-name: "Schedule"
+    category: "productivity"
     activation-hints:
       - "User wants to set a reminder for a future time (e.g. 'remind me at 9am tomorrow', 'remind me to take meds at 8pm')"
       - "User wants to schedule a recurring task or automation (e.g. 'every weekday at 9am', 'every Monday at noon')"

package/src/config/bundled-skills/schedule/TOOLS.json

@@ -3,7 +3,7 @@
   "tools": [
     {
       "name": "schedule_create",
-      "description": "Create a scheduled automation. For recurring: provide expression (cron/RRULE). For one-time: provide fire_at (ISO 8601 timestamp). ONLY use this when the user explicitly wants something to run on a schedule (e.g. \"every day at 9am\", \"remind me tomorrow at 3pm\", \"weekly on Mondays\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" - use task_list_add for those requests instead.",
+      "description": "Create a scheduled automation. Always provide a concise description of what the schedule does and why. For recurring: provide expression (cron/RRULE). For one-time: provide fire_at (ISO 8601 timestamp). ONLY use this when the user explicitly wants something to run on a schedule (e.g. \"every day at 9am\", \"remind me tomorrow at 3pm\", \"weekly on Mondays\"). Do NOT use this for \"add to my tasks\" or \"add to my queue\" - use task_list_add for those requests instead.",
       "category": "schedule",
       "risk": "medium",
       "input_schema": {
@@ -13,6 +13,10 @@
             "type": "string",
             "description": "A human-readable name for the scheduled task"
           },
+          "description": {
+            "type": "string",
+            "description": "Required concise authored description of what it does and why. Keep this distinct from the timing/cadence."
+          },
           "syntax": {
             "type": "string",
             "enum": ["cron", "rrule"],
@@ -77,7 +81,7 @@
             "description": "For script mode: maximum time in milliseconds the shell command may run before it is killed. Defaults to 60000 (60s). Allowed range: 1000 to 1800000."
           }
         },
-        "required": ["name"]
+        "required": ["name", "description"]
       },
       "executor": "tools/schedule-create.ts",
       "execution_target": "host"
@@ -106,7 +110,7 @@
     },
     {
       "name": "schedule_update",
-      "description": "Update an existing scheduled automation (expression, syntax, message, name, enabled state, mode, or routing)",
+      "description": "Update an existing scheduled automation (expression, syntax, message, name, description, enabled state, mode, or routing)",
       "category": "schedule",
       "risk": "medium",
       "input_schema": {
@@ -120,6 +124,10 @@
             "type": "string",
             "description": "New name for the job"
           },
+          "description": {
+            "type": "string",
+            "description": "New concise authored description of what the schedule does and why. Keep this distinct from the timing/cadence."
+          },
           "syntax": {
             "type": "string",
             "enum": ["cron", "rrule"],

package/src/config/bundled-skills/sequences/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "📧"
   vellum:
     display-name: "Email Sequences"
+    category: "email"
 ---
 
 You are an email sequence assistant. Use the sequence tools to help users create and manage automated multi-step email drip campaigns.

package/src/config/bundled-skills/settings/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   emoji: "\u2699\uFE0F"
   vellum:
     display-name: "Settings"
+    category: "system"
     activation-hints:
       - "User wants to change the assistant's voice, TTS provider, or speech output"
       - "User wants to rebind the push-to-talk key or adjust microphone / conversation timeout"