feat(eve): run task subagents as background tools

[ruiconti]

Summary

Related to #1084. With experimental.tasks, subagents still left the AI SDK tool loop as RuntimeActions, which forced subagent-specific execution into the harness path. This replaces that path with a generic background defineTool contract: defineSubagent and defineRemoteSubagent are ordinary tool definitions, the AI SDK executes sibling calls concurrently, and a task provider commits their durable receipts and executor effects.

Before → model tool call → RuntimeAction batch → post-model subagent dispatch.

After → model tool call → background defineTool.execute → generic durable task lifecycle → existing local or remote child dispatch.

The flag-off path still uses the existing RuntimeAction behavior. The background authoring surface remains experimental, adds no runtime dependency, and includes a minor changeset because generic task metadata widens the extension-facing task view. The main review boundary is the generic commit barrier: a parent session records every successfully delegated task before releasing child readiness; failures and authorization parks reject provisional tasks, while parent cancellation retains work that was already delegated. None of these paths serializes sibling calls.

Validation

The complete eve unit suite passed with 6,851 tests and one skip, and the complete integration suite passed with 657 tests. Coverage exercises real AI SDK sibling concurrency, repeated tool phases, local and remote child dispatch, task receipts, rollback, cancellation, fast completion, and authorization parking. A real Vercel weather-fixture build measured 9,021,573 bytes per function, +32,262 bytes (0.359%) from github/main, with no new functions or public routes and no size-budget failure.

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)

Diff size

Docs — 3 files · +55 / -20

The tool guide documents the experimental contract, the research plan records the settled ownership boundaries, and the changeset describes the published behavior.

Implementation — 40 files · +1622 / -206

Most of this category is the generic task provider and the local subagent definition that now owns child dispatch and executor-specific session effects. The existing task runtime still owns HITL and cancellation. The remaining changes carry the background execution discriminator through compilation, generalize task metadata and transitions, and record generated extension contract epochs.

Tests — 11 files · +905 / -11

Two new suites account for most of the additions: one proves generic AI SDK execution and rollback boundaries, and one runs concurrent local and remote definitions against the real task runtime. Existing tests cover feature gating, transition races, cancellation adoption, type inference, and extension compatibility.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
eve-docs	Ready	Preview	Aug 20, 2026 2:52pm
eve-docs-4759	Ready	Preview, v0	Aug 20, 2026 2:52pm
eve-rr	Error		Aug 20, 2026 2:52pm

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
eve-pkg	Skipped		Aug 20, 2026 2:52pm

[github-actions]

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

Key takeaways

• No notable deltas vs main (e843b4d).

Delta vs main (e843b4d)

Area	Metric	Baseline	Current	Delta
Package	Packed tarball	8.12 MB	8.13 MB	+11.4 kB ⚠️
Package	Unpacked publish size	30.56 MB	30.61 MB	+45.4 kB ⚠️
Package	Installed footprint	74.58 MB	74.62 MB	+45.4 kB ⚠️
Package	Published files	3352	3362	+10
Package	Installed files	7061	7071	+10
Package	Installed package instances	35	35	0
Package	Distinct installed package names	34	34	0
Package	Installed dependency edges	53	53	0
Package	Installed optional peer edges	47	47	0
Runtime	Unique function payloads	2	2	0
Runtime	Total function bytes	18.09 MB	18.16 MB	+71.2 kB ⚠️
Runtime	Public routes	16	16	0

Changed function payloads vs main (e843b4d) (2)

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

eve init install

Metric	Baseline	Current	Delta
Installed footprint	112.99 MB	113.03 MB	+45.4 kB ⚠️
Installed packages	121	121	0
dependencies	4	4	0
devDependencies	2	2	0
Dependency package bytes	45.08 MB	45.12 MB	+45.4 kB ⚠️
devDependency package bytes	5.04 MB	5.04 MB	0 B ➖

eve init dependency changes vs main (e843b4d)

dependencies

• Changed: eve@file:eve-0.39.3.tgz -> eve@file:eve-0.40.0.tgz

Build Metadata

• Preset: vercel
• Nitro: nitro@3.0.260610-beta
• Output directory: apps/fixtures/weather-agent/.vercel/output
• Build metadata timestamp: 2026-08-20T14:53:26.030Z
• Route aliases: 16 public, 1 internal (17 total aliases)
• Vercel routes in config: 19
• Severity legend: 🔴 dominant/large, 🟠 notable, 🟡 watch, ⚪ small

Package Drill-Down

Package Details

• Package: eve@0.40.0
• Package directory: packages/eve
• Tarball: 8.13 MB (eve-0.40.0.tgz)
• Unpacked payload: 30.61 MB across 3362 published files
• Installed footprint: 74.62 MB across 7071 installed files
• Installed root package: 29.25 MB
• Installed dependencies: 45.37 MB
• Installed package instances: 35
• Distinct installed package names: 34
• Installed dependency edges: 53
• Installed optional peer edges: 47
• Runtime dependencies: 2
• Peer dependencies: 5 (4 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: 29.25 MB (39.2%)
• @rolldown/binding-linux-x64-gnu: 19.91 MB (26.7%)
• ai: 6.71 MB (9.0%)
• zod: 5.07 MB (6.8%)
• undici: 3.50 MB (4.7%)

Publish payload breakdown

Published file size
🔴 dist/src/compiled/shadcn-registry/index.js       [###############.........] 9.76 MB 31.9%
🟠 dist/src/compiled/@photon-ai/chat-adapter-ime... [####....................] 2.44 MB 8.0%
🟠 dist/src/compiled/experimental-ai-sdk-code-mo... [##......................] 1.51 MB 4.9%
🟡 dist/src/compiled/_chunks/workflow/undici-Dzn... [#.......................] 512.7 kB 1.7%
🟡 dist/src/compiled/_chunks/node/undici-CUIybhQ... [#.......................] 508.8 kB 1.7%
🔴 Other published files                            [########################] 15.88 MB 51.9%

Installed footprint breakdown

Installed package size
🔴 eve                             [########################] 29.25 MB 39.2%
🔴 @rolldown/binding-linux-x64-gnu [################........] 19.91 MB 26.7%
🔴 ai                              [######..................] 6.71 MB 9.0%
🔴 zod                             [####....................] 5.07 MB 6.8%
🟠 undici                          [###.....................] 3.50 MB 4.7%
🟠 nitro                           [##......................] 2.41 MB 3.2%
🔴 Other installed packages        [######..................] 7.77 MB 10.4%

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

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

Heavy installed dependencies

• eve: 29.25 MB (25.9%)
• @typescript/typescript-linux-x64: 27.95 MB (24.7%)
• @rolldown/binding-linux-x64-gnu: 19.91 MB (17.6%)
• zod: 9.02 MB (8.0%)
• ai: 6.71 MB (5.9%)

Installed footprint breakdown

Installed package size
🔴 eve                              [########################] 29.25 MB 25.9%
🔴 @typescript/typescript-linux-x64 [#######################.] 27.95 MB 24.7%
🔴 @rolldown/binding-linux-x64-gnu  [################........] 19.91 MB 17.6%
🔴 zod                              [#######.................] 9.02 MB 8.0%
🔴 ai                               [######..................] 6.71 MB 5.9%
🟠 undici                           [###.....................] 3.50 MB 3.1%
🔴 Other installed packages         [##############..........] 16.69 MB 14.8%

dependencies (4)

Package	Range	Installed size	Share
@vercel/connect	0.4.3	141.0 kB	0.1%
ai	^7.0.58	6.71 MB	5.9%
eve	file:eve-0.40.0.tgz	29.25 MB	25.9%
zod	4.4.3	9.02 MB	8.0%

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     [########################] 9.08 MB 50.0%
🔴 functions/__server.func                         [########################] 9.08 MB 50.0%

Top Function Payloads

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

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

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                     [##################......] 2.04 MB 22.5%
🟠 _chunks/runtime-artifacts.mjs [###############.........] 1.80 MB 19.8%
🟡 _libs/undici.mjs              [########................] 980.5 kB 10.8%
🟡 _chunks/sandbox.mjs           [#######.................] 781.9 kB 8.6%
🟡 _chunks/frames-Dl2Hcma4.mjs   [######..................] 678.7 kB 7.5%
🟠 Other bundled files           [########################] 2.80 MB 30.8%

🧾 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 • 15 public routes, 1 internal alias • 9.08 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/[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/task-input/[token]
Internal aliases	/__server
Runtime	nodejs24.x
Handler	index.mjs
Payload	9.08 MB
Function files	9.08 MB across 50 files
Traced dependencies	0 B
Signal	🟠 Bundled file index.mjs is 2.04 MB (22.5%)

🟠 🔎 Dependency Analysis

📦 Bundled files:

Bundled file size
🟠 index.mjs                     [##################......] 2.04 MB 22.5%
🟠 _chunks/runtime-artifacts.mjs [###############.........] 1.80 MB 19.8%
🟡 _libs/undici.mjs              [########................] 980.5 kB 10.8%
🟡 _chunks/sandbox.mjs           [#######.................] 781.9 kB 8.6%
🟡 _chunks/frames-Dl2Hcma4.mjs   [######..................] 678.7 kB 7.5%
🟠 Other bundled files           [########################] 2.80 MB 30.8%

🧾 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.20 s -> 2.25 s (+46.7 ms) vs main (e843b4d).
• Timing is informational: shared GitHub runners are too variable for a hard timing budget.

Detailed phase timings vs `main (e843b4d)`

Phase	Baseline	Current	Delta
extension.check	1.1 ms	1.1 ms	0.0 ms
project.resolve	0.3 ms	0.3 ms	0.0 ms
workspace.create	0.7 ms	0.8 ms	+0.1 ms
host.prepare	236.7 ms	239.6 ms	+2.9 ms
vercel.service-prefix.resolve	2.6 ms	2.6 ms	0.0 ms
nitro.create	260.5 ms	249.5 ms	-11.0 ms
sandbox.prewarm	248.0 ms	320.4 ms	+72.4 ms
nitro.cache.prepare	0.2 ms	0.3 ms	+0.1 ms
nitro.prepare	0.7 ms	0.9 ms	+0.2 ms
nitro.public-assets	0.7 ms	0.8 ms	+0.1 ms
nitro.prerender	0.5 ms	0.5 ms	0.0 ms
nitro.bundle	1.41 s	1.39 s	-17.9 ms
nitro.cache.write	0.4 ms	0.4 ms	0.0 ms
vercel.workflow-function.materialize	27.1 ms	26.9 ms	-0.2 ms
agent-summary.emit	0.5 ms	0.6 ms	+0.1 ms
nitro.close	0.2 ms	0.1 ms	-0.1 ms
output.publish	3.4 ms	3.6 ms	+0.2 ms
workspace.remove	2.4 ms	2.3 ms	-0.1 ms