@desplega.ai/agent-swarm 1.149.1 → 1.151.0

package/src/tests/extensions-example-rewrite-and-suppress.test.ts

@@ -0,0 +1,70 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import {
+  closeDb,
+  completeTask,
+  createAgent,
+  createTaskExtended,
+  initDb,
+  startTask,
+} from "../be/db";
+import { installExtension } from "../be/extensions/db";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
+import { createWorkerTaskFollowUp } from "../tasks/worker-follow-up";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-rewrite-and-suppress.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function enableFixture(name: string): Promise<void> {
+  const installed = await installExtension(await loadBundleFixture(name));
+  await enableExtension(installed.extension.id);
+}
+
+describe("extension examples: rewrite and suppress", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  test("rewrites task priority and suppresses Slack lead follow-ups", async () => {
+    await enableFixture("rewrite-task-priority");
+    await enableFixture("suppress-lead-follow-up");
+
+    const rewritten = await createTaskWithSiblingAwareness("Prioritize this task", {
+      source: "api",
+      priority: 50,
+    });
+    expect(rewritten.priority).toBe(1);
+
+    await createAgent({ name: "example-lead", isLead: true, status: "idle" });
+    const worker = await createAgent({ name: "example-worker", isLead: false, status: "idle" });
+    const slackTask = await createTaskExtended("Slack task", {
+      agentId: worker.id,
+      source: "slack",
+    });
+    await startTask(slackTask.id);
+    const completed = await completeTask(slackTask.id, "done");
+
+    expect(
+      await createWorkerTaskFollowUp({
+        task: completed!,
+        status: "completed",
+        output: "done",
+      }),
+    ).toBeNull();
+  });
+});

package/src/tests/extensions-example-route-slack-channel.test.ts

@@ -0,0 +1,217 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  closeDb,
+  createAgent,
+  getDbClient,
+  getKv,
+  getMostRecentTaskInThread,
+  initDb,
+} from "../be/db";
+import { installExtension, listExtensionRuns } from "../be/extensions/db";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { _resetForTests as resetSlackEventDedup } from "../slack/event-dedup";
+import { registerMessageHandler, resetSlackHandlerCachesForTesting } from "../slack/handlers";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-route-slack-channel.sqlite";
+const BOT_USER_ID = "U_EXTENSION_ROUTE_BOT";
+const BOT_ID = "B_EXTENSION_ROUTE_BOT";
+
+let messageHandler: ((args: Record<string, unknown>) => Promise<void>) | undefined;
+let leadAgent: Awaited<ReturnType<typeof createAgent>>;
+let workerAgent: Awaited<ReturnType<typeof createAgent>>;
+let eventCounter = 0;
+
+const handlerClient = {
+  auth: { test: async () => ({ user_id: BOT_USER_ID, bot_id: BOT_ID }) },
+  conversations: { replies: async () => ({ messages: [], ok: true }) },
+  reactions: { add: async () => ({ ok: true }) },
+  users: { info: async () => ({ ok: true, user: { profile: {} } }) },
+};
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function sendMessage(channel: string, text: string): Promise<string> {
+  const ts = `1700000000.${String(++eventCounter).padStart(6, "0")}`;
+  await messageHandler!({
+    event: { channel, ts, text, user: "U_EXTENSION_ROUTE_USER" },
+    body: { event_id: `extension-route-${eventCounter}` },
+    client: handlerClient,
+    say: async () => ({}),
+  });
+  return ts;
+}
+
+async function waitFor(predicate: () => Promise<boolean>, timeoutMs = 5_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 Slack channel routing", () => {
+  const savedEnv = { ...process.env };
+
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+    process.env.ADDITIVE_SLACK = "false";
+    process.env.SLACK_RENDER_V2 = "false";
+    process.env.STEERING_ENABLED = "false";
+    leadAgent = await createAgent({
+      name: "extension-route-lead",
+      isLead: true,
+      status: "idle",
+      capabilities: [],
+    });
+    workerAgent = await createAgent({
+      name: "extension-route-worker",
+      isLead: false,
+      status: "idle",
+      capabilities: [],
+    });
+    registerMessageHandler({
+      event: (eventType: string, handler: (args: Record<string, unknown>) => Promise<void>) => {
+        if (eventType === "message") messageHandler = handler;
+      },
+    } as never);
+  });
+
+  afterAll(async () => {
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+    for (const key of Object.keys(process.env)) {
+      if (!(key in savedEnv)) delete process.env[key];
+    }
+    Object.assign(process.env, savedEnv);
+  });
+
+  beforeEach(async () => {
+    await stopExtensionRuntime();
+    await getDbClient().run("DELETE FROM agent_tasks");
+    await getDbClient().run("DELETE FROM extensions");
+    await getDbClient().run("DELETE FROM kv_entries");
+    resetSlackEventDedup();
+    resetSlackHandlerCachesForTesting();
+  });
+
+  test("routes the configured channel to its worker and leaves other channels with the lead", async () => {
+    const bundle = await loadBundleFixture("route-channel-to-agent");
+    const extension = (
+      await installExtension({
+        ...bundle,
+        config: { channelId: "C1", agentId: workerAgent.id },
+      })
+    ).extension;
+    await enableExtension(extension.id);
+
+    const routedTs = await sendMessage("C1", `<@${BOT_USER_ID}> route this task`);
+    expect(await getMostRecentTaskInThread("C1", routedTs)).toMatchObject({
+      agentId: workerAgent.id,
+      source: "slack",
+    });
+    expect(
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "pre.slack.route" && run.action === "modify",
+      ),
+    ).toBe(true);
+
+    const defaultTs = await sendMessage("C2", `<@${BOT_USER_ID}> use the normal route`);
+    expect(await getMostRecentTaskInThread("C2", defaultTs)).toMatchObject({
+      agentId: leadAgent.id,
+      source: "slack",
+    });
+  });
+
+  test("blocks messages in an ignored channel before task creation", async () => {
+    const bundle = await loadBundleFixture("ignore-channel");
+    const extension = (await installExtension({ ...bundle, config: { channelId: "C3" } }))
+      .extension;
+    await enableExtension(extension.id);
+
+    const ts = await sendMessage("C3", `<@${BOT_USER_ID}> do not create a task`);
+    expect(await getMostRecentTaskInThread("C3", ts)).toBeNull();
+    expect(
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "pre.slack.route" && run.action === "block",
+      ),
+    ).toBe(true);
+  });
+
+  test("falls back to the built-in router when an extension names an unknown agent", async () => {
+    const bundle = await loadBundleFixture("route-channel-to-agent");
+    const extension = (
+      await installExtension({
+        ...bundle,
+        config: { channelId: "C4", agentId: "missing-agent" },
+      })
+    ).extension;
+    await enableExtension(extension.id);
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const ts = await sendMessage("C4", `<@${BOT_USER_ID}> use the fallback`);
+      expect(await getMostRecentTaskInThread("C4", ts)).toMatchObject({ agentId: leadAgent.id });
+      expect(warn).toHaveBeenCalledWith(
+        "[Slack] Extension selected an unknown agent. Using the built-in router:",
+        "missing-agent",
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("treats a runtime-invalid route target as an extension failure and keeps routing", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const extension = (
+      await installExtension({
+        manifest: { ...bundle.manifest, name: "bad-route-target", description: "bad target" },
+        files: {
+          "hooks.ts": `import { modify, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.slack.route", () => modify({ target: null } as never));
+};
+export default extension;
+`,
+        },
+      })
+    ).extension;
+    await enableExtension(extension.id);
+
+    const ts = await sendMessage("C5", `<@${BOT_USER_ID}> survive the bad target`);
+    expect(await getMostRecentTaskInThread("C5", ts)).toMatchObject({ agentId: leadAgent.id });
+    const runs = await listExtensionRuns(extension.id);
+    expect(runs.some((run) => run.event === "pre.slack.route" && run.action === "error")).toBe(
+      true,
+    );
+  });
+
+  test("dispatches post.slack.message with the canonical channel and user fields", async () => {
+    const bundle = await loadBundleFixture("route-channel-to-agent");
+    const extension = (
+      await installExtension({
+        ...bundle,
+        config: { channelId: "C5", agentId: workerAgent.id },
+      })
+    ).extension;
+    const enabled = await enableExtension(extension.id);
+
+    await sendMessage("C5", `<@${BOT_USER_ID}> record this message`);
+    await waitFor(async () =>
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "post.slack.message" && run.action === "continue",
+      ),
+    );
+    expect(
+      await getKv(`task:agent:${enabled.agentId}`, "ext:route-channel-to-agent:slack:C5"),
+    ).toMatchObject({ value: "U_EXTENSION_ROUTE_USER" });
+  });
+});

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

@@ -0,0 +1,291 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getChildTasks,
+  getDbClient,
+  getTaskById,
+  initDb,
+  insertActiveSession,
+  startTask,
+} from "../be/db";
+import { installExtension, listExtensionRuns } from "../be/extensions/db";
+import { validateBundle } from "../be/extensions/validate";
+import { disableExtension, enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { codeLevelTriage } from "../heartbeat/heartbeat";
+import type { ExtensionInstallBody } from "../types";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-heartbeat.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await Bun.file(TEST_DB_PATH + suffix)
+      .delete()
+      .catch(() => {});
+  }
+}
+
+async function enableBundle(bundle: ExtensionInstallBody) {
+  const validation = await validateBundle(bundle);
+  if (!validation.ok) throw new Error(validation.diagnostics.join("\n"));
+  const installed = await installExtension(bundle);
+  return await enableExtension(installed.extension.id);
+}
+
+async function createStalledTask(options: {
+  minutes: number;
+  tags?: string[];
+  workflowStep?: boolean;
+  session?: "fresh" | "stale";
+  creatorAgentId?: string;
+  taskType?: string;
+}) {
+  const agent = await createAgent({
+    name: `heartbeat-worker-${crypto.randomUUID()}`,
+    isLead: false,
+    status: "busy",
+  });
+  const task = await createTaskExtended("Long-running heartbeat task", {
+    agentId: agent.id,
+    creatorAgentId: options.creatorAgentId,
+    tags: options.tags,
+    taskType: options.taskType,
+  });
+  await startTask(task.id);
+
+  if (options.workflowStep) {
+    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");
+    }
+  }
+
+  if (options.session) {
+    await insertActiveSession({
+      agentId: agent.id,
+      taskId: task.id,
+      triggerType: "task_assigned",
+    });
+  }
+
+  const staleAt = new Date(Date.now() - options.minutes * 60 * 1000).toISOString();
+  await getDbClient().run("UPDATE agent_tasks SET lastUpdatedAt = ? WHERE id = ?", [
+    staleAt,
+    task.id,
+  ]);
+  if (options.session === "stale") {
+    await getDbClient().run("UPDATE active_sessions SET lastHeartbeatAt = ? WHERE taskId = ?", [
+      staleAt,
+      task.id,
+    ]);
+  }
+
+  return { agent, task };
+}
+
+describe("pre.heartbeat.remediate extensions", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    closeDb();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await stopExtensionRuntime();
+    const client = getDbClient();
+    await client.run("DELETE FROM active_sessions");
+    await client.run("DELETE FROM agent_tasks");
+    await client.run("DELETE FROM extensions");
+    await client.run("DELETE FROM agents");
+  });
+
+  test("keeps default no-session remediation when no extension is enabled", async () => {
+    const { task } = await createStalledTask({ minutes: 10 });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.autoResumedTasks).toHaveLength(1);
+    expect(findings.autoResumedTasks[0]?.taskId).toBe(task.id);
+    expect(findings.extensionSkipped).toEqual([]);
+    expect((await getTaskById(task.id))?.status).toBe("superseded");
+  });
+
+  test("changes a workflow-step fail proposal to record", async () => {
+    const extension = await enableBundle(await loadBundleFixture("never-fail-long-tasks"));
+    const { task } = await createStalledTask({ minutes: 10, workflowStep: true });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.stalledTasks.map((candidate) => candidate.id)).toContain(task.id);
+    expect(findings.autoFailedTasks).toEqual([]);
+    expect(findings.autoResumedTasks).toEqual([]);
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+    expect(await listExtensionRuns(extension.id)).toMatchObject([
+      { event: "pre.heartbeat.remediate", action: "modify" },
+    ]);
+  });
+
+  test("escalates a Case A fail proposal to supersede-resume", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    bundle.manifest = { ...bundle.manifest, name: "resume-no-session-failures" };
+    bundle.files["hooks.ts"] = `
+import { modify, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.heartbeat.remediate", (event) => {
+    if (event.classification === "no-session" && event.proposedAction === "fail") {
+      return modify({ proposedAction: "supersede-resume" });
+    }
+  });
+};
+export default extension;
+`;
+    const extension = await enableBundle(bundle);
+    const { task } = await createStalledTask({ minutes: 10, taskType: "reroute-decision" });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.autoFailedTasks).toEqual([]);
+    expect(findings.autoResumedTasks[0]?.taskId).toBe(task.id);
+    expect((await getTaskById(task.id))?.status).toBe("superseded");
+    expect((await getChildTasks(task.id))[0]?.taskType).toBe("resume");
+    expect(await listExtensionRuns(extension.id)).toMatchObject([
+      { event: "pre.heartbeat.remediate", action: "modify" },
+    ]);
+  });
+
+  test("blocks remediation for a configured task tag", async () => {
+    const bundle = await loadBundleFixture("record-only-on-tag");
+    const extension = await enableBundle({ ...bundle, config: { tag: "manual" } });
+    const { task } = await createStalledTask({ minutes: 10, tags: ["manual"] });
+
+    const findings = await codeLevelTriage();
+
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+    expect(findings.stalledTasks.map((candidate) => candidate.id)).toContain(task.id);
+    expect(findings.extensionSkipped).toEqual([
+      {
+        taskId: task.id,
+        extension: { id: extension.id, name: "record-only-on-tag" },
+        reason: "Heartbeat remediation blocked for tag manual",
+      },
+    ]);
+
+    await disableExtension(extension.id);
+    const withoutExtension = await codeLevelTriage();
+    expect(withoutExtension.autoResumedTasks[0]?.taskId).toBe(task.id);
+    expect((await getTaskById(task.id))?.status).toBe("superseded");
+  });
+
+  test("provides stale-session details before remediation", async () => {
+    const bundle = await loadBundleFixture("never-fail-long-tasks");
+    bundle.manifest = { ...bundle.manifest, name: "record-stale-sessions" };
+    bundle.files["hooks.ts"] = `
+import { modify, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.heartbeat.remediate", (event) => {
+    if (
+      event.classification === "stale-session" &&
+      event.session &&
+      event.sessionHeartbeatAgeMs !== undefined &&
+      event.reason.includes("heartbeat is stale")
+    ) {
+      return modify({ proposedAction: "record" });
+    }
+  });
+};
+export default extension;
+`;
+    await enableBundle(bundle);
+    const { task } = await createStalledTask({ minutes: 20, session: "stale" });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.stalledTasks.map((candidate) => candidate.id)).toContain(task.id);
+    expect(findings.autoResumedTasks).toEqual([]);
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+  });
+
+  test("keeps the original action when an extension returns an invalid action", async () => {
+    const bundle = await loadBundleFixture("never-fail-long-tasks");
+    bundle.manifest = { ...bundle.manifest, name: "invalid-heartbeat-action" };
+    bundle.files["hooks.ts"] = `
+import { modify, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.heartbeat.remediate", () =>
+    modify({ proposedAction: "invalid-action" as never }),
+  );
+};
+export default extension;
+`;
+    await enableBundle(bundle);
+    const { task } = await createStalledTask({ minutes: 10 });
+    const warning = spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const findings = await codeLevelTriage();
+      expect(findings.autoResumedTasks[0]?.taskId).toBe(task.id);
+      expect((await getTaskById(task.id))?.status).toBe("superseded");
+      expect(warning).toHaveBeenCalledWith(
+        "[Heartbeat] Extension returned an invalid remediation action:",
+        "invalid-action",
+      );
+    } finally {
+      warning.mockRestore();
+    }
+  });
+
+  test("can escalate a fresh-session stall to supersede and resume", async () => {
+    const bundle = await loadBundleFixture("never-fail-long-tasks");
+    bundle.manifest = { ...bundle.manifest, name: "resume-fresh-stalls" };
+    bundle.files["hooks.ts"] = `
+import { modify, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.heartbeat.remediate", (event) => {
+    if (event.classification === "fresh-stalled") {
+      return modify({ proposedAction: "supersede-resume" });
+    }
+  });
+};
+export default extension;
+`;
+    await enableBundle(bundle);
+    const { task } = await createStalledTask({ minutes: 45, session: "fresh" });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.autoResumedTasks[0]?.taskId).toBe(task.id);
+    expect(findings.stalledTasks).toEqual([]);
+    expect((await getTaskById(task.id))?.status).toBe("superseded");
+    expect((await getChildTasks(task.id))[0]?.taskType).toBe("resume");
+  });
+
+  test("skips the extension that created the stalled task", async () => {
+    const bundle = await loadBundleFixture("record-only-on-tag");
+    bundle.manifest = { ...bundle.manifest, name: "skip-own-heartbeat" };
+    const extension = await enableBundle({ ...bundle, config: { tag: "manual" } });
+    const { task } = await createStalledTask({
+      minutes: 10,
+      tags: ["manual"],
+      creatorAgentId: extension.agentId ?? undefined,
+    });
+
+    const findings = await codeLevelTriage();
+
+    expect(findings.extensionSkipped).toEqual([]);
+    expect(findings.autoResumedTasks[0]?.taskId).toBe(task.id);
+    expect(await listExtensionRuns(extension.id)).toEqual([]);
+  });
+});