@desplega.ai/agent-swarm 1.173.0 → 2.1.0

package/src/tests/workflow-swarm-script.test.ts

@@ -9,6 +9,7 @@ import {
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
   initDb,
+  upsertSwarmConfig,
 } from "../be/db";
 import { upsertScriptConnection } from "../be/script-connections";
 import { getScript, upsertScriptByName } from "../be/scripts/db";
@@ -31,6 +32,7 @@ import {
 } from "../workflows/executors/swarm-script";
 import { interpolate } from "../workflows/template";
 import { SKIP_SANDBOX_SPAWN_TESTS } from "./sandbox-spawn-test-helpers";
+import { CHILD_PROCESS_TEST_BUDGET_MS } from "./test-proc";
 
 const skip = test.skipIf(SKIP_SANDBOX_SPAWN_TESTS);
 
@@ -370,6 +372,42 @@ describe("SwarmScriptExecutor", () => {
     expect(result.output?.result).toEqual({ apiKeys: ["workflowVendor"] });
   });
 
+  skip(
+    "swarm-script node reads swarm config through ctx.swarm.config.get",
+    async () => {
+      await upsertSwarmConfig({ scope: "global", key: "WORKFLOW_CFG_PLAIN", value: "node-value" });
+      await saveScript(
+        "ctx-config-get",
+        `export default async (_args, ctx) => {
+        const value = ctx.swarm.config.get("WORKFLOW_CFG_PLAIN");
+        return {
+          value: value === undefined ? null : ctx.stdlib.Redacted.value(value),
+          missing: ctx.swarm.config.get("WORKFLOW_CFG_NOT_SET") ?? "fallback",
+        };
+      };`,
+      );
+
+      const executor = new SwarmScriptExecutor(deps);
+      const wf = await makeWorkflow({ nodes: [] });
+      const result = await executor.run({
+        config: { scriptName: "ctx-config-get" },
+        context: {},
+        meta: {
+          runId: crypto.randomUUID(),
+          stepId: crypto.randomUUID(),
+          nodeId: "script",
+          workflowId: wf.id,
+          dryRun: false,
+        },
+      });
+      await getDbClient().run("DELETE FROM swarm_config WHERE key = 'WORKFLOW_CFG_PLAIN'");
+
+      expect(result.status).toBe("success");
+      expect(result.output?.result).toEqual({ value: "node-value", missing: "fallback" });
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
+
   skip("pinHash correctly resolves to a historic script_versions row", async () => {
     const first = await saveScript("versioned", `export default async () => ({ version: "old" });`);
     await saveScript("versioned", `export default async () => ({ version: "new" });`);

package/src/tests/workflow-wait-filter.test.ts

@@ -154,12 +154,14 @@ describe("matchesFilter — sandbox penetration (must all return false, never th
   });
 
   test("DoS: pathological regex terminates within timeout", async () => {
-    const filter = "(p) => /^(a+)+$/.test('a'.repeat(30) + 'X')";
+    // Still exponential backtracking, but 24 characters finish in ~0.1 s. The
+    // 50 ms timer cannot pre-empt a synchronous regex, so the elapsed time is
+    // the engine's own: 30 characters took 2058 ms on a loaded CI runner and
+    // failed the bound below without the matcher doing anything wrong.
+    const filter = "(p) => /^(a+)+$/.test('a'.repeat(24) + 'X')";
     const t0 = Date.now();
     const result = await matchesFilter({}, filter);
     const elapsed = Date.now() - t0;
-    // The regex would eventually return false on its own, but if it stalls
-    // the timeout catches it.
     expect(typeof result).toBe("boolean");
     expect(elapsed).toBeLessThan(2000);
   });

package/src/tools/chat-access.ts

@@ -0,0 +1,41 @@
+import { getAgentById, getAgentCurrentTask, getTaskById } from "@/be/db";
+import { can } from "@/rbac";
+import { chatThreadOfContextKey } from "@/tasks/context-key";
+import type { RequestInfo } from "@/tools/utils";
+
+/** Chat SDK verbs; the legacy policy grants them to the lead only. */
+export type ChatVerb = "integration.chat.post" | "integration.chat.read" | "integration.chat.dm";
+
+/**
+ * The Chat SDK thread of the task the caller works on: the task named by the
+ * X-Source-Task-ID header, else the agent's current task. Null when the caller
+ * neither owns nor created that task, or when the task did not come from a
+ * chat thread.
+ */
+export async function callerChatThread(
+  requestInfo: RequestInfo,
+): Promise<{ adapter: string; threadId: string } | null> {
+  if (!requestInfo.agentId) return null;
+  const task = requestInfo.sourceTaskId
+    ? await getTaskById(requestInfo.sourceTaskId)
+    : await getAgentCurrentTask(requestInfo.agentId);
+  if (!task) return null;
+  // Creator is safe: a non-lead agent can only create a chat-bound task under a parent it owns or created.
+  if (task.agentId !== requestInfo.agentId && task.creatorAgentId !== requestInfo.agentId) {
+    return null;
+  }
+  return chatThreadOfContextKey(task.contextKey);
+}
+
+/** RBAC decision for a chat verb, with the caller's lead flag read from the database. */
+export async function canUseChatVerb(requestInfo: RequestInfo, verb: ChatVerb): Promise<boolean> {
+  if (!requestInfo.agentId) return false;
+  const agent = await getAgentById(requestInfo.agentId);
+  if (!agent) return false;
+  return can({
+    principal: { kind: "agent", agentId: agent.id, isLead: agent.isLead },
+    verb,
+    resource: { kind: "none" },
+    source: "mcp",
+  }).allow;
+}

package/src/tools/chat-open-dm.ts

@@ -0,0 +1,59 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { CHAT_SDK_ADAPTER_NAMES } from "@/integrations/chat-sdk/config";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import { getChatInstance } from "@/integrations/chat-sdk/runtime";
+import { assertTrustedTeamsServiceUrl } from "@/integrations/chat-sdk/teams-origin";
+import { canUseChatVerb } from "@/tools/chat-access";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+export const registerChatOpenDmTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "chat-open-dm",
+    {
+      title: "Open a direct message on a chat platform",
+      description:
+        "Lead only. Open (or find) the direct-message thread with a user on a Chat SDK adapter and return its threadId. Post to it with chat-post. The userId is the platform user id from a chat message (Telegram numeric id, Slack U..., Discord snowflake, Teams 29:...). Telegram bots can message only users who started a chat with the bot.",
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        userId: z.string().min(1).describe("Platform user id."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        adapter: z.string().optional(),
+        threadId: z.string().optional(),
+      }),
+    },
+    async ({ adapter, userId }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      if (!(await canUseChatVerb(requestInfo, "integration.chat.dm"))) {
+        return toolErr("Permission denied. Only the lead can open a direct message.", { data });
+      }
+      const chat = getChatInstance(adapter);
+      if (!chat) return toolErr(`Chat SDK adapter '${adapter}' is not running.`, { data });
+      // Call the adapter directly: Chat.openDM guesses the adapter from the
+      // user id format, and numeric ids are ambiguous.
+      const platform = chat.getAdapter(adapter);
+      if (!platform?.openDM) {
+        return toolErr(`The ${adapter} adapter does not support direct messages.`, { data });
+      }
+      try {
+        if (adapter === "teams") {
+          // Teams opens the DM at the service URL cached from the user's last
+          // activity (adapter state key). The webhook route refuses untrusted
+          // ones; check again before the bot token goes out.
+          const cached = await chat.getState().get<string>(`teams:serviceUrl:${userId}`);
+          if (cached) assertTrustedTeamsServiceUrl(cached);
+        }
+        const threadId = await platform.openDM(userId);
+        return toolOk(`Direct-message thread with ${userId} on ${adapter}: ${threadId}.`, {
+          data: { ...data, adapter, threadId },
+        });
+      } catch (error) {
+        const message = errorMessage(error);
+        return toolErr(`Could not open a direct message: ${message}`, { data });
+      }
+    },
+  );
+};

package/src/tools/chat-post.ts

@@ -0,0 +1,74 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { CHAT_SDK_ADAPTER_NAMES } from "@/integrations/chat-sdk/config";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import { adapterOfChatId, postChatMessage } from "@/integrations/chat-sdk/outbound";
+import { canUseChatVerb } from "@/tools/chat-access";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+export const registerChatPostTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "chat-post",
+    {
+      title: "Post to a chat thread or channel",
+      description:
+        "Lead only. Post a message to any Chat SDK thread or channel (Telegram, Slack, Discord, Teams), outside the thread of your current task. Give threadId to reply in a thread, or channelId to start a new message in a channel. Ids carry the adapter prefix, such as telegram:12345. To answer the user of your current chat task, use chat-reply instead.",
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        threadId: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Full SDK thread id, such as telegram:12345 or slack:C123:1700000000.000100."),
+        channelId: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Full SDK channel id, such as slack:C123. Ignored when threadId is set."),
+        text: z.string().min(1).max(20_000).describe("Markdown text to post."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        messageId: z.string().optional(),
+        adapter: z.string().optional(),
+        threadId: z.string().optional(),
+        channelId: z.string().optional(),
+      }),
+    },
+    async ({ adapter, threadId, channelId, text }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      const target = threadId ?? channelId;
+      if (!target) return toolErr("Give a threadId or a channelId.", { data });
+      if (adapterOfChatId(target) !== adapter) {
+        return toolErr(`The id ${target} does not belong to the ${adapter} adapter.`, { data });
+      }
+      if (!(await canUseChatVerb(requestInfo, "integration.chat.post"))) {
+        return toolErr(
+          "Permission denied. Only the lead can post outside the thread of its task. Use chat-reply for the thread of your current task.",
+          { data },
+        );
+      }
+      try {
+        const sent = await postChatMessage({
+          adapter,
+          ...(threadId ? { threadId } : { channelId }),
+          text,
+          taskId: requestInfo.sourceTaskId,
+        });
+        return toolOk(`Posted to ${adapter} ${threadId ? "thread" : "channel"} ${target}.`, {
+          data: {
+            ...data,
+            messageId: sent.messageIds.at(-1),
+            adapter: sent.adapter,
+            threadId: sent.threadId,
+            channelId: sent.channelId,
+          },
+        });
+      } catch (error) {
+        const message = errorMessage(error);
+        return toolErr(`Could not post: ${message}`, { data });
+      }
+    },
+  );
+};

package/src/tools/chat-read-thread.ts

@@ -0,0 +1,100 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import { adapterOfChatId } from "@/integrations/chat-sdk/outbound";
+import { getChatInstance } from "@/integrations/chat-sdk/runtime";
+import { assertTrustedChatTarget } from "@/integrations/chat-sdk/teams-origin";
+import { callerChatThread, canUseChatVerb } from "@/tools/chat-access";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { scrubSecrets } from "@/utils/secret-scrubber";
+
+const DEFAULT_LIMIT = 30;
+
+export const registerChatReadThreadTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "chat-read-thread",
+    {
+      title: "Read recent messages of a chat thread",
+      description:
+        "Read the most recent messages of a Chat SDK thread, oldest first. Every agent can read the thread of its current task. Other threads are lead only. Limits per platform: Telegram has no history API, so you get the history the SDK stored in the swarm database, capped at 100 messages and 7 days. Teams needs the Chat.Read.* Graph permission. Slack and Discord return platform history.",
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      inputSchema: z.object({
+        threadId: z
+          .string()
+          .min(1)
+          .describe("Full SDK thread id with the adapter prefix, such as telegram:12345."),
+        limit: z
+          .number()
+          .int()
+          .min(1)
+          .max(100)
+          .optional()
+          .describe(`Number of messages to return (default ${DEFAULT_LIMIT}).`),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        threadId: z.string().optional(),
+        messages: z
+          .array(
+            z.looseObject({
+              id: z.string().optional(),
+              userId: z.string().optional(),
+              userName: z.string().optional(),
+              isBot: z.boolean().optional(),
+              sentAt: z.string().optional(),
+              text: z.string().optional(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ threadId, limit }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      // A worker reads only the thread its task came from; any other thread
+      // needs the lead verb, as slack-read does for direct channel reads.
+      const own = await callerChatThread(requestInfo);
+      if (own?.threadId !== threadId) {
+        if (!(await canUseChatVerb(requestInfo, "integration.chat.read"))) {
+          return toolErr(
+            own
+              ? `Permission denied. You can read only the thread of your current task, ${own.threadId}. Other threads need lead privileges.`
+              : "Permission denied. Reading a chat thread that is not the thread of your current task needs lead privileges.",
+            { data },
+          );
+        }
+      }
+      const adapter = adapterOfChatId(threadId);
+      const chat = getChatInstance(adapter);
+      if (!chat) return toolErr(`Chat SDK adapter '${adapter}' is not running.`, { data });
+      try {
+        // Teams reads history with the bot token from the service URL in the id.
+        assertTrustedChatTarget(threadId);
+        const page = await chat.history.thread.list(threadId, {
+          limit: limit ?? DEFAULT_LIMIT,
+          direction: "backward",
+        });
+        const messages = page.messages.map((message) => ({
+          id: message.id,
+          userId: message.author.userId,
+          userName: message.author.userName || message.author.fullName || undefined,
+          isBot: message.author.isBot === true,
+          sentAt: message.metadata?.dateSent?.toISOString(),
+          text: scrubSecrets(message.text ?? ""),
+        }));
+        const rendered = messages
+          .map(
+            (m) =>
+              `[${m.sentAt ?? "?"}] ${m.userName ?? m.userId}${m.isBot ? " (bot)" : ""}: ${m.text}`,
+          )
+          .join("\n");
+        return toolOk(`${messages.length} message(s) from ${threadId}.`, {
+          details: rendered || undefined,
+          data: { ...data, threadId, messages },
+        });
+      } catch (error) {
+        const message = errorMessage(error);
+        return toolErr(`Could not read the thread: ${message}`, { data });
+      }
+    },
+  );
+};

package/src/tools/chat-reply.ts

@@ -0,0 +1,75 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentCurrentTask, getTaskById } from "@/be/db";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import { ChatAdapterUnavailableError, postChatMessage } from "@/integrations/chat-sdk/outbound";
+import { chatThreadOfContextKey } from "@/tasks/context-key";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+export const registerChatReplyTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "chat-reply",
+    {
+      title: "Reply in the chat thread of this task",
+      description:
+        "Post a message to the Telegram, Slack, Discord or Teams thread your current task came from. Works only on a task whose contextKey starts with task:chat-sdk:. The task's final output is posted to the thread automatically when the task ends, so use this only for a question to the user or a short progress note on long work. Markdown is supported; long text is split into several messages.",
+      annotations: { openWorldHint: true },
+      inputSchema: z.object({
+        text: z.string().min(1).max(20_000).describe("Markdown text to post to the thread."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        messageId: z.string().optional(),
+        adapter: z.string().optional(),
+        threadId: z.string().optional(),
+      }),
+    },
+    async ({ text }, requestInfo) => {
+      if (!requestInfo.agentId) return toolErr("Agent ID not found.");
+      const data = { yourAgentId: requestInfo.agentId };
+
+      // The header names the task this session works on; without it, the
+      // agent's current in-progress task.
+      const task = requestInfo.sourceTaskId
+        ? await getTaskById(requestInfo.sourceTaskId)
+        : await getAgentCurrentTask(requestInfo.agentId);
+      if (!task) return toolErr("No current task found for chat-reply.", { data });
+      // Creator is safe: a non-lead agent can only create a chat-bound task under a parent it owns or created.
+      if (task.agentId !== requestInfo.agentId && task.creatorAgentId !== requestInfo.agentId) {
+        return toolErr("You don't have context for this task.", { data });
+      }
+      const thread = chatThreadOfContextKey(task.contextKey);
+      if (!thread) {
+        return toolErr(
+          `Task ${task.id} did not come from a chat thread (no task:chat-sdk contextKey). Use the tool of the channel the task came from.`,
+          { data },
+        );
+      }
+
+      try {
+        const sent = await postChatMessage({
+          adapter: thread.adapter,
+          threadId: thread.threadId,
+          text,
+          taskId: task.id,
+        });
+        return toolOk(`Posted to ${thread.adapter} thread ${sent.threadId}.`, {
+          data: {
+            ...data,
+            messageId: sent.messageIds.at(-1),
+            adapter: sent.adapter,
+            threadId: sent.threadId,
+          },
+        });
+      } catch (error) {
+        const message = errorMessage(error);
+        return toolErr(
+          error instanceof ChatAdapterUnavailableError
+            ? `${message}. The final task output is still posted when the adapter is back.`
+            : `Could not post to the chat thread: ${message}`,
+          { data },
+        );
+      }
+    },
+  );
+};

package/src/tools/create-page.ts

@@ -21,7 +21,8 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
-import { createPage, getPage, getPageBySlug, getPageVersions, updatePage } from "@/be/db";
+import { createPage, getPage, getPageBySlug, updatePage } from "@/be/db";
+import { getPageEditCounter } from "@/be/db/page-versions";
 import { snapshotPage } from "@/pages/version";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { AssetKeySchema, PageAuthModeSchema, PageContentTypeSchema } from "@/types";
@@ -45,17 +46,6 @@ function getAppBaseUrl(): string {
   return getAppUrl();
 }
 
-/**
- * Edit counter for a page — `MAX(page_versions.version) + 1`. Returned to
- * the agent as `version` so they have a monotonic "this page has been
- * edited N times" signal. Mirrors the value returned by
- * `PUT /api/pages/:id` (see src/http/pages.ts:pageEditCounter).
- */
-async function pageEditCounter(pageId: string): Promise<number> {
-  const versions = await getPageVersions(pageId);
-  return versions.length > 0 ? versions[0]!.version + 1 : 1;
-}
-
 export const registerCreatePageTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "create_page",
@@ -217,7 +207,7 @@ export const registerCreatePageTool = (server: McpServer) => {
 
       const apiUrl = `${getApiBaseUrl()}/p/${id}`;
       const appUrl = `${getAppBaseUrl()}/pages/${id}`;
-      const version = await pageEditCounter(id);
+      const version = await getPageEditCounter(id);
 
       return toolOk(`Page "${input.title}" saved (slug=${finalSlug}, version=${version}).`, {
         details: `API: ${apiUrl}\n  App: ${appUrl}`,

package/src/tools/model-catalog/index.ts

@@ -1,3 +1,4 @@
+import { openAICompatibleProviderIds } from "@desplega/model-catalog";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getAgentById } from "@/be/db";
@@ -86,7 +87,7 @@ export const registerModelCatalogOverlayUpsertTool = (server: McpServer) => {
           .string()
           .min(1)
           .describe(
-            "models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode.",
+            `models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode, ${openAICompatibleProviderIds().join(", ")}.`,
           ),
         modelId: z
           .string()

package/src/tools/model-profiles/list-model-profiles.ts

@@ -0,0 +1,54 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { listModelProfiles } from "@/be/db/model-profiles";
+import { createToolRegistrar, swarmToolOutputSchema, toolOk } from "@/tools/utils";
+import { ProviderNameSchema } from "@/types";
+
+export const registerListModelProfilesTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "list-model-profiles",
+    {
+      title: "List Model Profiles",
+      description:
+        "List model profiles: named harness + model + effort combinations. Pass a profile's name as `profile` on send-task to run that task on it, or set it as an agent's default through PATCH /api/agents/{id}/runtime. A profile runs only on its own harness. Filter by `harness` to see what an agent on that harness can run.",
+      annotations: { readOnlyHint: true },
+      inputSchema: z.object({
+        harness: ProviderNameSchema.optional().describe(
+          "Only profiles for this harness (claude, codex, pi, ...).",
+        ),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        profiles: z
+          .array(
+            z.looseObject({
+              name: z.string().optional(),
+              harness: z.string().optional(),
+              model: z.string().optional(),
+              effort: z.string().nullable().optional(),
+              description: z.string().nullable().optional(),
+            }),
+          )
+          .optional(),
+      }),
+    },
+    async ({ harness }) => {
+      const profiles = await listModelProfiles({ harness });
+      const lines = profiles.map(
+        (p) =>
+          `${p.name}: ${p.harness} / ${p.model}${p.effort ? ` / effort ${p.effort}` : ""}${p.description ? ` (${p.description})` : ""}`,
+      );
+      return toolOk(`${profiles.length} model profile(s)${harness ? ` for ${harness}` : ""}.`, {
+        details: lines.join("\n"),
+        data: {
+          profiles: profiles.map((p) => ({
+            name: p.name,
+            harness: p.harness,
+            model: p.model,
+            effort: p.effort,
+            description: p.description,
+          })),
+        },
+      });
+    },
+  );
+};

package/src/tools/register-chat-channel.ts

@@ -0,0 +1,139 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getWorkflow } from "@/be/db";
+import { CHAT_SDK_ADAPTER_NAMES } from "@/integrations/chat-sdk/config";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import {
+  type ChatChannelMapping,
+  chatChannelKey,
+  deleteChatChannelMapping,
+  putChatChannelMapping,
+} from "@/integrations/chat-sdk/router";
+import { can } from "@/rbac";
+import {
+  createToolRegistrar,
+  type RequestInfo,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
+
+async function canManageChatChannels(requestInfo: RequestInfo): Promise<boolean> {
+  const caller = requestInfo.agentId ? await getAgentById(requestInfo.agentId) : null;
+  return can({
+    principal: {
+      kind: "agent",
+      agentId: requestInfo.agentId ?? "",
+      isLead: caller?.isLead ?? false,
+    },
+    verb: "integration.chat.manage",
+    resource: { kind: "none" },
+    source: "mcp",
+  }).allow;
+}
+
+export const registerRegisterChatChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "register-chat-channel",
+    {
+      title: "Route a chat channel to an agent or workflow",
+      annotations: { idempotentHint: true },
+      description:
+        "Lead-only. Route every swarm-addressed message from one Chat SDK channel (a Telegram group, Slack channel, Discord channel or Teams chat) to a fixed agent or workflow instead of the lead. Give exactly one of agentId or workflowId. A swarm#<agentId> token in a message still wins over the mapping. Remove it with unregister-chat-channel.",
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        channelId: z
+          .string()
+          .min(1)
+          .describe("SDK channel id, such as telegram:-100123 or slack:C123 (prefix optional)."),
+        agentId: z.string().optional().describe("Agent that receives the channel's tasks."),
+        workflowId: z
+          .string()
+          .optional()
+          .describe("Workflow whose webhook trigger receives the channel's messages."),
+        name: z.string().max(200).optional().describe("Display name for the mapping."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        key: z.string().optional(),
+        mapping: z
+          .looseObject({
+            agentId: z.string().optional(),
+            workflowId: z.string().optional(),
+            name: z.string().optional(),
+            createdAt: z.string().optional(),
+          })
+          .optional(),
+      }),
+    },
+    async ({ adapter, channelId, agentId, workflowId, name }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      try {
+        if (!(await canManageChatChannels(requestInfo))) {
+          return toolErr("Permission denied. Only the lead can register a chat channel.", {
+            data,
+          });
+        }
+        if (Boolean(agentId) === Boolean(workflowId)) {
+          return toolErr("Give exactly one of agentId or workflowId.", { data });
+        }
+        if (agentId && !(await getAgentById(agentId))) {
+          return toolErr(`Agent ${agentId} not found.`, { data });
+        }
+        if (workflowId && !(await getWorkflow(workflowId))) {
+          return toolErr(`Workflow ${workflowId} not found.`, { data });
+        }
+        const mapping: ChatChannelMapping = {
+          ...(agentId ? { agentId } : {}),
+          ...(workflowId ? { workflowId } : {}),
+          ...(name ? { name } : {}),
+          createdAt: new Date().toISOString(),
+        };
+        const key = await putChatChannelMapping(adapter, channelId, mapping);
+        return toolOk(
+          `Registered chat channel ${key} -> ${workflowId ? `workflow ${workflowId}` : `agent ${agentId}`}.`,
+          { data: { ...data, key, mapping } },
+        );
+      } catch (error) {
+        return toolErr(errorMessage(error), { data });
+      }
+    },
+  );
+};
+
+export const registerUnregisterChatChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "unregister-chat-channel",
+    {
+      title: "Remove a chat channel route",
+      annotations: { idempotentHint: true },
+      description:
+        "Lead-only. Remove the channel-to-agent or channel-to-workflow route that register-chat-channel stored. Messages from the channel go back to the default route (thread owner, then the lead).",
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        channelId: z.string().min(1).describe("SDK channel id (prefix optional)."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        key: z.string().optional(),
+      }),
+    },
+    async ({ adapter, channelId }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      try {
+        if (!(await canManageChatChannels(requestInfo))) {
+          return toolErr("Permission denied. Only the lead can unregister a chat channel.", {
+            data,
+          });
+        }
+        const key = chatChannelKey(adapter, channelId);
+        const deleted = await deleteChatChannelMapping(adapter, channelId);
+        return deleted
+          ? toolOk(`Unregistered chat channel ${key}.`, { data: { ...data, key } })
+          : toolErr(`No mapping found for chat channel ${key}.`, { data: { ...data, key } });
+      } catch (error) {
+        return toolErr(errorMessage(error), { data });
+      }
+    },
+  );
+};