@vellumai/assistant 0.6.4 → 0.6.6

package/src/__tests__/plugin-skill-contribution.test.ts

@@ -0,0 +1,367 @@
+/**
+ * Tests for plugin-contributed skills (PR 33).
+ *
+ * Covers:
+ * - A plugin declaring `skills: [...]` has its entries registered after
+ *   bootstrap's `init()` succeeds.
+ * - The registered skill is discoverable via `loadSkillCatalog` and
+ *   resolvable via `loadSkillBySelector` (the exact entry points the model's
+ *   `skill_load` / `skill_execute` flow use).
+ * - Shutdown (runShutdownHooks) unregisters the plugin's skills so repeated
+ *   bootstraps don't leak catalog entries.
+ * - Ref-counted register/unregister semantics match the tool registry's
+ *   per-skill-id semantics (PR 13 precedent).
+ *
+ * Strategy mirrors `plugin-bootstrap.test.ts`: stub the credential store so
+ * bootstrap doesn't hit real backends, and `resetPluginRegistryForTests` /
+ * `resetPluginSkillContributionsForTests` between cases for isolation.
+ */
+
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Stub credential store before importing bootstrap so the module captures
+// the fake binding.
+const getSecureKeyAsyncMock = mock(
+  async (_account: string): Promise<string | undefined> => undefined,
+);
+mock.module("../security/secure-keys.js", () => ({
+  getSecureKeyAsync: getSecureKeyAsyncMock,
+}));
+
+import type { AssistantConfig } from "../config/schema.js";
+import { loadSkillBySelector, loadSkillCatalog } from "../config/skills.js";
+import {
+  bootstrapPlugins,
+  type DaemonContext,
+} from "../daemon/external-plugins-bootstrap.js";
+import { runShutdownHooks } from "../daemon/shutdown-registry.js";
+import {
+  getPluginContributedSkillDefinition,
+  getPluginContributedSkillSummaries,
+  getPluginSkillRefCount,
+  registerPluginSkills,
+  resetPluginSkillContributionsForTests,
+  unregisterPluginSkills,
+} from "../plugins/plugin-skill-contributions.js";
+import {
+  registerPlugin,
+  resetPluginRegistryForTests,
+} from "../plugins/registry.js";
+import {
+  type Plugin,
+  PluginExecutionError,
+  type PluginSkillRegistration,
+} from "../plugins/types.js";
+
+// Per-process temp tree so bootstrap's plugin-storage directory creation
+// doesn't touch the developer's real ~/.vellum.
+const TEST_INSTANCE_DIR = join(
+  tmpdir(),
+  `vellum-plugin-skill-test-${process.pid}`,
+);
+process.env.BASE_DATA_DIR = TEST_INSTANCE_DIR;
+
+const fakeConfig = {} as unknown as AssistantConfig;
+const fakeCtx: DaemonContext = {
+  config: fakeConfig,
+  assistantVersion: "9.9.9-test",
+};
+
+/** Build a plugin that contributes one or more skills. */
+function buildSkillPlugin(
+  name: string,
+  skills: PluginSkillRegistration[],
+  extras: Partial<Omit<Plugin, "manifest" | "skills">> = {},
+): Plugin {
+  return {
+    manifest: {
+      name,
+      version: "0.0.1",
+      requires: { pluginRuntime: "v1" },
+    },
+    skills,
+    ...extras,
+  };
+}
+
+describe("plugin skill contributions", () => {
+  beforeEach(async () => {
+    resetPluginRegistryForTests();
+    resetPluginSkillContributionsForTests();
+    getSecureKeyAsyncMock.mockReset();
+    getSecureKeyAsyncMock.mockImplementation(async () => undefined);
+    await rm(TEST_INSTANCE_DIR, { recursive: true, force: true });
+  });
+
+  test("plugin skills are registered after bootstrap and exposed by the catalog", async () => {
+    const skill: PluginSkillRegistration = {
+      id: "plugin-demo-skill",
+      name: "plugin-demo",
+      displayName: "Plugin Demo",
+      description: "A skill contributed by a plugin",
+      body: "# Plugin Demo\n\nThis is the plugin-provided body.",
+      activationHints: ["demo", "plugin"],
+    };
+
+    registerPlugin(buildSkillPlugin("demo-plugin", [skill]));
+    await bootstrapPlugins(fakeCtx);
+
+    // Ref count bumped to exactly 1 so we can tell register and unregister
+    // are balanced downstream.
+    expect(getPluginSkillRefCount("demo-plugin")).toBe(1);
+
+    // In-memory registry query surfaces the summary form.
+    const summaries = getPluginContributedSkillSummaries();
+    const registered = summaries.find((s) => s.id === "plugin-demo-skill");
+    expect(registered).toBeDefined();
+    expect(registered?.source).toBe("plugin");
+    expect(registered?.name).toBe("plugin-demo");
+    expect(registered?.displayName).toBe("Plugin Demo");
+    expect(registered?.activationHints).toEqual(["demo", "plugin"]);
+    // Summary must not carry the body — bodies are definition-only.
+    expect((registered as unknown as { body?: unknown }).body).toBeUndefined();
+
+    // The full definition is retrievable by id.
+    const def = getPluginContributedSkillDefinition("plugin-demo-skill");
+    expect(def).toBeDefined();
+    expect(def?.body).toContain("This is the plugin-provided body");
+  });
+
+  test("catalog and loadSkillBySelector discover plugin-contributed skills (skill_load pathway)", async () => {
+    const skill: PluginSkillRegistration = {
+      id: "catalog-visible-skill",
+      name: "catalog-visible",
+      description: "A plugin skill expected to surface in loadSkillCatalog",
+      body: "# Catalog-Visible Skill\n\nBody content for skill_load.",
+    };
+
+    registerPlugin(buildSkillPlugin("catalog-plugin", [skill]));
+    await bootstrapPlugins(fakeCtx);
+
+    // loadSkillCatalog is the exact entry point `skill_load` consults via
+    // `loadSkillBySelector` -> `resolveSkillSelector`.
+    const catalog = loadSkillCatalog();
+    const found = catalog.find((s) => s.id === "catalog-visible-skill");
+    expect(found).toBeDefined();
+    expect(found?.source).toBe("plugin");
+    expect(found?.description).toBe(skill.description);
+
+    // loadSkillBySelector is what SkillLoadTool.execute calls — it must
+    // return a fully-populated SkillDefinition, including the body.
+    const lookup = loadSkillBySelector("catalog-visible-skill");
+    expect(lookup.error).toBeUndefined();
+    expect(lookup.skill).toBeDefined();
+    expect(lookup.skill?.id).toBe("catalog-visible-skill");
+    expect(lookup.skill?.body).toContain("Body content for skill_load");
+
+    // And name-based resolution (what users type when the model picks a
+    // skill by name) works the same way.
+    const byName = loadSkillBySelector("catalog-visible");
+    expect(byName.skill?.id).toBe("catalog-visible-skill");
+  });
+
+  test("shutdown unregisters plugin skills so the catalog no longer lists them", async () => {
+    const skill: PluginSkillRegistration = {
+      id: "ephemeral-skill",
+      name: "ephemeral",
+      description: "Disappears after shutdown",
+      body: "Only visible while the plugin is alive.",
+    };
+
+    registerPlugin(buildSkillPlugin("ephemeral-plugin", [skill]));
+    await bootstrapPlugins(fakeCtx);
+
+    // Sanity: present before shutdown.
+    expect(loadSkillCatalog().some((s) => s.id === "ephemeral-skill")).toBe(
+      true,
+    );
+    expect(getPluginSkillRefCount("ephemeral-plugin")).toBe(1);
+
+    await runShutdownHooks("test-shutdown");
+
+    // After shutdown, the plugin's skill is gone from both the in-memory
+    // registry and any catalog view that consults it.
+    expect(getPluginSkillRefCount("ephemeral-plugin")).toBe(0);
+    expect(
+      getPluginContributedSkillDefinition("ephemeral-skill"),
+    ).toBeUndefined();
+
+    const catalogAfter = loadSkillCatalog();
+    expect(catalogAfter.some((s) => s.id === "ephemeral-skill")).toBe(false);
+
+    // And the selector lookup the model would use fails closed.
+    const lookup = loadSkillBySelector("ephemeral-skill");
+    expect(lookup.skill).toBeUndefined();
+  });
+
+  test("bootstrap is a no-op for plugins without a skills list", async () => {
+    // A plugin with no `skills` field must not bump ref counts or
+    // populate the catalog at all.
+    registerPlugin({
+      manifest: {
+        name: "no-skills-plugin",
+        version: "0.0.1",
+        requires: { pluginRuntime: "v1" },
+      },
+    });
+
+    await bootstrapPlugins(fakeCtx);
+
+    expect(getPluginSkillRefCount("no-skills-plugin")).toBe(0);
+    expect(getPluginContributedSkillSummaries()).toEqual([]);
+  });
+
+  test("duplicate skill id across plugins fails bootstrap with the plugin named", async () => {
+    const shared: PluginSkillRegistration = {
+      id: "contested-id",
+      name: "contested",
+      description: "First",
+      body: "from first plugin",
+    };
+    const duplicate: PluginSkillRegistration = {
+      id: "contested-id",
+      name: "contested",
+      description: "Second",
+      body: "from second plugin",
+    };
+
+    registerPlugin(buildSkillPlugin("first-plugin", [shared]));
+    registerPlugin(buildSkillPlugin("second-plugin", [duplicate]));
+
+    let caught: unknown;
+    try {
+      await bootstrapPlugins(fakeCtx);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(PluginExecutionError);
+    // The error must identify which plugin tripped the collision so
+    // operators can deploy a fix.
+    const msg = (caught as PluginExecutionError).message;
+    expect(msg).toContain("second-plugin");
+    expect(msg).toContain("contested-id");
+  });
+
+  test("intra-batch duplicate skill id in one plugin is rejected at registration", () => {
+    // Directly exercise the registry (no bootstrap) — a single plugin
+    // declaring the same id twice is a configuration bug and must fail
+    // loudly rather than silently overwrite.
+    expect(() =>
+      registerPluginSkills("dup-plugin", [
+        {
+          id: "dup-id",
+          name: "one",
+          description: "first",
+          body: "A",
+        },
+        {
+          id: "dup-id",
+          name: "two",
+          description: "second",
+          body: "B",
+        },
+      ]),
+    ).toThrow(PluginExecutionError);
+    expect(() =>
+      registerPluginSkills("dup-plugin", [
+        { id: "x", name: "one", description: "a", body: "A" },
+        { id: "x", name: "two", description: "b", body: "B" },
+      ]),
+    ).toThrow(/declared skill "x" more than once/);
+  });
+
+  test("ref-counted unregister: second unregister call after repeated registers drops skills", () => {
+    const registrations: PluginSkillRegistration[] = [
+      {
+        id: "refcount-skill",
+        name: "refcount",
+        description: "Ref-count demo",
+        body: "stays until the counter hits zero",
+      },
+    ];
+
+    registerPluginSkills("refcount-plugin", registrations);
+    // Second call is the "same plugin registered again" pattern (hot
+    // reload). It must bump the counter without re-inserting.
+    registerPluginSkills("refcount-plugin", registrations);
+    expect(getPluginSkillRefCount("refcount-plugin")).toBe(2);
+    expect(getPluginContributedSkillDefinition("refcount-skill")).toBeDefined();
+
+    // One unregister decrements only — skill must still be registered.
+    unregisterPluginSkills("refcount-plugin");
+    expect(getPluginSkillRefCount("refcount-plugin")).toBe(1);
+    expect(getPluginContributedSkillDefinition("refcount-skill")).toBeDefined();
+
+    // Second unregister drops the entry for real.
+    unregisterPluginSkills("refcount-plugin");
+    expect(getPluginSkillRefCount("refcount-plugin")).toBe(0);
+    expect(
+      getPluginContributedSkillDefinition("refcount-skill"),
+    ).toBeUndefined();
+
+    // Third unregister (over-decrement) is a no-op, not a throw — mirrors
+    // the tool-registry behavior so shutdown races don't crash the
+    // daemon.
+    expect(() => unregisterPluginSkills("refcount-plugin")).not.toThrow();
+  });
+
+  test("managed (filesystem) skill with the same id overrides a plugin-contributed skill", async () => {
+    // Plugin skills sit below managed/workspace in the catalog precedence
+    // chain so a user can shadow a plugin-provided skill by dropping a
+    // SKILL.md with the same id under ~/.vellum/workspace/skills. The test
+    // harness configures VELLUM_WORKSPACE_DIR via the bun test preload, so
+    // we can synthesize a filesystem skill for the same id and assert it
+    // wins.
+    const { mkdirSync, writeFileSync, rmSync, existsSync } =
+      await import("node:fs");
+
+    const workspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+    // Skip the filesystem override check when the harness did not provide a
+    // workspace dir — the other tests in this file still cover catalog
+    // visibility, which is the core of PR 33.
+    if (!workspaceDir) {
+      return;
+    }
+
+    const skillsDir = join(workspaceDir, "skills", "shared-id");
+    mkdirSync(skillsDir, { recursive: true });
+    writeFileSync(
+      join(skillsDir, "SKILL.md"),
+      [
+        "---",
+        'name: "filesystem-version"',
+        'description: "User-authored override"',
+        "---",
+        "",
+        "# Filesystem Override",
+      ].join("\n"),
+    );
+
+    const pluginSkill: PluginSkillRegistration = {
+      id: "shared-id",
+      name: "plugin-version",
+      description: "Plugin-provided skill that should be shadowed",
+      body: "plugin body",
+    };
+    registerPlugin(buildSkillPlugin("shadow-plugin", [pluginSkill]));
+
+    try {
+      await bootstrapPlugins(fakeCtx);
+
+      const catalog = loadSkillCatalog();
+      const entry = catalog.find((s) => s.id === "shared-id");
+      // The filesystem SKILL.md wins — source flips to "managed" and the
+      // plugin's metadata is not what we see.
+      expect(entry).toBeDefined();
+      expect(entry?.source).toBe("managed");
+      expect(entry?.name).toBe("filesystem-version");
+    } finally {
+      if (existsSync(skillsDir)) {
+        rmSync(skillsDir, { recursive: true, force: true });
+      }
+    }
+  });
+});

package/src/__tests__/plugin-tool-contribution.test.ts

@@ -0,0 +1,286 @@
+/**
+ * Tests for plugin tool contributions (PR 31).
+ *
+ * Covers the end-to-end flow that lets a plugin declare tools on its
+ * manifest and have them surface through the global tool registry:
+ *
+ * - Registering a plugin with `tools: Tool[]`, running `bootstrapPlugins`,
+ *   and observing the contributed tool via `getAllTools()` / `getTool()`.
+ * - Tool ownership metadata (`origin: "plugin"`, `ownerPluginId: <plugin>`)
+ *   stamped authoritatively by `registerPluginTools` regardless of what the
+ *   plugin author set on the incoming object.
+ * - Shutdown hook unregistering the contributed tools so the registry is
+ *   clean again after teardown.
+ * - Direct `registerPluginTools` / `unregisterPluginTools` semantics,
+ *   including the plugin-scoped ref count.
+ *
+ * Uses `mock.module` to stub the credential store so bootstrap doesn't hit
+ * the real backend. `resetPluginRegistryForTests()` and
+ * `__clearRegistryForTesting()` isolate registry state between cases so
+ * this file can run alongside other plugin/tool-registry tests without
+ * cross-contamination.
+ */
+
+import { rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+// Mock the credential store before importing the bootstrap so the module
+// under test captures the stubbed binding. Bootstrap only calls this for
+// plugins that declare `requiresCredential`; the tests in this file don't,
+// so the stub simply returns undefined.
+const getSecureKeyAsyncMock = mock(
+  async (_account: string): Promise<string | undefined> => undefined,
+);
+mock.module("../security/secure-keys.js", () => ({
+  getSecureKeyAsync: getSecureKeyAsyncMock,
+}));
+
+import type { AssistantConfig } from "../config/schema.js";
+import {
+  bootstrapPlugins,
+  type DaemonContext,
+} from "../daemon/external-plugins-bootstrap.js";
+import { runShutdownHooks } from "../daemon/shutdown-registry.js";
+import { RiskLevel } from "../permissions/types.js";
+import {
+  registerPlugin,
+  resetPluginRegistryForTests,
+} from "../plugins/registry.js";
+import type { Plugin } from "../plugins/types.js";
+import type { ToolDefinition } from "../providers/types.js";
+import {
+  __clearRegistryForTesting,
+  __resetRegistryForTesting,
+  getAllTools,
+  getPluginRefCount,
+  getTool,
+  registerPluginTools,
+  unregisterPluginTools,
+} from "../tools/registry.js";
+import type { Tool, ToolContext, ToolExecutionResult } from "../tools/types.js";
+
+// Redirect plugin-storage-directory creation into a per-process temp tree so
+// the test doesn't touch the developer's real ~/.vellum. This matches the
+// convention used by plugin-bootstrap.test.ts.
+const TEST_INSTANCE_DIR = join(
+  tmpdir(),
+  `vellum-plugin-tool-contrib-test-${process.pid}`,
+);
+process.env.BASE_DATA_DIR = TEST_INSTANCE_DIR;
+
+const fakeConfig = {} as unknown as AssistantConfig;
+const fakeCtx: DaemonContext = {
+  config: fakeConfig,
+  assistantVersion: "9.9.9-test",
+};
+
+function makeFakeTool(name: string, extras: Partial<Tool> = {}): Tool {
+  return {
+    name,
+    description: `Fake ${name}`,
+    category: "plugin-test",
+    defaultRiskLevel: RiskLevel.Low,
+    getDefinition(): ToolDefinition {
+      return {
+        name,
+        description: `Fake ${name}`,
+        input_schema: { type: "object", properties: {}, required: [] },
+      };
+    },
+    async execute(
+      _input: Record<string, unknown>,
+      _context: ToolContext,
+    ): Promise<ToolExecutionResult> {
+      return { content: "ok", isError: false };
+    },
+    ...extras,
+  };
+}
+
+function buildPlugin(
+  name: string,
+  extras: Partial<Omit<Plugin, "manifest">> = {},
+): Plugin {
+  return {
+    manifest: {
+      name,
+      version: "0.0.1",
+      requires: { pluginRuntime: "v1" },
+    },
+    ...extras,
+  };
+}
+
+describe("plugin tool contributions", () => {
+  beforeEach(async () => {
+    resetPluginRegistryForTests();
+    // Clear the tool registry completely so we can make vacuous-free
+    // assertions about which tools are present. We don't need any of the
+    // eager/host tools for these tests.
+    __clearRegistryForTesting();
+    getSecureKeyAsyncMock.mockReset();
+    getSecureKeyAsyncMock.mockImplementation(async () => undefined);
+    await rm(TEST_INSTANCE_DIR, { recursive: true, force: true });
+  });
+
+  test("bootstrap registers plugin tools and makes them discoverable", async () => {
+    const tool = makeFakeTool("plugin-contrib-tool");
+    const plugin = buildPlugin("alpha-contributor", {
+      async init() {},
+      tools: [tool],
+    });
+    registerPlugin(plugin);
+
+    await bootstrapPlugins(fakeCtx);
+
+    const retrieved = getTool("plugin-contrib-tool");
+    expect(retrieved).toBeDefined();
+    // Ownership metadata must be stamped authoritatively by the bootstrap —
+    // the registry uses it to drive ref-counting and conflict detection when
+    // the plugin shuts down or is hot-reloaded. Plugin tools live in their
+    // own `origin: "plugin"` namespace, disjoint from real skills, so a
+    // plugin name that happens to match a skill id cannot collide.
+    expect(retrieved?.origin).toBe("plugin");
+    expect(retrieved?.ownerPluginId).toBe("alpha-contributor");
+
+    // The tool surfaces in the global `getAllTools()` snapshot, which is
+    // what downstream consumers (tool-manifest, session projection) read.
+    const names = getAllTools().map((t) => t.name);
+    expect(names).toContain("plugin-contrib-tool");
+  });
+
+  test("plugin tools are unregistered when shutdown hooks run", async () => {
+    const plugin = buildPlugin("bravo-contributor", {
+      async init() {},
+      tools: [makeFakeTool("bravo-tool")],
+    });
+    registerPlugin(plugin);
+
+    await bootstrapPlugins(fakeCtx);
+    expect(getTool("bravo-tool")).toBeDefined();
+
+    await runShutdownHooks("test-shutdown");
+
+    expect(getTool("bravo-tool")).toBeUndefined();
+    expect(getPluginRefCount("bravo-contributor")).toBe(0);
+  });
+
+  test("bootstrap is a no-op for plugins that declare no tools", async () => {
+    const plugin = buildPlugin("no-tools", { async init() {} });
+    registerPlugin(plugin);
+
+    await bootstrapPlugins(fakeCtx);
+    // No tool should have been registered.
+    expect(getAllTools()).toHaveLength(0);
+
+    // Shutdown must also be safe — `unregisterPluginTools` is idempotent for
+    // plugins that never contributed any tools.
+    await runShutdownHooks("test-shutdown");
+    expect(getAllTools()).toHaveLength(0);
+  });
+
+  test("tools declared before init() runs are only visible after bootstrap", async () => {
+    // Registration alone must not touch the tool registry — only the
+    // bootstrap pass does. This matters because `bootstrapPlugins` runs once
+    // at daemon startup after the plugin registry is populated; if
+    // registration itself contributed tools, hot-reloading a plugin module
+    // during boot would race with `initializeTools()`.
+    const plugin = buildPlugin("charlie-contributor", {
+      async init() {},
+      tools: [makeFakeTool("charlie-tool")],
+    });
+    registerPlugin(plugin);
+
+    expect(getTool("charlie-tool")).toBeUndefined();
+
+    await bootstrapPlugins(fakeCtx);
+    expect(getTool("charlie-tool")).toBeDefined();
+  });
+
+  test("tools are only registered after init() succeeds", async () => {
+    // A plugin whose init throws must not contribute tools — the bootstrap
+    // aborts with a PluginExecutionError, and nothing from this plugin
+    // should leak into the tool registry.
+    const plugin = buildPlugin("delta-broken", {
+      async init() {
+        throw new Error("boom");
+      },
+      tools: [makeFakeTool("delta-tool")],
+    });
+    registerPlugin(plugin);
+
+    await expect(bootstrapPlugins(fakeCtx)).rejects.toThrow(/delta-broken/);
+    expect(getTool("delta-tool")).toBeUndefined();
+  });
+});
+
+describe("registerPluginTools / unregisterPluginTools helpers", () => {
+  beforeEach(() => {
+    __resetRegistryForTesting();
+  });
+
+  test("registerPluginTools stamps origin and ownerPluginId from the plugin name", () => {
+    // Even if the plugin author hands in a tool with no ownership metadata,
+    // the helper fills it in so the tool can be unregistered later.
+    const accepted = registerPluginTools("my-plugin", [
+      makeFakeTool("pt_stamped"),
+    ]);
+    expect(accepted).toHaveLength(1);
+    expect(accepted[0]?.origin).toBe("plugin");
+    expect(accepted[0]?.ownerPluginId).toBe("my-plugin");
+
+    const retrieved = getTool("pt_stamped");
+    expect(retrieved?.origin).toBe("plugin");
+    expect(retrieved?.ownerPluginId).toBe("my-plugin");
+  });
+
+  test("registerPluginTools overwrites any pre-existing ownership metadata", () => {
+    // A plugin author could (maliciously or mistakenly) hand in a tool
+    // pre-tagged with another skill's or plugin's ID. The helper must
+    // overwrite it so the bootstrap is always the source of truth for
+    // ownership — and it must clear cross-origin fields (ownerSkillId /
+    // ownerMcpServerId) so the stamped tool cannot leak across namespaces.
+    const spoofed = makeFakeTool("pt_spoof", {
+      origin: "skill",
+      ownerSkillId: "some-other-skill",
+    });
+    registerPluginTools("my-plugin", [spoofed]);
+    const retrieved = getTool("pt_spoof");
+    expect(retrieved?.origin).toBe("plugin");
+    expect(retrieved?.ownerPluginId).toBe("my-plugin");
+    expect(retrieved?.ownerSkillId).toBeUndefined();
+  });
+
+  test("unregisterPluginTools removes the plugin's tools", () => {
+    registerPluginTools("rm-plugin", [
+      makeFakeTool("pt_rm_a"),
+      makeFakeTool("pt_rm_b"),
+    ]);
+    expect(getTool("pt_rm_a")).toBeDefined();
+    expect(getTool("pt_rm_b")).toBeDefined();
+
+    unregisterPluginTools("rm-plugin");
+
+    expect(getTool("pt_rm_a")).toBeUndefined();
+    expect(getTool("pt_rm_b")).toBeUndefined();
+  });
+
+  test("unregisterPluginTools is a no-op for plugins that never contributed", () => {
+    expect(() => unregisterPluginTools("never-registered")).not.toThrow();
+  });
+
+  test("ref-counting: repeated registrations require matching unregister calls", () => {
+    registerPluginTools("rc-plugin", [makeFakeTool("pt_rc")]);
+    registerPluginTools("rc-plugin", [makeFakeTool("pt_rc")]);
+    expect(getPluginRefCount("rc-plugin")).toBe(2);
+
+    unregisterPluginTools("rc-plugin");
+    expect(getTool("pt_rc")).toBeDefined();
+
+    unregisterPluginTools("rc-plugin");
+    expect(getTool("pt_rc")).toBeUndefined();
+    expect(getPluginRefCount("rc-plugin")).toBe(0);
+  });
+});