docs(eve): document the instrumentation provider layout

[chadhietala]

Last PR in the instrumentation-providers stack. It documents the surface the
previous eight built, and fixes two things writing those docs turned up.

Everything here is still behind experimental.instrumentationProviders, off by
default.

The docs

A new guide, docs/guides/instrumentation-providers.md, covering the flag, one
provider per file, the otel()/otelIntegration() split, per-destination
content policy, the local spool as a destination, and what providers see:
lifecycle events, ctx.state across a start/terminal pair, the handler timeout,
and setup/flush/shutdown.

It is a separate page rather than a rewrite of instrumentation.ts, following
dynamic-workflows.md: the shipped layout is still the default, and the two are
mutually exclusive builds. instrumentation.ts gains a pointer to it and a
correction — that page claimed authoring instrumentation always ends local
tracing, which is no longer true under the provider layout.

Local tracing survived a backend only by accident

Authoring any file under agent/instrumentation/ sets the instrumentation
plugin path, which is what tells eve dev to skip its zero-config local tracing
plugin. Nothing in the provider path put the spool back, so adding a hosted
backend silently switched local tracing off — the opposite of what localTraces()
and disableInstrumentation() already promise in their own docs.

eve now seeds the slots it owns a default for before the first authored file
runs. Seeding beforehand rather than filling a gap afterwards is what lets a file
say either thing about the slot: localTraces(…) reconfigures it,
disableInstrumentation() removes it, and silence leaves it in place. eve dev
only, since the spool writes under the dev worker's app root.

A spool that declined content stopped being releasable

eve finds the local spool by looking for releaseSession on the pipeline's
processors, and uses it to retire a trace when its session ends. The content
filter wrapping a destination returned a plain delegating object, so under
EVE_TRACES_CONTENT=off the spool went unrecognized and would have held every
trace it opened live for the life of the process. The wrapper now forwards
releaseSession when the destination has one, and the predicate that finds it
has a single definition both sides share.

Also folded in

ac4520d4 (#1676), composing eve's telemetry bridge with integrations
registered through registerTelemetry. It belongs with the public provider
surface rather than ahead of it.

Not in scope

The plan listed agentRuns() and an "auto" production mode. Neither exists in
the codebase, and the settled design says Agent Runs "does not have to be a span
processor at all — it can be a provider, reading lifecycle events directly…
Either remains available; the point is that the choice is now internal rather
than forced." Inventing a public factory to satisfy a bullet would be the wrong
order, so it is dropped. The flag also stays off — flipping it is a separate
decision, and the otel() enrichment surface that replaces runtimeContext is
still open.

Validation

pnpm typecheck, pnpm lint, pnpm fmt, pnpm guard:invariants,
pnpm docs:check, pnpm test:unit (6123 passed), pnpm test:integration
(617 passed). Not run locally: scenario, e2e.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview	Aug 8, 2026 4:11pm
eve-docs-4759	Ready	Preview, v0	Aug 8, 2026 4:11pm

[github-actions]

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

Key takeaways

• No notable deltas vs instr/08-bus-hardening (585fe33).

Delta vs instr/08-bus-hardening (585fe33)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.86 MB	7.87 MB	+4.3 kB ⚠️
Package	Unpacked publish size	29.38 MB	29.39 MB	+13.3 kB ⚠️
Package	Installed footprint	72.81 MB	72.82 MB	+13.3 kB ⚠️
Package	Published files	3092	3093	+1
Package	Installed files	6802	6803	+1
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	17.09 MB	17.09 MB	+22 B ⚠️
Runtime	Public routes	13	13	0

Changed function payloads vs instr/08-bus-hardening (585fe33) (2)

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

eve init install

Metric	Baseline	Current	Delta
Installed footprint	111.22 MB	111.23 MB	+13.3 kB ⚠️
Installed packages	121	121	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	43.86 MB	43.87 MB	+13.3 kB ⚠️
devDependency package bytes	5.04 MB	5.04 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-08-08T16:12:10.097Z
• Route aliases: 13 public, 1 internal (14 total aliases)
• Vercel routes in config: 16
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.31.3
• Package directory: packages/eve
• Tarball: 7.87 MB (eve-0.31.3.tgz)
• Unpacked payload: 29.39 MB across 3093 published files
• Installed footprint: 72.82 MB across 6803 installed files
• Installed root package: 28.03 MB
• Installed dependencies: 44.79 MB
• Runtime dependencies: 2
• Peer dependencies: 5 (4 optional)

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

Heavy installed dependencies

• eve: 28.03 MB (38.5%)
• @rolldown/binding-linux-x64-gnu: 19.35 MB (26.6%)
• ai: 6.67 MB (9.2%)
• zod: 5.07 MB (7.0%)
• undici: 3.50 MB (4.8%)

Publish payload breakdown

Published file size
🔴 dist/src/compiled/shadcn-registry/index.js       [################........] 9.68 MB 33.0%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [#####...................] 2.92 MB 10.0%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [###.....................] 1.51 MB 5.1%
🟡 dist/src/compiled/@vercel/sandbox/index.js       [#.......................] 638.9 kB 2.2%
🟡 dist/src/compiled/_chunks/workflow/undici-CUI... [#.......................] 508.8 kB 1.7%
🔴 Other published files                            [########################] 14.13 MB 48.1%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 28.03 MB 38.5%
🔴 @rolldown/binding-linux-x64-gnu [#################.......] 19.35 MB 26.6%
🔴 ai                              [######..................] 6.67 MB 9.2%
🔴 zod                             [####....................] 5.07 MB 7.0%
🟠 undici                          [###.....................] 3.50 MB 4.8%
🟠 nitro                           [##......................] 2.41 MB 3.3%
🔴 Other installed packages        [#######.................] 7.79 MB 10.7%

Runtime dependencies (2)

Package	Range	Notes
nitro	3.0.260610-beta
undici	8.9.0

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: 111.23 MB across 8679 installed files
• Installed packages: 121 total (115 transitive-only)
• dependencies: 4 direct packages totaling 43.87 MB
• devDependencies: 2 direct packages totaling 5.04 MB
• Other transitive package files: 62.32 MB

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

Heavy installed dependencies

• eve: 28.03 MB (25.2%)
• @typescript/typescript-linux-x64: 27.95 MB (25.1%)
• @rolldown/binding-linux-x64-gnu: 19.35 MB (17.4%)
• zod: 9.02 MB (8.1%)
• ai: 6.67 MB (6.0%)

Installed footprint breakdown

Installed package size
🔴 eve                              [########################] 28.03 MB 25.2%
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 25.1%
🔴 @rolldown/binding-linux-x64-gnu  [#################.......] 19.35 MB 17.4%
🔴 zod                              [########................] 9.02 MB 8.1%
🔴 ai                               [######..................] 6.67 MB 6.0%
🟠 undici                           [###.....................] 3.50 MB 3.2%
🔴 Other installed packages         [##############..........] 16.71 MB 15.0%

dependencies (4)

Package	Range	Installed size	Share
@vercel/connect	0.4.3	141.0 kB	0.1%
ai	^7.0.38	6.67 MB	6.0%
eve	file:eve-0.31.3.tgz	28.03 MB	25.2%
zod	4.4.3	9.02 MB	8.1%

devDependencies (2)

Package	Range	Installed size	Share
@types/node	24.x	2.54 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     [########################] 8.54 MB 50.0%
🔴 functions/__server.func                         [########################] 8.54 MB 50.0%

Top Function Payloads

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

Metric	Value
Public routes	/.well-known/workflow/v1/flow
Runtime	nodejs24.x
Handler	index.mjs
Payload	8.54 MB
Function files	8.54 MB across 44 files
Traced dependencies	0 B
Signal	🟠 Bundled file index.mjs is 2.34 MB (27.4%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.34 MB 27.4%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.63 MB 19.1%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.5%
🟡 _chunks/sandbox.mjs             [########................] 777.1 kB 9.1%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.38 MB 27.9%

🧾 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 • 12 public routes, 1 internal alias • 8.54 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]/cancel /eve/v1/session/[sessionId]/clear /eve/v1/session/[sessionId]/compact /eve/v1/session/[sessionId]/reset /eve/v1/session/[sessionId]/stream
Internal aliases	/__server
Runtime	nodejs24.x
Handler	index.mjs
Payload	8.54 MB
Function files	8.54 MB across 44 files
Traced dependencies	0 B
Signal	🟠 Bundled file index.mjs is 2.34 MB (27.4%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.34 MB 27.4%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.63 MB 19.1%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.5%
🟡 _chunks/sandbox.mjs             [########................] 777.1 kB 9.1%
🟡 _libs/@ai-sdk/gateway+[...].mjs [####....................] 432.8 kB 5.1%
🟠 Other bundled files             [########################] 2.38 MB 27.9%

🧾 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: 1.85 s -> 1.79 s (-64.3 ms) vs instr/08-bus-hardening (585fe33).
• Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `instr/08-bus-hardening (585fe33)`

Phase	Baseline	Current	Delta
extension.check	9.2 ms	0.8 ms	-8.4 ms
project.resolve	3.5 ms	0.4 ms	-3.1 ms
workspace.create	1.0 ms	0.5 ms	-0.5 ms
host.prepare	286.8 ms	215.7 ms	-71.1 ms
vercel.service-prefix.resolve	1.4 ms	1.6 ms	+0.2 ms
nitro.create	150.5 ms	181.4 ms	+30.9 ms
sandbox.prewarm	306.0 ms	285.7 ms	-20.3 ms
nitro.cache.prepare	0.2 ms	0.2 ms	0.0 ms
nitro.prepare	0.6 ms	0.6 ms	0.0 ms
nitro.public-assets	0.6 ms	0.5 ms	-0.1 ms
nitro.prerender	0.3 ms	0.4 ms	+0.1 ms
nitro.bundle	1.04 s	1.05 s	+11.7 ms
nitro.cache.write	0.2 ms	0.3 ms	+0.1 ms
vercel.workflow-function.materialize	48.7 ms	35.7 ms	-13.0 ms
agent-summary.emit	0.5 ms	0.5 ms	0.0 ms
nitro.close	0.1 ms	0.1 ms	0.0 ms
output.publish	2.6 ms	11.9 ms	+9.3 ms
workspace.remove	1.6 ms	1.7 ms	+0.1 ms

[vercel]

agentRuns({ recordInputs: false }) silently leaks declined prompts/outputs to Vercel Agent Runs whenever a sibling OTel destination records content, because the "auto" exporter is never wrapped in a content-filtering processor and cannot drop declined content on its way out.