eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,9 +3,7 @@ title: "Remote Agents"
3
3
  description: "Call another eve deployment as a subagent with defineRemoteAgent: the same tool call as a local subagent, with outbound auth and durable callbacks."
4
4
  ---
5
5
 
6
- `defineRemoteAgent` calls a separately deployed eve agent as if it were a local subagent. Reach for it when the specialist you delegate to is a separately owned agent behind its own URL rather than a directory in your repo.
7
-
8
- The file lives under `agent/subagents/`, so its tool name is derived from the path. There's no `name` field.
6
+ A remote agent is a separately deployed eve agent that your agent calls as a subagent. Define one with `defineRemoteAgent` in a file under `agent/subagents/`. The tool name comes from the file path, so `agent/subagents/weather.ts` is the `weather` tool.
9
7
 
10
8
  ```ts title="agent/subagents/weather.ts"
11
9
  import { defineRemoteAgent } from "eve";
@@ -20,93 +18,25 @@ export default defineRemoteAgent({
20
18
 
21
19
  `defineRemoteAgent` accepts:
22
20
 
23
- | Parameter | Type | Required | Default | Description |
24
- | ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
25
- | `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Use a function for [runtime URLs](#runtime-urls). |
26
- | `description` | `string` | Yes | n/a | Model-visible delegation description. |
27
- | `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
28
- | `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
29
- | `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
30
- | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
31
- | `tool` | `boolean \| "deferred"` | No | `true` | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools. |
32
-
33
- ## Dynamic remote agents
34
-
35
- Wrap the file in `defineDynamic` when the target or its availability depends on
36
- the current session. The function returns `defineRemoteAgent(...)` to expose it or `null` to omit it:
37
-
38
- ```ts title="agent/subagents/weather.ts"
39
- import { defineDynamic, defineRemoteAgent } from "eve";
40
-
41
- export default defineDynamic((ctx) =>
42
- ctx.session.auth.current?.attributes.region === "us"
43
- ? defineRemoteAgent({
44
- description: "Answers weather questions for US customers.",
45
- url: "https://us-weather-agent.example.com",
46
- })
47
- : null,
48
- );
49
- ```
50
-
51
- eve evaluates the function before each ordinary model call. `auth` and `headers` can close over
52
- its context or memo results. They resolve before each outbound request; credentials are not
53
- memo results and must not be stored in them.
54
-
55
- ```ts title="agent/subagents/finance.ts"
56
- import { defineDynamic, defineRemoteAgent } from "eve";
57
- import { mintFinanceToken } from "../lib/finance";
58
-
59
- export default defineDynamic((ctx) => {
60
- const tenant = ctx.session.auth.current?.attributes.tenant;
61
- return typeof tenant === "string"
62
- ? defineRemoteAgent({
63
- description: "Analyzes the tenant's financial data.",
64
- url: "https://finance-agent.example.com",
65
- auth: async () => ({
66
- headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` },
67
- }),
68
- })
69
- : null;
70
- });
71
- ```
72
-
73
- A child keeps the parent context and memo results used to select its remote configuration.
74
- Later messages, answers, cancellation, session retirement, and stream reads use that original selection when
75
- rebuilding transport credentials. Only saved memo results are available: a missing result or a
76
- changed child name or URL fails before credentials are sent. `ctx.messages()` is unavailable
77
- during this reconstruction, including when eve opens the child; keep conversation-based
78
- selection inside a memo. This does not change the per-message caller identity described in
79
- [Forwarding the caller identity](#forwarding-the-caller-identity). See
80
- [Dynamic capabilities](./dynamic-capabilities#dynamic-subagents) for the memo rules.
81
-
82
- ## Runtime URLs
83
-
84
- A string `url` is read at compile time. Use a function when an environment variable
85
- supplies the URL only at runtime. eve invokes it when resolving the runtime agent graph;
86
- it can return a string or a promise:
87
-
88
- ```ts title="agent/subagents/weather.ts"
89
- import { defineRemoteAgent } from "eve";
90
-
91
- export default defineRemoteAgent({
92
- url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
93
- description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
94
- });
95
- ```
96
-
97
- The resolved `url` must be a non-empty string. Use `defineDynamic` when the current
98
- session determines which agent is exposed or whether it is available.
99
- `auth` and `headers` remain lazy callbacks resolved per request.
21
+ | Parameter | Type | Required | Default | Description |
22
+ | ------------------ | --------------------------------------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
+ | `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Pass a function to [read it at runtime](#runtime-urls). |
24
+ | `description` | `string` | Yes | n/a | What the parent model reads to decide when to delegate. |
25
+ | `auth` | `OutboundAuthFn` | No | none | Outbound auth from `eve/agents/auth`. |
26
+ | `forwardPrincipal` | `boolean` | No | `false` | Send the calling turn's user identity to the remote deployment. See [Forwarding the caller identity](#forwarding-the-caller-identity). |
27
+ | `headers` | `HeadersValue` | No | none | Request headers, static or resolved for each request. |
28
+ | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` to create the remote session. |
29
+ | `tool` | `boolean \| "deferred"` | No | `true` | `false` lets only authored workflow tools call it, through `ctx.agent()`. `"deferred"` keeps it out of the tool list but findable with `eve__search` and callable with `eve__tool`. |
100
30
 
101
31
  ## Calling a remote agent
102
32
 
103
- By default, a remote agent is another subagent tool to the model. The model calls it the same way it calls a local subagent, with a `message` and an optional `taskId`. Set `tool: false` when an authored workflow tool should be the only model-facing routing surface; the workflow can still call the remote agent by its path-derived name through `ctx.agent()`. Set `tool: "deferred"` to keep the remote agent out of the model's tool list while the model can still find it with `eve__search` and call it with `eve__tool`. The message must carry the full task, including any context the remote agent needs, because it never receives the parent's conversation history.
33
+ The model calls a remote agent like a local subagent, with a `message` and an optional `taskId`. Put the full task and context in the message, because the remote agent never sees the parent's conversation.
104
34
 
105
- To require structured output, open a session with the remote agent from an authored workflow tool with `ctx.agent(name)` and pass `outputSchema` to `send()`. The schema applies to that turn, the structured value is the response's `data`, and the session accepts follow-up messages until the workflow run finishes. See [Delegate work: `ctx.agent`](../tools/workflows#delegate-work-ctxagent).
35
+ A workflow tool calls the remote agent by its file name through `ctx.agent(name)`. For structured output, pass `outputSchema` to `send()` and read the value from the response's `data`. See [Delegate work: `ctx.agent`](../tools/workflows#delegate-work-ctxagent).
106
36
 
107
37
  ## Outbound auth
108
38
 
109
- Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as shown in the first example on this page.
39
+ Use `vercelOidc()` from `eve/agents/auth` when one Vercel-deployed eve agent calls another, as in the first example.
110
40
 
111
41
  For calls between different Vercel projects, allow the calling project on the receiving agent's eve channel:
112
42
 
@@ -131,13 +61,11 @@ export default eveChannel({
131
61
 
132
62
  Set `teamSlug`, `projectName`, and `environment` to the calling deployment's Vercel OIDC subject. See [subject patterns and `vercelSubject(...)`](./auth-and-route-protection#subjects-patterns-and-vercelsubject) for other environments and wildcard matching.
133
63
 
134
- If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is active on the receiving project, also configure [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources) to allow the calling project and environment. The eve subject allowlist and Trusted Sources are separate checks; cross-project calls need both.
64
+ If [Vercel Deployment Protection](https://vercel.com/docs/deployment-protection) is on for the receiving project, also allow the calling project and environment in [Trusted Sources](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/trusted-sources). Calls between projects must pass both the eve subject allowlist and Trusted Sources.
135
65
 
136
66
  ## Forwarding the caller identity
137
67
 
138
- Outbound auth authenticates your _deployment_ to the remote, so by default the remote session runs as your calling app — not as the end user who is talking to your agent. That breaks per-user workloads on the remote deployment, most directly per-user [Vercel Connect](./auth-and-route-protection#tool-and-connection-auth), which requires an authenticated `user` principal on the session.
139
-
140
- Set `forwardPrincipal: true` to forward the dispatching turn's session principal across the hop:
68
+ Outbound auth proves which _deployment_ is calling, so by default the remote session runs as your app, not as the end user. Work that must run as the user on the remote, such as per-user [Vercel Connect](./auth-and-route-protection#tool-and-connection-auth), needs the user's identity. Set `forwardPrincipal: true` to send it:
141
69
 
142
70
  ```ts title="agent/subagents/site-ops.ts"
143
71
  import { defineRemoteAgent } from "eve";
@@ -151,45 +79,89 @@ export default defineRemoteAgent({
151
79
  });
152
80
  ```
153
81
 
154
- The create-session request carries the parent turn's `session.auth.current` and `session.auth.initiator` as a `forwardedPrincipal` body field (`initiator` is optional on the wire; when absent, the receiver seeds both from `current`). A continuation by `taskId` carries the `session.auth.current` of the call that continues the task; the remote session keeps its original `auth.initiator`. Only principal metadata crosses the wire — never tokens or credentials. The receiving deployment resolves its own per-user credentials through its own connections.
82
+ - When eve creates the remote session, it sends the parent turn's `session.auth.current` and `session.auth.initiator`. When `initiator` is absent, the receiver uses `current` for both.
83
+ - A follow-up with `taskId` sends the follow-up call's `session.auth.current`. The remote session keeps its original `auth.initiator`.
84
+ - eve sends only identity metadata, never tokens or credentials. The receiver gets per-user credentials through its own connections.
85
+
86
+ Each turn runs as its own caller, even in a child session that persists. If Alice starts the child and Bob continues it with its `taskId`, the follow-up runs with Bob as `auth.current`. If the parent turn's auth is `null`, a local child clears `auth.current`, and a remote child runs as the verified calling deployment. Neither runs as Alice. A later turn can use only the OAuth grant of its own `auth.current` user.
155
87
 
156
- This makes caller authority turn-scoped even when the remote child session is persistent. If Alice starts the child and Bob later continues it with its `taskId`, the follow-up runs with Bob as `auth.current`, not Alice. If the parent turn's auth is `null`, a local child clears `auth.current`, while a remote child uses the freshly verified transport principal; neither inherits Alice. eve's in-step bearer cache is also keyed by the resolved principal and is not serialized across steps. The external authorization provider may preserve each user's server-side OAuth grant, but a later turn can resolve only the grant belonging to its own `auth.current` principal.
88
+ Forwarding doesn't make a child session private to one caller: its conversation history, tool outputs, and other state persist. If they must not be visible across users, give each user a separate child session or check ownership in your application.
157
89
 
158
- Identity forwarding does not make a persistent session private to one caller. Conversation history, tool outputs, and other child-session state still persist. If those values must not be visible across users, give each user a distinct child session or enforce that ownership at the application boundary.
90
+ The receiver must opt in. It names trusted deployments with `eveChannel({ trustedForwarders })` and can limit which users each one may assert (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)). A refused deployment or identity gets a 403. The same trust decision covers the parent session link and, with forwarding on, trace-content limits.
159
91
 
160
- Forwarding identity is explicit on both sides. The receiver names which deployments it trusts with `eveChannel({ trustedForwarders })` and can limit each one to the principals it may assert (see [Auth & route protection](./auth-and-route-protection#accepting-forwarded-identity-from-another-deployment)); refusing the forwarder or what it asserts rejects a forwarded principal with a 403. The same trust decision covers parent session lineage and, with principal forwarding, trace-content constraints.
92
+ ## Dynamic remote agents
93
+
94
+ Wrap the definition in `defineDynamic` when the target or whether to offer it depends on the session. Return `defineRemoteAgent(...)` to offer it or `null` to hide it:
95
+
96
+ ```ts title="agent/subagents/weather.ts"
97
+ import { defineDynamic, defineRemoteAgent } from "eve";
98
+
99
+ export default defineDynamic((ctx) =>
100
+ ctx.session.auth.current?.attributes.region === "us"
101
+ ? defineRemoteAgent({
102
+ description: "Answers weather questions for US customers.",
103
+ url: "https://us-weather-agent.example.com",
104
+ })
105
+ : null,
106
+ );
107
+ ```
108
+
109
+ eve runs the function before each ordinary model call. `auth` and `headers` can use its context or memo results, and they run before each outbound request. Don't store credentials in memo results.
110
+
111
+ ```ts title="agent/subagents/finance.ts"
112
+ import { defineDynamic, defineRemoteAgent } from "eve";
113
+ import { mintFinanceToken } from "../lib/finance";
114
+
115
+ export default defineDynamic((ctx) => {
116
+ const tenant = ctx.session.auth.current?.attributes.tenant;
117
+ return typeof tenant === "string"
118
+ ? defineRemoteAgent({
119
+ description: "Analyzes the tenant's financial data.",
120
+ url: "https://finance-agent.example.com",
121
+ auth: async () => ({
122
+ headers: { authorization: `Bearer ${await mintFinanceToken(tenant)}` },
123
+ }),
124
+ })
125
+ : null;
126
+ });
127
+ ```
128
+
129
+ A child keeps the parent context and memo results that chose its configuration:
130
+
131
+ - Later messages, answers, cancellation, ending the session, and stream reads rebuild the credentials from that original context, not from a newer caller.
132
+ - If a memo result is missing, or the child's name or URL changed, the request fails before eve sends credentials.
133
+ - `ctx.messages()` is unavailable during this rebuild, including when eve opens the child, so keep decisions based on the conversation inside a memo.
134
+
135
+ Each message still runs as its own caller, as described in [Forwarding the caller identity](#forwarding-the-caller-identity). See [Dynamic capabilities](./dynamic-capabilities#memo-rules) for the memo rules.
136
+
137
+ ## Runtime URLs
138
+
139
+ eve reads a string `url` at build time. When an environment variable supplies the URL only at runtime, pass a function. It returns a string or a promise, and eve calls it when it resolves the runtime agent graph:
140
+
141
+ ```ts title="agent/subagents/weather.ts"
142
+ import { defineRemoteAgent } from "eve";
143
+
144
+ export default defineRemoteAgent({
145
+ url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
146
+ description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
147
+ });
148
+ ```
149
+
150
+ The resolved `url` must be a non-empty string. To choose which agent to offer, or whether to offer one, from the current session, use [`defineDynamic`](#dynamic-remote-agents).
161
151
 
162
152
  ## Trace propagation
163
153
 
164
- A remote child starts its own trace with a root `invoke_agent` span. When caller
165
- trace context is available, the first turn links to the dispatch span with
166
- `eve.link.type=agent.dispatch`. The receiving deployment applies its sampler.
167
- Later turns start new traces without the original dispatch link. The first turn
168
- of a local child can use the remote agent's trace as a nested span.
154
+ A remote child starts its own trace with a root `invoke_agent` span, sampled by the receiving deployment. When the caller's trace context is available, the child's first turn links to the calling span with `eve.link.type=agent.dispatch`. Later turns start new traces without that link. The remote agent's local children can nest their first turn under its trace.
169
155
 
170
- Use `gen_ai.conversation.id` to find all turns and child sessions for one
171
- conversation. The child has its own session ID, message history, and agent
172
- state. Trace context identifies related work. It does not give authorization.
173
- See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure.
156
+ Use `gen_ai.conversation.id` to find all turns and child sessions for one conversation. Trace context only links related work; it doesn't authorize anything. See [OpenTelemetry](../observability/otel#trace-topology) for the trace structure.
174
157
 
175
- eve carries parent session lineage separately. The receiver accepts it only
176
- when `trustedForwarders` approves the authenticated caller; otherwise, trace
177
- correlation continues without it.
158
+ The receiver accepts the parent session link only when `trustedForwarders` approves the caller. Otherwise, traces still correlate without it.
178
159
 
179
- On Vercel, a remote agent's spans and its local subagents' spans carry the
180
- remote session's ID as `vercel.session_id`, so the receiving project groups
181
- them as their own session. `gen_ai.conversation.id` still names the sender's
182
- conversation, and the remote agent's `agent.parent_run.id` names the calling
183
- session.
160
+ On Vercel, spans from a remote agent and its local subagents carry the remote session's ID as `vercel.session_id`. The receiving project groups them as their own session. `gen_ai.conversation.id` still names the sender's conversation, and `agent.parent_run.id` names the calling session.
184
161
 
185
162
  ## Preserving trace content
186
163
 
187
- With `forwardPrincipal: true`, a sampled remote dispatch forwards its original
188
- audience and the maximum input and output content the next hop may record. eve
189
- sends this policy as [W3C Baggage](https://www.w3.org/TR/baggage/).
190
-
191
- The receiving deployment uses the policy only after it trusts the calling
192
- deployment:
164
+ With `forwardPrincipal: true`, a sampled remote call forwards its audience and the most input and output content the next hop may record, as [W3C Baggage](https://www.w3.org/TR/baggage/). The receiver uses this policy only from a trusted caller:
193
165
 
194
166
  ```ts title="agent/channels/eve.ts"
195
167
  import { eveChannel } from "eve/channels/eve";
@@ -202,105 +174,71 @@ export default eveChannel({
202
174
  });
203
175
  ```
204
176
 
205
- The request must include a callback and a valid sampled `traceparent`.
206
- `trustedForwarders` is the authorization boundary. When the assertion is
207
- accepted, the receiver uses the forwarded audience instead of reclassifying
208
- the child session with its local channel.
177
+ The request must include a callback and a valid sampled `traceparent`; `trustedForwarders` is the authorization boundary. An accepted audience replaces the one the receiver's channel would assign.
209
178
 
210
- The receiver combines the forwarded ceiling with its own trace policy. Each
211
- hop may narrow content capture, but cannot restore inputs or outputs removed by
212
- an earlier hop. Missing, malformed, unsampled, or untrusted assertions do not
213
- widen capture and use metadata-only tracing.
179
+ The receiver combines the forwarded limit with its own trace policy. Each hop can capture less content but can't restore what an earlier hop removed. A missing, malformed, unsampled, or untrusted value falls back to metadata-only tracing.
214
180
 
215
181
  ## How remote dispatch and callbacks work
216
182
 
217
- A remote subagent call runs a child session in the remote deployment as a task:
183
+ A remote subagent call runs a child session on the remote deployment as a task:
218
184
 
219
- 1. The parent starts a persistent conversation session on the remote's `POST /eve/v1/session`, passing a framework callback URL.
185
+ 1. The parent starts a conversation session on the remote's `POST /eve/v1/session` and passes a callback URL.
220
186
  2. The remote accepts the child and runs its turn while the task works.
221
- 3. The callback delivers the child's reply, which becomes the task's result.
187
+ 3. The callback returns the child's reply, which becomes the task's result.
222
188
 
223
- The callback URL must use `http` or `https` and reach the parent at a public address. The remote rejects a create-session request whose callback host is a private, link-local, or reserved IP address, and refuses to deliver a callback to a hostname that resolves to one. A refused delivery fails without retries. Loopback hosts such as `localhost` and `127.0.0.1` work only when the remote runs as a local development server (`eve dev` or `vercel dev`), so parents and remotes that reach each other over a private network can't exchange callbacks.
189
+ The parent stream shows the same `task.started`, `child.opened`, and `call.settled` events as local delegation.
224
190
 
225
- Callback URLs contain only the message's callback capability, never the parent's deployment-protection bypass secret. For a parent protected by Vercel Deployment Protection, configure Trusted Sources on the parent to admit the remote project and environment.
191
+ The callback URL must use `http` or `https` and reach the parent at a public address. The remote refuses a callback host that is, or resolves to, a private, link-local, or reserved IP address, and a refused callback fails without retries. Loopback hosts such as `localhost` and `127.0.0.1` work only when the remote runs `eve dev` or `vercel dev`. A parent and remote on a private network can't exchange callbacks.
226
192
 
227
- On the remote deployment, set `EVE_CALLBACK_TRUSTED_ORIGINS` to a comma-separated list of parent HTTPS origins, for example `https://parent.example.com`. Each entry is an exact origin or starts with a `*.` label, as described below. The remote attaches its own short-lived Vercel OIDC token only to those origins and its own deployment origins; an exact entry does not extend trust to other ports or subdomains. Keep the remote's Vercel OIDC token available at runtime. Callbacks do not follow redirects.
193
+ A callback URL carries only the message's callback capability, never the parent's deployment protection bypass secret. To let callbacks reach a parent behind Vercel Deployment Protection, configure Trusted Sources on the parent to admit the remote's project and environment.
228
194
 
229
- Outside production, a parent's callback URL uses its generated deployment URL, which changes with every deployment. If those deployments are served under a domain you control, trust them with a leading `*.` label, for example `https://*.preview.example.com`. The wildcard matches exactly one label (`parent-abc123.preview.example.com`, but not `preview.example.com` or `a.b.preview.example.com`), and the port still has to match. It must be followed by at least two labels, and entries with a trailing dot are rejected. eve also rejects `https://*.vercel.app`, because every Vercel deployment shares that domain, but it does not detect other shared domains such as `*.github.io`.
195
+ On the remote deployment, set `EVE_CALLBACK_TRUSTED_ORIGINS` to a comma-separated list of parent HTTPS origins, such as `https://parent.example.com`. Each entry is an exact origin, or starts with a `*.` label as described below. The remote attaches its own short-lived Vercel OIDC token only to those origins and to its own deployment origins. An exact entry doesn't trust other ports or subdomains. Keep the remote's Vercel OIDC token available at runtime. Callbacks don't follow redirects.
230
196
 
231
- Adding an origin grants trust: that recipient receives a bearer credential for the remote project's identity, not a token scoped to the callback recipient. List only parents you trust to act as the remote project until the token expires, and use a wildcard only when you control every host under it. A recipient can replay the token against other services, deployment-protection rules, or federated cloud roles that accept that identity.
197
+ Outside production, a parent's callback URL uses its generated deployment URL, which changes with every deployment. If you serve those deployments under a domain you control, trust them with a leading `*.` label, such as `https://*.preview.example.com`:
232
198
 
233
- This configuration is required when upgrading a protected cross-project setup that previously relied on a bypass secret in callback URLs. If either side is not on Vercel, make the capability-protected callback route reachable through your hosting policy; the framework does not forward a deployment-wide credential to the remote service.
199
+ - The wildcard matches exactly one label: `parent-abc123.preview.example.com`, but not `preview.example.com` or `a.b.preview.example.com`.
200
+ - The port must still match.
201
+ - At least two labels must follow the wildcard, and an entry with a trailing dot is rejected.
202
+ - eve rejects `https://*.vercel.app`, because every Vercel deployment shares that domain. It doesn't detect other shared domains, such as `*.github.io`.
234
203
 
235
- The parent stream carries the same `task.started`, `child.opened`, and `call.settled` facts as local delegation. A remote child's deployment binding is private: only the parent's stream proxy reads it.
204
+ Each origin you add receives a bearer credential for the remote project's identity, not a token scoped to the callback. Until the token expires, that parent can replay it against any service, deployment protection rule, or federated cloud role that accepts the identity. List only parents you trust to act as the remote project, and use a wildcard only when you control every host under it.
236
205
 
237
- Clients follow a remote child through the parent. [`session.agent(opened).stream()`](./client/streaming#follow-a-subagent) reads the `child.opened` event's `stream` path, a route on the parent deployment. The parent verifies that its session recorded the child for that tool call, resolves the remote agent's `auth` and `headers`, and relays the child's stream. A browser never calls the remote deployment or holds its credentials; it only needs access to the parent session.
206
+ When either side isn't on Vercel, make the parent's callback route reachable through your hosting policy. eve never forwards a deployment-wide credential to the remote.
238
207
 
239
- Cancelling the parent turn or the agent task with `eve__task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.settled` with `outcome: "cancelled"` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
208
+ Clients follow a remote child through the parent. [`session.agent(opened).stream()`](./client/streaming#follow-a-subagent) reads the `child.opened` event's `stream` path, a route on the parent deployment. The parent checks that the child belongs to that tool call, then relays the child's stream with the remote agent's `auth` and `headers`. A browser never calls the remote deployment or holds its credentials.
240
209
 
241
- When the workflow run that opened a remote child finishes, eve sends an authenticated request to end it. An agent task's run finishes when the parent session ends. Ending retires the parked remote session and recursively cleans up its descendants. Parent cleanup retains its earlier wire path so independently deployed parents and children can run different eve versions. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
210
+ Cancelling the parent turn, or the task with `eve__task_cancel`, cancels the remote child's current turn. The child reports `turn.settled` with `outcome: "cancelled"` on its own stream. Each cancel resolves `headers` and `auth` again and uses the standard eve cancel route on `url`, even when `path` is customized. If the remote is older or unreachable, eve logs it, and the parent's cancel still succeeds.
242
211
 
243
- The parent names its remote agent protocol version when it creates the child, and the remote
244
- answers with the version it serves. This release serves protocols 2 and 3. A protocol-3 parent
245
- accepts a protocol-2 remote's results and failures, but cannot follow its live stream. It relays that
246
- remote's approvals, questions, and sign-ins to the person it serves, as described below.
247
- A protocol-3 remote returns results and failures to callers on protocol 2, but cannot relay
248
- approvals, questions, or sign-ins to them: a turn that needs a person fails with upgrade guidance
249
- instead of waiting on an unreachable prompt. Unsupported versions, including protocol 1 from
250
- eve 0.66 through 0.68, fail at start with an error naming both versions.
212
+ When the workflow run that opened a remote child finishes, eve sends an authenticated request that ends the remote session and its descendants. An agent task's run finishes when the parent session ends. The request uses freshly resolved `headers` and `auth`. eve logs failures, so an unreachable remote can't block the parent from finishing.
251
213
 
252
- A receiver on an earlier supported protocol can reject a new caller's create request
253
- before admission. After an explicit `409 REMOTE_AGENT_PROTOCOL_MISMATCH` rejection,
254
- eve makes one request with that receiver's supported version and fresh credentials.
255
- It does not negotiate after an accepted response, an unreadable receipt, a rejection
256
- that names a session, or an unsupported version.
214
+ The parent names its remote agent protocol version when it creates the child, and the remote answers with the version it serves. eve serves protocols 2 and 3:
257
215
 
258
- A parent that negotiated protocol 2 relays that child's approvals, questions, and
259
- sign-ins like a protocol-3 child's. The person answers them in the parent's session,
260
- and their answers return in the form the child accepts. The child still decides who
261
- may answer: an answer it turns away, such as one from a responder its approval policy
262
- refuses, leaves the approval open. The child reports how its approvals and sign-ins
263
- settle. It doesn't report how a question or budget prompt settles, so the parent
264
- settles those once the child accepts the answer. Cancelling the parent's call withdraws
265
- what it mirrored.
216
+ | Parent | Remote | Behavior |
217
+ | ------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
218
+ | 3 | 2 | Results and failures return, and approvals, questions, and sign-ins relay to the person. The parent can't follow the child's live stream. |
219
+ | 2 | 3 | Results and failures return. Approvals, questions, and sign-ins can't relay, so a turn that needs a person fails with upgrade guidance instead of waiting. |
220
+
221
+ Unsupported versions fail at start with an error naming both versions.
222
+
223
+ A receiver on an older protocol can reject the create request with `409 REMOTE_AGENT_PROTOCOL_MISMATCH` before it accepts the child. eve then sends one more request with that receiver's version and fresh credentials. eve doesn't try again after an accepted response, an unreadable receipt, a rejection that names a session, or an unsupported version.
224
+
225
+ With a protocol-2 child, the person answers relayed requests in the parent's session. The child still decides who may answer, so an answer its approval policy refuses leaves the approval open. The child reports when approvals and sign-ins end, but not questions or budget prompts. The parent closes those when the child accepts the answer. Cancelling the parent's call withdraws the relayed requests.
266
226
 
267
227
  ### Upgrading callers and remote agents
268
228
 
269
- Upgrade callers before the remote agents they call, or both together. A caller on this release
270
- relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a remote agent on this
271
- release can't relay them to a protocol-2 caller.
229
+ Upgrade callers before the remote agents they call, or both together, because a protocol-3 remote can't relay approvals, questions, or sign-ins to a protocol-2 caller.
272
230
 
273
- A remote child's callback goes to the parent's current production deployment, not to the
274
- deployment that started the call; the parent's own sessions stay on the deployment that started
275
- them. Every callback URL a parent gives a child names the protocol they agreed
276
- (`eveRemoteProtocol`), and the parent reads a child's callbacks by that protocol. A URL that names
277
- none comes from a parent run started before v27. When an earlier child's approval, question, or
278
- sign-in for such a run reaches an upgraded deployment, the deployment passes it to that run as is,
279
- so the run receives it as it did before the upgrade.
231
+ A remote child's callback goes to the parent's current production deployment, not the deployment that started the call. The parent's own sessions stay on the deployment that started them.
280
232
 
281
233
  ### Retries and acknowledgements
282
234
 
283
- Each follow-up message and each set of answers a parent sends a protocol-3 child carries an
284
- `idempotencyKey` named by the parent's own durable step. When the child accepts a request but the
285
- parent doesn't hear back, the parent's retry is the same delivery: the child admits it once and
286
- returns the original receipt. Protocol-2 children don't accept the field, so the parent sends
287
- it only to protocol-3 children.
288
-
289
- A failed start fails the call immediately. After a remote starts, a terminal failure callback
290
- fails the call with the remote's error. Terminal callback delivery runs as a durable step on the
291
- underlying workflow engine (see [Execution model & durability](../concepts/execution-model-and-durability)).
292
- A failed callback POST is rethrown so the engine retries it. A parent's callback route answers
293
- `404` with `code: "CALLBACK_NOT_PENDING"` when nothing waits on the callback: the parent already
294
- took the result, for example from a delivery whose acknowledgement was lost, or stopped waiting for
295
- it. The child retries that answer for a few seconds, in case the parent hasn't yet registered the
296
- reply it sent the token for, then logs it and keeps its session, rather than failing it.
297
-
298
- If a remote accepts the create request but its response has an incompatible
299
- protocol or an unreadable body, the work may have completed. eve stops workflow
300
- retries and reports that uncertainty. A protocol mismatch includes the accepted
301
- remote session ID so you can inspect the outcome before sending another request.
302
- Upgrading the remote does not undo work that it already performed. An unsupported version, or a rejection of the single negotiated request,
303
- remains a compatibility error.
235
+ Each follow-up message and set of answers sent to a protocol-3 child carries an `idempotencyKey`. If the child accepts a request but the parent never gets the reply, the child accepts the retry once and returns the original receipt. Protocol-2 children don't receive the key.
236
+
237
+ A failed start fails the call immediately. After a remote starts, a final failure callback fails the call with the remote's error. eve retries a failed final callback request (see [Execution model & durability](../concepts/execution-model-and-durability)).
238
+
239
+ A parent's callback route answers `404` with `code: "CALLBACK_NOT_PENDING"` when nothing waits on the callback. Either the parent already took the result, for example after a lost acknowledgement, or it stopped waiting. The child retries for a few seconds in case the parent hasn't registered the reply yet, then logs it and keeps its session.
240
+
241
+ If a remote accepts the create request but its response has an incompatible protocol or an unreadable body, the work may have finished. eve stops workflow retries and reports that the outcome is unknown. A protocol mismatch includes the accepted remote session ID, so you can check the outcome before you send another request. Upgrading the remote doesn't undo work it already did. An unsupported version, or a rejection of the one retried request, is a compatibility error.
304
242
 
305
243
  ## What to read next
306
244
 
@@ -3,9 +3,9 @@ title: "Self-Modification"
3
3
  description: "Ask your agent to update its own authored files during local development, or let a deployed agent propose changes as draft pull requests."
4
4
  ---
5
5
 
6
- When `eve dev` starts a local server, it mounts the bundled self-modification extension by default. Ask your agent to change its instructions, tools, skills, or other files under `agent/`; eve delegates the source work to the `self-modification__agent` subagent. Connecting to an existing server with `eve remote connect --url <url>` does not add the bundled extension to that server.
6
+ Self-modification lets you ask your agent to change its own instructions, tools, skills, or other files under `agent/`. When `eve dev` starts a local server, it mounts the bundled `eve/extensions/self-modification/local` extension, which delegates the source work to the `self-modification__agent` subagent. `eve remote connect --url <url>` doesn't add it to the server it connects to.
7
7
 
8
- The bundled extension is `eve/extensions/self-modification/local`. It is for local development and is not included in production builds. To let a deployed agent propose source changes, mount the separate [`eve/extensions/self-modification/remote`](#propose-changes-from-a-deployed-agent) extension.
8
+ The local extension is not included in production builds. To let a deployed agent propose source changes, mount the separate [`eve/extensions/self-modification/remote`](#propose-changes-from-a-deployed-agent) extension.
9
9
 
10
10
  ```bash
11
11
  eve dev
@@ -17,11 +17,11 @@ For example, ask the agent to add a reusable action:
17
17
  Add a tool that converts temperatures between Celsius and Fahrenheit.
18
18
  ```
19
19
 
20
- The self-modification subagent changes the authored files in your project. Review the diff and test the new behavior as you would for any other source change. `eve dev` reloads changes while you work.
20
+ The subagent edits the authored files in your project, and `eve dev` reloads them. Review the diff and test the change as you would any other source change.
21
21
 
22
- The subagent is offered only to sessions authenticated by [`localDev()`](./auth-and-route-protection#localdev) or by the Vercel development token the dev TUI sends for a linked project. Sessions authenticated as Slack users or by your own authenticators, including HTTP Basic operator credentials, do not see it. The local mount has no `authorize` override; edit the authored files directly when using those authenticators.
22
+ The subagent is offered only to sessions authenticated by [`localDev()`](./auth-and-route-protection#localdev) or by the Vercel development token the dev TUI sends for a linked project. Sessions authenticated any other way, such as Slack users or HTTP Basic operator credentials, don't see it, and the local mount has no `authorize` override.
23
23
 
24
- A tunnel or reverse proxy running on the same machine can forward callers that `localDev()` accepts as the synthetic local developer. Those callers can use the editor. Before exposing `eve dev` through a tunnel, require authentication at the tunnel or proxy, or remove `localDev()` from the exposed channel's auth chain. Putting another authenticator before `localDev()` does not reject callers that it skips: they can still fall through to `localDev()`.
24
+ A tunnel or reverse proxy on the same machine can forward callers that `localDev()` accepts as the local developer. Those callers can use the subagent. Before exposing `eve dev` through a tunnel, require authentication at the tunnel or proxy, or remove `localDev()` from the exposed channel's auth chain. Another authenticator placed before `localDev()` doesn't help, because callers it skips still fall through to `localDev()`.
25
25
 
26
26
  ## Change the self-modification model
27
27
 
@@ -31,7 +31,7 @@ The subagent uses your agent's model by default. To give it a different model or
31
31
  Switch the self-modification subagent to openai/gpt-6-sol with low reasoning.
32
32
  ```
33
33
 
34
- The first time, this creates `agent/extensions/self-modification/extension.ts` with those settings. After that file exists, later changes edit it. You can also edit the file yourself: it accepts `model`, `reasoning`, and `local.enabled` options.
34
+ This creates or edits `agent/extensions/self-modification/extension.ts`. You can also edit the file yourself; it accepts `model`, `reasoning`, and `local.enabled`.
35
35
 
36
36
  ```ts
37
37
  // agent/extensions/self-modification/extension.ts
@@ -43,19 +43,13 @@ export default selfModification({
43
43
  });
44
44
  ```
45
45
 
46
- The bare `eve/self-modification` entry is removed. Mount `eve/extensions/self-modification/local` for development or `eve/extensions/self-modification/remote` for deployed source changes. The local mount does not accept a `deployed` option. If your mount sets `deployed`, eve rejects it and asks you to move that configuration to an `eve/extensions/self-modification/remote` mount.
47
-
48
- ## Migrate a retired scaffold
49
-
50
- The scaffold under `agent/subagents/self-modification/` is no longer supported. The disabled agent helper, including `eve/internal/self-modification/agent`, has been removed. Do not use the old `@eve/self-modification` compatibility package for new installations.
51
-
52
- Preserve any authored changes, then remove the old scaffold directory. Run `eve add eve/self-modification` to create the supported local extension mount. Setup rejects the old directory rather than deleting it. The bundled local extension and the separate remote extension remain supported.
46
+ The local mount rejects a `deployed` option with an error; configure deployed source changes on a separate `eve/extensions/self-modification/remote` mount.
53
47
 
54
48
  ## Propose changes from a deployed agent
55
49
 
56
- `eve/extensions/self-modification/remote` is a separate extension for deployed agents. It adds a subagent that checks out your repository in a sandbox, edits the authored source, and opens a draft pull request against a target branch. It never changes the running deployment. Changes take effect only after you review, merge, and redeploy.
50
+ `eve/extensions/self-modification/remote` adds a source-change subagent to a deployed agent. The subagent checks out your repository in a sandbox, edits the authored source, and opens a draft pull request against a target branch. It never changes the running deployment; changes take effect after you review, merge, and redeploy.
57
51
 
58
- Mount it under its own namespace so it does not replace the local extension:
52
+ Mount it under its own namespace so it doesn't replace the local extension:
59
53
 
60
54
  ```ts
61
55
  // agent/extensions/self-modification-remote/extension.ts
@@ -84,17 +78,23 @@ export default selfModification({
84
78
  | `credentials` | Required. An object with a `resolve({ capability, repository })` function that returns a GitHub token, or `{ pat: true }` to read `EVE_SELF_MODIFICATION_GITHUB_TOKEN` from the deployment environment. |
85
79
  | `model`, `reasoning` | Optional model and reasoning level for the deployed subagent. It defaults to the parent agent's model. |
86
80
 
87
- The deployed subagent is never offered during `eve dev`. It requires deploying on Vercel, where Vercel Sandbox provides the runtime credential transforms that keep the GitHub token out of the sandbox. Builds succeed on any host, but in a deployment outside Vercel the deployed subagent fails with an error that names this requirement when it opens its sandbox. Don't mount `eve/extensions/self-modification/remote` in self-hosted deployments. eve applies the GitHub token as a sandbox network credential only while it checks out or publishes, so commands in the sandbox cannot read it.
81
+ The deployed subagent is never offered during `eve dev`. It requires Vercel, because Vercel Sandbox keeps the GitHub token out of the sandbox. eve applies the token only while it checks out or publishes, so sandbox commands can't read it. Builds succeed on any host. Outside Vercel, the subagent fails with an error naming this requirement when it opens its sandbox, so don't mount it in self-hosted deployments.
88
82
 
89
83
  ## Run without self-modification
90
84
 
91
- Pass `--no-default-extensions` when you do not want `eve dev` to mount bundled development extensions:
85
+ Pass `--no-default-extensions` to stop `eve dev` from mounting its bundled development extensions:
92
86
 
93
87
  ```bash
94
88
  eve dev --no-default-extensions
95
89
  ```
96
90
 
97
- This disables the complete bundled default set for that server, including self-modification. It does not remove files from your project or disable extensions that you have explicitly mounted under `agent/extensions/`.
91
+ This disables every bundled default extension for that server, including self-modification. Extensions you mount under `agent/extensions/` still load.
92
+
93
+ ## Troubleshooting
94
+
95
+ | What you see | What to do |
96
+ | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
97
+ | `The legacy agent/subagents/self-modification layout is no longer supported.` from setup | Keep any authored changes, remove `agent/subagents/self-modification/`, then run `eve add eve/self-modification` to mount the extension at `agent/extensions/self-modification/extension.ts`. |
98
98
 
99
99
  ## What to read next
100
100