fix(agents-server): sanitize attachment filename fallback

Author: KyleAMathews

.changeset/attachment-filename-fallback.md

@@ -0,0 +1,5 @@
+---
+"@electric-ax/agents-server": patch
+---
+
+Sanitize attachment Content-Disposition filename fallbacks to avoid ByteString errors for Unicode filenames.

packages/agents-server/src/routing/entities-router.ts

@@ -658,7 +658,12 @@ async function parseAttachmentForm(
 }
 
 function contentDisposition(filename: string): string {
-  const fallback = filename.replace(/["\\\r\n]/g, `_`)
+  // Header values are converted to WebIDL ByteString by undici, so every
+  // character in the raw header value must fit in a single byte. Keep the
+  // RFC 5987 filename* parameter for the full UTF-8 filename, but make the
+  // legacy filename fallback ASCII-only to avoid throwing on names containing
+  // e.g. narrow no-break spaces or emoji.
+  const fallback = filename.replace(/[^\x20-\x7e]|["\\]/g, `_`)
   return `attachment; filename="${fallback}"; filename*=UTF-8''${encodeURIComponent(filename)}`
 }
 

packages/agents-server/test/electric-agents-routes.test.ts

@@ -248,6 +248,38 @@ describe(`ElectricAgentsRoutes schedule endpoints`, () => {
   })
 })
 
+describe(`ElectricAgentsRoutes attachment endpoints`, () => {
+  it(`serves attachments with non-ASCII filenames without throwing`, async () => {
+    const manager = {
+      registry: {
+        getEntity: vi.fn().mockResolvedValue({ url: `/chat/test` }),
+        getEntityType: vi.fn(),
+      },
+      readAttachment: vi.fn().mockResolvedValue({
+        attachment: {
+          mimeType: `image/png`,
+          filename: `Screenshot 2026-06-09 at 12.09.29 PM.png`,
+        },
+        bytes: new Uint8Array([1, 2, 3]),
+      }),
+    } as any
+
+    const response = await routeResponse(
+      manager,
+      `GET`,
+      `/_electric/entities/chat/test/attachments/att-1`
+    )
+
+    expect(response.status).toBe(200)
+    expect(response.headers.get(`content-disposition`)).toBe(
+      `attachment; filename="Screenshot 2026-06-09 at 12.09.29_PM.png"; filename*=UTF-8''Screenshot%202026-06-09%20at%2012.09.29%E2%80%AFPM.png`
+    )
+    await expect(response.arrayBuffer()).resolves.toEqual(
+      new Uint8Array([1, 2, 3]).buffer
+    )
+  })
+})
+
 describe(`ElectricAgentsRoutes cron stream ensure endpoint`, () => {
   it(`rejects cron ensure requests without an expression in the schema layer`, async () => {
     const manager = {