feat(eve): compile agent/instrumentation/ behind a flag

[chadhietala]

Summary

Fifth in the instrumentation-provider stack, on top of #1686.

The settled proposal replaces the single agent/instrumentation.ts config object with an agent/instrumentation/ directory holding one provider per file. This adds experimental.instrumentationProviders, off by default, and teaches the compiler to read whichever layout the flag selects. Flag off, nothing changes — the new provider types ship unconditionally but are inert, because nothing discovers the directory. Flag on, eve compiles every file in the directory and awaits each provider's setup before any event is published. Mixing the two layouts is a build error naming the flag and the other layout, never a silent ignore: telemetry that quietly does nothing is the bug class this design exists to fix.

Two parts deserve a closer look:

• Both layouts now share one setup context, which was not planned. A union of two differing setup signatures has no contextual signature, so every authored setup(context) parameter silently became an implicit any — the @eve-e2e/config fixture caught it as TS7031, and overloads cannot fix it. Identical signatures can, so InstrumentationSetupContext is now an alias of ProviderSetupContext and existing config authors gain environment and frameworkVersion alongside agentName. Additive, but a public type change that ships with the flag off.
• defineInstrumentation takes a union, which weakens its excess-property check: a misspelled key can reach eve build rather than failing at tsc. Nothing at the value level separates a provider from a config — they overlap on events and setup — so the layout decides, and the brand only catches a default export that never went through eve.

Out of scope, higher in the stack: agentRuns(), the otel()/otelIntegration() split, content and redaction options, bus hardening, and the docs for the authoring surface. The flag stays off.

Validation

• pnpm fmt, pnpm lint, pnpm guard:invariants
• pnpm typecheck — 33/33 projects
• pnpm test:unit — 6,070 passed, 1 skipped
• pnpm test:integration — 617 passed across 87 files
• compiled-artifacts-bootstrap and prepare-application-host scenarios — 8 passed
• A new flag-on scenario test compiles a real agent and imports the generated Nitro plugin, asserting one module per file, slot order, and that each setup is awaited. It reads the provider registry by package alias while the plugin writes it by absolute path, which also proves the globalThis rooting survives the two module instances Nitro produces.

Not run locally: e2e, which CI covers, and pnpm dev against the weather fixture with the flag on.

Checklist

• I linked an issue with prior discussion confirming this change is wanted
• I ran the relevant checks from CONTRIBUTING.md
• 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 (UTC)
eve-docs	Building	Preview	Aug 8, 2026 2:44pm
eve-docs-4759	Ready	Preview, v0	Aug 8, 2026 2:44pm

[github-actions]

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

Key takeaways

• No notable deltas vs instr/04-otel-provider (c0e749d).

Delta vs instr/04-otel-provider (c0e749d)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.69 MB	7.70 MB	+5.8 kB ⚠️
Package	Unpacked publish size	28.81 MB	28.83 MB	+17.2 kB ⚠️
Package	Installed footprint	72.24 MB	72.26 MB	+17.2 kB ⚠️
Package	Published files	3069	3077	+8
Package	Installed files	6779	6787	+8
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	17.07 MB	17.07 MB	+1.5 kB ⚠️
Runtime	Public routes	13	13	0

Changed function payloads vs instr/04-otel-provider (c0e749d) (2)

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

eve init install

Metric	Baseline	Current	Delta
Installed footprint	110.65 MB	110.67 MB	+17.2 kB ⚠️
Installed packages	121	121	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	43.29 MB	43.31 MB	+17.2 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-08T14:45:59.052Z
• 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.70 MB (eve-0.31.3.tgz)
• Unpacked payload: 28.83 MB across 3077 published files
• Installed footprint: 72.26 MB across 6787 installed files
• Installed root package: 27.47 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: 27.47 MB (38.0%)
• @rolldown/binding-linux-x64-gnu: 19.35 MB (26.8%)
• 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.6%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [####....................] 2.42 MB 8.4%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [###.....................] 1.51 MB 5.2%
🟡 dist/src/compiled/_chunks/workflow/undici-CUI... [#.......................] 508.8 kB 1.8%
🟡 dist/src/compiled/_chunks/node/undici-DWL_MYm... [#.......................] 502.4 kB 1.7%
🔴 Other published files                            [########################] 14.20 MB 49.3%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 27.47 MB 38.0%
🔴 @rolldown/binding-linux-x64-gnu [#################.......] 19.35 MB 26.8%
🔴 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.8%

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: 110.67 MB across 8663 installed files
• Installed packages: 121 total (115 transitive-only)
• dependencies: 4 direct packages totaling 43.31 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

• @typescript/typescript-linux-x64: 27.95 MB (25.3%)
• eve: 27.47 MB (24.8%)
• @rolldown/binding-linux-x64-gnu: 19.35 MB (17.5%)
• zod: 9.02 MB (8.2%)
• ai: 6.67 MB (6.0%)

Installed footprint breakdown

Installed package size
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 25.3%
🔴 eve                              [########################] 27.47 MB 24.8%
🔴 @rolldown/binding-linux-x64-gnu  [#################.......] 19.35 MB 17.5%
🔴 zod                              [########................] 9.02 MB 8.2%
🔴 ai                               [######..................] 6.67 MB 6.0%
🟠 undici                           [###.....................] 3.50 MB 3.2%
🔴 Other installed packages         [##############..........] 16.71 MB 15.1%

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	27.47 MB	24.8%
zod	4.4.3	9.02 MB	8.2%

devDependencies (2)

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

Function Drill-Down

Payload Size Graph

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

Top Function Payloads

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

Metric	Value
Public routes	/.well-known/workflow/v1/flow
Runtime	nodejs24.x
Handler	index.mjs
Payload	8.53 MB
Function files	8.53 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             [########................] 769.0 kB 9.0%
🟡 _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.53 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.53 MB
Function files	8.53 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             [########................] 769.0 kB 9.0%
🟡 _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: 2.22 s -> 2.22 s (0.0 ms) vs instr/04-otel-provider (c0e749d).
• Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `instr/04-otel-provider (c0e749d)`

Phase	Baseline	Current	Delta
extension.check	16.0 ms	12.8 ms	-3.2 ms
project.resolve	3.3 ms	6.5 ms	+3.2 ms
workspace.create	7.8 ms	1.4 ms	-6.4 ms
host.prepare	258.1 ms	229.2 ms	-28.9 ms
vercel.service-prefix.resolve	2.2 ms	2.3 ms	+0.1 ms
nitro.create	209.4 ms	218.3 ms	+8.9 ms
sandbox.prewarm	294.0 ms	306.6 ms	+12.6 ms
nitro.cache.prepare	0.3 ms	0.3 ms	0.0 ms
nitro.prepare	1.0 ms	1.0 ms	0.0 ms
nitro.public-assets	0.7 ms	0.8 ms	+0.1 ms
nitro.prerender	0.6 ms	0.5 ms	-0.1 ms
nitro.bundle	1.37 s	1.41 s	+36.8 ms
nitro.cache.write	0.3 ms	0.5 ms	+0.2 ms
vercel.workflow-function.materialize	36.2 ms	23.5 ms	-12.7 ms
agent-summary.emit	0.5 ms	0.6 ms	+0.1 ms
nitro.close	0.1 ms	0.1 ms	0.0 ms
output.publish	13.4 ms	3.6 ms	-9.8 ms
workspace.remove	2.6 ms	2.1 ms	-0.5 ms