eve 0.85.0 → 0.87.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 (290) hide show
  1. package/CHANGELOG.md +34 -3073
  2. package/README.md +7 -4
  3. package/dist/src/acp/adapter.d.ts +2 -26
  4. package/dist/src/acp/adapter.js +1 -1
  5. package/dist/src/acp/server.d.ts +0 -3
  6. package/dist/src/ai/decision-adapter.d.ts +5 -3
  7. package/dist/src/ai/decision-adapter.js +1 -1
  8. package/dist/src/ai/decision-types.d.ts +4 -3
  9. package/dist/src/channel/adapter.d.ts +0 -14
  10. package/dist/src/channel/auth/definitions.d.ts +0 -4
  11. package/dist/src/channel/channel-address.d.ts +1 -1
  12. package/dist/src/channel/channel-address.js +1 -1
  13. package/dist/src/channel/channel-operations.d.ts +2 -2
  14. package/dist/src/channel/channel-operations.js +1 -1
  15. package/dist/src/channel/prompt-queue.d.ts +0 -2
  16. package/dist/src/channel/session-not-active-error.d.ts +10 -5
  17. package/dist/src/channel/session-not-active-error.js +1 -1
  18. package/dist/src/channel/session-stranded-error.d.ts +1 -1
  19. package/dist/src/channel/session.d.ts +3 -4
  20. package/dist/src/channel/session.js +1 -1
  21. package/dist/src/channel/types.d.ts +5 -14
  22. package/dist/src/chunks/{use-eve-agent-B2jCfcnG.js → use-eve-agent-BExXjBv6.js} +82 -72
  23. package/dist/src/chunks/{use-eve-agent-DCLFi26P.js → use-eve-agent-C0KHCyb9.js} +82 -72
  24. package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
  25. package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
  26. package/dist/src/cli/dev/command-options.d.ts +4 -4
  27. package/dist/src/cli/dev/command.js +1 -1
  28. package/dist/src/cli/dev/tui/runner.d.ts +1 -1
  29. package/dist/src/cli/dev/tui/runner.js +2 -2
  30. package/dist/src/cli/dev/tui/test/fake-eve-server.js +1 -1
  31. package/dist/src/cli/dev/tui/tool-format.d.ts +2 -2
  32. package/dist/src/cli/dev/ui-options.d.ts +4 -4
  33. package/dist/src/cli/dev/ui-options.js +1 -1
  34. package/dist/src/cli/run.js +1 -1
  35. package/dist/src/client/agent-info-error.d.ts +4 -1
  36. package/dist/src/client/agent-info-error.js +1 -1
  37. package/dist/src/client/agent-session.d.ts +1 -4
  38. package/dist/src/client/agent-session.js +1 -1
  39. package/dist/src/client/agent-stream-follower.js +1 -1
  40. package/dist/src/client/client-error.d.ts +13 -4
  41. package/dist/src/client/client-error.js +1 -1
  42. package/dist/src/client/delivery.d.ts +2 -17
  43. package/dist/src/client/health-response-error.d.ts +4 -1
  44. package/dist/src/client/health-response-error.js +1 -1
  45. package/dist/src/client/index.d.ts +5 -3
  46. package/dist/src/client/index.js +1 -1
  47. package/dist/src/client/open-stream.d.ts +7 -12
  48. package/dist/src/client/open-stream.js +1 -1
  49. package/dist/src/client/session-controls.d.ts +2 -2
  50. package/dist/src/client/session-controls.js +1 -1
  51. package/dist/src/client/session-event-stream.d.ts +2 -2
  52. package/dist/src/client/session-event-stream.js +1 -1
  53. package/dist/src/client/session-store.d.ts +2 -6
  54. package/dist/src/client/session-store.js +1 -1
  55. package/dist/src/client/session.d.ts +4 -13
  56. package/dist/src/client/session.js +1 -1
  57. package/dist/src/client/sessions.d.ts +3 -6
  58. package/dist/src/client/types.d.ts +23 -32
  59. package/dist/src/compiled/.vendor-stamp.json +4 -4
  60. package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
  61. package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
  62. package/dist/src/compiled/@vercel/schedules/index.js +2 -2
  63. package/dist/src/compiler/manifest.js +1 -1
  64. package/dist/src/compiler/normalize-agent-config.js +1 -1
  65. package/dist/src/compiler/normalize-connection.d.ts +1 -1
  66. package/dist/src/compiler/normalize-connection.js +1 -1
  67. package/dist/src/compiler/normalize-instructions.js +1 -1
  68. package/dist/src/compiler/normalize-skill.js +1 -1
  69. package/dist/src/compiler/resolve-workspace-subagent.js +1 -1
  70. package/dist/src/context/memory-tools.d.ts +9 -5
  71. package/dist/src/discover/sandbox.js +1 -1
  72. package/dist/src/dynamic/definition.d.ts +11 -5
  73. package/dist/src/dynamic/definition.js +1 -1
  74. package/dist/src/evals/mock-model.d.ts +1 -1
  75. package/dist/src/evals/session-manager.d.ts +0 -2
  76. package/dist/src/evals/session.d.ts +1 -11
  77. package/dist/src/evals/session.js +1 -1
  78. package/dist/src/eve-channel/index.js +1 -1
  79. package/dist/src/eve-channel/support.js +1 -1
  80. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  81. package/dist/src/execution/effective-agent-config.js +1 -1
  82. package/dist/src/execution/proxied-deliver-step.js +1 -1
  83. package/dist/src/execution/sandbox/bindings/just-bash-runtime.d.ts +1 -2
  84. package/dist/src/execution/sandbox/bindings/just-bash-runtime.js +1 -1
  85. package/dist/src/execution/sandbox/bindings/just-bash.js +1 -1
  86. package/dist/src/execution/session/active-turn.js +1 -1
  87. package/dist/src/execution/session/answer-caller.d.ts +9 -5
  88. package/dist/src/execution/session/answer-caller.js +1 -1
  89. package/dist/src/execution/session/principal.d.ts +8 -0
  90. package/dist/src/execution/session/principal.js +1 -1
  91. package/dist/src/execution/session/program.js +1 -1
  92. package/dist/src/execution/session/turn-step.js +1 -1
  93. package/dist/src/execution/session/turn.js +1 -1
  94. package/dist/src/execution/session-callback-request.js +1 -1
  95. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  96. package/dist/src/harness/attachment-staging.d.ts +2 -2
  97. package/dist/src/harness/attachment-staging.js +1 -1
  98. package/dist/src/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  99. package/dist/src/instrumentation/providers.d.ts +1 -38
  100. package/dist/src/instrumentation/providers.js +1 -1
  101. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  102. package/dist/src/internal/application/package.d.ts +1 -0
  103. package/dist/src/internal/application/package.js +1 -1
  104. package/dist/src/internal/application/stamped-package-version.js +1 -1
  105. package/dist/src/internal/authored-definition/core.js +1 -1
  106. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  107. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  108. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  109. package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
  110. package/dist/src/internal/runtime-model.d.ts +9 -4
  111. package/dist/src/internal/runtime-model.js +1 -1
  112. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  113. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  114. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  115. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  116. package/dist/src/models/auto.js +1 -1
  117. package/dist/src/protocol/delivery.d.ts +1 -0
  118. package/dist/src/protocol/reset-session.d.ts +0 -2
  119. package/dist/src/protocol/routes.d.ts +9 -2
  120. package/dist/src/protocol/routes.js +1 -1
  121. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  122. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  123. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  124. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  125. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  126. package/dist/src/public/channels/github/state.d.ts +0 -2
  127. package/dist/src/public/channels/index.d.ts +1 -2
  128. package/dist/src/public/channels/index.js +1 -1
  129. package/dist/src/public/channels/linear/index.d.ts +1 -1
  130. package/dist/src/public/channels/linear/index.js +1 -1
  131. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  132. package/dist/src/public/channels/linq/index.d.ts +1 -1
  133. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  134. package/dist/src/public/channels/photon/index.d.ts +1 -1
  135. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  136. package/dist/src/public/channels/slack/api.d.ts +1 -1
  137. package/dist/src/public/channels/slack/api.js +1 -1
  138. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  139. package/dist/src/public/channels/slack/blocks.js +2 -2
  140. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  141. package/dist/src/public/channels/slack/cards.js +1 -1
  142. package/dist/src/public/channels/slack/index.d.ts +2 -2
  143. package/dist/src/public/channels/slack/index.js +1 -1
  144. package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
  145. package/dist/src/public/channels/slack/session-operations.js +1 -1
  146. package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
  147. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  148. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  149. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  150. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  151. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  152. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  153. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  154. package/dist/src/public/definitions/agent.d.ts +15 -7
  155. package/dist/src/public/definitions/agent.js +1 -1
  156. package/dist/src/public/definitions/channel.d.ts +7 -5
  157. package/dist/src/public/definitions/channel.js +1 -1
  158. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  159. package/dist/src/public/definitions/connections/protocol.js +1 -1
  160. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  161. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  162. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  163. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  164. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  165. package/dist/src/public/experimental/workspace/index.js +1 -0
  166. package/dist/src/public/index.d.ts +2 -2
  167. package/dist/src/public/index.js +1 -1
  168. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  169. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  170. package/dist/src/public/instrumentation/provider.js +1 -1
  171. package/dist/src/public/memory/file/backend.d.ts +1 -1
  172. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  173. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  174. package/dist/src/public/memory/file/provider.js +1 -1
  175. package/dist/src/public/memory/index.d.ts +3 -11
  176. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  177. package/dist/src/public/models/index.d.ts +1 -0
  178. package/dist/src/public/models/openai/index.d.ts +2 -2
  179. package/dist/src/public/next/index.d.ts +2 -2
  180. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  181. package/dist/src/public/sandbox/just-bash.d.ts +0 -1
  182. package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
  183. package/dist/src/public/schedules/providers/vercel.js +1 -1
  184. package/dist/src/public/sessions/index.d.ts +1 -0
  185. package/dist/src/public/sessions/index.js +1 -1
  186. package/dist/src/public/tools/index.d.ts +1 -1
  187. package/dist/src/public/tools/index.js +1 -1
  188. package/dist/src/public/workflow/api.d.ts +25 -0
  189. package/dist/src/public/workflow/api.js +1 -0
  190. package/dist/src/public/workflow/index.d.ts +76 -0
  191. package/dist/src/public/workflow/index.js +1 -0
  192. package/dist/src/public/workflow-modules.d.ts +2 -17
  193. package/dist/src/react/use-eve-agent.d.ts +3 -2
  194. package/dist/src/react/use-eve-agent.js +1 -1
  195. package/dist/src/reactions/kinds/model.js +1 -1
  196. package/dist/src/runtime/agent/resolve-model.js +1 -1
  197. package/dist/src/runtime/resolve-agent.js +1 -1
  198. package/dist/src/runtime/resolve-dynamic.js +1 -1
  199. package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
  200. package/dist/src/runtime/subagents/workflow.js +1 -1
  201. package/dist/src/sandbox/providers/default.js +1 -1
  202. package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
  203. package/dist/src/self-modification/sandbox.js +1 -1
  204. package/dist/src/setup/integrations/discord/daemon.js +2 -2
  205. package/dist/src/setup/scaffold/create/project.js +2 -2
  206. package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
  207. package/dist/src/setup/scaffold/create/web-template.js +2 -2
  208. package/dist/src/setup/verified-remote-agent.d.ts +1 -3
  209. package/dist/src/shared/agent-definition.d.ts +18 -9
  210. package/dist/src/shared/eve-error.d.ts +22 -0
  211. package/dist/src/shared/eve-error.js +1 -0
  212. package/dist/src/shared/session.d.ts +2 -2
  213. package/dist/src/shared/token-usage.d.ts +7 -1
  214. package/dist/src/svelte/index.js +1 -1
  215. package/dist/src/svelte/use-eve-agent.d.ts +2 -1
  216. package/dist/src/svelte/use-eve-agent.js +1 -1
  217. package/dist/src/tools/definition.d.ts +7 -5
  218. package/dist/src/tools/definition.js +1 -1
  219. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  220. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  221. package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
  222. package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
  223. package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
  224. package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
  225. package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
  226. package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
  227. package/dist/src/tracing/local/traces.d.ts +0 -13
  228. package/dist/src/vue/index.js +1 -1
  229. package/dist/src/vue/use-eve-agent.d.ts +3 -2
  230. package/dist/src/vue/use-eve-agent.js +1 -1
  231. package/docs/agent-config.md +15 -11
  232. package/docs/channels/custom.mdx +26 -10
  233. package/docs/channels/discord.mdx +10 -10
  234. package/docs/channels/eve.mdx +15 -13
  235. package/docs/channels/linear.mdx +11 -0
  236. package/docs/channels/linq.mdx +5 -1
  237. package/docs/channels/photon.mdx +6 -1
  238. package/docs/channels/slack.mdx +73 -14
  239. package/docs/channels/telegram.mdx +6 -0
  240. package/docs/code-extension.mdx +25 -0
  241. package/docs/concepts/default-harness.md +2 -2
  242. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  243. package/docs/concepts/project-structure.mdx +1 -1
  244. package/docs/concepts/security-model.md +6 -2
  245. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  246. package/docs/concepts/upgrade-to-v27-events.md +70 -1
  247. package/docs/connections/overview.mdx +4 -0
  248. package/docs/evals/reporters.mdx +21 -0
  249. package/docs/extensions.md +12 -0
  250. package/docs/getting-started.mdx +6 -0
  251. package/docs/guides/auth-and-route-protection.md +2 -1
  252. package/docs/guides/client/continuations.mdx +12 -10
  253. package/docs/guides/client/messages.mdx +24 -1
  254. package/docs/guides/client/overview.mdx +8 -6
  255. package/docs/guides/client/streaming.mdx +25 -7
  256. package/docs/guides/decide.md +3 -3
  257. package/docs/guides/deployment/self-hosting.md +1 -1
  258. package/docs/guides/deployment/vercel.mdx +1 -1
  259. package/docs/guides/dev-tui.md +2 -2
  260. package/docs/guides/frontend/meta.json +1 -0
  261. package/docs/guides/frontend/nextjs.mdx +329 -121
  262. package/docs/guides/frontend/overview.mdx +115 -335
  263. package/docs/guides/frontend/tanstack.mdx +1 -1
  264. package/docs/guides/frontend/use-eve-agent-svelte.mdx +18 -16
  265. package/docs/guides/frontend/use-eve-agent-vue.mdx +18 -16
  266. package/docs/guides/frontend/use-eve-agent.mdx +385 -0
  267. package/docs/guides/hooks.md +1 -1
  268. package/docs/guides/instrumentation/otel.mdx +3 -1
  269. package/docs/guides/prepare-for-1-0.md +255 -0
  270. package/docs/guides/remote-agents.md +26 -22
  271. package/docs/guides/self-modification.md +6 -0
  272. package/docs/instructions.mdx +1 -1
  273. package/docs/memory/custom-provider.md +1 -1
  274. package/docs/memory/file.md +11 -2
  275. package/docs/meta.json +1 -0
  276. package/docs/reference/agent-files.md +17 -17
  277. package/docs/reference/cli.md +15 -11
  278. package/docs/reference/typescript-api.md +46 -20
  279. package/docs/sandbox/custom-providers.mdx +2 -0
  280. package/docs/sandbox/default.mdx +6 -6
  281. package/docs/sandbox/index.mdx +6 -6
  282. package/docs/sandbox/just-bash.mdx +30 -21
  283. package/docs/subagents/index.mdx +4 -4
  284. package/docs/tools/human-in-the-loop.md +1 -1
  285. package/docs/tools/workflows.mdx +52 -8
  286. package/docs/tutorial/first-agent.mdx +1 -1
  287. package/package.json +46 -27
  288. package/dist/src/public/channels/discord/gateway/index.js +0 -1
  289. package/dist/src/self-modification/agent.d.ts +0 -12
  290. package/dist/src/self-modification/agent.js +0 -1
@@ -32,8 +32,11 @@ A session completes after 30 idle days by default; configure
32
32
  timeout. The idle window restarts each time a turn settles, and a session never
33
33
  expires while a turn is open. At expiration, eve emits `session.ended` with `outcome: "completed"` and
34
34
  releases the session's continuation addresses so the next qualifying channel
35
- message starts fresh. Stored session data is not deleted. See
36
- [Agent config](../agent-config#runtime-limits).
35
+ message starts fresh. Stored data follows the session's
36
+ [run-data retention policy](../agent-config#run-data-retention). Under the default
37
+ policy outside development, eve requests deletion when private and unknown-audience
38
+ sessions end. The Workflow World must support deletion to enforce it. See
39
+ [Agent config](../agent-config#runtime-limits) for timeout settings.
37
40
 
38
41
  React, Vue, and Svelte apps reach for [`useEveAgent()`](../guides/frontend/overview) instead of calling these routes by hand. Next.js and Nuxt apps can proxy them to the eve runtime from the same origin.
39
42
 
@@ -115,6 +118,13 @@ The full catalog, its outcome sets, and TypeScript types are exported from `eve/
115
118
  import { FACT_CATALOG, foldEvents, activeTurn, reply } from "eve/events";
116
119
  ```
117
120
 
121
+ The family-specific arrays `SESSION_OUTCOMES`, `DELIVERY_OUTCOMES`, `TURN_OUTCOMES`,
122
+ `MODEL_OUTCOMES`, `CALL_OUTCOMES`, `TASK_OUTCOMES`, `INTERACTION_OUTCOMES`,
123
+ `RESPONSE_OUTCOMES`, and `CONTEXT_OUTCOMES` list the outcomes known to this release.
124
+ `TERMINAL_OUTCOMES` maps terminal fact types to those arrays. `isTerminal(fact)`
125
+ narrows a fact to one that ends its entity; it does not test whether the whole
126
+ session has ended. These helpers come from `eve/events`.
127
+
118
128
  #### What a later release can add
119
129
 
120
130
  Within stream version 27, a later minor release can add:
@@ -152,7 +162,7 @@ Spend is recorded on `usage.recorded`, once per model run (`owner: { runId }`) a
152
162
 
153
163
  ### Deliveries and responses
154
164
 
155
- Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `reset`, or a sign-in callback. `delivery.admitted` records it, with the sender's `principal` and its `source`. A message that a turn takes in is `delivery.consumed`, with the `parts` it received: text, plus file metadata without raw bytes or internal sandbox paths. A delivery that brought [prior history](../channels/eve#start-from-prior-history) also carries it there, in `history`. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
165
+ Everything that reaches a session arrives as a delivery: a message, an answer, a control such as `cancel` or `end`, or a sign-in callback. `delivery.admitted` records it, with the sender's `principal` and its `source`. A message that a turn takes in is `delivery.consumed`, with the `parts` it received: text, plus file metadata without raw bytes or internal sandbox paths. A delivery that brought [prior history](../channels/eve#start-from-prior-history) also carries it there, in `history`. Every delivery ends with exactly one `delivery.settled`, except after a degraded termination (see below):
156
166
 
157
167
  | Outcome | Meaning |
158
168
  | ---------------- | --------------------------------------------------------------------------------------------------- |
@@ -165,8 +175,9 @@ Everything that reaches a session arrives as a delivery: a message, an answer, a
165
175
 
166
176
  `POST /eve/v1/session/:sessionId` returns the message's `deliveryId`, so a client resuming from an old cursor knows which `delivery.settled` ends its response. Steering and coalesced messages each keep their own delivery. The id is assigned before dispatch,
167
177
  not derived from stream position. An answer-only delivery stops on its own `delivery.settled`.
168
- A stranded reset records its control's admission and settlement before ending the session, with
169
- `session.ended.data.cause.deliveryId` naming the reset.
178
+ Ending a stranded session records the control's admission and settlement, with
179
+ `session.ended.data.cause.deliveryId` naming that delivery. Its stream control value
180
+ remains `"reset"` for compatibility with recorded history.
170
181
  An answer and message sent together by someone other than the turn's caller become separate deliveries: the answer reaches the waiting turn, and the message retains the receipt and waits. Follow the answer through its interaction.
171
182
 
172
183
  To follow an accepted receipt in a client view, use `delivery(view, receipt.deliveryId)` from
@@ -232,6 +243,8 @@ const observed = call(agent.view, callId);
232
243
  if (observed?.state === "failed") console.error(observed.error.message);
233
244
  ```
234
245
 
246
+ `callOutputSource(view, callId)` returns the observation of the call that produced a call's output. `call(view, callId)?.output` already follows `outputOf`, so use `callOutputSource` when you need the producing call itself, such as its `callId` or label.
247
+
235
248
  Calls include their resolved `turnId`, `runId`, and `taskId` when known, so applications do not
236
249
  join calls to runs to find their turn. `turns`, `deliveries`, `tasks`, `runs`, `parts`, and
237
250
  `children` return curated observations. Identity lookups include `turn`,
@@ -362,14 +375,14 @@ Custom channel routes request the same cancellation through
362
375
  `from(address).cancel()` or `attachSession(sessionId).cancel()`. See
363
376
  [custom channels](../channels/custom#channel-operations-and-session-handles).
364
377
 
365
- ## Compact, clear, and reset
378
+ ## Compact, clear, and end
366
379
 
367
380
  All session controls are ID-addressed and accept no continuation token:
368
381
 
369
382
  ```bash
370
383
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/compact
371
384
  curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/clear
372
- curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/reset \
385
+ curl -X POST http://127.0.0.1:2000/eve/v1/session/<sessionId>/end \
373
386
  -H 'content-type: application/json' \
374
387
  -d '{"reason":"Start over"}'
375
388
  ```
@@ -380,9 +393,9 @@ Clear removes model-message history in place, including static and dynamic user-
380
393
 
381
394
  A cancel stops turns, not a compaction or clear: one that arrives while either runs settles `ignored`, and the change finishes. A cancel, clear, or compact sent to a prewarmed session before its first message has nothing to act on, and settles `ignored` once the session starts.
382
395
 
383
- Reset terminally retires the exact session ID. A reset ID never becomes a new session; create another session explicitly for a fresh conversation. All controls return delivery receipts when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
396
+ End terminally retires the exact session ID. An ended ID never becomes a new session; create another session explicitly for a fresh conversation. All controls return delivery receipts when accepted. An inactive target throws `SessionNotActiveError` from a handle or returns `409 session_not_active` over HTTP.
384
397
 
385
- A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. Reset still works: eve retires the stranded workflow run and returns its delivery. Its settlement follows retirement and address release. Clear and compact cannot repair a stranded owner; use reset instead.
398
+ A [stranded session](./execution-model-and-durability#stranded-sessions) cannot run commands. End still works: eve retires the stranded workflow run and returns its delivery. Its settlement follows retirement and address release. Clear and compact cannot repair a stranded owner; use end instead.
386
399
 
387
400
  ## Reconnect and rewind
388
401
 
@@ -431,7 +444,7 @@ for await (const event of events) {
431
444
  }
432
445
  ```
433
446
 
434
- `stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `streamReconnectPolicy`. Key stored events on [`meta.position`](#positions), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
447
+ `stream()` takes `SessionStreamOptions` from `eve/sessions`: `startIndex` (a durable line position, with negative values counting back from the tail), `follow`, and `signal`. Client readers also accept `reconnect: false` or a `ReconnectOptions` object from `eve/client`. Key stored events on [`meta.position`](#positions), which stays stable across reads. With `follow: false`, the read ends at the durable tail observed when it opens; otherwise it keeps following new events until the stream closes or the signal aborts.
435
448
 
436
449
  A read reflects events that are already durable. A hook runs after its line is written, so a bounded read there includes the event that triggered it. `sessions` reads any session ID without channel auth, so check that a caller may read a session before passing an ID from a request. It is available only in code that runs inside the eve server.
437
450
 
@@ -10,6 +10,7 @@ This guide covers breaking changes to agent definitions, approvals, channels, cl
10
10
  - Rebuild and republish installed extensions. Earlier epoch-based distributions cannot be loaded by this release; see [Extensions](../extensions).
11
11
  - Keep the deployments that own existing sessions available. A session whose deployment runs eve 0.69 through 0.83 moves to this release the next time it receives a message while idle, or earlier when a channel prepares it for the next message. A session that has a background task, including an idle resumable one, stays on the deployment that owns it until the task finishes, and a session whose deployment runs an earlier release stays there. When a session moves, eve compacts its earlier conversation, so the model continues from a summary while the stored transcript stays intact. The session also starts over on remembered tool approvals and usage limits. On worlds without deployment routing, follow the [stranded-session recovery guidance](./execution-model-and-durability#stranded-sessions).
12
12
  - Update event consumers, frontend persistence, and custom channel handlers using the mappings below. See [Sessions, runs & streaming](./sessions-runs-and-streaming) for the current stream contract.
13
+ - If your application saves session history, follows streams itself, or derives outcomes from events, plan that work with [Migrate application-owned state](#migrate-application-owned-state).
13
14
 
14
15
  ## Restore saved history
15
16
 
@@ -30,6 +31,17 @@ Save the converted events with their metadata unchanged and pass them as `Sessio
30
31
 
31
32
  A session saved mid-turn stays unfinished. Convert each session separately: the function throws for an array that doesn't start at `session.started`, that holds a second session, or that holds current events. `convertLegacyEvents` is a migration aid with no compatibility promise and will be removed in a later release.
32
33
 
34
+ Saved records often hold more than one stream's worth of history. Before you hydrate or convert:
35
+
36
+ - **Select one session.** A chat record can hold several sessions, for example after a chat moves to a new session or a fork copies its parent's history. Pass only the current session's events, from its `session.started`, to `initialEvents` or `convertLegacyEvents`.
37
+ - **Split mixed prefixes.** A record written across the upgrade can hold v26 events followed by v27 events. If its stream has expired, convert only the v26 prefix and keep the later v27 events and their metadata unchanged.
38
+ - **Don't convert folded caches.** Message lists produced by v26 reducers aren't raw events. Re-read the stream, or render those caches as read-only records.
39
+ - **End computed cursors at a complete line.** An event with `meta.endOfLine: false` has more events in the same line. If you compute a cursor yourself, stop at the last complete line.
40
+ - **Treat missing data as unknown.** A partial read must not overwrite a fuller archive, and an expired stream must not replace saved history with an empty one. A child session you can no longer read hasn't necessarily completed.
41
+ - **Guard concurrent writes.** Browser saves, server catch-up reads, and background capture can race. Bind each write to its session, reject a cursor that moves backward, and track each child session's progress separately from its parent's.
42
+ - **Keep copied history inert.** Interactions in a fork, shared copy, or historical transcript belong to the original session. Render them read-only, not as live approval or sign-in controls.
43
+ - **Qualify IDs with the session.** Turn and message IDs aren't unique across sessions. When one record holds several sessions, include the session ID in keys for derived UI state.
44
+
33
45
  ## Event mapping
34
46
 
35
47
  | v26 | v27 |
@@ -108,7 +120,7 @@ export default defineHook({
108
120
 
109
121
  **Instrumentation** uses `session.ended`, `turn.settled`, `call.requested`/`call.settled`, and `interaction.opened`/`interaction.settled`, with terminal `outcome` instead of separate success/failure event names. `channel.delivery.*` becomes `delivery.consumed`/`delivery.settled`; `step.attempt.*` becomes `model.started`/`model.retried`/`model.settled`. See [Instrumentation](/docs/observability/instrumentation#lifecycle-events).
110
122
 
111
- **Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `reset()` retires the server session. Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
123
+ **Clients** receive a `Delivery` immediately on acceptance. Use `delivery.result()` for its settlement or `delivery.stream()` for its events; each read is independent and can take a read signal. `result().status` describes the request (`completed`, `awaiting-input`, `failed`, `cancelled`), not session termination: check `sessionEnded` separately. Results no longer include an `events` array. Frontend hooks expose `view`, `messages`, `agents`, `events`, `session`, `status`, and `error` directly, not under `data`. `newSession()` clears local state; `end()` retires the server session (renamed from `reset()`). Persist events and cursor as they change so paused turns survive reloads. See [Client streaming](../guides/client/streaming) and [Frontend](../guides/frontend/overview).
112
124
 
113
125
  **Evals** match v27 facts and use `view` queries. Rename `loadedSkill` to `calledSkill`, `calledSubagent` to `calledAgent`, `noFailedActions` to `noFailedCalls`, and `parked()` to `awaitingInput()`. Use `t.target.attach(id)` instead of `attachSession(id)` and `turn.waitForToolCall()` instead of the old action matcher. See [Evals](../evals/overview).
114
126
 
@@ -122,7 +134,64 @@ export default defineHook({
122
134
  - Replace connection auth's `credentialOwner` with `principalType: "app" | "user"`. With `getToken` alone, omitted ownership defaults to `"app"`; set `"user"` for per-user tokens. See [connection credential ownership](/docs/connections#choose-app-vs-user-auth).
123
135
  - Dynamic capabilities use `defineDynamic(ctx => value)`, not lifecycle event maps. Replace `defineDurableCallback` and `defineDurableSchema` wrappers with ordinary functions and schemas; put external JSON observations in `ctx.memo(key, fn)`. See [Dynamic capabilities](../guides/dynamic-capabilities).
124
136
  - Recalled memory stays outside durable conversation history and is recalled before turns, not during compaction. Remove memory `visibility` options; a failed memory capture now prevents compaction. See [Memory providers](../memory/custom-provider).
137
+ - Memory document backend `read()` and `write()` inputs use `signal` again, restoring the pre-`0.84.0` contract. Backends written for `0.83.x` or earlier need no change; replace `abortSignal` only in backends and calls written for `0.84.x`. Memory and tool execution contexts keep `ctx.abortSignal`. See [Custom backends](../memory/file#custom-backend).
125
138
  - `grep` lists matching files by default. Set `outputMode: "content"` when the caller needs matching lines; see [Built-in tools](./built-in-tools#grep).
126
139
  - Replace `eve remote invoke` with `eve remote connect --print <prompt>` for one-shot requests. Use `eve/client` for scripted multi-turn sessions and answers; see the [CLI reference](../reference/cli#eve-remote-connect).
127
140
  - MCP's `input_required` now covers sign-ins as well as approvals and questions. Answer non-sign-in interactions using `responses: [{ interactionId, optionId?, text? }]`; complete sign-ins externally. Direct `invokeTool` calls return call-shaped outcomes, not conversational pauses. See [MCP](../channels/mcp).
128
141
  - Remote agent protocol 3 supports relaying interactions. A protocol-3 caller relays a protocol-2 remote agent's approvals, questions, and sign-ins, but a protocol-3 remote agent can't relay them to a protocol-2 caller, so upgrade callers before the remote agents they call. Older peers can still exchange results. See [Upgrading callers and remote agents](../guides/remote-agents#upgrading-callers-and-remote-agents).
142
+
143
+ ## Migrate application-owned state
144
+
145
+ The tables above cover renamed events and APIs. Applications that save history, follow streams, or track lifecycle state themselves also need to decide which of that state they still own.
146
+
147
+ ### Decide what eve owns
148
+
149
+ Let eve own live execution and observation: turn lifecycle, streaming and reconnection, optimistic sends, and interaction state. Use `useEveAgent` or `SessionStore` to follow a session, `view` queries from `eve/events` for lifecycle questions, and `delivery.result()` for a request's outcome.
150
+
151
+ Keep the records eve doesn't hold: saved archives and their cursors, forks and shared copies, feedback, authorization and responder policy, budgets you authored, and ledgers of external effects such as uploads or published changes.
152
+
153
+ - Replace an application-owned lifecycle model as a whole. A second reducer layered on the store becomes another source of truth that can disagree with it.
154
+ - Adapt at the presentation boundary. Map `messages`, `view`, and interaction parts into your existing components instead of rebuilding a lifecycle to feed them.
155
+
156
+ ### Find every consumer
157
+
158
+ A clean typecheck doesn't find every v26 consumer. Code that parses NDJSON or saved JSON with locally declared event types compiles against any `eve` version and ignores facts it doesn't recognize.
159
+
160
+ - Search for v26 event names such as `message.completed`, `action.result`, `actions.requested`, and `authorization.required`, not only for `eve` imports. Include scripts, test helpers, and server routes that proxy streams.
161
+ - Run a recorded v27 stream through each consumer and check its output. A reducer that returns nothing, or a filter that matches nothing, still compiles.
162
+ - Check server code that filters or redacts streamed content before it reaches a browser. A filter keyed on v26 event types passes v27 `content.delta` and `content.completed` events through unchanged.
163
+ - Check consumers in other deployments, such as remote agents and their callers, along with their protocol versions.
164
+
165
+ ### Attribute results to their delivery
166
+
167
+ - Bind each outcome to the delivery that requested it. Use `delivery.result()` or that delivery's own turn, not the session's latest turn or every event after a polling cursor. Otherwise a queued or concurrent turn can claim another turn's output.
168
+ - For a child session that several calls reuse, follow the `child.sent` links from a call to the child delivery it sent, for example with `agentCallActivity(state, callId)` from `eve/client`. Don't count `delivery.consumed` on the child's stream: answers to the child's questions are deliveries too. See [Child agents](../guides/frontend/use-eve-agent#child-agents).
169
+ - Decide approvals from the interaction's `outcome`, not the call's state. Only `accepted` and `declined` record a decision. An approval that settled `withdrawn` or `interrupted`, for example because its turn was cancelled, wasn't approved. See [Interactions](../guides/frontend/use-eve-agent#interactions).
170
+ - Don't identify runs by the shape of their input. A steering message adds a run to the same turn, and a retry reuses its run ID. Use `turn.started` for once-per-turn work, and `runId` with `turnId` when you need a specific run.
171
+ - Treat acceptance as admission, not completion. When an outcome is unconfirmed, read it again instead of resending after a timeout. Use `operationId` for create requests that you retry; see [the eve channel](../channels/eve).
172
+ - Read payloads by their documented shape. `turn.settled.data.reply` lists the reply's part IDs, not its text; use `reply(ctx.view, turnId)` in hooks and channels, or `messages` in the frontend.
173
+
174
+ ### Simplify code eve now owns
175
+
176
+ Application code that mirrors eve's state is usually removable. Measure the result by the state owners you remove, not only by deleted lines.
177
+
178
+ | Usually replaceable | Replacement |
179
+ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ |
180
+ | Custom stream followers, reconnect loops, and optimistic-send state | `useEveAgent` or `SessionStore` |
181
+ | Hook or session state that mirrors turns, calls, tasks, or models | `ctx.view` and selectors from `eve/events` |
182
+ | Folds over raw events for status, replies, timing, usage, or cursors | The queries in [Use eve's answers](../guides/frontend/use-eve-agent#use-eves-answers) |
183
+ | Hand-written finite stream readers and history scanners | `session.stream({ follow: false })` or `session.snapshot()` |
184
+ | Conversions from `Interaction` to a custom request shape and back | Native `Interaction` values and the channel's interaction rendering |
185
+ | Retirement code for Slack approval cards and sign-in messages eve posted | Slack's native settlement. Check each channel's docs before removing code for other cards, such as questions |
186
+ | An explicit `turnPolicy: "steer"` on follow-ups | Omit it: messages steer an open turn by default |
187
+ | Event-keyed dynamic capability maps | `defineDynamic(ctx => value)` |
188
+ | Local v26-to-v27 event translators | `convertLegacyEvents` during migration, or a fresh read from position 0 |
189
+ | Tests that only exercised removed machinery | Delete them with that machinery; keep tests for behavior that remains |
190
+
191
+ Keep code that enforces your application's own contracts: archive storage and cursor guards, effect ledgers and deduplication receipts, authorization and responder checks, budgets you authored, `operationId` retries, and product UI such as composers, branches, and sharing.
192
+
193
+ ### Verify the migration
194
+
195
+ - Build fixtures from real saved history. Record v26 data with the release you're upgrading from, and pass it through a JSON round trip so tests use the shape you actually store.
196
+ - Test history paths explicitly: expired streams, sessions saved mid-turn, forks, records holding several sessions, and caches written across the upgrade.
197
+ - Test interaction endings other than an answer: cancel a turn while an approval is pending, and send a message while a sign-in is pending.
@@ -10,6 +10,10 @@ Connections live under `agent/connections/`. A static connection's runtime name
10
10
 
11
11
  A connection owns its name and every name that starts with `<name>__`, so `linear__list_issues` always means the `linear` connection's `list_issues` tool. The compiler rejects a tool, subagent, or connection whose name is a static connection's name or starts with its `<name>__` prefix. eve applies the same rule to dynamic connections, tools, and subagents when they resolve, except that a dynamic connection with exactly a static connection's name replaces that static connection; see [Naming and conflicts](/docs/guides/dynamic-capabilities#naming-and-conflicts). Both errors name the two sides of the conflict; rename either one.
12
12
 
13
+ Static and dynamic connection definitions must use `defineMcpClientConnection`
14
+ or `defineOpenAPIConnection` from `eve/connections`. Plain object exports are
15
+ rejected because they do not identify a protocol.
16
+
13
17
  ## MCP connections
14
18
 
15
19
  Use an MCP connection when the external service already exposes an MCP server. The server publishes its tools and schemas, and eve makes the matched tools callable by the model. Each tool's JSON Schema reaches the model as published, minus any arguments you supply with `toolCall.providedArguments`, and eve checks the model's arguments against it before it calls the server.
@@ -9,6 +9,27 @@ You are responsible for ensuring any observability or eval provider is approved
9
9
 
10
10
  Reporters attach in two places. Declare them in `evals.config.ts` to observe **every** eval in the run, the usual choice for a shared destination like one Braintrust experiment, so you don't repeat the reporter in each file. Or list them on an individual eval's `reporters` to scope a destination to that eval (or to a group of evals that share one instance).
11
11
 
12
+ ## Console
13
+
14
+ The CLI adds `consoleReporter()` from `eve/evals/reporters` unless you pass
15
+ `--json`. There is no public runner API, so reporters compose only through
16
+ `evals.config.ts` and per-eval `reporters`. A custom console reporter mostly
17
+ makes sense with `--json`, for example logging to stderr so stdout stays valid
18
+ JSON:
19
+
20
+ ```ts title="evals/evals.config.ts"
21
+ import { defineEvalConfig } from "eve/evals";
22
+ import { consoleReporter } from "eve/evals/reporters";
23
+
24
+ export default defineEvalConfig({
25
+ reporters: [consoleReporter({ color: false, log: (line) => console.error(line) })],
26
+ });
27
+ ```
28
+
29
+ Both options are optional; the default logger is `console.log` and color
30
+ follows whether stdout is a terminal. Without `--json`, another console reporter
31
+ duplicates the CLI's output.
32
+
12
33
  ## Braintrust
13
34
 
14
35
  `braintrustReporter(...)` uploads eval results to Braintrust experiments. Put one instance in the config so it covers the whole run:
@@ -340,6 +340,18 @@ Hooks and instruction fragments are additive, so they cannot be replaced. To rep
340
340
 
341
341
  You can also place an override in the corresponding agent-root slot by using the final qualified name. For example, `agent/tools/crm__search.ts` replaces `tools/search.ts` from the extension package or its directory override. Application sources have the highest precedence, so an agent-root override wins when both forms exist.
342
342
 
343
+ ### Computer-use overrides
344
+
345
+ The bundled `eve/extensions/computer-use` extension exports `computer_use` from
346
+ `eve/extensions/computer-use/tools`. Reuse that tool definition in a same-named
347
+ override, as with the [code extension's tools](/docs/code-extension#override-bundled-tools).
348
+
349
+ For a custom sandbox, `eve/extensions/computer-use/sandbox` exports
350
+ `installComputerUse(sandbox)` and `startComputerUse(sandbox)`. Run the installer
351
+ in the environment's preparation callback to install desktop packages and the
352
+ driver; it requires an apt-based image with root or passwordless sudo. Start
353
+ the managed display and driver after opening each session sandbox.
354
+
343
355
  ### Use an extension tool result in a hook
344
356
 
345
357
  To retain an extension tool's result type in a consumer hook, import its definition from `./tools` and pass it to [`toolResultFrom`](/docs/guides/hooks#narrowing-tool-results):
@@ -84,6 +84,12 @@ npm install eve@latest ai zod
84
84
 
85
85
  Declare Node.js 24 in `package.json`, then create `agent/instructions.md` and, when you need runtime configuration, `agent/agent.ts`.
86
86
 
87
+ The installed package's `node_modules/eve/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. For an upgrade across multiple releases, review each version between the installed and target versions in the target version's changelog at `https://raw.githubusercontent.com/vercel/eve/refs/tags/eve%40<version>/packages/eve/CHANGELOG.md`.
88
+
89
+ ## Upgrade an existing project
90
+
91
+ For the coordinated pre-1.0 API cleanup, follow [Prepare for 1.0](./guides/prepare-for-1-0) before updating an existing server, client, or authored agent.
92
+
87
93
  ## Continue with the tutorial
88
94
 
89
95
  The [Tutorial](/docs/tutorial/first-agent) builds a data analytics agent step by step. It adds tools, state, sandboxed analysis, reusable skills, and human approval before deploying the result.
@@ -16,7 +16,7 @@ The route-auth policy lives on the HTTP channel factory (`agent/channels/eve.ts`
16
16
 
17
17
  - `POST /eve/v1/session`
18
18
  - `POST /eve/v1/session/:sessionId`
19
- - `POST /eve/v1/session/:sessionId/{cancel,compact,clear,reset}`
19
+ - `POST /eve/v1/session/:sessionId/{cancel,compact,clear,end}`
20
20
  - `GET /eve/v1/session/:sessionId/stream`
21
21
 
22
22
  These routes are protected by the channel's auth policy. eve fails closed by default: production traffic is rejected unless you configure an authenticator that accepts it, and anonymous access requires an explicit `none()`.
@@ -298,6 +298,7 @@ Inside runtime code, `ctx.session.auth` carries the result of the channel's rout
298
298
  - `auth.current`: the caller on the active inbound turn.
299
299
  - `auth.initiator`: the caller that started the durable session.
300
300
  - A follow-up message updates `auth.current` but leaves `auth.initiator` alone. When a different caller follows up on the same session, `auth.current` tracks the new caller for that turn while `auth.initiator` stays pinned to whoever started it.
301
+ - Within a turn the principal is fixed; only its claims may update. A message from the turn's own principal, including a typed answer to a pending `ctx.ask()` or `ask_question`, joins the turn and updates `auth.current` with its claims. A message from anyone else waits for the turn to end and runs as its own turn. Someone else can still answer a pending request with a button or structured response; that settles the request with them as its responder, and the turn keeps its `auth.current`.
301
302
  - `auth.current` is whatever the channel passed as `auth` when it dispatched the message. Route auth either accepts the request or returns `401`, but a route handler or channel hook can still dispatch with `auth: null`, such as `source.send(message, { auth: null })` or a Slack `onMessage` hook that returns `{ auth: null }`. On a new session, both values are then `null`. On a continuation, `auth.current` is `null` while `auth.initiator` stays pinned to the session's original caller. Internal runtime paths, such as subagents, can also have no caller auth.
302
303
 
303
304
  Use the principal on `auth.current` (or `auth.initiator`) to scope tools, resolve [dynamic capabilities](./dynamic-capabilities) per principal, or enforce tenant boundaries. There's no second per-session ownership ACL stacked on top of route auth. Access is decided at the HTTP boundary, and the durable session carries the caller snapshot forward into your runtime code.
@@ -27,6 +27,8 @@ The state is deliberately small:
27
27
  interface ClientSessionState {
28
28
  sessionId: string;
29
29
  streamIndex: number;
30
+ /** Opaque; persist it and pass it back unchanged. eve may extend it. */
31
+ inbox?: string;
30
32
  }
31
33
  ```
32
34
 
@@ -41,15 +43,14 @@ Attach a fixed handle to the saved ID and restore its cursor:
41
43
  import type { ClientSessionState } from "eve/client";
42
44
 
43
45
  const saved = (await loadSessionState()) as ClientSessionState;
44
- const session = client.sessions.attach(saved.sessionId, {
45
- streamIndex: saved.streamIndex,
46
- });
46
+ const session = client.sessions.attach(saved.sessionId, saved);
47
47
 
48
48
  const response = await session.send("Now shorten it.");
49
49
  console.log((await response.result()).message);
50
50
  ```
51
51
 
52
- `attach()` performs no request. Every later operation targets exactly
52
+ Pass the whole saved state so its optional [`inbox`](./overview#faster-sends-with-inbox) value
53
+ reaches later sends. `attach()` performs no request. Every later operation targets exactly
53
54
  `saved.sessionId`; it never follows or creates a replacement.
54
55
 
55
56
  `send()` correlates its response with the message accepted by the server. If the
@@ -63,14 +64,17 @@ If a configured reconnect limit ends the stream before the accepted turn reaches
63
64
  a boundary, collecting its response throws. A partial stream is not a completed
64
65
  result.
65
66
 
66
- ## Waiting, completed, and reset sessions
67
+ <a id="waiting-completed-and-reset-sessions" />
68
+
69
+ ## Waiting, completed, and ended sessions
67
70
 
68
71
  A session that hasn't ended (`session.ended`) accepts another message through the
69
- same handle. A terminal or reset session does not. Start a fresh conversation
72
+ same handle. An ended session does not. Start a fresh conversation
70
73
  explicitly with another `client.sessions.create(firstTurn)` call.
71
74
 
72
75
  ```ts
73
- const reset = await session.reset({ reason: "Start over" });
76
+ const ended = await session.end({ reason: "Start over" });
77
+ await ended.result();
74
78
  const { session: fresh, delivery } = await client.sessions.create({ message: "Begin again." });
75
79
  ```
76
80
 
@@ -102,9 +106,7 @@ The shared `Client` owns the base URL, auth, headers, and redirect policy. Each
102
106
  read:
103
107
 
104
108
  ```ts
105
- const session = client.sessions.attach(saved.sessionId, {
106
- streamIndex: saved.streamIndex,
107
- });
109
+ const session = client.sessions.attach(saved.sessionId, saved);
108
110
 
109
111
  for await (const event of session.stream()) {
110
112
  console.log(event.type);
@@ -54,13 +54,36 @@ or terminal session throws `SessionNotActiveError` immediately with `retryable:
54
54
  [stranded](../../concepts/execution-model-and-durability#stranded-sessions) session throws
55
55
  `ClientSessionStrandedError`, a `ClientError` with `code: "session_stranded"` and the
56
56
  `eveVersion` that built the session when it recorded one. It is never retried automatically. Call
57
- `session.reset()` and create a new session.
57
+ `session.end()` and create a new session.
58
58
  The client never creates a replacement session. Following or reconnecting to a stranded session's
59
59
  stream reports the same typed error without retrying, including when you were waiting for a
60
60
  response to a message accepted before the upgrade. That accepted message is not redelivered.
61
61
  `session.clear()` throws the same error, because clearing would keep a session that cannot run.
62
62
  `session.stream({ follow: false })` and `session.snapshot()` still read the recorded history.
63
63
 
64
+ The typed errors `eve/client` throws (`ClientError` and its subclasses, `SessionNotActiveError`,
65
+ `HealthResponseError`, and `AgentInfoResponseError`) extend `EveError` and have a stable snake_case
66
+ `code`: `SessionNotActiveError` uses `session_not_active` or `session_not_ready`; `ClientError` carries
67
+ the response's code (such as `session_stranded` or `session_expired`), or `http_error` when the
68
+ response had none. Narrow with the static `is()` of the class you expect instead of `instanceof`,
69
+ so errors from a separately bundled copy of eve still match:
70
+
71
+ ```ts
72
+ import { ClientError, SessionNotActiveError } from "eve/client";
73
+
74
+ try {
75
+ await session.send("Continue.");
76
+ } catch (error) {
77
+ if (SessionNotActiveError.is(error) && !error.retryable) {
78
+ // Start a new session.
79
+ } else if (ClientError.is(error) && error.code === "unauthorized") {
80
+ // Sign in again.
81
+ } else {
82
+ throw error;
83
+ }
84
+ }
85
+ ```
86
+
64
87
  ## Send a full turn payload
65
88
 
66
89
  Pass the full payload to `create()` for the first turn or `send()` for a follow-up:
@@ -113,11 +113,13 @@ await response.result();
113
113
 
114
114
  Per-request headers override client-level values with the same name. For example, a turn can set its application user's `Authorization` header while `vercelOidc` continues to send the deployment-protection credential in `x-vercel-trusted-oidc-idp-token`.
115
115
 
116
- ## Reusing a session inbox
116
+ ## Faster sends with `inbox`
117
117
 
118
118
  Keep the complete `session.state` when saving and restoring a conversation. It can include an
119
- opaque `inbox` handle returned by the server. The client sends this handle with later messages
120
- to avoid another hook lookup. Treat it as transport state: do not inspect or edit it.
119
+ opaque `inbox` value issued by the server. The client sends it back with later messages to avoid
120
+ another hook lookup. Persist it and pass it back unchanged: do
121
+ not inspect, edit, or construct it, because eve may change or extend its contents in any release.
122
+ A missing, stale, or rejected value only costs a slower lookup.
121
123
 
122
124
  Set `EVE_INBOX_HANDLE_SECRET` to the same server-only random secret (at least 32 characters)
123
125
  on the deployments that share sessions. Without this key, handles are neither issued nor used.
@@ -131,7 +133,7 @@ is configured. This change keeps the released SDK dependencies; adopting the SDK
131
133
  enables the optimization. Handles exclude user metadata, live capabilities, and trace carriers,
132
134
  which may contain private server baggage. The signature authenticates a handle; it does not hide its contents.
133
135
 
134
- The server checks that the handle addresses the requested inbox. Workflow still validates the
136
+ The server checks that the handle addresses the requested session's inbox. Workflow still validates the
135
137
  hook, persists the message, and wakes the workflow. A definite stale-owner rejection resolves
136
138
  the current inbox again. An uncertain write is surfaced without submitting a second delivery.
137
139
 
@@ -182,10 +184,10 @@ for await (const event of session.stream({ follow: false })) {
182
184
  console.log(event.type);
183
185
  }
184
186
 
185
- await session.reset({ reason: "User requested a fresh session" });
187
+ await session.end({ reason: "User requested a fresh session" });
186
188
  ```
187
189
 
188
- `client.sessions` stores the session ID, stream cursor, and optional opaque inbox handle. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and reset leaves the handle pinned to the retired ID.
190
+ `client.sessions` stores the session ID, stream cursor, and optional opaque `inbox` value. Every method calls an ID-addressed `/eve/v1/session/:sessionId/...` route. Sending through a handle for an unknown or terminal ID fails instead of creating a replacement, and `end()` leaves the handle pinned to the retired ID. Replace calls to the old `reset()` method with `end()`; use `client.sessions.create()` to start a different session. Upgrade the server before using a new client's `end()` method: earlier servers do not serve `/end`.
189
191
 
190
192
  A client can own many independent fixed sessions at once:
191
193
 
@@ -37,7 +37,7 @@ 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.reset()` instead retires the session; its delivery settles after retirement and address release.
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.
41
41
 
42
42
  ## Aggregate a turn
43
43
 
@@ -172,11 +172,11 @@ Browser network failures use the same reconnect policy, both when opening a stre
172
172
 
173
173
  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
174
 
175
- Set `streamReconnectPolicy: { 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:
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:
176
176
 
177
177
  ```ts
178
178
  const response = await session.send("Run the long operation.", {
179
- streamReconnectPolicy: { reconnect: false },
179
+ reconnect: false,
180
180
  });
181
181
 
182
182
  for await (const event of response.stream()) {
@@ -184,7 +184,24 @@ for await (const event of response.stream()) {
184
184
  }
185
185
  ```
186
186
 
187
- The same option is available on manual attachments as `session.stream({ streamReconnectPolicy: { reconnect: false } })`.
187
+ The same option is available on manual attachments as `session.stream({ reconnect: false })`.
188
+
189
+ To tune connection-open retries, pass a `ReconnectOptions` object from `eve/client`:
190
+
191
+ ```ts
192
+ const response = await session.send("Run the long operation.", {
193
+ reconnect: {
194
+ maxAttempts: 6,
195
+ baseDelayMs: 250,
196
+ maxDelayMs: 5_000,
197
+ retryableStatuses: [404, 409, 425, 500, 502, 503, 504],
198
+ },
199
+ });
200
+ ```
201
+
202
+ `maxAttempts` defaults to `12` for each connection open. It also bounds consecutive transport failures during a bounded read (`follow: false`). Following reads continue reconnecting until stopped. `baseDelayMs` and `maxDelayMs` tune retries when opening a connection; reconnects after an interrupted response body retain their default backoff.
203
+
204
+ `retryableStatuses` replaces the default list (`404`, `409`, `425`, `500`, `502`, `503`, `504`) rather than extending it, so include any defaults you still want retried.
188
205
 
189
206
  ## Open a stream manually
190
207
 
@@ -253,8 +270,9 @@ continue. `snapshot()` always reads from line `0`; use a bounded stream directly
253
270
  when you only need the unread suffix from an existing cursor.
254
271
 
255
272
  Unlike `stream()`, `snapshot()` does not advance the originating
256
- `ClientSession`. Its returned cursor contains the fixed session ID and the exact
257
- line after the captured prefix.
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.
258
276
 
259
277
  ## Follow a subagent
260
278
 
@@ -317,7 +335,7 @@ try {
317
335
 
318
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.
319
337
 
320
- `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/overview#returned-state) for limits, states, and cursor semantics. Child conversations are whole-session views; their messages do not replace authoritative call results.
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.
321
339
 
322
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.
323
341
 
@@ -173,10 +173,10 @@ To use that choice to delegate while keeping specialist subagents out of the par
173
173
  Pass `signal: ctx.abortSignal` to cancel the request. Import `DecisionModel`, `DecisionState`,
174
174
  `DecisionStatePart`, `DecisionInput`, `DecisionQuestion`, `DecisionAnswer`, `DecisionOptions`,
175
175
  and `DecisionResult` from `eve/ai` to annotate reusable configs and handlers.
176
- Model instances must implement a decision model specification supported by the installed AI SDK;
176
+ Model instances must implement decision model specification `v4`, the version AI SDK 7 supports;
177
177
  a matching `provider`, `modelId`, and `specificationVersion` alone is not an implementation.
178
- A newer specification can typecheck but still be rejected by an older SDK at runtime. Input and
179
- answer validation, retries, and provider errors follow AI SDK semantics.
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.
180
180
 
181
181
  You can also call `decide` outside a tool; it does not require an active eve
182
182
  session. Each call performs its own decision. `auto` uses this function
@@ -114,7 +114,7 @@ A frontend under `apps/web/` is another service managed by your host, not by `ev
114
114
 
115
115
  For path-based mounts, strip the public prefix before forwarding requests to the agent and set `EVE_PUBLIC_ROUTE_PREFIX` in that agent's build and runtime environments. Forward its workflow callback routes as well as its eve routes. Keep the browser client, callback URLs, and peer transports consistent with the public mounts.
116
116
 
117
- You can instead use [`eve/next`](../frontend/nextjs#dev-vs-deploy-topology) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.
117
+ You can instead use [`eve/next`](../frontend/nextjs#self-host) if you want Next.js to start built agent processes and provide the browser-facing proxy routes. That integration is optional; `eve/vercel` configuration is not used by a self-hosted process manager.
118
118
 
119
119
  ## Run schedules
120
120
 
@@ -83,7 +83,7 @@ Vercel evaluates `vercel.ts` before resolving the service graph. `withEve` adds
83
83
 
84
84
  The Web Chat installer can generate this composition for a standalone agent or a selected workspace agent. Configure authentication for every exposed agent. To self-host the same source layout, replace Vercel composition with your own [process and proxy configuration](./self-hosting#run-workspace-members).
85
85
 
86
- Run Vercel CLI 59.16.0 or newer with `vercel dev --local` to start the complete service graph locally without linking a Vercel project. A generated Vercel Web Chat project exposes this as `pnpm dev:all`. When the directory is linked, Vercel also loads its development environment and settings. Use `pnpm dev` or `pnpm dev:eve` when you want one agent and the eve terminal UI, or `pnpm dev:web` when you want the frontend without its agent services. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials.
86
+ Run Vercel CLI 59.16.0 or newer with `vercel dev --local` to start the complete service graph locally without linking a Vercel project. A generated Vercel Web Chat project exposes this as `pnpm dev:all`. When the directory is linked, Vercel also loads its development environment and settings. Use `pnpm dev` or `pnpm dev:eve` when you want one agent and the eve terminal UI, or `pnpm dev:web` when you want the frontend without its agent services. Named agents use the same `/eve/<name>/v1/*` routes in development, and default `defineWorkspaceAgent` transports can call peers without deployment credentials. Import the experimental helper from `eve/experimental/workspace`; see [Vercel workspace peers](../../subagents#vercel-workspace-peers). The workspace layout and `eve/vercel` integration are not experimental.
87
87
 
88
88
  Generated transport routes are inserted before a filesystem handler or, when no filesystem handler exists, before authored routes. `withEve` throws instead of overwriting an authored service key or exact transport route that belongs to a generated agent. Remove the authored route, and remove or rename the authored service; `withEve` adds both automatically. Names in the array form of `services` must also be unique. Other service names, routes, bindings, and Cron Jobs remain authored in `vercel.ts`.
89
89
 
@@ -133,10 +133,10 @@ Use `/traces` to inspect traces recorded during local development. See [Local tr
133
133
  Use `eve dev` flags to control tool calls, reasoning, subagents, connection authorization, response statistics, context usage, and logs:
134
134
 
135
135
  ```bash
136
- eve dev --tools full --reasoning collapsed --logs all
136
+ eve dev --show-tools full --show-reasoning collapsed --logs all
137
137
  ```
138
138
 
139
- `--subagents` accepts `collapsed` (the default), `full`, or `hidden`. `full` also writes each subagent message and tool call to the transcript as it finishes, and `hidden` leaves subagent tasks out of the transcript and the task panel.
139
+ `--show-subagents` accepts `collapsed` (the default), `full`, or `hidden`. `full` also writes each subagent message and tool call to the transcript as it finishes, and `hidden` leaves subagent tasks out of the transcript and the task panel.
140
140
 
141
141
  Use `--host` and `--port` to bind the local server, or `--no-ui` to run without the terminal UI. Set `EVE_TUI_RENDER_MARKDOWN=0` to show assistant and subagent responses without Markdown parsing or styling; `1` (the default) enables Markdown rendering. See the [`eve dev` CLI reference](../reference/cli#eve-dev) for the complete option list, accepted values, and defaults.
142
142
 
@@ -3,6 +3,7 @@
3
3
  "defaultOpen": false,
4
4
  "pages": [
5
5
  "overview",
6
+ "use-eve-agent",
6
7
  "nextjs",
7
8
  "nuxt",
8
9
  "sveltekit",