@desplega.ai/agent-swarm 2.4.3 → 2.4.5

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

@@ -0,0 +1,120 @@
+import type { Message, Thread } from "chat";
+
+/** Why a message counts as meant for the swarm. `none`: it reached the router unaddressed. */
+export type ChatAddressedReason =
+  | "dm"
+  | "mention"
+  | "reply-to-bot"
+  | "requester-follow-up"
+  | "none";
+
+/**
+ * Facts about one inbound message that only core can read: the chat it came
+ * from (Telegram `message.raw.chat`) and whether it answers the bot.
+ */
+export interface ChatMessageFacts {
+  /** Platform chat type, such as Telegram `private`, `group` or `supergroup`. */
+  chatType?: string;
+  isForum?: boolean;
+  /** Group or channel title. */
+  title?: string;
+  /** Forum topic: `"<name>"` when the update carries it, else `#<thread id>`. */
+  topic?: string;
+  /** The sender as people know them: `Name (@username)`. */
+  from: string;
+  /** The message replies to one of the bot's own messages. */
+  replyToBot: boolean;
+  /** Start of the message it replies to. */
+  replyToSnippet?: string;
+}
+
+const SNIPPET_MAX = 80;
+
+interface TelegramRawMessage {
+  message_id?: number;
+  message_thread_id?: number;
+  is_topic_message?: boolean;
+  chat?: { type?: string; title?: string; is_forum?: boolean };
+  from?: { first_name?: string; last_name?: string; username?: string };
+  reply_to_message?: {
+    message_id?: number;
+    from?: { id?: number | string };
+    text?: string;
+    caption?: string;
+    forum_topic_created?: { name?: string };
+  };
+}
+
+function snippet(text: string | undefined): string | undefined {
+  const flat = text?.replace(/\s+/g, " ").trim();
+  if (!flat) return undefined;
+  return flat.length > SNIPPET_MAX ? `${flat.slice(0, SNIPPET_MAX)}...` : flat;
+}
+
+function personLabel(name: string | undefined, username: string | undefined, fallback: string) {
+  if (name && username && name !== username) return `${name} (@${username})`;
+  if (username) return `@${username}`;
+  return name || fallback;
+}
+
+function telegramFacts(raw: TelegramRawMessage, message: Message, botUserId?: string) {
+  const reply = raw.reply_to_message;
+  // In a forum topic every plain message replies to the topic's creation
+  // message, so that reply is the topic, not an answer to anyone.
+  const replyIsTopicRoot =
+    reply !== undefined &&
+    (reply.forum_topic_created !== undefined ||
+      (raw.is_topic_message === true && reply.message_id === raw.message_thread_id));
+  const realReply = reply && !replyIsTopicRoot ? reply : undefined;
+  const topicName = replyIsTopicRoot ? reply?.forum_topic_created?.name : undefined;
+  const name = [raw.from?.first_name, raw.from?.last_name].filter(Boolean).join(" ").trim();
+  return {
+    chatType: raw.chat?.type,
+    isForum: raw.chat?.is_forum === true ? true : undefined,
+    title: raw.chat?.title,
+    topic:
+      raw.is_topic_message === true && raw.message_thread_id !== undefined
+        ? topicName
+          ? `"${topicName}"`
+          : `#${raw.message_thread_id}`
+        : undefined,
+    from: personLabel(name || undefined, raw.from?.username, message.author.userId),
+    replyToBot:
+      realReply?.from?.id !== undefined &&
+      botUserId !== undefined &&
+      String(realReply.from.id) === botUserId,
+    replyToSnippet: snippet(realReply?.text ?? realReply?.caption),
+  } satisfies ChatMessageFacts;
+}
+
+/** Read the chat facts of one message. Telegram reads the raw update; other adapters the SDK message. */
+export function readChatMessageFacts(thread: Thread, message: Message): ChatMessageFacts {
+  const raw = message.raw as TelegramRawMessage | undefined;
+  if (thread.adapter.name === "telegram" && raw && typeof raw === "object") {
+    return telegramFacts(raw, message, thread.adapter.botUserId);
+  }
+  const { fullName, userName, userId } = message.author;
+  return {
+    chatType: thread.isDM ? "dm" : undefined,
+    from: personLabel(fullName || undefined, userName || undefined, userId),
+    replyToBot: message.replyTo?.author.isMe === true,
+    replyToSnippet: snippet(message.replyTo?.text),
+  };
+}
+
+/** One line of facts for the task header: `telegram · supergroup "Life" · from: ... · addressed: ...`. */
+export function formatChatHeaderFacts(
+  adapter: string,
+  facts: ChatMessageFacts,
+  addressed: ChatAddressedReason,
+): string {
+  // Title, topic and sender are user-set: one line each, so none can forge a header line.
+  const oneLine = (text: string) => text.replace(/\s+/g, " ").trim();
+  const parts = [adapter];
+  if (facts.chatType)
+    parts.push(facts.title ? `${facts.chatType} "${oneLine(facts.title)}"` : facts.chatType);
+  if (facts.isForum) parts.push(facts.topic ? `forum topic ${oneLine(facts.topic)}` : "forum");
+  parts.push(`from: ${oneLine(facts.from)}`, `addressed: ${addressed}`);
+  if (facts.replyToSnippet) parts.push(`reply-to: "${facts.replyToSnippet}"`);
+  return parts.join(" · ");
+}

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

@@ -2,12 +2,15 @@ import type { Adapter, Message, Thread } from "chat";
 import { z } from "zod";
 import {
   getAgentById,
+  getAgentWorkingOnContextKey,
   getAllAgents,
   getLatestActiveTaskByContextKey,
   getLatestTaskByContextKey,
   getLeadAgent,
   isExtensionAgent,
 } from "@/be/db";
+import { resolveIdentity } from "@/be/identity";
+import { recordUnmappedIdentity } from "@/be/unmapped-identities";
 import { dispatchPre } from "@/extensions/dispatcher";
 import { resolveTemplate } from "@/prompts/resolver";
 import { chatSdkContextKey } from "@/tasks/context-key";
@@ -21,19 +24,25 @@ import {
   buildChatAttachmentText,
   createChatTaskWithFiles,
   fetchChatFiles,
+  formatTooLargeReply,
   toChatFiles,
+  transcribeChatAudio,
 } from "./attachments";
 import { getChatThreadResetAt } from "./commands";
+import { type ChatAddressedReason, formatChatHeaderFacts, readChatMessageFacts } from "./facts";
 import { errorMessage } from "./logger";
-import { emitChatMessageSent } from "./outbound";
+import { emitChatMessageSent, postChatMessage } from "./outbound";
 import {
   type ChatAgentMatch,
   type ChatRouteTarget,
+  chatOwnerWindowStart,
+  getChatChannelMapping,
+  hasRoutingToken,
   routeChatMessage,
   stripRoutingTokens,
 } from "./router";
 import { getChatInstance } from "./runtime";
-import { readPersistedThreadHistory } from "./state";
+import { readPersistedThreadHistory, SqliteChatState } from "./state";
 import { formatChatSteeringAck, requestChatThreadSteering } from "./steering";
 import {
   bufferChatMessage,
@@ -109,11 +118,37 @@ export async function handleChatInbound(
   if (immediate) text = text.replace(/^!now\s*/i, "").trim();
   const attachments = message.attachments ?? [];
 
+  const facts = readChatMessageFacts(thread, message);
+  const isDirectMessage = kind === "dm" || thread.isDM;
+  const mentioned = kind === "mention" || message.isMention === true;
+  let addressed: ChatAddressedReason = isDirectMessage
+    ? "dm"
+    : facts.replyToBot
+      ? "reply-to-bot"
+      : mentioned
+        ? "mention"
+        : "none";
+  // A Telegram group is one shared conversation, not a thread about the task:
+  // an unaddressed message there is side chatter unless its sender asked for
+  // the thread's open task. Chatter neither steers nor reaches the router.
+  if (addressed === "none" && (facts.chatType === "group" || facts.chatType === "supergroup")) {
+    const unaddressed = await classifyUnaddressedGroupMessage(thread, message.author.userId, text);
+    if (unaddressed === "chatter") {
+      console.log(
+        `[chat-sdk] ${thread.id}: unaddressed group message from a non-requester, ignored`,
+      );
+      return;
+    }
+    if (unaddressed === "requester-follow-up") addressed = unaddressed;
+  }
+
   // A thread with messages already waiting keeps its order: append, do not steer past them.
+  // Another sender's message takes the buffer, so it gets its own header and requester.
   if (!immediate && attachments.length === 0 && text && !isChatThreadBuffered(thread.id)) {
     const steering = await requestChatThreadSteering({
       contextKey: chatSdkContextKey(thread.id),
       message: text,
+      resolveSender: () => resolveChatSender(adapter, message.author.userId),
     });
     if (steering) {
       console.log(
@@ -148,8 +183,10 @@ export async function handleChatInbound(
       text,
       userId: message.author.userId,
       userName: message.author.userName || undefined,
-      botMentioned: kind === "mention" || message.isMention === true,
-      isDirectMessage: kind === "dm" || thread.isDM,
+      botMentioned: mentioned || facts.replyToBot,
+      isDirectMessage,
+      addressed,
+      facts,
       attachments,
     });
     // Subscribed-thread messages may be dropped by the router at flush time;
@@ -159,6 +196,76 @@ export async function handleChatInbound(
   if (immediate) await instantFlushChat(thread.id);
 }
 
+const REQUESTER_KEY_PREFIX = "swarm:requester:";
+const REQUESTER_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** Platform user id of whoever asked for the thread's latest task. */
+async function rememberChatThreadRequester(threadId: string, userId: string): Promise<void> {
+  try {
+    await new SqliteChatState().set(`${REQUESTER_KEY_PREFIX}${threadId}`, userId, REQUESTER_TTL_MS);
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not store the thread requester: ${errorMessage(error)}`);
+  }
+}
+
+/**
+ * An unaddressed message outside a DM. `routable`: a routing token or an
+ * agent channel mapping routes it whoever sent it. `requester-follow-up`: its
+ * sender asked for the thread's task and the owner window is open. Anything
+ * else is `chatter`.
+ */
+async function classifyUnaddressedGroupMessage(
+  thread: Thread,
+  senderId: string,
+  text: string,
+): Promise<"routable" | "requester-follow-up" | "chatter"> {
+  if (hasRoutingToken(text)) return "routable";
+  if ((await getChatChannelMapping(thread.adapter.name, thread.channelId))?.agentId) {
+    return "routable";
+  }
+  const owner = await getAgentWorkingOnContextKey(
+    chatSdkContextKey(thread.id),
+    "chat",
+    chatOwnerWindowStart(),
+  );
+  if (!owner) return "chatter";
+  const requester = await new SqliteChatState().get<string>(`${REQUESTER_KEY_PREFIX}${thread.id}`);
+  return requester === senderId ? "requester-follow-up" : "chatter";
+}
+
+/**
+ * Canonical user behind a chat sender, through the same identity registry as
+ * Slack: `(<adapter>, <platform user id>)` in `user_external_ids`. An unknown
+ * sender goes to the Unmapped tracker and the task has no requester.
+ */
+async function resolveChatRequester(
+  adapter: string,
+  item: ChatBufferedMessage,
+): Promise<string | undefined> {
+  return resolveChatSender(adapter, item.userId, {
+    sampleEventType: "chat.message",
+    sampleContext: `${item.facts.from}: ${item.text}`,
+  });
+}
+
+/** {@link resolveChatRequester} for a bare sender id; records it as unmapped only when `sample` is set. */
+async function resolveChatSender(
+  adapter: string,
+  userId: string,
+  sample?: { sampleEventType: string; sampleContext: string },
+): Promise<string | undefined> {
+  // Telegram `sender_chat` posts (anonymous admins, linked channels) are no person.
+  if (!userId || userId.startsWith("chat:")) return undefined;
+  try {
+    const resolution = await resolveIdentity(adapter, userId);
+    if (resolution.status === "resolved") return resolution.userId;
+    if (sample) await recordUnmappedIdentity(adapter, userId, sample);
+  } catch (error) {
+    console.warn(`[chat-sdk] Could not resolve the requester: ${errorMessage(error)}`);
+  }
+  return undefined;
+}
+
 /**
  * Earlier messages of the thread for the task description, minus the flushed
  * ones and anything before the last `/reset`. The adapter's view is merged with
@@ -265,6 +372,11 @@ export async function flushChatThread(
     .join("\n---\n");
   const botMentioned = items.some((item) => item.botMentioned);
   const isDirectMessage = items.some((item) => item.isDirectMessage);
+  // The task's requester: the first sender who addressed the swarm.
+  const requester = items.find((item) => item.addressed !== "none") ?? first;
+  // One task carries every sender's text, so a batch from several people
+  // gets no requester: one sender's identity must not vouch for another's words.
+  const otherSenders = new Set(items.map((item) => item.userId)).size - 1;
 
   // After `/reset` the thread's earlier tasks are not context: the new task gets
   // no parent and no thread history older than the reset.
@@ -285,6 +397,9 @@ export async function flushChatThread(
       text: rawText,
       botMentioned,
       isDirectMessage,
+      ...(first.facts.chatType ? { chatType: first.facts.chatType } : {}),
+      ...(first.facts.isForum ? { isForum: true } : {}),
+      replyToBot: items.some((item) => item.facts.replyToBot),
       ...(mostRecentTask ? { threadContext: { adapter, threadId } } : {}),
     },
     {
@@ -354,7 +469,19 @@ export async function flushChatThread(
   const body = stripRoutingTokens(rawText);
   const files = items.flatMap((item) => toChatFiles(adapter, item.messageId, item.attachments));
   await using inbound = await fetchChatFiles(files);
-  const fileText = buildChatAttachmentText(inbound.files, inbound.failed);
+  const tooLarge = inbound.failed.filter((failure) => failure.tooLarge);
+  if (tooLarge.length > 0) {
+    // The user would otherwise never learn the file was dropped.
+    try {
+      await postChatMessage({ adapter, threadId, text: formatTooLargeReply(tooLarge) });
+    } catch (error) {
+      console.warn(
+        `[chat-sdk] ${threadId}: could not post the too-large reply: ${errorMessage(error)}`,
+      );
+    }
+  }
+  const notes = await transcribeChatAudio(inbound.fetched);
+  const fileText = buildChatAttachmentText(inbound.files, inbound.failed, notes);
   const combined = [body, fileText].filter(Boolean).join("\n\n");
   const marked =
     items.length > 1
@@ -364,9 +491,26 @@ export async function flushChatThread(
     mostRecentTask && thread
       ? await getChatThreadContext(thread, new Set(items.map((item) => item.messageId)), resetAt)
       : "";
-  const description = threadContext
-    ? `${resolveTemplate("chat.message.thread_context", { thread_messages: threadContext }).text}\n\n${marked}`
-    : marked;
+  const header = resolveTemplate("chat.message.header", {
+    chat_facts: formatChatHeaderFacts(
+      adapter,
+      otherSenders > 0
+        ? { ...requester.facts, from: `${requester.facts.from} +${otherSenders} more` }
+        : requester.facts,
+      requester.addressed,
+    ),
+  }).text;
+  const description = [
+    header,
+    threadContext
+      ? resolveTemplate("chat.message.thread_context", { thread_messages: threadContext }).text
+      : "",
+    marked,
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+  const requestedByUserId =
+    otherSenders > 0 ? undefined : await resolveChatRequester(adapter, requester);
 
   const latestActive = await getLatestActiveTaskByContextKey(contextKey, "chat");
   const dependsOn = !immediate && latestActive ? [latestActive.id] : undefined;
@@ -382,7 +526,10 @@ export async function flushChatThread(
       priority: 70,
       contextKey,
       dependsOn,
+      requestedByUserId,
       parentTaskId: mostRecentTask?.id,
+      // The parent's requester asked an earlier message: an unknown sender stays unattributed.
+      inheritParentRequester: false,
       // A human message in the thread: never answer it in the previous task's
       // structured-output contract.
       inheritParentOutputSchema: false,
@@ -404,6 +551,7 @@ export async function flushChatThread(
     }
   }
   if (created > 0) {
+    await rememberChatThreadRequester(threadId, requester.userId);
     await subscribe(thread);
     // Subscribed-thread messages start typing only here, once a task exists.
     startTypingKeepalive(adapter, threadId);

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

@@ -19,6 +19,30 @@ export function chatMessageLimit(adapter: string): number {
   return CHAT_MESSAGE_LIMITS[adapter] ?? FALLBACK_LIMIT;
 }
 
+const MB = 1024 * 1024;
+
+/**
+ * Per-file outbound upload ceiling, in bytes. Every adapter is capped at
+ * 50 MB, the task attachment cap, because a file is read into memory before
+ * it is sent. Telegram's Bot API takes 50 MB per upload (photos 10 MB, see
+ * `TELEGRAM_PHOTO_LIMIT`); Discord takes 10 MB without a server boost.
+ */
+const CHAT_UPLOAD_LIMITS: Record<string, number> = {
+  telegram: 50 * MB,
+  discord: 10 * MB,
+};
+const FALLBACK_UPLOAD_LIMIT = 50 * MB;
+
+/** Telegram sends a larger image with `sendDocument` instead of `sendPhoto`. */
+export const TELEGRAM_PHOTO_LIMIT = 10 * MB;
+
+export function chatUploadLimit(adapter: string): number {
+  return CHAT_UPLOAD_LIMITS[adapter] ?? FALLBACK_UPLOAD_LIMIT;
+}
+
+/** Most files one platform message can carry (Telegram media groups, Discord). */
+export const CHAT_FILES_PER_MESSAGE = 10;
+
 /**
  * Split `text` into chunks of at most `limit` characters. A chunk ends at the
  * last line break inside the window, else at the last space, else at the

package/src/integrations/chat-sdk/outbound-files.ts

@@ -0,0 +1,186 @@
+/**
+ * Files an agent sends to a chat thread: task attachments, read through the
+ * active file provider, and agent-fs paths, read with the caller's own agent-fs
+ * credential. `postChatMessage` sends them.
+ */
+import { getResolvedConfig, getTaskAttachments } from "@/be/db";
+import { backingProviderId, scopeFromAttachment } from "@/be/task-attachment-store";
+import { AgentFsProvider } from "@/fs/agent-fs-provider";
+import {
+  type FileScope,
+  type FileStorageProvider,
+  FilesError,
+  normalizeStoredKey,
+} from "@/fs/provider";
+import { getFileStorageProvider } from "@/fs/registry";
+import type { TaskAttachment } from "@/types";
+import { createValueScrubber } from "@/utils/secret-scrubber";
+import { SHARED_FILE_INTENT } from "./attachments";
+import { errorMessage } from "./logger";
+import { ChatFileTooLargeError, type OutboundChatFile } from "./outbound";
+
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** The caller's own agent-fs credential and default drive. Never the API's `API_AGENT_FS_API_KEY`. */
+export type CallerAgentFs = { apiUrl: string; apiKey: string; orgId: string; driveId: string };
+
+async function download(
+  scope: FileScope,
+  maxBytes: number,
+  provider: Pick<FileStorageProvider, "download"> = getFileStorageProvider(),
+): Promise<{ data: Uint8Array; mimeType?: string }> {
+  const response = await provider.download(scope);
+  const length = Number(response.headers.get("content-length"));
+  if (Number.isFinite(length) && length > maxBytes) {
+    await response.body?.cancel();
+    throw new ChatFileTooLargeError(length);
+  }
+  const data = new Uint8Array(await response.arrayBuffer());
+  if (data.byteLength > maxBytes) throw new ChatFileTooLargeError(data.byteLength);
+  return { data, mimeType: response.headers.get("content-type") ?? undefined };
+}
+
+/** A task attachment as a file to send, or undefined when the active provider does not hold its bytes. */
+export function chatFileOfTaskAttachment(attachment: TaskAttachment): OutboundChatFile | undefined {
+  if (backingProviderId(attachment) !== getFileStorageProvider().id) return undefined;
+  return {
+    name: attachment.name,
+    mimeType: attachment.mimeType,
+    sizeBytes: attachment.sizeBytes,
+    load: (maxBytes) => download(scopeFromAttachment(attachment), maxBytes),
+  };
+}
+
+/**
+ * The segments of a tool-supplied path, each decoded once and checked, so an
+ * encoded `..`, separator, `?` or `#` cannot leave the drive or change the endpoint.
+ */
+function pathSegments(path: string): string[] {
+  return normalizeStoredKey(path)
+    .split("/")
+    .map((segment) => {
+      let decoded = segment;
+      try {
+        decoded = decodeURIComponent(segment);
+      } catch {
+        // A lone `%` is part of the name; it is encoded below.
+      }
+      if (!decoded || decoded === "." || decoded === ".." || /[/\\\0]/.test(decoded)) {
+        throw new FilesError(
+          "Provider",
+          "Path must not contain empty, `.` or `..` segments, or encoded separators",
+        );
+      }
+      return decoded;
+    });
+}
+
+/** The agent-fs credential and drive the caller itself holds, or undefined when it has none. */
+async function callerAgentFs(agentId: string | undefined): Promise<CallerAgentFs | undefined> {
+  if (!agentId) return undefined;
+  const configs = await getResolvedConfig(agentId);
+  const value = (key: string) => configs.find((c) => c.key === key)?.value?.trim();
+  const apiUrl = value("AGENT_FS_API_URL") || process.env.AGENT_FS_API_URL?.trim();
+  const apiKey = value("AGENT_FS_API_KEY");
+  const orgId = value("AGENT_FS_DEFAULT_ORG_ID");
+  const driveId = value("AGENT_FS_DEFAULT_DRIVE_ID");
+  return apiUrl && apiKey && orgId && driveId ? { apiUrl, apiKey, orgId, driveId } : undefined;
+}
+
+/**
+ * A file at a path of the caller's agent-fs drive, read with the caller's own
+ * credential: a path the caller cannot read is not sent, and the thread gets a note.
+ */
+export function chatFileOfPath(path: string, access: CallerAgentFs): OutboundChatFile {
+  const segments = pathSegments(path);
+  const name = segments.at(-1)!;
+  const key = segments.map(encodeURIComponent).join("/");
+  // The caller's key can be shorter than the global scrubber's floor, so a
+  // storage error body or transport error is scrubbed of it by exact value.
+  const keyScrubber = createValueScrubber([{ value: access.apiKey, name: "AGENT_FS_API_KEY" }]);
+  return {
+    name,
+    load: async (maxBytes) => {
+      try {
+        return await download(
+          { taskId: "chat", name, key, orgId: access.orgId, driveId: access.driveId },
+          maxBytes,
+          new AgentFsProvider(access),
+        );
+      } catch (error) {
+        if (error instanceof ChatFileTooLargeError) throw error;
+        if (error instanceof FilesError && error.code === "Unauthorized") {
+          throw new Error("your agent-fs credential cannot read this path");
+        }
+        throw new Error(keyScrubber.text(error instanceof Error ? error.message : String(error)));
+      }
+    },
+  };
+}
+
+/**
+ * Resolve the `attachments` of `chat-reply` and `chat-post`: an attachment id
+ * of `taskId`, or an agent-fs path read as `agentId`. Returns an error naming
+ * the first entry that cannot be sent, so the tool refuses before posting anything.
+ */
+export async function resolveChatAttachmentRefs(
+  refs: string[],
+  taskId: string | undefined,
+  agentId: string | undefined,
+): Promise<{ files: OutboundChatFile[] } | { error: string }> {
+  let taskAttachments: TaskAttachment[] | undefined;
+  let access: CallerAgentFs | undefined | null = null;
+  const files: OutboundChatFile[] = [];
+  for (const ref of refs) {
+    if (UUID_PATTERN.test(ref)) {
+      if (!taskId) return { error: `Attachment ${ref}: no current task to look it up in.` };
+      taskAttachments ??= await getTaskAttachments(taskId);
+      const attachment = taskAttachments.find((a) => a.id === ref);
+      if (!attachment)
+        return { error: `Attachment ${ref} is not an attachment of task ${taskId}.` };
+      const file = chatFileOfTaskAttachment(attachment);
+      if (!file) {
+        return {
+          error: `Attachment ${ref} (${attachment.kind}) is not stored in the swarm file provider, so it cannot be sent as a file. Post its link instead.`,
+        };
+      }
+      files.push(file);
+      continue;
+    }
+    if (access === null) access = await callerAgentFs(agentId);
+    if (!access) {
+      return {
+        error: `Path ${ref}: you have no agent-fs credential and drive to read it with. Attach the file to your task and send its attachment id.`,
+      };
+    }
+    try {
+      files.push(chatFileOfPath(ref, access));
+    } catch (error) {
+      return { error: `Path ${ref}: ${errorMessage(error)}` };
+    }
+  }
+  return { files };
+}
+
+/** A Slack file an agent fetched into its task; recorded with that agent's id. */
+const FETCHED_SLACK_FILE_INTENT = "slack-file";
+
+/**
+ * The output files of a task, for the result relay: attachments an agent
+ * added that the active provider holds. Input files (a user's upload, a Slack
+ * file an agent fetched) are left out, as the Slack relay does, so they are not
+ * echoed back or carried into another chat thread.
+ */
+export async function taskOutputChatFiles(taskId: string): Promise<OutboundChatFile[]> {
+  return (await getTaskAttachments(taskId)).flatMap((attachment) => {
+    if (attachment.agentId === null) return [];
+    if (
+      attachment.intent === SHARED_FILE_INTENT ||
+      attachment.intent === FETCHED_SLACK_FILE_INTENT
+    ) {
+      return [];
+    }
+    const file = chatFileOfTaskAttachment(attachment);
+    return file ? [file] : [];
+  });
+}