@desplega.ai/agent-swarm 1.149.1 → 1.151.0

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

@@ -0,0 +1,216 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { closeDb, getDbClient, initDb } from "../be/db";
+import {
+  deleteExtension,
+  getExtensionById,
+  getExtensionFiles,
+  getExtensionVersion,
+  insertExtensionRun,
+  installExtension,
+  listExtensionRuns,
+  listExtensionVersions,
+  pruneExtensionRuns,
+  setExtensionState,
+  updateExtensionMeta,
+} from "../be/extensions/db";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-db.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+describe("extension DB helpers", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await getDbClient().run("DELETE FROM extensions");
+  });
+
+  test("install creates version 1 and one active file", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const result = await installExtension({
+      ...bundle,
+      agentId: "lead-1",
+      createdBy: "user-1",
+    });
+
+    expect(result.isNew).toBe(true);
+    expect(result.contentDeduped).toBe(false);
+    expect(result.extension.version).toBe(1);
+    expect(result.extension.activeVersion).toBe(1);
+    expect(result.extension.enabled).toBe(false);
+    expect(await getExtensionFiles(result.extension.id)).toEqual(bundle.files);
+    expect((await listExtensionVersions(result.extension.id)).map((row) => row.version)).toEqual([
+      1,
+    ]);
+    expect(
+      (
+        await getDbClient().get<{ count: number }>(
+          "SELECT COUNT(*) AS count FROM extension_files WHERE extensionId = ?",
+          [result.extension.id],
+        )
+      )?.count,
+    ).toBe(1);
+  });
+
+  test("matching bundles dedupe and changed hooks create a complete snapshot", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const first = await installExtension(bundle);
+    const same = await installExtension(bundle);
+    expect(same.contentDeduped).toBe(true);
+    expect(same.extension.version).toBe(1);
+
+    const changedFiles = {
+      ...bundle.files,
+      "hooks.ts": `${bundle.files["hooks.ts"]}\n// version 2\n`,
+    };
+    const changed = await installExtension({
+      manifest: bundle.manifest,
+      files: changedFiles,
+      changeReason: "Change hooks",
+    });
+    expect(changed.contentDeduped).toBe(false);
+    expect(changed.extension.id).toBe(first.extension.id);
+    expect(changed.extension.version).toBe(2);
+    expect(await getExtensionFiles(changed.extension.id)).toEqual(changedFiles);
+
+    const versions = await listExtensionVersions(changed.extension.id);
+    expect(versions.map((row) => row.version)).toEqual([2, 1]);
+    expect(JSON.parse(versions[0]!.filesJson)).toEqual(changedFiles);
+    expect(JSON.parse(versions[1]!.filesJson)).toEqual(bundle.files);
+    expect((await getExtensionVersion(changed.extension.id, 2))?.changeReason).toBe("Change hooks");
+  });
+
+  test("manifest-only changes create a version with a complete snapshot", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const first = await installExtension(bundle);
+    const manifest = { ...bundle.manifest, description: "Changed manifest description" };
+    const changed = await installExtension({ manifest, files: bundle.files });
+
+    expect(changed.contentDeduped).toBe(false);
+    expect(changed.extension.id).toBe(first.extension.id);
+    expect(changed.extension.version).toBe(2);
+    const versions = await listExtensionVersions(first.extension.id);
+    expect(versions.map((row) => row.version)).toEqual([2, 1]);
+    expect(JSON.parse(versions[0]!.manifestJson)).toEqual(manifest);
+    expect(JSON.parse(versions[1]!.manifestJson)).toEqual(bundle.manifest);
+    expect(JSON.parse(versions[0]!.filesJson)).toEqual(bundle.files);
+    expect(JSON.parse(versions[1]!.filesJson)).toEqual(bundle.files);
+  });
+
+  test("identical content can activate the current version without creating another version", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const first = await installExtension(bundle);
+    const files = { ...bundle.files, "hooks.ts": `${bundle.files["hooks.ts"]}\n// version 2\n` };
+    const changed = await installExtension({ manifest: bundle.manifest, files });
+    expect(changed.extension).toMatchObject({ version: 2, activeVersion: 1 });
+
+    const activated = await installExtension({ manifest: bundle.manifest, files, activate: true });
+    expect(activated.contentDeduped).toBe(true);
+    expect(activated.extension).toMatchObject({ version: 2, activeVersion: 2 });
+    expect((await getExtensionById(first.extension.id))?.activeVersion).toBe(2);
+    expect(await listExtensionVersions(first.extension.id)).toHaveLength(2);
+  });
+
+  test("concurrent changed installs allocate distinct versions atomically", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const first = await installExtension(bundle);
+    const changedA = { ...bundle.files, "hooks.ts": `${bundle.files["hooks.ts"]}\n// A\n` };
+    const changedB = { ...bundle.files, "hooks.ts": `${bundle.files["hooks.ts"]}\n// B\n` };
+
+    const results = await Promise.all([
+      installExtension({ manifest: bundle.manifest, files: changedA }),
+      installExtension({ manifest: bundle.manifest, files: changedB }),
+    ]);
+
+    expect(results.map((result) => result.extension.version).sort()).toEqual([2, 3]);
+    const versions = await listExtensionVersions(first.extension.id);
+    expect(versions.map((row) => row.version)).toEqual([3, 2, 1]);
+    expect(await getExtensionFiles(first.extension.id)).toEqual(JSON.parse(versions[0]!.filesJson));
+  });
+
+  test("metadata and state updates preserve the stored bundle", async () => {
+    const installed = await installExtension(await loadBundleFixture("minimal"));
+    const updated = await updateExtensionMeta(installed.extension.id, {
+      priority: 10,
+      config: { channelId: "C1" },
+      description: "Updated description",
+    });
+    expect(updated?.priority).toBe(10);
+    expect(updated?.configJson).toBe('{"channelId":"C1"}');
+    expect(updated?.description).toBe("Updated description");
+
+    const enabled = await setExtensionState(installed.extension.id, {
+      enabled: true,
+      status: "enabled",
+      consecutiveFailures: 2,
+      lastError: "test error",
+    });
+    expect(enabled?.enabled).toBe(true);
+    expect(enabled?.status).toBe("enabled");
+    expect(enabled?.consecutiveFailures).toBe(2);
+    expect(enabled?.lastError).toBe("test error");
+  });
+
+  test("run logs retain only the newest 500 rows", async () => {
+    const installed = await installExtension(await loadBundleFixture("minimal"));
+    for (let index = 0; index < 505; index++) {
+      await insertExtensionRun({
+        extensionId: installed.extension.id,
+        version: 1,
+        event: "pre.task.create",
+        action: "continue",
+        message: String(index),
+      });
+    }
+    expect(
+      (
+        await getDbClient().get<{ count: number }>(
+          "SELECT count(*) AS count FROM extension_runs WHERE extensionId = ?",
+          [installed.extension.id],
+        )
+      )?.count,
+    ).toBe(505);
+    await pruneExtensionRuns(installed.extension.id);
+    expect(
+      (
+        await getDbClient().get<{ count: number }>(
+          "SELECT count(*) AS count FROM extension_runs WHERE extensionId = ?",
+          [installed.extension.id],
+        )
+      )?.count,
+    ).toBe(500);
+    const rows = await listExtensionRuns(installed.extension.id, 500);
+    expect(rows).toHaveLength(500);
+    expect(rows[0]?.message).toBe("504");
+    expect(rows.at(-1)?.message).toBe("5");
+  });
+
+  test("delete cascades extension children", async () => {
+    const installed = await installExtension(await loadBundleFixture("minimal"));
+    await insertExtensionRun({
+      extensionId: installed.extension.id,
+      version: 1,
+      event: "post.task.created",
+      action: "continue",
+    });
+    expect(await deleteExtension(installed.extension.id)).toBe(true);
+    expect(await getExtensionById(installed.extension.id)).toBeNull();
+    expect(await listExtensionVersions(installed.extension.id)).toEqual([]);
+    expect(await listExtensionRuns(installed.extension.id)).toEqual([]);
+  });
+});

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

@@ -0,0 +1,275 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { closeDb, getDbClient, getKv, initDb } from "../be/db";
+import {
+  getExtensionById,
+  installExtension,
+  listExtensionRuns,
+  setExtensionState,
+} from "../be/extensions/db";
+import { buildCtx } from "../extensions/ctx";
+import {
+  dispatchPost,
+  dispatchPre,
+  ExtensionAbortedError,
+  extensionIdForAgent,
+  isExtensionAgentId,
+  listRegistered,
+  registerLoaded,
+  unregister,
+} from "../extensions/dispatcher";
+import { ensureExtensionAgent } from "../extensions/identity";
+import {
+  ExtensionLifecycleError,
+  setExtensionLoopbackBaseUrl,
+  stopExtensionRuntime,
+} from "../extensions/lifecycle";
+import { cleanExtensionTmpRoot, loadExtension } from "../extensions/loader";
+import type { ExtensionInstallBody } from "../types";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-dispatcher.sqlite";
+let savedTimeout: string | undefined;
+let savedFailureLimit: string | undefined;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function loadAndRegister(bundle: ExtensionInstallBody, priority = 100) {
+  const installed = await installExtension({ ...bundle, priority });
+  const record = await setExtensionState(installed.extension.id, {
+    agentId: await ensureExtensionAgent(installed.extension.name),
+  });
+  const loaded = await loadExtension({ record: record!, ...bundle });
+  registerLoaded(loaded);
+  return loaded;
+}
+
+async function fixture(name: string, priority = 100) {
+  return await loadAndRegister(await loadBundleFixture(name), priority);
+}
+
+function taskPayload(description = "start") {
+  return { options: {}, description, origin: "rest" as const };
+}
+
+async function blockBundle(name: string, reason: string): Promise<ExtensionInstallBody> {
+  const bundle = await loadBundleFixture("minimal");
+  bundle.manifest = { ...bundle.manifest, name, description: reason };
+  bundle.files["hooks.ts"] = `
+import { block, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.task.create", () => block(${JSON.stringify(reason)}));
+};
+export default extension;
+`;
+  return bundle;
+}
+
+describe("extension dispatcher", () => {
+  beforeAll(async () => {
+    savedTimeout = process.env.EXTENSION_HANDLER_TIMEOUT_MS;
+    savedFailureLimit = process.env.EXTENSION_MAX_CONSECUTIVE_FAILURES;
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    for (const loaded of listRegistered()) {
+      unregister(loaded.record.id);
+      await loaded.dispose();
+    }
+    await cleanExtensionTmpRoot();
+    closeDb();
+    await removeDbFiles();
+    if (savedTimeout === undefined) delete process.env.EXTENSION_HANDLER_TIMEOUT_MS;
+    else process.env.EXTENSION_HANDLER_TIMEOUT_MS = savedTimeout;
+    if (savedFailureLimit === undefined) delete process.env.EXTENSION_MAX_CONSECUTIVE_FAILURES;
+    else process.env.EXTENSION_MAX_CONSECUTIVE_FAILURES = savedFailureLimit;
+  });
+
+  beforeEach(async () => {
+    for (const loaded of listRegistered()) {
+      unregister(loaded.record.id);
+      await loaded.dispose();
+    }
+    await cleanExtensionTmpRoot();
+    await getDbClient().run("DELETE FROM extensions");
+    process.env.EXTENSION_HANDLER_TIMEOUT_MS = "5000";
+    process.env.EXTENSION_MAX_CONSECUTIVE_FAILURES = "5";
+  });
+
+  test("runs by priority and feeds each modify into the next handler", async () => {
+    await fixture("priority-a", 20);
+    await fixture("priority-b", 10);
+    expect(await dispatchPre("pre.task.create", taskPayload())).toEqual({
+      action: "modify",
+      data: { description: "startba" },
+    });
+  });
+
+  test("returns the first block", async () => {
+    await loadAndRegister(await blockBundle("block-first", "first"), 10);
+    await loadAndRegister(await blockBundle("block-second", "second"), 20);
+    const result = await dispatchPre("pre.task.create", taskPayload());
+    expect(result).toMatchObject({ action: "block", reason: "first" });
+  });
+
+  test("fails open and records thrown handlers", async () => {
+    const loaded = await fixture("throws");
+    expect(await dispatchPre("pre.task.create", taskPayload())).toEqual({ action: "continue" });
+    expect((await getExtensionById(loaded.record.id))?.consecutiveFailures).toBe(1);
+    expect(await listExtensionRuns(loaded.record.id)).toMatchObject([
+      { action: "error", event: "pre.task.create", message: "fixture failure" },
+    ]);
+  });
+
+  test("auto-disables after five consecutive failures", async () => {
+    const loaded = await fixture("throws");
+    for (let attempt = 0; attempt < 5; attempt++) {
+      expect(await dispatchPre("pre.task.create", taskPayload())).toEqual({ action: "continue" });
+    }
+    expect(await getExtensionById(loaded.record.id)).toMatchObject({
+      enabled: false,
+      status: "auto-disabled",
+      consecutiveFailures: 5,
+    });
+    expect(listRegistered()).toHaveLength(0);
+  });
+
+  test("times out and fails open", async () => {
+    process.env.EXTENSION_HANDLER_TIMEOUT_MS = "5";
+    const loaded = await fixture("slow");
+    const handler = loaded.handlers[0]!;
+    const original = handler.handler;
+    const finished = Promise.withResolvers<void>();
+    let lateError: unknown;
+    handler.handler = async (event, ctx) => {
+      try {
+        return await original(event, ctx);
+      } catch (error) {
+        lateError = error;
+        throw error;
+      } finally {
+        finished.resolve();
+      }
+    };
+    expect(await dispatchPre("pre.task.create", taskPayload())).toEqual({ action: "continue" });
+    expect(
+      (await listExtensionRuns(loaded.record.id)).some((run) => run.action === "timeout"),
+    ).toBe(true);
+    await finished.promise;
+    expect(lateError).toBeInstanceOf(ExtensionAbortedError);
+    expect(await getKv(`task:agent:${loaded.record.agentId}`, "ext:slow:after-timeout")).toBeNull();
+  });
+
+  test("uses the script SDK through the bound loopback URL and rejects before listen", async () => {
+    await stopExtensionRuntime();
+    const loaded = await fixture("minimal");
+    const ctx = buildCtx(loaded, "pre.task.create", new AbortController().signal);
+    await expect(ctx.swarm.task_get({ taskId: "x" })).rejects.toBeInstanceOf(
+      ExtensionLifecycleError,
+    );
+    await expect(ctx.swarm.task_get({ taskId: "x" })).rejects.toThrow(
+      "extension loopback not ready",
+    );
+    const savedFetch = globalThis.fetch;
+    const savedKey = process.env.AGENT_SWARM_API_KEY;
+    const requests: Request[] = [];
+    try {
+      process.env.AGENT_SWARM_API_KEY = "123123";
+      setExtensionLoopbackBaseUrl("http://127.0.0.1:1");
+      globalThis.fetch = (async (input, init) => {
+        requests.push(new Request(input, init));
+        return Response.json({ task: { id: "x" } });
+      }) as typeof fetch;
+      let result: unknown;
+      loaded.handlers[0]!.handler = async (_event, handlerCtx) => {
+        result = await handlerCtx.swarm.task_get({ taskId: "x" });
+      };
+      await dispatchPre("pre.task.create", taskPayload());
+      expect(requests[0]?.url).toBe("http://127.0.0.1:1/api/tasks/x");
+      expect(requests[0]?.headers.get("X-Agent-ID")).toBe(loaded.record.agentId);
+      expect(requests[0]?.headers.get("Authorization")).toBe("Bearer 123123");
+      expect(result).toEqual({ success: true, status: 200, data: { task: { id: "x" } } });
+      expect(isExtensionAgentId(loaded.record.agentId)).toBe(true);
+      expect(extensionIdForAgent(loaded.record.agentId)).toBe(loaded.record.id);
+    } finally {
+      globalThis.fetch = savedFetch;
+      if (savedKey === undefined) delete process.env.AGENT_SWARM_API_KEY;
+      else process.env.AGENT_SWARM_API_KEY = savedKey;
+      await stopExtensionRuntime();
+    }
+    expect(isExtensionAgentId(loaded.record.agentId)).toBe(false);
+    expect(extensionIdForAgent(loaded.record.agentId)).toBeUndefined();
+  });
+
+  test("post dispatch skips its creator and runs the other extension", async () => {
+    const first = await fixture("priority-a");
+    const second = await fixture("priority-b");
+    const calls: string[] = [];
+    for (const loaded of [first, second]) {
+      loaded.handlers = [
+        {
+          event: "post.slack.message",
+          priority: 100,
+          handler: () => {
+            calls.push(loaded.record.name);
+          },
+        },
+      ];
+    }
+    await dispatchPost(
+      "post.slack.message",
+      { channelId: "C1", userId: "U1", text: "test" },
+      { skipExtensionId: first.record.id },
+    );
+    expect(calls).toEqual(["priority-b"]);
+  });
+
+  test("auto-disable skips remaining handlers in the same chain", async () => {
+    process.env.EXTENSION_MAX_CONSECUTIVE_FAILURES = "1";
+    const loaded = await fixture("throws");
+    let called = false;
+    loaded.handlers.push({
+      event: "pre.task.create",
+      priority: 200,
+      handler: () => {
+        called = true;
+      },
+    });
+    await dispatchPre("pre.task.create", taskPayload());
+    expect(called).toBe(false);
+  });
+
+  test("refuses to dispatch inside a transaction", async () => {
+    const loaded = await fixture("priority-a");
+    const error = spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const result = await getDbClient().transaction(async () =>
+        dispatchPre("pre.task.create", taskPayload()),
+      );
+      expect(result).toEqual({ action: "continue" });
+      expect(error).toHaveBeenCalledWith(
+        "[extensions] pre dispatch inside transaction:",
+        "pre.task.create",
+      );
+      expect(await listExtensionRuns(loaded.record.id)).toEqual([]);
+    } finally {
+      error.mockRestore();
+    }
+  });
+
+  test("skips the requested extension id", async () => {
+    const loaded = await fixture("priority-a");
+    expect(
+      await dispatchPre("pre.task.create", taskPayload(), {
+        skipExtensionId: loaded.record.id,
+      }),
+    ).toEqual({ action: "continue" });
+  });
+});

package/src/tests/extensions-example-heartbeat-remediate.test.ts

@@ -0,0 +1,69 @@
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getDbClient,
+  getTaskById,
+  initDb,
+  startTask,
+} from "../be/db";
+import { installExtension } from "../be/extensions/db";
+import { validateBundle } from "../be/extensions/validate";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { codeLevelTriage } from "../heartbeat/heartbeat";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-heartbeat-remediate.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+beforeAll(async () => {
+  await removeDbFiles();
+  closeDb();
+  initDb(TEST_DB_PATH);
+});
+
+afterAll(async () => {
+  await stopExtensionRuntime();
+  closeDb();
+  await removeDbFiles();
+});
+
+test("never-fail-long-tasks records a stalled workflow task", async () => {
+  const bundle = await loadBundleFixture("never-fail-long-tasks");
+  const validation = await validateBundle(bundle);
+  if (!validation.ok) throw new Error(validation.diagnostics.join("\n"));
+  const installed = await installExtension(bundle);
+  await enableExtension(installed.extension.id);
+
+  const agent = await createAgent({ name: "example-worker", isLead: false, status: "busy" });
+  const task = await createTaskExtended("Example long workflow task", { agentId: agent.id });
+  await startTask(task.id);
+  await getDbClient().run("PRAGMA foreign_keys = OFF");
+  try {
+    await getDbClient().run("UPDATE agent_tasks SET workflowRunStepId = ? WHERE id = ?", [
+      crypto.randomUUID(),
+      task.id,
+    ]);
+  } finally {
+    await getDbClient().run("PRAGMA foreign_keys = ON");
+  }
+  const staleAt = new Date(Date.now() - 10 * 60 * 1000).toISOString();
+  await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+    staleAt,
+    task.id,
+  ]);
+
+  const findings = await codeLevelTriage();
+
+  expect(findings.stalledTasks.map((candidate) => candidate.id)).toContain(task.id);
+  expect(findings.autoFailedTasks).toEqual([]);
+  expect((await getTaskById(task.id))?.status).toBe("in_progress");
+});

package/src/tests/extensions-example-mcp-install.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerExtensionInstallTool } from "../tools/extension-install";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+};
+
+test("a lead can draft the minimal bundle while an operator retains activation", async () => {
+  const previousBaseUrl = process.env.MCP_BASE_URL;
+  const previousApiKey = process.env.AGENT_SWARM_API_KEY;
+  const savedFetch = globalThis.fetch;
+  const leadId = crypto.randomUUID();
+
+  process.env.MCP_BASE_URL = "http://extensions-example.test";
+  process.env.AGENT_SWARM_API_KEY = "extensions-example-key";
+  globalThis.fetch = (async (_input, init) => {
+    const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+    expect(body.enabled).toBeUndefined();
+    expect(body.activeVersion).toBeUndefined();
+    return new Response(
+      JSON.stringify({
+        extension: {
+          id: "extension-1",
+          name: "minimal",
+          version: 1,
+          activeVersion: 1,
+          enabled: false,
+          status: "disabled",
+          priority: 100,
+          consecutiveFailures: 0,
+        },
+        contentDeduped: false,
+      }),
+      { status: 200, headers: { "Content-Type": "application/json" } },
+    );
+  }) as typeof globalThis.fetch;
+
+  try {
+    const server = new McpServer({ name: "extensions-example", version: "1" });
+    registerExtensionInstallTool(server);
+    const tool = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+      ._registeredTools["extension-install"]!;
+    const result = (await tool.handler(await loadBundleFixture("minimal"), {
+      sessionId: "extensions-example",
+      requestInfo: { headers: { "x-agent-id": leadId } },
+    })) as {
+      isError?: boolean;
+      structuredContent: Record<string, unknown>;
+    };
+
+    expect(result.isError).toBe(false);
+    expect(result.structuredContent).toMatchObject({ enabled: false, status: "disabled" });
+    expect(String(result.structuredContent.message)).toContain("operator must enable it");
+  } finally {
+    globalThis.fetch = savedFetch;
+    if (previousBaseUrl === undefined) delete process.env.MCP_BASE_URL;
+    else process.env.MCP_BASE_URL = previousBaseUrl;
+    if (previousApiKey === undefined) delete process.env.AGENT_SWARM_API_KEY;
+    else process.env.AGENT_SWARM_API_KEY = previousApiKey;
+  }
+});

package/src/tests/extensions-example-no-exclamation-marks.test.ts

@@ -0,0 +1,72 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { closeDb, createAgent, createTaskExtended, getTaskById, initDb, startTask } from "../be/db";
+import { installExtension } from "../be/extensions/db";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { registerStoreProgressTool } from "../tools/store-progress";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-no-exclamation-marks.sqlite";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<CallToolResult>;
+};
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+describe("no-exclamation-marks extension example", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  test("rejects emphatic progress and accepts compliant progress", async () => {
+    const installed = await installExtension(await loadBundleFixture("no-exclamation-marks"));
+    await enableExtension(installed.extension.id);
+    const agent = await createAgent({
+      name: "no-exclamation-example-worker",
+      isLead: false,
+      status: "busy",
+      capabilities: [],
+    });
+    const task = await createTaskExtended("no exclamation example", {
+      agentId: agent.id,
+      source: "mcp",
+    });
+    await startTask(task.id);
+
+    const server = new McpServer({ name: "no-exclamation-example", version: "1.0.0" });
+    registerStoreProgressTool(server);
+    const tools = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+      ._registeredTools;
+    const tool = tools["store-progress"];
+    if (!tool) throw new Error("store-progress was not registered");
+    const meta = {
+      sessionId: crypto.randomUUID(),
+      requestInfo: { headers: { "x-agent-id": agent.id } },
+    };
+
+    const blocked = await tool.handler({ taskId: task.id, progress: "done!" }, meta);
+    expect(blocked.isError).toBe(true);
+    expect(JSON.stringify(blocked)).toContain("Progress text must not contain exclamation marks.");
+    expect(JSON.stringify(blocked)).toContain("no-exclamation-marks");
+    expect((await getTaskById(task.id))?.progress).toBeUndefined();
+
+    const accepted = await tool.handler({ taskId: task.id, progress: "done." }, meta);
+    expect(accepted.isError).toBe(false);
+    expect((await getTaskById(task.id))?.progress).toBe("done.");
+  });
+});