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

package/Dockerfile

@@ -130,13 +130,13 @@ RUN bun run scripts/smoke-container-workspace-dependencies.ts
 # The repo-root .dockerignore decides which skills (and files) ship.
 COPY skills /app/skills
 
-# Materialize the git-ignored offline plugin manifest from its canonical source.
-# `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
-# (loaded even when platform features are enabled), so it must exist in the image
-# — the build installs with --ignore-scripts, so the postinstall sync that
-# regenerates it in dev never runs here. Mirrors how CI materializes the
-# feature-flag registry before building.
-COPY plugins/marketplace.json /app/assistant/src/cli/lib/bundled-marketplace.json
+# Materialize the git-ignored offline marketplace and reviewed local packages.
+# The build installs with --ignore-scripts, so the postinstall sync that creates
+# these static imports in development never runs here.
+COPY plugins /app/plugins
+COPY meta/sync-bundled-copies.ts /app/meta/
+RUN cd /app && bun run meta/sync-bundled-copies.ts --plugins-only && \
+    bun run assistant/scripts/generate-bundled-plugin-packages.ts
 
 # Install assistant CLI launcher backed by the bundled assistant package
 RUN printf '#!/usr/bin/env sh\nexec bun run /app/assistant/src/index.ts "$@"\n' > /usr/local/bin/assistant && \

package/openapi.yaml

@@ -26622,26 +26622,44 @@ paths:
                     description: Resolved version (installed copy first, then repo `package.json`).
                   source:
                     anyOf:
-                      - type: object
-                        properties:
-                          kind:
-                            type: string
-                            const: github
-                          repo:
-                            type: string
-                            description: "`owner/repo` of the external plugin repository."
-                          path:
-                            description: Directory within the repo, when the plugin is not at the root.
-                            type: string
-                          ref:
-                            type: string
-                            description: Pinned git ref the plugin is fetched from.
-                        required:
-                          - kind
-                          - repo
-                          - ref
-                        additionalProperties: false
-                        description: "Origin of the match: a whitelisted external plugin repository."
+                      - oneOf:
+                          - type: object
+                            properties:
+                              kind:
+                                type: string
+                                const: github
+                              repo:
+                                type: string
+                                description: "`owner/repo` of the external plugin repository."
+                              path:
+                                description: Directory within the repo, when the plugin is not at the root.
+                                type: string
+                              ref:
+                                type: string
+                                description: Pinned git ref the plugin is fetched from.
+                            required:
+                              - kind
+                              - repo
+                              - ref
+                            additionalProperties: false
+                          - type: object
+                            properties:
+                              kind:
+                                type: string
+                                const: local
+                              path:
+                                type: string
+                                description: Package key in the assistant bundle.
+                              version:
+                                type: string
+                                description: Bundled package version.
+                            required:
+                              - kind
+                              - path
+                              - version
+                            additionalProperties: false
+                        description: Reviewed source of the marketplace entry.
+                        type: object
                       - type: "null"
                     description: Pinned origin from the marketplace entry, or null when an installed copy has no catalog entry.
                   readme:
@@ -26996,28 +27014,42 @@ paths:
                             description: ISO-8601 install timestamp from the sidecar; null when absent.
                           source:
                             anyOf:
-                              - type: object
-                                properties:
-                                  kind:
-                                    type: string
-                                    description: Source kind. Only `github` is written today.
-                                  owner:
-                                    type: string
-                                  repo:
-                                    type: string
-                                  path:
-                                    description: Repo-relative directory holding the plugin root; absent = repo root.
-                                    type: string
-                                  ref:
-                                    type: string
-                                    description: Ref the install resolved through (the pinned commit SHA for marketplace installs).
-                                required:
-                                  - kind
-                                  - owner
-                                  - repo
-                                  - ref
-                                additionalProperties: false
+                              - oneOf:
+                                  - type: object
+                                    properties:
+                                      kind:
+                                        type: string
+                                        const: github
+                                      owner:
+                                        type: string
+                                      repo:
+                                        type: string
+                                      path:
+                                        type: string
+                                      ref:
+                                        type: string
+                                    required:
+                                      - kind
+                                      - owner
+                                      - repo
+                                      - ref
+                                    additionalProperties: false
+                                  - type: object
+                                    properties:
+                                      kind:
+                                        type: string
+                                        const: local
+                                      path:
+                                        type: string
+                                      version:
+                                        type: string
+                                    required:
+                                      - kind
+                                      - path
+                                      - version
+                                    additionalProperties: false
                                 description: Source coordinates recorded in the install-time provenance sidecar.
+                                type: object
                               - type: "null"
                             description: Source recorded at install time; null when no sidecar exists.
                           localChanges:
@@ -27076,6 +27108,9 @@ paths:
                     anyOf:
                       - type: object
                         properties:
+                          kind:
+                            type: string
+                            const: local
                           repo:
                             type: string
                             description: "`owner/repo` of the external plugin repository."
@@ -27111,6 +27146,9 @@ paths:
                           marketplaceRef:
                             type: string
                             description: Ref of the canonical repo the marketplace manifest was read from.
+                          version:
+                            description: Bundled package version.
+                            type: string
                         required:
                           - repo
                           - path
@@ -27547,7 +27585,7 @@ paths:
                           description: Install name. Matches `assistant plugins install <name>`.
                         path:
                           type: string
-                          description: "Human-readable origin: a `github:owner/repo@ref` locator for the external plugin."
+                          description: Human-readable catalog origin locator.
                         description:
                           description: Short description, when known (external entries only today).
                           type: string
@@ -27561,27 +27599,87 @@ paths:
                             - type: string
                             - type: "null"
                           description: Marketplace category slug (Skills taxonomy); null when the entry declares none.
-                        source:
+                        integration:
                           type: object
                           properties:
                             kind:
                               type: string
-                              const: github
-                            repo:
+                              const: mcp
+                            displayName:
+                              type: string
+                            documentationUrl:
                               type: string
-                              description: "`owner/repo` of the external plugin repository."
-                            path:
-                              description: Directory within the repo, when the plugin is not at the root.
+                            verifiedAt:
+                              type: string
+                            verification:
+                              type: string
+                              const: documentation-only
+                            setup:
+                              type: object
+                              properties:
+                                mode:
+                                  type: string
+                                  enum:
+                                    - oauth
+                                    - manual
+                                instructions:
+                                  type: string
+                              required:
+                                - mode
+                                - instructions
+                              additionalProperties: false
+                            logo:
                               type: string
-                            ref:
+                            oauthProvider:
                               type: string
-                              description: Pinned git ref the plugin is fetched from.
                           required:
                             - kind
-                            - repo
-                            - ref
+                            - displayName
+                            - documentationUrl
+                            - verifiedAt
+                            - verification
+                            - setup
+                            - logo
                           additionalProperties: false
-                          description: "Origin of the match: a whitelisted external plugin repository."
+                        source:
+                          oneOf:
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: github
+                                repo:
+                                  type: string
+                                  description: "`owner/repo` of the external plugin repository."
+                                path:
+                                  description: Directory within the repo, when the plugin is not at the root.
+                                  type: string
+                                ref:
+                                  type: string
+                                  description: Pinned git ref the plugin is fetched from.
+                              required:
+                                - kind
+                                - repo
+                                - ref
+                              additionalProperties: false
+                            - type: object
+                              properties:
+                                kind:
+                                  type: string
+                                  const: local
+                                path:
+                                  type: string
+                                  description: Package key in the assistant bundle.
+                                version:
+                                  type: string
+                                  description: Bundled package version.
+                              required:
+                                - kind
+                                - path
+                                - version
+                              additionalProperties: false
+                          description: Reviewed source of the marketplace entry.
+                          type: object
                       required:
                         - name
                         - path

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.2-staging.4",
+  "version": "0.12.2-staging.6",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -24,16 +24,17 @@
     "lint:unused": "knip --include files,dependencies,unlisted",
     "lint:circular": "bun run scripts/check-circular-deps.ts",
     "lint:unused:production": "knip --production --include exports",
-    "pretypecheck": "cd .. && bun run meta/sync-bundled-copies.ts",
+    "sync:bundled-catalog": "cd .. && bun run meta/sync-bundled-copies.ts && bun run assistant/scripts/generate-bundled-plugin-packages.ts",
+    "pretypecheck": "bun run sync:bundled-catalog",
     "typecheck": "bunx tsc --noEmit",
-    "pretypecheck:fast": "cd .. && bun run meta/sync-bundled-copies.ts",
+    "pretypecheck:fast": "bun run sync:bundled-catalog",
     "typecheck:fast": "bunx tsgo --noEmit",
     "test": "bun run scripts/test.ts",
     "test:coverage": "COVERAGE=true bun run scripts/test.ts",
     "test:stable": "EXCLUDE_EXPERIMENTAL=true bun run scripts/test.ts",
     "test:bench": "find src -type f -name '*.benchmark.test.ts' -print0 | xargs -0 -P 1 -I {} bun test {}",
     "test:filesystem-tools": "bash scripts/test-filesystem-tools.sh",
-    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/sync-bundled-copies.ts ] && bun run meta/sync-bundled-copies.ts 2>/dev/null || true)"
+    "postinstall": "cd .. && (git config core.hooksPath || git config core.hooksPath .githooks 2>/dev/null || true) && ([ -f meta/sync-bundled-copies.ts ] && (bun run meta/sync-bundled-copies.ts && bun run assistant/scripts/generate-bundled-plugin-packages.ts) 2>/dev/null || true)"
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "0.25.0",

package/scripts/bundled-plugin-packages.ts

@@ -0,0 +1,154 @@
+import { lstatSync, readdirSync, readFileSync, realpathSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+
+import {
+  AGENT_PLUGINS_MCP_SCHEMA_URL,
+  SpecMcpDocumentSchema,
+  SpecMcpServerSchema,
+} from "../src/mcp/spec-schema.js";
+import {
+  readPluginManifest,
+  STANDARD_PLUGIN_MANIFEST,
+} from "../src/util/plugin-manifest.js";
+
+export interface BundledPackageFile {
+  path: string;
+  contentBase64: string;
+}
+
+export interface BundledPackage {
+  version: string;
+  files: BundledPackageFile[];
+}
+
+/** Validate and embed every local source in the canonical marketplace. */
+export function buildBundledPluginPackages(
+  repoRoot: string,
+): Record<string, BundledPackage> {
+  const marketplacePath = join(repoRoot, "plugins", "marketplace.json");
+  const manifest = JSON.parse(readFileSync(marketplacePath, "utf8")) as {
+    plugins?: unknown;
+  };
+  if (!Array.isArray(manifest.plugins)) {
+    throw new Error("plugins/marketplace.json is missing its plugins array");
+  }
+
+  const pluginsRoot = realpathSync(join(repoRoot, "plugins"));
+  const packages: Record<string, BundledPackage> = {};
+  for (const rawEntry of manifest.plugins) {
+    if (typeof rawEntry !== "object" || rawEntry === null) {
+      continue;
+    }
+    const entry = rawEntry as Record<string, unknown>;
+    const rawSource = entry.source;
+    if (typeof rawSource !== "object" || rawSource === null) {
+      continue;
+    }
+    const source = rawSource as Record<string, unknown>;
+    if (source.source !== "local") {
+      continue;
+    }
+    if (
+      typeof entry.name !== "string" ||
+      typeof source.path !== "string" ||
+      typeof source.version !== "string"
+    ) {
+      throw new Error(
+        "local marketplace entries require name, path, and version",
+      );
+    }
+
+    const pathSegments = source.path.split("/");
+    if (
+      !source.path.startsWith("plugins/") ||
+      source.path.includes("\\") ||
+      pathSegments.some(
+        (segment) => segment === "" || segment === "." || segment === "..",
+      )
+    ) {
+      throw new Error(
+        `local marketplace package path is not canonical: ${source.path}`,
+      );
+    }
+    let packageRoot = resolve(repoRoot);
+    for (const segment of pathSegments) {
+      packageRoot = join(packageRoot, segment);
+      if (lstatSync(packageRoot).isSymbolicLink()) {
+        throw new Error(
+          `local marketplace package path may not contain symlinks: ${source.path}`,
+        );
+      }
+    }
+    const packageRealpath = realpathSync(packageRoot);
+    const relativeToPlugins = relative(pluginsRoot, packageRealpath);
+    if (
+      relativeToPlugins === "" ||
+      relativeToPlugins === ".." ||
+      relativeToPlugins.startsWith(`..${sep}`)
+    ) {
+      throw new Error(
+        `local marketplace package escapes plugins/: ${source.path}`,
+      );
+    }
+
+    const pluginManifest = readPluginManifest(packageRealpath);
+    if (
+      pluginManifest.source !== STANDARD_PLUGIN_MANIFEST ||
+      pluginManifest.name !== entry.name ||
+      pluginManifest.version !== source.version
+    ) {
+      throw new Error(
+        `local marketplace package ${source.path} must match entry name and version`,
+      );
+    }
+    const rawMcp = JSON.parse(
+      readFileSync(join(packageRealpath, "mcp.json"), "utf8"),
+    ) as unknown;
+    const mcp = SpecMcpDocumentSchema.parse(rawMcp);
+    if (mcp.$schema !== AGENT_PLUGINS_MCP_SCHEMA_URL) {
+      throw new Error(
+        `local marketplace package ${source.path} must use the Agent Plugins MCP schema`,
+      );
+    }
+    if (Object.keys(mcp.mcpServers).length === 0) {
+      throw new Error(
+        `local marketplace package ${source.path} must declare an MCP server`,
+      );
+    }
+    for (const server of Object.values(mcp.mcpServers)) {
+      SpecMcpServerSchema.parse(server);
+    }
+
+    const files: BundledPackageFile[] = [];
+    const visit = (directory: string): void => {
+      for (const child of readdirSync(directory, { withFileTypes: true })) {
+        const childPath = join(directory, child.name);
+        if (child.isSymbolicLink() || lstatSync(childPath).isSymbolicLink()) {
+          throw new Error(
+            `local marketplace packages may not contain symlinks: ${source.path}/${child.name}`,
+          );
+        }
+        if (child.isDirectory()) {
+          visit(childPath);
+          continue;
+        }
+        if (!child.isFile()) {
+          throw new Error(
+            `local marketplace package contains an unsupported entry: ${childPath}`,
+          );
+        }
+        files.push({
+          path: relative(packageRealpath, childPath).split(sep).join("/"),
+          contentBase64: readFileSync(childPath).toString("base64"),
+        });
+      }
+    };
+    visit(packageRealpath);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    if (packages[source.path]) {
+      throw new Error(`duplicate local marketplace package: ${source.path}`);
+    }
+    packages[source.path] = { version: source.version, files };
+  }
+  return packages;
+}

package/scripts/generate-bundled-plugin-packages.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env bun
+
+import { writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { buildBundledPluginPackages } from "./bundled-plugin-packages.js";
+
+const repoRoot = resolve(import.meta.dir, "../..");
+const output = {
+  version: 1,
+  packages: buildBundledPluginPackages(repoRoot),
+};
+
+if (process.argv.includes("--check")) {
+  console.log("✓ Local marketplace packages are valid");
+} else {
+  writeFileSync(
+    join(
+      repoRoot,
+      "assistant",
+      "src",
+      "cli",
+      "lib",
+      "bundled-plugin-packages.json",
+    ),
+    `${JSON.stringify(output, null, 2)}\n`,
+  );
+  console.log("✓ Generated bundled local plugin packages");
+}

package/scripts/test.ts

@@ -62,26 +62,28 @@ const EXPERIMENTAL_FILES = new Set([
 const KNOWN_BROKEN_FILES = new Set<string>([]);
 
 // ---------------------------------------------------------------------------
-// Feature-flag registry sync
+// Bundled catalog sync
 // ---------------------------------------------------------------------------
 
-// Ensure the bundled feature-flag-registry.json exists before running tests.
-// The canonical copy lives at meta/feature-flags/feature-flag-registry.json and
-// is synced into assistant/src/ and gateway/src/. CI runs this as a dedicated
-// step; locally postinstall handles it — but when node_modules is symlinked
-// (e.g. worktrees) postinstall never fires, so the bundled copy can be missing
-// and feature-flag-registry-bundled.test.ts fails. Running the sync here is
-// idempotent and cheap (two file copies).
-function syncFeatureFlagRegistry(): void {
+// Ensure generated catalog inputs exist before tests. Locally, postinstall may
+// not run in worktrees that share node_modules, so the static JSON imports can
+// otherwise be missing.
+function syncBundledCatalog(): void {
   const syncScript = join("..", "meta", "sync-bundled-copies.ts");
   if (!existsSync(syncScript)) {
     return;
   }
-  Bun.spawnSync(["bun", "run", "meta/sync-bundled-copies.ts"], {
-    cwd: join(process.cwd(), ".."),
+  const result = Bun.spawnSync(["bun", "run", "sync:bundled-catalog"], {
+    cwd: process.cwd(),
     stdout: "ignore",
-    stderr: "ignore",
+    stderr: "pipe",
+    windowsHide: true,
   });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to generate bundled catalog inputs: ${result.stderr.toString()}`,
+    );
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -514,7 +516,7 @@ async function buildMigratedFixture(outWorkspaceDir: string): Promise<void> {
 // ---------------------------------------------------------------------------
 
 async function main(): Promise<void> {
-  syncFeatureFlagRegistry();
+  syncBundledCatalog();
 
   let testFiles = collectTestFiles();
   if (testFiles.length === 0) {

package/src/__tests__/managed-store.test.ts

@@ -332,6 +332,127 @@ describe("createManagedSkill", () => {
     expect(content).toContain("Overwritten");
   });
 
+  test("an overwrite keeps the frontmatter the call omits and replaces the body", () => {
+    createManagedSkill({
+      id: "kept",
+      name: "Kept",
+      description: "V1",
+      bodyMarkdown: "Old body.",
+      emoji: "📊",
+      includes: ["csv-basics"],
+      activationHints: ["user asks for the weekly report"],
+      avoidWhen: ["the report is monthly"],
+      category: "productivity",
+    });
+
+    const result = createManagedSkill({
+      id: "kept",
+      name: "Kept",
+      description: "V2",
+      bodyMarkdown: "New body.",
+      overwrite: true,
+    });
+    expect(result.created).toBe(true);
+
+    const catalog = loadSkillCatalog(undefined, [join(TEST_DIR, "skills")]);
+    const skill = catalog.find((s) => s.id === "kept")!;
+    expect(skill.description).toBe("V2");
+    expect(skill.emoji).toBe("📊");
+    expect(skill.includes).toEqual(["csv-basics"]);
+    expect(skill.activationHints).toEqual(["user asks for the weekly report"]);
+    expect(skill.avoidWhen).toEqual(["the report is monthly"]);
+    expect(skill.category).toBe("productivity");
+    expect(readFileSync(result.path, "utf-8")).toContain("New body.");
+    expect(readFileSync(result.path, "utf-8")).not.toContain("Old body.");
+  });
+
+  test("an overwrite carries through frontmatter the tool does not own", () => {
+    const dir = join(TEST_DIR, "skills", "hand-edited");
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(
+      join(dir, "SKILL.md"),
+      [
+        "---",
+        'name: "Hand Edited"',
+        'description: "Has fields the tool never writes"',
+        "metadata:",
+        "  custom: kept",
+        "  vellum:",
+        '    display-name: "Hand Edited Skill"',
+        "    platforms:",
+        "      - macos",
+        "    always-candidate: true",
+        '    emoji: "📊"',
+        "---",
+        "",
+        "Old body.",
+        "",
+      ].join("\n"),
+    );
+
+    const result = createManagedSkill({
+      id: "hand-edited",
+      name: "Hand Edited",
+      description: "V2",
+      bodyMarkdown: "New body.",
+      overwrite: true,
+      category: "productivity",
+    });
+    expect(result.created).toBe(true);
+
+    const fm = parseYaml(
+      readFileSync(result.path, "utf-8").match(/^---\n([\s\S]*?)\n---/)![1],
+    );
+    expect(fm.metadata.custom).toBe("kept");
+    expect(fm.metadata.vellum["display-name"]).toBe("Hand Edited Skill");
+    expect(fm.metadata.vellum.platforms).toEqual(["macos"]);
+    expect(fm.metadata.vellum["always-candidate"]).toBe(true);
+    expect(fm.metadata.vellum.emoji).toBe("📊");
+    expect(fm.metadata.vellum.category).toBe("productivity");
+    const skill = loadSkillCatalog(undefined, [join(TEST_DIR, "skills")]).find(
+      (s) => s.id === "hand-edited",
+    )!;
+    expect(skill.displayName).toBe("Hand Edited Skill");
+    expect(skill.platforms).toEqual(["macos"]);
+    expect(skill.alwaysCandidate).toBe(true);
+  });
+
+  test("an overwrite replaces a field it passes and clears one passed empty", () => {
+    createManagedSkill({
+      id: "patched",
+      name: "Patched",
+      description: "V1",
+      bodyMarkdown: "Body.",
+      emoji: "📊",
+      includes: ["csv-basics"],
+      activationHints: ["old hint"],
+      avoidWhen: ["the report is monthly"],
+      category: "productivity",
+    });
+
+    createManagedSkill({
+      id: "patched",
+      name: "Patched",
+      description: "V2",
+      bodyMarkdown: "Body.",
+      overwrite: true,
+      emoji: "🚀",
+      activationHints: ["new hint"],
+      avoidWhen: [],
+      category: "",
+    });
+
+    const catalog = loadSkillCatalog(undefined, [join(TEST_DIR, "skills")]);
+    const skill = catalog.find((s) => s.id === "patched")!;
+    expect(skill.emoji).toBe("🚀");
+    expect(skill.activationHints).toEqual(["new hint"]);
+    // Omitted: kept.
+    expect(skill.includes).toEqual(["csv-basics"]);
+    // Passed empty: cleared.
+    expect(skill.avoidWhen).toBeUndefined();
+    expect(skill.category).toBeUndefined();
+  });
+
   test("writes category to frontmatter and round-trips through catalog load", () => {
     createManagedSkill({
       id: "categorized-skill",