@desplega.ai/agent-swarm 2.4.4 → 2.4.5

package/src/tests/transcription.test.ts

@@ -0,0 +1,299 @@
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import {
+  isTranscriptionConfigured,
+  NOT_TRANSCRIBED_NOTE,
+  resolveTranscriptionConfig,
+  TRANSCRIPTION_ENV_KEYS,
+  TranscriptionError,
+  transcribeAudio,
+  transcribeAudioNotes,
+} from "../utils/transcription";
+
+// Includes the provider keys the fallback reads: a worker shell often has
+// OPENAI_API_KEY or ELEVENLABS_API_KEY set, which would leak into every test.
+const ENV_KEYS = TRANSCRIPTION_ENV_KEYS;
+const savedEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]]));
+
+type Captured = {
+  path: string;
+  authorization: string | null;
+  xiApiKey: string | null;
+  fields: string[];
+  model: FormDataEntryValue | null;
+  modelId: FormDataEntryValue | null;
+  filename: string;
+};
+
+const captured: Captured[] = [];
+// The file part's Content-Type as sent. Bun's `formData()` re-derives a File's
+// type from its extension (`.webm` reads back as video/webm), so read it raw.
+const sentFileTypes: string[] = [];
+let reply: () => Response = () => Response.json({ text: " hello " });
+let stt: ReturnType<typeof Bun.serve>;
+
+beforeAll(() => {
+  for (const key of ENV_KEYS) delete process.env[key];
+  stt = Bun.serve({
+    port: 0,
+    hostname: "127.0.0.1",
+    async fetch(req) {
+      const raw = await req.clone().text();
+      sentFileTypes.push(
+        /name="file"; filename="[^"]*"\r\nContent-Type: ([^\r\n]+)/.exec(raw)?.[1] ?? "",
+      );
+      const form = await req.formData();
+      captured.push({
+        path: new URL(req.url).pathname,
+        authorization: req.headers.get("authorization"),
+        xiApiKey: req.headers.get("xi-api-key"),
+        fields: [...form.keys()].sort(),
+        model: form.get("model"),
+        modelId: form.get("model_id"),
+        filename: (form.get("file") as File).name,
+      });
+      return reply();
+    },
+  });
+});
+
+afterAll(() => {
+  stt.stop(true);
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+afterEach(() => {
+  captured.length = 0;
+  sentFileTypes.length = 0;
+  reply = () => Response.json({ text: " hello " });
+  for (const key of ENV_KEYS) delete process.env[key];
+});
+
+function configure(provider?: string) {
+  process.env.TRANSCRIPTION_API_KEY = "stt-test-key-123456";
+  process.env.TRANSCRIPTION_BASE_URL = `http://127.0.0.1:${stt.port}/v1`;
+  if (provider) process.env.TRANSCRIPTION_PROVIDER = provider;
+}
+
+const audio = {
+  data: new Blob([new Uint8Array([1, 2, 3])]),
+  filename: "note.ogg",
+  mimeType: "audio/ogg",
+};
+
+describe("transcribeAudio request shape", () => {
+  test("elevenlabs posts to /speech-to-text with xi-api-key and model_id", async () => {
+    configure("elevenlabs");
+    expect(await transcribeAudio(audio)).toBe("hello");
+    expect(captured).toEqual([
+      {
+        path: "/v1/speech-to-text",
+        authorization: null,
+        xiApiKey: "stt-test-key-123456",
+        fields: ["file", "model_id"],
+        model: null,
+        modelId: "scribe_v2",
+        filename: "note.ogg",
+      },
+    ]);
+  });
+
+  test("elevenlabs honours TRANSCRIPTION_MODEL in model_id", async () => {
+    configure("ElevenLabs");
+    process.env.TRANSCRIPTION_MODEL = "scribe_v1";
+    await transcribeAudio(audio);
+    expect(captured[0]).toMatchObject({ fields: ["file", "model_id"], modelId: "scribe_v1" });
+  });
+
+  test("negative control: the default provider keeps the OpenAI shape", async () => {
+    configure();
+    expect(await transcribeAudio(audio)).toBe("hello");
+    expect(captured).toEqual([
+      {
+        path: "/v1/audio/transcriptions",
+        authorization: "Bearer stt-test-key-123456",
+        xiApiKey: null,
+        fields: ["file", "model"],
+        model: "whisper-1",
+        modelId: null,
+        filename: "note.ogg",
+      },
+    ]);
+  });
+
+  test("an unknown provider fails before any request", async () => {
+    configure("deepgram");
+    await expect(transcribeAudio(audio)).rejects.toThrow(
+      new TranscriptionError(
+        'TRANSCRIPTION_PROVIDER "deepgram" is not supported (use openai, groq, elevenlabs)',
+      ),
+    );
+    expect(captured).toHaveLength(0);
+  });
+
+  test("an elevenlabs error detail is surfaced with the key scrubbed", async () => {
+    configure("elevenlabs");
+    reply = () =>
+      Response.json(
+        { detail: { status: "invalid_api_key", message: "Invalid key stt-test-key-123456" } },
+        { status: 401 },
+      );
+    await expect(transcribeAudio(audio)).rejects.toThrow(
+      "Invalid key [REDACTED:TRANSCRIPTION_API_KEY]",
+    );
+  });
+});
+
+describe("provider key fallback", () => {
+  // Built at runtime so the secret scanner does not read them as keys.
+  const fake = (provider: string) => [provider, "fixture", "value"].join("-");
+  const ELEVEN_FAKE = fake("eleven");
+  const OPENAI_FAKE = fake("openai");
+  const GROQ_FAKE = fake("groq");
+
+  // Auto-detected keys always go to the provider's public endpoint, so record
+  // that URL and forward the request to the local stub on the same path.
+  const realFetch = globalThis.fetch;
+  const calledUrls: string[] = [];
+  beforeEach(() => {
+    calledUrls.length = 0;
+    globalThis.fetch = (async (input: string | URL | Request, init?: RequestInit) => {
+      const url = new URL(String(input));
+      calledUrls.push(url.href);
+      return realFetch(`http://127.0.0.1:${stt.port}${url.pathname}`, init);
+    }) as typeof fetch;
+  });
+  afterEach(() => {
+    globalThis.fetch = realFetch;
+  });
+
+  test("no key at all means not configured", async () => {
+    expect(resolveTranscriptionConfig()).toBeNull();
+    expect(isTranscriptionConfigured()).toBe(false);
+    const notes = await transcribeAudioNotes([{ key: "a", name: "a.ogg", data: audio.data }], "t");
+    expect(notes.get("a")).toBe(NOT_TRANSCRIBED_NOTE);
+    expect(NOT_TRANSCRIBED_NOTE).toBe(
+      "(not transcribed: no transcription provider configured, set TRANSCRIPTION_API_KEY or one of ELEVENLABS_API_KEY, OPENAI_API_KEY, GROQ_API_KEY)",
+    );
+    expect(calledUrls).toHaveLength(0);
+  });
+
+  test("ELEVENLABS_API_KEY alone uses the elevenlabs shape", async () => {
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    expect(resolveTranscriptionConfig()).toMatchObject({
+      provider: "elevenlabs",
+      keyEnv: "ELEVENLABS_API_KEY",
+      source: "auto",
+    });
+    expect(await transcribeAudio(audio)).toBe("hello");
+    expect(calledUrls).toEqual(["https://api.elevenlabs.io/v1/speech-to-text"]);
+    expect(captured[0]).toMatchObject({
+      xiApiKey: ELEVEN_FAKE,
+      authorization: null,
+      modelId: "scribe_v2",
+    });
+  });
+
+  test("OPENAI_API_KEY alone uses the openai shape", async () => {
+    process.env.OPENAI_API_KEY = OPENAI_FAKE;
+    expect(resolveTranscriptionConfig()).toMatchObject({ provider: "openai", source: "auto" });
+    await transcribeAudio(audio);
+    expect(calledUrls).toEqual(["https://api.openai.com/v1/audio/transcriptions"]);
+    expect(captured[0]).toMatchObject({
+      authorization: `Bearer ${OPENAI_FAKE}`,
+      model: "whisper-1",
+    });
+  });
+
+  test("GROQ_API_KEY alone uses Groq's OpenAI-compatible endpoint and whisper model", async () => {
+    process.env.GROQ_API_KEY = GROQ_FAKE;
+    expect(resolveTranscriptionConfig()).toMatchObject({
+      provider: "groq",
+      keyEnv: "GROQ_API_KEY",
+    });
+    await transcribeAudio(audio);
+    expect(calledUrls).toEqual(["https://api.groq.com/openai/v1/audio/transcriptions"]);
+    expect(captured[0]).toMatchObject({
+      authorization: `Bearer ${GROQ_FAKE}`,
+      model: "whisper-large-v3-turbo",
+    });
+  });
+
+  test("ElevenLabs wins over OpenAI and Groq when all are set", async () => {
+    process.env.OPENAI_API_KEY = OPENAI_FAKE;
+    process.env.GROQ_API_KEY = GROQ_FAKE;
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    await transcribeAudio(audio);
+    expect(captured[0]).toMatchObject({ xiApiKey: ELEVEN_FAKE, authorization: null });
+  });
+
+  test("OpenAI wins over Groq", () => {
+    process.env.GROQ_API_KEY = GROQ_FAKE;
+    process.env.OPENAI_API_KEY = OPENAI_FAKE;
+    expect(resolveTranscriptionConfig()?.provider).toBe("openai");
+  });
+
+  test("an explicit TRANSCRIPTION_API_KEY overrides both detected keys", async () => {
+    process.env.OPENAI_API_KEY = OPENAI_FAKE;
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    configure();
+    expect(resolveTranscriptionConfig()).toMatchObject({
+      provider: "openai",
+      keyEnv: "TRANSCRIPTION_API_KEY",
+      source: "explicit",
+    });
+    await transcribeAudio(audio);
+    // The explicit key honours TRANSCRIPTION_BASE_URL.
+    expect(calledUrls).toEqual([`http://127.0.0.1:${stt.port}/v1/audio/transcriptions`]);
+    expect(captured[0]).toMatchObject({
+      authorization: "Bearer stt-test-key-123456",
+      xiApiKey: null,
+    });
+  });
+
+  test("an auto-detected key never goes to TRANSCRIPTION_BASE_URL", async () => {
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    process.env.TRANSCRIPTION_BASE_URL = "https://collector.example/v1";
+    await transcribeAudio(audio);
+    expect(calledUrls).toEqual(["https://api.elevenlabs.io/v1/speech-to-text"]);
+  });
+
+  test("a pinned provider uses only its own key", async () => {
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    process.env.OPENAI_API_KEY = OPENAI_FAKE;
+    process.env.TRANSCRIPTION_PROVIDER = "openai";
+    await transcribeAudio(audio);
+    expect(captured[0]).toMatchObject({ authorization: `Bearer ${OPENAI_FAKE}` });
+
+    delete process.env.OPENAI_API_KEY;
+    expect(isTranscriptionConfigured()).toBe(false);
+  });
+
+  test("a detected key is scrubbed from errors under its own name", async () => {
+    process.env.ELEVENLABS_API_KEY = ELEVEN_FAKE;
+    reply = () => Response.json({ detail: `bad key ${ELEVEN_FAKE}` }, { status: 401 });
+    await expect(transcribeAudio(audio)).rejects.toThrow("bad key [REDACTED:ELEVENLABS_API_KEY]");
+  });
+
+  // The composer's mic button records webm in Chrome and Firefox; the upload
+  // route drops `;codecs=` before it gets here. Each provider reads the format
+  // from the file name, and all three list webm as supported.
+  test.each([
+    ["elevenlabs", "ELEVENLABS_API_KEY", "https://api.elevenlabs.io/v1/speech-to-text"],
+    ["openai", "OPENAI_API_KEY", "https://api.openai.com/v1/audio/transcriptions"],
+    ["groq", "GROQ_API_KEY", "https://api.groq.com/openai/v1/audio/transcriptions"],
+  ])("a recorded webm clip reaches %s as a .webm audio/webm file", async (name, keyEnv, url) => {
+    process.env[keyEnv] = fake(name);
+    const clip = new Blob([new Uint8Array([0x1a, 0x45, 0xdf, 0xa3])], { type: "audio/webm" });
+    const notes = await transcribeAudioNotes(
+      [{ key: "c", name: "recording-2026-10-21-143005.webm", data: clip, mimeType: "audio/webm" }],
+      "t",
+    );
+    expect(notes.get("c")).toBe("[Transcript of recording-2026-10-21-143005.webm]\nhello");
+    expect(calledUrls).toEqual([url]);
+    expect(captured[0]).toMatchObject({ filename: "recording-2026-10-21-143005.webm" });
+    expect(sentFileTypes).toEqual(["audio/webm"]);
+  });
+});

package/src/tests/workflow-system-one-decision-providers.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { unlink } from "node:fs/promises";
 import { closeDb, getDbClient, initDb, upsertSwarmConfig } from "../be/db";
+import { SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS, validateConfigValue } from "../be/swarm-config-guard";
 import type { WorkflowNode } from "../types";
 import { validateDefinition } from "../workflows/definition";
 import { InProcessEventBus } from "../workflows/event-bus";
@@ -11,6 +12,7 @@ import {
   SystemOneDecisionExecutor,
   type SystemOneDecisionExecutorOptions,
 } from "../workflows/executors/system-one-decision";
+import { SYSTEM_ONE_PROVIDER_IDS } from "../workflows/executors/system-one-providers";
 import { interpolate } from "../workflows/template";
 
 const TEST_DB_PATH = "./test-workflow-system-one-decision-providers.sqlite";
@@ -50,7 +52,7 @@ afterAll(async () => {
 
 beforeEach(async () => {
   await getDbClient().run(
-    "DELETE FROM swarm_config WHERE key IN ('OPENAI_API_KEY', 'OPENAI_DECISIONS_API_KEY', 'CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN')",
+    "DELETE FROM swarm_config WHERE key IN ('OPENAI_API_KEY', 'OPENAI_DECISIONS_API_KEY', 'CLOUDFLARE_ACCOUNT_ID', 'CLOUDFLARE_API_TOKEN', 'SYSTEM_ONE_DEFAULT_PROVIDER')",
   );
 });
 
@@ -708,6 +710,101 @@ describe("system-one-decision openai provider", () => {
   });
 });
 
+// ─── Default provider ───────────────────────────────────────
+
+describe("system-one-decision default provider", () => {
+  const TYPESAFE_KEY = "typesafe-example-test-key-0123456789";
+  const jevBody = () =>
+    jsonResponse({
+      model: "jev",
+      answers: systemOneAnswers,
+      usage: { input_tokens: 1, output_tokens: 0 },
+    });
+  const setDefault = (value: string) =>
+    upsertSwarmConfig({ scope: "global", key: "SYSTEM_ONE_DEFAULT_PROVIDER", value });
+  const withTypesafeKey = {
+    getApiKey: async (id: string) =>
+      id === "typesafe" ? TYPESAFE_KEY : id === "cloudflare" ? CF_TOKEN : null,
+  };
+
+  test("unset, a node with no provider still calls typesafe", async () => {
+    const { executor, calls } = makeExecutor([jevBody()], withTypesafeKey);
+    const result = await run(executor, config());
+    expect(result.status).toBe("success");
+    expect(calls[0]?.url).toBe("https://api.typesafe.ai/v1/systemone");
+    expect(calls[0]?.body.model).toBe("jev-latest");
+    // The schema leaves the provider unset; the executor resolves it per run.
+    expect(SystemOneDecisionConfigSchema.parse(config()).provider).toBeUndefined();
+  });
+
+  test("set to cloudflare, a node with no provider calls Clef with no workflow edit", async () => {
+    await setDefault("cloudflare");
+    const { executor, calls } = makeExecutor([jsonResponse(clefEnvelope())], withTypesafeKey);
+    const result = await run(executor, config());
+    expect(result.status).toBe("success");
+    expect(calls[0]?.url).toBe(`${CF_BASE}/clef`);
+    expect((calls[0]?.init.headers as Record<string, string>).authorization).toBe(
+      `Bearer ${CF_TOKEN}`,
+    );
+    expect(result.output).toMatchObject({ model: "clef", answers: systemOneAnswers as never });
+  });
+
+  test("a node that names its provider keeps it", async () => {
+    await setDefault("cloudflare");
+    const { executor, calls } = makeExecutor([jevBody()], withTypesafeKey);
+    expect((await run(executor, config({ provider: "typesafe" }))).status).toBe("success");
+    expect(calls[0]?.url).toBe("https://api.typesafe.ai/v1/systemone");
+  });
+
+  test("readiness checks the default provider's credentials", async () => {
+    await setDefault("cloudflare");
+    const { executor } = makeExecutor([], { getApiKey: async () => null });
+    const problems = await executor.checkReadiness([{ id: "a", config: config() }]);
+    expect(problems).toHaveLength(1);
+    expect(problems[0]?.nodeIds).toEqual(["a"]);
+    expect(problems[0]?.message).toContain("CLOUDFLARE_API_TOKEN is not configured");
+  });
+
+  test("the environment is read when no row is stored; a stored row wins", async () => {
+    const env = { SYSTEM_ONE_DEFAULT_PROVIDER: "cloudflare" };
+    const fromEnv = makeExecutor([jsonResponse(clefEnvelope())], { ...withTypesafeKey, env });
+    expect((await run(fromEnv.executor, config())).status).toBe("success");
+    expect(fromEnv.calls[0]?.url).toBe(`${CF_BASE}/clef`);
+
+    await setDefault("typesafe");
+    const stored = makeExecutor([jevBody()], { ...withTypesafeKey, env });
+    expect((await run(stored.executor, config())).status).toBe("success");
+    expect(stored.calls[0]?.url).toBe("https://api.typesafe.ai/v1/systemone");
+  });
+
+  test("a defaulted provider's limits are checked at run, and nothing is sent", async () => {
+    await setDefault("cloudflare");
+    const qs: Record<string, unknown> = {};
+    const rs: Record<string, unknown> = {};
+    for (let i = 0; i < 65; i++) {
+      qs[`q${i}`] = { type: "noul", instructions: `Question ${i}?` };
+      rs[`q${i}`] = { type: "noul" };
+    }
+    const { executor, calls } = makeExecutor([jsonResponse(clefEnvelope())]);
+    const result = await run(executor, config({ questions: qs, returns: rs }));
+    expect(result.status).toBe("failed");
+    expect(result.error).toContain("at most 64 questions per node; this node has 65");
+    expect(calls).toHaveLength(0);
+  });
+
+  test("the config guard accepts exactly the decide hosts", () => {
+    expect([...SYSTEM_ONE_DEFAULT_PROVIDER_OPTIONS].sort()).toEqual(
+      [...SYSTEM_ONE_PROVIDER_IDS].sort(),
+    );
+    for (const id of SYSTEM_ONE_PROVIDER_IDS) {
+      expect(validateConfigValue("SYSTEM_ONE_DEFAULT_PROVIDER", id)).toBeNull();
+    }
+    expect(validateConfigValue("SYSTEM_ONE_DEFAULT_PROVIDER", "jev")).toContain(
+      "Invalid SYSTEM_ONE_DEFAULT_PROVIDER value",
+    );
+  });
+});
+
 // ─── Existing providers ─────────────────────────────────────
 
 describe("system-one-decision SystemOne wire is unchanged", () => {

package/src/tests/workflow-system-one-decision.test.ts

@@ -227,7 +227,8 @@ describe("system-one-decision config schema", () => {
       questions: { fit: { type: "noul", instructions: "Is it real?" } },
       returns: { fit: { type: "noul" } },
     });
-    expect(parsed.provider).toBe("typesafe");
+    // Unset: the executor reads SYSTEM_ONE_DEFAULT_PROVIDER at run time (typesafe when unset).
+    expect(parsed.provider).toBeUndefined();
     // The model default belongs to the provider, so the schema leaves it unset.
     expect(parsed.model).toBeUndefined();
     expect(parsed.timeoutMs).toBe(30_000);

package/src/tools/chat-access.ts

@@ -1,8 +1,18 @@
+import * as z from "zod";
 import { getAgentById, getAgentCurrentTask, getTaskById } from "@/be/db";
 import { can } from "@/rbac";
 import { chatThreadOfContextKey } from "@/tasks/context-key";
 import type { RequestInfo } from "@/tools/utils";
 
+/** The `attachments` input of `chat-reply` and `chat-post`. */
+export const chatAttachmentsSchema = z
+  .array(z.string().min(1))
+  .max(10)
+  .optional()
+  .describe(
+    "Files to send after the text, up to 10: attachment ids of your current task (from get-task-details) or file paths in your agent-fs drive, such as thoughts/<agent-id>/report.pdf, read with your own agent-fs credential. Telegram shows JPEG and PNG as photos, MP4 as video, MP3 and M4A as audio, and anything else as a document. A file over the platform upload limit (Telegram 50 MB, Discord 10 MB) is not sent, and the thread gets a note naming it.",
+  );
+
 /** Chat SDK verbs; the legacy policy grants them to the lead only. */
 export type ChatVerb = "integration.chat.post" | "integration.chat.read" | "integration.chat.dm";
 

package/src/tools/chat-post.ts

@@ -2,8 +2,13 @@ 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 {
+  adapterOfChatId,
+  postChatMessage,
+  unsentFilesSummary,
+} from "@/integrations/chat-sdk/outbound";
+import { resolveChatAttachmentRefs } from "@/integrations/chat-sdk/outbound-files";
+import { canUseChatVerb, chatAttachmentsSchema } from "@/tools/chat-access";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerChatPostTool = (server: McpServer) => {
@@ -27,6 +32,7 @@ export const registerChatPostTool = (server: McpServer) => {
           .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."),
+        attachments: chatAttachmentsSchema,
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
@@ -34,9 +40,12 @@ export const registerChatPostTool = (server: McpServer) => {
         adapter: z.string().optional(),
         threadId: z.string().optional(),
         channelId: z.string().optional(),
+        unsentFiles: z
+          .array(z.looseObject({ name: z.string().optional(), reason: z.string().optional() }))
+          .optional(),
       }),
     },
-    async ({ adapter, threadId, channelId, text }, requestInfo) => {
+    async ({ adapter, threadId, channelId, text, attachments }, requestInfo) => {
       const data = { yourAgentId: requestInfo.agentId };
       const target = threadId ?? channelId;
       if (!target) return toolErr("Give a threadId or a channelId.", { data });
@@ -49,22 +58,33 @@ export const registerChatPostTool = (server: McpServer) => {
           { data },
         );
       }
+      const resolved = await resolveChatAttachmentRefs(
+        attachments ?? [],
+        requestInfo.sourceTaskId,
+        requestInfo.agentId,
+      );
+      if ("error" in resolved) return toolErr(resolved.error, { data });
       try {
         const sent = await postChatMessage({
           adapter,
           ...(threadId ? { threadId } : { channelId }),
           text,
           taskId: requestInfo.sourceTaskId,
+          files: resolved.files,
         });
-        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,
+        return toolOk(
+          `Posted to ${adapter} ${threadId ? "thread" : "channel"} ${target}.${unsentFilesSummary(sent.unsentFiles)}`,
+          {
+            data: {
+              ...data,
+              messageId: sent.messageIds.at(-1),
+              adapter: sent.adapter,
+              threadId: sent.threadId,
+              channelId: sent.channelId,
+              unsentFiles: sent.unsentFiles,
+            },
           },
-        });
+        );
       } catch (error) {
         const message = errorMessage(error);
         return toolErr(`Could not post: ${message}`, { data });

package/src/tools/chat-reply.ts

@@ -2,8 +2,14 @@ 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 {
+  ChatAdapterUnavailableError,
+  postChatMessage,
+  unsentFilesSummary,
+} from "@/integrations/chat-sdk/outbound";
+import { resolveChatAttachmentRefs } from "@/integrations/chat-sdk/outbound-files";
 import { chatThreadOfContextKey } from "@/tasks/context-key";
+import { chatAttachmentsSchema } from "@/tools/chat-access";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerChatReplyTool = (server: McpServer) => {
@@ -12,19 +18,23 @@ export const registerChatReplyTool = (server: McpServer) => {
     {
       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.",
+        "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, a short progress note on long work, or to send files (attachments). Markdown is supported; long text is split into several messages. When the final output of a task is posted, the files attached to that task go with it.",
       annotations: { openWorldHint: true },
       inputSchema: z.object({
         text: z.string().min(1).max(20_000).describe("Markdown text to post to the thread."),
+        attachments: chatAttachmentsSchema,
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
         messageId: z.string().optional(),
         adapter: z.string().optional(),
         threadId: z.string().optional(),
+        unsentFiles: z
+          .array(z.looseObject({ name: z.string().optional(), reason: z.string().optional() }))
+          .optional(),
       }),
     },
-    async ({ text }, requestInfo) => {
+    async ({ text, attachments }, requestInfo) => {
       if (!requestInfo.agentId) return toolErr("Agent ID not found.");
       const data = { yourAgentId: requestInfo.agentId };
 
@@ -46,21 +56,33 @@ export const registerChatReplyTool = (server: McpServer) => {
         );
       }
 
+      const resolved = await resolveChatAttachmentRefs(
+        attachments ?? [],
+        task.id,
+        requestInfo.agentId,
+      );
+      if ("error" in resolved) return toolErr(resolved.error, { data });
+
       try {
         const sent = await postChatMessage({
           adapter: thread.adapter,
           threadId: thread.threadId,
           text,
           taskId: task.id,
+          files: resolved.files,
         });
-        return toolOk(`Posted to ${thread.adapter} thread ${sent.threadId}.`, {
-          data: {
-            ...data,
-            messageId: sent.messageIds.at(-1),
-            adapter: sent.adapter,
-            threadId: sent.threadId,
+        return toolOk(
+          `Posted to ${thread.adapter} thread ${sent.threadId}.${unsentFilesSummary(sent.unsentFiles)}`,
+          {
+            data: {
+              ...data,
+              messageId: sent.messageIds.at(-1),
+              adapter: sent.adapter,
+              threadId: sent.threadId,
+              unsentFiles: sent.unsentFiles,
+            },
           },
-        });
+        );
       } catch (error) {
         const message = errorMessage(error);
         return toolErr(

package/src/tools/memory-search.ts

@@ -11,6 +11,7 @@ import {
   recordRetrievals,
 } from "@/be/memory/raters/retrieval";
 import { rerank } from "@/be/memory/reranker";
+import { searchMemoryCandidates } from "@/be/memory/search-candidates";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import type { AgentMemorySource } from "@/types";
 import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
@@ -122,7 +123,8 @@ export const registerMemorySearchTool = (server: McpServer) => {
       const queryEmbedding = await provider.embed(query);
 
       const candidateLimit = limit * CANDIDATE_SET_MULTIPLIER;
-      const candidates = await store.search(
+      const candidates = await searchMemoryCandidates(
+        store,
         queryEmbedding ?? new Float32Array(0),
         requestInfo.agentId,
         {