eve 0.90.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 (185) hide show
  1. package/CHANGELOG.md +34 -23
  2. package/dist/src/channel/auth/http-basic.js +1 -1
  3. package/dist/src/channel/channel-operations.d.ts +1 -1
  4. package/dist/src/channel/types.d.ts +2 -0
  5. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  6. package/dist/src/client/session.d.ts +1 -1
  7. package/dist/src/compiled/.vendor-stamp.json +1 -1
  8. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  9. package/dist/src/execution/proxied-deliver-step.js +1 -1
  10. package/dist/src/execution/sandbox/bash.js +2 -2
  11. package/dist/src/execution/session/active-turn.js +1 -1
  12. package/dist/src/execution/session/admission.d.ts +6 -0
  13. package/dist/src/execution/session/admission.js +1 -1
  14. package/dist/src/execution/session/delivery-facts.js +1 -1
  15. package/dist/src/execution/session/next-input.d.ts +2 -2
  16. package/dist/src/execution/session/next-input.js +1 -1
  17. package/dist/src/execution/session/program.js +1 -1
  18. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  19. package/dist/src/execution/session-inbox/inbox.js +1 -1
  20. package/dist/src/execution/session-inbox/protocol.js +1 -1
  21. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  22. package/dist/src/harness/compaction/engine.js +2 -2
  23. package/dist/src/harness/current-messages.js +1 -1
  24. package/dist/src/harness/emission.d.ts +3 -0
  25. package/dist/src/harness/emission.js +1 -1
  26. package/dist/src/harness/facts.d.ts +5 -2
  27. package/dist/src/harness/facts.js +1 -1
  28. package/dist/src/harness/model-call/call.d.ts +7 -1
  29. package/dist/src/harness/model-call/call.js +3 -1
  30. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  31. package/dist/src/harness/provider-tool-history.js +1 -1
  32. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  33. package/dist/src/harness/step/after-model.js +1 -1
  34. package/dist/src/harness/step/context.js +1 -1
  35. package/dist/src/harness/step/intake.js +1 -1
  36. package/dist/src/harness/step/prompt.js +1 -1
  37. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  38. package/dist/src/harness/tool-history-repair.js +1 -1
  39. package/dist/src/harness/tool-loop.js +1 -1
  40. package/dist/src/internal/application/stamped-package-version.js +1 -1
  41. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  42. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  43. package/dist/src/protocol/session-projection/fold.js +1 -1
  44. package/dist/src/public/channels/discord/hitl.js +1 -1
  45. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  46. package/dist/src/public/channels/slack/hitl.js +3 -3
  47. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  48. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  49. package/dist/src/public/channels/teams/hitl.js +1 -1
  50. package/dist/src/public/channels/teams/verify.js +1 -1
  51. package/dist/src/public/definitions/hook.d.ts +90 -7
  52. package/dist/src/public/definitions/hook.js +1 -1
  53. package/dist/src/public/hooks/index.d.ts +3 -2
  54. package/dist/src/reactions/continuation.d.ts +19 -0
  55. package/dist/src/reactions/continuation.js +1 -0
  56. package/dist/src/reactions/intents.d.ts +10 -4
  57. package/dist/src/reactions/intents.js +1 -1
  58. package/dist/src/reactions/kinds/hook.js +1 -1
  59. package/dist/src/reactions/runner.js +1 -1
  60. package/dist/src/reactions/state.d.ts +15 -2
  61. package/dist/src/reactions/state.js +1 -1
  62. package/dist/src/runtime/resolve-connection.js +1 -1
  63. package/dist/src/runtime/subagents/workflow.js +1 -1
  64. package/dist/src/setup/primitives/open-url.js +1 -1
  65. package/dist/src/setup/scaffold/create/project.js +1 -1
  66. package/dist/src/shared/value-delta.d.ts +5 -4
  67. package/dist/src/shared/value-delta.js +1 -1
  68. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  69. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  70. package/dist/src/tools/provided/web-fetch.js +1 -1
  71. package/docs/agent-config.md +199 -222
  72. package/docs/channels/chat-sdk.mdx +60 -64
  73. package/docs/channels/custom.mdx +264 -281
  74. package/docs/channels/discord.mdx +176 -123
  75. package/docs/channels/eve.mdx +136 -206
  76. package/docs/channels/github.mdx +24 -22
  77. package/docs/channels/linear.mdx +30 -30
  78. package/docs/channels/linq.mdx +25 -13
  79. package/docs/channels/mcp.mdx +154 -116
  80. package/docs/channels/overview.mdx +31 -32
  81. package/docs/channels/photon.mdx +32 -56
  82. package/docs/channels/slack.mdx +538 -375
  83. package/docs/channels/teams.mdx +40 -26
  84. package/docs/channels/telegram.mdx +13 -13
  85. package/docs/channels/twilio.mdx +11 -11
  86. package/docs/code-extension.mdx +40 -42
  87. package/docs/concepts/built-in-tools.md +89 -57
  88. package/docs/concepts/context-control.md +20 -20
  89. package/docs/concepts/default-harness.md +20 -36
  90. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  91. package/docs/concepts/project-structure.mdx +21 -14
  92. package/docs/concepts/security-model.md +27 -27
  93. package/docs/concepts/sessions-runs-and-streaming.md +184 -198
  94. package/docs/concepts/state.md +7 -15
  95. package/docs/connections/mcp.mdx +109 -93
  96. package/docs/connections/openapi.mdx +57 -59
  97. package/docs/connections/overview.mdx +175 -170
  98. package/docs/evals/assertions.mdx +36 -29
  99. package/docs/evals/cases.mdx +38 -42
  100. package/docs/evals/judge.mdx +21 -29
  101. package/docs/evals/overview.mdx +42 -38
  102. package/docs/evals/reporters.mdx +54 -27
  103. package/docs/evals/running.mdx +15 -8
  104. package/docs/evals/targets.mdx +16 -19
  105. package/docs/evals/tool-stubs.mdx +111 -97
  106. package/docs/experimental/dynamic-schedules.mdx +118 -63
  107. package/docs/extensions.md +58 -65
  108. package/docs/getting-started.mdx +4 -6
  109. package/docs/guides/auth-and-route-protection.md +87 -70
  110. package/docs/guides/client/continuations.mdx +23 -26
  111. package/docs/guides/client/messages.mdx +47 -66
  112. package/docs/guides/client/output-schema.mdx +8 -8
  113. package/docs/guides/client/overview.mdx +45 -43
  114. package/docs/guides/client/streaming.mdx +62 -71
  115. package/docs/guides/decide.md +24 -79
  116. package/docs/guides/deployment/meta.json +1 -1
  117. package/docs/guides/deployment/overview.md +27 -18
  118. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  119. package/docs/guides/deployment/self-hosting.md +63 -80
  120. package/docs/guides/deployment/vercel.mdx +31 -27
  121. package/docs/guides/deployment/workflow-worlds.md +100 -0
  122. package/docs/guides/dev-tui.md +48 -41
  123. package/docs/guides/dynamic-capabilities.md +49 -50
  124. package/docs/guides/frontend/nextjs.mdx +2 -2
  125. package/docs/guides/frontend/nuxt.mdx +11 -11
  126. package/docs/guides/frontend/overview.mdx +1 -1
  127. package/docs/guides/frontend/sveltekit.mdx +11 -11
  128. package/docs/guides/frontend/tanstack.mdx +16 -16
  129. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  130. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  131. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  132. package/docs/guides/hooks.md +152 -106
  133. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  134. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  135. package/docs/guides/instrumentation/meta.json +1 -1
  136. package/docs/guides/instrumentation/otel.mdx +113 -179
  137. package/docs/guides/remote-agents.md +125 -187
  138. package/docs/guides/self-modification.md +18 -18
  139. package/docs/guides/session-context.md +16 -16
  140. package/docs/install-integrations.mdx +26 -24
  141. package/docs/instructions.mdx +37 -42
  142. package/docs/memory/custom-provider.md +35 -41
  143. package/docs/memory/file.md +93 -76
  144. package/docs/memory/overview.mdx +145 -156
  145. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  146. package/docs/patterns/dynamic-scheduling.md +19 -23
  147. package/docs/patterns/multi-tenant-approvals.md +17 -22
  148. package/docs/patterns/multi-tenant-auth.md +43 -42
  149. package/docs/patterns/multi-tenant-memory.md +39 -36
  150. package/docs/patterns/voice-notes.md +3 -3
  151. package/docs/protocols/acp.md +13 -13
  152. package/docs/protocols/ucp.mdx +7 -7
  153. package/docs/reference/agent-files.md +6 -6
  154. package/docs/reference/cli.md +99 -98
  155. package/docs/reference/telemetry.md +1 -1
  156. package/docs/reference/typescript-api.md +52 -53
  157. package/docs/responsible-use.md +2 -2
  158. package/docs/sandbox/custom-providers.mdx +60 -56
  159. package/docs/sandbox/default.mdx +23 -24
  160. package/docs/sandbox/docker.mdx +16 -10
  161. package/docs/sandbox/index.mdx +93 -61
  162. package/docs/sandbox/just-bash.mdx +17 -11
  163. package/docs/sandbox/troubleshooting.mdx +29 -23
  164. package/docs/sandbox/vercel.mdx +45 -52
  165. package/docs/schedules.mdx +65 -54
  166. package/docs/skills.mdx +74 -49
  167. package/docs/subagents/index.mdx +97 -136
  168. package/docs/tools/human-in-the-loop.md +160 -90
  169. package/docs/tools/meta.json +1 -1
  170. package/docs/tools/overview.mdx +229 -237
  171. package/docs/tools/tasks.md +118 -117
  172. package/docs/tools/workflows.mdx +447 -543
  173. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  174. package/docs/tutorial/first-agent.mdx +14 -16
  175. package/docs/tutorial/guard-the-spend.mdx +6 -8
  176. package/docs/tutorial/how-it-runs.mdx +8 -8
  177. package/docs/tutorial/query-sample-data.mdx +8 -8
  178. package/docs/tutorial/remember-definitions.mdx +4 -4
  179. package/docs/tutorial/run-analysis.mdx +20 -22
  180. package/docs/tutorial/ship-it.mdx +19 -19
  181. package/docs/tutorial/team-playbooks.mdx +9 -9
  182. package/docs/use-cases.mdx +13 -11
  183. package/package.json +1 -1
  184. package/docs/guides/instrumentation/migration.md +0 -96
  185. package/docs/tools/tasks-upgrade.md +0 -218
@@ -3,9 +3,9 @@ title: "Streaming"
3
3
  description: "Consume eve client stream events live, reconnect by line position, and aggregate turn results."
4
4
  ---
5
5
 
6
- `ClientSession.send()` posts a message and returns a `Delivery` when the server accepts it. The receipt has its own `sessionId` and `deliveryId`; it does not wait for a reply. Call `result()` for its summary or `stream()` to observe it live. Both methods support independent, repeated reads. Import the shared delivery and reader contracts from `eve/sessions`.
6
+ A `Delivery` is the receipt `ClientSession.send()` returns once the server accepts a message. It carries a `sessionId` and `deliveryId` and doesn't wait for a reply. Call `result()` for its summary or `stream()` to watch it live. Each read is independent, and you can repeat either one. Import `Delivery` and its read types from `eve/sessions`.
7
7
 
8
- Session controls return deliveries too. `session.cancel({ turnId })` targets an observed turn, so a late cancellation cannot stop unrelated later work. Omitting `turnId` cancels the current work. For example, cancel as soon as this message reaches a turn:
8
+ Session controls return a `Delivery` too. `session.cancel({ turnId })` targets a turn you saw on the stream, so a late cancellation can't stop unrelated later work. Omit `turnId` to cancel the current work. For example, cancel as soon as this message reaches a turn:
9
9
 
10
10
  ```ts
11
11
  const { session, delivery } = await client.sessions.create({ message: "Run the long operation." });
@@ -22,9 +22,9 @@ for await (const event of delivery.stream()) {
22
22
  }
23
23
  ```
24
24
 
25
- The cancellation delivery settles when the command is applied, including a no-op for a turn that already ended. Continue reading the original message's delivery to observe its outcome and advance its cursor. A live idle session also accepts cancellation; it does not return a separate `no_active_turn` result.
25
+ The cancellation's `result()` resolves once eve applies the cancel, even as a no-op for a turn that already ended. An idle session that hasn't ended also accepts cancellation instead of returning `no_active_turn`. Keep reading the original message's `Delivery` to see its outcome.
26
26
 
27
- Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` removes model-message history while retaining the session and its durable resources. Client `messages` and `transcriptOf()` then leave out everything before the clear. Await their deliveries before sending another turn:
27
+ Between turns, `session.compact()` queues context compaction without sending model input. `session.clear()` cancels a running turn and every working task, then removes the model's message history. It keeps the session and its other saved resources. Client `messages` and `transcriptOf()` then leave out everything before the clear. Await their results before you send another turn:
28
28
 
29
29
  ```ts
30
30
  const compaction = await session.compact();
@@ -37,11 +37,11 @@ const cleared = await session.clear();
37
37
  await cleared.result();
38
38
  ```
39
39
 
40
- Observe `context.settled` while streaming to check whether summarization succeeded. A failed or empty summary preserves the previous history. `session.end()` instead retires the session; its delivery settles after retirement and address release.
40
+ `context.settled` reports whether summarization succeeded; a failed or empty summary keeps the previous history. `session.end()` instead retires the session, and its `result()` resolves after the session is retired.
41
41
 
42
42
  ## Aggregate a turn
43
43
 
44
- Use `result()` when you only need the final turn summary:
44
+ Use `result()` when you need only the final turn summary:
45
45
 
46
46
  ```ts
47
47
  const response = await session.send("Summarize the latest forecast.");
@@ -53,37 +53,33 @@ console.log(result.outcome);
53
53
  if (result.status === "failed") console.error(result.error.code, result.error.message);
54
54
  ```
55
55
 
56
- This reads until the message's delivery settles (`delivery.settled` for its
57
- `deliveryId`), finishing that line. A stream that ends without the accepted delivery's settlement
58
- rejects the read, including when only a session terminal was observed. A delivery settles when the
59
- turn that consumed it settles (`handled`), or when the turn pauses on an interaction
60
- (`awaiting-input`), such as for an approval, question, or sign-in. See
56
+ `result()` reads until the `delivery.settled` event for the message's `deliveryId`. If the stream
57
+ ends first, the read rejects, even when the session has ended. That event arrives when the turn
58
+ finishes (`handled`) or pauses for an approval, question, or sign-in (`awaiting-input`). See
61
59
  [authorization pauses](#authorization-pauses).
62
60
 
63
- A turn that waits on its [tasks](/docs/tools/workflows#run-calls-as-tasks-task) stays open:
64
- `result()` keeps reading to its final reply. The text the model wrote before the wait is
65
- narration, not the reply. When a call the turn runs asks a question, such as a workflow tool's
66
- `ctx.ask()`, `result()` returns `status: "awaiting-input"` with the question in `interactions`. Answer it
67
- with `respond()`, which keeps reading the same turn. A question stays pending until its
68
- `interaction.settled`, which the session you answer on also emits for a subagent's or workflow
69
- tool's question.
61
+ A turn that waits on its [tasks](/docs/tools/workflows#run-calls-as-tasks-task) stays open, and
62
+ `result()` keeps reading to its final reply; text written before the wait is narration. When a
63
+ call asks a question, such as a workflow tool's `ctx.ask()`, `result()` returns
64
+ `status: "awaiting-input"` with the question in `interactions`. Answer it with `respond()`, which
65
+ keeps reading the same turn. A question stays open until its `interaction.settled` event. The
66
+ session you answer on emits that event, even for a subagent's or workflow tool's question.
70
67
 
71
- `result().status` describes the settled request: `awaiting-input`, `completed`, `failed`, or
72
- `cancelled`. To inspect live progress, use `delivery(view, deliveryId)` and, when it has a `turnId`, `turn(view, turnId)` from `eve/events`.
73
- A completed request can leave its session open. Read `result().sessionEnded` to check whether
74
- the session itself ended, and `outcome` to distinguish an applied control from an ignored one.
68
+ `result().status` is `awaiting-input`, `completed`, `failed`, or `cancelled`. A completed
69
+ request can leave its session open, so read `result().sessionEnded` to check whether the session
70
+ ended. Read `outcome` to tell an applied control from an ignored one. To inspect live progress, use
71
+ `delivery(view, deliveryId)` and, when it has a `turnId`, `turn(view, turnId)` from `eve/events`.
75
72
 
76
- Results do not collect an `events` array. To keep a request log, append events from
77
- `response.stream()` to your own collection. You can still call `response.result()` afterward;
78
- the reads do not share a consumption cursor.
73
+ Results don't collect an `events` array. To keep a request log, append events from
74
+ `response.stream()` to your own collection. Reads don't share a cursor, so a later
75
+ `response.result()` still reads the whole delivery.
79
76
 
80
- `result()` closes that HTTP stream, including when fetch instrumentation clones
81
- the response for tracing. The durable session remains available for follow-up
82
- turns.
77
+ `result()` closes its HTTP stream, even when fetch instrumentation clones the response. The
78
+ session stays available for follow-up turns.
83
79
 
84
80
  ## Stream events live
85
81
 
86
- Use `for await...of` when you want to render progress:
82
+ Iterate `stream()` with `for await...of` to render progress:
87
83
 
88
84
  ```ts
89
85
  const response = await session.send("Draft a plan and show your work.");
@@ -99,9 +95,9 @@ for await (const event of response.stream()) {
99
95
  }
100
96
  ```
101
97
 
102
- `content.delta` and `call.input` are progress records that carry only their new text. eve may merge adjacent deltas for the same part or call when the writer is busy; the text and ordering stay the same.
98
+ `content.delta` and `call.input` carry only their new text. eve may merge adjacent deltas for the same part or call without changing the text or order.
103
99
 
104
- The default message reducer accumulates these for you. A raw stream consumer can apply the same rule directly, keyed by part:
100
+ The default message reducer accumulates them for you. A raw consumer appends them by part:
105
101
 
106
102
  ```ts
107
103
  const parts = new Map<string, string>();
@@ -112,13 +108,13 @@ for await (const event of response.stream()) {
112
108
  }
113
109
  ```
114
110
 
115
- After reconnecting without local state, replay the earlier lines or wait for the part's `content.completed`, which carries its whole value, instead of appending a later delta to an empty value.
111
+ After reconnecting without local state, don't append a later delta to an empty value. Replay the earlier lines, or wait for the part's `content.completed`, which carries its whole value.
116
112
 
117
- The eve client validates the stream version on every connection and accepts version 27. A missing or different version fails instead of being read as current events.
113
+ The client checks the stream version on every connection and accepts only version 27; a missing or different version fails the read.
118
114
 
119
115
  ## Handle event types
120
116
 
121
- Import event types from `eve/client`, or the full catalog, the shared fold, and selectors from `eve/events`. Events read from a stream are `SessionStreamEvent`: a fact or progress record with its `meta` envelope.
117
+ Import event types from `eve/client`, or the full catalog, the shared fold, and selectors from `eve/events`. Events read from a stream are `SessionStreamEvent`: a recorded event or a progress update, with its `meta` envelope.
122
118
 
123
119
  ```ts
124
120
  import type { SessionStreamEvent } from "eve/client";
@@ -152,27 +148,27 @@ The most common UI events are:
152
148
 
153
149
  For the complete catalog, see [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming).
154
150
 
155
- For `call.input`, the conversation's `tool` part reads `state: "streaming"` and accumulates the deltas in `inputText`, cumulative raw text that may be incomplete JSON. `call.requested` replaces it with the validated `input`.
151
+ During `call.input`, the conversation's `tool` part has `state: "streaming"` and accumulates raw, possibly incomplete JSON in `inputText`. `call.requested` replaces it with the validated `input`.
156
152
 
157
- A call to a tool that runs as a [task](/docs/tools/workflows#run-calls-as-tasks-task) starts with `call.started` carrying its `taskId` and settles later with its own `call.settled`. The model receives the result in its history.
153
+ A call to a tool that runs as a [task](/docs/tools/workflows#run-calls-as-tasks-task) starts with a `call.started` that carries its `taskId`. It ends later with its own `call.settled`, and the model receives that result in its history.
158
154
 
159
- File parts in `delivery.consumed.data.parts` never include raw bytes or internal sandbox paths; `url` appears only for `http(s)` URLs, and an inline file reports its `size` instead.
155
+ File parts in `delivery.consumed.data.parts` never include raw bytes or internal sandbox paths. They include `url` only for `http(s)` URLs; an inline file reports its `size` instead.
160
156
 
161
157
  ## Authorization pauses
162
158
 
163
- A sign-in is an `interaction.opened` whose `request.kind` is `"sign-in"`. It means a connection needs OAuth or another authorization challenge before the paused turn can continue. Chat UIs should render the sign-in prompt from `request.signIn`, disable ordinary text input for that session, and persist the event with the rest of the chat history.
159
+ A sign-in is an `interaction.opened` whose `request.kind` is `"sign-in"`: a connection needs OAuth or another authorization challenge before the turn can continue. Render the prompt from `request.signIn`, disable ordinary text input for that session, and persist the event with the chat history.
164
160
 
165
- The sign-in holds the turn open, and the stream emits `turn.paused` awaiting it while the callback is pending. The current delivery settles with `status: "awaiting-input"`. Follow the session with `session.stream()` to observe the callback and the resumed work. If you support refresh while authorization is pending, save the session cursor and events, then rehydrate them on load. The callback or a structured decline resumes the same eve session.
161
+ While the sign-in is pending, the stream emits `turn.paused`, and the current message's result returns `status: "awaiting-input"`. Completing the sign-in, or declining it, resumes the same session. Follow it with `session.stream()` to see the resumed work. To keep the prompt across a page refresh, save the session cursor and events, and restore them on load.
166
162
 
167
163
  ## Reconnection
168
164
 
169
- HTTP connections can end before a run does. The client reconnects from the next line it hasn't read, so long turns continue without replaying events. By default, a delivery keeps reconnecting until it settles or is aborted. Use a session stream to follow work beyond that delivery's settlement. A stream ends for good on `{"$eve":"stream.ended"}`, which the server sends once the session has ended.
165
+ When an HTTP connection ends before the run does, the client reconnects from the next unread line without replaying events. Omit a policy to keep reconnecting until the message's work finishes or you abort the read. Use a session stream to follow work past that point. A stream ends for good on `{"$eve":"stream.ended"}`, which the server sends once the session has ended.
170
166
 
171
- Browser network failures use the same reconnect policy, both when opening a stream (`TypeError: Failed to fetch`, `TypeError: Load failed`, or `TypeError: NetworkError when attempting to fetch resource.`) and while reading a response body (any `TypeError`, such as `TypeError: network error`). Invalid stream events still fail the read.
167
+ Browser network failures also reconnect, both when opening a stream (`TypeError: Failed to fetch`, `TypeError: Load failed`, or `TypeError: NetworkError when attempting to fetch resource.`) and while reading the body (any `TypeError`, such as `TypeError: network error`). Invalid stream events still fail the read.
172
168
 
173
169
  If your consumer persists events, key on `event.meta.position`. It is stable across reconnects and rewinds, so an overlapping replay is safe to ingest twice. See [Positions](../../concepts/sessions-runs-and-streaming#positions).
174
170
 
175
- Set `reconnect: false` when a relay or proxy owns the cursor and reconnection policy. This makes a single stream GET attempt and returns when that connection ends; it does not stop the server-side turn:
171
+ Set `reconnect: false` when a relay or proxy owns the cursor and reconnection. The client makes one stream GET and returns when that connection ends, without stopping the server-side turn:
176
172
 
177
173
  ```ts
178
174
  const response = await session.send("Run the long operation.", {
@@ -205,7 +201,7 @@ const response = await session.send("Run the long operation.", {
205
201
 
206
202
  ## Open a stream manually
207
203
 
208
- Use `session.stream()` when you already have a session cursor and only need to attach to the existing stream:
204
+ Use `session.stream()` to attach to an existing stream from a saved cursor:
209
205
 
210
206
  ```ts
211
207
  const session = client.sessions.attach("wrun_01ARYZ6S41TSV4RRFFQ69G5FAV", {
@@ -234,11 +230,11 @@ for await (const event of session.stream({ startIndex: -1 })) {
234
230
  }
235
231
  ```
236
232
 
237
- Tail-relative attachments do not automatically reconnect or advance the session's stored absolute `streamIndex`. Break after the event you need when using one as a tail lookup.
233
+ Tail-relative reads don't reconnect or advance the session's stored `streamIndex`. Break after the event you need.
238
234
 
239
235
  ## Bounded catch-up reads
240
236
 
241
- Pass `follow: false` to read from the cursor to the durable tail and then stop, instead of following the live stream (the default):
237
+ Pass `follow: false` to read from the cursor to the stream's current end and then stop, instead of following the live stream (the default):
242
238
 
243
239
  ```ts
244
240
  for await (const event of session.stream({ follow: false })) {
@@ -247,9 +243,9 @@ for await (const event of session.stream({ follow: false })) {
247
243
  // Returns once every line recorded before the stream opened is consumed.
248
244
  ```
249
245
 
250
- The first connection pins the bound to the tail the server reports at open time; events recorded afterward are not part of the read. Reconnects during the read keep that original bound, and the session's stored `streamIndex` still advances past the consumed events, so a follow-up `stream()` or `send()` picks up exactly where the bounded read ended. When the cursor is already at or past the tail, the iterator returns immediately without yielding.
246
+ The server reports that end when the first connection opens, and reconnects keep it. The stored `streamIndex` still advances, so a later `stream()` or `send()` picks up where the bounded read ended. When the cursor is already at or past that end, the iterator returns without yielding.
251
247
 
252
- Because a tail-relative cursor cannot be bounded, `follow: false` throws when combined with a negative `startIndex`. It also fails if the server does not report the durable tail (an agent running an older eve version).
248
+ `follow: false` throws with a negative `startIndex`, because a tail-relative cursor can't be bounded. It also fails when the server doesn't report the stream's end, as an agent on an older eve version doesn't.
253
249
 
254
250
  ## Snapshot a session
255
251
 
@@ -263,20 +259,16 @@ const snapshot = await session.snapshot();
263
259
  // snapshot.events holds lines 0 through snapshot.session.streamIndex - 1.
264
260
  ```
265
261
 
266
- The read pins the durable tail when it opens, just like
267
- `stream({ follow: false })`. Events written afterward are not included, and
268
- `snapshot.session.streamIndex` is the exact line from which a live consumer can
269
- continue. `snapshot()` always reads from line `0`; use a bounded stream directly
270
- when you only need the unread suffix from an existing cursor.
271
-
272
- Unlike `stream()`, `snapshot()` does not advance the originating
273
- `ClientSession`. Its returned `session` is the handle's full `ClientSessionState`, including the
274
- opaque `inbox` value, with `streamIndex` set to the exact line after the captured prefix. Persist
275
- it as is to restore the conversation later.
262
+ Like `stream({ follow: false })`, the read fixes the stream's end when it opens,
263
+ and `snapshot.session.streamIndex` is the line a live reader continues from.
264
+ `snapshot()` always reads from line `0` and doesn't advance the originating
265
+ `ClientSession`; use a bounded stream when you need only the unread suffix.
266
+ The returned `session` is the handle's full `ClientSessionState`, including the
267
+ opaque `inbox` value. Save it as is to restore the conversation later.
276
268
 
277
269
  ## Follow a subagent
278
270
 
279
- A delegated subagent reports its progress on its own child session. The parent stream announces each child session with `child.opened`, whether the model called a subagent tool or a [workflow tool](/docs/tools/workflows#delegate-work-ctxagent) opened the session with `ctx.agent`. Pass the event to `agent()` on the parent's session handle to get the child's handle, then follow it with `stream()`:
271
+ A delegated subagent reports progress on its own child session. The parent stream announces each one with `child.opened`, whether a subagent tool or a [workflow tool](/docs/tools/workflows#delegate-work-ctxagent)'s `ctx.agent` opened it. Pass the event to `agent()` on the parent's handle to get the child's handle, then follow it with `stream()`:
280
272
 
281
273
  ```ts
282
274
  import { endsTurn } from "eve/client";
@@ -294,18 +286,18 @@ if (opened?.type === "child.opened") {
294
286
  }
295
287
  ```
296
288
 
297
- Pass the received event, including its source position. The reader asks the parent's server to verify the opening at that committed line before returning child history. Cached events and their `stream` strings are not authority to access another session or destination.
289
+ Pass the event as you received it, including its position, because the parent's server checks that line before it returns child history. Cached events and their `stream` strings grant no access to another session or destination.
298
290
 
299
291
  - Local children are read only after verifying the recorded relationship on the same deployment.
300
292
  - Remote children use the parent deployment's proxy and the remote agent's authored `auth` and `headers`. The browser never needs the remote URL or its credentials. Foreign redirects are not followed.
301
293
 
302
- To read a deeper child, pass its received `child.opened` event to `child.agent(opened)`. Each hop verifies its own recorded relationship, including through remote proxies. Unsupported or unavailable relationships fail rather than attaching by ID. Paths are limited to eight hops.
294
+ To read a deeper child, pass its `child.opened` event to `child.agent(opened)`. Each hop verifies its own relationship, including through remote proxies, and fails instead of attaching by ID when the relationship is unsupported or unavailable. Paths are limited to eight hops.
303
295
 
304
- The child has its own cursor, starting at `0`, and reading it never advances the parent's `streamIndex`. Pass `startIndex` to resume, `follow: false` for a bounded read, and `signal` to detach. A child parks after answering and can be continued later, so stop at a turn boundary with `endsTurn` when you only need the current turn. A parent follows only a child that speaks the current remote agent protocol; an earlier remote child's result still arrives, but its descendant reader reports unsupported history.
296
+ The child has its own cursor, starting at `0`, and reading it never advances the parent's `streamIndex`. Pass `startIndex` to resume, `follow: false` for a bounded read, and `signal` to detach. A child waits for more input after it answers. To read only the current turn, stop at the turn's end with `endsTurn`. A remote child on an earlier agent protocol still returns its result, but its descendant reader reports unsupported history.
305
297
 
306
298
  ## Observe nested traces without a framework
307
299
 
308
- Use `SessionStore` when you need projected nested conversations rather than managing readers yourself:
300
+ Use `SessionStore` when you want eve to track nested conversations for you instead of managing readers yourself:
309
301
 
310
302
  ```ts
311
303
  import { SessionStore } from "eve/client";
@@ -333,17 +325,17 @@ try {
333
325
  }
334
326
  ```
335
327
 
336
- Construction does not start reads. `observe()` activates a reference-counted scope and returns an idempotent cleanup function. Root streaming also activates child following; framework bindings activate and release scopes after mount. The store continues refreshing admitted children within an active scope even if `followWhile` closes the root stream. There is no full-tree catch-up barrier.
328
+ Creating a store doesn't start any reads. `observe()` starts observation and returns a cleanup function that is safe to call more than once. Observation is reference-counted, so it stops after every caller cleans up. Streaming the root also starts following children, and framework bindings start observation on mount. While observation is active, admitted children keep refreshing even after `followWhile` closes the root stream. No call waits for the whole tree to catch up.
337
329
 
338
- `followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child observations](../frontend/use-eve-agent#child-agents) for limits, states, and cursor semantics. Child conversations are whole-session views; their messages do not replace authoritative call results.
330
+ `followAgents: true` recursively follows all eligible recorded children within fixed depth, admission, and request limits. A predicate such as `({ depth }) => depth === 1` selects only immediate children. See [child agents](../frontend/use-eve-agent#child-agents) for limits, states, and cursor semantics. Each child conversation shows the child's whole session. Use the parent's call results, not the child's messages, as the outcome of a call.
339
331
 
340
- Stop the old scope and construct a new store when the principal or tenant changes. Token refresh callbacks resolve again for each request without changing observation identity. For a cross-origin browser connection, expose `x-eve-observation-key` in the channel's CORS configuration alongside the stream version and tail headers.
332
+ When the signed-in user or tenant changes, stop the old observation and create a new store. Token callbacks run again for each request without changing the observation key. For a cross-origin browser connection, expose `x-eve-observation-key` in the channel's CORS configuration alongside the stream version and tail headers.
341
333
 
342
- Archive projected messages and their per-node positions in an application-owned, versioned format. `SessionView` is opaque and is not a serialized archive format. Descendants can advance while the root position stays unchanged. A failed observation retains its last committed data; do not replace an existing archive with an empty failed read.
334
+ To archive nested conversations, save their messages and each child's position in your own versioned format. `SessionView` is opaque and isn't an archive format. Children can advance while the root position stays the same. A failed observation keeps its last recorded data, so don't replace an existing archive with an empty failed read.
343
335
 
344
336
  ## Abort a request
345
337
 
346
- Pass an `AbortSignal` to `send()` to abort submission, and to `stream()` or `result()` to abort a read. Aborting is local transport cancellation: turns are resumable across disconnects, so detaching never stops server-side work. Use `session.cancel()` to stop the active turn. Cancellation is asynchronous; watch the stream for `turn.settled` with `outcome: "cancelled"`.
338
+ Pass an `AbortSignal` to `send()` to abort submission, and to `stream()` or `result()` to abort a read. Aborting only detaches the client and never stops server-side work. To stop the active turn, call `session.cancel()` and watch for `turn.settled` with `outcome: "cancelled"`.
347
339
 
348
340
  Arm the timeout before awaiting `send()` so it covers the POST as well as the stream:
349
341
 
@@ -362,10 +354,9 @@ for await (const event of response.stream({ signal: controller.signal })) {
362
354
  clearTimeout(timeout);
363
355
  ```
364
356
 
365
- An interrupted read does not consume the delivery. Call `response.stream()` or
366
- `response.result()` again without the aborted signal to observe the same accepted work.
367
- Aborting one read leaves concurrent readers running; do not send the message again merely to
368
- resume observation.
357
+ An interrupted read doesn't consume the `Delivery`, and other concurrent readers keep running.
358
+ Call `response.stream()` or `response.result()` again without the aborted signal instead of
359
+ sending the message again.
369
360
 
370
361
  ## What to read next
371
362
 
@@ -3,21 +3,14 @@ title: Automatic Model Selection
3
3
  description: "Choose agent models automatically or ask typed questions in your tools and application code."
4
4
  ---
5
5
 
6
- Use `auto` from `eve/models` to choose an agent model from an allowlist before
7
- inference begins. It uses the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions),
8
- so the decider can be a Vercel AI Gateway model ID or a decision model from
9
- an installed provider. Use `decide` from `eve/ai` to ask typed questions in
10
- your own tools or application code.
6
+ `auto` from `eve/models` chooses an agent model from an allowlist before each turn's inference. `decide` from `eve/ai` asks typed questions in your own tools or application code. Both use the [AI SDK decision API](https://ai-sdk.dev/docs/ai-sdk-core/decisions). The decider can be a Vercel AI Gateway model ID or a decision model from an installed provider.
11
7
 
12
8
  The AI SDK decision model specification is experimental and can change in
13
9
  patch releases.
14
10
 
15
11
  ## Choose from Gateway models
16
12
 
17
- By default, `auto` decides with `typesafe-ai/jev`, TypeSafe AI's
18
- [Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK
19
- model strings, it uses Vercel AI Gateway unless the application has configured a
20
- different global default provider.
13
+ Omit `model` to decide with `typesafe-ai/jev`, TypeSafe AI's [Jev decision model](https://vercel.com/i/what-is-jev). Like other AI SDK model strings, it resolves through Vercel AI Gateway unless the application configures a different global default provider.
21
14
 
22
15
  ```ts title="agent/agent.ts"
23
16
  import { defineAgent } from "eve";
@@ -33,17 +26,9 @@ export default defineAgent({
33
26
  });
34
27
  ```
35
28
 
36
- Configure Gateway authentication as you would for any other AI SDK model. eve
37
- does not add a TypeSafe credential or transport layer. During `eve dev`, a
38
- Gateway decider uses the same connection selected through `/login` as Gateway
39
- language models. A configured AI SDK default provider still owns string model
40
- resolution during development. The TUI footer displays `dynamic model` when the
41
- agent uses `auto`, then adds the resolved model for the current turn, such as
42
- `dynamic model · openai/gpt-6-luna`.
29
+ Configure Gateway authentication as for any other AI SDK model; there is no separate TypeSafe credential. During `eve dev`, a Gateway decider uses the connection selected through `/login`, unless a configured AI SDK default provider resolves string models. The TUI footer shows `dynamic model` and then the turn's resolved model, such as `dynamic model · openai/gpt-6-luna`.
43
30
 
44
- Set `fallback` to keep the turn running when the decider is unavailable or
45
- returns an error. The fallback can be a Gateway model ID, an AI SDK language
46
- model instance, or an object with `model` and a `reasoning` override:
31
+ Set `fallback` to keep the turn running when the decider is unavailable or returns an error. The fallback can be a Gateway model ID, an AI SDK language model instance, or an object with `model` and a `reasoning` override:
47
32
 
48
33
  ```ts title="agent/agent.ts"
49
34
  import { defineAgent } from "eve";
@@ -60,16 +45,11 @@ export default defineAgent({
60
45
  });
61
46
  ```
62
47
 
63
- The fallback applies only to decider failures. eve logs a warning with the
64
- decider error and fallback identity when it switches models. Invalid prompts,
65
- including requests without user text or with a latest message over the routing
66
- limit, still fail before decider I/O. Cancelling the turn also aborts routing
67
- instead of selecting the fallback.
48
+ The fallback applies only to decider failures. When eve switches, it logs a warning with the decider error and the fallback model. Invalid prompts and cancelled turns don't use the fallback; see [Runtime behavior](#runtime-behavior).
68
49
 
69
50
  ## Use a provider directly
70
51
 
71
- Install the provider package yourself and pass its decision model. The provider
72
- owns its credentials and settings.
52
+ Install the provider package and pass its decision model. The provider owns its credentials and settings.
73
53
 
74
54
  ```sh
75
55
  pnpm add @ai-sdk/typesafe-ai
@@ -91,14 +71,11 @@ export default defineAgent({
91
71
  });
92
72
  ```
93
73
 
94
- Any provider that implements the AI SDK `Experimental_DecisionModel` contract
95
- works here.
74
+ Any provider that implements the AI SDK `Experimental_DecisionModel` contract works.
96
75
 
97
76
  ## Route to provider models and set reasoning
98
77
 
99
- An option's key is the value shown to the decider. A string value describes a
100
- Gateway model whose ID is the key. Use the object form when the selected model is
101
- a provider instance, an alias, or needs a reasoning override.
78
+ The decider sees each option's key. A string value describes the Gateway model whose ID is the key. Use the object form for a provider instance, an alias, or a reasoning override.
102
79
 
103
80
  ```ts title="agent/agent.ts"
104
81
  import { anthropic } from "@ai-sdk/anthropic";
@@ -120,22 +97,13 @@ export default defineAgent({
120
97
  });
121
98
  ```
122
99
 
123
- The decider sees option keys, descriptions, and recent text messages. It never
124
- receives provider credentials or serialized language model instances. When it
125
- selects `my_secret_model`, eve resolves the key back to the authored Anthropic
126
- model.
100
+ The decider sees option keys, descriptions, and recent text messages, never provider credentials or model instances. When it selects `my_secret_model`, eve resolves the key back to the authored Anthropic model.
127
101
 
128
- Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`,
129
- `"low"`, `"medium"`, `"high"`, and `"xhigh"`. An omitted value inherits the
130
- agent's reasoning setting.
102
+ Supported reasoning values are `"provider-default"`, `"none"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, and `"xhigh"`. Omit `reasoning` to inherit the agent's reasoning setting.
131
103
 
132
104
  ## Decide inside a tool
133
105
 
134
- Use `decide` to ask choice, score, or boolean questions about the state you pass to it.
135
- It defaults to `typesafe-ai/jev` and uses the same authentication as `auto`,
136
- including the Gateway connection selected through `/login` during `eve dev`.
137
- Pass `model` to use another decision model ID or a provider instance. A configured
138
- AI SDK default provider takes precedence over the local Gateway connection.
106
+ `decide` asks choice, score, or boolean questions about the state you pass it. It defaults to `typesafe-ai/jev` with the same authentication as `auto`. Pass `model` to use another decision model ID or a provider instance.
139
107
 
140
108
  ```ts title="agent/tools/classify-request.ts"
141
109
  import { decide } from "eve/ai";
@@ -165,33 +133,21 @@ export default defineTool({
165
133
  });
166
134
  ```
167
135
 
168
- The choice above is typed as `"billing" | "support"`. Each question appears under
169
- its authored key in `result.answers`. Results also include normalized token usage in `usage`.
170
- To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
136
+ The choice above is typed as `"billing" | "support"`. Each answer appears under its question's key in `result.answers`, and `usage` holds normalized token usage. To use that choice to delegate while keeping specialist subagents out of the parent model's tools, see [Route to a hidden subagent with Jev](/docs/tools/workflows#route-to-a-hidden-subagent-with-jev).
171
137
 
172
- `decide` accepts `model`, `state`, `questions`, `maxRetries`, and `signal`.
173
- Pass `signal: ctx.abortSignal` to cancel the request. Import `DecisionModel`, `DecisionState`,
174
- `DecisionStatePart`, `DecisionInput`, `DecisionQuestion`, `DecisionAnswer`, `DecisionOptions`,
175
- and `DecisionResult` from `eve/ai` to annotate reusable configs and handlers.
176
- Model instances must implement decision model specification `v4`, the version AI SDK 7 supports;
177
- a matching `provider`, `modelId`, and `specificationVersion` alone is not an implementation.
178
- If the installed `ai` package does not export a decision API, `decide` throws an error naming the
179
- missing export. Input and answer validation, retries, and provider errors follow AI SDK semantics.
138
+ `decide` accepts `model`, `state`, `questions`, `maxRetries`, and `signal`; pass `signal: ctx.abortSignal` to cancel with the tool call. Import `DecisionModel`, `DecisionState`, `DecisionStatePart`, `DecisionInput`, `DecisionQuestion`, `DecisionAnswer`, `DecisionOptions`, and `DecisionResult` from `eve/ai` to type reusable configs and handlers.
180
139
 
181
- You can also call `decide` outside a tool; it does not require an active eve
182
- session. Each call performs its own decision. `auto` uses this function
183
- and adds the per-turn routing behavior described below.
140
+ A model instance must implement decision model specification `v4`, the version AI SDK 7 supports. A matching `provider`, `modelId`, and `specificationVersion` alone is not enough. If the installed `ai` package does not export a decision API, `decide` throws an error that names the missing export. Validation, retries, and provider errors follow AI SDK semantics.
141
+
142
+ `decide` also works outside a tool and doesn't need an active eve session.
184
143
 
185
144
  ## Judge eval results
186
145
 
187
- Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses this same `decide` implementation and default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
146
+ Eval authors can use `t.judge(...)` to turn decision answers into scored assertions, including batches of questions sharing one state. It uses `decide` and its default model. See [Judge](../evals/judge) for criteria, rubrics, and thresholds.
188
147
 
189
148
  ## Decide tool approvals
190
149
 
191
- Use `auto({ model? })` when a decision model should decide whether a
192
- tool call can run automatically or needs human approval. It accepts the same
193
- AI SDK decision model strings and provider instances described above and
194
- defaults to `typesafe-ai/jev`:
150
+ `auto({ model? })` from `eve/tools/approval` lets a decision model decide whether a tool call runs automatically or needs human approval. It accepts the same decision model strings and provider instances and defaults to `typesafe-ai/jev`:
195
151
 
196
152
  ```ts title="agent/tools/deploy.ts"
197
153
  import { defineTool } from "eve/tools";
@@ -206,8 +162,7 @@ export default defineTool({
206
162
  });
207
163
  ```
208
164
 
209
- The decision model reviews the tool name and input for dangerous effects. A
210
- caution, failed review, or incomplete input requires human approval. See
165
+ The decision model reviews the tool name and input for dangerous effects. A caution, failed review, or incomplete input requires human approval. See
211
166
  [Human-in-the-loop approvals](/docs/human-in-the-loop#approvals) for classifier
212
167
  options and data handling, and the
213
168
  [Auto-approve tool calls with Jev](https://vercel.com/kb/guide/auto-approve-tool-calls-eve-jev)
@@ -215,18 +170,8 @@ guide for an end-to-end walkthrough.
215
170
 
216
171
  ## Runtime behavior
217
172
 
218
- `auto` decides before the first model call of each turn, after the incoming
219
- prompt is available and before the selected language model runs. eve keeps the
220
- choice in the session and reuses it for the turn's later model calls, including
221
- in a fresh process, without deciding again. A new turn makes a new choice, and
222
- child sessions route from their own prompts.
223
-
224
- The decider receives up to eight recent user and assistant text messages,
225
- capped at 16,000 characters. Requests without user text and latest messages over
226
- the limit fail before provider I/O.
227
-
228
- Decision validation, retries, provider errors, and model resolution follow AI
229
- SDK semantics. Without `fallback`, a decider error fails the turn. With
230
- `fallback`, eve uses and retains that model for the rest of the turn. Cancelling
231
- the active turn aborts decision and prevents a routed or fallback choice from
232
- being retained.
173
+ `auto` decides once per turn, before the first model call. The choice holds for the turn's later model calls, including in a fresh process. A new turn makes a new choice, and child sessions route from their own prompts.
174
+
175
+ The decider receives up to eight recent user and assistant text messages, capped at 16,000 characters. A request without user text, or with a latest message over the limit, fails before provider I/O.
176
+
177
+ Without `fallback`, a decider error fails the turn; with it, eve uses the fallback model for the rest of the turn. Cancelling the turn aborts the decision and keeps no routed or fallback choice. Validation, retries, provider errors, and model resolution follow AI SDK semantics.
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "title": "Deployment",
3
3
  "defaultOpen": false,
4
- "pages": ["overview", "vercel", "self-hosting"]
4
+ "pages": ["overview", "vercel", "self-hosting", "workflow-worlds", "self-hosted-operations"]
5
5
  }
@@ -1,40 +1,51 @@
1
1
  ---
2
2
  title: "Overview"
3
- description: "Choose a deployment strategy and prepare an eve agent for production."
3
+ description: "How an eve agent runs in production, and the backends you choose on Vercel or your own infrastructure."
4
4
  ---
5
5
 
6
- Deploy eve to Vercel or run it as a Node service on your own infrastructure. Your deployment strategy determines the build output, workflow storage, sandbox provider, and routing. The agent’s filesystem-based configuration remains portable across these strategies.
6
+ Deploy eve to Vercel or run it as a Node service on your own infrastructure. Both targets run on the open-source [Workflow SDK](https://workflow-sdk.dev/), so conversations, approvals, and subagent work survive restarts and long waits. The agent directory stays the same on every target.
7
7
 
8
- ## Choose a deployment strategy
8
+ ## Choose a deployment target
9
9
 
10
- Choose where the eve runtime will run:
10
+ | Target | Build output | Choose it when |
11
+ | ------------------------------ | ---------------------- | --------------------------------------------------------------- |
12
+ | [Vercel](./vercel) | `.vercel/output` | You want Vercel to operate the runtime services |
13
+ | [Self-hosting](./self-hosting) | `.output/` Node server | You run Node services on your own servers or container platform |
11
14
 
12
- | Strategy | Build output | Workflows | Sandbox | Choose it when |
13
- | ------------------------------ | ---------------------- | ------------------------------ | ---------------- | ----------------------------------------------------- |
14
- | [Vercel](./vercel) | `.vercel/output` | Vercel Workflow | Vercel Sandbox | You want Vercel to operate the runtime services |
15
- | [Self-hosting](./self-hosting) | `.output/` Node server | Local or custom Workflow world | Docker or custom | You operate your own Node or container infrastructure |
15
+ You can also deploy eve beside a Next.js, Nuxt, SvelteKit, or TanStack Start application that routes browser requests to the agent. See [Frontend integrations](../frontend/overview).
16
16
 
17
- eve is frontend agnostic and can be deployed within Next.js, Nuxt, SvelteKit, or TanStack Start applications. See [Frontend integrations](../frontend/overview) for more details.
17
+ ## Backends
18
+
19
+ The eve server hands storage, isolation, model access, scheduling, and tracing to backends. Each deployment target picks a default for every backend, so a new agent deploys without backend configuration.
20
+
21
+ | Backend | What it does | On Vercel | Self-hosted |
22
+ | ---------------- | ------------------------------------------------------------------- | -------------------------------------------- | -------------------------------------------------------------- |
23
+ | Workflow world | Stores sessions, queues their work, and resumes them after restarts | Vercel Workflow | [Local, Postgres, or another world package](./workflow-worlds) |
24
+ | Sandbox provider | Runs the `bash`, `read_file`, and `write_file` tools | Vercel Sandbox | Docker by default, or another [provider](../../sandbox) |
25
+ | Model access | Sends model calls | AI Gateway via OIDC | AI Gateway API key or an AI SDK provider package |
26
+ | Schedules | Runs authored [schedules](../../schedules) | Vercel Cron | The schedule runner in `eve start` |
27
+ | Observability | Records traces of sessions, turns, and tool calls | [Agent Runs](../../observability/agent-runs) | [OpenTelemetry](../../observability/otel) |
28
+
29
+ Self-hosted defaults store workflow state on disk, and run sandboxes in Docker when Docker is available during the build. See [Self-host eve](./self-hosting) for the persistent storage and sandbox setup your host must provide.
18
30
 
19
31
  ## Prepare for production
20
32
 
21
- Every production deployment must satisfy the same runtime requirements:
33
+ Every production deployment needs these steps:
22
34
 
23
35
  1. Run `eve build` to compile the agent and create host output.
24
36
  2. Provide a model credential and any secrets required by tools, connections, and route authentication.
25
37
  3. Replace `placeholderAuth()` with a production route policy before accepting browser traffic.
26
- 4. Select workflow and sandbox implementations that match the host.
27
- 5. Verify the health route and complete a real agent turn.
38
+ 4. Verify the health route and complete a real agent turn.
28
39
 
29
- `eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the standard Nitro server under `.output/`.
40
+ `eve build` always writes compiler artifacts under `.eve/`. A Vercel build also writes `.vercel/output`. A build for another host writes the eve server under `.output/`.
30
41
 
31
42
  ## Configure credentials
32
43
 
33
- Keep credentials in your deployment environment or secret manager. Don’t include them in source or compiled artifacts.
44
+ Keep credentials in your deployment environment or secret manager, not in source or compiled artifacts.
34
45
 
35
46
  Your model configuration determines the required credential. A string model ID uses the [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) and requires Vercel project OpenID Connect (OIDC) or `AI_GATEWAY_API_KEY`. A provider-authored model uses that provider’s package and API key. See [Agent configuration](../../agent-config#set-the-model) for both forms.
36
47
 
37
- Configure production route authentication separately from model access. The default policy rejects browser traffic in production. See [Authentication](../auth-and-route-protection) for the available policies and secret requirements.
48
+ Route authentication is separate from model access. The default policy rejects browser traffic in production. See [Authentication](../auth-and-route-protection) for the available policies and secret requirements.
38
49
 
39
50
  ## Verify the deployment
40
51
 
@@ -54,8 +65,6 @@ Set `VERCEL_AUTOMATION_BYPASS_SECRET` locally first if a Vercel deployment uses
54
65
 
55
66
  ## Continue with a platform guide
56
67
 
57
- Follow the guide for your deployment platform or application topology:
58
-
59
68
  - [Deploy to Vercel](./vercel): use Vercel Build Output, Workflow, Sandbox, Cron, and observability
60
- - [Self-host eve](./self-hosting): run the Nitro Node server with infrastructure you manage
69
+ - [Self-host eve](./self-hosting): run the eve server on Node with backends you choose
61
70
  - [Frontend integrations](../frontend/overview): mount eve alongside Next.js, Nuxt, SvelteKit, or TanStack Start