feat(eve): add fetchFile to eveChannel for large web uploads

[AndrewBarba]

Summary

A browser that sends a file as a base64 data: URL hits the Vercel Functions request body limit at about 3.3 MB, because the limit is 4.5 MB and base64 adds a third (#4194). The usual fix is to upload the file to your own storage and send its URL. eveChannel() had no fetchFile to load such a URL. eveChannel({ fetchFile }) now takes the same resolver as defineChannel. Earlier in this stack, the HTTP channel already began passing URL strings to the resolver. A URL has no size when the request arrives, so the channel's uploadPolicy runs again on the fetched bytes. A file over the cap or of a disallowed type becomes a note.

The web chat conformance driver now attaches files through the template's composer. The HTTP channel therefore joins the image, PDF, and earlier-file attachment rows in the matrix. The download-failure row is marked unsupported, because a browser sends the bytes with the message.

Closes #4194. Part of the stack from the research plan in #4625.

Validation

• New eve.test.ts case covers staging through fetchFile, null passthrough, and both upload-policy checks on fetched bytes.
• pnpm --filter eve exec vitest run --config vitest.browser.config.ts -t "a person sends|sent earlier in the conversation": the three web chat attachment rows pass in headless Chromium.
• pnpm --filter eve exec vitest run --config vitest.unit.config.ts channel-conformance/matrix -u regenerated MATRIX.md.
• pnpm --filter eve exec vitest run --config vitest.unit.config.ts src/public/channels src/internal/testing src/eve-channel: 1240 passed.
• pnpm --filter eve run typecheck, pnpm fmt, pnpm guard:invariants, and pnpm docs:check pass.

Checklist

• I added tests and documentation where relevant
• I added a changeset if this touches the published eve package
• DCO sign-off passes for every commit (git commit --signoff)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
eve-docs	Ready	Preview, v0	Oct 10, 2026 4:57pm UTC
eve-pkg	Ready	Preview, v0	Oct 10, 2026 4:57pm UTC

[github-actions]

Bundle + Package Summary: apps/fixtures/weather-agent

Key takeaways

• No notable deltas vs barba/attachments-read-file-pdf (cf98a7a).

Delta vs barba/attachments-read-file-pdf (cf98a7a)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.58 MB	7.58 MB	+2.3 kB ⚠️
Package	Unpacked publish size	26.70 MB	26.70 MB	+3.6 kB ⚠️
Package	Installed footprint	74.50 MB	74.50 MB	+3.6 kB ⚠️
Package	Published files	4115	4115	0
Package	Installed files	8120	8120	0
Package	Installed package instances	34	34	0
Package	Distinct installed package names	32	32	0
Package	Installed dependency edges	51	51	0
Package	Installed optional peer edges	9	9	0
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	20.39 MB	20.39 MB	+1.8 kB ⚠️
Runtime	Public routes	18	18	0

Changed function payloads vs barba/attachments-read-file-pdf (cf98a7a) (2)

Function	Status	Baseline	Current	Delta	Route changes
functions/__server.func	changed	10.20 MB	10.20 MB	+918 B ⚠️	none
functions/.well-known/workflow/v1/flow.func	changed	10.20 MB	10.20 MB	+918 B ⚠️	none

eve init install

Metric	Baseline	Current	Delta
Installed footprint	112.79 MB	112.80 MB	+3.6 kB ⚠️
Installed packages	97	97	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	44.78 MB	44.79 MB	+3.6 kB ⚠️
devDependency package bytes	5.11 MB	5.11 MB	0 B ➖

Build Metadata

• Preset: vercel
• Nitro: nitro@3.0.260903-beta
• Output directory: apps/fixtures/weather-agent/.vercel/output
• Build metadata timestamp: 2026-10-10T16:57:33.223Z
• Route aliases: 18 public, 1 internal (19 total aliases)
• Vercel routes in config: 21
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.76.2
• Package directory: packages/eve
• Tarball: 7.58 MB (eve-0.76.2.tgz)
• Unpacked payload: 26.70 MB across 4115 published files
• Installed footprint: 74.50 MB across 8120 installed files
• Installed root package: 26.70 MB
• Installed dependencies: 47.80 MB
• Installed package instances: 34
• Distinct installed package names: 32
• Installed dependency edges: 51
• Installed optional peer edges: 9
• Runtime dependencies: 2
• Peer dependencies: 7 (6 optional)

Installed footprint is measured from an isolated temporary npm install of the packed tarball.
Graph metrics read only package.json files in package directories directly beneath a node_modules boundary, including nested boundaries. Each directory is one package instance; distinct names come from those manifests. Dependency edges count each unique name in dependencies or optionalDependencies per instance; optional peer edges count peerDependencies marked optional.

Heavy installed dependencies

• eve: 26.70 MB (35.8%)
• @rolldown/binding-linux-x64-gnu: 19.62 MB (26.3%)
• ai: 8.14 MB (10.9%)
• zod: 6.14 MB (8.2%)
• undici: 3.56 MB (4.8%)

Publish payload breakdown

Published file size
🟠 dist/src/compiled/shadcn-registry/index.js       [#####...................] 3.85 MB 14.4%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [###.....................] 2.29 MB 8.6%
🟠 dist/src/compiled/@ai-sdk/code-mode/index.js     [#.......................] 1.03 MB 3.8%
🟡 dist/src/compiled/@vercel/blob/index.js          [#.......................] 604.9 kB 2.3%
🟡 dist/src/compiled/_chunks/workflow/undici-D-I... [#.......................] 521.9 kB 2.0%
🔴 Other published files                            [########################] 18.41 MB 68.9%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 26.70 MB 35.8%
🔴 @rolldown/binding-linux-x64-gnu [##################......] 19.62 MB 26.3%
🔴 ai                              [#######.................] 8.14 MB 10.9%
🔴 zod                             [######..................] 6.14 MB 8.2%
🟠 undici                          [###.....................] 3.56 MB 4.8%
🟠 nitro                           [##......................] 1.89 MB 2.5%
🔴 Other installed packages        [########................] 8.44 MB 11.3%

Runtime dependencies (2)

Package	Range	Notes
nitro	3.0.260903-beta
undici	8.10.2

Peer dependencies (7)

Package	Range	Notes
@opentelemetry/api	^1.0.0	optional peer
ai	catalog:
braintrust	^3.0.0	optional peer
chat	^4.41.0	optional peer
dd-trace	^6.13.0	optional peer
just-bash	^3.1.0	optional peer
microsandbox	^0.5.0	optional peer

eve init install drill-down

eve init install details

• Command: eve init my-agent
• Package manager: npm
• Installed footprint: 112.80 MB across 10015 installed files
• Installed packages: 97 total (91 transitive-only)
• dependencies: 4 direct packages totaling 44.79 MB
• devDependencies: 2 direct packages totaling 5.11 MB
• Other transitive package files: 62.90 MB

Installed footprint is measured from an isolated temporary eve init my-agent using the current packed eve tarball.

Heavy installed dependencies

• @typescript/typescript-linux-x64: 27.95 MB (24.8%)
• eve: 26.70 MB (23.7%)
• @rolldown/binding-linux-x64-gnu: 19.62 MB (17.4%)
• zod: 9.76 MB (8.6%)
• ai: 8.14 MB (7.2%)

Installed footprint breakdown

Installed package size
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 24.8%
🔴 eve                              [#######################.] 26.70 MB 23.7%
🔴 @rolldown/binding-linux-x64-gnu  [#################.......] 19.62 MB 17.4%
🔴 zod                              [########................] 9.76 MB 8.6%
🔴 ai                               [#######.................] 8.14 MB 7.2%
🟠 undici                           [###.....................] 3.56 MB 3.2%
🔴 Other installed packages         [###############.........] 17.07 MB 15.1%

dependencies (4)

Package	Range	Installed size	Share
@vercel/connect	2.2.0	188.7 kB	0.2%
ai	^7.0.128	8.14 MB	7.2%
eve	file:eve-0.76.2.tgz	26.70 MB	23.7%
zod	4.5.4	9.76 MB	8.6%

devDependencies (2)

Package	Range	Installed size	Share
@types/node	24.x	2.61 MB	2.3%
typescript	7.0.2	2.50 MB	2.2%

Function Drill-Down

Payload Size Graph

Unique function payload size and share of total
🔴 functions/.well-known/workflow/v1/flow.func     [########################] 10.20 MB 50.0%
🔴 functions/__server.func                         [########################] 10.20 MB 50.0%

Top Function Payloads

🟠 functions/.well-known/workflow/v1/flow.func • 1 public route • 10.20 MB

Metric	Value
Public routes	/.well-known/workflow/v1/flow
Runtime	nodejs24.x
Handler	index.mjs
Payload	10.20 MB
Function files	10.20 MB across 118 files
Traced dependencies	0 B
Signal	🟠 Bundled file _chunks/vercel.web.mjs is 2.25 MB (22.1%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 _chunks/vercel.web.mjs                         [############............] 2.25 MB 22.1%
🟠 _libs/undici.mjs                               [#####...................] 1.01 MB 9.9%
🟡 _chunks/sandbox3.mjs                           [####....................] 815.4 kB 8.0%
🟡 _chunks/compiled-artifacts-instrumentation.mjs [####....................] 757.3 kB 7.4%
🟡 _chunks/token-util-Bla5Z0G9.mjs                [####....................] 704.7 kB 6.9%
🔴 Other bundled files                            [########################] 4.66 MB 45.7%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x",
  "maxDuration": "max",
  "experimentalTriggers": [
    {
      "type": "queue/v2beta",
      "topic": "__eve776561746865722d6167656e74_wkf_workflow_*",
      "consumer": "default",
      "retryAfterSeconds": 5,
      "initialDelaySeconds": 0
    }
  ],
  "environment": {
    "WORKFLOW_PRECONDITION_GUARD": "1"
  }
}

---

🟠 functions/__server.func • 17 public routes, 1 internal alias • 10.20 MB

Metric	Value
Public routes	/ /.well-known/workflow/v1/webhook/[token] /eve/v1/callback/[token] /eve/v1/connections/[name]/callback/[attemptId]/[token] /eve/v1/connections/[name]/callback/[token] /eve/v1/health /eve/v1/info /eve/v1/session /eve/v1/session/[parentSessionId]/subagents/[callId]/[childSessionId]/stream /eve/v1/session/[sessionId] /eve/v1/session/[sessionId]/cancel /eve/v1/session/[sessionId]/clear /eve/v1/session/[sessionId]/compact /eve/v1/session/[sessionId]/reset /eve/v1/session/[sessionId]/stream /eve/v1/session/[sessionId]/stubs /eve/v1/task-input/[token]
Internal aliases	/__server
Runtime	nodejs24.x
Handler	index.mjs
Payload	10.20 MB
Function files	10.20 MB across 118 files
Traced dependencies	0 B
Signal	🟠 Bundled file _chunks/vercel.web.mjs is 2.25 MB (22.1%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 _chunks/vercel.web.mjs                         [############............] 2.25 MB 22.1%
🟠 _libs/undici.mjs                               [#####...................] 1.01 MB 9.9%
🟡 _chunks/sandbox3.mjs                           [####....................] 815.4 kB 8.0%
🟡 _chunks/compiled-artifacts-instrumentation.mjs [####....................] 757.3 kB 7.4%
🟡 _chunks/token-util-Bla5Z0G9.mjs                [####....................] 704.7 kB 6.9%
🔴 Other bundled files                            [########################] 4.66 MB 45.7%

🧾 Vercel Config

{
  "handler": "index.mjs",
  "launcherType": "Nodejs",
  "shouldAddHelpers": false,
  "supportsResponseStreaming": true,
  "runtime": "nodejs24.x"
}

Build Timing: e2e/fixtures/agent-tools-sandbox

This is an informational timing measurement inside eve build, from preflight through publication. Output-size measurement and profile writing are excluded.

Build mode: deployable Vercel build with sandbox template prewarm included.

• Build pipeline: 2.34 s -> 2.42 s (+75.4 ms) vs barba/attachments-read-file-pdf (cf98a7a).
• Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `barba/attachments-read-file-pdf (cf98a7a)`

Phase	Baseline	Current	Delta
extension.check	12.9 ms	12.8 ms	-0.1 ms
project.resolve	0.3 ms	0.3 ms	0.0 ms
workspace.create	0.4 ms	0.4 ms	0.0 ms
host.prepare	448.8 ms	536.7 ms	+87.9 ms
vercel.service-prefix.resolve	0.9 ms	0.9 ms	0.0 ms
nitro.create	379.8 ms	343.8 ms	-36.0 ms
sandbox.prewarm	312.3 ms	278.6 ms	-33.7 ms
nitro.cache.prepare	0.2 ms	0.2 ms	0.0 ms
nitro.prepare	0.5 ms	0.4 ms	-0.1 ms
nitro.public-assets	0.5 ms	0.5 ms	0.0 ms
nitro.prerender	0.3 ms	0.3 ms	0.0 ms
nitro.bundle	1.04 s	1.11 s	+71.2 ms
nitro.cache.write	0.2 ms	0.2 ms	0.0 ms
vercel.workflow-function.materialize	98.4 ms	71.7 ms	-26.7 ms
agent-summary.emit	0.4 ms	0.4 ms	0.0 ms
connect-manifest.emit	0.2 ms	0.2 ms	0.0 ms
nitro.close	0.1 ms	0.1 ms	0.0 ms
output.publish	2.4 ms	3.8 ms	+1.4 ms
workspace.remove	1.4 ms	1.4 ms	0.0 ms

[roboeve]

When fetchFile returns null, the policy is skipped completely. resolveLink then falls back to fetchPublicAttachment (harness/attachment-staging.ts:582-583), which caps at DEFAULT_UPLOAD_POLICY.maxBytes and never checks the response type against this channel's allowlist (internal/attachments/public-link.ts:24-43). The request-time check only sees the declared type of a URL part, and a URL has no known size (upload-policy.ts:139-156).

So with uploadPolicy: { maxBytes: 4 * 1024 * 1024, allowedMediaTypes: ["image/*"] }, a part declared image/png whose URL fetchFile doesn't claim still stages a 20 MB PDF from any public host. The docs ("The bytes fetchFile returns must pass uploadPolicy") and the changeset ("holds the fetched bytes to the channel's uploadPolicy") read as if every URL part is covered.

The cleaner cut is to enforce the policy once in the shared resolution path, on whatever resolveLink returns (callback bytes or the public download), and pass the channel's byte cap into fetchPublicAttachment. That would also remove the need for this wrapper. If that's out of scope, the docs should say the public fallback uses the default 25 MB cap and isn't held to uploadPolicy. The new test only checks that the wrapper returns null, so it doesn't cover this path.

[roboeve]

This reimplements assertWithinLimit from #internal/attachments/limited-read.js, which exists for exactly this case ("bytes arrived some other way than a Response") and is already used that way in chatSdkChannel.ts:724. The bespoke version leaves adapterKind off the error, so the attachment resolver failed warning in attachment-staging.ts:507 logs it as undefined (resolveLink rethrows an EveAttachmentError as is). It also builds a different note style: "could not be retrieved: The file is 26214401 bytes, over the 26214400-byte upload limit." instead of the shared "it is over the 25 MB upload limit."

assertWithinLimit(bytes, maxBytesOf(policy), "eve") replaces these lines. The type error below also needs an adapterKind. Its message embeds mediaType verbatim from the callback, often an upstream content-type header, and errors.ts:30-33 says model-visible messages must not include verbatim upstream text. Use the normalized type there, or leave it out.

[roboeve]

This example buffers the whole response before eve checks the size, so maxBytes rejects an oversized file but doesn't limit memory. The wrapper only sees the returned Buffer (index.ts:765-771), and attachment-staging.ts stages parts with Promise.all. This feature exists for large files a browser uploads straight to your storage, so a client can upload a multi-GB object and send its URL, and this fetchFile reads all of it into the function first.

Since the callback has to bound its own read, the example should do that. At minimum, reject a content-length over the cap before reading, and ideally stream with a running byte count and cancel past the limit, the way readLimitedBytes does. The prose on line 198 should also say the cap is checked after fetchFile returns.

[vercel]

The docs/type-docs claim fetched bytes must pass uploadPolicy, but eve's public https: download fallback (used when fetchFile returns null) ignores the channel's uploadPolicy size cap and media-type allowlist.

[vercel]

withUploadPolicy throws EveAttachmentErrors that omit adapterKind and embed verbatim upstream media-type text into a model-visible error message, violating a documented invariant.

[AndrewBarba]

Collapsed into #4636.