fix(eve): degrade missing attachment bytes on resume instead of failing the turn

[ruiconti]

Fixes #276. Carries #325 forward (both commits cherry-picked with authorship intact, re-signed) plus a correction to the root-cause story and a recovery hint in the model-facing text.

The incident

Resuming a Slack thread that contained an image failed every follow-up turn:

Step "step//eve@0.11.5//turnStep" failed after 3 retries: Sandbox-ref FilePart
references missing file: "/workspace/attachments/<id>/crayon.png".

hydrateMessageContent threw on the missing read, the turn ended in session.failed, and the bot never replied again in that thread.

Actual root cause (differs from #325's framing)

The sandbox was never torn down. Session sandbox names embed the deployment id (keys.ts scopes session keys with scopeKind: "deployment", which hashes VERCEL_DEPLOYMENT_ID). Tracing the reporting incident in project v: the screenshot turn ran at 18:19 UTC on dpl_ExWJSEJ... and the failing turn 2h05m later on dpl_7NnBDX3..., with four production deploys in between. sha256(deploymentId)[:16] matches both sandbox names exactly. The old sandbox still exists, bytes intact; the resumed session derives a new name, gets a 404, and eve creates a fresh sandbox from the template. Across project v, 55 of 1221 sessions show sandboxes under 2+ deployment hashes, so this fires for any thread that crosses a deploy.

What this does

Hydration no longer throws when a historical eve-sandbox: ref has no bytes behind it. The file part becomes an error-shaped text part:

FileNotFound: Current snapshot may be newer and does not contain /workspace/attachments/.../crayon.png.

plus a log.warn with path/size/mediaType. A freshly staged attachment in the current turn hydrates as before. The error shape is new relative to #325, which used a prose notice; models already know how to react to a failed read (answer without the file, or ask for it again), so the notice reads like one.

This is the floor, not the fix for the class. Keeping session filesystems alive across deploys (sandbox drives) is a separate research PR.

Tests

Rewrote the "missing file" integration case to assert the degrade (leading text survives, ref becomes the notice, no file part reaches the model) and added a regression staging into one sandbox and hydrating against a fresh one, the same shape as a resume after a deploy. Attachment-staging unit + integration suites green.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview, Comment, Open in v0	Jul 2, 2026 7:34pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
eve-docs-1644	Skipped	Open in v0	Jul 2, 2026 7:34pm
eve-docs-4759	Skipped	Open in v0	Jul 2, 2026 7:34pm

[github-actions]

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

Key takeaways

• No notable deltas vs main (c233a6a).

Delta vs main (c233a6a)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	3.51 MB	3.51 MB	-55 B ✅
Package	Unpacked publish size	12.76 MB	12.76 MB	+171 B ⚠️
Package	Installed footprint	51.77 MB	51.77 MB	+171 B ⚠️
Package	Published files	2419	2419	0
Package	Installed files	5638	5638	0
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	9.23 MB	9.23 MB	-12 B ✅
Runtime	Public routes	9	9	0

Changed function payloads vs main (c233a6a) (2)

Function	Status	Baseline	Current	Delta	Route changes
functions/__server.func	changed	3.48 MB	3.48 MB	-144 B ✅	none
functions/.well-known/workflow/v1/flow.func	changed	5.75 MB	5.75 MB	+132 B ⚠️	none

eve init install

Metric	Baseline	Current	Delta
Installed footprint	91.56 MB	91.56 MB	+171 B ⚠️
Installed packages	120	120	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	26.87 MB	26.87 MB	+171 B ⚠️
devDependency package bytes	4.81 MB	4.81 MB	0 B ➖

Build Metadata

• Preset: vercel
• Nitro: nitro@3.0.260610-beta
• Output directory: apps/fixtures/weather-agent/.vercel/output
• Build metadata timestamp: 2026-07-02T19:34:38.282Z
• Route aliases: 9 public, 1 internal (10 total aliases)
• Vercel routes in config: 10
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.19.0
• Package directory: packages/eve
• Tarball: 3.51 MB (eve-0.19.0.tgz)
• Unpacked payload: 12.76 MB across 2419 published files
• Installed footprint: 51.77 MB across 5638 installed files
• Installed root package: 11.49 MB
• Installed dependencies: 40.29 MB
• Runtime dependencies: 1
• Peer dependencies: 5 (4 optional)

Installed footprint is measured from an isolated temporary npm install of the packed tarball.

Heavy installed dependencies

• @rolldown/binding-linux-x64-gnu: 19.18 MB (37.0%)
• eve: 11.49 MB (22.2%)
• ai: 6.29 MB (12.2%)
• zod: 5.04 MB (9.7%)
• nitro: 2.41 MB (4.6%)

Publish payload breakdown

Published file size
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [####....................] 1.51 MB 11.8%
🟡 dist/src/compiled/@workflow/core/runtime.js      [##......................] 794.4 kB 6.2%
🟡 dist/src/compiled/@vercel/sandbox/index.js       [##......................] 632.2 kB 5.0%
🟡 dist/src/compiled/@chat-adapter/slack/index.js   [#.......................] 433.8 kB 3.4%
🟡 dist/src/compiled/_chunks/workflow/attribute-... [#.......................] 371.6 kB 2.9%
🔴 Other published files                            [########################] 9.02 MB 70.7%

Installed footprint breakdown

Installed package size
🔴 @rolldown/binding-linux-x64-gnu [########################] 19.18 MB 37.0%
🔴 eve                             [##############..........] 11.49 MB 22.2%
🔴 ai                              [########................] 6.29 MB 12.2%
🔴 zod                             [######..................] 5.04 MB 9.7%
🟠 nitro                           [###.....................] 2.41 MB 4.6%
🟡 rolldown                        [#.......................] 771.7 kB 1.5%
🔴 Other installed packages        [########................] 6.60 MB 12.7%

Runtime dependencies (1)

Package	Range	Notes
nitro	3.0.260610-beta

Peer dependencies (5)

Package	Range	Notes
@opentelemetry/api	^1.0.0	optional peer
ai	catalog:
braintrust	^3.0.0	optional peer
just-bash	^3.0.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: 91.56 MB across 7390 installed files
• Installed packages: 120 total (114 transitive-only)
• dependencies: 4 direct packages totaling 26.87 MB
• devDependencies: 2 direct packages totaling 4.81 MB
• Other transitive package files: 59.87 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: 29.69 MB (32.4%)
• @rolldown/binding-linux-x64-gnu: 19.18 MB (20.9%)
• eve: 11.49 MB (12.5%)
• zod: 9.00 MB (9.8%)
• ai: 6.29 MB (6.9%)

Installed footprint breakdown

Installed package size
🔴 @typescript/typescript-linux-x64 [########################] 29.69 MB 32.4%
🔴 @rolldown/binding-linux-x64-gnu  [###############.........] 19.18 MB 20.9%
🔴 eve                              [#########...............] 11.49 MB 12.5%
🔴 zod                              [#######.................] 9.00 MB 9.8%
🔴 ai                               [#####...................] 6.29 MB 6.9%
🟠 @types/node                      [##......................] 2.54 MB 2.8%
🔴 Other installed packages         [###########.............] 13.37 MB 14.6%

dependencies (4)

Package	Range	Installed size	Share
@vercel/connect	0.2.2	98.6 kB	0.1%
ai	^7.0.0	6.29 MB	6.9%
eve	file:eve-0.19.0.tgz	11.49 MB	12.5%
zod	4.4.3	9.00 MB	9.8%

devDependencies (2)

Package	Range	Installed size	Share
@types/node	24.x	2.54 MB	2.8%
typescript	7.0.1-rc	2.27 MB	2.5%

Function Drill-Down

Payload Size Graph

Unique function payload size and share of total
🔴 functions/.well-known/workflow/v1/flow.func     [########################] 5.75 MB 62.3%
🟠 functions/__server.func                         [###############.........] 3.48 MB 37.7%

Top Function Payloads

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

Metric	Value
Public routes	/.well-known/workflow/v1/flow
Runtime	nodejs24.x
Handler	index.mjs
Payload	5.75 MB
Function files	5.75 MB across 26 files
Traced dependencies	0 B
Signal	🟠 Bundled file __eve_nitro_handler__.mjs is 1.98 MB (34.4%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 __eve_nitro_handler__.mjs              [########################] 1.98 MB 34.4%
🟠 _chunks/runtime.mjs                    [############............] 983.9 kB 17.1%
🟡 _chunks/sandbox.mjs                    [#########...............] 766.3 kB 13.3%
🟡 _chunks/attribute-changes-zAifvEhb.mjs [######..................] 473.4 kB 8.2%
🟡 _libs/@ai-sdk/gateway+[...].mjs        [#####...................] 413.5 kB 7.2%
🟠 Other bundled files                    [##############..........] 1.14 MB 19.8%

🧾 Vercel Config

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

---

🟠 functions/__server.func • 8 public routes, 1 internal alias • 3.48 MB

Metric	Value
Public routes	/ /eve/v1/callback/[token] /eve/v1/connections/[name]/callback/[token] /eve/v1/health /eve/v1/info /eve/v1/session /eve/v1/session/[sessionId] /eve/v1/session/[sessionId]/stream
Internal aliases	/__server
Runtime	nodejs24.x
Handler	index.mjs
Payload	3.48 MB
Function files	3.48 MB across 21 files
Traced dependencies	0 B
Signal	🟠 Bundled file _chunks/dev-runtime-artifacts.mjs is 913.6 kB (26.3%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 _chunks/dev-runtime-artifacts.mjs      [########################] 913.6 kB 26.3%
🟠 _chunks/runtime.mjs                    [#######################.] 891.6 kB 25.6%
🟠 _chunks/sandbox.mjs                    [####################....] 766.3 kB 22.0%
🟡 _chunks/attribute-changes-zAifvEhb.mjs [############............] 449.0 kB 12.9%
⚪ _libs/zod.mjs                          [###.....................] 114.2 kB 3.3%
🟡 Other bundled files                    [#########...............] 341.6 kB 9.8%

🧾 Vercel Config

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