@desplega.ai/agent-swarm 1.150.0 → 1.152.0

package/src/tests/extensions-lifecycle.test.ts

@@ -0,0 +1,209 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { closeDb, createTaskExtended, getAllAgents, getDbClient, getKv, initDb } from "../be/db";
+import {
+  getExtensionById,
+  installExtension,
+  listExtensionRuns,
+  setExtensionState,
+} from "../be/extensions/db";
+import { dispatchPre, listRegistered } from "../extensions/dispatcher";
+import {
+  activateVersion,
+  disableExtension,
+  enableExtension,
+  loadEnabledExtensions,
+  stopExtensionRuntime,
+} from "../extensions/lifecycle";
+import type { ExtensionInstallBody } from "../types";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-lifecycle.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function install(bundle: ExtensionInstallBody) {
+  return (await installExtension(bundle)).extension;
+}
+
+async function waitFor(predicate: () => Promise<boolean>, timeoutMs = 10_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (!(await predicate())) {
+    if (Date.now() >= deadline) throw new Error("Timed out while waiting for extension event");
+    await Bun.sleep(20);
+  }
+}
+
+describe("extension lifecycle", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await stopExtensionRuntime();
+    const client = getDbClient();
+    await client.run("DELETE FROM agent_tasks");
+    await client.run("DELETE FROM extensions");
+    await client.run("DELETE FROM kv_entries");
+  });
+
+  test("enable creates an offline extension agent and disable unregisters", async () => {
+    const extension = await install(await loadBundleFixture("minimal"));
+    const enabled = await enableExtension(extension.id);
+    expect(enabled).toMatchObject({ enabled: true, status: "enabled" });
+    expect(listRegistered().map((loaded) => loaded.record.id)).toEqual([extension.id]);
+
+    const agent = (await getAllAgents()).find((candidate) => candidate.name === "ext:minimal");
+    expect(agent).toMatchObject({
+      id: enabled.agentId,
+      status: "offline",
+      role: "extension",
+      description: "System agent for extension minimal",
+      maxTasks: 0,
+    });
+
+    expect(await disableExtension(extension.id)).toMatchObject({
+      enabled: false,
+      status: "disabled",
+    });
+    expect(listRegistered()).toHaveLength(0);
+  });
+
+  test("activate-version swaps source and reloads an enabled extension", async () => {
+    const bundle = await loadBundleFixture("priority-a");
+    const extension = await install(bundle);
+    await enableExtension(extension.id);
+
+    const versionTwo: ExtensionInstallBody = {
+      manifest: bundle.manifest,
+      files: {
+        "hooks.ts": `
+import { block, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.task.create", () => block("version two"));
+};
+export default extension;
+`,
+      },
+    };
+    await installExtension(versionTwo);
+
+    expect(await activateVersion(extension.id, 2)).toMatchObject({
+      activeVersion: 2,
+      enabled: true,
+    });
+    expect(
+      await dispatchPre("pre.task.create", {
+        options: {},
+        description: "start",
+        origin: "rest",
+      }),
+    ).toMatchObject({ action: "block", reason: "version two" });
+
+    expect(await activateVersion(extension.id, 1)).toMatchObject({
+      activeVersion: 1,
+      enabled: true,
+    });
+    expect(
+      await dispatchPre("pre.task.create", {
+        options: {},
+        description: "start",
+        origin: "rest",
+      }),
+    ).toEqual({ action: "modify", data: { description: "starta" } });
+  });
+
+  test("boot loads enabled rows and continues after one load error", async () => {
+    const valid = await install(await loadBundleFixture("post-logger"));
+    const invalidBundle = await loadBundleFixture("minimal");
+    invalidBundle.manifest = { ...invalidBundle.manifest, name: "boot-invalid" };
+    invalidBundle.files["hooks.ts"] = "export const invalid = true;";
+    const invalid = await install(invalidBundle);
+    await setExtensionState(valid.id, { enabled: true, status: "enabled" });
+    await setExtensionState(invalid.id, { enabled: true, status: "enabled" });
+
+    await loadEnabledExtensions();
+
+    expect(listRegistered().map((loaded) => loaded.record.id)).toEqual([valid.id]);
+    expect(await getExtensionById(invalid.id)).toMatchObject({ enabled: true, status: "error" });
+    expect(await listExtensionRuns(invalid.id)).toMatchObject([{ action: "load-error" }]);
+
+    await createTaskExtended("boot-loaded extension test", { source: "api" });
+    await waitFor(async () =>
+      (await listExtensionRuns(valid.id)).some(
+        (run) => run.event === "post.task.created" && run.action === "continue",
+      ),
+    );
+  });
+
+  test("the post bridge dispatches post.task.created after commit", async () => {
+    const extension = await install(await loadBundleFixture("post-logger"));
+    const enabled = await enableExtension(extension.id);
+    await createTaskExtended("extension post bridge test", { source: "api" });
+
+    await waitFor(async () =>
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "post.task.created" && run.action === "continue",
+      ),
+    );
+    expect(await getExtensionById(extension.id)).toMatchObject({
+      enabled: true,
+      consecutiveFailures: 0,
+    });
+    expect(await getKv(`task:agent:${enabled.agentId}`, "ext:post-logger:created")).toMatchObject({
+      value: 1,
+    });
+  });
+
+  test("five post handler failures auto-disable and re-enable resets the counter", async () => {
+    const extension = await install(await loadBundleFixture("throws"));
+    await enableExtension(extension.id);
+
+    for (let index = 0; index < 5; index += 1) {
+      await createTaskExtended(`throwing extension test ${index}`, { source: "api" });
+      await waitFor(
+        async () => (await getExtensionById(extension.id))!.consecutiveFailures > index,
+      );
+    }
+
+    expect(await getExtensionById(extension.id)).toMatchObject({
+      enabled: false,
+      status: "auto-disabled",
+      consecutiveFailures: 5,
+    });
+    expect(listRegistered()).toHaveLength(0);
+    expect(await enableExtension(extension.id)).toMatchObject({
+      enabled: true,
+      status: "enabled",
+      consecutiveFailures: 0,
+    });
+  });
+
+  test("the post bridge skips the extension that created a task", async () => {
+    const first = await install(await loadBundleFixture("post-logger"));
+    const secondBundle = await loadBundleFixture("post-logger");
+    secondBundle.manifest = { ...secondBundle.manifest, name: "other-logger" };
+    const second = await install(secondBundle);
+    const creator = await enableExtension(first.id);
+    await enableExtension(second.id);
+    await createTaskExtended("extension-created task", {
+      source: "api",
+      creatorAgentId: creator.agentId!,
+    });
+    await waitFor(async () => (await listExtensionRuns(second.id)).length > 0);
+    expect(await listExtensionRuns(first.id)).toEqual([]);
+    expect(await listExtensionRuns(second.id)).toMatchObject([{ action: "continue" }]);
+  });
+});

package/src/tests/extensions-loader.test.ts

@@ -0,0 +1,95 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { closeDb, getDbClient, initDb } from "../be/db";
+import { getExtensionById, installExtension, listExtensionRuns } from "../be/extensions/db";
+import {
+  cleanExtensionTmpRoot,
+  EXTENSIONS_TMP_ROOT,
+  type LoadableExtension,
+  loadExtension,
+} from "../extensions/loader";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-loader.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function installLoadable(name: string, priority?: number): Promise<LoadableExtension> {
+  const bundle = await loadBundleFixture(name);
+  const installed = await installExtension({ ...bundle, priority });
+  return { record: installed.extension, ...bundle };
+}
+
+describe("extension loader", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    await cleanExtensionTmpRoot();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await cleanExtensionTmpRoot();
+    await getDbClient().run("DELETE FROM extensions");
+  });
+
+  test("imports hooks and exposes registered handlers", async () => {
+    const loaded = await loadExtension(await installLoadable("minimal", 17));
+    expect(EXTENSIONS_TMP_ROOT.endsWith(`/swarm-extensions/${process.pid}`)).toBe(true);
+    expect(loaded.handlers).toHaveLength(1);
+    expect(loaded.handlers[0]).toMatchObject({ event: "pre.task.create", priority: 17 });
+    expect(await Bun.file(loaded.sourcePath).exists()).toBe(true);
+    await loaded.dispose();
+    expect(await Bun.file(loaded.sourcePath).exists()).toBe(false);
+  });
+
+  test("defensively rejects file traversal before writing bundle files", async () => {
+    const input = await installLoadable("minimal");
+    input.files["../escape.ts"] = "export default () => {};";
+    await expect(loadExtension(input)).rejects.toThrow("Unsafe bundle file path");
+    expect((await getExtensionById(input.record.id))?.status).toBe("error");
+  });
+
+  test("records a load error when hooks have no default export", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    bundle.manifest = { ...bundle.manifest, name: "missing-default" };
+    bundle.files["hooks.ts"] = "export const value = 1;";
+    const installed = await installExtension(bundle);
+
+    await expect(loadExtension({ record: installed.extension, ...bundle })).rejects.toThrow(
+      "default function",
+    );
+    expect((await getExtensionById(installed.extension.id))?.status).toBe("error");
+    expect(await listExtensionRuns(installed.extension.id)).toMatchObject([
+      { action: "load-error", event: "load" },
+    ]);
+  });
+
+  test("removes the previous content-hash directory after a successful import", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const first = await installExtension(bundle);
+    const firstLoaded = await loadExtension({ record: first.extension, ...bundle });
+    expect(await Bun.file(firstLoaded.sourcePath).exists()).toBe(true);
+
+    const files = { ...bundle.files, "hooks.ts": `${bundle.files["hooks.ts"]}\n// v2\n` };
+    const second = await installExtension({ ...bundle, files, activate: true });
+    const secondLoaded = await loadExtension({
+      record: second.extension,
+      manifest: bundle.manifest,
+      files,
+    });
+
+    expect(await Bun.file(firstLoaded.sourcePath).exists()).toBe(false);
+    expect(await Bun.file(secondLoaded.sourcePath).exists()).toBe(true);
+    await secondLoaded.dispose();
+  });
+});

package/src/tests/extensions-mcp-tools.test.ts

@@ -0,0 +1,353 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
+import { getExtensionById, setExtensionState } from "../be/extensions/db";
+import { typecheckScript } from "../be/scripts/typecheck";
+import { stopExtensionRuntime } from "../extensions/lifecycle";
+import { handleCore } from "../http/core";
+import { handleExtensions } from "../http/extensions";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { registerExtensionActivateVersionTool } from "../tools/extension-activate-version";
+import { registerExtensionDeleteTool } from "../tools/extension-delete";
+import { registerExtensionDisableTool } from "../tools/extension-disable";
+import { registerExtensionEnableTool } from "../tools/extension-enable";
+import { registerExtensionInstallTool } from "../tools/extension-install";
+import { registerExtensionListTool } from "../tools/extension-list";
+import { refreshSecretScrubberCache } from "../utils/secret-scrubber";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-mcp-tools.sqlite";
+const API_KEY = "test-extensions-mcp-tools-key-1234567890";
+const API_URL = "http://extensions-mcp-tools.test";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+};
+
+type ToolResult = {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+  structuredContent: Record<string, unknown>;
+};
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function buildToolServer() {
+  const server = new McpServer({ name: "extensions-mcp-tools", version: "1" });
+  registerExtensionDeleteTool(server);
+  registerExtensionEnableTool(server);
+  registerExtensionDisableTool(server);
+  registerExtensionActivateVersionTool(server);
+  registerExtensionInstallTool(server);
+  registerExtensionListTool(server);
+  const tools = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  return {
+    install: tools["extension-install"]!,
+    list: tools["extension-list"]!,
+    enable: tools["extension-enable"]!,
+    disable: tools["extension-disable"]!,
+    activate: tools["extension-activate-version"]!,
+    delete: tools["extension-delete"]!,
+  };
+}
+
+function meta(agentId: string) {
+  return { sessionId: "extensions-mcp-tools", requestInfo: { headers: { "x-agent-id": agentId } } };
+}
+
+function headersRecord(headers: HeadersInit | undefined): Record<string, string> {
+  if (!headers) return {};
+  if (headers instanceof Headers) return Object.fromEntries(headers.entries());
+  if (Array.isArray(headers)) return Object.fromEntries(headers);
+  return headers as Record<string, string>;
+}
+
+async function dispatchExtensionsApi(url: string, init: RequestInit = {}): Promise<Response> {
+  const parsedUrl = new URL(url);
+  const headers = Object.fromEntries(
+    Object.entries(headersRecord(init.headers)).map(([key, value]) => [
+      key.toLowerCase(),
+      String(value),
+    ]),
+  );
+  const body = init.body === undefined ? undefined : String(init.body);
+  const req = Readable.from(body ? [Buffer.from(body)] : []) as IncomingMessage;
+  req.method = init.method ?? "GET";
+  req.url = `${parsedUrl.pathname}${parsedUrl.search}`;
+  req.headers = headers;
+
+  let status = 200;
+  let text = "";
+  const res = {
+    headersSent: false,
+    writableEnded: false,
+    setHeader() {},
+    writeHead(code: number) {
+      status = code;
+      this.headersSent = true;
+      return this;
+    },
+    end(chunk?: unknown) {
+      if (chunk !== undefined) text += String(chunk);
+      this.writableEnded = true;
+      return this;
+    },
+  } as unknown as ServerResponse;
+
+  const agentId = headers["x-agent-id"];
+  if (!(await handleCore(req, res, agentId, API_KEY))) {
+    const pathSegments = getPathSegments(req.url || "");
+    const queryParams = parseQueryParams(req.url || "");
+    if (!(await handleExtensions(req, res, pathSegments, queryParams, agentId))) {
+      res.writeHead(404);
+      res.end("Not Found");
+    }
+  }
+
+  return new Response(text, { status, headers: { "Content-Type": "application/json" } });
+}
+
+let leadId: string;
+let workerId: string;
+let savedEnv: NodeJS.ProcessEnv;
+let savedFetch: typeof globalThis.fetch;
+
+beforeAll(async () => {
+  savedEnv = { ...process.env };
+  savedFetch = globalThis.fetch;
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+  process.env.AGENT_SWARM_API_KEY = API_KEY;
+  delete process.env.API_KEY;
+  process.env.MCP_BASE_URL = API_URL;
+  refreshSecretScrubberCache();
+  leadId = (await createAgent({ name: "extensions-mcp-lead", isLead: true, status: "idle" })).id;
+  workerId = (await createAgent({ name: "extensions-mcp-worker", isLead: false, status: "idle" }))
+    .id;
+  globalThis.fetch = (async (input, init) => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.startsWith(`${API_URL}/api/extensions`)) return dispatchExtensionsApi(url, init);
+    return savedFetch(input, init);
+  }) as typeof globalThis.fetch;
+});
+
+afterAll(async () => {
+  await stopExtensionRuntime();
+  globalThis.fetch = savedFetch;
+  closeDb();
+  await removeDbFiles();
+  for (const key of Object.keys(process.env)) {
+    if (!(key in savedEnv)) delete process.env[key];
+  }
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  refreshSecretScrubberCache();
+});
+
+beforeEach(async () => {
+  await stopExtensionRuntime();
+  await getDbClient().run("DELETE FROM extensions");
+});
+
+describe("extension MCP HTTP proxy tools", () => {
+  test("script SDK typechecks the full extension lifecycle", async () => {
+    const result = await typecheckScript(`
+      import type { ScriptContext } from "swarm-sdk";
+      export default async (_args: unknown, ctx: ScriptContext) => {
+        await ctx.swarm.extension_install({
+          manifest: {},
+          files: { "hooks.ts": "export default () => {}" },
+        });
+        const id = "00000000-0000-4000-8000-000000000001";
+        await ctx.swarm.extension_enable({ id });
+        await ctx.swarm.extension_activate_version({ id, version: 1 });
+        await ctx.swarm.extension_disable({ id });
+        await ctx.swarm.extension_delete({ id });
+        return await ctx.swarm.extension_list({ enabledOnly: true });
+      };
+    `);
+    expect(result.ok).toBe(true);
+  });
+
+  test("lead installation stays disabled and returns the shared tool envelope", async () => {
+    const tools = buildToolServer();
+    const result = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(leadId),
+    )) as ToolResult;
+
+    expect(result.isError).toBe(false);
+    expect(result.content[0]?.text).toContain("POST /api/extensions/{id}/enable");
+    expect(result.structuredContent).toMatchObject({
+      success: true,
+      enabled: false,
+      status: "disabled",
+    });
+    expect(result.structuredContent.message).toBeTruthy();
+  });
+
+  test("worker installation returns the REST permission error in the shared tool envelope", async () => {
+    const tools = buildToolServer();
+    const result = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(workerId),
+    )) as ToolResult;
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toMatchObject({ success: false });
+    expect(String(result.structuredContent.message)).toContain("Forbidden");
+  });
+
+  test("lead reinstall stores an inactive version of an enabled extension", async () => {
+    const tools = buildToolServer();
+    const first = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(leadId),
+    )) as ToolResult;
+    const id = String(first.structuredContent.id);
+    await setExtensionState(id, { enabled: true, status: "enabled" });
+
+    const changed = await loadBundleFixture("minimal");
+    changed.files["hooks.ts"] += "\n// updated by MCP\n";
+    const result = (await tools.install.handler(changed, meta(leadId))) as ToolResult;
+
+    expect(result.isError).toBe(false);
+    expect(result.structuredContent).toMatchObject({
+      version: 2,
+      activeVersion: 1,
+      enabled: true,
+    });
+  });
+
+  test("typecheck diagnostics reach the error details", async () => {
+    const tools = buildToolServer();
+    const broken = await loadBundleFixture("minimal");
+    broken.files["hooks.ts"] = "export default 42;";
+    const result = (await tools.install.handler(broken, meta(leadId))) as ToolResult;
+
+    expect(result.isError).toBe(true);
+    expect(result.structuredContent).toMatchObject({
+      success: false,
+      message: "Extension rejected by typecheck.",
+    });
+    expect(String(result.structuredContent.details)).toContain("TS");
+  });
+
+  test("extension-list renders a table and supports enabledOnly", async () => {
+    const tools = buildToolServer();
+    await tools.install.handler(await loadBundleFixture("minimal"), meta(leadId));
+
+    const all = (await tools.list.handler({}, meta(leadId))) as ToolResult;
+    expect(all.isError).toBe(false);
+    expect(all.content[0]?.text).toContain(
+      "| Name | Version | Active | Enabled | Status | Priority | Failures |",
+    );
+    expect(all.structuredContent).toMatchObject({ success: true });
+    expect((all.structuredContent.extensions as unknown[]).length).toBe(1);
+
+    const enabledOnly = (await tools.list.handler(
+      { enabledOnly: true },
+      meta(leadId),
+    )) as ToolResult;
+    expect(enabledOnly.structuredContent).toMatchObject({ success: true, extensions: [] });
+  });
+});
+
+describe("extension lifecycle MCP tools", () => {
+  test("lead enables, activates, disables, and deletes through the shared HTTP routes", async () => {
+    const tools = buildToolServer();
+    const installed = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(leadId),
+    )) as ToolResult;
+    const id = String(installed.structuredContent.id);
+    const enabled = (await tools.enable.handler({ id }, meta(leadId))) as ToolResult;
+    expect(enabled.structuredContent).toMatchObject({
+      success: true,
+      enabled: true,
+      activeVersion: 1,
+    });
+
+    const rejected = await dispatchExtensionsApi(`${API_URL}/api/extensions/${id}`, {
+      method: "DELETE",
+      headers: { "x-agent-id": leadId, authorization: `Bearer ${API_KEY}` },
+    });
+    expect(rejected.status).toBe(409);
+    const blocked = (await tools.delete.handler({ id }, meta(leadId))) as ToolResult;
+    expect(blocked.isError).toBe(true);
+    expect(blocked.structuredContent).toMatchObject({ success: false });
+    expect(blocked.content[0]?.text).toContain("Disable");
+    expect(await getExtensionById(id)).not.toBeNull();
+
+    const changed = await loadBundleFixture("minimal");
+    changed.files["hooks.ts"] += "\n// next lifecycle version\n";
+    await tools.install.handler(changed, meta(leadId));
+    const activated = (await tools.activate.handler(
+      { id, version: 2 },
+      meta(leadId),
+    )) as ToolResult;
+    expect(activated.structuredContent).toMatchObject({
+      success: true,
+      activeVersion: 2,
+      enabled: true,
+    });
+    const disabled = (await tools.disable.handler({ id }, meta(leadId))) as ToolResult;
+    expect(disabled.structuredContent).toMatchObject({ success: true, enabled: false });
+    const deleted = (await tools.delete.handler({ id }, meta(leadId))) as ToolResult;
+    expect(deleted.isError).toBe(false);
+    expect(deleted.structuredContent).toMatchObject({ success: true, id, deleted: true });
+    expect(await getExtensionById(id)).toBeNull();
+  });
+
+  test("workers cannot mutate the extension lifecycle", async () => {
+    const tools = buildToolServer();
+    const installed = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(leadId),
+    )) as ToolResult;
+    const id = String(installed.structuredContent.id);
+    for (const tool of [tools.enable, tools.disable, tools.activate, tools.delete]) {
+      const result = (await tool.handler({ id, version: 1 }, meta(workerId))) as ToolResult;
+      expect(result.isError).toBe(true);
+      expect(String(result.structuredContent.message)).toContain("Forbidden");
+    }
+    expect(await getExtensionById(id)).toMatchObject({ enabled: false, activeVersion: 1 });
+  });
+
+  test("missing extensions and versions return error envelopes", async () => {
+    const tools = buildToolServer();
+    const id = crypto.randomUUID();
+    for (const tool of [tools.enable, tools.disable, tools.activate, tools.delete]) {
+      const result = (await tool.handler({ id, version: 1 }, meta(leadId))) as ToolResult;
+      expect(result.isError).toBe(true);
+      expect(result.structuredContent.success).toBe(false);
+    }
+    const installed = (await tools.install.handler(
+      await loadBundleFixture("minimal"),
+      meta(leadId),
+    )) as ToolResult;
+    const result = (await tools.activate.handler(
+      { id: installed.structuredContent.id, version: 99 },
+      meta(leadId),
+    )) as ToolResult;
+    expect(result.isError).toBe(true);
+    expect(await getExtensionById(String(installed.structuredContent.id))).toMatchObject({
+      activeVersion: 1,
+      enabled: false,
+    });
+  });
+});