@vellumai/vellum-gateway 0.5.13 → 0.5.15

package/ARCHITECTURE.md

@@ -53,14 +53,14 @@ The gateway exposes a REST API for reading and mutating assistant feature flags.
 
 **Token separation (authentication boundary):**
 
-The assistant feature flags API uses a dedicated feature-flag token stored at `~/.vellum/feature-flag-token`, separate from JWT auth tokens. This separation ensures that clients with feature-flag access cannot access runtime endpoints, and vice versa.
+The assistant feature flags API uses scope-based JWT auth. The gateway issues JWTs with `feature_flags.read` and `feature_flags.write` scopes to control access.
 
-| Operation                      | Accepted tokens                                                     |
-| ------------------------------ | ------------------------------------------------------------------- |
-| `GET /v1/feature-flags`        | JWT bearer token OR feature-flag token                              |
-| `PATCH /v1/feature-flags/:key` | Feature-flag token ONLY (JWT bearer tokens are explicitly rejected) |
+| Operation                      | Required scope        |
+| ------------------------------ | --------------------- |
+| `GET /v1/feature-flags`        | `feature_flags.read`  |
+| `PATCH /v1/feature-flags/:key` | `feature_flags.write` |
 
-The feature-flag token is auto-generated on first gateway startup if the file does not exist. The gateway watches the token file for changes and hot-reloads without restart.
+The assistant daemon does not read or distribute a feature-flag token. All feature-flag auth flows go through the gateway's scoped JWT mechanism.
 
 **Protected feature flag store:** The canonical storage for assistant feature flag overrides is `~/.vellum/protected/feature-flags.json` (local) or `GATEWAY_SECURITY_DIR/feature-flags.json` (Docker). The store is managed by `gateway/src/feature-flag-store.ts` and uses a versioned JSON format with `Record<string, boolean>` values keyed by canonical flag keys (simple kebab-case, e.g., `browser`). The gateway's PATCH handler writes exclusively to this store. The daemon's resolver reads it with highest priority, falling back to the defaults registry. Undeclared keys are ignored by the resolver.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/vellum-gateway",
-  "version": "0.5.13",
+  "version": "0.5.15",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/schema.test.ts

@@ -55,6 +55,7 @@ describe("/schema route", () => {
     expect(body.paths["/readyz"]).toBeDefined();
     expect(body.paths["/schema"]).toBeDefined();
     expect(body.paths["/v1/health"]).toBeDefined();
+    expect(body.paths["/v1/healthz"]).toBeDefined();
     expect(body.paths["/webhooks/telegram"]).toBeDefined();
     expect(body.paths["/webhooks/twilio/voice"]).toBeDefined();
     expect(body.paths["/webhooks/twilio/status"]).toBeDefined();

package/src/feature-flag-registry.json

@@ -289,6 +289,14 @@
       "description": "Auto-expand completed tool call step groups instead of showing them collapsed",
       "defaultEnabled": false
     },
+    {
+      "id": "show-thinking-blocks",
+      "scope": "macos",
+      "key": "show-thinking-blocks",
+      "label": "Show Thinking Blocks",
+      "description": "Display the assistant's thinking/reasoning inline in chat messages as collapsible blocks",
+      "defaultEnabled": false
+    },
     {
       "id": "inline-skill-commands",
       "scope": "assistant",
@@ -344,6 +352,14 @@
       "label": "Voice Mode",
       "description": "Show the live voice conversation button in the composer",
       "defaultEnabled": false
+    },
+    {
+      "id": "fast-mode",
+      "scope": "assistant",
+      "key": "fast-mode",
+      "label": "Fast Mode",
+      "description": "Enable Anthropic fast mode for Opus 4.6, delivering up to 2.5x higher output tokens per second at premium pricing",
+      "defaultEnabled": false
     }
   ]
 }

package/src/http/routes/oauth-providers-proxy.ts

@@ -0,0 +1,114 @@
+/**
+ * Gateway proxy endpoints for OAuth provider discovery routes.
+ *
+ * These routes remain available even when the broad runtime proxy is
+ * disabled, so skills and clients can use gateway URLs exclusively.
+ */
+
+import { mintServiceToken } from "../../auth/token-exchange.js";
+import type { GatewayConfig } from "../../config.js";
+import { fetchImpl } from "../../fetch.js";
+import { getLogger } from "../../logger.js";
+import { stripHopByHop } from "../../util/strip-hop-by-hop.js";
+
+const log = getLogger("oauth-providers-proxy");
+
+export function createOAuthProvidersProxyHandler(config: GatewayConfig) {
+  async function proxyToRuntime(
+    req: Request,
+    upstreamPath: string,
+    upstreamSearch: string,
+  ): Promise<Response> {
+    const start = performance.now();
+    const upstream = `${config.assistantRuntimeBaseUrl}${upstreamPath}${upstreamSearch}`;
+
+    const reqHeaders = stripHopByHop(new Headers(req.headers));
+    reqHeaders.delete("host");
+    reqHeaders.delete("authorization");
+
+    reqHeaders.set("authorization", `Bearer ${mintServiceToken()}`);
+
+    const hasBody = req.method !== "GET" && req.method !== "HEAD";
+    const bodyBuffer = hasBody ? await req.arrayBuffer() : null;
+    if (bodyBuffer !== null) {
+      reqHeaders.set("content-length", String(bodyBuffer.byteLength));
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => {
+      controller.abort(
+        new DOMException(
+          "The operation was aborted due to timeout",
+          "TimeoutError",
+        ),
+      );
+    }, config.runtimeTimeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetchImpl(upstream, {
+        method: req.method,
+        headers: reqHeaders,
+        body: bodyBuffer,
+        signal: controller.signal,
+      });
+      clearTimeout(timeoutId);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      const duration = Math.round(performance.now() - start);
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        log.error(
+          { path: upstreamPath, duration },
+          "OAuth providers proxy upstream timed out",
+        );
+        return Response.json({ error: "Gateway Timeout" }, { status: 504 });
+      }
+      log.error(
+        { err, path: upstreamPath, duration },
+        "OAuth providers proxy upstream connection failed",
+      );
+      return Response.json({ error: "Bad Gateway" }, { status: 502 });
+    }
+
+    const resHeaders = stripHopByHop(new Headers(response.headers));
+    const duration = Math.round(performance.now() - start);
+
+    if (response.status >= 400) {
+      const body = await response.text();
+      log.warn(
+        { path: upstreamPath, status: response.status, duration },
+        "OAuth providers proxy upstream error",
+      );
+      return new Response(body, {
+        status: response.status,
+        headers: resHeaders,
+      });
+    }
+
+    log.info(
+      { path: upstreamPath, status: response.status, duration },
+      "OAuth providers proxy completed",
+    );
+    return new Response(response.body, {
+      status: response.status,
+      headers: resHeaders,
+    });
+  }
+
+  return {
+    async handleListProviders(req: Request): Promise<Response> {
+      return proxyToRuntime(
+        req,
+        "/v1/oauth/providers",
+        new URL(req.url).search,
+      );
+    },
+
+    async handleGetProvider(
+      req: Request,
+      providerKey: string,
+    ): Promise<Response> {
+      return proxyToRuntime(req, `/v1/oauth/providers/${providerKey}`, "");
+    },
+  };
+}

package/src/index.ts

@@ -56,6 +56,7 @@ import { createVercelControlPlaneProxyHandler } from "./http/routes/vercel-contr
 import { createContactsControlPlaneProxyHandler } from "./http/routes/contacts-control-plane-proxy.js";
 import { createSlackControlPlaneProxyHandler } from "./http/routes/slack-control-plane-proxy.js";
 import { createOAuthAppsProxyHandler } from "./http/routes/oauth-apps-proxy.js";
+import { createOAuthProvidersProxyHandler } from "./http/routes/oauth-providers-proxy.js";
 import { createChannelReadinessProxyHandler } from "./http/routes/channel-readiness-proxy.js";
 import { createRuntimeHealthProxyHandler } from "./http/routes/runtime-health-proxy.js";
 import { createUpgradeBroadcastProxyHandler } from "./http/routes/upgrade-broadcast-proxy.js";
@@ -76,12 +77,17 @@ import {
   createTrustRulesStarterBundleHandler,
 } from "./http/routes/trust-rules.js";
 import { getLogger, initLogger } from "./logger.js";
-import { CircuitBreakerOpenError } from "./runtime/client.js";
+import {
+  AttachmentValidationError,
+  CircuitBreakerOpenError,
+  uploadAttachment,
+} from "./runtime/client.js";
 import { buildSchema } from "./schema.js";
 import {
   createSlackSocketModeClient,
   type SlackSocketModeClient,
 } from "./slack/socket-mode.js";
+import { downloadSlackFile } from "./slack/download.js";
 import { fetchThreadContext } from "./slack/thread-context.js";
 import { handleInbound } from "./handlers/handle-inbound.js";
 import { checkAuthRateLimit } from "./http/middleware/rate-limit.js";
@@ -276,6 +282,7 @@ async function main() {
   const twilioControlPlaneProxy = createTwilioControlPlaneProxyHandler(config);
   const slackControlPlaneProxy = createSlackControlPlaneProxyHandler(config);
   const oauthAppsProxy = createOAuthAppsProxyHandler(config);
+  const oauthProvidersProxy = createOAuthProvidersProxyHandler(config);
   const channelReadinessProxy = createChannelReadinessProxyHandler(config);
   const runtimeHealthProxy = createRuntimeHealthProxyHandler(config);
   const upgradeBroadcastProxy = createUpgradeBroadcastProxyHandler(config);
@@ -417,6 +424,12 @@ async function main() {
       auth: "edge",
       handler: (req) => runtimeHealthProxy.handleRuntimeHealth(req),
     },
+    {
+      path: "/v1/healthz",
+      method: "GET",
+      auth: "edge",
+      handler: (req) => runtimeHealthProxy.handleRuntimeHealth(req),
+    },
 
     // ── Brain graph ──
     {
@@ -708,6 +721,21 @@ async function main() {
       handler: (req) => slackControlPlaneProxy.handleShareToSlack(req),
     },
 
+    // ── OAuth providers ──
+    {
+      path: "/v1/oauth/providers",
+      method: "GET",
+      auth: "edge",
+      handler: (req) => oauthProvidersProxy.handleListProviders(req),
+    },
+    {
+      path: /^\/v1\/oauth\/providers\/([^/]+)\/?$/,
+      method: "GET",
+      auth: "edge",
+      handler: (req, params) =>
+        oauthProvidersProxy.handleGetProvider(req, params[0]),
+    },
+
     // ── OAuth apps ──
     {
       path: "/v1/oauth/apps",
@@ -1194,28 +1222,147 @@ async function main() {
           !isEdit &&
           !isCallback;
 
-        const forward = (threadContextHint?: string) => {
-          const hints: string[] = [];
-          if (threadContextHint) hints.push(threadContextHint);
-
-          handleInbound(config, normalized.event, {
-            replyCallbackUrl,
-            routingOverride: normalized.routing,
-            ...(hints.length > 0 ? { transportMetadata: { hints } } : {}),
-          }).catch((err) => {
+        const forward = async (threadContextHint?: string) => {
+          try {
+            const hints: string[] = [];
+            if (threadContextHint) hints.push(threadContextHint);
+
+            // Download and upload attachments if present (skip for edits and
+            // callback actions — edits only update text, callbacks have no media)
+            let attachmentIds: string[] | undefined;
+            const eventAttachments = normalized.event.message.attachments;
+            if (
+              eventAttachments &&
+              eventAttachments.length > 0 &&
+              normalized.slackFiles &&
+              !isEdit &&
+              !isCallback
+            ) {
+              attachmentIds = [];
+              const maxBytes =
+                config.maxAttachmentBytes.slack ??
+                config.maxAttachmentBytes.default;
+
+              // Filter oversized attachments
+              const eligible = eventAttachments.filter((att) => {
+                if (
+                  att.fileSize !== undefined &&
+                  att.fileSize > maxBytes
+                ) {
+                  log.warn(
+                    {
+                      fileId: att.fileId,
+                      fileSize: att.fileSize,
+                      limit: maxBytes,
+                    },
+                    "Skipping oversized Slack attachment",
+                  );
+                  return false;
+                }
+                return true;
+              });
+
+              // Process with bounded concurrency. Socket Mode has no retry
+              // mechanism, so all errors (validation and transient) are logged
+              // and skipped — the message is still delivered without the
+              // failed attachment.
+              for (
+                let i = 0;
+                i < eligible.length;
+                i += config.maxAttachmentConcurrency
+              ) {
+                const batch = eligible.slice(
+                  i,
+                  i + config.maxAttachmentConcurrency,
+                );
+                const results = await Promise.allSettled(
+                  batch.map(async (att) => {
+                    const slackFile = normalized.slackFiles?.get(att.fileId);
+                    if (!slackFile) {
+                      throw new Error(
+                        `No SlackFile found for attachment ${att.fileId}`,
+                      );
+                    }
+                    const downloaded = await downloadSlackFile(
+                      slackFile,
+                      botToken,
+                    );
+                    return uploadAttachment(config, downloaded, {
+                      skipCircuitBreaker: true,
+                    });
+                  }),
+                );
+                for (const result of results) {
+                  if (result.status === "fulfilled") {
+                    attachmentIds.push(result.value.id);
+                  } else if (
+                    result.reason instanceof AttachmentValidationError
+                  ) {
+                    log.warn(
+                      { err: result.reason },
+                      "Skipping Slack attachment with validation error",
+                    );
+                  } else {
+                    log.warn(
+                      { err: result.reason },
+                      "Skipping Slack attachment due to download/upload failure",
+                    );
+                  }
+                }
+              }
+            }
+
+            handleInbound(config, normalized.event, {
+              replyCallbackUrl,
+              routingOverride: normalized.routing,
+              ...(attachmentIds && attachmentIds.length > 0
+                ? { attachmentIds }
+                : {}),
+              ...(hints.length > 0 ? { transportMetadata: { hints } } : {}),
+            }).catch((err) => {
+              log.error(
+                { err, channel, threadTs },
+                "Failed to forward Slack event to runtime",
+              );
+            });
+          } catch (err) {
             log.error(
               { err, channel, threadTs },
-              "Failed to forward Slack event to runtime",
+              "Failed to process Slack event — delivering message without attachments",
             );
-          });
+            handleInbound(config, normalized.event, {
+              replyCallbackUrl,
+              routingOverride: normalized.routing,
+              ...(threadContextHint
+                ? { transportMetadata: { hints: [threadContextHint] } }
+                : {}),
+            }).catch((fwdErr) => {
+              log.error(
+                { err: fwdErr, channel, threadTs },
+                "Failed to forward Slack event to runtime (fallback)",
+              );
+            });
+          }
         };
 
         if (isThreadReply && botToken) {
           fetchThreadContext(channel, threadTs, messageTs, botToken)
-            .then((context) => forward(context ?? undefined))
-            .catch(() => forward());
+            .then((context) => context ?? undefined)
+            .catch(() => undefined)
+            .then((context) => forward(context))
+            .catch((err) => {
+              log.error(
+                { err, channel, threadTs },
+                "Unhandled error in Slack forward (thread reply)",
+              );
+            });
         } else {
-          forward();
+          forward().catch((err) => {
+            log.error(
+              { err, channel, threadTs },
+              "Unhandled error in Slack forward",
+            );
+          });
         }
 
         // When an approval button is clicked, store the approval message ts

package/src/runtime/client.ts

@@ -547,8 +547,11 @@ export async function forwardTwilioConnectActionWebhook(
 export async function uploadAttachment(
   config: GatewayConfig,
   input: UploadAttachmentInput,
+  opts?: { skipCircuitBreaker?: boolean },
 ): Promise<UploadAttachmentResponse> {
-  cbBeforeRequest();
+  const skipCb = opts?.skipCircuitBreaker === true;
+
+  if (!skipCb) cbBeforeRequest();
 
   const url = `${config.assistantRuntimeBaseUrl}/v1/attachments`;
 
@@ -563,7 +566,7 @@ export async function uploadAttachment(
       signal: AbortSignal.timeout(config.runtimeTimeoutMs),
     });
   } catch (err) {
-    cbOnFailure();
+    if (!skipCb) cbOnFailure();
     throw err;
   }
 
@@ -573,16 +576,16 @@ export async function uploadAttachment(
     // extension, missing fields). Distinguish from transient 5xx/network errors
     // so callers can decide whether to skip or propagate.
     if (response.status >= 400 && response.status < 500) {
-      cbOnSuccess();
+      if (!skipCb) cbOnSuccess();
       throw new AttachmentValidationError(
         `Attachment rejected (${response.status}): ${body}`,
       );
     }
-    cbOnFailure();
+    if (!skipCb) cbOnFailure();
     throw new Error(`Attachment upload failed (${response.status}): ${body}`);
   }
 
-  cbOnSuccess();
+  if (!skipCb) cbOnSuccess();
   return (await response.json()) as UploadAttachmentResponse;
 }
 

package/src/schema.ts

@@ -153,6 +153,52 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/healthz": {
+        get: {
+          summary: "Runtime health (via gateway, alias)",
+          description:
+            "Alias for `/v1/health`. Authenticated gateway endpoint that proxies runtime health checks to `/v1/health` on the assistant runtime.",
+          operationId: "runtimeHealthz",
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "Runtime health returned",
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "503": {
+              description: "Bearer token not configured",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "502": {
+              description: "Failed to reach assistant runtime",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+            "504": {
+              description: "Assistant runtime request timed out",
+              content: {
+                "application/json": {
+                  schema: { $ref: "#/components/schemas/ErrorResponse" },
+                },
+              },
+            },
+          },
+        },
+      },
       "/v1/brain-graph": {
         get: {
           summary: "Brain graph data",
@@ -1725,6 +1771,74 @@ export function buildSchema(): Record<string, unknown> {
           },
         },
       },
+      "/v1/oauth/providers": {
+        get: {
+          summary: "List OAuth providers",
+          description:
+            "Authenticated gateway endpoint that lists available OAuth providers by proxying to the assistant runtime.",
+          operationId: "oauthProvidersList",
+          parameters: [
+            {
+              name: "supports_managed_mode",
+              in: "query",
+              required: false,
+              schema: { type: "boolean" },
+              description:
+                "When true, only return providers that support managed mode.",
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth providers returned",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
+      "/v1/oauth/providers/{providerKey}": {
+        get: {
+          summary: "Get OAuth provider",
+          description:
+            "Authenticated gateway endpoint that retrieves a single OAuth provider by key by proxying to the assistant runtime.",
+          operationId: "oauthProvidersGet",
+          parameters: [
+            {
+              name: "providerKey",
+              in: "path",
+              required: true,
+              schema: { type: "string" },
+              description: "The provider key, for example `google`.",
+            },
+          ],
+          security: [{ BearerAuth: [] }],
+          responses: {
+            "200": {
+              description: "OAuth provider returned",
+              content: {
+                "application/json": {
+                  schema: { type: "object" },
+                },
+              },
+            },
+            "401": {
+              description: "Unauthorized — missing or invalid bearer token",
+            },
+            "404": { description: "OAuth provider not found" },
+            "502": { description: "Failed to reach assistant runtime" },
+            "504": { description: "Assistant runtime request timed out" },
+          },
+        },
+      },
       "/v1/oauth/apps": {
         get: {
           summary: "List OAuth apps",

package/src/slack/download.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import type { SlackFile } from "./normalize.js";
+
+type FetchFn = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+let fetchMock: ReturnType<typeof mock<FetchFn>> = mock(
+  async () => new Response(),
+);
+
+mock.module("../fetch.js", () => ({
+  fetchImpl: (...args: Parameters<FetchFn>) => fetchMock(...args),
+}));
+
+const { downloadSlackFile } = await import("./download.js");
+
+function makeSlackFile(overrides?: Partial<SlackFile>): SlackFile {
+  return {
+    id: "F12345",
+    name: "test-image.png",
+    mimetype: "image/png",
+    url_private_download: "https://files.slack.com/download/F12345",
+    url_private: "https://files.slack.com/files-pri/F12345",
+    ...overrides,
+  };
+}
+
+/** Create a minimal valid PNG buffer that file-type can detect. */
+function makePngBuffer(): ArrayBuffer {
+  // PNG signature (8 bytes) + minimal IHDR chunk (25 bytes)
+  const png = new Uint8Array([
+    // PNG signature
+    0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+    // IHDR chunk: length (13)
+    0x00, 0x00, 0x00, 0x0d,
+    // IHDR type
+    0x49, 0x48, 0x44, 0x52,
+    // Width: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Height: 1
+    0x00, 0x00, 0x00, 0x01,
+    // Bit depth, color type, compression, filter, interlace
+    0x08, 0x02, 0x00, 0x00, 0x00,
+    // CRC (placeholder)
+    0x90, 0x77, 0x53, 0xde,
+  ]);
+  return png.buffer;
+}
+
+/** Create a plain text buffer (undetectable by file-type). */
+function makeTextBuffer(): ArrayBuffer {
+  return new TextEncoder().encode("hello world").buffer;
+}
+
+describe("downloadSlackFile", () => {
+  afterEach(() => {
+    fetchMock = mock(async () => new Response());
+  });
+
+  test("downloads file using url_private_download", async () => {
+    const fileBuffer = makePngBuffer();
+    fetchMock = mock(async () => new Response(fileBuffer));
+
+    const file = makeSlackFile();
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.filename).toBe("test-image.png");
+    expect(result.mimeType).toBe("image/png");
+    expect(result.data).toBe(
+      Buffer.from(fileBuffer).toString("base64"),
+    );
+
+    // Verify the correct URL and auth header were used
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://files.slack.com/download/F12345");
+    expect((init as RequestInit).headers).toEqual({
+      Authorization: "Bearer xoxb-test-token",
+    });
+  });
+
+  test("falls back to url_private when url_private_download is absent", async () => {
+    const fileBuffer = makePngBuffer();
+    fetchMock = mock(async () => new Response(fileBuffer));
+
+    const file = makeSlackFile({
+      url_private_download: undefined,
+    });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.filename).toBe("test-image.png");
+
+    const [url] = fetchMock.mock.calls[0];
+    expect(url).toBe("https://files.slack.com/files-pri/F12345");
+  });
+
+  test("throws when neither URL is present", async () => {
+    const file = makeSlackFile({
+      url_private_download: undefined,
+      url_private: undefined,
+    });
+
+    await expect(
+      downloadSlackFile(file, "xoxb-test-token"),
+    ).rejects.toThrow("Slack file F12345 has no download URL");
+  });
+
+  test("throws on HTTP error response", async () => {
+    fetchMock = mock(
+      async () => new Response("Forbidden", { status: 403, statusText: "Forbidden" }),
+    );
+
+    const file = makeSlackFile();
+
+    await expect(
+      downloadSlackFile(file, "xoxb-test-token"),
+    ).rejects.toThrow(
+      "Failed to download Slack file F12345: 403 Forbidden",
+    );
+  });
+
+  test("file.mimetype wins over detected and Content-Type", async () => {
+    // Return a PNG buffer but set file.mimetype to a custom type
+    const fileBuffer = makePngBuffer();
+    fetchMock = mock(
+      async () =>
+        new Response(fileBuffer, {
+          headers: { "Content-Type": "application/octet-stream" },
+        }),
+    );
+
+    const file = makeSlackFile({ mimetype: "image/webp" });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.mimeType).toBe("image/webp");
+  });
+
+  test("falls back to detected MIME when file.mimetype is absent", async () => {
+    const fileBuffer = makePngBuffer();
+    fetchMock = mock(async () => new Response(fileBuffer));
+
+    const file = makeSlackFile({ mimetype: undefined });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.mimeType).toBe("image/png");
+  });
+
+  test("falls back to Content-Type when mimetype is absent and type is undetectable", async () => {
+    const fileBuffer = makeTextBuffer();
+    fetchMock = mock(
+      async () =>
+        new Response(fileBuffer, {
+          headers: { "Content-Type": "text/plain; charset=utf-8" },
+        }),
+    );
+
+    const file = makeSlackFile({ mimetype: undefined });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.mimeType).toBe("text/plain");
+  });
+
+  test("falls back to application/octet-stream when nothing else is available", async () => {
+    const fileBuffer = makeTextBuffer();
+    fetchMock = mock(async () => new Response(fileBuffer));
+
+    const file = makeSlackFile({ mimetype: undefined });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.mimeType).toBe("application/octet-stream");
+  });
+
+  test("falls back to slack_file_{id} when file.name is absent", async () => {
+    const fileBuffer = makeTextBuffer();
+    fetchMock = mock(async () => new Response(fileBuffer));
+
+    const file = makeSlackFile({ name: undefined, mimetype: "text/plain" });
+    const result = await downloadSlackFile(file, "xoxb-test-token");
+
+    expect(result.filename).toBe("slack_file_F12345");
+  });
+});

package/src/slack/download.ts

@@ -0,0 +1,50 @@
+import { fileTypeFromBuffer } from "file-type";
+import { fetchImpl } from "../fetch.js";
+import type { SlackFile } from "./normalize.js";
+
+export interface DownloadedFile {
+  filename: string;
+  mimeType: string;
+  data: string; // base64-encoded
+}
+
+const DOWNLOAD_TIMEOUT_MS = 30_000;
+
+/**
+ * Download a Slack file using the bot token for authentication.
+ * Prefers url_private_download; falls back to url_private.
+ */
+export async function downloadSlackFile(
+  file: SlackFile,
+  botToken: string,
+): Promise<DownloadedFile> {
+  const url = file.url_private_download || file.url_private;
+  if (!url) {
+    throw new Error(`Slack file ${file.id} has no download URL`);
+  }
+
+  const response = await fetchImpl(url, {
+    headers: { Authorization: `Bearer ${botToken}` },
+    signal: AbortSignal.timeout(DOWNLOAD_TIMEOUT_MS),
+  });
+
+  if (!response.ok) {
+    throw new Error(
+      `Failed to download Slack file ${file.id}: ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const buffer = await response.arrayBuffer();
+  const detected = await fileTypeFromBuffer(new Uint8Array(buffer));
+
+  const mimeType =
+    file.mimetype ||
+    detected?.mime ||
+    response.headers.get("Content-Type")?.split(";")[0].trim() ||
+    "application/octet-stream";
+
+  const filename = file.name || `slack_file_${file.id}`;
+  const data = Buffer.from(buffer).toString("base64");
+
+  return { filename, mimeType, data };
+}

package/src/slack/normalize.test.ts

@@ -2,8 +2,15 @@ import { describe, it, expect } from "bun:test";
 import {
   normalizeSlackBlockActions,
   normalizeSlackReactionAdded,
+  normalizeSlackDirectMessage,
+  normalizeSlackChannelMessage,
+  normalizeSlackAppMention,
   type SlackBlockActionsPayload,
   type SlackReactionAddedEvent,
+  type SlackDirectMessageEvent,
+  type SlackChannelMessageEvent,
+  type SlackAppMentionEvent,
+  type SlackFile,
 } from "./normalize.js";
 import type { GatewayConfig } from "../config.js";
 
@@ -252,3 +259,216 @@ describe("normalizeSlackReactionAdded", () => {
     );
   });
 });
+
+// --- Attachment extraction tests ---
+
+function makeSlackFile(overrides?: Partial<SlackFile>): SlackFile {
+  return {
+    id: "F001",
+    name: "photo.png",
+    mimetype: "image/png",
+    size: 12345,
+    url_private_download: "https://files.slack.com/download/photo.png",
+    url_private: "https://files.slack.com/files/photo.png",
+    ...overrides,
+  };
+}
+
+function makeDmEvent(
+  overrides?: Partial<SlackDirectMessageEvent>,
+): SlackDirectMessageEvent {
+  return {
+    type: "message",
+    user: "U123",
+    text: "hello",
+    ts: "1234567890.123456",
+    channel: "D789",
+    channel_type: "im",
+    ...overrides,
+  };
+}
+
+function makeChannelEvent(
+  overrides?: Partial<SlackChannelMessageEvent>,
+): SlackChannelMessageEvent {
+  return {
+    type: "message",
+    user: "U123",
+    text: "hello",
+    ts: "1234567890.123456",
+    channel: "C456",
+    channel_type: "channel",
+    ...overrides,
+  };
+}
+
+function makeAppMentionEvent(
+  overrides?: Partial<SlackAppMentionEvent>,
+): SlackAppMentionEvent {
+  return {
+    type: "app_mention",
+    user: "U123",
+    text: "<@UBOT> hello",
+    ts: "1234567890.123456",
+    channel: "C456",
+    ...overrides,
+  };
+}
+
+describe("attachment extraction in normalize functions", () => {
+  describe("normalizeSlackDirectMessage", () => {
+    it("populates attachments with type 'image' for image files", () => {
+      const config = makeConfig();
+      const event = makeDmEvent({
+        files: [
+          makeSlackFile({ id: "F001", mimetype: "image/png", name: "photo.png" }),
+          makeSlackFile({ id: "F002", mimetype: "image/jpeg", name: "pic.jpg" }),
+        ],
+      });
+      const result = normalizeSlackDirectMessage(event, "evt-1", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toHaveLength(2);
+      expect(result!.event.message.attachments![0]).toEqual({
+        type: "image",
+        fileId: "F001",
+        fileName: "photo.png",
+        mimeType: "image/png",
+        fileSize: 12345,
+      });
+      expect(result!.event.message.attachments![1]).toEqual({
+        type: "image",
+        fileId: "F002",
+        fileName: "pic.jpg",
+        mimeType: "image/jpeg",
+        fileSize: 12345,
+      });
+
+      // slackFiles map should be populated
+      expect(result!.slackFiles).toBeDefined();
+      expect(result!.slackFiles!.size).toBe(2);
+      expect(result!.slackFiles!.get("F001")!.id).toBe("F001");
+      expect(result!.slackFiles!.get("F002")!.id).toBe("F002");
+    });
+
+    it("populates attachments with type 'document' for non-image files", () => {
+      const config = makeConfig();
+      const event = makeDmEvent({
+        files: [
+          makeSlackFile({
+            id: "F003",
+            mimetype: "application/pdf",
+            name: "doc.pdf",
+            size: 99999,
+          }),
+        ],
+      });
+      const result = normalizeSlackDirectMessage(event, "evt-2", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toHaveLength(1);
+      expect(result!.event.message.attachments![0]).toEqual({
+        type: "document",
+        fileId: "F003",
+        fileName: "doc.pdf",
+        mimeType: "application/pdf",
+        fileSize: 99999,
+      });
+    });
+
+    it("filters out files missing download URLs", () => {
+      const config = makeConfig();
+      const event = makeDmEvent({
+        files: [
+          makeSlackFile({ id: "F004" }),
+          makeSlackFile({
+            id: "F005",
+            url_private_download: undefined,
+            url_private: undefined,
+          }),
+        ],
+      });
+      const result = normalizeSlackDirectMessage(event, "evt-3", config);
+
+      expect(result).not.toBeNull();
+      // Only F004 has download URLs
+      expect(result!.event.message.attachments).toHaveLength(1);
+      expect(result!.event.message.attachments![0].fileId).toBe("F004");
+      expect(result!.slackFiles!.size).toBe(1);
+      expect(result!.slackFiles!.has("F005")).toBe(false);
+    });
+
+    it("omits attachments field when files is empty", () => {
+      const config = makeConfig();
+      const event = makeDmEvent({ files: [] });
+      const result = normalizeSlackDirectMessage(event, "evt-4", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toBeUndefined();
+      expect(result!.slackFiles).toBeUndefined();
+    });
+
+    it("omits attachments field when files is undefined", () => {
+      const config = makeConfig();
+      const event = makeDmEvent();
+      const result = normalizeSlackDirectMessage(event, "evt-5", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toBeUndefined();
+      expect(result!.slackFiles).toBeUndefined();
+    });
+  });
+
+  describe("normalizeSlackChannelMessage", () => {
+    it("populates attachments for channel messages with files", () => {
+      const config = makeConfig();
+      const event = makeChannelEvent({
+        files: [
+          makeSlackFile({ id: "F010", mimetype: "image/gif", name: "anim.gif" }),
+        ],
+      });
+      const result = normalizeSlackChannelMessage(event, "evt-ch-1", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toHaveLength(1);
+      expect(result!.event.message.attachments![0]).toEqual({
+        type: "image",
+        fileId: "F010",
+        fileName: "anim.gif",
+        mimeType: "image/gif",
+        fileSize: 12345,
+      });
+      expect(result!.slackFiles).toBeDefined();
+      expect(result!.slackFiles!.get("F010")!.name).toBe("anim.gif");
+    });
+  });
+
+  describe("normalizeSlackAppMention", () => {
+    it("populates attachments for app mention events with files", () => {
+      const config = makeConfig();
+      const event = makeAppMentionEvent({
+        files: [
+          makeSlackFile({
+            id: "F020",
+            mimetype: "text/plain",
+            name: "notes.txt",
+            size: 500,
+          }),
+        ],
+      });
+      const result = normalizeSlackAppMention(event, "evt-am-1", config);
+
+      expect(result).not.toBeNull();
+      expect(result!.event.message.attachments).toHaveLength(1);
+      expect(result!.event.message.attachments![0]).toEqual({
+        type: "document",
+        fileId: "F020",
+        fileName: "notes.txt",
+        mimeType: "text/plain",
+        fileSize: 500,
+      });
+      expect(result!.slackFiles).toBeDefined();
+      expect(result!.slackFiles!.get("F020")!.id).toBe("F020");
+    });
+  });
+});

package/src/slack/normalize.ts

@@ -166,6 +166,16 @@ export function getUserInfoCacheSize(): number {
   return userInfoCache.size;
 }
 
+/** Slack file object (subset relevant to attachment handling). */
+export interface SlackFile {
+  id: string;
+  name?: string;
+  mimetype?: string;
+  size?: number;
+  url_private_download?: string;
+  url_private?: string;
+}
+
 /**
  * Slack `app_mention` event shape (subset relevant to normalization).
  */
@@ -178,6 +188,7 @@ export interface SlackAppMentionEvent {
   thread_ts?: string;
   client_msg_id?: string;
   event_ts?: string;
+  files?: SlackFile[];
 }
 
 /**
@@ -194,6 +205,7 @@ export interface SlackDirectMessageEvent {
   thread_ts?: string;
   client_msg_id?: string;
   event_ts?: string;
+  files?: SlackFile[];
 }
 
 /**
@@ -211,6 +223,7 @@ export interface SlackChannelMessageEvent {
   thread_ts?: string;
   client_msg_id?: string;
   event_ts?: string;
+  files?: SlackFile[];
 }
 
 /**
@@ -251,6 +264,29 @@ export function stripBotMention(text: string): string {
   return stripped || text.trim();
 }
 
+function extractSlackAttachments(
+  files: SlackFile[] | undefined,
+): Array<{
+  type: "image" | "document";
+  fileId: string;
+  fileName?: string;
+  mimeType?: string;
+  fileSize?: number;
+}> {
+  if (!files || files.length === 0) return [];
+  return files
+    .filter((f) => f.url_private_download || f.url_private)
+    .map((f) => ({
+      type: f.mimetype?.startsWith("image/")
+        ? ("image" as const)
+        : ("document" as const),
+      fileId: f.id,
+      fileName: f.name,
+      mimeType: f.mimetype,
+      fileSize: f.size,
+    }));
+}
+
 export type NormalizedSlackEvent = {
   event: GatewayInboundEvent;
   routing: RouteResult;
@@ -258,6 +294,8 @@ export type NormalizedSlackEvent = {
   threadTs: string;
   /** Slack channel ID. */
   channel: string;
+  /** Original Slack file objects keyed by file ID, for download in the I/O layer. */
+  slackFiles?: Map<string, SlackFile>;
 };
 
 /**
@@ -300,6 +338,15 @@ export function normalizeSlackDirectMessage(
   const externalMessageId =
     event.client_msg_id ?? event.ts ?? `${event.channel}:${event.ts}`;
 
+  const attachments = extractSlackAttachments(event.files);
+  const slackFiles = event.files?.length
+    ? new Map(
+        event.files
+          .filter((f) => f.url_private_download || f.url_private)
+          .map((f) => [f.id, f]),
+      )
+    : undefined;
+
   // Use cache-only lookup to avoid blocking normalization on network calls.
   // A background fetch warms the cache for subsequent messages from this user.
   const userInfo =
@@ -316,6 +363,7 @@ export function normalizeSlackDirectMessage(
         content: event.text,
         conversationExternalId: event.channel,
         externalMessageId,
+        ...(attachments.length > 0 ? { attachments } : {}),
       },
       actor: {
         actorExternalId: event.user,
@@ -333,6 +381,7 @@ export function normalizeSlackDirectMessage(
     routing,
     threadTs: event.thread_ts ?? event.ts,
     channel: event.channel,
+    ...(slackFiles ? { slackFiles } : {}),
   };
 }
 
@@ -361,6 +410,15 @@ export function normalizeSlackChannelMessage(
   const externalMessageId =
     event.client_msg_id ?? event.ts ?? `${event.channel}:${event.ts}`;
 
+  const attachments = extractSlackAttachments(event.files);
+  const slackFiles = event.files?.length
+    ? new Map(
+        event.files
+          .filter((f) => f.url_private_download || f.url_private)
+          .map((f) => [f.id, f]),
+      )
+    : undefined;
+
   const userInfo =
     botToken && event.user
       ? resolveSlackUserSync(event.user, botToken)
@@ -375,6 +433,7 @@ export function normalizeSlackChannelMessage(
         content,
         conversationExternalId: event.channel,
         externalMessageId,
+        ...(attachments.length > 0 ? { attachments } : {}),
       },
       actor: {
         actorExternalId: event.user,
@@ -393,6 +452,7 @@ export function normalizeSlackChannelMessage(
     routing,
     threadTs: event.thread_ts ?? event.ts,
     channel: event.channel,
+    ...(slackFiles ? { slackFiles } : {}),
   };
 }
 
@@ -418,6 +478,15 @@ export function normalizeSlackAppMention(
   const externalMessageId =
     event.client_msg_id ?? event.ts ?? `${event.channel}:${event.ts}`;
 
+  const attachments = extractSlackAttachments(event.files);
+  const slackFiles = event.files?.length
+    ? new Map(
+        event.files
+          .filter((f) => f.url_private_download || f.url_private)
+          .map((f) => [f.id, f]),
+      )
+    : undefined;
+
   const userInfo =
     botToken && event.user
       ? resolveSlackUserSync(event.user, botToken)
@@ -432,6 +501,7 @@ export function normalizeSlackAppMention(
         content,
         conversationExternalId: event.channel,
         externalMessageId,
+        ...(attachments.length > 0 ? { attachments } : {}),
       },
       actor: {
         actorExternalId: event.user,
@@ -449,6 +519,7 @@ export function normalizeSlackAppMention(
     routing,
     threadTs: event.thread_ts ?? event.ts,
     channel: event.channel,
+    ...(slackFiles ? { slackFiles } : {}),
   };
 }