@vellumai/assistant 0.9.0 → 0.10.0-staging.2

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

@@ -36,6 +36,10 @@ import {
   fetchMarketplaceEntries,
   type MarketplaceEntry,
 } from "./plugin-marketplace.js";
+import {
+  detectPluginSurfaces,
+  type PluginSurfaces,
+} from "./plugin-surfaces.js";
 
 /** Full commit SHA (40 hex SHA-1 or 64 hex SHA-256). */
 const FULL_SHA_RE = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/i;
@@ -131,6 +135,12 @@ export interface PluginInspection {
   readonly remote: PluginRemoteInfo | null;
   /** Marketplace fetch error message, when the catalog could not be read. */
   readonly remoteError: string | null;
+  /**
+   * Surfaces the installed copy contributes (skills, hooks, tools), read from
+   * its on-disk tree. `null` when the plugin is not installed — there is no
+   * tree to inspect, and the marketplace metadata does not enumerate surfaces.
+   */
+  readonly surfaces: PluginSurfaces | null;
 }
 
 /** Neither an installed copy nor a marketplace entry claims the name. */
@@ -266,6 +276,7 @@ export async function inspectPlugin(
   });
   const installed = entry !== null;
   const local = entry ? readLocal(entry, readInstallMeta(entry.target)) : null;
+  const surfaces = entry ? detectPluginSurfaces(entry.target) : null;
 
   let remote: PluginRemoteInfo | null = null;
   let remoteError: string | null = null;
@@ -294,7 +305,7 @@ export async function inspectPlugin(
   }
 
   const status = classify(installed, local, remote, remoteError);
-  return { name, installed, status, local, remote, remoteError };
+  return { name, installed, status, local, remote, remoteError, surfaces };
 }
 
 function classify(

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

@@ -221,7 +221,7 @@ function isTransientUpstreamStatus(res: Response): boolean {
 }
 
 /** Resolved GitHub coordinates a plugin name is fetched from. */
-interface PluginFetchSource {
+export interface PluginFetchSource {
   readonly owner: string;
   readonly repo: string;
   /** Repo-relative directory holding the plugin root; `""` = repo root. */
@@ -376,22 +376,13 @@ export async function installPlugin(
   let commit: string | null = null;
   let committedAt: string | null = null;
   try {
-    const cloned = await copyExternalViaGit(
-      source,
-      stagingDir,
-      deps.runGit ?? defaultGitRunner,
+    const materialized = await materializePluginTree(
+      { source, name, stubRef: marketplaceRef, destDir: stagingDir },
+      deps,
     );
-    fileCount = cloned.fileCount;
-    commit = cloned.commit;
-    committedAt = cloned.committedAt;
-    // 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);
-    }
+    fileCount = materialized.fileCount;
+    commit = materialized.commit;
+    committedAt = materialized.committedAt;
   } catch (err) {
     rmSync(stagingDir, { recursive: true, force: true });
     throw err;
@@ -402,6 +393,52 @@ export async function installPlugin(
     throw new PluginNotFoundError(name, ref, sourceLabel(source));
   }
 
+  finalizeStagedInstall(stagingDir, {
+    name,
+    source,
+    ref,
+    commit,
+    committedAt,
+    pluginsDir,
+  });
+
+  return { name, target, fileCount, ref, commit, committedAt };
+}
+
+/** Inputs for {@link finalizeStagedInstall}. */
+export interface FinalizeStagedInstallParams {
+  readonly name: string;
+  /** Source coordinates recorded in the provenance sidecar. */
+  readonly source: PluginFetchSource;
+  /** Ref recorded in the sidecar (the resolved commit SHA for marketplace installs). */
+  readonly ref: string;
+  readonly commit: string | null;
+  /** ISO-8601 committer timestamp of {@link FinalizeStagedInstallParams.commit} (UTC); null when unknown. */
+  readonly committedAt: string | null;
+  /** Served plugins directory; the staging dir is swapped into `<pluginsDir>/<name>`. */
+  readonly pluginsDir: string;
+}
+
+/**
+ * Fingerprint a fully-populated `stagingDir`, write its provenance sidecar, and
+ * atomically swap it into `<pluginsDir>/<name>`. Returns the final install path
+ * and the fingerprint that was recorded.
+ *
+ * Shared by {@link installPlugin} (fresh materialization) and the merge-based
+ * `plugins upgrade --strategy` path so both record identical provenance and use
+ * the same atomic rm+rename swap.
+ */
+export function finalizeStagedInstall(
+  stagingDir: string,
+  {
+    name,
+    source,
+    ref,
+    commit,
+    committedAt,
+    pluginsDir,
+  }: FinalizeStagedInstallParams,
+): { target: string; fingerprint: Fingerprint } {
   // Hash the materialized tree before the sidecar is written (so the sidecar
   // never hashes itself) — the baseline `plugins inspect` uses to detect later
   // local edits. The per-file fingerprint answers "which files changed"; the
@@ -428,13 +465,14 @@ export async function installPlugin(
   // 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.
+  const target = join(pluginsDir, name);
   mkdirSync(pluginsDir, { recursive: true });
   if (existsSync(target)) {
     rmSync(target, { recursive: true, force: true });
   }
   renameSync(stagingDir, target);
 
-  return { name, target, fileCount, ref, commit, committedAt };
+  return { target, fingerprint };
 }
 
 /** Cap on any single git invocation; a shallow fetch is well under this. */
@@ -523,6 +561,56 @@ export interface InstallMeta {
   readonly fingerprint: Fingerprint | null;
 }
 
+/** Outcome of materializing an external plugin tree into a directory. */
+export interface MaterializedTree {
+  /** Number of regular files written into the destination. */
+  readonly fileCount: number;
+  /** Commit SHA the source was cloned at; `null` when it could not be read. */
+  readonly commit: string | null;
+  /** ISO-8601 committer timestamp of {@link MaterializedTree.commit}; `null` when unread. */
+  readonly committedAt: string | null;
+}
+
+/**
+ * Produce the exact plugin tree an install stages, into `destDir`: clone the
+ * source at `source.ref`, then overlay the curated adapter stub (when one
+ * exists) so a foreign-ecosystem clone is translated into Vellum shape.
+ *
+ * `installPlugin` calls this and then fingerprints, records provenance, and
+ * swaps the result into the workspace. `diffPlugin` (see {@link ./diff-plugin})
+ * calls it with the *recorded install commit* to reconstruct the install-time
+ * baseline. Routing both through one path guarantees a re-materialized commit
+ * is byte-identical to what the original install produced, so an install-time
+ * adapter transform never reads as local drift when diffing.
+ */
+export async function materializePluginTree(
+  opts: {
+    /** Source coordinates; `source.ref` selects the commit to clone. */
+    readonly source: PluginFetchSource;
+    /** Install name, used to locate the curated adapter stub. */
+    readonly name: string;
+    /** Ref the curated adapter stub is fetched at (the canonical repo ref). */
+    readonly stubRef: string;
+    /** Directory the tree is written into. */
+    readonly destDir: string;
+  },
+  deps: InstallPluginDeps,
+): Promise<MaterializedTree> {
+  const cloned = await copyExternalViaGit(
+    opts.source,
+    opts.destDir,
+    deps.runGit ?? defaultGitRunner,
+  );
+  // 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 (cloned.fileCount > 0) {
+    await applyAdapterStub(opts.name, opts.stubRef, opts.destDir, deps);
+  }
+  return cloned;
+}
+
 /**
  * Materialize an external plugin by shallow-cloning its repo at the pinned ref.
  *

package/src/cli/lib/merge-plugin-tree.ts

@@ -0,0 +1,328 @@
+/**
+ * Three-way merge of a plugin tree, used by `plugins upgrade --strategy` to
+ * carry local edits forward across an upgrade instead of discarding them.
+ *
+ * An upgrade has three inputs, exactly like a git merge:
+ * - **base** — the tree the plugin was installed at (the recorded commit,
+ *   re-materialized through the install pipeline; see {@link ./diff-plugin}).
+ * - **ours** — the current on-disk install, carrying any local edits.
+ * - **theirs** — the marketplace's current pin, the tree being upgraded to.
+ *
+ * Per file the merge is delegated to `git merge-file`, the same line-level
+ * three-way algorithm git itself uses: a hunk edited on only one side is taken
+ * from that side, so non-conflicting edits from *both* sides survive. Only a
+ * hunk edited differently on both sides is a true conflict, resolved per the
+ * caller's strategy:
+ * - `ours` keeps the local hunk (`git merge-file --ours`),
+ * - `theirs` keeps the pinned hunk (`git merge-file --theirs`),
+ * - `assistant` writes standard git conflict markers into the file (no resolve
+ *   flag) and reports the path, leaving the conflict for the assistant to
+ *   resolve — exactly the mid-merge working-tree UX.
+ *
+ * File-level add/delete divergence (a file added, removed, or modified on only
+ * one side) is resolved here before any line merge, since `git merge-file`
+ * operates on three existing blobs.
+ *
+ * Binary files cannot be line-merged, so a binary file that diverged on both
+ * sides is resolved whole-file by the strategy (`ours`/`theirs`); under
+ * `assistant` the local copy is kept and the path is reported as a binary
+ * conflict, since markers cannot be written into binary content.
+ *
+ * The `overwrite` strategy never reaches here — it discards local edits and is
+ * a plain re-install at the pin.
+ */
+
+import { execFile } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { promisify } from "node:util";
+
+import { INSTALL_META_FILENAME } from "./install-from-github.js";
+import { computeFingerprint } from "./plugin-fingerprint.js";
+
+const execFileAsync = promisify(execFile);
+
+/** Cap on a single `git merge-file`; a per-file line merge is near-instant. */
+const MERGE_TIMEOUT_MS = 30_000;
+
+/**
+ * How hunks edited differently on both sides are reconciled. `ours`/`theirs`
+ * auto-resolve toward that side; `assistant` writes conflict markers and
+ * reports the conflict for later resolution. `overwrite` is not a merge
+ * strategy — the caller re-installs the pin wholesale instead of merging.
+ */
+export type PluginMergeStrategy = "ours" | "theirs" | "assistant";
+
+/** Human-readable labels for the conflict markers `assistant` writes. */
+export interface ConflictLabels {
+  readonly ours: string;
+  readonly base: string;
+  readonly theirs: string;
+}
+
+const DEFAULT_CONFLICT_LABELS: ConflictLabels = {
+  ours: "local edits",
+  base: "install baseline",
+  theirs: "upgrade pin",
+};
+
+/** Inputs for a three-way plugin-tree merge. */
+export interface MergePluginTreeOptions {
+  /** Re-materialized install-commit tree (the merge base). */
+  readonly baseDir: string;
+  /** Current on-disk install, carrying local edits (`ours`). */
+  readonly oursDir: string;
+  /** Marketplace-pinned tree being upgraded to (`theirs`). */
+  readonly theirsDir: string;
+  /** Empty directory the merged tree is written into. */
+  readonly destDir: string;
+  /** How to resolve hunks edited differently on both sides. */
+  readonly strategy: PluginMergeStrategy;
+  /** Marker labels for the `assistant` strategy. Defaults are used when omitted. */
+  readonly conflictLabels?: ConflictLabels;
+}
+
+/** Outcome of a three-way plugin-tree merge. */
+export interface PluginMergeResult {
+  /** Number of files written into the destination tree. */
+  readonly fileCount: number;
+  /**
+   * Paths (relative to the tree root) left for the assistant to resolve.
+   * Text files carry git conflict markers; modify/delete divergences keep the
+   * surviving content. Empty for `ours`/`theirs`, which auto-resolve.
+   */
+  readonly conflicts: readonly string[];
+  /**
+   * Paths of binary files that diverged on both sides. The local copy is kept
+   * (markers cannot be written into binary content), so the assistant must
+   * choose a version rather than edit markers. Empty for `ours`/`theirs`.
+   */
+  readonly binaryConflicts: readonly string[];
+}
+
+/** Result of merging a single file. */
+interface MergedFile {
+  readonly content: Buffer;
+  /** Conflict markers were written into `content` (text, `assistant` only). */
+  readonly conflicted: boolean;
+  /** A binary file conflicted; `content` is the kept local copy (`assistant`). */
+  readonly binaryConflicted: boolean;
+}
+
+/** A NUL byte in the leading bytes is the heuristic git uses to flag a blob as binary. */
+function isBinary(buf: Buffer): boolean {
+  const len = Math.min(buf.length, 8000);
+  for (let i = 0; i < len; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/** Write `content` to `destDir/rel`, creating parent directories as needed. */
+function writeInto(destDir: string, rel: string, content: Buffer): void {
+  const abs = join(destDir, rel);
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, content);
+}
+
+/**
+ * Line-merge three blobs with `git merge-file`. Non-conflicting hunks from both
+ * sides are always kept. `ours`/`theirs` auto-resolve conflicting hunks toward
+ * that side (no markers); `assistant` writes git conflict markers and flags the
+ * file as conflicted.
+ *
+ * Binary input cannot be line-merged: a side that matches the base did not
+ * change, so the other side's edit is taken. A binary blob changed on *both*
+ * sides is a true conflict — resolved whole-file by `ours`/`theirs`, or kept as
+ * the local copy and flagged under `assistant` (no markers possible).
+ */
+async function threeWayMergeFile(
+  ours: Buffer,
+  base: Buffer,
+  theirs: Buffer,
+  strategy: PluginMergeStrategy,
+  labels: ConflictLabels,
+): Promise<MergedFile> {
+  if (isBinary(ours) || isBinary(base) || isBinary(theirs)) {
+    if (ours.equals(base))
+      return { content: theirs, conflicted: false, binaryConflicted: false };
+    if (theirs.equals(base))
+      return { content: ours, conflicted: false, binaryConflicted: false };
+    if (strategy === "assistant") {
+      return { content: ours, conflicted: false, binaryConflicted: true };
+    }
+    return {
+      content: strategy === "ours" ? ours : theirs,
+      conflicted: false,
+      binaryConflicted: false,
+    };
+  }
+
+  const scratch = mkdtempSync(join(tmpdir(), "plugin-merge-file-"));
+  try {
+    const oursPath = join(scratch, "ours");
+    const basePath = join(scratch, "base");
+    const theirsPath = join(scratch, "theirs");
+    writeFileSync(oursPath, ours);
+    writeFileSync(basePath, base);
+    writeFileSync(theirsPath, theirs);
+
+    // `-p` prints the merged result to stdout instead of editing `ours` in
+    // place. `--ours`/`--theirs` auto-resolve conflicting hunks toward that
+    // side; with neither (the `assistant` strategy) git writes conflict
+    // markers, labelled via `-L` so the assistant can tell the sides apart.
+    const args = ["merge-file", "-p"];
+    if (strategy === "ours" || strategy === "theirs") {
+      args.push(`--${strategy}`);
+    } else {
+      args.push("-L", labels.ours, "-L", labels.base, "-L", labels.theirs);
+    }
+    args.push(oursPath, basePath, theirsPath);
+    try {
+      const { stdout } = await execFileAsync("git", args, {
+        cwd: scratch,
+        encoding: "buffer",
+        timeout: MERGE_TIMEOUT_MS,
+        maxBuffer: 64 * 1024 * 1024,
+      });
+      return { content: stdout, conflicted: false, binaryConflicted: false };
+    } catch (err) {
+      // `git merge-file` exits with the (positive) conflict count when markers
+      // were left, still printing the full merged bytes to stdout — that is the
+      // only rejection we may install. A killed process (timeout) or a
+      // `maxBuffer` overflow also rejects here, but with truncated/partial
+      // stdout we must NOT install it, or a large conflicted file would be
+      // silently corrupted; surface those as errors. A resolving flag never
+      // leaves conflicts, so any non-zero exit there is likewise a real
+      // failure.
+      const e = err as {
+        stdout?: Buffer;
+        code?: unknown;
+        killed?: boolean;
+        signal?: string | null;
+      };
+      const isConflictExit =
+        strategy === "assistant" &&
+        e.killed !== true &&
+        e.signal == null &&
+        typeof e.code === "number" &&
+        e.code > 0;
+      if (isConflictExit && Buffer.isBuffer(e.stdout)) {
+        return { content: e.stdout, conflicted: true, binaryConflicted: false };
+      }
+      throw err;
+    }
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Three-way merge `oursDir`/`theirsDir` against `baseDir` into `destDir` per
+ * `strategy`. The provenance sidecar is excluded on every side — it is
+ * rewritten by the caller after the swap and must not be carried through the
+ * merge.
+ *
+ * Returns the file count plus, for the `assistant` strategy, the paths left for
+ * the assistant to resolve (text files with conflict markers and modify/delete
+ * divergences) and the binary files that conflicted.
+ */
+export async function mergePluginTree({
+  baseDir,
+  oursDir,
+  theirsDir,
+  destDir,
+  strategy,
+  conflictLabels,
+}: MergePluginTreeOptions): Promise<PluginMergeResult> {
+  const labels = conflictLabels ?? DEFAULT_CONFLICT_LABELS;
+  const exclude = [INSTALL_META_FILENAME];
+  const base = computeFingerprint(baseDir, exclude).files;
+  const ours = computeFingerprint(oursDir, exclude).files;
+  const theirs = computeFingerprint(theirsDir, exclude).files;
+
+  const paths = new Set([
+    ...Object.keys(base),
+    ...Object.keys(ours),
+    ...Object.keys(theirs),
+  ]);
+
+  const readBase = (rel: string) => readFileSync(join(baseDir, rel));
+  const readOurs = (rel: string) => readFileSync(join(oursDir, rel));
+  const readTheirs = (rel: string) => readFileSync(join(theirsDir, rel));
+
+  let fileCount = 0;
+  const conflicts: string[] = [];
+  const binaryConflicts: string[] = [];
+  const keep = (rel: string, content: Buffer): void => {
+    writeInto(destDir, rel, content);
+    fileCount++;
+  };
+
+  for (const rel of paths) {
+    const b = base[rel];
+    const o = ours[rel];
+    const t = theirs[rel];
+
+    if (o !== undefined && t !== undefined) {
+      // Present on both sides: identical needs no merge; otherwise line-merge
+      // (an empty base when the file was added on both sides).
+      if (o === t) {
+        keep(rel, readOurs(rel));
+      } else {
+        const merged = await threeWayMergeFile(
+          readOurs(rel),
+          b !== undefined ? readBase(rel) : Buffer.alloc(0),
+          readTheirs(rel),
+          strategy,
+          labels,
+        );
+        keep(rel, merged.content);
+        if (merged.conflicted) conflicts.push(rel);
+        if (merged.binaryConflicted) binaryConflicts.push(rel);
+      }
+      continue;
+    }
+
+    if (o !== undefined) {
+      // Present only locally. A local-only addition (no base) always survives.
+      // A file deleted upstream is a delete: drop it when unchanged locally.
+      // On a modify/delete conflict `ours` keeps the edit and `theirs` honors
+      // the deletion; `assistant` keeps the edit and flags it (a whole-file
+      // conflict markers can't express).
+      if (b === undefined || (b !== o && strategy !== "theirs")) {
+        keep(rel, readOurs(rel));
+        if (b !== undefined && b !== o && strategy === "assistant") {
+          conflicts.push(rel);
+        }
+      }
+      continue;
+    }
+
+    if (t !== undefined) {
+      // Present only at the pin. A remote-only addition (no base) always lands.
+      // A file deleted locally is a delete: keep upstream's removal when the
+      // pin left it unchanged. On a delete/modify conflict `theirs` keeps the
+      // pin's edit and `ours` honors the local deletion; `assistant` keeps the
+      // pin's edit and flags it.
+      if (b === undefined || (b !== t && strategy !== "ours")) {
+        keep(rel, readTheirs(rel));
+        if (b !== undefined && b !== t && strategy === "assistant") {
+          conflicts.push(rel);
+        }
+      }
+      continue;
+    }
+
+    // Present only in the base: removed on both sides, so it stays removed.
+  }
+
+  return { fileCount, conflicts, binaryConflicts };
+}

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

@@ -120,6 +120,20 @@ export function compareFingerprint(
   };
 }
 
+/**
+ * Whether two fingerprints cover the same files with identical digests. Used to
+ * confirm a re-materialized tree faithfully reproduces a recorded baseline
+ * before it is trusted as a merge base.
+ */
+export function fingerprintsEqual(a: Fingerprint, b: Fingerprint): boolean {
+  const aKeys = Object.keys(a.files);
+  if (aKeys.length !== Object.keys(b.files).length) return false;
+  for (const key of aKeys) {
+    if (a.files[key] !== b.files[key]) return false;
+  }
+  return true;
+}
+
 /**
  * Parse a fingerprint from already-decoded JSON. Lenient by design — any shape
  * problem yields `null` so an older or hand-edited sidecar simply reports "no

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

@@ -0,0 +1,104 @@
+/**
+ * Detect the surfaces an installed plugin contributes to the running assistant,
+ * read directly from its on-disk tree.
+ *
+ * The host discovers a plugin's contributions from fixed directory conventions:
+ *
+ * - `hooks/<name>.{ts,js}`     → a lifecycle hook keyed by the file basename
+ *                                (see the external plugin loader's `loadHooks`).
+ * - `tools/<name>.{ts,js}`     → a tool, also keyed by the file basename
+ *                                (see the external plugin loader's tool walk).
+ * - `skills/<id>/SKILL.md`     → a skill owned by the plugin (see the skills
+ *                                catalog's `discoverPluginResidentSkills`).
+ *
+ * This module re-derives those same sets so `plugins inspect` can report exactly
+ * what a plugin contributes. Detection is intentionally a self-contained walk of
+ * the install tree — `cli/lib` does not reach into the daemon-internal loader or
+ * skills catalog — but it mirrors their conventions so inspect agrees with what
+ * the runtime actually loads.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** The surfaces an installed plugin contributes, each sorted and de-duplicated. */
+export interface PluginSurfaces {
+  /** Skill ids shipped at `skills/<id>/SKILL.md`. */
+  readonly skills: readonly string[];
+  /** Lifecycle hook names from `hooks/<name>.{ts,js}` (e.g. `pre-model-call`). */
+  readonly hooks: readonly string[];
+  /**
+   * Registered tool names from `tools/<name>.{ts,js}`. The loader derives a
+   * tool's name from its filename via {@link deriveToolName} (e.g.
+   * `create-issue.ts` registers as `create_issue`), so the derived form is
+   * reported rather than the raw basename. A tool module that overrides its own
+   * name via an exported `name` is not reflected here: that would require
+   * importing and executing untrusted plugin code, which inspection avoids.
+   */
+  readonly tools: readonly string[];
+}
+
+/**
+ * Derive a tool's registered name from its file basename, mirroring the
+ * external plugin loader's `deriveToolName`: non-alphanumeric runs collapse to
+ * `_`, leading/trailing `_` are trimmed, and an empty result falls back to
+ * `tool`. Keeps the inspected tool name aligned with the callable tool name.
+ */
+function deriveToolName(basename: string): string {
+  return (
+    basename.replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "tool"
+  );
+}
+
+/**
+ * List the basenames of every `.ts`/`.js` module directly under `dir`,
+ * preferring `.js` over `.ts` for the same basename (compiled-binary semantics)
+ * and skipping `.d.ts` declaration files. Returns names sorted for a
+ * deterministic listing. A missing or non-directory path yields `[]`.
+ *
+ * Mirrors the external plugin loader's `listSurfaceDir`, the gate it uses to
+ * turn a `hooks/`/`tools/` directory into loadable surfaces.
+ */
+function listModuleBasenames(dir: string): string[] {
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
+  const bases = new Set<string>();
+  for (const entry of readdirSync(dir)) {
+    if (entry.endsWith(".d.ts")) continue;
+    if (!entry.endsWith(".ts") && !entry.endsWith(".js")) continue;
+    bases.add(entry.slice(0, -3));
+  }
+  return [...bases].sort();
+}
+
+/**
+ * List the skill ids a plugin ships: each subdirectory of `skills/` that
+ * contains a `SKILL.md`. Mirrors the skills catalog's plugin-resident skill
+ * discovery so inspect reports the same set the runtime would surface.
+ */
+function listSkillIds(skillsDir: string): string[] {
+  if (!existsSync(skillsDir) || !statSync(skillsDir).isDirectory()) return [];
+  const ids: string[] = [];
+  for (const entry of readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    if (existsSync(join(skillsDir, entry.name, "SKILL.md"))) {
+      ids.push(entry.name);
+    }
+  }
+  return ids.sort();
+}
+
+/**
+ * Detect the {@link PluginSurfaces} an installed plugin contributes by walking
+ * its install tree at `pluginDir`. Surface types with no contributions come
+ * back as empty arrays; callers omit empty types from the rendered output.
+ */
+export function detectPluginSurfaces(pluginDir: string): PluginSurfaces {
+  const toolNames = listModuleBasenames(join(pluginDir, "tools")).map(
+    deriveToolName,
+  );
+  return {
+    skills: listSkillIds(join(pluginDir, "skills")),
+    hooks: listModuleBasenames(join(pluginDir, "hooks")),
+    tools: [...new Set(toolNames)].sort(),
+  };
+}