@vellumai/assistant 0.9.1-staging.1 → 0.10.0-staging.2

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

@@ -0,0 +1,111 @@
+/**
+ * Tests for {@link detectPluginSurfaces}.
+ *
+ * Surface detection is a pure walk of an installed plugin's on-disk tree, so
+ * the fixtures materialize the `hooks/`, `tools/`, and `skills/` directory
+ * conventions in a real temp dir and assert the derived listing matches what
+ * the runtime loader / skills catalog would discover.
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { detectPluginSurfaces } from "../plugin-surfaces.js";
+
+let pluginDir: string;
+
+beforeEach(() => {
+  pluginDir = mkdtempSync(join(tmpdir(), "plugin-surfaces-"));
+});
+
+afterEach(() => {
+  rmSync(pluginDir, { recursive: true, force: true });
+});
+
+/** Create `<pluginDir>/<rel>` with empty contents, making parents as needed. */
+function touch(rel: string): void {
+  const path = join(pluginDir, rel);
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, "");
+}
+
+describe("detectPluginSurfaces", () => {
+  test("lists hooks, tools, and skills from the directory conventions", () => {
+    // GIVEN a plugin shipping two hooks, one tool, and two skills
+    touch("hooks/post-model-call.ts");
+    touch("hooks/init.ts");
+    touch("tools/summarize.ts");
+    touch("skills/first-skill/SKILL.md");
+    touch("skills/second-skill/SKILL.md");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN each surface type lists its items, sorted
+    expect(surfaces.hooks).toEqual(["init", "post-model-call"]);
+    expect(surfaces.tools).toEqual(["summarize"]);
+    expect(surfaces.skills).toEqual(["first-skill", "second-skill"]);
+  });
+
+  test("reports tools under their registered name, not the raw filename", () => {
+    // GIVEN a tool whose filename is not already a valid tool-name segment
+    touch("tools/create-issue.ts");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN the derived (registered) name is reported, matching the loader
+    expect(surfaces.tools).toEqual(["create_issue"]);
+  });
+
+  test("omits surface types the plugin does not contribute", () => {
+    // GIVEN a plugin that ships only a hook
+    touch("hooks/post-model-call.ts");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN the contributed type is listed and the others are empty
+    expect(surfaces.hooks).toEqual(["post-model-call"]);
+    expect(surfaces.tools).toEqual([]);
+    expect(surfaces.skills).toEqual([]);
+  });
+
+  test("prefers .js over .ts for the same basename and skips .d.ts declarations", () => {
+    // GIVEN a compiled hook shipping both .ts and .js plus a .d.ts declaration
+    touch("hooks/post-model-call.ts");
+    touch("hooks/post-model-call.js");
+    touch("hooks/post-model-call.d.ts");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN the basename appears once and the declaration file is ignored
+    expect(surfaces.hooks).toEqual(["post-model-call"]);
+  });
+
+  test("ignores skill directories without a SKILL.md", () => {
+    // GIVEN a skills dir with one real skill and one stray subdirectory
+    touch("skills/real-skill/SKILL.md");
+    touch("skills/not-a-skill/README.md");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN only the directory carrying a SKILL.md is reported
+    expect(surfaces.skills).toEqual(["real-skill"]);
+  });
+
+  test("returns empty surfaces for a plugin with no surface directories", () => {
+    // GIVEN a plugin tree with only a package.json
+    touch("package.json");
+
+    // WHEN its surfaces are detected
+    const surfaces = detectPluginSurfaces(pluginDir);
+
+    // THEN every surface type is empty
+    expect(surfaces).toEqual({ skills: [], hooks: [], tools: [] });
+  });
+});

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

@@ -31,7 +31,6 @@ import { PluginNotInstalledError } from "../uninstall-plugin.js";
 import {
   PluginMergeBaselineError,
   PluginNotUpgradableError,
-  PluginUpgradeStrategyUnsupportedError,
   upgradePlugin,
 } from "../upgrade-plugin.js";
 
@@ -582,19 +581,62 @@ describe("upgradePlugin --strategy", () => {
     expect(installedFile("level-up", "local-only.txt")).toBeNull();
   });
 
-  test("throws PluginUpgradeStrategyUnsupportedError for the assistant strategy", async () => {
-    // GIVEN an installed copy and an advanced pin
+  test("--strategy assistant writes conflict markers and reports the conflicted path", async () => {
+    // GIVEN an install at SHA_A with local edits, and a pin at SHA_B
     installMergeCopy("level-up", OURS, SHA_A, BASE);
     const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: BASE, [SHA_B]: THEIRS });
 
-    // WHEN an upgrade requests the not-yet-implemented `assistant` strategy
-    // THEN it is rejected before any clone runs
-    await expect(
-      upgradePlugin(
-        { name: "level-up", strategy: "assistant" },
-        { fetch, runGit: unusedGitRunner, workspacePluginsDir: pluginsDir },
-      ),
-    ).rejects.toBeInstanceOf(PluginUpgradeStrategyUnsupportedError);
+    // WHEN the plugin is upgraded with the `assistant` strategy
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "assistant" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN it moves to the pin and records the strategy
+    expect(result.outcome).toBe("upgraded");
+    expect(result.toCommit).toBe(SHA_B);
+    expect(result.strategy).toBe("assistant");
+    // AND non-conflicting edits from both sides still auto-merge
+    expect(installedFile("level-up", "common.txt")).toBe("A\nb\nC\n");
+    expect(installedFile("level-up", "local-only.txt")).toBe("added locally\n");
+    expect(installedFile("level-up", "remote-only.txt")).toBe(
+      "added upstream\n",
+    );
+    // AND the true conflict carries git markers naming both commits
+    const conflict = installedFile("level-up", "conflict.txt") ?? "";
+    expect(conflict).toContain("<<<<<<<");
+    expect(conflict).toContain(SHA_A.slice(0, 7));
+    expect(conflict).toContain(SHA_B.slice(0, 7));
+    expect(conflict).toContain("ours\n");
+    expect(conflict).toContain("theirs\n");
+    // AND the conflicted path is surfaced for the assistant to resolve
+    expect(result.conflicts).toEqual(["conflict.txt"]);
+    expect(result.binaryConflicts).toEqual([]);
+  });
+
+  test("--strategy assistant reports no conflicts on a clean three-way merge", async () => {
+    // GIVEN an install whose only divergence from the pin auto-merges cleanly
+    const cleanOurs: Tree = { "common.txt": "A\nb\nc\n" };
+    const cleanBase: Tree = { "common.txt": "a\nb\nc\n" };
+    const cleanTheirs: Tree = { "common.txt": "a\nb\nC\n" };
+    installMergeCopy("level-up", cleanOurs, SHA_A, cleanBase);
+    const fetch = makeFetch({ manifest: manifestWith("level-up", SHA_B) });
+    const runGit = treeGitRunner({ [SHA_A]: cleanBase, [SHA_B]: cleanTheirs });
+
+    // WHEN the plugin is upgraded with the `assistant` strategy
+    const result = await upgradePlugin(
+      { name: "level-up", strategy: "assistant" },
+      { fetch, runGit, workspacePluginsDir: pluginsDir },
+    );
+
+    // THEN both edits merge with no markers and nothing needs resolution
+    expect(result.strategy).toBe("assistant");
+    expect(result.conflicts).toEqual([]);
+    expect(result.binaryConflicts).toEqual([]);
+    const merged = installedFile("level-up", "common.txt") ?? "";
+    expect(merged).toBe("A\nb\nC\n");
+    expect(merged).not.toContain("<<<<<<<");
   });
 
   test("throws PluginMergeBaselineError when no fingerprint was recorded", async () => {

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/merge-plugin-tree.ts

@@ -11,18 +11,25 @@
  * 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 by the
- * caller's strategy — `--ours` keeps the local hunk, `--theirs` the pinned one.
+ * 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 rather than corrupted with
- * conflict markers.
+ * 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. The `assistant` strategy is not yet supported.
+ * a plain re-install at the pin.
  */
 
 import { execFile } from "node:child_process";
@@ -46,11 +53,25 @@ const execFileAsync = promisify(execFile);
 const MERGE_TIMEOUT_MS = 30_000;
 
 /**
- * Conflict-resolution strategy for the hunks `git merge-file` cannot
- * auto-resolve. `overwrite` and `assistant` are not merge strategies and are
- * handled by the caller before a merge is attempted.
+ * 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 MergeConflictStrategy = "ours" | "theirs";
+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 {
@@ -63,7 +84,36 @@ export interface MergePluginTreeOptions {
   /** Empty directory the merged tree is written into. */
   readonly destDir: string;
   /** How to resolve hunks edited differently on both sides. */
-  readonly strategy: MergeConflictStrategy;
+  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. */
@@ -83,23 +133,36 @@ function writeInto(destDir: string, rel: string, content: Buffer): void {
 }
 
 /**
- * Line-merge three blobs with `git merge-file`, resolving conflicting hunks
- * toward `strategy`. Non-conflicting hunks from both sides are always kept.
+ * 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; only a blob changed on *both*
- * sides is a true conflict resolved whole-file by `strategy`, avoiding a
- * marker-corrupted blob.
+ * 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: MergeConflictStrategy,
-): Promise<Buffer> {
+  strategy: PluginMergeStrategy,
+  labels: ConflictLabels,
+): Promise<MergedFile> {
   if (isBinary(ours) || isBinary(base) || isBinary(theirs)) {
-    if (ours.equals(base)) return theirs;
-    if (theirs.equals(base)) return ours;
-    return strategy === "ours" ? ours : 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-"));
@@ -112,18 +175,16 @@ async function threeWayMergeFile(
     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 (so no markers are ever written). `git merge-file` exits non-zero
-    // when conflicts remained — impossible with a resolving flag, but stdout
-    // still carries the merged bytes, so capture it from the error too.
-    const args = [
-      "merge-file",
-      "-p",
-      `--${strategy}`,
-      oursPath,
-      basePath,
-      theirsPath,
-    ];
+    // 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,
@@ -131,10 +192,31 @@ async function threeWayMergeFile(
         timeout: MERGE_TIMEOUT_MS,
         maxBuffer: 64 * 1024 * 1024,
       });
-      return stdout;
+      return { content: stdout, conflicted: false, binaryConflicted: false };
     } catch (err) {
-      const stdout = (err as { stdout?: Buffer }).stdout;
-      if (Buffer.isBuffer(stdout)) return stdout;
+      // `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 {
@@ -143,12 +225,14 @@ async function threeWayMergeFile(
 }
 
 /**
- * Three-way merge `oursDir`/`theirsDir` against `baseDir` into `destDir`,
- * resolving conflicts toward `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.
+ * 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 number of files written into `destDir`.
+ * 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,
@@ -156,7 +240,9 @@ export async function mergePluginTree({
   theirsDir,
   destDir,
   strategy,
-}: MergePluginTreeOptions): Promise<number> {
+  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;
@@ -173,6 +259,8 @@ export async function mergePluginTree({
   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++;
@@ -194,18 +282,26 @@ export async function mergePluginTree({
           b !== undefined ? readBase(rel) : Buffer.alloc(0),
           readTheirs(rel),
           strategy,
+          labels,
         );
-        keep(rel, merged);
+        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,
-      // and on a modify/delete conflict let the strategy decide.
-      if (b === undefined || (b !== o && strategy === "ours")) {
+      // 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;
     }
@@ -213,10 +309,14 @@ export async function mergePluginTree({
     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, and on a delete/modify conflict let the strategy
-      // decide.
-      if (b === undefined || (b !== t && strategy === "theirs")) {
+      // 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;
     }
@@ -224,5 +324,5 @@ export async function mergePluginTree({
     // Present only in the base: removed on both sides, so it stays removed.
   }
 
-  return fileCount;
+  return { fileCount, conflicts, binaryConflicts };
 }

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(),
+  };
+}