@vellumai/assistant 0.9.0-dev.202606170806.f7bee44 → 0.9.0-dev.202606171417.d2192ab

package/openapi.yaml

@@ -13241,7 +13241,7 @@ paths:
             type: string
           description:
             "Filter by provider. One of: anthropic, openai, gemini, ollama, fireworks, openrouter, openai-compatible,
-            minimax"
+            minimax, atlascloud"
       responses:
         "200":
           description: Successful response
@@ -19573,6 +19573,35 @@ paths:
                       - type: string
                       - type: "null"
                     description: Marketplace fetch error message, when the catalog could not be read.
+                  surfaces:
+                    anyOf:
+                      - type: object
+                        properties:
+                          skills:
+                            type: array
+                            items:
+                              type: string
+                            description: Skill ids shipped at `skills/<id>/SKILL.md`.
+                          hooks:
+                            type: array
+                            items:
+                              type: string
+                            description: Lifecycle hook names from `hooks/<name>.{ts,js}` (e.g. `pre-model-call`).
+                          tools:
+                            type: array
+                            items:
+                              type: string
+                            description:
+                              Registered tool names from `tools/<name>.{ts,js}` (filenames derived to tool names, e.g. `create-issue` →
+                              `create_issue`).
+                        required:
+                          - skills
+                          - hooks
+                          - tools
+                        additionalProperties: false
+                        description: Surfaces the installed copy contributes, read from its on-disk tree.
+                      - type: "null"
+                    description: Surfaces the installed copy contributes (skills, hooks, tools); null when the plugin is not installed.
                 required:
                   - name
                   - installed
@@ -19580,6 +19609,7 @@ paths:
                   - local
                   - remote
                   - remoteError
+                  - surfaces
                 additionalProperties: false
         "400":
           description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
@@ -19596,11 +19626,12 @@ paths:
         commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching
         the install. Installs lacking provenance are re-pinned to the current SHA. The assistant must be restarted to
         load the upgraded code. `strategy` controls how local edits are reconciled: `overwrite` (default) discards them
-        and re-installs the pin wholesale; `ours`/`theirs` perform a three-way merge against the re-materialized install
-        commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local
-        edit or the pin respectively; `assistant` is not yet supported (400). A merge strategy whose install-time
-        baseline cannot be reconstructed returns 409. Mirrors the CLI''s `assistant plugins upgrade <name> [--strategy
-        <s>]`.'
+        and re-installs the pin wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the
+        re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting
+        hunks toward the local edit (`ours`) or the pin (`theirs`), or writing git conflict markers into the file and
+        reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy
+        whose install-time baseline cannot be reconstructed returns 409. Mirrors the CLI''s `assistant plugins upgrade
+        <name> [--strategy <s>]`.'
       tags:
         - plugins
       parameters:
@@ -19689,6 +19720,20 @@ paths:
                       - overwrite
                       - assistant
                     description: Conflict-resolution strategy the upgrade applied.
+                  conflicts:
+                    type: array
+                    items:
+                      type: string
+                    description:
+                      "Paths left for the assistant to resolve under the `assistant` strategy: text files carry git conflict
+                      markers, modify/delete divergences keep the surviving content. Empty for other strategies."
+                  binaryConflicts:
+                    type: array
+                    items:
+                      type: string
+                    description:
+                      Binary files that conflicted under the `assistant` strategy; the local copy was kept since markers cannot
+                      be written into binary content. Empty for other strategies.
                   provenanceWasUnknown:
                     type: boolean
                     description:
@@ -19705,12 +19750,12 @@ paths:
                   - fileCount
                   - dryRun
                   - strategy
+                  - conflicts
+                  - binaryConflicts
                   - provenanceWasUnknown
                 additionalProperties: false
         "400":
-          description:
-            The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters), or the
-            `assistant` strategy was requested (not yet supported).
+          description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
         "404":
           description: No copy of the plugin is installed, or its source resolves to nothing.
         "409":
@@ -28199,6 +28244,7 @@ components:
         - openrouter
         - openai-compatible
         - minimax
+        - atlascloud
     ProfilePatchEntry:
       type: object
       properties:
@@ -28556,6 +28602,7 @@ components:
         - openrouter
         - openai-compatible
         - minimax
+        - atlascloud
     Auth:
       oneOf:
         - type: object

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0-dev.202606170806.f7bee44",
+  "version": "0.9.0-dev.202606171417.d2192ab",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/scheduler-reuse-conversation.test.ts

@@ -210,10 +210,13 @@ describe("scheduler conversation reuse", () => {
     expect(runs2[0].conversationId).toBe(firstConversationId);
   });
 
-  test("recurring schedule defaults to reuseConversation=true", async () => {
+  test("recurring schedule defaults to reuseConversation=false", async () => {
     /**
      * When no explicit reuseConversation is provided, recurring schedules
-     * default to true — subsequent runs reuse the same conversation.
+     * default to false — each run gets a fresh conversation. This keeps a
+     * weak model's per-run context bounded instead of accumulating a long,
+     * self-similar transcript that primes it to repeat or drift; durable
+     * cross-run state belongs in workspace files and memory, not history.
      */
 
     // GIVEN a recurring schedule with no explicit reuseConversation
@@ -224,7 +227,7 @@ describe("scheduler conversation reuse", () => {
       message: "Default reuse message",
       syntax: "rrule",
       expression: rruleExpr,
-      // no explicit reuseConversation — should default to true for recurring
+      // no explicit reuseConversation — should default to false
     });
 
     // WHEN the schedule fires for the first time
@@ -250,9 +253,9 @@ describe("scheduler conversation reuse", () => {
     await new Promise((resolve) => setTimeout(resolve, 500));
     scheduler2.stop();
 
-    // THEN the same conversation is reused
+    // THEN a fresh conversation is created instead of reusing the first
     expect(processedMessages).toHaveLength(1);
-    expect(processedMessages[0].conversationId).toBe(firstConversationId);
+    expect(processedMessages[0].conversationId).not.toBe(firstConversationId);
   });
 
   test("recurring schedule with reuseConversation=false creates new conversation each run", async () => {

package/src/cli/commands/plugins.ts

@@ -46,7 +46,6 @@ import {
   PluginNotUpgradableError,
   type PluginUpgradeResult,
   type PluginUpgradeStrategy,
-  PluginUpgradeStrategyUnsupportedError,
   upgradePlugin,
 } from "../lib/upgrade-plugin.js";
 import { getCliLogger } from "../logger.js";
@@ -76,6 +75,7 @@ Examples:
   $ assistant plugins upgrade example --dry-run
   $ assistant plugins upgrade example --strategy ours
   $ assistant plugins upgrade example --strategy theirs
+  $ assistant plugins upgrade example --strategy assistant
   $ assistant plugins search example
   $ assistant plugins search "^example"
   $ assistant plugins search example --json
@@ -180,7 +180,7 @@ Examples:
       plugins
         .command("inspect <name>")
         .description(
-          "Show a plugin's local install metadata and the marketplace pin, and whether an update is available",
+          "Show a plugin's local install metadata, the marketplace pin, whether an update is available, and the surfaces (skills, hooks, tools) it contributes",
         )
         .option("--json", "Emit machine-readable JSON instead of a summary")
         .action(async (name: string, opts: { json?: boolean }) => {
@@ -465,7 +465,6 @@ Examples:
               if (
                 err instanceof PluginNotInstalledError ||
                 err instanceof PluginNotUpgradableError ||
-                err instanceof PluginUpgradeStrategyUnsupportedError ||
                 err instanceof PluginMergeBaselineError ||
                 err instanceof InvalidPluginNameError
               ) {
@@ -550,12 +549,20 @@ function remoteLocation(remote: PluginRemoteInfo): string {
  * `location`, with a `drift` line under the installed copy.
  */
 function formatInspection(inspection: PluginInspection): string[] {
-  const { name, status, local, remote, remoteError } = inspection;
+  const { name, status, local, remote, remoteError, surfaces } = inspection;
   const lines: string[] = [name, "─".repeat(44)];
   const topRow = (label: string, value: string) =>
     lines.push(`${label.padEnd(11)} ${value}`);
   const blockRow = (label: string, value: string) =>
     lines.push(`  ${label.padEnd(9)} ${value}`);
+  // A surface block: the surface type as a heading, then its items indented
+  // under it. Omitted entirely when the plugin contributes none of that type,
+  // so the listing only ever shows what the plugin actually contributes.
+  const surfaceBlock = (label: string, items: readonly string[]) => {
+    if (items.length === 0) return;
+    lines.push(label);
+    for (const item of items) lines.push(`  ${item}`);
+  };
 
   topRow("status", statusLine(status));
 
@@ -590,6 +597,12 @@ function formatInspection(inspection: PluginInspection): string[] {
   const description = remote?.description ?? local?.description ?? null;
   if (description) topRow("description", description);
 
+  if (surfaces) {
+    surfaceBlock("skills", surfaces.skills);
+    surfaceBlock("hooks", surfaces.hooks);
+    surfaceBlock("tools", surfaces.tools);
+  }
+
   for (const issue of local?.issues ?? []) topRow("issue", issue);
 
   return lines;
@@ -628,10 +641,49 @@ function formatUpgrade(result: PluginUpgradeResult): string[] {
         result.fileCount === null
           ? ""
           : `(${result.fileCount} file${result.fileCount === 1 ? "" : "s"}) `;
+      const hasConflicts =
+        result.conflicts.length > 0 || result.binaryConflicts.length > 0;
+
+      // Under `assistant`, an unresolved merge leaves conflicts in the tree —
+      // the plugin would fail to load while any remain, so the usual "restart
+      // now" guidance is replaced with resolution instructions. Most conflicts
+      // carry git markers, but a modify/delete divergence (a file edited on one
+      // side and deleted on the other) keeps the surviving content with no
+      // markers, so the guidance covers both rather than assuming markers.
+      if (result.strategy === "assistant" && hasConflicts) {
+        const lines = [
+          `Merged "${name}" ${move} with conflicts`,
+          "",
+          `${count}→ ${result.target}`,
+        ];
+        if (result.conflicts.length > 0) {
+          lines.push(
+            "",
+            `Resolve ${result.conflicts.length} conflicted file${result.conflicts.length === 1 ? "" : "s"} (open each: resolve its git conflict markers, or — if a modify/delete divergence kept the file with none — decide whether to keep or remove it):`,
+            ...result.conflicts.map((p) => `  ${p}`),
+          );
+        }
+        if (result.binaryConflicts.length > 0) {
+          lines.push(
+            "",
+            `Binary conflict${result.binaryConflicts.length === 1 ? "" : "s"} (kept the local copy — choose a version manually):`,
+            ...result.binaryConflicts.map((p) => `  ${p}`),
+          );
+        }
+        lines.push(
+          "",
+          "Resolve the conflicts, then restart the assistant to pick up the upgrade.",
+        );
+        if (provenanceNote) lines.push(provenanceNote);
+        return lines;
+      }
+
       const mergeNote =
         result.strategy === "ours" || result.strategy === "theirs"
           ? `Local edits were merged (--strategy ${result.strategy}).`
-          : null;
+          : result.strategy === "assistant"
+            ? "Local edits were merged with no conflicts (--strategy assistant)."
+            : null;
       const lines = [
         `Upgraded "${name}" ${move}`,
         "",

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

@@ -90,6 +90,8 @@ function installPlugin(
     } | null;
     /** Embed a content fingerprint of the materialized tree in the sidecar. */
     fingerprint?: boolean;
+    /** Materialize surface directories (`hooks/<name>.ts`, `skills/<id>/SKILL.md`). */
+    surfaces?: { hooks?: string[]; tools?: string[]; skills?: string[] };
   } = {},
 ): void {
   const dir = join(workspace, name);
@@ -102,6 +104,18 @@ function installPlugin(
       description: "Installed copy.",
     }),
   );
+  for (const hook of opts.surfaces?.hooks ?? []) {
+    mkdirSync(join(dir, "hooks"), { recursive: true });
+    writeFileSync(join(dir, "hooks", `${hook}.ts`), "export default () => {};");
+  }
+  for (const tool of opts.surfaces?.tools ?? []) {
+    mkdirSync(join(dir, "tools"), { recursive: true });
+    writeFileSync(join(dir, "tools", `${tool}.ts`), "export default {};");
+  }
+  for (const skill of opts.surfaces?.skills ?? []) {
+    mkdirSync(join(dir, "skills", skill), { recursive: true });
+    writeFileSync(join(dir, "skills", skill, "SKILL.md"), `# ${skill}`);
+  }
   if (opts.sidecar !== null) {
     const sidecar = opts.sidecar ?? { commit: SHA_A };
     // Mirror install: fingerprint the tree before the sidecar is written so it
@@ -367,6 +381,46 @@ describe("inspectPlugin", () => {
     expect(result.local?.localChanges).toBeNull();
   });
 
+  test("reports the surfaces an installed copy contributes", async () => {
+    // GIVEN an installed plugin shipping hooks and skills but no tools
+    installPlugin(workspace, "level-up", {
+      sidecar: { commit: SHA_A },
+      surfaces: {
+        hooks: ["post-model-call", "init"],
+        skills: ["second-skill", "first-skill"],
+      },
+    });
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_A) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN the contributed surfaces are listed (sorted) and tools is empty
+    expect(result.surfaces).toEqual({
+      skills: ["first-skill", "second-skill"],
+      hooks: ["init", "post-model-call"],
+      tools: [],
+    });
+  });
+
+  test("leaves surfaces null when the plugin is not installed", async () => {
+    // GIVEN a marketplace entry with no local copy to walk
+    const fetch = makeFetch({ marketplace: manifestWith("level-up", SHA_B) });
+
+    // WHEN it is inspected
+    const result = await inspectPlugin(
+      { name: "level-up" },
+      { fetch, workspacePluginsDir: workspace },
+    );
+
+    // THEN there is no tree to read surfaces from
+    expect(result.installed).toBe(false);
+    expect(result.surfaces).toBeNull();
+  });
+
   test("throws when the plugin is neither installed nor in the marketplace", async () => {
     // GIVEN no local copy and an empty catalog
     const fetch = makeFetch({ marketplace: undefined });

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

@@ -4,8 +4,9 @@
  * The merge is exercised against three real temp directories (base/ours/theirs)
  * and the merged tree is read back from a fourth (dest). `git merge-file` runs
  * for real — these tests assert the line-level merge behavior (non-conflicting
- * hunks from both sides survive; conflicts resolve toward the strategy), the
- * file-level add/delete resolution, and binary whole-file handling.
+ * hunks from both sides survive; conflicts resolve toward `ours`/`theirs` or
+ * get conflict markers under `assistant`), the file-level add/delete
+ * resolution, and binary whole-file handling.
  */
 
 import {
@@ -97,7 +98,9 @@ describe("mergePluginTree", () => {
     expect(read("local-only.txt")).toBe("local\n");
     expect(read("remote-only.txt")).toBe("remote\n");
     expect(read("conflict.txt")).toBe("ours\n");
-    expect(count).toBe(4);
+    expect(count.fileCount).toBe(4);
+    expect(count.conflicts).toEqual([]);
+    expect(count.binaryConflicts).toEqual([]);
   });
 
   test("resolves conflicts toward the pin under the theirs strategy", async () => {
@@ -289,7 +292,7 @@ describe("mergePluginTree", () => {
 
     // THEN the sidecar is never carried through (the caller rewrites it)
     expect(read("install-meta.json")).toBeNull();
-    expect(count).toBe(1);
+    expect(count.fileCount).toBe(1);
   });
 
   test("merges files in nested directories", async () => {
@@ -310,4 +313,131 @@ describe("mergePluginTree", () => {
     // THEN the nested path is preserved and resolved
     expect(read("src/a/b.txt")).toBe("ours\n");
   });
+
+  test("writes git conflict markers and reports the path under the assistant strategy", async () => {
+    // GIVEN a file edited on disjoint lines by each side plus one true conflict
+    writeTree(baseDir, { "common.txt": "a\nb\nc\n", "conflict.txt": "base\n" });
+    writeTree(oursDir, { "common.txt": "A\nb\nc\n", "conflict.txt": "ours\n" });
+    writeTree(theirsDir, {
+      "common.txt": "a\nb\nC\n",
+      "conflict.txt": "theirs\n",
+    });
+
+    // WHEN merged with the `assistant` strategy
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "assistant",
+    });
+
+    // THEN the non-conflicting edits still auto-merge and only the true
+    // conflict carries markers naming both sides, and its path is reported
+    expect(read("common.txt")).toBe("A\nb\nC\n");
+    const conflict = read("conflict.txt") ?? "";
+    expect(conflict).toContain("<<<<<<<");
+    expect(conflict).toContain("=======");
+    expect(conflict).toContain(">>>>>>>");
+    expect(conflict).toContain("ours\n");
+    expect(conflict).toContain("theirs\n");
+    expect(result.conflicts).toEqual(["conflict.txt"]);
+    expect(result.binaryConflicts).toEqual([]);
+  });
+
+  test("uses the supplied conflict labels in the markers", async () => {
+    // GIVEN a true conflict and custom marker labels
+    writeTree(baseDir, { "f.txt": "base\n" });
+    writeTree(oursDir, { "f.txt": "ours\n" });
+    writeTree(theirsDir, { "f.txt": "theirs\n" });
+
+    // WHEN merged with the `assistant` strategy and explicit labels
+    await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "assistant",
+      conflictLabels: {
+        ours: "local edits (was abc1234)",
+        base: "install baseline abc1234",
+        theirs: "upgrade pin def5678",
+      },
+    });
+
+    // THEN the marker lines carry those labels
+    const merged = read("f.txt") ?? "";
+    expect(merged).toContain("<<<<<<< local edits (was abc1234)");
+    expect(merged).toContain(">>>>>>> upgrade pin def5678");
+  });
+
+  test("auto-merges with no markers when the assistant strategy hits no true conflict", async () => {
+    // GIVEN edits on disjoint lines of the same file (no overlapping hunk)
+    writeTree(baseDir, { "f.txt": "a\nb\nc\n" });
+    writeTree(oursDir, { "f.txt": "A\nb\nc\n" });
+    writeTree(theirsDir, { "f.txt": "a\nb\nC\n" });
+
+    // WHEN merged with the `assistant` strategy
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "assistant",
+    });
+
+    // THEN both edits merge cleanly with no markers and nothing is reported
+    const merged = read("f.txt") ?? "";
+    expect(merged).toBe("A\nb\nC\n");
+    expect(merged).not.toContain("<<<<<<<");
+    expect(result.conflicts).toEqual([]);
+    expect(result.binaryConflicts).toEqual([]);
+  });
+
+  test("keeps the local copy and reports a binary conflict under the assistant strategy", async () => {
+    // GIVEN a binary file (NUL bytes) diverged on both sides
+    const base = Buffer.from([0x00, 0x01, 0x02]);
+    const ours = Buffer.from([0x00, 0xaa, 0xbb]);
+    const theirs = Buffer.from([0x00, 0xcc, 0xdd]);
+    writeTree(baseDir, { "img.bin": base });
+    writeTree(oursDir, { "img.bin": ours });
+    writeTree(theirsDir, { "img.bin": theirs });
+
+    // WHEN merged with the `assistant` strategy
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "assistant",
+    });
+
+    // THEN the local copy is kept byte-for-byte (markers are impossible) and
+    // the path is surfaced as a binary conflict, not a marker conflict
+    expect(readFileSync(join(destDir, "img.bin")).equals(ours)).toBe(true);
+    expect(result.binaryConflicts).toEqual(["img.bin"]);
+    expect(result.conflicts).toEqual([]);
+  });
+
+  test("keeps the surviving content and reports a modify/delete conflict under the assistant strategy", async () => {
+    // GIVEN a file edited locally but deleted at the pin
+    writeTree(baseDir, { "f.txt": "base\n" });
+    writeTree(oursDir, { "f.txt": "local edit\n" });
+    writeTree(theirsDir, {});
+
+    // WHEN merged with the `assistant` strategy
+    const result = await mergePluginTree({
+      baseDir,
+      oursDir,
+      theirsDir,
+      destDir,
+      strategy: "assistant",
+    });
+
+    // THEN the local edit is preserved (never silently dropped) and the
+    // modify/delete divergence is reported for resolution
+    expect(read("f.txt")).toBe("local edit\n");
+    expect(result.conflicts).toEqual(["f.txt"]);
+    expect(result.binaryConflicts).toEqual([]);
+  });
 });

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: [] });
+  });
+});