@vellumai/assistant 0.8.10 → 0.8.11-staging.1

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

@@ -1,24 +1,19 @@
 /**
  * Install a plugin by name from the canonical GitHub source.
  *
- * A name resolves to one of two sources, materialized into
- * `<workspacePluginsDir>/<name>/` so the daemon discovers it on next start:
- *   1. A whitelisted external ecosystem plugin, when the name matches an entry
- *      in the curated `experimental/plugins/marketplace.json` manifest. The
- *      pinned `owner/repo[/path]@ref` (see {@link ./plugin-marketplace}) is
- *      fetched with a shallow `git` clone at that ref — one network operation
- *      regardless of repo size, immune to GitHub's unauthenticated API
- *      rate-limit, and recording the exact resolved commit for provenance.
- *      When we curate an adapter stub for the plugin (an
- *      `experimental/plugins/<name>/` directory in this repo with a
- *      `scripts.postinstall` command), the stub is overlaid onto the clone and
- *      its postinstall runs to translate a foreign-ecosystem layout into the
- *      shape Vellum's loader runs (see {@link applyAdapterStub}).
- *   2. Otherwise the first-party convention
- *      `vellum-ai/vellum-assistant/experimental/plugins/<name>/` at the
- *      configured ref, fetched via the GitHub Contents API (a small handful of
- *      in-repo files — cloning the whole monorepo to install one would be
- *      wasteful).
+ * A name resolves to a whitelisted external ecosystem plugin — an entry in the
+ * curated `plugins/marketplace.json` manifest. The pinned
+ * `owner/repo[/path]@ref` (see {@link ./plugin-marketplace}) is fetched with a
+ * shallow `git` clone at that ref — one network operation regardless of repo
+ * size, immune to GitHub's unauthenticated API rate-limit, and recording the
+ * exact resolved commit for provenance — and materialized into
+ * `<workspacePluginsDir>/<name>/` so the daemon discovers it on next start.
+ *
+ * When we curate an adapter stub for the plugin (a `plugins/<name>/` directory
+ * in this repo with a `scripts.postinstall` command), the stub is overlaid
+ * onto the clone and its postinstall runs to translate a foreign-ecosystem
+ * layout into the shape Vellum's loader runs (see {@link applyAdapterStub}). A
+ * name with no marketplace entry is a not-found.
  *
  * Designed for direct programmatic use. The CLI command
  * `assistant plugins install <name>` is a thin wrapper that supplies
@@ -47,6 +42,8 @@ import { ensureBun } from "../../util/bun-runtime.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
 import {
   fetchMarketplaceEntries,
+  MarketplaceFetchError,
+  type ResolvedPluginSource,
   resolveMarketplaceSource,
 } from "./plugin-marketplace.js";
 
@@ -54,7 +51,7 @@ const execFileAsync = promisify(execFile);
 
 const PLUGIN_SOURCE_OWNER = "vellum-ai";
 const PLUGIN_SOURCE_REPO = "vellum-assistant";
-const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
+const PLUGIN_SOURCE_PATH_PREFIX = "plugins";
 /** Default git ref to fetch from when callers don't override. */
 export const DEFAULT_PLUGIN_REF = "main";
 
@@ -130,7 +127,7 @@ export interface InstallPluginResult {
   readonly target: string;
   readonly fileCount: number;
   readonly ref: string;
-  /** Resolved commit SHA for git-cloned external sources; null for first-party (no clone). */
+  /** Resolved commit SHA the external source was cloned at; null when it could not be read. */
   readonly commit: string | null;
 }
 
@@ -214,8 +211,6 @@ function isTransientUpstreamStatus(res: Response): boolean {
 
 /** Resolved GitHub coordinates a plugin name is fetched from. */
 interface PluginFetchSource {
-  /** Whether the plugin lives in our monorepo or an external whitelisted repo. */
-  readonly kind: "first-party" | "external";
   readonly owner: string;
   readonly repo: string;
   /** Repo-relative directory holding the plugin root; `""` = repo root. */
@@ -230,54 +225,42 @@ function sourceLabel(source: PluginFetchSource): string {
     : `${source.owner}/${source.repo}`;
 }
 
-/** First-party `experimental/plugins/<name>` coordinates at a given ref. */
-function firstPartySource(name: string, ref: string): PluginFetchSource {
-  return {
-    kind: "first-party",
-    owner: PLUGIN_SOURCE_OWNER,
-    repo: PLUGIN_SOURCE_REPO,
-    rootPath: `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
-    ref,
-  };
-}
-
 /**
- * Resolve a plugin name to concrete GitHub coordinates.
+ * Resolve a plugin name to the concrete GitHub coordinates of its pinned
+ * marketplace entry, or `null` when no entry claims the name.
  *
- * A name claimed by the curated marketplace resolves to its pinned external
- * repo; any other name resolves to the first-party `experimental/plugins/<name>`
- * convention. The marketplace is external-only by construction — a same-named
- * `experimental/plugins/<name>` directory is the plugin's optional *adapter
- * stub* (a curated `package.json` + postinstall script overlaid onto the clone
- * to translate it into Vellum's shape; see {@link applyAdapterStub}), not a
- * standalone first-party plugin. So letting the marketplace win the name is
- * what makes the stub apply to the external clone, and the search catalog
- * surfaces the same name as external — install and search stay in agreement.
+ * The marketplace is external-only by construction — a same-named
+ * `plugins/<name>` directory is the plugin's optional *adapter stub* (a curated
+ * `package.json` + postinstall script overlaid onto the clone to translate it
+ * into Vellum's shape; see {@link applyAdapterStub}), not a standalone plugin.
  *
- * A missing or malformed manifest degrades to first-party resolution — the
- * whitelist is supplementary and must never block installing a first-party
- * plugin. An external name then surfaces a clear not-found error downstream.
+ * A transient marketplace failure (rate-limit / 5xx) surfaces as a retryable
+ * {@link PluginSourceUnavailableError}; a malformed manifest propagates as a
+ * hard error, since the marketplace is the source of truth for what is
+ * installable.
  */
 async function resolvePluginSource(
   name: string,
   marketplaceRef: string,
   fetchFn: FetchLike,
-): Promise<PluginFetchSource> {
-  let resolved = null;
+): Promise<PluginFetchSource | null> {
+  let resolved: ResolvedPluginSource | null;
   try {
     const entries = await fetchMarketplaceEntries(
       { fetch: fetchFn },
       { ref: marketplaceRef },
     );
     resolved = resolveMarketplaceSource(name, entries);
-  } catch {
-    // Degrade to first-party resolution below.
+  } catch (err) {
+    if (err instanceof MarketplaceFetchError && err.transient) {
+      throw new PluginSourceUnavailableError(err.message, err.status ?? 503);
+    }
+    throw err;
   }
 
-  if (!resolved) return firstPartySource(name, marketplaceRef);
+  if (!resolved) return null;
 
   return {
-    kind: "external",
     owner: resolved.owner,
     repo: resolved.repo,
     rootPath: resolved.path,
@@ -288,7 +271,7 @@ async function resolvePluginSource(
 /**
  * Reject plugin names that could escape the canonical source path or the
  * install target. The source convention is a flat namespace under
- * `experimental/plugins/`, so a legitimate name is a single path segment
+ * `plugins/`, so a legitimate name is a single path segment
  * built from kebab-case alphanumerics.
  *
  * Exported so callers (e.g. the CLI input prompt) can validate up front
@@ -344,6 +327,13 @@ export async function installPlugin(
   const force = opts.force ?? false;
 
   const source = await resolvePluginSource(name, marketplaceRef, deps.fetch);
+  if (!source) {
+    throw new PluginNotFoundError(
+      name,
+      marketplaceRef,
+      "plugins/marketplace.json",
+    );
+  }
   const ref = source.ref;
 
   const pluginsDir = deps.workspacePluginsDir ?? getWorkspacePluginsDir();
@@ -353,10 +343,19 @@ export async function installPlugin(
     throw new PluginAlreadyInstalledError(name, target);
   }
 
-  // Stage into a sibling temp dir so an in-progress install never destroys
-  // the currently installed version. `process.pid` keeps concurrent installs
-  // of the same plugin from clobbering each other's staging.
-  const stagingDir = `${target}.installing.${process.pid}`;
+  // Stage *outside* the served `plugins/` directory. The daemon watches that
+  // directory and its startup loader enumerates it, so a staging dir living
+  // inside it is observed mid-install — before the adapter overlay runs, an
+  // external clone still carries its upstream `package.json` (wrong name, no
+  // plugin-api peer dep), which the loader rejects with spurious name-mismatch
+  // and missing-peer-dependency warnings. Staging in a sibling directory keeps
+  // the half-built tree invisible until the final swap. The root is on the
+  // same filesystem as the target, so that swap stays an atomic rename.
+  // `process.pid` keeps concurrent installs of the same plugin from clobbering
+  // each other's staging.
+  const stagingRoot = join(dirname(pluginsDir), ".plugins-staging");
+  mkdirSync(stagingRoot, { recursive: true });
+  const stagingDir = join(stagingRoot, `${name}.installing.${process.pid}`);
   if (existsSync(stagingDir)) {
     rmSync(stagingDir, { recursive: true, force: true });
   }
@@ -365,52 +364,20 @@ export async function installPlugin(
   let fileCount: number;
   let commit: string | null = null;
   try {
-    if (source.kind === "external") {
-      const cloned = await copyExternalViaGit(
-        source,
-        stagingDir,
-        deps.runGit ?? defaultGitRunner,
-      );
-      fileCount = cloned.fileCount;
-      commit = cloned.commit;
-      // An external clone is often a foreign-ecosystem plugin (e.g. a Claude
-      // Code plugin) that the Vellum loader can't run as-is. When we curate an
-      // adapter stub for it, overlay the stub and run its transform so the
-      // materialized tree is a valid Vellum plugin. Raw clones (no stub) are
-      // left untouched.
-      if (fileCount > 0) {
-        await applyAdapterStub(name, marketplaceRef, stagingDir, deps);
-      }
-    } else {
-      fileCount = await copyDir(
-        source.owner,
-        source.repo,
-        source.rootPath,
-        ref,
-        stagingDir,
-        deps.fetch,
-      );
-      // We only land in the first-party branch for this name when the
-      // marketplace lookup returned no claim. A *healthy* marketplace that
-      // claims the name routes to the external+adapter branch above; reaching
-      // here for a directory that is actually an adapter stub (declares a
-      // `scripts.postinstall`) therefore means the marketplace failed to load
-      // (rate-limit / 5xx / malformed) and we degraded past it. A stub has no
-      // hooks/tools of its own — it only transforms an external clone — so
-      // installing it alone would materialize a non-functional plugin. Fail
-      // loudly and retryably instead of silently shipping a broken plugin.
-      // Genuine first-party plugins (no postinstall) install normally.
-      if (
-        fileCount > 0 &&
-        resolvePostinstallScript(name, stagingDir) !== null
-      ) {
-        throw new PluginPostinstallError(
-          name,
-          "resolved to a first-party adapter stub, but its marketplace entry " +
-            "could not be read to locate the external source it adapts — the " +
-            "marketplace lookup likely failed transiently. Retry the install.",
-        );
-      }
+    const cloned = await copyExternalViaGit(
+      source,
+      stagingDir,
+      deps.runGit ?? defaultGitRunner,
+    );
+    fileCount = cloned.fileCount;
+    commit = cloned.commit;
+    // An external clone is often a foreign-ecosystem plugin (e.g. a Claude
+    // Code plugin) that the Vellum loader can't run as-is. When we curate an
+    // adapter stub for it, overlay the stub and run its transform so the
+    // materialized tree is a valid Vellum plugin. Raw clones (no stub) are
+    // left untouched.
+    if (fileCount > 0) {
+      await applyAdapterStub(name, marketplaceRef, stagingDir, deps);
     }
   } catch (err) {
     rmSync(stagingDir, { recursive: true, force: true });
@@ -431,6 +398,9 @@ export async function installPlugin(
   // Atomic-ish swap: rmSync + renameSync. On POSIX the rename itself is
   // atomic, so the only window where the target is absent is between the
   // rm and the rename — and at that point the staging dir is fully populated.
+  // Ensure the served `plugins/` directory exists: staging now lives outside
+  // it, so the target's parent is no longer created as a side effect.
+  mkdirSync(pluginsDir, { recursive: true });
   if (existsSync(target)) {
     rmSync(target, { recursive: true, force: true });
   }
@@ -534,14 +504,16 @@ const POSTINSTALL_TIMEOUT_MS = 60_000;
  * Overlay our curated adapter stub onto a freshly cloned external plugin and
  * run its postinstall transform, returning whether a transform ran.
  *
- * The stub lives at `experimental/plugins/<name>/` in our own repo and carries
+ * The stub lives at `plugins/<name>/` in our own repo and carries
  * a `package.json` (with a `scripts.postinstall` adapter command) plus the
  * adapter script it names. We fetch it via the Contents API — a couple of
- * small files, well within the rate limit — and copy it over the clone, which
- * deliberately overwrites the clone's `package.json` so the postinstall we run
- * is ours, never the upstream repo's lifecycle script. Absent a stub (the
- * common case for a plugin already in Vellum shape), nothing is overlaid and
- * the clone is installed as-is.
+ * small files, well within the rate limit — and copy it over the clone so the
+ * postinstall we run is ours, never the upstream repo's lifecycle script. The
+ * overlaid stub `package.json` exists only to name that adapter; the installed
+ * plugin's manifest is rebuilt from the upstream `package.json` afterwards (see
+ * {@link normalizeInstalledManifest}). Absent a stub (the common case for a
+ * plugin already in Vellum shape), nothing is overlaid and the clone is
+ * installed as-is.
  *
  * On any adapter failure the error propagates so {@link installPlugin} rolls
  * back staging — better to fail loudly than ship a half-transformed plugin.
@@ -552,6 +524,11 @@ async function applyAdapterStub(
   stagingDir: string,
   deps: InstallPluginDeps,
 ): Promise<boolean> {
+  // Capture the cloned upstream manifest before the stub overlay replaces it,
+  // so the installed plugin can preserve it verbatim except for the two fields
+  // the Vellum loader requires (name + plugin-api peer dep).
+  const upstreamPkg = readPackageJson(join(stagingDir, "package.json"));
+
   const stubFileCount = await copyDir(
     PLUGIN_SOURCE_OWNER,
     PLUGIN_SOURCE_REPO,
@@ -571,9 +548,89 @@ async function applyAdapterStub(
   } catch (err) {
     throw new PluginPostinstallError(name, subprocessErrorText(err));
   }
+
+  normalizeInstalledManifest(name, stagingDir, upstreamPkg);
   return true;
 }
 
+/**
+ * Default `@vellumai/plugin-api` peer-dependency range stamped onto an adapted
+ * plugin that doesn't already declare one.
+ */
+const PLUGIN_API_PEER_RANGE = ">=0.8.0";
+
+type PackageManifest = Record<string, unknown>;
+
+/** Parse the `package.json` at `path`, or null if it's absent or unparseable. */
+function readPackageJson(path: string): PackageManifest | null {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    return typeof parsed === "object" &&
+      parsed !== null &&
+      !Array.isArray(parsed)
+      ? (parsed as PackageManifest)
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the installed plugin's final `package.json` after the adapter has run.
+ *
+ * A curated adapter stub deliberately overlays its own `package.json` onto the
+ * clone so the installer can find and run the stub's `scripts.postinstall`.
+ * That stub is install-time machinery, not the plugin's manifest, so once the
+ * adapter has run we rebuild the manifest from the upstream `package.json`
+ * captured before the overlay — preserving its `version`, `description`,
+ * `license`, and every other field — and mutate only what the Vellum loader
+ * requires: `name` must equal the install directory, and `@vellumai/plugin-api`
+ * must be declared as a peer dependency. The spent `postinstall` script is
+ * dropped so the installed plugin carries no install-time machinery.
+ *
+ * When the upstream repo shipped no `package.json`, the overlaid stub is the
+ * only manifest available, so it becomes the base instead.
+ */
+function normalizeInstalledManifest(
+  name: string,
+  stagingDir: string,
+  upstreamPkg: PackageManifest | null,
+): void {
+  const manifestPath = join(stagingDir, "package.json");
+  const base = upstreamPkg ?? readPackageJson(manifestPath) ?? {};
+
+  const peer =
+    typeof base.peerDependencies === "object" && base.peerDependencies !== null
+      ? (base.peerDependencies as Record<string, unknown>)
+      : {};
+  const existingRange = peer["@vellumai/plugin-api"];
+
+  const manifest: PackageManifest = {
+    ...base,
+    name,
+    peerDependencies: {
+      ...peer,
+      "@vellumai/plugin-api":
+        typeof existingRange === "string"
+          ? existingRange
+          : PLUGIN_API_PEER_RANGE,
+    },
+  };
+
+  if (typeof manifest.scripts === "object" && manifest.scripts !== null) {
+    const scripts = { ...(manifest.scripts as Record<string, unknown>) };
+    delete scripts.postinstall;
+    if (Object.keys(scripts).length === 0) {
+      delete manifest.scripts;
+    } else {
+      manifest.scripts = scripts;
+    }
+  }
+
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
 /**
  * Resolve the absolute path of the adapter script named by the (overlaid stub)
  * `package.json`'s `scripts.postinstall`, or `null` when there is no stub
@@ -695,7 +752,8 @@ function pluginPostinstallEnv(bun: string): NodeJS.ProcessEnv {
 
 /**
  * Recursively copy regular files from `srcRoot` into `destDir`, skipping the
- * top-level `.git` directory and any symlinks. Returns the file count.
+ * top-level `.git` directory, a top-level `bunfig.toml` (see below), and any
+ * symlinks. Returns the file count.
  */
 function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
   let count = 0;
@@ -705,6 +763,17 @@ function copyTreeSkippingGit(srcRoot: string, destDir: string): number {
       // Drop git metadata and symlinks: the loader follows neither, and a
       // symlink could otherwise point outside the staging tree.
       if (relDir === "" && entry.name === ".git") continue;
+      // Drop a top-level `bunfig.toml`. The adapter postinstall runs `bun` with
+      // its cwd at the staged root, and Bun auto-loads `$cwd/bunfig.toml` as
+      // project config — including a `preload` list it executes before the
+      // entry point. An upstream config would therefore run arbitrary code
+      // ahead of the curated adapter, defeating the command/env guards. Bun
+      // reads only the cwd's file (it neither walks up nor descends), so
+      // dropping it at the root closes the vector; a Vellum plugin never
+      // consumes `bunfig.toml`. Match case-insensitively because the macOS
+      // install target's filesystem is case-insensitive, where Bun would still
+      // open a clone-supplied `BUNFIG.TOML`.
+      if (relDir === "" && entry.name.toLowerCase() === "bunfig.toml") continue;
       if (entry.isSymbolicLink()) continue;
 
       const rel = relDir ? join(relDir, entry.name) : entry.name;
@@ -799,7 +868,7 @@ function writeInstallManifest(
   const manifest = {
     name,
     source: {
-      kind: source.kind,
+      kind: "github",
       owner: source.owner,
       repo: source.repo,
       path: source.rootPath || undefined,
@@ -815,13 +884,14 @@ function writeInstallManifest(
 }
 
 /**
- * Recursively copy a first-party plugin directory via the GitHub Contents API.
+ * Recursively copy a curated adapter stub directory via the GitHub Contents API.
  *
- * First-party plugins live in our own monorepo as a small handful of files, so
- * the per-directory walk stays well within the unauthenticated rate limit —
- * and avoids cloning the entire repository just to install one plugin. Returns
- * the number of files written; zero means the directory doesn't exist at this
- * ref, which the caller maps to a not-found error.
+ * An adapter stub lives in our own monorepo at `plugins/<name>/` as a small
+ * handful of files (a `package.json` + postinstall script), so the
+ * per-directory walk stays well within the unauthenticated rate limit — and
+ * avoids cloning the entire repository just to overlay it. Returns the number
+ * of files written; zero means no stub exists at this ref, in which case the
+ * external clone is installed as-is.
  */
 async function copyDir(
   owner: string,

package/src/cli/lib/plugin-catalog-cache.ts

@@ -1,12 +1,12 @@
 /**
  * In-memory cache for the installable plugin catalog.
  *
- * The catalog (`loadPluginCatalog`) is built from two unauthenticated GitHub
- * Contents API calls — the first-party `experimental/plugins/` directory
- * listing and the `marketplace.json` manifest. GitHub's unauthenticated rate
- * limit is 60 requests/hour per IP, so a long-lived daemon that hit GitHub on
- * every catalog search (on web mount, on every keystroke, across reloads and
- * multiple clients) would exhaust that budget and start getting HTTP 403s.
+ * The catalog (`loadPluginCatalog`) is built from a single unauthenticated
+ * GitHub Contents API call — the `marketplace.json` manifest. GitHub's
+ * unauthenticated rate limit is 60 requests/hour per IP, so a long-lived
+ * daemon that hit GitHub on every catalog search (on web mount, on every
+ * keystroke, across reloads and multiple clients) would exhaust that budget
+ * and start getting HTTP 403s.
  *
  * Because the GitHub responses are **query-independent** — `searchPlugins`
  * applies the regex filter in memory — one catalog load serves any number of
@@ -44,9 +44,9 @@ const cache = new Map<string, CacheEntry>();
  * transient upstream error ({@link PluginCatalogUnavailableError} — rate
  * limiting or a 5xx) and a cached catalog exists, the stale catalog is served
  * (and its TTL window is reset so a sustained outage doesn't re-enter the
- * failing fetch on every call). A hard error (e.g. the canonical plugins
- * prefix returning 404, or a deleted ref) always propagates — serving stale
- * there would silently mask a real misconfiguration. With no cache to fall
+ * failing fetch on every call). A hard error (e.g. a malformed manifest, or a
+ * deleted ref) always propagates — serving stale there would silently mask a
+ * real misconfiguration. With no cache to fall
  * back on, the underlying error propagates regardless so the caller can
  * surface it (e.g. the route maps a rate-limit failure to 503).
  */

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

@@ -6,18 +6,19 @@
  * most authoritative for each field:
  *   1. The locally installed copy under `<workspacePluginsDir>/<name>/`, when
  *      present — its `package.json` and `README.md` are read straight off disk.
- *   2. The curated `experimental/plugins/marketplace.json` entry, for external
+ *   2. The curated `plugins/marketplace.json` entry, for external
  *      ecosystem plugins (description / homepage / license / pinned source).
- *   3. The plugin's own repository at the pinned ref (first-party
- *      `experimental/plugins/<name>/` or the external `owner/repo[/path]`),
+ *   3. The plugin's own external repository at the pinned `owner/repo[/path]`,
  *      fetched via the GitHub Contents API for the README and any
  *      `package.json` fields the manifest doesn't carry.
  *
- * Name-collision precedence matches {@link ./search-plugins} and
- * {@link ./install-from-github}: a marketplace entry owns its name, so the
+ * The `source` field is the marketplace entry's pinned origin when one claims
+ * the name, otherwise `null` — an installed copy with no catalog entry has no
+ * advertised origin. Name-collision precedence matches {@link ./search-plugins}
+ * and {@link ./install-from-github}: a marketplace entry owns its name, so the
  * detail page advertises the external source the catalog and installer use. A
- * same-named `experimental/plugins/<name>/` directory is that plugin's adapter
- * stub, not a standalone first-party plugin, so it does not override the claim.
+ * same-named `plugins/<name>/` directory is that plugin's adapter stub, not a
+ * standalone plugin, so it does not override the claim.
  *
  * Designed for direct programmatic use with an injected `fetch`, mirroring the
  * sibling plugin libraries.
@@ -38,10 +39,6 @@ import {
 } from "./plugin-marketplace.js";
 import type { PluginMatchSource } from "./search-plugins.js";
 
-const PLUGIN_SOURCE_OWNER = "vellum-ai";
-const PLUGIN_SOURCE_REPO = "vellum-assistant";
-const PLUGIN_SOURCE_PATH_PREFIX = "experimental/plugins";
-
 /** Recognised README filenames, matched case-insensitively against a listing. */
 const README_RE = /^readme(\.md|\.markdown)?$/i;
 
@@ -91,8 +88,11 @@ export interface PluginDetails {
   readonly license: string | null;
   /** Resolved version (installed copy first, then repo `package.json`); `null` when unknown. */
   readonly version: string | null;
-  /** Discriminated origin, mirroring the catalog's {@link PluginMatchSource}. */
-  readonly source: PluginMatchSource;
+  /**
+   * Pinned origin, mirroring the catalog's {@link PluginMatchSource}; `null`
+   * when an installed copy has no marketplace entry to advertise an origin.
+   */
+  readonly source: PluginMatchSource | null;
   /** README markdown, or `null` when the plugin ships none. */
   readonly readme: string | null;
   /** Git ref the catalog metadata / README were resolved at. */
@@ -114,8 +114,8 @@ export class PluginDetailsNotFoundError extends Error {
  * Resolve the detail view for {@link opts.name}.
  *
  * Throws {@link PluginDetailsNotFoundError} when the name is neither installed
- * locally nor present in the catalog (first-party directory or marketplace
- * entry). Network failures while enriching from GitHub degrade to the fields
+ * locally nor present in the marketplace catalog. Network failures while
+ * enriching from GitHub degrade to the fields
  * already known from disk / the manifest rather than failing the whole view —
  * a detail page that renders metadata without a README beats a hard error.
  */
@@ -132,40 +132,24 @@ export async function getPluginDetails(
 
   const marketplaceEntry = await findMarketplaceEntry(name, ref, fetchFn);
 
-  // A marketplace entry owns its name (the same-named in-repo directory, if
-  // any, is its adapter stub) — so only probe the first-party directory when
-  // the name is unclaimed, which also spares a GitHub request in the common
-  // external case.
-  const firstPartyEntries =
-    marketplaceEntry === null
-      ? await listDirSafe(
-          PLUGIN_SOURCE_OWNER,
-          PLUGIN_SOURCE_REPO,
-          `${PLUGIN_SOURCE_PATH_PREFIX}/${name}`,
-          ref,
-          fetchFn,
-        )
-      : null;
-  const firstPartyExists = firstPartyEntries !== null;
-
-  if (!local.installed && !firstPartyExists && !marketplaceEntry) {
+  if (!local.installed && !marketplaceEntry) {
     throw new PluginDetailsNotFoundError(name, ref);
   }
 
-  const useExternal = marketplaceEntry !== null;
-
-  const source: PluginMatchSource = useExternal
+  const source: PluginMatchSource | null = marketplaceEntry
     ? {
         kind: "github",
-        repo: marketplaceEntry!.source.repo,
-        ref: marketplaceEntry!.source.ref,
-        ...(marketplaceEntry!.source.path
-          ? { path: marketplaceEntry!.source.path }
+        repo: marketplaceEntry.source.repo,
+        ref: marketplaceEntry.source.ref,
+        ...(marketplaceEntry.source.path
+          ? { path: marketplaceEntry.source.path }
           : {}),
       }
-    : { kind: "first-party" };
+    : null;
 
-  const remote = await readRemotePlugin(source, firstPartyEntries, fetchFn);
+  const remote = source
+    ? await readRemotePlugin(source, fetchFn)
+    : { manifest: emptyManifest(), readme: null };
 
   const readme = local.readme ?? remote.readme;
 
@@ -244,39 +228,25 @@ interface RemotePlugin {
 }
 
 /**
- * Fetch README + `package.json` from the plugin's repository.
+ * Fetch README + `package.json` from the plugin's external repository.
  *
- * For a first-party plugin the listing is the in-repo directory the caller
- * already fetched at the catalog ref (passed through to avoid a duplicate
- * request). For an external plugin we list its `owner/repo[/path]` directory
- * fresh at the plugin's own pinned `source.ref`.
+ * Lists the plugin's `owner/repo[/path]` directory fresh at its own pinned
+ * `source.ref` — the detail page must describe the same artifact the installer
+ * resolves from `source.ref`, even when that differs from the catalog ref
+ * (`main`).
  */
 async function readRemotePlugin(
   source: PluginMatchSource,
-  firstPartyEntries: readonly GitHubContentEntry[] | null,
   fetchFn: FetchLike,
 ): Promise<RemotePlugin> {
-  let owner: string;
-  let repo: string;
-  let entries: readonly GitHubContentEntry[] | null;
-
-  if (source.kind === "github") {
-    [owner, repo] = source.repo.split("/", 2) as [string, string];
-    // Read the external repo at its pinned ref, not the assistant catalog ref —
-    // the detail page must describe the same artifact the installer resolves
-    // from `source.ref`, even when that differs from the catalog ref (`main`).
-    entries = await listDirSafe(
-      owner,
-      repo,
-      source.path ?? "",
-      source.ref,
-      fetchFn,
-    );
-  } else {
-    owner = PLUGIN_SOURCE_OWNER;
-    repo = PLUGIN_SOURCE_REPO;
-    entries = firstPartyEntries;
-  }
+  const [owner, repo] = source.repo.split("/", 2) as [string, string];
+  const entries = await listDirSafe(
+    owner,
+    repo,
+    source.path ?? "",
+    source.ref,
+    fetchFn,
+  );
 
   if (!entries) {
     return { manifest: emptyManifest(), readme: null };