@desplega.ai/agent-swarm 2.4.3 → 2.4.5

package/src/http/session-access.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import { getSteeringMessageById } from "../be/db";
 import { getActiveSessionById } from "../be/db/active-sessions";
 import { getUserGrant } from "../be/rbac-roles";
@@ -10,10 +10,12 @@ import {
   sessionAccessForRoot,
 } from "../be/session-shares";
 import { findUserById } from "../be/users";
-import { isRbacEnabled } from "../rbac";
+import { can, isRbacEnabled, type RbacPrincipal } from "../rbac";
+import type { AgentTask } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { dashboardUserIdHeader } from "./favorite-owner";
 import { type RouteDef, routePathParams } from "./route-def";
+import { jsonError } from "./utils";
 
 /**
  * Who a request acts for when it touches a session.
@@ -76,6 +78,53 @@ export function readableByFor(actor: SessionActor): { userId: string | null } |
 export const SESSION_WRITE_DENIED =
   "You can't write in this session. Ask the owner to share it with edit access.";
 
+/** True unless the request acts for a user who lacks write access to the task's session. */
+export async function hasSessionWrite(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+  taskId: string,
+): Promise<boolean> {
+  const access = await sessionAccessFor(await resolveSessionActor(req, myAgentId), taskId);
+  return hasSessionAccess(access, "write");
+}
+
+/**
+ * The parent gate shared by `POST /api/tasks` and `POST /api/apps/{id}/actions/{name}`.
+ * The child inherits the parent's thread context, so an agent caller must own or
+ * have created the parent (`task.parent.attach`; operator and user callers keep
+ * their access), and a follow-up in someone else's session needs a write share.
+ * Writes the 403 and returns true when denied.
+ */
+export async function denyParentAttach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  myAgentId: string | undefined,
+  parentTask: Pick<AgentTask, "id" | "requestedByUserId" | "creatorAgentId" | "agentId">,
+  principal: RbacPrincipal,
+): Promise<boolean> {
+  const attach = can({
+    principal,
+    verb: "task.parent.attach",
+    resource: {
+      kind: "task",
+      taskId: parentTask.id,
+      requestedByUserId: parentTask.requestedByUserId,
+      creatorAgentId: parentTask.creatorAgentId,
+      agentId: parentTask.agentId,
+    },
+    source: "http",
+  });
+  if (!attach.allow) {
+    jsonError(res, `You don't have context for parent task ${parentTask.id}.`, 403);
+    return true;
+  }
+  if (!(await hasSessionWrite(req, myAgentId, parentTask.id))) {
+    jsonError(res, SESSION_WRITE_DENIED, 403);
+    return true;
+  }
+  return false;
+}
+
 /**
  * The denial for an actor lacking `needed` access to the session holding
  * `taskId`, or null. An unknown task passes, so the handler still answers 404.

package/src/http/sessions.ts

@@ -2,11 +2,14 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
   countSessions,
+  createAgent,
+  getAgentById,
   getDbClient,
   getRootTaskChain,
   getTaskById,
   listRecentSessions,
 } from "../be/db";
+import { getUserGrant } from "../be/rbac-roles";
 import {
   getSessionRoot,
   listActiveSessionShares,
@@ -18,13 +21,17 @@ import {
 import { getTaskSteeringFieldsForTasks } from "../be/steering";
 import { getTaskCitationsForTasks, TaskCitationSchema } from "../be/task-citations";
 import {
+  AgentTokenExistsError,
   findUserById,
   InvalidRuntimeTokenError,
+  mintAgentToken,
   mintRuntimeToken,
   mintSessionToken,
+  revokeAgentTokens,
   revokeSessionToken,
+  rotateAgentToken,
 } from "../be/users";
-import { can } from "../rbac";
+import { can, isRbacEnabled } from "../rbac";
 import { sessionAccessTopic } from "../realtime/auth";
 import { realtimeBus } from "../realtime/bus";
 import {
@@ -39,6 +46,7 @@ import {
 } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { isRuntimePoolsEnabled } from "../utils/runtime-pools-flag";
+import { agentFirstPrincipal } from "./request-principal";
 import { route } from "./route-def";
 import { resolveSessionActor, type SessionActor } from "./session-access";
 import { jsonError } from "./utils";
@@ -118,7 +126,7 @@ const mintSessionTokenRoute = route({
   },
   summary: "Mint an ephemeral task or runtime token",
   description:
-    "Operators can mint task or runtime tokens. Runtime tokens can mint task tokens for their own assigned tasks. Child tokens expire with their parent runtime.",
+    "Operators can mint task or runtime tokens. Runtime and agent tokens can mint task tokens for their own assigned tasks. A child token never outlives its parent and is revoked with it.",
   tags: ["Sessions"],
   body: z
     .object({
@@ -147,7 +155,8 @@ const mintSessionTokenRoute = route({
   },
   auth: { apiKey: true },
   rbac: {
-    ungated: "operator or runtime token minting for its own assigned task, enforced in the handler",
+    ungated:
+      "operator, or a runtime or agent token minting for its own assigned task, enforced in the handler",
   },
 });
 
@@ -157,7 +166,7 @@ const revokeSessionTokenRoute = route({
   pattern: ["api", "sessions", "tokens", null],
   summary: "Revoke an ephemeral session token",
   description:
-    "Operators can revoke any ephemeral token. With runtime pools enabled, runtime tokens can revoke their own child task tokens. Repeated revocation has no effect.",
+    "Operators can revoke any ephemeral token. Agent tokens, and runtime tokens when runtime pools are enabled, can revoke their own child task tokens. Repeated revocation has no effect.",
   tags: ["Sessions"],
   params: z.object({ tokenId: z.string() }),
   responses: {
@@ -167,10 +176,234 @@ const revokeSessionTokenRoute = route({
   },
   auth: { apiKey: true },
   rbac: {
-    ungated: "operator or runtime token revoking its own child, enforced in the handler",
+    ungated:
+      "operator, or a runtime or agent token revoking its own child, enforced in the handler",
   },
 });
 
+/** Default rotation grace: the old worker token keeps working this long. */
+const AGENT_TOKEN_ROTATE_GRACE_SEC = 300;
+
+const AgentTokenSchema = z.object({
+  agentId: z.string(),
+  tokenId: z.string(),
+  plaintext: z.string(),
+  expiresAt: z.string().nullable().describe("null when the token does not expire"),
+});
+
+const agentTokenTtl = z
+  .number()
+  .int()
+  .positive()
+  .optional()
+  .describe("Token lifetime in ms. Omit for the default (no expiry).");
+
+const mintAgentTokenRoute = route({
+  method: "post",
+  path: "/api/agents/{id}/token",
+  pattern: ["api", "agents", null, "token"],
+  operationId: "agents_mintWorkerToken",
+  summary: "Mint an agent-bound worker token",
+  description:
+    "Returns the token once. A worker runs on it in place of the swarm API key and acts only as this agent. Creates the agent when it does not exist and `name` is given. Fails with 409 when the agent already holds an active token.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z
+    .object({ name: z.string().min(1).optional(), ttlMs: agentTokenTtl })
+    .strict()
+    .optional(),
+  responses: {
+    200: {
+      description: "Minted worker token",
+      schema: AgentTokenSchema.extend({ agentCreated: z.boolean() }),
+    },
+    403: { description: "Operator or user credentials required" },
+    404: { description: "Agent not found and no name given" },
+    409: { description: "Agent already holds an active token" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const rotateAgentTokenRoute = route({
+  method: "post",
+  path: "/api/agents/{id}/token/rotate",
+  pattern: ["api", "agents", null, "token", "rotate"],
+  operationId: "agents_rotateWorkerToken",
+  summary: "Rotate an agent-bound worker token",
+  description:
+    "Returns a new token once. The previous token keeps working for `graceSec` (default 300), then expires. Use revoke for a token that must stop now.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z
+    .object({ graceSec: z.number().int().min(0).max(86_400).optional(), ttlMs: agentTokenTtl })
+    .strict()
+    .optional(),
+  responses: {
+    200: {
+      description: "New worker token",
+      schema: AgentTokenSchema.extend({ previousExpiresAt: z.string() }),
+    },
+    403: { description: "Operator or user credentials required" },
+    404: { description: "Agent holds no active token" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const revokeAgentTokenRoute = route({
+  method: "delete",
+  path: "/api/agents/{id}/token",
+  pattern: ["api", "agents", null, "token"],
+  operationId: "agents_revokeWorkerToken",
+  summary: "Revoke an agent-bound worker token",
+  description:
+    "Revokes every active worker token of the agent and the task tokens they minted. Open realtime connections on them close.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  responses: {
+    200: {
+      description: "Number of worker tokens revoked (0 when none was active)",
+      schema: z.object({ revoked: z.number().int() }),
+    },
+    403: { description: "Operator or user credentials required" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const AGENT_TOKEN_ROUTES = [mintAgentTokenRoute, rotateAgentTokenRoute, revokeAgentTokenRoute];
+
+/**
+ * Gate the worker-token routes. Only an operator key or a user may manage
+ * them, never a session token. The principal is agent-first: an operator key
+ * sent with X-Agent-ID acts as that agent and is refused, as on the
+ * controller-token route.
+ */
+async function ensureAgentTokenManager(
+  req: IncomingMessage,
+  res: ServerResponse,
+  agentId: string,
+): Promise<boolean> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "operator" && auth?.kind !== "user") {
+    jsonError(res, "Worker tokens require operator or user credentials", 403);
+    return false;
+  }
+  const header = req.headers["x-agent-id"];
+  const decision = can({
+    principal: await agentFirstPrincipal(req, Array.isArray(header) ? header[0] : header),
+    verb: "agent.token.manage",
+    resource: { kind: "agent", agentId },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(res, decision.reason, 403);
+    return false;
+  }
+  // A worker token carries the target agent's privileges and reads that
+  // agent's resolved config, global secrets included. A user without a
+  // grant-all role must already hold both, and may not manage the token of an
+  // agent that may itself act on any agent (a lead).
+  if (auth.kind === "user" && isRbacEnabled()) {
+    const grant = await getUserGrant(auth.userId);
+    if (!grant.grantsAll) {
+      const target = await getAgentById(agentId);
+      const targetActsOnAny = can({
+        principal: { kind: "agent", agentId, isLead: target?.isLead ?? false },
+        verb: "agent.act.any",
+        resource: { kind: "agent", agentId },
+        source: "http",
+      }).allow;
+      if (targetActsOnAny) {
+        jsonError(res, "A lead agent's worker token requires a grant-all role", 403);
+        return false;
+      }
+      const missing = (["agent.act.any", "config.read.secrets"] as const).filter(
+        (verb) => !grant.verbs.has(verb),
+      );
+      if (missing.length > 0) {
+        jsonError(res, `Worker tokens also require: ${missing.join(", ")}`, 403);
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+async function handleAgentTokens(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  const matched = AGENT_TOKEN_ROUTES.find((def) => def.match(req.method, pathSegments));
+  if (!matched) return false;
+  if (!(await ensureAgentTokenManager(req, res, pathSegments[2]!))) return true;
+  res.setHeader("Cache-Control", "no-store");
+
+  if (matched === mintAgentTokenRoute) {
+    const parsed = await mintAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const agentId = parsed.params.id;
+    const result = await getDbClient()
+      .transaction(async () => {
+        let agentCreated = false;
+        if (!(await getAgentById(agentId))) {
+          if (!parsed.body?.name) return { status: 404 as const };
+          // Same defaults as a worker's first registration; it is offline until it connects.
+          await createAgent({
+            id: agentId,
+            name: parsed.body.name,
+            isLead: false,
+            status: "offline",
+            capabilities: [],
+            maxTasks: 1,
+          });
+          agentCreated = true;
+        }
+        return {
+          status: 200 as const,
+          agentCreated,
+          token: await mintAgentToken(agentId, parsed.body?.ttlMs),
+        };
+      })
+      .catch((error) => {
+        if (error instanceof AgentTokenExistsError) return { status: 409 as const };
+        throw error;
+      });
+    if (result.status === 404) {
+      jsonError(res, "Agent not found; pass name to create it", 404);
+      return true;
+    }
+    if (result.status === 409) {
+      jsonError(res, "Agent already holds an active worker token; rotate or revoke it", 409);
+      return true;
+    }
+    mintAgentTokenRoute.respond(res, 200, {
+      agentId,
+      ...result.token,
+      agentCreated: result.agentCreated,
+    });
+    return true;
+  }
+
+  if (matched === rotateAgentTokenRoute) {
+    const parsed = await rotateAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const graceSec = parsed.body?.graceSec ?? AGENT_TOKEN_ROTATE_GRACE_SEC;
+    const token = await rotateAgentToken(parsed.params.id, graceSec * 1000, parsed.body?.ttlMs);
+    if (!token) {
+      jsonError(res, "Agent holds no active worker token", 404);
+      return true;
+    }
+    rotateAgentTokenRoute.respond(res, 200, { agentId: parsed.params.id, ...token });
+    return true;
+  }
+
+  const parsed = await revokeAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true;
+  revokeAgentTokenRoute.respond(res, 200, { revoked: await revokeAgentTokens(parsed.params.id) });
+  return true;
+}
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -309,9 +542,11 @@ export async function handleSessions(
   queryParams: URLSearchParams,
   myAgentId?: string,
 ): Promise<boolean> {
+  if (await handleAgentTokens(req, res, pathSegments, queryParams)) return true;
+
   if (mintSessionTokenRoute.match(req.method, pathSegments)) {
     const auth = getRequestAuth(req);
-    if (auth?.kind !== "operator" && !(auth?.kind === "agent" && auth.runtimeId)) {
+    if (auth?.kind !== "operator" && !(auth?.kind === "agent" && auth.tokenKind !== "task")) {
       jsonError(res, "Unauthorized", 401);
       return true;
     }
@@ -334,7 +569,7 @@ export async function handleSessions(
           return {
             token: await mintSessionToken(agentId, taskId!, ttlMs!, {
               tokenId: auth.tokenId,
-              runtimeId: auth.runtimeId!,
+              runtimeId: auth.runtimeId,
             }),
           };
         }
@@ -365,7 +600,10 @@ export async function handleSessions(
     const auth = getRequestAuth(req);
     if (
       auth?.kind !== "operator" &&
-      !(isRuntimePoolsEnabled() && auth?.kind === "agent" && auth.runtimeId)
+      !(
+        auth?.kind === "agent" &&
+        (auth.tokenKind === "agent" || (auth.tokenKind === "runtime" && isRuntimePoolsEnabled()))
+      )
     ) {
       jsonError(res, "Unauthorized", 401);
       return true;
@@ -375,8 +613,9 @@ export async function handleSessions(
     const revoked = await getDbClient().transaction(async (client) => {
       if (auth.kind === "agent") {
         const child = await client.get(
-          "SELECT id FROM session_tokens WHERE id = ? AND agentId = ? AND parentRuntimeId = ? AND taskId IS NOT NULL",
-          [parsed.params.tokenId, auth.agentId, auth.runtimeId!],
+          `SELECT id FROM session_tokens WHERE id = ? AND agentId = ? AND taskId IS NOT NULL
+           AND ${auth.runtimeId ? "parentRuntimeId" : "parentTokenId"} = ?`,
+          [parsed.params.tokenId, auth.agentId, auth.runtimeId ?? auth.tokenId],
         );
         if (!child) return false;
       }

package/src/http/tasks.ts

@@ -87,6 +87,7 @@ import { buildTaskRequestedBy, TaskRequestedBySchema } from "./requested-by";
 import { bodyTask, route } from "./route-def";
 import {
   canReadSession,
+  denyParentAttach,
   readableByFor,
   resolveSessionActor,
   SESSION_READ_DENIED,
@@ -779,16 +780,6 @@ const updateTaskTitleRoute = route({
   },
 });
 
-/** True unless the request acts for a user who lacks write access to the task's session. */
-async function hasSessionWrite(
-  req: IncomingMessage,
-  myAgentId: string | undefined,
-  taskId: string,
-): Promise<boolean> {
-  const access = await sessionAccessFor(await resolveSessionActor(req, myAgentId), taskId);
-  return hasSessionAccess(access, "write");
-}
-
 async function canSteerTask(
   req: IncomingMessage,
   myAgentId: string | undefined,
@@ -1069,29 +1060,10 @@ export async function handleTasks(
       ? await getTaskById(parsed.body.parentTaskId)
       : null;
     // The child inherits the parent's thread context, so an agent caller must own or
-    // have created the parent. Operator and user callers keep their access.
+    // have created the parent, and a follow-up in someone else's session needs a
+    // write share. The same gate guards app actions that chain under a task.
     const principal = await resolveTaskWritePrincipal(req, myAgentId);
-    if (
-      parentTask &&
-      !can({
-        principal,
-        verb: "task.parent.attach",
-        resource: {
-          kind: "task",
-          taskId: parentTask.id,
-          requestedByUserId: parentTask.requestedByUserId,
-          creatorAgentId: parentTask.creatorAgentId,
-          agentId: parentTask.agentId,
-        },
-        source: "http",
-      }).allow
-    ) {
-      jsonError(res, `You don't have context for parent task ${parentTask.id}.`, 403);
-      return true;
-    }
-    // A follow-up in someone else's session needs a write share.
-    if (parentTask && !(await hasSessionWrite(req, myAgentId, parentTask.id))) {
-      jsonError(res, SESSION_WRITE_DENIED, 403);
+    if (parentTask && (await denyParentAttach(req, res, myAgentId, parentTask, principal))) {
       return true;
     }
     // A chat-sdk contextKey binds the task to a chat thread that its assignee and creator

package/src/http/users.ts

@@ -550,7 +550,18 @@ const deleteIdentityRoute = route({
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-const UNMAPPED_KINDS = ["slack", "github", "gitlab", "azure-devops", "linear", "kapso"] as const;
+const UNMAPPED_KINDS = [
+  "slack",
+  "github",
+  "gitlab",
+  "azure-devops",
+  "linear",
+  "kapso",
+  // Chat SDK adapters record unknown senders under the adapter name.
+  "telegram",
+  "discord",
+  "teams",
+] as const;
 
 /**
  * Group the two-key-per-identity kv entries (`<externalId>:meta` json +

package/src/integrations/chat-sdk/adapters.ts

@@ -63,9 +63,13 @@ export async function loadAdapter(
     case "telegram": {
       const { createTelegramAdapter } = await import("@chat-adapter/telegram");
       // Explicit `false` blocks the TELEGRAM_ALLOW_UNVERIFIED_WEBHOOKS env fallback.
-      return createTelegramAdapter({ ...base, allowUnverifiedWebhooks: false } as Parameters<
-        typeof createTelegramAdapter
-      >[0]);
+      // Explicit `true` makes a reply to the bot a mention whatever
+      // TELEGRAM_MENTION_ON_REPLY says.
+      return createTelegramAdapter({
+        ...base,
+        allowUnverifiedWebhooks: false,
+        mentionOnReply: true,
+      } as Parameters<typeof createTelegramAdapter>[0]);
     }
     case "slack": {
       const { createSlackAdapter } = await import("@chat-adapter/slack");

package/src/integrations/chat-sdk/attachments.ts

@@ -9,7 +9,9 @@
  * row. The task is created in `draft` while its uploads run, with its lease
  * renewed, so no worker can claim it before its attachments exist. Every file
  * also stays in the task text as a `[File: ...]` line. Only a fetch failure is
- * flagged there; upload and record failures are logged.
+ * flagged there; upload and record failures are logged. Audio files (voice
+ * notes) get their transcript in the task text when transcription is
+ * configured, and keep the audio attached.
  */
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
@@ -21,12 +23,28 @@ import { providerPath } from "@/fs/provider";
 import { getFileStorageProvider } from "@/fs/registry";
 import { createTaskWithSiblingAwareness } from "@/tasks/sibling-awareness";
 import type { AgentTask, CreateTaskOptions } from "@/types";
+import { transcribeAudioNotes } from "@/utils/transcription";
 import { errorMessage } from "./logger";
 
 /** How often a draft's lease is renewed while its uploads run; the sweep waits 5 minutes. */
 const DRAFT_LEASE_REFRESH_MS = 60_000;
 /** A file a user sent the bot, like one uploaded from the dashboard composer. */
-const SHARED_FILE_INTENT = "user-upload";
+export const SHARED_FILE_INTENT = "user-upload";
+
+const MB = 1024 * 1024;
+/**
+ * Per-file inbound cap by adapter. A Telegram bot can download at most 20 MB
+ * through `getFile`; a larger file fails at Telegram before our own cap.
+ * Other adapters use the task attachment cap.
+ */
+const CHAT_INBOUND_FILE_LIMITS: Record<string, number> = { telegram: 20 * MB };
+
+export function chatInboundFileLimit(adapter: string): number {
+  return Math.min(
+    CHAT_INBOUND_FILE_LIMITS[adapter] ?? MAX_TASK_ATTACHMENT_BYTES,
+    MAX_TASK_ATTACHMENT_BYTES,
+  );
+}
 
 /**
  * One attachment of a buffered chat message. `id` is `<messageId>-<n>` with
@@ -43,7 +61,8 @@ export interface ChatFile {
   attachment: Attachment;
 }
 
-export type ChatFileFailure = { file: ChatFile; reason: string };
+/** `tooLarge` marks a file over the inbound cap; the user gets a reply naming it. */
+export type ChatFileFailure = { file: ChatFile; reason: string; tooLarge?: boolean };
 
 export type FetchedChatFile = { file: ChatFile; path: string; sizeBytes: number; sha256: string };
 
@@ -55,7 +74,7 @@ export type InboundChatFiles = {
   [Symbol.asyncDispose](): Promise<void>;
 };
 
-function formatFileSize(bytes: number): string {
+export function formatFileSize(bytes: number): string {
   if (bytes < 1024) return `${bytes} B`;
   if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
   if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
@@ -81,20 +100,71 @@ export function toChatFiles(
 
 /**
  * `[File: <name> (<mime>, <size>) id=<id>]` per file, followed by
- * `(not attached: <reason>)` when the file never reached the task.
+ * `(not attached: <reason>)` when the file never reached the task, and by the
+ * file's note (a voice-note transcript) on the next line.
  */
-export function buildChatAttachmentText(files: ChatFile[], failed: ChatFileFailure[] = []): string {
+export function buildChatAttachmentText(
+  files: ChatFile[],
+  failed: ChatFileFailure[] = [],
+  notes: Map<string, string> = new Map(),
+): string {
   const reasons = new Map(failed.map((f) => [f.file.id, f.reason]));
   return files
     .map((f) => {
       const size = typeof f.size === "number" ? formatFileSize(f.size) : "unknown size";
       const line = `[File: ${f.name} (${f.mimeType ?? "unknown type"}, ${size}) id=${f.id}]`;
       const reason = reasons.get(f.id);
-      return reason ? `${line} (not attached: ${reason})` : line;
+      const note = notes.get(f.id);
+      return [reason ? `${line} (not attached: ${reason})` : line, note].filter(Boolean).join("\n");
     })
     .join("\n");
 }
 
+/**
+ * A sender-chosen file name as an inline code span, so the bot's reply shows it
+ * as literal text and never renders a link, image or heading from it. Backslash
+ * escapes are not enough: the Chat SDK parser still autolinks bare URLs.
+ */
+function markdownLiteral(value: string): string {
+  const text = value.replace(/[\r\n]+/g, " ");
+  const longestRun = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
+  const fence = "`".repeat(longestRun + 1);
+  // CommonMark strips one space from each end of a padded span.
+  const pad = /^[` ]|[` ]$/.test(text) ? " " : "";
+  return `${fence}${pad}${text}${pad}${fence}`;
+}
+
+/** The reply posted to the thread when files were over the inbound cap. */
+export function formatTooLargeReply(failed: ChatFileFailure[]): string {
+  const lines = failed.map((f) => `- ${markdownLiteral(f.file.name)}: ${f.reason}`);
+  return [
+    `Too large to read, so the swarm did not get ${failed.length === 1 ? "this file" : "these files"}:`,
+    ...lines,
+    "Send a smaller file or a link.",
+  ].join("\n");
+}
+
+/**
+ * Transcribe every fetched audio file. Returns one task-text note per file:
+ * the transcript, the failure, or (when no provider is configured) a line
+ * saying so. Never throws.
+ */
+export async function transcribeChatAudio(
+  fetched: FetchedChatFile[],
+): Promise<Map<string, string>> {
+  return transcribeAudioNotes(
+    fetched
+      .filter(({ file }) => file.attachment.type === "audio")
+      .map(({ file, path }) => ({
+        key: file.id,
+        name: file.name,
+        data: Bun.file(path),
+        mimeType: file.mimeType,
+      })),
+    "[chat-sdk]",
+  );
+}
+
 async function readAttachment(attachment: Attachment): Promise<Uint8Array> {
   if (attachment.data instanceof Blob) return new Uint8Array(await attachment.data.arrayBuffer());
   if (attachment.data) return new Uint8Array(attachment.data);
@@ -119,17 +189,25 @@ export async function fetchChatFiles(files: ChatFile[]): Promise<InboundChatFile
   };
   if (files.length === 0) return result;
 
-  const limit = `larger than the ${MAX_TASK_ATTACHMENT_BYTES / (1024 * 1024)} MB limit`;
+  const tooLarge = (file: ChatFile, size: number): ChatFileFailure => {
+    const limit = chatInboundFileLimit(file.adapter);
+    const platform = file.adapter.charAt(0).toUpperCase() + file.adapter.slice(1);
+    return {
+      file,
+      reason: `too large (${formatFileSize(size)}, the limit for files sent to the ${platform} bot is ${formatFileSize(limit)})`,
+      tooLarge: true,
+    };
+  };
   dir = await mkdtemp(join(tmpdir(), "chat-files-"));
   for (const [index, file] of files.entries()) {
-    if (typeof file.size === "number" && file.size > MAX_TASK_ATTACHMENT_BYTES) {
-      result.failed.push({ file, reason: limit });
+    if (typeof file.size === "number" && file.size > chatInboundFileLimit(file.adapter)) {
+      result.failed.push(tooLarge(file, file.size));
       continue;
     }
     try {
       const bytes = await readAttachment(file.attachment);
-      if (bytes.byteLength > MAX_TASK_ATTACHMENT_BYTES) {
-        result.failed.push({ file, reason: limit });
+      if (bytes.byteLength > chatInboundFileLimit(file.adapter)) {
+        result.failed.push(tooLarge(file, bytes.byteLength));
         continue;
       }
       const path = join(dir, String(index));