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,87 +3,90 @@ title: "Execution Model and Durability"
3
3
  description: "How an eve session runs. Durable conversations, turns that checkpoint at steps, and parked work that resumes later."
4
4
  ---
5
5
 
6
- An eve session is a durable conversation. It can run for days and survives process restarts and redeploys without any work on your part. You write the capabilities (tools, instructions, channels) and eve runs the loop.
6
+ An eve session is a conversation that can run for days and survives process restarts and redeploys. You write the tools, instructions, and channels, and eve runs the loop.
7
7
 
8
8
  ## Sessions, turns, and steps
9
9
 
10
10
  Work nests in three levels:
11
11
 
12
- - **session**: the whole durable conversation or task. It's long-lived and can span many requests over days or weeks without losing context.
12
+ - **session**: the whole conversation or task. It can span many requests over days or weeks without losing context.
13
13
  - **turn**: one user message and all the work it triggers (model calls, tool calls, reasoning) until the agent produces its response.
14
- - **step**: a durable checkpoint inside a turn. By default, it contains one model call and the inline tool calls that follow it.
14
+ - **step**: a saved checkpoint inside a turn. By default, it contains one model call and the inline tool calls that follow it.
15
15
 
16
- Every session runs as one durable workflow, built on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). The session workflow executes each turn and checkpoints progress at step boundaries. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session underneath them is durable.
16
+ Every session runs as one workflow on the open-source [Workflow SDK](https://workflow-sdk.dev/) (Vercel Workflow when you deploy on Vercel). The workflow runs each turn and saves progress at step boundaries. Your code runs inside a managed step, so tools, the sandbox, and subagents feel synchronous even though the session can pause and resume underneath them.
17
17
 
18
- The experimental
19
- [`workflow.modelCallsPerStep`](../agent-config#workflow-checkpoint-batching)
20
- agent setting can group several sequential model-and-tool cycles into one
21
- Workflow step. This reduces checkpoint overhead but makes the entire group one
22
- replay unit.
18
+ The experimental [`workflow.modelCallsPerStep`](../agent-config#workflow-checkpoint-batching) agent setting groups several sequential model-and-tool cycles into one Workflow step. This reduces checkpoint overhead but makes the whole group one replay unit.
23
19
 
24
- The Workflow SDK is not inherently tied to Vercel. In local development and in a self-deployed `eve start` process, eve uses the SDK's local world by default; that world persists workflow runs on disk under `.eve/.workflow-data` and dispatches through the same Nitro-hosted workflow routes. On Vercel, the same workflow code runs against Vercel Workflow instead, which adds deployment-aware routing and dashboard run metadata.
20
+ In local development and a self-deployed `eve start` process, eve uses the SDK's local world by default. It persists workflow runs under `.eve/.workflow-data`. On Vercel, the same workflow code runs on Vercel Workflow, which adds deployment-aware routing and dashboard run metadata.
25
21
 
26
- When a Vercel production deployment changes, a new delivery to an idle session hands the session's settled state to the exact deployment that accepted the request. This applies whether the delivery arrives through the session ID or through any channel continuation address the session has claimed. The session keeps its original ID and event stream, while the next model turn uses that deployment's current system-role instructions, model, and tools. Static user-role instructions stay pinned in the durable conversation history and are not seeded again. As with any turn, the triggering delivery restarts the session's [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window, whether or not the handoff succeeds; disabled timeouts stay disabled.
22
+ Nitro hosts eve's HTTP routes and workflow entrypoints, but not the workflow store or the sandbox runtime. Workflow state lives in the active world, and the sandbox comes from `agent/sandbox` or the default sandbox. To choose a world for a self-hosted deployment, see [Workflow worlds](../guides/deployment/workflow-worlds) and [agent.ts](../agent-config#workflow-world).
27
23
 
28
- Before taking ownership, the target deployment checks checkpoint compatibility and that no pending work remains. A session with an incompatible checkpoint stays on its current deployment; see the [migration guide](./upgrade-to-v27-events#before-you-upgrade) for this release's requirements. An older release cannot read a newer checkpoint: after a rollback, a session that already moved to the newer deployment stays there. State that the target deployment no longer defines, such as a removed `defineState` key, is dropped, and the runtime logs identify the unknown key. Authored session state remains opaque to this validation.
24
+ When a Vercel production deployment changes, the next delivery to an idle session moves the session to the deployment that accepted it. A delivery is anything sent to the session: a message, an answer, or a control. It can arrive by session ID or by any channel address the session claimed. The session keeps its ID and event stream. Its next model turn uses the new deployment's system-role instructions, model, and tools. Static user-role instructions stay in the session history and aren't added again. The delivery restarts the [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window whether or not the move succeeds; disabled timeouts stay disabled.
29
25
 
30
- Messages that arrive while a handoff is in progress are accepted right away and are not lost. The new owner processes them after the triggering delivery, in the order they arrived, whichever run accepted them.
26
+ A session whose checkpoint the target deployment can't read stays on its current deployment. An older release can't read a newer checkpoint. After a rollback, a session that already moved to the newer deployment stays there. The target drops state it doesn't define, such as a removed `defineState` key, and its runtime logs name the unknown key. eve doesn't otherwise validate authored session state.
31
27
 
32
- The previous owner forwards the messages it accepted as soon as the new owner has taken over the session. Until they arrive, the new owner holds back everything it receives itself, including replies to tool runs and subagents that its first turn started, and processes it afterwards. A cancel still stops the new owner's running turn as soon as it arrives. If either run ends before the handoff settles, the other stops waiting for it.
28
+ Messages that arrive during a handoff are accepted right away and not lost. The new deployment processes them after the delivery that triggered the move, in arrival order. Until the previous deployment forwards its messages, the new one holds back other input, including replies to tool runs and subagents. A cancel still stops the new deployment's running turn as soon as it arrives. If either run ends before the handoff finishes, the other stops waiting for it.
33
29
 
34
- If the target deployment rejects the session, the previous owner keeps it and processes the triggering delivery, followed by any messages that arrived during the attempt. When the target deployment cannot read the checkpoint, its Vercel runtime logs show a `session handoff refused` warning with the checkpoint version and the reason. Owners on this release or later also write a `session handoff failed` warning to their own runtime logs, with the target deployment and the reason.
30
+ If the target deployment rejects the session, the previous deployment keeps it. It processes the triggering delivery, then any messages that arrived during the attempt. Two runtime-log warnings explain a failed handoff:
35
31
 
36
- eve does not move live work between deployments. A session with a running turn, pending human input or authorization, queued messages, or active tasks and subagents stays on its current deployment. After that work settles, a later delivery can move the idle session; the earlier deployment signal is not remembered.
32
+ | Warning | Logged by | Includes |
33
+ | ------------------------- | -------------------------------------------------------- | --------------------------------- |
34
+ | `session handoff refused` | The target deployment, when it can't read the checkpoint | The checkpoint version and reason |
35
+ | `session handoff failed` | The previous deployment | The target deployment and reason |
36
+
37
+ eve doesn't move live work between deployments. A session stays on its current deployment while it has a running turn, pending human input or authorization, queued messages, or active tasks and subagents. After that work finishes, the next delivery can move the idle session.
37
38
 
38
39
  ### Compaction handoff
39
40
 
40
- Every workflow run records each step it executes, so a session that ran on one run for weeks would carry its whole history in that run. To bound this, eve moves a session to a fresh run on its current deployment after [compaction](./default-harness#compaction) rewrites the conversation history. This applies to automatic compaction during a turn and to a client or channel compaction request.
41
+ After [compaction](./default-harness#compaction) rewrites the history, eve moves the session to a fresh workflow run on its current deployment. This keeps the run history of a long session bounded. It applies to automatic compaction and to compaction a client or channel requested.
42
+
43
+ The move happens once the turn ends and nothing is waiting: no queued messages, running tasks or subagents, or pending human input. If work is pending, eve tries again after a later turn ends. The new run continues with the compacted history and saved state. A message that arrives during the move is accepted right away and runs once, on the new run.
41
44
 
42
- The move happens once the turn settles and nothing else is waiting: no queued messages, running tasks or subagents, or pending human input. The new run receives the compacted history and settled state, then waits for the next message. A message that is already waiting when the turn settles runs on the current run first, and the session moves at the next point where nothing is waiting. A message that arrives after the move starts is accepted right away and runs once, on the new run. If work is still pending, eve tries again after a later turn settles. The session keeps its ID, event stream, and continuation addresses, and its [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window still counts from the turn that compacted. If the new run cannot take ownership, the current run keeps the session, writes a `session handoff failed` warning to its runtime logs, and tries again later.
45
+ The session keeps its ID, event stream, and channel addresses. Its [`sessionTimeoutMs`](../agent-config#runtime-limits) idle window still counts from the turn that compacted. If the new run can't take over the session, the current run keeps it, logs a `session handoff failed` warning, and tries again later.
43
46
 
44
- Both kinds of handoff need a Workflow world that can move a session's addresses from one run to another without releasing them, and can keep a released address reserved for a while (the `hookForceClaim` and `hookRetention` capabilities). Vercel Workflow, the local world, and `@workflow/world-postgres` 5.0.4 and later provide both. On a world without them, sessions never move between runs: deployment and compaction handoffs are skipped, and a session's run history grows for as long as the session lives. The first skipped attempt writes a `session handoff unavailable` warning to the runtime logs.
47
+ Both kinds of handoff need a Workflow world that supports `hookForceClaim` and `hookRetention`. Vercel Workflow, the local world, and `@workflow/world-postgres` 5.0.4 and later provide both. On other worlds, eve skips both handoffs, so a session's run history grows for as long as the session lives. The first skipped attempt logs a `session handoff unavailable` warning.
45
48
 
46
49
  ### Stranded sessions
47
50
 
48
- A session is stranded when another eve version built the workflow run that owns it. A run can only be replayed by the eve version that started it, so the conversation is still stored, but nothing on the current deployment can process a new message. On worlds without per-deployment routing, eve checks the owner before delivering channel messages and input responses, rather than committing them to a session that cannot answer.
51
+ A session is stranded when a different eve version built the workflow run that holds it. Only the eve version that started a run can replay it. The conversation stays stored, but the current deployment can't process a new message. On worlds without per-deployment routing, eve checks the run's eve version first, so channel messages and input responses never reach a session that can't answer.
49
52
 
50
- eve treats every world other than Vercel Workflow as running one eve version at a time, so a stranded session can never run again:
53
+ eve treats every world other than Vercel Workflow as running one eve version at a time, so a stranded session there never runs again:
51
54
 
52
- | World | When a session is stranded |
53
- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
- | Vercel Workflow | eve does not check. Each run keeps executing on the deployment that started it, and handoff moves idle sessions to newer deployments. |
55
- | Local world with `eve start` | After any upgrade that changes the eve version. Sessions created before eve recorded its version on the run are treated the same way. |
56
- | Postgres and other worlds | Same as the local world. Serve one world from one eve version at a time: a deployment running another version cannot replay these sessions, and eve does not route runs between deployments. |
57
- | `eve dev` | After an eve version change. A session from a previous dev server invocation built by the same eve version is not stranded: it stays dormant until you restart `eve dev` with [`--resume`](../reference/cli#local-workflow-recovery). |
55
+ | World | When a session is stranded |
56
+ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
57
+ | Vercel Workflow | eve does not check. Each run keeps executing on the deployment that started it, and handoff moves idle sessions to newer deployments. |
58
+ | Local world with `eve start` | After any upgrade that changes the eve version. |
59
+ | Postgres and other worlds | Same as the local world. Serve one world from one eve version at a time, because eve doesn't route runs between deployments. |
60
+ | `eve dev` | After an eve version change. A session from an earlier `eve dev` run on the same version stays dormant until you restart with [`--resume`](../reference/cli#local-workflow-recovery). |
58
61
 
59
- eve ends a stranded session without running any of its code. When that happens depends on the kind of run:
62
+ eve ends a stranded session without running any of its code. When it ends depends on the kind of run:
60
63
 
61
- - **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, an explicit end retires it, or its session timeout elapses, whichever comes first.
62
- - **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it, for example when the local world or Postgres recovers active runs at startup. No later message could resume its interrupted work, so eve does not wait.
64
+ - **A root session**, one that a channel or client started, keeps its address and executes nothing. It ends when a new channel message replaces it, `end()` ends it, or its session timeout elapses.
65
+ - **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it. One example is the local world or Postgres recovering active runs at startup. No later message could resume its interrupted work, so eve doesn't wait.
63
66
 
64
- See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
67
+ See [How a stranded session ends](#how-a-stranded-session-ends) for details.
65
68
 
66
69
  For a root session, what happens next depends on how the message is addressed:
67
70
 
68
- - **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. The fresh session names the session it replaced, whose recorded conversation your instructions can read; see [What a replacement session receives](#what-a-replacement-session-receives). A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).
71
+ - **A channel address**, such as a Slack thread or any `from(address).send(...)`, ends the stranded session and starts one fresh session at the same address. Concurrent messages also get one fresh session. The message becomes its first turn. The fresh session names the session it replaced, and your instructions can read its recorded conversation; see [What a replacement session receives](#what-a-replacement-session-receives). A send that carries answers to pending requests throws `SessionStrandedError` and leaves the stranded session in place. A fresh session has no request for those answers. See [custom channels](../channels/custom#channel-operations-and-session-handles).
69
72
  - **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `end()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
70
- - **A session ID** is never reset implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).
71
- - **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`; the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.
72
- - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to end it.
73
- - **End** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. End the session instead.
74
- - **Session timeouts** end a stranded session the same way an explicit end does; see [How a stranded session ends](#how-a-stranded-session-ends).
73
+ - **A session ID** is never ended implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).
74
+ - **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`, and the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.
75
+ - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the recorded events without changing the session. Read a stranded conversation this way before you decide to end it.
76
+ - **End** works through a channel address or a session ID. **Clear** is refused because it would keep a session that can't run: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes.
77
+ - **Session timeouts** end a stranded session the same way `end()` does; see [How a stranded session ends](#how-a-stranded-session-ends).
75
78
 
76
- An explicit `end()` retires the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, ending fails without retiring the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the end delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. An end that fails partway through can be retried.
79
+ `end()` ends the stranded session without running any of its code and releases its channel addresses. If another run took over the session in the meantime, ending fails and leaves that run alone. The stranded session's `session.ended` hooks don't run; a replacement session runs `session.started` as usual. eve tries to record the end and a `session.ended` event with `outcome: "failed"` and error code `session_stranded`, then close the old stream. This is best effort: unavailable storage doesn't prevent retirement, so the final event may be missing. You can retry an end that fails partway.
77
80
 
78
- Each retirement logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`. The internal command and log value remain `reset` for compatibility; the public control is `end()`.
81
+ Each retirement logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`. The `trigger` for an explicit `end()` is `reset`.
79
82
 
80
- Ending a session cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit end leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session ends. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
83
+ Ending a session can't be undone. A fresh session started by a message can read at most the stranded conversation's text. After an explicit end, the next session has no link to the stranded one. Rolling back to the eve version that built a session helps only before the session ends. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose.
81
84
 
82
85
  #### What a replacement session receives
83
86
 
84
87
  A replacement session is a new session with its own ID, stream, auth, channel binding, and state. It starts with no history from the stranded session. `ctx.session.predecessor` and the `session.started` event's `data.predecessor` name the session it replaced: `{ sessionId }`.
85
88
 
86
- To let the model continue the conversation, read the stranded session's recorded stream with `sessions.attach()` from `eve/server`, read it with `transcriptOf()` from `eve/client`, and return the result from a [dynamic user-role instruction](../instructions#dynamic-instructions) with a memo keyed by the predecessor's ID:
89
+ To let the model continue the conversation, read the stranded session's stream with `sessions.attach()` from `eve/server`. Turn it into a transcript with `transcriptOf()` from `eve/client`. Return the result from a [dynamic user-role instruction](../instructions#dynamic-instructions), memoized by the predecessor's ID:
87
90
 
88
91
  ```ts title="agent/instructions/replaced-conversation.ts"
89
92
  import { transcriptOf } from "eve/client";
@@ -119,75 +122,40 @@ export default defineDynamic(async (ctx) => {
119
122
  });
120
123
  ```
121
124
 
122
- The memo runs before the replacement's first model call, and the instruction enters the replacement's durable history once, ahead of the new message. In a session that replaced no other, `ctx.session.predecessor` is undefined and the instruction contributes nothing.
125
+ The memo runs before the replacement's first model call, and the instruction enters the replacement's history once, ahead of the new message. In a session that replaced no other, `ctx.session.predecessor` is undefined and the instruction contributes nothing.
123
126
 
124
- `transcriptOf()` keeps the history each consumed delivery imported, the text of each consumed delivery, and each completed reply part, oldest first, as `{ role, text }` messages. Reasoning, narration, tool calls and results, attachments, interactions, and interrupted output are left out. Only the session's current conversation is kept: a clear in the stranded session starts the transcript over, so text the user cleared is never returned. `sessions.attach()` also converts older session history to v27 events. That conversion reads from the beginning to reconstruct the conversation, even when `startIndex` requests a later position. `maxMessages` keeps only the newest messages in the resulting transcript.
127
+ `transcriptOf()` returns `{ role, text }` messages, oldest first: the history each received message imported, the text of each received message, and each completed reply part. It leaves out reasoning, narration, tool calls and results, attachments, approvals and questions, and interrupted output. It keeps only the session's current conversation: a clear in the stranded session starts the transcript over, so text the user cleared is never returned. `maxMessages` keeps only the newest messages.
128
+
129
+ For a session recorded before stream version 27, `sessions.attach()` reads from the beginning, even when `startIndex` requests a later position.
125
130
 
126
131
  The read and the prompt are yours to bound:
127
132
 
128
- - `startIndex: -2000` requests the newest 2,000 stored lines, not 2,000 events. Older history conversion still reads from the beginning; the `signal` limits read time in either case. The example catches a read that throws or times out and returns `null`, so the instruction contributes nothing and the turn continues. A memo that throws fails the turn instead, and eve tries it again at the next model call.
129
- - Keep the instruction's role `"user"` and label the text as historical data. Text the earlier user wrote should not reach the model as system instructions.
133
+ - `startIndex: -2000` requests the newest 2,000 stored lines, not 2,000 events. The `signal` limits read time, including for older-history conversion. The example returns `null` when the read throws or times out, so the instruction contributes nothing and the turn continues. A memo that throws fails the turn instead, and eve tries it again at the next model call.
134
+ - Keep the instruction's role `"user"` and label the text as historical data, so text the earlier user wrote never reaches the model as system instructions.
130
135
  - `sessions` reads any session ID, including a session that set `experimental.workflow.retention: 0`, until its data is deleted. Skip such sessions if your agent sets zero retention. Pass only the ID eve provides in `ctx.session.predecessor`, never one taken from a request or a model.
131
136
 
132
137
  To use other context instead, such as a summary your application stored for the earlier session, look it up by `ctx.session.predecessor.sessionId`.
133
138
 
134
- The transcript is context only: tools, approvals, files, sandbox contents, authored state, and interrupted work do not carry over. It includes only messages the stranded session recorded itself. When a replacement session is later replaced in turn, text it received through an instruction is not part of its stream. Each session's `session.started` event records its own `data.predecessor`, so you can follow `predecessor.sessionId` back through earlier sessions if you need older text.
139
+ The transcript is context only: tools, approvals, files, sandbox contents, authored state, and interrupted work don't carry over. It includes only messages the stranded session recorded itself, so text a replacement received through an instruction isn't part of its stream. Each session's `session.started` event records its own `data.predecessor`, so you can follow `predecessor.sessionId` back through earlier sessions for older text.
135
140
 
136
141
  #### How a stranded session ends
137
142
 
138
- A stranded root session ends on its next channel message, an explicit end, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
139
-
140
- The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or an explicit end, just as a healthy one would stay open.
141
-
142
- Ending a root session does not immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. A run that never receives a delivery, such as one parked in a dormant `eve dev` generation, can stay active; cancel it in your Workflow world if you need to. Cancellation does not run authored cleanup or lifecycle hooks, undo side effects, or stop independent external jobs, and results and approvals do not carry over to a replacement session.
143
-
144
- Runs that recorded no eve version, including every run from a release before eve recorded versions, are treated as stranded.
145
-
146
- ### Upgrading sessions from the former execution model
143
+ A stranded root session ends on its next channel message, an explicit end, or its [session timeout](../agent-config#runtime-limits), whichever comes first, and executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve skips the root session without replaying it. It logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses, and a later restart skips it the same way.
147
144
 
148
- You can upgrade directly from a release that used a session driver and separate
149
- turn workflows. When an existing driver next dispatches a turn to this deployment,
150
- eve imports its committed conversation into the current runtime. The session
151
- keeps its ID, history, authored state, usage, limits, and original event stream.
152
- Subsequent turns use the new deployment's instructions, model, and tools.
145
+ The timeout is the session's own timer, which keeps running after the upgrade. A stranded session ends at most `sessionTimeoutMs` after its last turn ended (30 days by default), and possibly sooner. The timeout retires the stranded session without starting a fresh one. The next message to the address starts an ordinary session. With `sessionTimeoutMs: false`, a stranded session stays until a message or `end()`.
153
146
 
154
- This is a one-time interruption of pending work. Old tool calls, subagents,
155
- input requests, and authorization attempts are abandoned; start that work again
156
- if it is still needed. Messages already buffered exclusively inside the old
157
- driver are not imported. The triggering message is preserved without repeating
158
- committed tool effects.
147
+ Ending a root session doesn't immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. A run that never receives a delivery, such as one in a dormant `eve dev` generation, can stay active. Cancel it in your Workflow world if needed. Cancellation doesn't run authored cleanup or hooks, undo side effects, or stop independent external jobs. Results and approvals don't carry over to a replacement session.
159
148
 
160
- Import supports drivers started on eve 0.45 or later. A session from an older
161
- release reports itself inactive on its next message, and its channel starts a
162
- fresh session.
149
+ Runs that recorded no eve version are treated as stranded.
163
150
 
164
- Keep the original deployment available until these sessions end. Their old
165
- drivers remain waiting to keep the original streams open; the current runtime
166
- owns subsequent turns. Import restarts the session's idle window;
167
- disabled timeouts stay disabled. A driver
168
- that has not reached its next turn dispatch has not migrated yet.
151
+ #### Sessions from session-driver releases
169
152
 
170
- Transparent rollback to the former execution model is unsupported. Retire and
171
- restart affected sessions before rolling back.
153
+ Some eve releases ran each session as a session driver with separate turn workflows. When such a driver sends its next turn to the current deployment, eve imports the session. The session keeps its ID, history, authored state, usage, limits, and event stream, and later turns use the new deployment's instructions, model, and tools.
172
154
 
173
- Nitro hosts the HTTP routes and workflow entrypoints. It does not supply the workflow state store or the sandbox runtime. Those are separate adapters: Workflow uses the active world implementation, and Sandbox uses the backend from `agent/sandbox` or the default sandbox environment.
174
-
175
- For advanced self-hosted deployments, the root `agent.ts` can select the installed Workflow world package to use with `experimental.workflow.world`:
176
-
177
- ```ts title="agent/agent.ts"
178
- import { defineAgent } from "eve";
179
-
180
- export default defineAgent({
181
- model: "anthropic/claude-opus-5.5",
182
- experimental: {
183
- workflow: {
184
- world: "@workflow/world-postgres",
185
- },
186
- },
187
- });
188
- ```
189
-
190
- The world package backs workflow state, queues, hooks, and streams. Keep secrets and deployment-specific options in runtime environment variables read by that package, not in `agent.ts`. Custom worlds must implement the runtime protocol expected by eve's vendored `@workflow/*` packages (currently the `5.0.0-beta` line); the Workflow SDK rejects incompatible protocol versions during initialization. See [Self-host eve](../guides/deployment/self-hosting#persist-workflow-state), [agent.ts](../agent-config#workflow-world), and [Workflow Worlds](https://workflow-sdk.dev/worlds).
155
+ - Pending work from the old driver doesn't carry over: tool calls, subagents, input requests, and sign-ins. Start it again if it's still needed. Messages buffered only in the old driver aren't imported.
156
+ - Keep the original deployment available until these sessions end, because their drivers keep the original streams open.
157
+ - A driver started before eve 0.45 can't be imported. Its next message fails with `This session predates eve 0.45 and cannot be continued. Start a new session.`, and its channel starts a fresh session.
158
+ - Rolling back to a session-driver release isn't supported. Retire and restart affected sessions before you roll back.
191
159
 
192
160
  ## Agent loop and sandbox
193
161
 
@@ -195,13 +163,13 @@ An eve agent spans two execution environments with different responsibilities:
195
163
 
196
164
  <AgentRuntimeDiagram />
197
165
 
198
- The agent loop runs as a durable workflow in the app runtime. Model calls, tool executors, hooks, instrumentation, and connection clients also run there with full Node.js access.
166
+ The agent loop runs as a workflow in the app runtime. Model calls, tool executors, hooks, instrumentation, and connection clients also run there with full Node.js access.
199
167
 
200
168
  App-side code reaches the sandbox through `ctx.getSandbox()`. The default `bash`, `read_file`, and `write_file` tools use it, as do opt-in framework tools such as `glob` and `grep`. Authored tools can use it when they need isolated filesystem or process access.
201
169
 
202
- The [sandbox](../sandbox) owns the per-session filesystem and processes. Authored skills are materialized under `$HOME/.agents/skills`, and `agent/sandbox/workspace/**` seeds `/workspace`. The loop and sandbox have decoupled lifetimes: the durable workflow can park or restart independently, while the app runtime opens or reuses sandbox compute only when code needs it.
170
+ The [sandbox](../sandbox) owns the per-session filesystem and processes. Authored skills are materialized under `$HOME/.agents/skills`, and `agent/sandbox/workspace/**` seeds `/workspace`. The loop and sandbox have separate lifetimes. The workflow can park or restart without holding sandbox compute, and the app runtime opens sandbox compute only when code needs it.
203
171
 
204
- This split gives the agent a real filesystem and process environment without putting credentials or trusted integration code in model-controlled compute. The workflow can park without holding sandbox compute, while sandbox capacity and backends can change independently of durable orchestration. Because access flows through app-side tools, sandbox work gets the same approval and instrumentation path as any other tool call.
172
+ The split gives the agent a real filesystem and processes without putting credentials or trusted integration code in model-controlled compute. Because access flows through app-side tools, sandbox work gets the same approval and instrumentation path as any other tool call.
205
173
 
206
174
  Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay in the app runtime. When a sandbox process needs authenticated network access, [credential brokering](./security-model#credential-brokering) handles the request without exposing the credential to the process.
207
175
 
@@ -209,104 +177,72 @@ Provider keys, tool secrets, and MCP, OpenAPI, and connection credentials stay i
209
177
 
210
178
  Crash the process, hit a timeout, or redeploy mid-turn, and the run picks up from the last completed step rather than replaying the whole turn. Completed steps never re-run; eve replays the recorded result. An interrupted step runs again from the checkpoint before it, so model calls in that step can run again.
211
179
 
212
- A step publishes session events as it works, before it saves its checkpoint. When an interrupted step already wrote some, its retry continues the stream after them instead of writing them again:
180
+ A step publishes session events before it saves its checkpoint. A retried step continues the stream after the events the interrupted attempt wrote:
213
181
 
214
- - A tool call whose start is present in the recovered stream does not run again. The model reads each such call's name, input, and what eve knows of it, such as that it completed but its result was lost, and decides what to call again.
215
- - What the interrupted attempt left open settles `abandoned`: its model run, unfinished calls, and the approvals or questions it asked. The model asks again if it still needs them.
216
- - A turn the interrupted attempt already settled stays settled, with its input and reply in history.
217
- - A clear the interrupted attempt finished still empties history. An unfinished clear or compaction change settles `interrupted`; its control delivery settles `failed` instead of running again. A completed compaction keeps its recorded outcome, but its lost private summary is not reconstructed. The checkpoint history remains available for a later compaction.
218
- - Hooks and channel handlers do not run again for the events the interrupted attempt wrote. New recovery facts use normal hooks and instrumentation.
182
+ - A tool call whose start is in the recovered stream doesn't run again. The model reads each such call's name, input, and known status, such as completed with a lost result. The model decides what to call again.
183
+ - What the interrupted attempt left open ends `abandoned`: its model run, unfinished calls, and the approvals or questions it asked. The model asks again if it still needs them.
184
+ - A turn the interrupted attempt already ended stays ended, with its input and reply in history.
185
+ - A clear the interrupted attempt finished still empties history. An unfinished clear or compaction ends `interrupted`, and the clear or compact request ends `failed` instead of running again. A completed compaction keeps its recorded outcome, but its lost private summary is not reconstructed. The checkpoint history remains available for a later compaction.
186
+ - Hooks and channel handlers do not run again for the events the interrupted attempt wrote. New events from recovery use normal hooks and instrumentation.
219
187
 
220
188
  A turn fails with `STEP_INTERRUPTED` after more than three interrupted steps, or with `STEP_FAILED` when one of its steps fails on every retry. The session stays open for the next message.
221
189
 
222
- Terminal cleanup preserves recorded outcomes and closes any remaining work. Its final publication does not run authored hooks; channel notification depends on whether the channel context can be restored. Do not rely on a terminal hook for guaranteed external cleanup: a hook interrupted after publication may have completed its side effect, partly completed it, or never run.
190
+ Terminal cleanup keeps recorded outcomes and closes any remaining work. It doesn't run authored hooks, and it notifies the channel only when eve can restore the channel context. Don't rely on a terminal hook for guaranteed external cleanup. A hook interrupted after publication may have completed, partly completed, or never run its side effect.
191
+
192
+ These are step retries, not the model provider's retry loop or tool errors handled within a step. Recovery doesn't make external effects exactly-once:
223
193
 
224
- These are durable-step retries, not the model provider's retry loop or ordinary tool errors handled within a step. Recovery does not make external effects exactly-once. A call's start record may not be durable when execution begins, so a crash can lose that record. A call whose start had not reached the stream when the step was interrupted can run again, a call reported as interrupted may have taken effect, and the model can call a tool again. A world that redelivers a step while its earlier attempt is still running can also run both. Give tools with irreversible effects a stable operation ID, or have them check whether the action already happened.
194
+ - A call's start record may not be saved yet when the call begins, so a call whose start hadn't reached the stream can run again.
195
+ - A call reported as interrupted may have taken effect, and the model can call the tool again.
196
+ - A world that redelivers a step while its earlier attempt is still running can run both.
225
197
 
226
- With `experimental.workflow.modelCallsPerStep` greater than `1`, an
227
- interrupted step can repeat earlier model calls from the same batch. Approval, input, and blocking coordination
228
- boundaries still force a checkpoint before eve waits.
198
+ Give tools with irreversible effects a stable operation ID, or have them check whether the action already happened.
229
199
 
230
- Steering can interrupt pending model generation before assistant output begins.
231
- An executing tool finishes safely, then the batch yields before another model
232
- call so the owner can apply accepted steering within the same turn.
200
+ With `experimental.workflow.modelCallsPerStep` greater than `1`, an interrupted step can repeat earlier model calls from the same batch. eve still checkpoints before it waits for an approval or input. Steering still applies after an executing tool finishes, within the same turn.
233
201
 
234
- Durability itself needs no configuration. eve owns the workflow lifecycle, and
235
- sessions are durable by default; checkpoint batching is an explicit
236
- experimental opt-in.
202
+ Checkpoints and recovery need no configuration; checkpoint batching is an explicit experimental opt-in.
237
203
 
238
- For ordinary tools, eve manages the workflow around your executor. Use [`defineWorkflowTool`](../tools/workflows) when your own tool body needs durable waits, such as a timer, webhook, or human answer. Two surfaces give your own code session data: tools read the current session's metadata (id, turn, auth, parent lineage) via `ctx.session`, and [`defineState`](./state) reads or writes session-scoped durable state. See [State](./state) for the read/write model.
204
+ For ordinary tools, eve manages the workflow around your executor. Use [`defineWorkflowTool`](../tools/workflows) when your own tool body needs waits that survive restarts, such as a timer, webhook, or human answer. Tools read the current session's metadata (id, turn, auth, parent lineage) through `ctx.session`. [`defineState`](./state) reads and writes per-session state.
239
205
 
240
206
  ## Parked work
241
207
 
242
- Some work has to wait, including a human approving a [tool](../tools) or an interactive OAuth sign-in for a [connection](../connections). At those points the turn parks durably. The workflow suspends and holds no compute until the input it's waiting on arrives, even if that's much later. When it does, the conversation picks up exactly where it left off.
208
+ Some work has to wait, such as a human approving a [tool](../tools) or an interactive OAuth sign-in for a [connection](../connections). At those points the turn parks and holds no compute until the input arrives, even much later. The conversation then picks up where it left off.
243
209
 
244
- A workflow tool can suspend too, with its original tool call still pending and the turn parked
245
- until the workflow settles. `defineTool` always executes inside its initiating step. A workflow
246
- tool that defines `task(input, ctx)` or `serve(receive, ctx)` doesn't park the turn: its call returns a receipt, the run keeps working,
247
- and the turn parks only when the model calls `eve__task_wait` or tries to end the turn while the task
248
- works. See [tasks](../tools/workflows#run-calls-as-tasks-task).
210
+ A workflow tool can suspend too, with its tool call pending and the turn parked until the workflow finishes. `defineTool` always executes inside its initiating step. A workflow tool that defines `task(input, ctx)` or `serve(receive, ctx)` doesn't park the turn. Its call returns a receipt and the run keeps working. The turn parks only when the model calls `eve__task_wait` or tries to end the turn while the task works. See [tasks](../tools/workflows#run-calls-as-tasks-task).
249
211
 
250
- An awaited workflow operation provides the durable wait. A generator's `yield` reports progress.
251
- See [durable waits](../tools#durable-waits) and
252
- [workflow suspension](../tools/workflows#how-suspension-works) for the execution and result rules.
212
+ An awaited workflow operation provides the wait, and a generator's `yield` reports progress. See [durable waits](../tools#durable-waits) and [workflow suspension](../tools/workflows#how-suspension-works) for the execution and result rules.
253
213
 
254
214
  ## Message delivery and steering
255
215
 
256
- eve does not maintain a durable FIFO queue of user messages for a session. An
257
- ID-addressed HTTP delivery and a channel-address delivery both target the
258
- session's current command inbox; neither is a general message queue.
216
+ A delivery is a message, answer, or control sent to a session by its session ID or a channel address.
259
217
 
260
- Only one active session can own a channel continuation token. A channel-created
261
- session claims both its stable session-ID inbox and its initial channel address
262
- before processing the first turn, and fails creation if another run already
263
- owns the channel address. Aliasing adds another continuation address to the
264
- same session; every previously claimed address remains active until the session
265
- ends. An ID-only HTTP session has the stable inbox and no channel
266
- continuation address. When cold starts race for the same address, the losing
267
- candidate forwards its accepted message to the owner and exits.
218
+ Only one active session can hold a channel address. A channel-created session claims its first address before the first turn. Creation fails if another session already holds the address. Aliasing adds another address to the same session, and every claimed address stays active until the session ends. An ID-only HTTP session has no channel address. When first messages race for the same address, one session wins and receives every message.
268
219
 
269
- Channel delivery attempts to resume the address before creating a session.
270
- After Workflow accepts the delivery, eve resolves the stable session ID for
271
- the returned handle. That identity lookup does not block workflow resumption.
272
- ID-addressed delivery already knows the session ID and needs no hook metadata
273
- lookup. An ambiguous delivery failure does not trigger session creation.
220
+ A channel send continues the address's session before creating one. A send that fails ambiguously never creates a session.
274
221
 
275
- Pass a [delivery idempotency key](../channels/custom#retried-deliveries) to prevent
276
- retried input from interrupting generation or starting another turn. Each session
277
- remembers its last 1,024 distinct keys across replay and owner handoffs. Keyed
278
- cold-start sends wait for the winning session's ID; sends without a key can
279
- return a candidate ID before ownership is settled.
222
+ Pass a [delivery idempotency key](../channels/custom#retried-deliveries) so retried input can't interrupt generation or start another turn. Each session remembers its last 1,024 distinct keys across restarts and handoffs. A keyed send that starts a session returns the winning session's ID. A send without a key can return the ID of a session that loses the race.
280
223
 
281
- A handoff never leaves the session's addresses without an owner. The previous
282
- owner keeps every address until the new run takes all of them over, so a
283
- delivery during a handoff is accepted immediately and is never reported as an
284
- inactive session. An owner still running an earlier eve release gives up its
285
- addresses briefly during a handoff and leaves a short-lived marker for each
286
- one; a delivery that lands in that interval retries until the successor
287
- claims the address. Either way, a channel never starts a replacement session
288
- for an address that is changing owners.
224
+ A handoff never leaves the session's addresses unclaimed. A delivery during a handoff is accepted immediately, never reported as an inactive session. A deployment running an earlier eve release releases its addresses briefly instead. A delivery in that interval retries until the new deployment claims the address. Either way, a channel never starts a replacement session for an address that is moving between deployments.
289
225
 
290
- When a session is waiting, a delivery through its ID or any claimed channel address wakes it and starts the next turn. Message sends default to `turnPolicy: "steer"`. Before assistant output begins, the session owner signals pending model generation to stop, then applies the correction within the same turn and with the same turn ID. This includes model requests that perform provider-managed search before answering; interrupted search work may run again. Reasoning and search progress do not count as assistant output.
226
+ A message by session ID or by any claimed channel address wakes a waiting session and starts the next turn. Message sends default to `turnPolicy: "steer"`. Before assistant output begins, eve stops pending model generation and applies the new message within the same turn and turn ID. This includes model requests that run provider-managed search, and interrupted search work may run again. Reasoning and search progress don't count as assistant output.
291
227
 
292
- An executing eve tool finishes and commits its result before steering reaches the next model request. Steering does not cancel the turn. After assistant output starts, steering applies at the next committed workflow boundary and preserves streamed text. A message that reaches the boundary after the turn has settled starts another turn.
228
+ An executing eve tool finishes and keeps its result before steering reaches the next model request. When the model also called a provider-executed tool beside it whose result hasn't arrived, such as Anthropic `web_search`, the message waits one more model request, because the provider returns that result at the start of the next response. Steering doesn't cancel the turn. After assistant output starts, steering applies at the next step boundary and keeps streamed text. A message that reaches the boundary after the turn ends starts another turn.
293
229
 
294
- Once eve publishes an input request or begins publishing turn completion or failure, eve finishes committing that boundary before applying new messages.
230
+ Once eve starts recording a request for input or the turn's completion or failure, it finishes recording it before applying new messages.
295
231
 
296
- `turnPolicy: "queue"` preserves the message until the active turn settles. If several deliveries are ready when the owner checks, eve may fold adjacent messages into the next turn while preserving their arrival order. Pure `answers` deliveries do not steer; they remain available to the pending request they address.
232
+ `turnPolicy: "queue"` holds the message until the active turn ends. eve may fold adjacent ready messages into the next turn, in arrival order. A send with only `answers` doesn't steer; the answers stay available to the requests they name.
297
233
 
298
- Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy is part of the same durable delivery command as the message, so concurrent senders cannot separate replacement ownership from cancellation intent. Separate sessions still run independently.
234
+ Every built-in and custom channel accepts a default `turnPolicy`, and imperative message sends can override it. The policy travels with its message, so concurrent senders can't separate the two. Separate sessions run independently.
299
235
 
300
236
  ## Subagents
301
237
 
302
- A turn can hand work off to a [subagent](../subagents). Each subagent gets its own context and its own durable session; a declared subagent also gets its own sandbox, skills, and state. Nothing crosses the boundary implicitly.
238
+ A turn can hand work off to a [subagent](../subagents). Each subagent gets its own context and its own session; a declared subagent also gets its own sandbox, skills, and state. Nothing crosses the boundary implicitly.
303
239
 
304
240
  ## How eve orders session history
305
241
 
306
- Conversation history within a session is append-only. Static user-role instructions lead fresh-session history. Dynamic user-role instructions are added before a model call when their content changes. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too. Read a session back and you see messages in the order they happened.
242
+ Conversation history within a session is append-only. Static user-role instructions start a new session's history. Dynamic user-role instructions are added before a model call when their content changes. Turns follow in order, and the tool calls inside a turn (plus their results) keep their order too.
307
243
 
308
244
  ## What to read next
309
245
 
310
246
  - [Sessions and streaming](./sessions-runs-and-streaming): the handles you hold and the event stream you watch.
311
247
  - [Security model](./security-model): the trust boundaries the runtime enforces.
312
- - [State](./state): durable per-session memory that persists across step boundaries.
248
+ - [State](./state): per-session values that survive restarts and redeploys.
@@ -3,7 +3,7 @@ title: "Project Structure"
3
3
  description: "Start with one agent, keep application code beside it, and split into a workspace only when you need separately addressable agents."
4
4
  ---
5
5
 
6
- Start with one root agent in `agent/`. A root agent accepts requests through its own HTTP API or channels; it can have many tools, skills, and subagents. Keep browser application files outside `agent/`.
6
+ An eve project starts with one root agent in `agent/`. A root agent accepts requests through its own HTTP API or channels, and can have many tools, skills, and subagents. Keep browser application files outside `agent/`.
7
7
 
8
8
  | When you need… | Structure |
9
9
  | ---------------------------------------------------------------------- | ------------------------------------------------ |
@@ -12,7 +12,7 @@ Start with one root agent in `agent/`. A root agent accepts requests through its
12
12
  | Several separately addressable agents sharing a package and deployment | `agents/<name>/agent/` in an eve agent workspace |
13
13
  | Separate dependencies, versions, or release schedules | Separate agent packages or projects |
14
14
 
15
- Every root agent can have [declared subagents](/docs/subagents#declared-subagents) with their own prompts, tools, and sandboxes. These specialists have no separate channel endpoint and do not inherit the parent's authored capabilities. Use a [skill](/docs/skills) instead when you only need an optional procedure.
15
+ [Declared subagents](/docs/subagents#declared-subagents) have their own prompts, tools, and sandboxes, but no channel endpoint. They don't inherit the parent's tools, connections, or skills. Use a [skill](/docs/skills) instead when you only need an optional procedure.
16
16
 
17
17
  ## One agent
18
18
 
@@ -30,7 +30,7 @@ project/
30
30
  └── next.config.ts # optional Next.js integration
31
31
  ```
32
32
 
33
- Create the agent with [Getting Started](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`; share reusable capabilities through [extensions](/docs/extensions).
33
+ Create the agent with [Getting Started](/docs/getting-started). The [Agent Files reference](/docs/reference/agent-files) lists supported paths. Keep agent-only helpers in `agent/lib/`. Share reusable tools, skills, and connections through [extensions](/docs/extensions).
34
34
 
35
35
  For a generated chat UI, run `eve add channel/web` from the project root and choose Next.js or TanStack Start. For an existing browser app, follow your [framework integration guide](/docs/guides/frontend/overview#per-framework-integration).
36
36
 
@@ -52,7 +52,7 @@ project/
52
52
  └── web/
53
53
  ```
54
54
 
55
- Members share the root package, dependencies, scripts, and Vercel deployment. Their directory names identify them in the CLI and public routes. Members have no `package.json` of their own: adding one excludes that directory from eve workspace discovery. Unlike a package-manager workspace, this layout does not give members separate dependency or version boundaries.
55
+ Members share the root package, dependencies, scripts, and Vercel deployment, so they have no separate dependency or version boundaries. Their directory names identify them in the CLI and public routes. A member with its own `package.json` is excluded from eve workspace discovery.
56
56
 
57
57
  Create a workspace, then select an agent to run:
58
58
 
@@ -62,24 +62,31 @@ cd operations
62
62
  npx eve dev --agent support
63
63
  ```
64
64
 
65
- Run agent commands such as `dev`, `info`, and `eval` from `agents/<name>/`, or pass `--agent <name>` from the workspace root. `eve dev --agent support` runs the selected agent, not peer applications. Start other agents separately when needed; local [workspace-peer calls](/docs/subagents#vercel-workspace-peers) require an explicit transport.
65
+ Run agent commands such as `dev`, `info`, and `eval` from `agents/<name>/`, or pass `--agent <name>` from the workspace root. `eve dev --agent support` runs only that agent, not other agents or peer applications; local [workspace-peer calls](/docs/subagents#vercel-workspace-peers) require an explicit transport.
66
66
 
67
- On Vercel, run `eve link` and `eve deploy` from the root; deployment includes all members. No frontend is required. For self-hosting, [build and run each member separately](/docs/guides/deployment/self-hosting#run-workspace-members).
67
+ On Vercel, run `eve link` and `eve deploy` from the root; deployment includes all members. No frontend is required. For self-hosting, [build and run each member separately](/docs/guides/deployment/self-hosted-operations#run-workspace-members).
68
68
 
69
69
  ## Independent releases
70
70
 
71
- Use separate packages or projects when agents need independent dependencies or releases, even within the same monorepo. These are not eve agent-workspace members. Share capabilities through [workspace extensions](/docs/extensions#use-an-extension-in-a-workspace); delegate across deployments with [remote agents](/docs/guides/remote-agents).
71
+ Use separate packages or projects when agents need independent dependencies or releases, even within the same monorepo. These are not eve agent-workspace members. Share tools, skills, and connections through [workspace extensions](/docs/extensions#use-an-extension-in-a-workspace); delegate across deployments with [remote agents](/docs/guides/remote-agents).
72
72
 
73
73
  ## Configure a web deployment
74
74
 
75
- Choose how the frontend and agents run together independently of how many agents you have:
75
+ Either setup works with one agent or a workspace:
76
76
 
77
- - **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js owns the application lifecycle; the integration starts agent processes and proxies requests locally, and contributes separate agent services on Vercel. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically. A peer app such as `apps/web/` can select its eve project with `eveRoot: "../.."`.
78
- - **Add a frontend to an agent workspace:** keep the frontend as a peer application, for example under `apps/web/`. On Vercel, use [`eve/vercel` in root `vercel.ts`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosting#run-workspace-members), run the services with your process manager and configure a reverse proxy. The frontend does not need `eve/next`.
77
+ - **Add agents to a Next.js application:** use [`eve/next`](/docs/guides/frontend/nextjs) in `next.config.ts`. Next.js runs the application. Locally, the integration starts the agents and forwards requests to them. On Vercel, it adds the agents as separate services. A root Next.js app can sit beside either `agent/` or `agents/`; workspace members are discovered automatically. A peer app such as `apps/web/` can select its eve project with `eveRoot: "../.."`.
78
+ - **Add a frontend to an agent workspace:** keep the frontend as a peer application, for example under `apps/web/`. On Vercel, use [`eve/vercel` in root `vercel.ts`](/docs/guides/deployment/vercel#compose-agents-with-other-vercel-services) to contribute the agents alongside the frontend service. For [self-hosting](/docs/guides/deployment/self-hosted-operations#run-workspace-members), run the services with your process manager and configure a reverse proxy. The frontend does not need `eve/next`.
79
79
 
80
- `apps/web/` is an organizational convention, not an eve filesystem slot. Deployment configuration owns peer services; eve discovers only the agents. Both Vercel integrations deploy the services together, not as independent releases.
80
+ `apps/web/` is a convention, not a directory eve reads. Your deployment configuration defines peer services, and eve finds only the agents. Both Vercel integrations deploy the services together, not as independent releases.
81
81
 
82
- Run `eve add channel/web` from a standalone agent or select a workspace agent with `--agent <name>`. The installer asks which framework to use and creates a Next.js or TanStack Start frontend under `apps/web/`. Choose **Vercel services** to configure separate Vercel services and run them with `pnpm dev:all`; you don't need to link a Vercel project to run them locally. Choose **Next.js** or **TanStack Start** to let the frontend host the agent and run the application with `pnpm dev:web`. Use `pnpm dev` or `pnpm dev:eve` when you only want one agent and the eve terminal UI.
82
+ Run `eve add channel/web` from a standalone agent, or pass `--agent <name>` in a workspace, to create a Next.js or TanStack Start frontend under `apps/web/`. The installer then asks how to host it:
83
+
84
+ | Choice | Result |
85
+ | --------------------------------- | ------------------------------------------------------------------------------------------- |
86
+ | **Vercel services** | Separate Vercel services, run locally with `pnpm dev:all` without linking a Vercel project. |
87
+ | **Next.js** or **TanStack Start** | The frontend hosts the agent; run the application with `pnpm dev:web`. |
88
+
89
+ Use `pnpm dev` or `pnpm dev:eve` for one agent and the eve terminal UI.
83
90
 
84
91
  ## Add a second root agent
85
92
 
@@ -90,13 +97,13 @@ mkdir -p agents/support
90
97
  mv agent agents/support/agent
91
98
  ```
92
99
 
93
- Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `package.json`, dependencies, environment files, and any browser application at the project root. Do not leave a root `agent/` directory: eve treats a project with `agent/` as single-agent even when `agents/` also exists.
100
+ Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `package.json`, dependencies, environment files, and any browser application at the project root. Don't leave a root `agent/` directory, because eve treats a project with `agent/` as single-agent even when `agents/` exists.
94
101
 
95
102
  Before adding the next agent:
96
103
 
97
104
  - Update `tsconfig.json` to include `agents/**/*.ts`, preserving any application includes. Update moved-file imports and path aliases, including scaffolded `package.json#imports` entries that point at `./agent/*` or `./evals/*`.
98
105
  - Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#run-build-and-deploy).
99
- - Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name alongside durable-session links.
106
+ - Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name with any saved session links.
100
107
 
101
108
  Then add the second agent and check discovery:
102
109