@vellumai/assistant 0.12.2-staging.5 → 0.12.2-staging.6

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

@@ -1,17 +1,16 @@
 /**
  * Read the curated plugin marketplace manifest from the canonical repo.
  *
- * 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
- * (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.
+ * The manifest at `plugins/marketplace.json` whitelists reviewed plugins so
+ * they appear in `assistant plugins search` / the web catalog and become
+ * installable by name. Its shape extends the Claude Code marketplace manifest
+ * (https://code.claude.com/docs/en/plugin-marketplaces) with packages embedded
+ * in the assistant distribution.
  *
- * 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 both fetched from the repo at a git ref and bundled into the
+ * assistant build. GitHub entries may grow without a new release. Local entries
+ * can only resolve when their exact path and version are embedded in that
+ * 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
@@ -60,7 +59,7 @@ const PLUGIN_NAME_RE = /^[a-z0-9][a-z0-9_-]*$/;
 const COMMIT_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
 
 export const githubSourceSchema = z.object({
-  /** Discriminator. Only GitHub sources are resolved today. */
+  /** Discriminator for a reviewed external repository. */
   source: z.literal("github"),
   /** `owner/repo` of the external plugin repository. */
   repo: z.string().regex(REPO_SLUG_RE, "expected an `owner/repo` slug"),
@@ -89,10 +88,53 @@ export const githubSourceSchema = z.object({
     ),
 });
 
+/**
+ * A plugin package shipped inside the assistant distribution. The path is a
+ * key into the generated bundled-package map, never a path resolved from the
+ * current working directory.
+ */
+export const localSourceSchema = z.object({
+  source: z.literal("local"),
+  path: z
+    .string()
+    .regex(/^plugins\/[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+$/)
+    .refine(
+      (path) =>
+        !path
+          .split(/[/\\]/)
+          .some((segment) => segment === "." || segment === ".."),
+      "path must be a clean bundled-package path",
+    ),
+  version: z.string().min(1),
+  repo: z.never().optional(),
+  ref: z.never().optional(),
+});
+
+export const marketplaceSourceSchema = z.discriminatedUnion("source", [
+  githubSourceSchema,
+  localSourceSchema,
+]);
+
+export const mcpIntegrationSchema = z.object({
+  kind: z.literal("mcp"),
+  displayName: z.string().min(1),
+  documentationUrl: z.string().url(),
+  verifiedAt: z.iso.date(),
+  verification: z.literal("documentation-only"),
+  setup: z.object({
+    mode: z.enum(["oauth", "manual"]),
+    instructions: z.string().min(1),
+  }),
+  /** Filename under the web client's bundled integration-image directory. */
+  logo: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]*$/),
+  /** Existing main OAuth provider used to group a related MCP connection. */
+  oauthProvider: z.string().regex(PLUGIN_NAME_RE).optional(),
+});
+
 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,
+  source: marketplaceSourceSchema,
   description: z.string().optional(),
   /** Free-form grouping hint (e.g. `productivity`). Informational. */
   category: z.string().optional(),
@@ -111,9 +153,10 @@ const marketplaceEntrySchema = z.object({
       "expected a short emoji, not a URL or path",
     )
     .optional(),
+  integration: mcpIntegrationSchema.optional(),
 });
 
-export const marketplaceManifestSchema = z.object({
+const marketplaceManifestBaseSchema = z.object({
   name: z.string(),
   owner: z
     .object({
@@ -122,14 +165,33 @@ export const marketplaceManifestSchema = z.object({
       email: z.string().optional(),
     })
     .optional(),
+});
+
+export const marketplaceManifestSchema = marketplaceManifestBaseSchema.extend({
   plugins: z.array(marketplaceEntrySchema),
 });
 
-/** A single whitelisted external plugin entry. */
+const fetchedMarketplaceManifestSchema = marketplaceManifestBaseSchema.extend({
+  plugins: z.array(z.unknown()),
+});
+
+function readSourceDiscriminator(entry: unknown): unknown {
+  if (typeof entry !== "object" || entry === null) {
+    return null;
+  }
+  const source = (entry as Record<string, unknown>).source;
+  if (typeof source !== "object" || source === null) {
+    return null;
+  }
+  return (source as Record<string, unknown>).source;
+}
+
+/** A single reviewed plugin entry. */
 export type MarketplaceEntry = z.infer<typeof marketplaceEntrySchema>;
 
 /** Concrete GitHub coordinates an entry resolves to for install. */
-export interface ResolvedPluginSource {
+export interface ResolvedGitHubPluginSource {
+  readonly kind: "github";
   readonly owner: string;
   readonly repo: string;
   /** Directory within the repo holding the plugin root; `""` = repo root. */
@@ -138,6 +200,17 @@ export interface ResolvedPluginSource {
   readonly ref: string;
 }
 
+/** Concrete bundled-package coordinates an entry resolves to for install. */
+export interface ResolvedLocalPluginSource {
+  readonly kind: "local";
+  readonly path: string;
+  readonly version: string;
+}
+
+export type ResolvedPluginSource =
+  | ResolvedGitHubPluginSource
+  | ResolvedLocalPluginSource;
+
 /** Options controlling which marketplace revision to read. */
 export interface FetchMarketplaceOptions {
   /** Ref of the canonical repo to read the manifest from. */
@@ -236,23 +309,42 @@ export async function fetchMarketplaceEntries(
     json = JSON.parse(await res.text());
   } catch (err) {
     throw new MarketplaceFetchError(
-      `Marketplace manifest is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+      `Marketplace manifest is not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
     );
   }
 
-  const parsed = marketplaceManifestSchema.safeParse(json);
+  const parsed = fetchedMarketplaceManifestSchema.safeParse(json);
   if (!parsed.success) {
     throw new MarketplaceFetchError(
       `Marketplace manifest failed validation: ${parsed.error.message}`,
     );
   }
-
-  return parsed.data.plugins;
+  const entries: MarketplaceEntry[] = [];
+  for (const rawEntry of parsed.data.plugins) {
+    const sourceKind = readSourceDiscriminator(rawEntry);
+    if (
+      typeof sourceKind === "string" &&
+      sourceKind !== "github" &&
+      sourceKind !== "local"
+    ) {
+      continue;
+    }
+    const entry = marketplaceEntrySchema.safeParse(rawEntry);
+    if (!entry.success) {
+      throw new MarketplaceFetchError(
+        `Marketplace manifest failed validation: ${entry.error.message}`,
+      );
+    }
+    entries.push(entry.data);
+  }
+  return entries;
 }
 
 /**
- * Resolve a plugin name to concrete GitHub coordinates using the supplied
- * marketplace entries. Returns `null` when no entry claims the name.
+ * Resolve a plugin name to its exact source using the supplied marketplace
+ * entries. Returns `null` when no entry claims the name.
  */
 export function resolveMarketplaceSource(
   name: string,
@@ -262,8 +354,16 @@ export function resolveMarketplaceSource(
   if (!entry) {
     return null;
   }
+  if (entry.source.source === "local") {
+    return {
+      kind: "local",
+      path: entry.source.path,
+      version: entry.source.version,
+    };
+  }
   const [owner, repo] = entry.source.repo.split("/", 2) as [string, string];
   return {
+    kind: "github",
     owner,
     repo,
     path: entry.source.path ?? "",

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

@@ -130,7 +130,9 @@ async function listManifestCommits(
     body = JSON.parse(await res.text());
   } catch (err) {
     throw new PluginPinHistoryError(
-      `Marketplace commit history is not valid JSON: ${err instanceof Error ? err.message : String(err)}`,
+      `Marketplace commit history is not valid JSON: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
     );
   }
   if (!Array.isArray(body)) {
@@ -166,7 +168,8 @@ async function pinAtCommit(
     { fetch: fetchFn },
     { ref: marketplaceCommit },
   );
-  return entries.find((e) => e.name === name)?.source.ref ?? null;
+  const source = entries.find((entry) => entry.name === name)?.source;
+  return source?.source === "github" ? source.ref : null;
 }
 
 /**

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

@@ -22,26 +22,49 @@ export interface SearchPluginsDeps {
 }
 
 /** Where a catalog match comes from. */
-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;
-};
+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;
+    }
+  | {
+      readonly kind: "local";
+      /** Exact package key in the assistant's embedded plugin bundle. */
+      readonly path: string;
+      readonly version: string;
+      readonly repo?: undefined;
+      readonly ref?: undefined;
+    };
+
+export interface McpPluginIntegration {
+  readonly kind: "mcp";
+  readonly displayName: string;
+  readonly documentationUrl: string;
+  readonly verifiedAt: string;
+  readonly verification: "documentation-only";
+  readonly setup: {
+    readonly mode: "oauth" | "manual";
+    readonly instructions: string;
+  };
+  readonly logo: string;
+  readonly oauthProvider?: 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: a `github:owner/repo[/path]@ref`
-   * locator for the external plugin source.
+   * Human-readable origin: either `github:owner/repo[/path]@ref` or
+   * `local:plugins/path@version`.
    */
   readonly path: string;
-  /** Short description, when known (external entries only today). */
+  /** Short description, when known. */
   readonly description?: string;
   /**
    * Plugin icon: a curated emoji from the marketplace entry, or an icon URL
@@ -57,6 +80,7 @@ export interface PluginSearchMatch {
   readonly homepage?: string;
   /** License identifier, from the curated marketplace entry when present. */
   readonly license?: string;
+  readonly integration?: McpPluginIntegration;
   /** Discriminated origin, so callers can render/install accordingly. */
   readonly source: PluginMatchSource;
 }
@@ -121,14 +145,31 @@ export interface PluginCatalog {
 
 /**
  * Project a marketplace entry onto the catalog match shape, building a
- * `github:owner/repo[/path]@ref` locator for display.
+ * a source-specific locator for display.
  *
  * Shared by the platform fetcher and bundled reader so all catalog sources
  * project entries identically.
  */
 export function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
-  const { repo, path, ref } = entry.source;
-  const locator = `github:${repo}${path ? `/${path}` : ""}@${ref}`;
+  const source: PluginMatchSource =
+    entry.source.source === "github"
+      ? {
+          kind: "github",
+          repo: entry.source.repo,
+          path: entry.source.path,
+          ref: entry.source.ref,
+        }
+      : {
+          kind: "local",
+          path: entry.source.path,
+          version: entry.source.version,
+        };
+  const locator =
+    source.kind === "github"
+      ? `github:${source.repo}${source.path ? `/${source.path}` : ""}@${
+          source.ref
+        }`
+      : `local:${source.path}@${source.version}`;
   return {
     name: entry.name,
     path: locator,
@@ -137,7 +178,8 @@ export function marketplaceMatch(entry: MarketplaceEntry): PluginSearchMatch {
     category: entry.category ?? null,
     homepage: entry.homepage,
     license: entry.license,
-    source: { kind: "github", repo, path, ref },
+    integration: entry.integration,
+    source,
   };
 }
 

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

@@ -64,6 +64,7 @@ import {
   finalizeStagedInstall,
   type GitRunner,
   installPlugin,
+  type InstallPluginDeps,
   isFullCommitSha,
   materializePluginTree,
   type PluginFetchSource,
@@ -94,6 +95,7 @@ import {
   type PluginUpgradeStrategy,
 } from "./plugin-constants.js";
 import { computeFingerprint, fingerprintsEqual } from "./plugin-fingerprint.js";
+import type { PluginCatalog } from "./search-plugins.js";
 import { PluginNotInstalledError } from "./uninstall-plugin.js";
 
 /**
@@ -167,6 +169,8 @@ export interface UpgradePluginDeps {
    * upgrades alike; dry runs and no-ops never stage, so it is not invoked.
    */
   readonly confirmStaged?: ConfirmStagedInstall;
+  readonly materializeLocalPackage?: InstallPluginDeps["materializeLocalPackage"];
+  readonly localCatalog?: PluginCatalog;
 }
 
 /** Result of an upgrade attempt. */
@@ -317,7 +321,11 @@ export async function upgradePlugin(
   try {
     inspection = await inspectPlugin(
       { name },
-      { fetch: deps.fetch, workspacePluginsDir: deps.workspacePluginsDir },
+      {
+        fetch: deps.fetch,
+        workspacePluginsDir: deps.workspacePluginsDir,
+        localCatalog: deps.localCatalog,
+      },
     );
   } catch (err) {
     if (err instanceof PluginInspectNotFoundError) {
@@ -373,6 +381,19 @@ export async function upgradePlugin(
   const toTimestamp = remote.committedAt;
   const provenanceWasUnknown = inspection.status === "unknown-provenance";
 
+  const localSource = local.source;
+  const sourceChanged =
+    remote.kind === "local"
+      ? localSource?.kind !== "local" || localSource.path !== remote.path
+      : localSource?.kind === "local";
+  if (sourceChanged) {
+    throw new PluginNotUpgradableError(
+      name,
+      "its marketplace source changed; reinstall explicitly with 'plugins install " +
+        `${name} --force' to accept the new source`,
+    );
+  }
+
   if (inspection.status === "up-to-date") {
     return {
       name,
@@ -417,6 +438,12 @@ export async function upgradePlugin(
     strategy === "theirs" ||
     strategy === "assistant"
   ) {
+    if (remote.kind === "local") {
+      throw new PluginMergeBaselineError(
+        name,
+        "bundled packages do not retain the previous package version needed for a three-way merge",
+      );
+    }
     const [remoteOwner, remoteRepo] = remote.repo.split("/");
     return mergeUpgrade(
       {
@@ -445,7 +472,19 @@ export async function upgradePlugin(
   }
 
   const result = await installPlugin(
-    { name, force: true },
+    {
+      name,
+      force: true,
+      ...(remote.kind === "local"
+        ? {
+            trustedSource: {
+              kind: "local" as const,
+              path: remote.path,
+              version: remote.version ?? remote.commit,
+            },
+          }
+        : {}),
+    },
     {
       fetch: deps.fetch,
       workspacePluginsDir: deps.workspacePluginsDir,
@@ -454,6 +493,7 @@ export async function upgradePlugin(
       runInstallDeps: deps.runInstallDeps,
       beforeSwap: deps.beforeSwap,
       confirmStaged: deps.confirmStaged,
+      materializeLocalPackage: deps.materializeLocalPackage,
     },
   );
 
@@ -716,7 +756,12 @@ async function mergeUpgrade(
   };
 
   const meta = readInstallMeta(local.target);
-  if (!meta || !meta.commit || !meta.fingerprint) {
+  if (
+    !meta ||
+    meta.source.kind !== "github" ||
+    !meta.commit ||
+    !meta.fingerprint
+  ) {
     throw new PluginMergeBaselineError(
       name,
       "no install commit or fingerprint was recorded (an older or manually-copied install)",

package/src/config/bundled-skills/skill-management/SKILL.md

@@ -28,7 +28,7 @@ Do NOT use this skill when the user just wants to run an existing skill. That is
 ## Capabilities
 
 - **Scaffold** a new managed skill with YAML frontmatter and markdown body
-- **Edit** an existing skill by scaffolding over it (rewrites the SKILL.md in place)
+- **Edit** an existing skill by scaffolding over it (replaces the body and needs `activation_hints` restated; every other frontmatter field you leave out keeps its current value, and an empty value clears one)
 - **Delete** an existing managed skill directory
 
 Skills created via `scaffold_managed_skill` become available for `skill_load` when a valid top-level `SKILL.md` is written under the skill directory.

package/src/config/bundled-skills/skill-management/TOOLS.json

@@ -27,15 +27,15 @@
           },
           "emoji": {
             "type": "string",
-            "description": "Optional emoji icon for the skill."
+            "description": "Optional emoji icon for the skill. On an overwrite, omit to keep the current one; pass an empty string to clear it."
           },
           "category": {
             "type": "string",
-            "description": "Optional single lowercase category for grouping the skill in the Skills UI sidebar. Must be one of the published categories — a value outside this list shows under All with no sidebar bucket, so always pick the closest fit: browsing, calendar, commerce, content, development, email, health, integrations, messaging, productivity, system, voice."
+            "description": "Optional single lowercase category for grouping the skill in the Skills UI sidebar. Must be one of the published categories: a value outside this list shows under All with no sidebar bucket, so always pick the closest fit: browsing, calendar, commerce, content, development, email, health, integrations, messaging, productivity, system, voice. On an overwrite, omit to keep the current category; pass an empty string to clear it."
           },
           "overwrite": {
             "type": "boolean",
-            "description": "Whether to overwrite an existing skill with the same ID (default: false)."
+            "description": "Whether to overwrite an existing skill with the same ID (default: false). An overwrite always replaces the body and must restate activation_hints; every other frontmatter field keeps its current value when omitted (emoji, category, includes, avoid_when, and anything else the file carries), and an empty value clears one."
           },
           "change_summary": {
             "type": "string",
@@ -44,17 +44,17 @@
           "includes": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional list of child skill IDs this skill composes. When this skill is loaded via skill_load, each child's body is inlined after the parent's and the child's tools are projected, so the parent can rely on the child's procedure without re-stating it. Does not affect which skills get selected for a turn."
+            "description": "Optional list of child skill IDs this skill composes. When this skill is loaded via skill_load, each child's body is inlined after the parent's and the child's tools are projected, so the parent can rely on the child's procedure without re-stating it. Does not affect which skills get selected for a turn. On an overwrite, omit to keep the current list; pass an empty list to clear it."
           },
           "activation_hints": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Required. 1-4 short trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name. Scaffolding rewrites the whole SKILL.md, so an overwrite must pass the hints the skill should keep, revised if the procedure changed."
+            "description": "Required. 1-4 short trigger phrases describing the situations where this skill should activate, phrased as the observed intent (e.g. \"user asks to deploy staging\"). Surfaced in memory as a \"Use when: …\" clause so the skill is retrievable by intent, not just by name. Required on an overwrite too: the hints should track the body, so restate them, revised if the procedure changed."
           },
           "avoid_when": {
             "type": "array",
             "items": { "type": "string" },
-            "description": "Optional situations where this skill should NOT be used. Surfaced in memory as an \"Avoid when: …\" clause to steer retrieval away from the wrong contexts."
+            "description": "Optional situations where this skill should NOT be used. Surfaced in memory as an \"Avoid when: …\" clause to steer retrieval away from the wrong contexts. On an overwrite, omit to keep the current list; pass an empty list to clear it."
           },
           "files": {
             "type": "array",

package/src/daemon/conversation-tool-setup.ts

@@ -45,11 +45,8 @@ import {
   injectActivityField,
   stripActivityField,
 } from "../tools/schema-transforms.js";
-import {
-  augmentSkillExecuteError,
-  recoverSkillExecuteEnvelope,
-  resolveSkillExecuteInput,
-} from "../tools/skills/execute.js";
+import { augmentSkillExecuteError } from "../tools/skills/execute.js";
+import { resolveSkillExecuteInvocation } from "../tools/skills/resolve-execute-invocation.js";
 import { resolveToolInvocationAlias } from "../tools/tool-name-aliases.js";
 import type {
   ProxyApprovalCallback,
@@ -535,23 +532,8 @@ export function createToolExecutor(
     // risk level, permission checks, hooks, and lifecycle events all fire
     // with the real tool name.
     if (executionName === "skill_execute") {
-      // Recover an envelope the provider wrapped as unparseable when MiniMax's
-      // coercion failed to JSON-decode a bare-string `input` (see
-      // recoverSkillExecuteEnvelope), then resolve the inner tool + params.
-      const envelope = recoverSkillExecuteEnvelope(executionInput);
-      const rawToolName =
-        typeof envelope.tool === "string" ? envelope.tool : "";
-      const innerSchema = rawToolName
-        ? getTool(rawToolName)?.input_schema
-        : undefined;
-      const rawToolInput = resolveSkillExecuteInput(envelope, innerSchema);
-
-      // Clone to avoid mutating shared input objects
-      const { name: toolName, input: toolInput } = resolveToolInvocationAlias(
-        rawToolName,
-        { ...rawToolInput },
-        ctx.allowedToolNames,
-      );
+      const { name: toolName, input: toolInput } =
+        resolveSkillExecuteInvocation(executionInput, ctx.allowedToolNames);
 
       if (!toolName) {
         return {