feat(eve): instructions - add role-aware persisted context

[AndrewBarba]

Summary

Closes #2017.

Instructions now accept { content, role? }, with role defaulting to system. The legacy { markdown } shape remains source-compatible, is deprecated, and always materializes as system-role content.

System-role instructions remain outside durable model history. Static system instructions are rebuilt from the active deployment, while dynamic system instructions use session, turn, and step scope with narrower values shadowing the same resolver slug. They therefore survive history compaction and manual clear.

User-role instructions enter ordinary durable history. Static values are seeded once when a session is created and are not re-seeded during hydration or deployment refresh. Dynamic values append once at their matching session, turn, or step boundary. Once appended, either form can be summarized by compaction or removed by clear and is not restored.

Hooks and dynamic capability resolvers for instructions, tools, skills, and subagents receive the session, agent, channel, abort signal, sandbox/skill access, and model-history snapshot available at their existing lifecycle boundary. Discovery, compiled-manifest, agent-info, Vercel-summary, and affected extension capability contracts advance for the new instruction and callback shapes.

Scope boundary

This PR does not change dynamic model selection, event names, event ordering, or the stream protocol. The existing ambiguity around step-scoped dynamic model resolution is tracked separately in #2022.

Validation

• pnpm lint
• pnpm typecheck (36 workspace packages)
• pnpm guard:invariants
• pnpm docs:check
• pnpm update:extension-contracts --check
• pnpm test (all unit and integration tasks passed; eve reported 6,455 unit tests with 1 skipped and 641 integration tests)
• Focused final-branch unit suite (250 tests passed)
• pnpm test:scenario (384 passed, 15 skipped; two Bun-install cases were blocked by local private-registry 401s, while the three concurrent timing/init failures passed on isolated rerun)

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 because this touches the published eve package
• Every commit is signed and includes a DCO sign-off

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview	Aug 13, 2026 3:42am
eve-docs-4759	Ready	Preview, v0	Aug 13, 2026 3:42am

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
eve-pkg	Skipped		Aug 13, 2026 3:42am

[github-actions]

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

Key takeaways

• No notable deltas vs main (1cd563b).

Delta vs main (1cd563b)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	7.96 MB	7.96 MB	+1.9 kB ⚠️
Package	Unpacked publish size	29.73 MB	29.74 MB	+14.9 kB ⚠️
Package	Installed footprint	73.24 MB	73.26 MB	+14.9 kB ⚠️
Package	Published files	3178	3178	0
Package	Installed files	6888	6888	0
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	17.18 MB	17.19 MB	+10.2 kB ⚠️
Runtime	Public routes	14	14	0

Changed function payloads vs main (1cd563b) (2)

Function	Status	Baseline	Current	Delta	Route changes
functions/__server.func	changed	8.59 MB	8.60 MB	+5.1 kB ⚠️	none
functions/.well-known/workflow/v1/flow.func	changed	8.59 MB	8.60 MB	+5.1 kB ⚠️	none

eve init install

Metric	Baseline	Current	Delta
Installed footprint	111.65 MB	111.67 MB	+14.9 kB ⚠️
Installed packages	121	121	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	44.22 MB	44.23 MB	+14.9 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-13T03:43:38.556Z
• Route aliases: 14 public, 1 internal (15 total aliases)
• Vercel routes in config: 17
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.34.0
• Package directory: packages/eve
• Tarball: 7.96 MB (eve-0.34.0.tgz)
• Unpacked payload: 29.74 MB across 3178 published files
• Installed footprint: 73.26 MB across 6888 installed files
• Installed root package: 28.39 MB
• Installed dependencies: 44.87 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.39 MB (38.7%)
• @rolldown/binding-linux-x64-gnu: 19.41 MB (26.5%)
• ai: 6.68 MB (9.1%)
• zod: 5.07 MB (6.9%)
• undici: 3.50 MB (4.8%)

Publish payload breakdown

Published file size
🔴 dist/src/compiled/shadcn-registry/index.js       [#################.......] 10.19 MB 34.3%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [####....................] 2.42 MB 8.1%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [##......................] 1.51 MB 5.1%
🟡 dist/src/compiled/_chunks/workflow/undici-BNc... [#.......................] 508.8 kB 1.7%
🟡 dist/src/compiled/_chunks/node/undici-CUIybhQ... [#.......................] 508.8 kB 1.7%
🔴 Other published files                            [########################] 14.60 MB 49.1%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 28.39 MB 38.7%
🔴 @rolldown/binding-linux-x64-gnu [################........] 19.41 MB 26.5%
🔴 ai                              [######..................] 6.68 MB 9.1%
🔴 zod                             [####....................] 5.07 MB 6.9%
🟠 undici                          [###.....................] 3.50 MB 4.8%
🟠 nitro                           [##......................] 2.41 MB 3.3%
🔴 Other installed packages        [#######.................] 7.80 MB 10.6%

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.67 MB across 8764 installed files
• Installed packages: 121 total (115 transitive-only)
• dependencies: 4 direct packages totaling 44.23 MB
• devDependencies: 2 direct packages totaling 5.04 MB
• Other transitive package files: 62.39 MB

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

Heavy installed dependencies

• eve: 28.39 MB (25.4%)
• @typescript/typescript-linux-x64: 27.95 MB (25.0%)
• @rolldown/binding-linux-x64-gnu: 19.41 MB (17.4%)
• zod: 9.02 MB (8.1%)
• ai: 6.68 MB (6.0%)

Installed footprint breakdown

Installed package size
🔴 eve                              [########################] 28.39 MB 25.4%
🔴 @typescript/typescript-linux-x64 [########################] 27.95 MB 25.0%
🔴 @rolldown/binding-linux-x64-gnu  [################........] 19.41 MB 17.4%
🔴 zod                              [########................] 9.02 MB 8.1%
🔴 ai                               [######..................] 6.68 MB 6.0%
🟠 undici                           [###.....................] 3.50 MB 3.1%
🔴 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.58	6.68 MB	6.0%
eve	file:eve-0.34.0.tgz	28.39 MB	25.4%
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.60 MB 50.0%
🔴 functions/__server.func                         [########################] 8.60 MB 50.0%

Top Function Payloads

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

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

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.46 MB 28.6%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.64 MB 19.1%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.4%
🟡 _chunks/sandbox.mjs             [########................] 777.7 kB 9.0%
🟡 _chunks/token-util-DNwIAn_u.mjs [####....................] 381.0 kB 4.4%
🟠 Other bundled files             [#######################.] 2.36 MB 27.4%

🧾 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 • 13 public routes, 1 internal alias • 8.60 MB

Metric	Value
Public routes	/ /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/[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.60 MB
Function files	8.60 MB across 46 files
Traced dependencies	0 B
Signal	🟠 Bundled file index.mjs is 2.46 MB (28.6%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                       [########################] 2.46 MB 28.6%
🟠 _chunks/runtime-artifacts.mjs   [################........] 1.64 MB 19.1%
🟡 _libs/undici.mjs                [##########..............] 980.5 kB 11.4%
🟡 _chunks/sandbox.mjs             [########................] 777.7 kB 9.0%
🟡 _chunks/token-util-DNwIAn_u.mjs [####....................] 381.0 kB 4.4%
🟠 Other bundled files             [#######################.] 2.36 MB 27.4%

🧾 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.35 s -> 1.97 s (-375.8 ms) vs main (1cd563b).
• Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `main (1cd563b)`

Phase	Baseline	Current	Delta
extension.check	1.3 ms	1.3 ms	0.0 ms
project.resolve	0.6 ms	0.7 ms	+0.1 ms
workspace.create	0.7 ms	0.7 ms	0.0 ms
host.prepare	538.7 ms	177.7 ms	-361.0 ms
vercel.service-prefix.resolve	2.3 ms	2.0 ms	-0.3 ms
nitro.create	222.6 ms	226.9 ms	+4.3 ms
sandbox.prewarm	211.3 ms	167.6 ms	-43.7 ms
nitro.cache.prepare	0.3 ms	0.2 ms	-0.1 ms
nitro.prepare	0.8 ms	0.8 ms	0.0 ms
nitro.public-assets	0.8 ms	0.7 ms	-0.1 ms
nitro.prerender	0.5 ms	0.5 ms	0.0 ms
nitro.bundle	1.34 s	1.37 s	+26.2 ms
nitro.cache.write	0.3 ms	0.3 ms	0.0 ms
vercel.workflow-function.materialize	21.7 ms	20.5 ms	-1.2 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	3.3 ms	3.3 ms	0.0 ms
workspace.remove	1.9 ms	1.9 ms	0.0 ms