@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/tests/ui-logs-parser.test.ts

@@ -1154,6 +1154,49 @@ describe("ui logs parser", () => {
     ]);
   });
 
+  test("keeps a Claude sub-agent's parent_tool_use_id on its messages", () => {
+    const messages = parseSessionLogs([
+      log("spawn", "claude", 1, {
+        type: "assistant",
+        message: {
+          role: "assistant",
+          content: [{ type: "tool_use", id: "toolu_agent_1", name: "Agent", input: {} }],
+        },
+      }),
+      log("child-call", "claude", 2, {
+        type: "assistant",
+        parent_tool_use_id: "toolu_agent_1",
+        message: {
+          role: "assistant",
+          content: [
+            { type: "thinking", thinking: "Look at the fixtures." },
+            { type: "tool_use", id: "toolu_read_1", name: "Read", input: { file_path: "a.ts" } },
+          ],
+        },
+      }),
+      log("child-result", "claude", 3, {
+        type: "user",
+        parent_tool_use_id: "toolu_agent_1",
+        message: {
+          role: "user",
+          content: [{ type: "tool_result", tool_use_id: "toolu_read_1", content: "ok" }],
+        },
+      }),
+      log("main-text", "claude", 4, {
+        type: "assistant",
+        parent_tool_use_id: null,
+        message: { role: "assistant", content: [{ type: "text", text: "Done." }] },
+      }),
+    ]);
+
+    expect(messages.map((m) => [m.id, m.parentToolUseId])).toEqual([
+      ["spawn", undefined],
+      ["child-call", "toolu_agent_1"],
+      ["child-result", "toolu_agent_1"],
+      ["main-text", undefined],
+    ]);
+  });
+
   test("extracts a completed Claude foreground Agent run from its paired result", () => {
     const runs = extractSubagentRuns([
       log("spawn", "claude", 1, {

package/src/tests/used-by-route.test.ts

@@ -61,10 +61,14 @@ const configValue = async (key: string) =>
 
 describe("POST /api/used-by", () => {
   const originalFetch = globalThis.fetch;
+  const savedEnvWebsite = process.env.SWARM_ORG_WEBSITE;
+  const savedEnvName = process.env.SWARM_ORG_NAME;
   let proxied: Array<{ url: string; body: Record<string, unknown> }>;
   let proxyStatus: number;
 
   beforeAll(async () => {
+    delete process.env.SWARM_ORG_WEBSITE;
+    delete process.env.SWARM_ORG_NAME;
     await removeDbFiles();
     initDb(TEST_DB_PATH);
     await createAgent({ id: WORKER_ID, name: "Worker", isLead: false, status: "idle" });
@@ -75,6 +79,8 @@ describe("POST /api/used-by", () => {
   });
 
   afterAll(async () => {
+    if (savedEnvWebsite !== undefined) process.env.SWARM_ORG_WEBSITE = savedEnvWebsite;
+    if (savedEnvName !== undefined) process.env.SWARM_ORG_NAME = savedEnvName;
     globalThis.fetch = originalFetch;
     closeDb();
     await removeDbFiles();

package/src/tests/vendored-openapi.test.ts

@@ -255,13 +255,28 @@ describe("vendored OpenAPI", () => {
           new Date().toISOString(),
           new Bun.CryptoHasher("sha256").update(migration117).digest("hex"),
         );
+      // 213 rebuilds script_connections with post-117 columns, so it must wait for 117 too.
+      const migration213 = readFileSync(
+        "src/be/migrations/213_script_connections_sql.sql",
+        "utf-8",
+      );
+      database
+        .prepare(
+          "INSERT INTO _migrations (version, name, applied_at, checksum) VALUES (?, ?, ?, ?)",
+        )
+        .run(
+          213,
+          "213_script_connections_sql",
+          new Date().toISOString(),
+          new Bun.CryptoHasher("sha256").update(migration213).digest("hex"),
+        );
       runMigrations(database);
       database
         .query(
           "INSERT INTO script_connections (id, slug, kind, openapi_spec_json) VALUES (?, ?, ?, ?)",
         )
         .run("legacy-row", "legacy", "openapi", "{}");
-      database.run("DELETE FROM _migrations WHERE version = 117");
+      database.run("DELETE FROM _migrations WHERE version IN (117, 213)");
       runMigrations(database);
       expect(
         database.query<{ id: string }, []>("SELECT id FROM script_connections").get()?.id,

package/src/tests/vercel-ai-gateway.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Vercel AI Gateway (`vercel/<vendor>/<model>`) on pi and opencode: the full
+ * chat catalog, and the one endpoint no env var or hand-written block can move.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  isAgentChatModel,
+  OPENAI_COMPATIBLE_PROVIDERS,
+  openAICompatibleBaseUrlVars,
+  providerBaseUrl,
+  providerForModel,
+  withRegistryCatalogSections,
+} from "@desplega/model-catalog";
+import { buildCatalogEntries } from "../be/model-catalog-store";
+import { isKnownCatalogModel } from "../be/model-validation";
+import { buildModelsCatalog } from "../be/models-catalog";
+import { loadModelsDevCache, type ModelsDevCache } from "../be/modelsdev-cache";
+import snapshot from "../be/modelsdev-cache.json";
+import { applyProviderKeySplice, type OpencodeConfig } from "../providers/opencode-adapter";
+import { customProviderModelsBlock, writeSessionModelsJson } from "../providers/pi-mono-adapter";
+
+const VERCEL = OPENAI_COMPATIBLE_PROVIDERS.vercel;
+const ENDPOINT = "https://ai-gateway.vercel.sh/v1";
+const WRONG = "https://ai-gateway.vercel.sh";
+const raw = snapshot as unknown as ModelsDevCache;
+const rawVercel = (raw.vercel?.models ?? {}) as Record<
+  string,
+  Parameters<typeof isAgentChatModel>[0]
+>;
+const chatIds = Object.keys(rawVercel).filter((id) => isAgentChatModel(rawVercel[id] ?? {}));
+
+describe("Vercel AI Gateway catalog", () => {
+  test("the snapshot carries non-chat rows, so the filter is exercised", () => {
+    expect(rawVercel["voyage/voyage-code-3"]).toBeDefined();
+    expect(chatIds.length).toBeGreaterThan(200);
+    expect(chatIds.length).toBeLessThan(Object.keys(rawVercel).length);
+  });
+
+  test("pi lists every AI Gateway chat model, and no embedding or video model", () => {
+    const block = customProviderModelsBlock(VERCEL);
+    const ids = block.models.map((m) => m.id as string);
+    expect(ids.sort()).toEqual([...chatIds].sort());
+    expect(ids).toContain("zai/glm-5.3");
+    expect(ids).toContain("moonshotai/kimi-k3");
+    expect(ids).toContain("anthropic/claude-sonnet-4.6");
+    expect(ids).not.toContain("voyage/voyage-code-3");
+    expect(ids).not.toContain("klingai/kling-v3.0-t2v");
+    const glm = block.models.find((m) => m.id === "zai/glm-5.3");
+    expect(glm).toMatchObject({ contextWindow: 1000000, maxTokens: 1000000, reasoning: true });
+    expect(block).toMatchObject({
+      baseUrl: ENDPOINT,
+      api: "openai-completions",
+      apiKey: "$AI_GATEWAY_API_KEY",
+    });
+  });
+
+  test("picker, live and validation catalogs drop non-chat Vercel rows", () => {
+    const merged = withRegistryCatalogSections(raw);
+    expect(Object.keys(merged.vercel?.models ?? {}).sort()).toEqual([...chatIds].sort());
+    // OpenRouter is not a registry provider and keeps its full section.
+    expect(Object.keys(merged.openrouter?.models ?? {}).length).toBe(
+      Object.keys(raw.openrouter?.models ?? {}).length,
+    );
+
+    const live = buildCatalogEntries(raw, 0).filter((e) => e.provider === "vercel");
+    expect(live.map((e) => e.modelId).sort()).toEqual([...chatIds].sort());
+
+    const cache = loadModelsDevCache();
+    if (!cache) throw new Error("snapshot missing");
+    const catalog = buildModelsCatalog(cache) as Parameters<typeof isKnownCatalogModel>[1];
+    expect(isKnownCatalogModel("vercel/zai/glm-5.3", catalog)).toBe(true);
+    expect(isKnownCatalogModel("vercel/anthropic/claude-sonnet-4.6", catalog)).toBe(true);
+    expect(isKnownCatalogModel("vercel/voyage/voyage-code-3", catalog)).toBe(false);
+    expect(providerForModel("vercel/moonshotai/kimi-k3")?.id).toBe("vercel");
+  });
+});
+
+describe("Vercel AI Gateway endpoint is fixed", () => {
+  const dirs: string[] = [];
+  afterEach(async () => {
+    await Promise.all(dirs.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+  });
+
+  test("VERCEL_BASE_URL is never read or forwarded", () => {
+    expect(VERCEL.baseUrl).toBe(ENDPOINT);
+    expect(providerBaseUrl(VERCEL, { VERCEL_BASE_URL: WRONG })).toBe(ENDPOINT);
+    expect(openAICompatibleBaseUrlVars()).not.toContain("VERCEL_BASE_URL");
+    expect(openAICompatibleBaseUrlVars()).toContain("NAN_BASE_URL");
+  });
+
+  test("opencode gets the key and no baseURL, even over a configured one", () => {
+    const key = crypto.randomUUID();
+    const config: OpencodeConfig = {
+      model: "vercel/zai/glm-5.3",
+      provider: { vercel: { options: { baseURL: WRONG } } },
+    };
+    const picked = applyProviderKeySplice(config, config.model, {
+      AI_GATEWAY_API_KEY: key,
+      VERCEL_BASE_URL: WRONG,
+    });
+    expect(picked?.key).toBe(key);
+    expect(config.provider?.vercel).toEqual({ env: [], options: { apiKey: key } });
+  });
+
+  test("pi gets the Chat Completions endpoint over VERCEL_BASE_URL and a hand-written block", async () => {
+    const agentDir = await mkdtemp(join(tmpdir(), "pi-vercel-"));
+    dirs.push(agentDir);
+    await Bun.write(
+      join(agentDir, "models.json"),
+      JSON.stringify({
+        providers: { vercel: { baseUrl: WRONG, api: "anthropic-messages", headers: { a: "b" } } },
+      }),
+    );
+    const env = { AI_GATEWAY_API_KEY: "k", VERCEL_BASE_URL: WRONG };
+    const session = await writeSessionModelsJson(agentDir, env, "vercel/vendor/brand-new-model");
+    try {
+      expect(session.modelsPath).toBeDefined();
+      const written = await Bun.file(session.modelsPath as string).json();
+      const block = written.providers.vercel;
+      expect(block.baseUrl).toBe(ENDPOINT);
+      expect(block.api).toBe("openai-completions");
+      expect(block.headers).toEqual({ a: "b" });
+      const ids = (block.models as { id: string }[]).map((m) => m.id);
+      expect(ids).toContain("zai/glm-5.3");
+      // An id the catalog does not know yet still resolves (bare entry).
+      expect(ids).toContain("vendor/brand-new-model");
+    } finally {
+      await session.dispose();
+    }
+  });
+
+  test("pi without a shared block also lands on the endpoint", async () => {
+    const agentDir = await mkdtemp(join(tmpdir(), "pi-vercel-"));
+    dirs.push(agentDir);
+    const session = await writeSessionModelsJson(agentDir, {
+      AI_GATEWAY_API_KEY: "k",
+      VERCEL_BASE_URL: WRONG,
+    });
+    try {
+      const written = await Bun.file(session.modelsPath as string).json();
+      expect(written.providers.vercel.baseUrl).toBe(ENDPOINT);
+    } finally {
+      await session.dispose();
+    }
+  });
+});

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 });
+      }
+    },
+  );
+};