@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/tests/db-task-write-contract.test.ts

@@ -95,6 +95,7 @@ type:McpServerFilters
 type:McpServerInsert
 type:MentionPreview
 type:PageListOptions
+type:PendingChatRelay
 type:PlanSource
 type:RecordBudgetRefusalNotificationInput
 type:ScheduledTaskFilters
@@ -260,6 +261,7 @@ value:getAgentMcpServers
 value:getAgentSkills
 value:getAgentStatusCounts
 value:getAgentWithTasks
+value:getAgentWorkingOnContextKey
 value:getAgentWorkingOnThread
 value:getAllAgentMailInboxMappings
 value:getAllAgents
@@ -321,8 +323,10 @@ value:getKv
 value:getLastReadAt
 value:getLastRunStart
 value:getLastSuccessfulRun
+value:getLatestActiveTaskByContextKey
 value:getLatestActiveTaskInThread
 value:getLatestContextVersion
+value:getLatestLeadTaskByContextKey
 value:getLatestLeadTaskInThread
 value:getLatestPageBySlug
 value:getLatestScriptRunStepTaskByContextKey
@@ -352,6 +356,7 @@ value:getPageVersion
 value:getPageVersions
 value:getPausedTasksForAgent
 value:getPendingApprovalVoteState
+value:getPendingChatRelayTasks
 value:getPendingEventWaitNames
 value:getPendingSlackRelayTasks
 value:getPendingSteeringForAgent
@@ -449,6 +454,7 @@ value:getWorkflowRunStepsByRunId
 value:getWorkflowVersion
 value:getWorkflowVersions
 value:getWorkflowsByScheduleId
+value:giveUpStaleChatRelays
 value:hasBudgetRefusalNotificationToday
 value:hasCapacity
 value:hasFirstCompletedTask
@@ -500,6 +506,9 @@ value:listUserFavorites
 value:listWorkflowRuns
 value:listWorkflowRunsPage
 value:listWorkflows
+value:markChatRelayAttempted
+value:markChatRelayDelivered
+value:markChatRelayGivenUp
 value:markFinalizedSlackRelaysDelivered
 value:markInboxMessageDelegated
 value:markInboxMessageRead
@@ -528,6 +537,7 @@ value:promoteDraftTask
 value:reassociateSessionLogs
 value:recordApprovalVotes
 value:recordBudgetRefusalNotification
+value:recordChatRelayError
 value:recordInlineScriptRun
 value:recordKeyAuthFailure
 value:recordKeyRateLimitWindows

package/src/tests/deferred-task-wake.test.ts

@@ -76,9 +76,9 @@ afterAll(async () => {
   await rm(dir, { recursive: true, force: true });
 });
 
-async function activeTask() {
+async function activeTask(owner = agentId) {
   const task = await createTaskExtended("work in progress", {
-    agentId,
+    agentId: owner,
     modelTier: "smart",
     priority: 70,
   });
@@ -90,6 +90,7 @@ async function defer(
   watchedId: string,
   event: TaskWakeEvent = "settled",
   extra: Record<string, unknown> = {},
+  caller = agentId,
 ) {
   return tool.handler(
     {
@@ -101,7 +102,7 @@ async function defer(
       checks: ["verify output"],
       ...extra,
     },
-    { sessionId: crypto.randomUUID(), requestInfo: { headers: { "x-agent-id": agentId } } },
+    { sessionId: crypto.randomUUID(), requestInfo: { headers: { "x-agent-id": caller } } },
   );
 }
 async function fixture(event: TaskWakeEvent = "settled") {
@@ -364,10 +365,57 @@ describe("defer-task wakeOn", () => {
     expect(await children(schedule.id)).toHaveLength(1);
   });
 
+  test("duplicate watcher admission is atomic, agent-scoped, and permits the fired chain to re-defer", async () => {
+    const producer = await activeTask();
+    const sibling = await activeTask();
+    const first = await activeTask();
+    const second = await activeTask();
+    const results = await Promise.all([
+      defer(first.id, producer.id, "settled", {
+        wakeOn: { event: "settled", taskIds: [producer.id, sibling.id] },
+      }),
+      defer(second.id, producer.id),
+    ]);
+    const accepted = results.find((result) => result.structuredContent.success)!;
+    const rejected = results.find((result) => !result.structuredContent.success)!;
+    expect(accepted).toBeDefined();
+    expect(rejected).toBeDefined();
+    expect(rejected.structuredContent.message).toContain(accepted.structuredContent.scheduleId!);
+    const rejectedTask = results[0] === rejected ? first : second;
+    expect((await getTaskById(rejectedTask.id))?.status).toBe("in_progress");
+    expect(
+      await getDbClient().query("SELECT id FROM scheduled_tasks WHERE parentTaskId = ?", [
+        rejectedTask.id,
+      ]),
+    ).toHaveLength(0);
+
+    const other = await createAgent({ name: "Independent watcher", isLead: false, status: "idle" });
+    const otherWatcher = await activeTask(other.id);
+    expect(
+      (await defer(otherWatcher.id, producer.id, "settled", {}, other.id)).structuredContent
+        .success,
+    ).toBe(true);
+    const dispatched = await dispatchDeferredTaskWait(
+      accepted.structuredContent.scheduleId!,
+      "ceiling",
+    );
+    expect(dispatched?.task).toBeDefined();
+    await startTask(dispatched!.task!.id);
+    expect((await defer(dispatched!.task!.id, producer.id)).structuredContent.success).toBe(true);
+  });
+
   test("two waiters follow a time-based deferral and fire once on the resume task's completion", async () => {
     await initDeferredTaskWaits();
     const { producer, schedule } = await fixture();
-    const second = await defer((await activeTask()).id, producer.id, "task.completed");
+    const secondAgent = await createAgent({ name: "Second waiter", isLead: false, status: "idle" });
+    const second = await defer(
+      (await activeTask(secondAgent.id)).id,
+      producer.id,
+      "task.completed",
+      {},
+      secondAgent.id,
+    );
+    expect(second.structuredContent.success).toBe(true);
     const secondSchedule = (await getScheduledTaskById(second.structuredContent.scheduleId!))!;
     const deferred = await defer(producer.id, producer.id, "settled", { wakeOn: undefined });
     expect(deferred.structuredContent.success).toBe(true);

package/src/tests/docs-index-footprint.test.js

@@ -78,7 +78,7 @@ describe("docs API index footprint", () => {
     expect(tasks).toContain('"path":"/api/task-templates","method":"get"');
   });
 
-  test("OpenAPI and generated pages keep all 423 operations", async () => {
+  test("OpenAPI and generated pages keep all 425 operations", async () => {
     const spec = await Bun.file(resolve(repoRoot, "openapi.json")).json();
     const operationKeys = [];
     const tags = new Set();
@@ -103,8 +103,8 @@ describe("docs API index footprint", () => {
     expect(spec.paths["/api/agents/{id}/runtime"]?.get).toBeDefined();
 
     const generatedKeys = await generatedOperationKeys();
-    expect(operationKeys).toHaveLength(423);
-    expect(generatedKeys).toHaveLength(423);
+    expect(operationKeys).toHaveLength(425);
+    expect(generatedKeys).toHaveLength(425);
     expect(new Set(generatedKeys)).toEqual(new Set(operationKeys));
   });
 

package/src/tests/dsh-adapter.test.ts

@@ -376,7 +376,7 @@ describe("dsh harness", () => {
     await rename(join(config.cwd, "dsh"), join(config.cwd, "npx"));
     config.env = { ...config.env, DSH_BINARY: "", PATH: config.cwd };
     await expect(new DshAdapter().createSession(config)).rejects.toThrow(
-      "dsh CLI not found. Install @deepseek-ai/dsh@0.2.1-alpha.2",
+      "dsh CLI not found. Install @deepseek-ai/dsh@0.2.1-alpha.4",
     );
     expect(await Bun.file(join(config.cwd, "invocation.json")).exists()).toBe(false);
   });

package/src/tests/enabled-capabilities.test.ts

@@ -0,0 +1,20 @@
+import { afterEach, expect, test } from "bun:test";
+import { ALL_CAPABILITIES, getEnabledCapabilities, hasCapability } from "../server";
+
+const originalCapabilities = process.env.CAPABILITIES;
+
+afterEach(() => {
+  if (originalCapabilities === undefined) delete process.env.CAPABILITIES;
+  else process.env.CAPABILITIES = originalCapabilities;
+});
+
+// `services` was a real capability until the PM2 service registry was removed.
+// A deployment that still lists it must keep registering agents: the register
+// response validates enabledCapabilities against ALL_CAPABILITIES.
+test("enabledCapabilities drops retired and free-form names", () => {
+  process.env.CAPABILITIES = "core,services,artifacts,pages";
+
+  expect(ALL_CAPABILITIES as readonly string[]).not.toContain("services");
+  expect(getEnabledCapabilities()).toEqual(["core", "pages"]);
+  expect(hasCapability("pages")).toBe(true);
+});

package/src/tests/entrypoint-api-readiness.test.ts

@@ -221,28 +221,34 @@ describe("wait_for_api_ready: immediate success", () => {
 
 describe("wait_for_api_ready: transient failure then success", () => {
   test("retries roughly once per second until the server recovers", async () => {
-    let requestCount = 0;
+    // A per-test path prefix: an ephemeral port can be reused from another test
+    // process whose poller still hits /health, and those stray requests used
+    // to count as retries (3 requests in 1033 ms on CI).
+    const prefix = `/${crypto.randomUUID()}`;
+    const requestTimes: number[] = [];
     server = Bun.serve({
       port: 0,
       hostname: "127.0.0.1",
       fetch(req) {
         const url = new URL(req.url);
-        if (url.pathname !== "/health") return new Response("not found", { status: 404 });
-        requestCount += 1;
-        if (requestCount < 3) return new Response("unavailable", { status: 503 });
+        if (url.pathname !== `${prefix}/health`) return new Response("not found", { status: 404 });
+        requestTimes.push(performance.now());
+        if (requestTimes.length < 3) return new Response("unavailable", { status: 503 });
         return new Response("ok", { status: 200 });
       },
     });
 
-    const result = await runWaitForApiReady(server.url.toString(), {
+    const result = await runWaitForApiReady(`${server.url.origin}${prefix}/`, {
       WORKER_API_READY_TIMEOUT_SECONDS: "10",
     });
 
     expect(result.exitCode).toBe(0);
-    expect(requestCount).toBeGreaterThanOrEqual(3);
+    expect(requestTimes).toHaveLength(3);
     expect(result.stdout).toContain("API ready at");
-    // Two ~1s retries before success — bounded, not instant, not stalled.
-    expect(result.durationMs).toBeGreaterThanOrEqual(1500);
+    // Each retry waits out `sleep 1` after the previous response, so the
+    // server-side gap cannot shrink under load: paced, not a hot loop.
+    expect(requestTimes[1]! - requestTimes[0]!).toBeGreaterThanOrEqual(900);
+    expect(requestTimes[2]! - requestTimes[1]!).toBeGreaterThanOrEqual(900);
     expect(result.durationMs).toBeLessThan(15000);
   }, 20000);
 });

package/src/tests/entrypoint-config-env-export.test.ts

@@ -93,7 +93,10 @@ function extractExportFilter(lineMarker: string): string {
   const line = script.split("\n").find((l) => l.includes(lineMarker) && l.includes("jq -r '"));
   if (!line) throw new Error(`Could not locate the jq line containing ${lineMarker}`);
   const start = line.indexOf("jq -r '") + "jq -r '".length;
-  const end = line.indexOf("' /tmp/swarm_config.json", start);
+  // Inline programs read /tmp/swarm_config.json; the swarm_config_env_lines
+  // function reads its "$1" argument.
+  const ends = ["' /tmp/swarm_config.json", '\' "$1"'].map((tail) => line.indexOf(tail, start));
+  const end = ends.find((index) => index !== -1) ?? -1;
   if (end === -1) throw new Error(`Could not locate the end of the jq program for ${lineMarker}`);
   return line.slice(start, end);
 }
@@ -127,7 +130,7 @@ describe("entrypoint config env export: real jq filter", () => {
   test(
     "never exports codex_oauth or codex_oauth_<n>, nor the runner-resolved keys",
     async () => {
-      const lines = await runJq(extractExportFilter("> /tmp/swarm_config.env"), configs);
+      const lines = await runJq(extractExportFilter("(.value | @sh)"), configs);
       const keys = lines.map((l) => l.slice(0, l.indexOf("=")));
       expect(keys).toEqual(["NORMAL", "codex_oauth_extra"]);
       expect(lines.join("\n")).not.toContain("rt.secret");

package/src/tests/entrypoint-export-to-env.test.ts

@@ -0,0 +1,78 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CHILD_PROCESS_TEST_BUDGET_MS, expectChildOk, runChild } from "./test-proc";
+
+/**
+ * Runs the real swarm_config_env block from docker-entrypoint.sh (extracted
+ * between its BEGIN/END markers) against a /api/config/resolved fixture, the
+ * same way the entrypoint sources it, and reads the resulting env.
+ */
+
+const entrypoint = readFileSync("docker-entrypoint.sh", "utf8");
+const block = entrypoint.slice(
+  entrypoint.indexOf("# BEGIN swarm_config_env"),
+  entrypoint.indexOf("# END swarm_config_env"),
+);
+
+let dir = "";
+
+beforeAll(() => {
+  dir = mkdtempSync(join(tmpdir(), "entrypoint-export-"));
+});
+afterAll(() => {
+  rmSync(dir, { recursive: true, force: true });
+});
+
+async function exportedEnv(configs: unknown[], containerEnv: Record<string, string> = {}) {
+  const fixture = join(dir, `${crypto.randomUUID()}.json`);
+  writeFileSync(fixture, JSON.stringify({ configs }));
+  const script = `${block}
+swarm_config_env_lines "$1" > "$1.env"
+set -a; . "$1.env"; set +a
+for withheld_key in $(swarm_config_withheld_keys "$1"); do unset "$withheld_key"; done
+env
+`;
+  const result = await runChild(["bash", "-c", script, "bash", fixture], {
+    env: { PATH: process.env.PATH ?? "/usr/bin:/bin", ...containerEnv },
+    timeoutMs: CHILD_PROCESS_TEST_BUDGET_MS,
+  });
+  expectChildOk(result, "entrypoint export block");
+  return Object.fromEntries(
+    result.stdout
+      .split("\n")
+      .filter((line) => line.includes("="))
+      .map((line) => [line.slice(0, line.indexOf("=")), line.slice(line.indexOf("=") + 1)]),
+  );
+}
+
+describe("docker-entrypoint.sh swarm_config_env", () => {
+  test("markers are present", () => {
+    expect(block).toContain("swarm_config_env_lines()");
+    expect(block).toContain("swarm_config_withheld_keys()");
+  });
+
+  test("exports exportToEnv rows and drops withheld ones, including container copies", async () => {
+    const env = await exportedEnv(
+      [
+        { key: "GITHUB_TOKEN", value: "row-github", isSecret: true, exportToEnv: true },
+        { key: "VERCEL_TOKEN", value: "row-vercel", isSecret: true, exportToEnv: false },
+        { key: "QUOTED", value: "it's $HOME", isSecret: false, exportToEnv: true },
+        // A pre-215 API sends no flag: the row keeps exporting.
+        { key: "LEGACY", value: "row-legacy", isSecret: true },
+        { key: "CF-Access-Client-Id", value: "x", isSecret: true, exportToEnv: true },
+        { key: "codex_oauth_1", value: "x", isSecret: true, exportToEnv: true },
+        { key: "HARNESS_PROVIDER", value: "pi", isSecret: false, exportToEnv: true },
+      ],
+      { VERCEL_TOKEN: "container-vercel" },
+    );
+    expect(env.GITHUB_TOKEN).toBe("row-github");
+    expect(env.QUOTED).toBe("it's $HOME");
+    expect(env.LEGACY).toBe("row-legacy");
+    expect(env.VERCEL_TOKEN).toBeUndefined();
+    expect(env.codex_oauth_1).toBeUndefined();
+    expect(env.HARNESS_PROVIDER).toBeUndefined();
+    expect(Object.values(env)).not.toContain("row-vercel");
+  });
+});

package/src/tests/explicit-model-validation.test.ts

@@ -542,7 +542,12 @@ describe("harness compatibility at every create entry point", () => {
   });
 
   test("send-task: the parent auto-route target is judged", async () => {
-    const parent = await createTaskExtended("codex parent", { agentId: codexId, source: "mcp" });
+    // The worker created the parent, so it may continue it (task.parent.attach).
+    const parent = await createTaskExtended("codex parent", {
+      agentId: codexId,
+      creatorAgentId: workerId,
+      source: "mcp",
+    });
     const refused = await sendTaskHandler(ownerCtx({ agentId: workerId }), {
       task: "child of a codex task",
       parentTaskId: parent.id,
@@ -662,3 +667,102 @@ describe("harness compatibility at every create entry point", () => {
     expect(String(res.body.error)).toContain("does not run on the codex harness");
   });
 });
+
+describe("nan and helmcode catalog models", () => {
+  let piId = "";
+  let opencodeId = "";
+
+  beforeAll(async () => {
+    piId = (
+      await createAgent({
+        name: "validation-pi",
+        isLead: false,
+        status: "idle",
+        harnessProvider: "pi",
+      })
+    ).id;
+    opencodeId = (
+      await createAgent({
+        name: "validation-opencode",
+        isLead: false,
+        status: "idle",
+        harnessProvider: "opencode",
+      })
+    ).id;
+  });
+
+  const ids = [
+    "nan/glm5.3-flash",
+    "nan/glm5.3",
+    "nan/mimo-v2.6-flash",
+    "helmcode/glm5.3",
+    "helmcode/qwen3.6",
+    "helmcode/deepseek-v4-flash",
+  ];
+
+  test("pi and opencode accept the ids without allowCustomModel", async () => {
+    for (const harnessProvider of ["pi", "opencode"]) {
+      for (const model of ids) {
+        expect(await explicitModelError({ model, harnessProvider })).toBeNull();
+      }
+    }
+  });
+
+  test("claude and codex reject them with the harness mismatch, even with allowCustomModel", async () => {
+    for (const harnessProvider of ["claude", "codex"]) {
+      for (const allowCustomModel of [false, true]) {
+        for (const model of ["nan/glm5.3-flash", "helmcode/glm5.3"]) {
+          expect(await explicitModelError({ model, harnessProvider, allowCustomModel })).toContain(
+            `does not run on the ${harnessProvider} harness`,
+          );
+        }
+      }
+    }
+  });
+
+  test("a misspelt helmcode id is unknown", async () => {
+    expect(
+      await explicitModelError({ model: "helmcode/glm-5.3", harnessProvider: "pi" }),
+    ).toContain("Unknown model");
+  });
+
+  test("send-task: pi and opencode agents take the ids, a claude agent gets the mismatch", async () => {
+    const sender = ownerCtx({ agentId: leadId });
+    const args = {
+      task: "nan route",
+      offerMode: false,
+      allowDuplicate: false,
+      routingReason: "human_pinned" as const,
+      routingNote: "pinned to check the nan/helmcode catalog ids",
+    };
+    for (const agentId of [piId, opencodeId]) {
+      for (const model of ["nan/mimo-v2.6-flash", "helmcode/glm5.3"]) {
+        const accepted = await sendTaskHandler(sender, {
+          ...args,
+          task: `nan route ${model} to ${agentId}`,
+          agentId,
+          model,
+        });
+        expect({ ok: accepted.ok, message: accepted.message }).toEqual({
+          ok: true,
+          message: expect.any(String),
+        });
+      }
+    }
+    const refused = await sendTaskHandler(sender, {
+      ...args,
+      agentId: workerId,
+      model: "helmcode/glm5.3",
+    });
+    expect(refused.ok).toBe(false);
+    expect(refused.message).toContain("does not run on the claude harness");
+  });
+
+  test("PATCH /api/agents/:id/runtime stores a helmcode model on a pi agent", async () => {
+    const res = await api("PATCH", `/api/agents/${piId}/runtime`, {
+      harness_provider: "pi",
+      model: "helmcode/glm5.3",
+    });
+    expect(res.status).toBe(200);
+  });
+});

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

@@ -0,0 +1,154 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { closeDb, createAgent, getDbClient, getKv, initDb } from "../be/db";
+import { installExtension, listExtensionRuns } from "../be/extensions/db";
+import { enableExtension, stopExtensionRuntime } from "../extensions/lifecycle";
+import { chatSdkContextKey } from "../tasks/context-key";
+import type { Agent } from "../types";
+import {
+  flushChatBuffers,
+  postTelegramUpdate,
+  startTelegramHarness,
+  type TelegramHarness,
+  telegramUpdate,
+} from "./chat-sdk-harness";
+import { loadBundleFixture } from "./fixtures/extensions/load";
+
+const TEST_DB_PATH = "./test-extensions-example-route-chat-channel.sqlite";
+
+let harness: TelegramHarness;
+let lead: Agent;
+let worker: Agent;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+}
+
+async function chatTask(chatId: number) {
+  return getDbClient().get<{ agentId: string | null }>(
+    "SELECT agentId FROM agent_tasks WHERE source = 'chat' AND contextKey = ? ORDER BY createdAt DESC LIMIT 1",
+    [chatSdkContextKey(`telegram:${chatId}`)],
+  );
+}
+
+/** A private-chat message, flushed out of the thread buffer. */
+async function sendDm(chatId: number, text: string): Promise<void> {
+  await postTelegramUpdate(telegramUpdate({ id: chatId, type: "private" }, text));
+  await flushChatBuffers();
+}
+
+async function installRouteFixture(channelId: string, agentId: string) {
+  const bundle = await loadBundleFixture("route-chat-channel-to-agent");
+  const { extension } = await installExtension({
+    ...bundle,
+    config: { adapter: "telegram", channelId, agentId },
+  });
+  return { extension, enabled: await enableExtension(extension.id) };
+}
+
+describe("extension Chat SDK channel routing", () => {
+  beforeAll(async () => {
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+    lead = await createAgent({
+      id: crypto.randomUUID(),
+      name: "chat-route-lead",
+      isLead: true,
+      status: "idle",
+    });
+    worker = await createAgent({
+      id: crypto.randomUUID(),
+      name: "chat-route-worker",
+      isLead: false,
+      status: "idle",
+    });
+    harness = await startTelegramHarness();
+  });
+
+  afterAll(async () => {
+    await harness.stop();
+    await stopExtensionRuntime();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    await stopExtensionRuntime();
+    await getDbClient().run("DELETE FROM extensions");
+  });
+
+  test("routes the configured channel to its agent and leaves other channels with the lead", async () => {
+    const { extension } = await installRouteFixture("telegram:3001", worker.id);
+
+    await sendDm(3001, "route this to the worker");
+    expect(await chatTask(3001)).toEqual({ agentId: worker.id });
+    expect(
+      (await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "pre.chat.route" && run.action === "modify",
+      ),
+    ).toBe(true);
+
+    await sendDm(3002, "use the normal route");
+    expect(await chatTask(3002)).toEqual({ agentId: lead.id });
+  });
+
+  test("a block creates no task", async () => {
+    const bundle = await loadBundleFixture("minimal");
+    const { extension } = await installExtension({
+      manifest: { ...bundle.manifest, name: "block-chat-route", description: "blocks chat" },
+      files: {
+        "hooks.ts": `import { block, type SwarmExtension } from "swarm-extension";
+const extension: SwarmExtension = (api) => {
+  api.on("pre.chat.route", () => block("chat is muted"));
+};
+export default extension;
+`,
+      },
+    });
+    await enableExtension(extension.id);
+
+    await sendDm(3003, "this must not become a task");
+    expect(await chatTask(3003)).toBeNull();
+    const runs = await listExtensionRuns(extension.id);
+    expect(runs.some((run) => run.event === "pre.chat.route" && run.action === "block")).toBe(true);
+    // Ids only in the run subject: never the message text.
+    expect(runs.every((run) => !run.subject?.includes("must not"))).toBe(true);
+  });
+
+  test("falls back to the built-in router when the extension names an unknown agent", async () => {
+    await installRouteFixture("telegram:3004", "missing-agent");
+    const warn = spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      await sendDm(3004, "use the fallback");
+      expect(await chatTask(3004)).toEqual({ agentId: lead.id });
+      expect(warn).toHaveBeenCalledWith(
+        "[chat-sdk] Extension selected an unknown agent missing-agent. Using the router.",
+      );
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  test("post.chat.message carries the inbound sender", async () => {
+    const { extension, enabled } = await installRouteFixture("telegram:3005", worker.id);
+    await sendDm(3005, "record this message");
+
+    const deadline = Date.now() + 5_000;
+    while (
+      !(await listExtensionRuns(extension.id)).some(
+        (run) => run.event === "post.chat.message" && run.action === "continue",
+      ) &&
+      Date.now() < deadline
+    ) {
+      await Bun.sleep(20);
+    }
+    expect(
+      await getKv(
+        `task:agent:${enabled.agentId}`,
+        "ext:route-chat-channel-to-agent:chat:telegram:3005",
+      ),
+    ).toMatchObject({ value: "777001" });
+  });
+});

package/src/tests/extensions-post-bridge.test.ts

@@ -33,6 +33,7 @@ const NEW_EVENTS = [
   "post.task.budgetRefused",
   "post.email.received",
   "post.kapso.message",
+  "post.chat.message",
   "post.vcs.event",
 ] as const satisfies readonly (keyof SwarmEventMap)[];
 
@@ -358,6 +359,56 @@ describe("extension post bridge: new events", () => {
     });
   });
 
+  describe("post.chat.message", () => {
+    test("chat.message.received dispatches an inbound event", async () => {
+      await registerCapture("capture");
+      workflowEventBus.emit("chat.message.received", {
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        userId: "555001",
+        text: "hello swarm",
+        messageId: "555001:11",
+      });
+      await waitForEvents(1);
+      expect(received).toEqual([
+        {
+          extension: "capture",
+          event: "post.chat.message",
+          payload: {
+            adapter: "telegram",
+            channelId: "telegram:555001",
+            threadId: "telegram:555001",
+            userId: "555001",
+            text: "hello swarm",
+            direction: "inbound",
+            messageId: "555001:11",
+          },
+        },
+      ]);
+    });
+
+    test("chat.message.sent dispatches an outbound event", async () => {
+      await registerCapture("capture");
+      workflowEventBus.emit("chat.message.sent", {
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        text: "done",
+        taskId: "task-1",
+      });
+      await waitForEvents(1);
+      expect(received[0]?.payload).toEqual({
+        adapter: "telegram",
+        channelId: "telegram:555001",
+        threadId: "telegram:555001",
+        text: "done",
+        direction: "outbound",
+        taskId: "task-1",
+      });
+    });
+  });
+
   describe("post.kapso.message", () => {
     test("a bus emit dispatches the typed payload", async () => {
       await registerCapture("capture");