@desplega.ai/agent-swarm 1.161.0 → 1.162.0

package/src/tests/api-drain.test.ts

@@ -0,0 +1,351 @@
+/**
+ * API drain, server side: the process-local state, the bounded wait for worker
+ * handoffs, and the rule that a draining API dispatches no new work through any
+ * of the three paths that start or claim a task (HTTP poll, MCP poll-task, MCP
+ * task-action claim and accept).
+ */
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { createServer as createHttpServer, type Server } from "node:http";
+import {
+  beginApiDrain,
+  countStillInProgress,
+  DEFAULT_API_DRAIN_MAX_MS,
+  drainApi,
+  isApiDraining,
+  listLiveInFlightTaskIds,
+  resetApiDrainForTesting,
+  resolveApiDrainMaxMs,
+} from "../be/api-drain";
+import {
+  closeDb,
+  createAgent,
+  createTaskExtended,
+  getDbClient,
+  getTaskById,
+  initDb,
+  startTask,
+} from "../be/db";
+import { validateConfigValue } from "../be/swarm-config-guard";
+import { handlePoll } from "../http/poll";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { registerPollTaskTool } from "../tools/poll-task";
+import { registerTaskActionTool } from "../tools/task-action";
+import { API_DRAIN_MAX_MS_LIMIT } from "../utils/api-drain";
+import { listenOnFreePort } from "./test-net";
+
+const TEST_DB_PATH = "./test-api-drain.sqlite";
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(TEST_DB_PATH + suffix).catch(() => {});
+  }
+}
+
+class MockMcpServer {
+  handlers = new Map<string, (args: unknown, extra: unknown) => Promise<unknown>>();
+  registerTool(
+    name: string,
+    _config: unknown,
+    handler: (args: unknown, extra: unknown) => Promise<unknown>,
+  ) {
+    this.handlers.set(name, handler);
+    return { name };
+  }
+}
+
+let server: Server;
+let baseUrl = "";
+const mcp = new MockMcpServer();
+
+beforeAll(async () => {
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+  registerPollTaskTool(mcp as unknown as Parameters<typeof registerPollTaskTool>[0]);
+  registerTaskActionTool(mcp as unknown as Parameters<typeof registerTaskActionTool>[0]);
+  server = createHttpServer(async (req, res) => {
+    const myAgentId = req.headers["x-agent-id"] as string | undefined;
+    const handled = await handlePoll(
+      req,
+      res,
+      getPathSegments(req.url || ""),
+      parseQueryParams(req.url || ""),
+      myAgentId,
+    );
+    if (!handled) {
+      res.writeHead(404);
+      res.end();
+    }
+  });
+  baseUrl = `http://127.0.0.1:${await listenOnFreePort(server)}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  await removeDbFiles();
+});
+
+afterEach(() => {
+  resetApiDrainForTesting();
+});
+
+async function makeAgent(opts: { isLead?: boolean; lastUpdatedAt?: string; status?: string } = {}) {
+  const id = crypto.randomUUID();
+  await createAgent({
+    id,
+    name: "drain-test-agent",
+    isLead: opts.isLead ?? false,
+    status: "idle",
+    capabilities: [],
+    maxTasks: 1,
+  });
+  if (opts.lastUpdatedAt || opts.status) {
+    await getDbClient().run(
+      "UPDATE agents SET lastUpdatedAt = COALESCE(?, lastUpdatedAt), status = COALESCE(?, status) WHERE id = ?",
+      [opts.lastUpdatedAt ?? null, opts.status ?? null, id],
+    );
+  }
+  return id;
+}
+
+async function poll(agentId: string) {
+  const res = await fetch(`${baseUrl}/api/poll`, { headers: { "X-Agent-ID": agentId } });
+  return (await res.json()) as { trigger: { type: string; taskId?: string } | null };
+}
+
+async function callTool(name: string, args: unknown, agentId: string) {
+  const handler = mcp.handlers.get(name);
+  if (!handler) throw new Error(`${name} not registered`);
+  return (await handler(args, {
+    sessionId: "test-session",
+    requestInfo: { headers: { "x-agent-id": agentId } },
+    sendNotification: async () => {},
+  })) as { isError?: boolean; content?: Array<{ text?: string }> };
+}
+
+describe("drain state", () => {
+  test("starts not draining; begin is idempotent; reset clears it", () => {
+    expect(isApiDraining()).toBe(false);
+    expect(beginApiDrain()).toBe(true);
+    expect(isApiDraining()).toBe(true);
+    expect(beginApiDrain()).toBe(false);
+    resetApiDrainForTesting();
+    expect(isApiDraining()).toBe(false);
+  });
+
+  test("API_DRAIN_MAX_MS: opt-in, so unset, empty, or invalid means 0 (off)", () => {
+    expect(DEFAULT_API_DRAIN_MAX_MS).toBe(0);
+    expect(resolveApiDrainMaxMs({})).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "" })).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "  " })).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "abc" })).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "-5" })).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "0" })).toBe(0);
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "5000" })).toBe(5000);
+  });
+});
+
+describe("API_DRAIN_MAX_MS config", () => {
+  test("the validator and the resolver share one range", () => {
+    expect(validateConfigValue("API_DRAIN_MAX_MS", "0")).toBeNull();
+    expect(validateConfigValue("API_DRAIN_MAX_MS", "30000")).toBeNull();
+    expect(validateConfigValue("API_DRAIN_MAX_MS", String(API_DRAIN_MAX_MS_LIMIT))).toBeNull();
+    expect(validateConfigValue("API_DRAIN_MAX_MS", String(API_DRAIN_MAX_MS_LIMIT + 1))).toContain(
+      `between 0 and ${API_DRAIN_MAX_MS_LIMIT}`,
+    );
+    expect(validateConfigValue("API_DRAIN_MAX_MS", "-1")).not.toBeNull();
+    expect(validateConfigValue("API_DRAIN_MAX_MS", "soon")).not.toBeNull();
+    // A value past the limit would be clamped at shutdown, never silently honored.
+    expect(resolveApiDrainMaxMs({ API_DRAIN_MAX_MS: "9999999" })).toBe(API_DRAIN_MAX_MS_LIMIT);
+  });
+});
+
+describe("drainApi", () => {
+  /** A fake clock: sleeping advances it, so the wait is deterministic. */
+  function fakeClock() {
+    let t = 1_000;
+    return {
+      now: () => t,
+      sleep: async (ms: number) => {
+        t += ms;
+      },
+    };
+  }
+
+  test("off: does not enter the draining state and reads nothing", async () => {
+    // Unset is the default and must behave exactly like an explicit 0.
+    for (const env of [{}, { API_DRAIN_MAX_MS: "0" }, { API_DRAIN_MAX_MS: "garbage" }]) {
+      let reads = 0;
+      const outcome = await drainApi({
+        env,
+        log: () => {},
+        listInFlight: async () => {
+          reads++;
+          return ["in-flight"];
+        },
+      });
+      expect(outcome.enabled).toBe(false);
+      expect(isApiDraining()).toBe(false);
+      expect(reads).toBe(0);
+    }
+  });
+
+  test("no in-flight tasks: drains at once without waiting", async () => {
+    const clock = fakeClock();
+    const outcome = await drainApi({
+      ...clock,
+      env: { API_DRAIN_MAX_MS: "30000" },
+      log: () => {},
+      listInFlight: async () => [],
+    });
+    expect(isApiDraining()).toBe(true);
+    expect(outcome).toMatchObject({ enabled: true, inFlight: 0, remaining: 0, timedOut: false });
+    expect(clock.now()).toBe(1_000);
+  });
+
+  test("returns as soon as every in-flight task is handed off", async () => {
+    const clock = fakeClock();
+    const remainingByRead = [2, 1, 0];
+    let reads = 0;
+    const outcome = await drainApi({
+      ...clock,
+      env: { API_DRAIN_MAX_MS: "30000" },
+      log: () => {},
+      listInFlight: async () => ["a", "b"],
+      countRemaining: async () => remainingByRead[reads++] ?? 0,
+    });
+    expect(outcome).toMatchObject({ inFlight: 2, remaining: 0, timedOut: false });
+    expect(outcome.waitedMs).toBe(1_000);
+    expect(isApiDraining()).toBe(true);
+  });
+
+  test("gives up at the cap and reports what was left", async () => {
+    const clock = fakeClock();
+    const outcome = await drainApi({
+      ...clock,
+      env: { API_DRAIN_MAX_MS: "3000" },
+      log: () => {},
+      listInFlight: async () => ["a", "b"],
+      countRemaining: async () => 1,
+    });
+    expect(outcome).toMatchObject({ inFlight: 2, remaining: 1, timedOut: true });
+    expect(outcome.waitedMs).toBe(3_000);
+  });
+
+  test("a failing read ends the wait instead of blocking shutdown", async () => {
+    const lines: string[] = [];
+    const clock = fakeClock();
+    const outcome = await drainApi({
+      ...clock,
+      env: { API_DRAIN_MAX_MS: "30000" },
+      log: (line) => lines.push(line),
+      listInFlight: async () => {
+        throw new Error("database is locked");
+      },
+    });
+    expect(outcome).toMatchObject({ enabled: true, inFlight: 0, timedOut: false });
+    expect(lines.join("\n")).toContain("database is locked");
+  });
+});
+
+describe("in-flight reads", () => {
+  test("only in_progress tasks held by a worker that pinged recently count", async () => {
+    const live = await makeAgent();
+    const silent = await makeAgent({
+      lastUpdatedAt: new Date(Date.now() - 5 * 60_000).toISOString(),
+    });
+    const offline = await makeAgent({ status: "offline" });
+    const idleLive = await makeAgent();
+
+    const liveTask = await createTaskExtended("live", { agentId: live });
+    const silentTask = await createTaskExtended("silent", { agentId: silent });
+    const offlineTask = await createTaskExtended("offline", { agentId: offline });
+    const pendingTask = await createTaskExtended("pending", { agentId: idleLive });
+    for (const task of [liveTask, silentTask, offlineTask]) await startTask(task.id);
+
+    const ids = await listLiveInFlightTaskIds();
+    expect(ids).toContain(liveTask.id);
+    expect(ids).not.toContain(silentTask.id);
+    expect(ids).not.toContain(offlineTask.id);
+    expect(ids).not.toContain(pendingTask.id);
+  });
+
+  test("countStillInProgress drops a task once it leaves in_progress", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("to-hand-off", { agentId: agent });
+    await startTask(task.id);
+    expect(await countStillInProgress([task.id])).toBe(1);
+    expect(await countStillInProgress([])).toBe(0);
+    await getDbClient().run("UPDATE agent_tasks SET status = 'superseded' WHERE id = ?", [task.id]);
+    expect(await countStillInProgress([task.id])).toBe(0);
+  });
+});
+
+describe("a draining API dispatches nothing", () => {
+  test("HTTP poll starts no assigned task, then does once the drain ends", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("assigned", { agentId: agent });
+    beginApiDrain();
+
+    expect((await poll(agent)).trigger).toBeNull();
+    expect((await getTaskById(task.id))?.status).toBe("pending");
+
+    resetApiDrainForTesting();
+    const after = await poll(agent);
+    expect(after.trigger?.type).toBe("task_assigned");
+    expect(after.trigger?.taskId).toBe(task.id);
+    expect((await getTaskById(task.id))?.status).toBe("in_progress");
+  });
+
+  test("HTTP poll claims no pool task while draining", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("pool task");
+    beginApiDrain();
+    expect((await poll(agent)).trigger).toBeNull();
+    expect((await getTaskById(task.id))?.agentId ?? null).toBeNull();
+  });
+
+  test("a poll still answers 404 for an unknown agent while draining", async () => {
+    beginApiDrain();
+    const res = await fetch(`${baseUrl}/api/poll`, {
+      headers: { "X-Agent-ID": crypto.randomUUID() },
+    });
+    expect(res.status).toBe(404);
+  });
+
+  test("MCP poll-task starts no pending task while draining", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("mcp-assigned", { agentId: agent });
+    beginApiDrain();
+
+    const result = await callTool("poll-task", {}, agent);
+    expect(result.isError).not.toBe(true);
+    expect(JSON.stringify(result)).toContain("draining");
+    expect((await getTaskById(task.id))?.status).toBe("pending");
+  });
+
+  test("MCP task-action claim is refused while draining", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("mcp-pool");
+    beginApiDrain();
+
+    const result = await callTool("task-action", { action: "claim", taskId: task.id }, agent);
+    expect(JSON.stringify(result)).toContain("draining");
+    expect((await getTaskById(task.id))?.agentId ?? null).toBeNull();
+
+    resetApiDrainForTesting();
+    await callTool("task-action", { action: "claim", taskId: task.id }, agent);
+    expect((await getTaskById(task.id))?.agentId).toBe(agent);
+  });
+
+  test("MCP task-action accept is refused while draining", async () => {
+    const agent = await makeAgent();
+    const task = await createTaskExtended("offered", { offeredTo: agent });
+    beginApiDrain();
+
+    const result = await callTool("task-action", { action: "accept", taskId: task.id }, agent);
+    expect(JSON.stringify(result)).toContain("draining");
+    expect((await getTaskById(task.id))?.status).toBe("offered");
+  });
+});

package/src/tests/comb-config-guard.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from "bun:test";
+import { validateConfigValue } from "../be/swarm-config-guard";
+
+describe("Comb config keys", () => {
+  test("COMB_ENABLED accepts boolean literals only", () => {
+    for (const value of ["true", "false", "1", "0", " TRUE "]) {
+      expect(validateConfigValue("COMB_ENABLED", value)).toBeNull();
+    }
+    for (const value of ["yes", "on", ""]) {
+      expect(validateConfigValue("COMB_ENABLED", value)).toContain("Invalid COMB_ENABLED");
+    }
+  });
+
+  test("AGENT_FS_PUBLIC_URL accepts blank or an http(s) base URL", () => {
+    for (const value of ["", "http://localhost:7433", "https://agent-fs.example.com/base"]) {
+      expect(validateConfigValue("AGENT_FS_PUBLIC_URL", value)).toBeNull();
+    }
+    for (const value of [
+      "agent-fs.example.com",
+      "not a url",
+      "ftp://agent-fs.example.com",
+      "https://agent-fs.example.com/?x=1",
+      "https://agent-fs.example.com/#frag",
+    ]) {
+      expect(validateConfigValue("AGENT_FS_PUBLIC_URL", value)).toContain(
+        "Invalid AGENT_FS_PUBLIC_URL",
+      );
+    }
+  });
+
+  test("OPENROUTER_BASE_URL keeps its rules after sharing the URL validator", () => {
+    expect(validateConfigValue("OPENROUTER_BASE_URL", "")).toBeNull();
+    expect(validateConfigValue("OPENROUTER_BASE_URL", "https://api.example.com/v1")).toBeNull();
+    expect(validateConfigValue("OPENROUTER_BASE_URL", "https://api.example.com/v1?x=1")).toContain(
+      "Invalid OPENROUTER_BASE_URL",
+    );
+  });
+});

package/src/tests/comb-links.test.ts

@@ -0,0 +1,162 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { buildCitationUrl } from "../be/task-citations";
+import type { TaskAttachment } from "../types";
+import { buildAgentFsLiveUrl, buildCombFileUrl } from "../utils/constants";
+import { taskAttachmentDisplayUrl } from "../utils/task-attachment-links";
+
+const ENV_KEYS = [
+  "COMB_ENABLED",
+  "APP_URL",
+  "DASHBOARD_URL",
+  "AGENT_FS_API_URL",
+  "AGENT_FS_LIVE_URL",
+  "AGENT_FS_DEFAULT_ORG_ID",
+  "AGENT_FS_DEFAULT_DRIVE_ID",
+] as const;
+const saved = new Map<string, string | undefined>();
+
+beforeEach(() => {
+  for (const key of ENV_KEYS) {
+    saved.set(key, process.env[key]);
+    delete process.env[key];
+  }
+  process.env.AGENT_FS_API_URL = "http://agent-fs:7433";
+  process.env.AGENT_FS_LIVE_URL = "https://live.example.test/";
+});
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    const value = saved.get(key);
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+function agentFsAttachment(overrides: Partial<TaskAttachment> = {}): TaskAttachment {
+  return {
+    id: "att-1",
+    taskId: "task-1",
+    kind: "agent-fs",
+    name: "notes.md",
+    providerId: "agent-fs",
+    path: "comb-qa/notes.md",
+    orgId: "org-1",
+    driveId: "drive-1",
+    ...overrides,
+  } as TaskAttachment;
+}
+
+const LIVE = "https://live.example.test/file/~/org-1/drive-1/comb-qa/notes.md";
+const COMB = "http://localhost:5274/file/~/org-1/drive-1/comb-qa/notes.md";
+
+describe("taskAttachmentDisplayUrl for agent-fs attachments", () => {
+  test("flag off: the live URL, even with APP_URL set", () => {
+    process.env.APP_URL = "http://localhost:5274";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(LIVE);
+    process.env.COMB_ENABLED = "false";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(LIVE);
+  });
+
+  test("flag on with APP_URL: the dashboard URL", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274/";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(COMB);
+  });
+
+  test("the deprecated DASHBOARD_URL also counts as a configured app URL", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.DASHBOARD_URL = "http://localhost:5274";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(COMB);
+  });
+
+  test("flag on without APP_URL: the live URL (never the hosted default dashboard)", () => {
+    process.env.COMB_ENABLED = "true";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(LIVE);
+  });
+
+  test("flag on without an agent-fs API URL: Comb is off, so the live URL", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    delete process.env.AGENT_FS_API_URL;
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(LIVE);
+  });
+
+  test("comb: false keeps the live URL", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment(), { comb: false })).toBe(LIVE);
+  });
+
+  test("row ids override env ids, and a partial row never mixes with them", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    process.env.AGENT_FS_DEFAULT_ORG_ID = "env-org";
+    process.env.AGENT_FS_DEFAULT_DRIVE_ID = "env-drive";
+    expect(taskAttachmentDisplayUrl(agentFsAttachment())).toBe(COMB);
+    expect(
+      taskAttachmentDisplayUrl(agentFsAttachment({ orgId: undefined, driveId: undefined })),
+    ).toBe("http://localhost:5274/file/~/env-org/env-drive/comb-qa/notes.md");
+    expect(taskAttachmentDisplayUrl(agentFsAttachment({ driveId: undefined }))).toBe(
+      "agent-fs:comb-qa/notes.md",
+    );
+  });
+
+  test("encoding keeps existing %HH escapes and encodes raw text", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    expect(
+      taskAttachmentDisplayUrl(
+        agentFsAttachment({ path: "/shared%20reports/final report 100%.md" }),
+      ),
+    ).toBe(
+      "http://localhost:5274/file/~/org-1/drive-1/shared%20reports/final%20report%20100%25.md",
+    );
+    expect(
+      buildCombFileUrl({ path: "reports/café #1?.md", orgId: "org-1", driveId: "drive-1" }),
+    ).toBe("http://localhost:5274/file/~/org-1/drive-1/reports/caf%C3%A9%20%231%3F.md");
+  });
+
+  test("other attachment kinds are unchanged", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    expect(
+      taskAttachmentDisplayUrl(
+        agentFsAttachment({ kind: "url", providerId: undefined, url: "https://example.com/a" }),
+      ),
+    ).toBe("https://example.com/a");
+    expect(
+      taskAttachmentDisplayUrl(
+        agentFsAttachment({ kind: "page", providerId: undefined, pageId: "page-1" }),
+      ),
+    ).toBe("http://localhost:5274/pages/page-1");
+  });
+
+  test("a dot segment, raw or encoded, falls back to agent-fs:<path>", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    for (const path of ["../../settings", "%2e%2e/%2e%2e/settings", "a/./b.md", "a/.%2E/b.md"]) {
+      const file = { path, orgId: "org-1", driveId: "drive-1" };
+      expect(buildCombFileUrl(file)).toBeNull();
+      expect(buildAgentFsLiveUrl(file)).toBeNull();
+      expect(taskAttachmentDisplayUrl(agentFsAttachment({ path }))).toBe(`agent-fs:${path}`);
+    }
+    // Dots inside a name are not dot segments.
+    expect(buildAgentFsLiveUrl({ path: "a/.b/c..md", orgId: "org-1", driveId: "drive-1" })).toBe(
+      "https://live.example.test/file/~/org-1/drive-1/a/.b/c..md",
+    );
+  });
+});
+
+describe("agent-fs citations", () => {
+  test("store the live URL even with Comb on (the dashboard maps it when it renders)", () => {
+    process.env.COMB_ENABLED = "true";
+    process.env.APP_URL = "http://localhost:5274";
+    process.env.AGENT_FS_DEFAULT_ORG_ID = "org-1";
+    process.env.AGENT_FS_DEFAULT_DRIVE_ID = "drive-1";
+    expect(buildCitationUrl({ index: 1, kind: "agent-fs", ref: "comb-qa/notes.md" })).toBe(LIVE);
+    // Slack and prompts still link attachments to the dashboard.
+    expect(
+      taskAttachmentDisplayUrl(agentFsAttachment({ orgId: undefined, driveId: undefined })),
+    ).toBe(COMB);
+  });
+});

package/src/tests/comb-markers.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import * as ui from "../../apps/ui/src/lib/comb/markers";
+import * as server from "../comb/markers";
+
+// The server posts the "sent" reply and the dashboard reads it. Both copies
+// of the pattern and of the "is it sent" rule must agree. The `@swarm` marker
+// (`SWARM_MARKER_RE`) has no server copy: the server does not require it.
+
+const TASK_ID = "0b8e1f5c-3d2a-4c6b-9e7f-1a2b3c4d5e6f";
+const SERVICE = "svc";
+const HUMAN = "human";
+
+const BODIES = [
+  `${server.sentMarker(TASK_ID)} Sent to the swarm: https://app.example/tasks/${TASK_ID}`,
+  server.sentMarker(TASK_ID),
+  `ok ${server.sentMarker(TASK_ID)}`,
+  "[comb:sent task=not-a-uuid]",
+  `[comb:sent task=${TASK_ID.toUpperCase()}]`,
+  "",
+  "plain reply",
+];
+
+const THREADS: Array<{ author: string; replies: Array<{ author: string; body: string }> }> = [
+  { author: HUMAN, replies: [] },
+  { author: HUMAN, replies: [{ author: SERVICE, body: server.sentMarker(TASK_ID) }] },
+  { author: HUMAN, replies: [{ author: HUMAN, body: server.sentMarker(TASK_ID) }] },
+  { author: HUMAN, replies: [{ author: "other", body: server.sentMarker(TASK_ID) }] },
+  { author: HUMAN, replies: [{ author: SERVICE, body: `ok ${server.sentMarker(TASK_ID)}` }] },
+  {
+    author: HUMAN,
+    replies: [
+      { author: "other", body: "thanks" },
+      { author: SERVICE, body: server.sentMarker(TASK_ID) },
+    ],
+  },
+];
+
+describe("sent marker: server and dashboard agree", () => {
+  test("the patterns are the same, byte for byte", () => {
+    expect(String(server.SENT_MARKER_RE)).toBe(String(ui.SENT_MARKER_RE));
+  });
+
+  test("the server's reply parses in the dashboard", () => {
+    expect(ui.sentTaskIdOf({ body: server.sentMarker(TASK_ID) })).toBe(TASK_ID);
+  });
+
+  test("both match the same bodies", () => {
+    for (const body of BODIES) {
+      expect(server.SENT_MARKER_RE.test(body)).toBe(ui.SENT_MARKER_RE.test(body));
+    }
+  });
+
+  test("both decide 'sent' the same way, with and without a known service account", () => {
+    for (const serviceUserId of [SERVICE, null]) {
+      for (const thread of THREADS) {
+        expect(server.sentTaskId(thread, thread.replies, serviceUserId) !== null).toBe(
+          ui.isSentToSwarm(thread, serviceUserId),
+        );
+      }
+    }
+  });
+
+  test("a known service account is the only trusted author", () => {
+    const byOther = THREADS[3] as (typeof THREADS)[number];
+    expect(server.sentTaskId(byOther, byOther.replies, SERVICE)).toBeNull();
+    expect(server.sentTaskId(byOther, byOther.replies, null)).toBe(TASK_ID);
+  });
+});