eve 0.86.0 → 0.88.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 (282) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +1 -1
  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/dev/command-options.d.ts +4 -4
  25. package/dist/src/cli/dev/command.js +1 -1
  26. package/dist/src/cli/dev/tui/runner.js +1 -1
  27. package/dist/src/cli/dev/tui/test/fake-eve-server.js +1 -1
  28. package/dist/src/cli/dev/tui/tool-format.d.ts +2 -2
  29. package/dist/src/cli/dev/ui-options.d.ts +4 -4
  30. package/dist/src/cli/dev/ui-options.js +1 -1
  31. package/dist/src/client/agent-info-error.d.ts +4 -1
  32. package/dist/src/client/agent-info-error.js +1 -1
  33. package/dist/src/client/agent-session.d.ts +1 -4
  34. package/dist/src/client/agent-session.js +1 -1
  35. package/dist/src/client/agent-stream-follower.js +1 -1
  36. package/dist/src/client/client-error.d.ts +13 -4
  37. package/dist/src/client/client-error.js +1 -1
  38. package/dist/src/client/delivery.d.ts +2 -17
  39. package/dist/src/client/health-response-error.d.ts +4 -1
  40. package/dist/src/client/health-response-error.js +1 -1
  41. package/dist/src/client/index.d.ts +5 -3
  42. package/dist/src/client/index.js +1 -1
  43. package/dist/src/client/open-stream.d.ts +7 -12
  44. package/dist/src/client/open-stream.js +1 -1
  45. package/dist/src/client/session-controls.d.ts +2 -2
  46. package/dist/src/client/session-controls.js +1 -1
  47. package/dist/src/client/session-event-stream.d.ts +2 -2
  48. package/dist/src/client/session-event-stream.js +1 -1
  49. package/dist/src/client/session-store.d.ts +2 -6
  50. package/dist/src/client/session-store.js +1 -1
  51. package/dist/src/client/session.d.ts +4 -13
  52. package/dist/src/client/session.js +1 -1
  53. package/dist/src/client/sessions.d.ts +3 -6
  54. package/dist/src/client/types.d.ts +23 -32
  55. package/dist/src/compiled/.vendor-stamp.json +3 -3
  56. package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
  57. package/dist/src/compiler/manifest.js +1 -1
  58. package/dist/src/compiler/normalize-agent-config.js +1 -1
  59. package/dist/src/compiler/normalize-connection.d.ts +1 -1
  60. package/dist/src/compiler/normalize-connection.js +1 -1
  61. package/dist/src/compiler/normalize-instructions.js +1 -1
  62. package/dist/src/compiler/normalize-skill.js +1 -1
  63. package/dist/src/compiler/resolve-workspace-subagent.js +1 -1
  64. package/dist/src/context/memory-tools.d.ts +9 -5
  65. package/dist/src/discover/sandbox.js +1 -1
  66. package/dist/src/dynamic/definition.d.ts +11 -5
  67. package/dist/src/dynamic/definition.js +1 -1
  68. package/dist/src/evals/mock-model.d.ts +1 -1
  69. package/dist/src/evals/session-manager.d.ts +0 -2
  70. package/dist/src/evals/session.d.ts +1 -11
  71. package/dist/src/evals/session.js +1 -1
  72. package/dist/src/eve-channel/index.js +1 -1
  73. package/dist/src/eve-channel/support.js +1 -1
  74. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  75. package/dist/src/execution/effective-agent-config.js +1 -1
  76. package/dist/src/execution/sandbox/bindings/just-bash-runtime.d.ts +1 -2
  77. package/dist/src/execution/sandbox/bindings/just-bash-runtime.js +1 -1
  78. package/dist/src/execution/sandbox/bindings/just-bash.js +1 -1
  79. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  80. package/dist/src/extensions/git/extension/extension.d.ts +5 -2
  81. package/dist/src/extensions/git/extension/extension.js +1 -1
  82. package/dist/src/extensions/git/extension/instructions/github.js +1 -1
  83. package/dist/src/extensions/git/extension/lib/connect-user-auth.d.ts +15 -0
  84. package/dist/src/extensions/git/extension/lib/connect-user-auth.js +1 -0
  85. package/dist/src/extensions/git/extension/lib/gh-tool.d.ts +8 -1
  86. package/dist/src/extensions/git/extension/lib/gh-tool.js +1 -1
  87. package/dist/src/extensions/git/extension/lib/github-guidance.d.ts +2 -1
  88. package/dist/src/extensions/git/extension/lib/github-guidance.js +14 -1
  89. package/dist/src/extensions/git/extension/lib/github-shell.d.ts +12 -4
  90. package/dist/src/extensions/git/extension/lib/github-shell.js +1 -1
  91. package/dist/src/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  92. package/dist/src/instrumentation/providers.d.ts +1 -38
  93. package/dist/src/instrumentation/providers.js +1 -1
  94. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  95. package/dist/src/internal/application/package.d.ts +1 -0
  96. package/dist/src/internal/application/package.js +1 -1
  97. package/dist/src/internal/application/stamped-package-version.js +1 -1
  98. package/dist/src/internal/authored-definition/core.js +1 -1
  99. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  100. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  101. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  102. package/dist/src/internal/runtime-model.d.ts +9 -4
  103. package/dist/src/internal/runtime-model.js +1 -1
  104. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  105. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  106. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  107. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  108. package/dist/src/models/auto.js +1 -1
  109. package/dist/src/protocol/delivery.d.ts +1 -0
  110. package/dist/src/protocol/reset-session.d.ts +0 -2
  111. package/dist/src/protocol/routes.d.ts +9 -2
  112. package/dist/src/protocol/routes.js +1 -1
  113. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  114. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  115. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  116. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  117. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  118. package/dist/src/public/channels/github/state.d.ts +0 -2
  119. package/dist/src/public/channels/index.d.ts +1 -2
  120. package/dist/src/public/channels/index.js +1 -1
  121. package/dist/src/public/channels/linear/index.d.ts +1 -1
  122. package/dist/src/public/channels/linear/index.js +1 -1
  123. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  124. package/dist/src/public/channels/linq/index.d.ts +1 -1
  125. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  126. package/dist/src/public/channels/photon/index.d.ts +1 -1
  127. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  128. package/dist/src/public/channels/slack/api.d.ts +1 -1
  129. package/dist/src/public/channels/slack/api.js +1 -1
  130. package/dist/src/public/channels/slack/app-manifest.d.ts +4 -0
  131. package/dist/src/public/channels/slack/app-manifest.js +1 -1
  132. package/dist/src/public/channels/slack/auth.d.ts +1 -0
  133. package/dist/src/public/channels/slack/auth.js +1 -1
  134. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  135. package/dist/src/public/channels/slack/blocks.js +2 -2
  136. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  137. package/dist/src/public/channels/slack/cards.js +1 -1
  138. package/dist/src/public/channels/slack/defaults.js +1 -1
  139. package/dist/src/public/channels/slack/inbound.d.ts +7 -0
  140. package/dist/src/public/channels/slack/index.d.ts +3 -2
  141. package/dist/src/public/channels/slack/index.js +1 -1
  142. package/dist/src/public/channels/slack/model-context.d.ts +3 -2
  143. package/dist/src/public/channels/slack/model-context.js +3 -3
  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 +37 -72
  147. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  148. package/dist/src/public/channels/slack/user-info.d.ts +64 -0
  149. package/dist/src/public/channels/slack/user-info.js +1 -0
  150. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  151. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  152. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  153. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  154. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  155. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  156. package/dist/src/public/definitions/agent.d.ts +15 -7
  157. package/dist/src/public/definitions/agent.js +1 -1
  158. package/dist/src/public/definitions/channel.d.ts +7 -5
  159. package/dist/src/public/definitions/channel.js +1 -1
  160. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  161. package/dist/src/public/definitions/connections/protocol.js +1 -1
  162. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  163. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  164. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  165. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  166. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  167. package/dist/src/public/experimental/workspace/index.js +1 -0
  168. package/dist/src/public/index.d.ts +2 -2
  169. package/dist/src/public/index.js +1 -1
  170. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  171. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  172. package/dist/src/public/instrumentation/provider.js +1 -1
  173. package/dist/src/public/memory/file/backend.d.ts +1 -1
  174. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  175. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  176. package/dist/src/public/memory/file/provider.js +1 -1
  177. package/dist/src/public/memory/index.d.ts +3 -11
  178. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  179. package/dist/src/public/models/index.d.ts +1 -0
  180. package/dist/src/public/models/openai/index.d.ts +2 -2
  181. package/dist/src/public/next/index.d.ts +2 -2
  182. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  183. package/dist/src/public/sandbox/just-bash.d.ts +0 -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 +14 -8
  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 +141 -15
  239. package/docs/channels/telegram.mdx +6 -0
  240. package/docs/code-extension.mdx +76 -12
  241. package/docs/concepts/default-harness.md +2 -2
  242. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  243. package/docs/concepts/security-model.md +2 -2
  244. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  245. package/docs/concepts/upgrade-to-v27-events.md +2 -1
  246. package/docs/connections/overview.mdx +4 -0
  247. package/docs/evals/reporters.mdx +21 -0
  248. package/docs/extensions.md +12 -0
  249. package/docs/getting-started.mdx +5 -1
  250. package/docs/guides/auth-and-route-protection.md +1 -1
  251. package/docs/guides/client/continuations.mdx +12 -10
  252. package/docs/guides/client/messages.mdx +24 -1
  253. package/docs/guides/client/overview.mdx +8 -6
  254. package/docs/guides/client/streaming.mdx +24 -6
  255. package/docs/guides/decide.md +3 -3
  256. package/docs/guides/deployment/vercel.mdx +1 -1
  257. package/docs/guides/dev-tui.md +2 -2
  258. package/docs/guides/frontend/overview.mdx +1 -1
  259. package/docs/guides/frontend/use-eve-agent-svelte.mdx +13 -11
  260. package/docs/guides/frontend/use-eve-agent-vue.mdx +13 -11
  261. package/docs/guides/frontend/use-eve-agent.mdx +4 -4
  262. package/docs/guides/instrumentation/otel.mdx +3 -1
  263. package/docs/guides/prepare-for-1-0.md +255 -0
  264. package/docs/guides/remote-agents.md +22 -20
  265. package/docs/instructions.mdx +1 -1
  266. package/docs/memory/custom-provider.md +1 -1
  267. package/docs/memory/file.md +11 -2
  268. package/docs/meta.json +1 -0
  269. package/docs/reference/agent-files.md +17 -17
  270. package/docs/reference/cli.md +14 -9
  271. package/docs/reference/typescript-api.md +46 -20
  272. package/docs/sandbox/custom-providers.mdx +2 -0
  273. package/docs/sandbox/default.mdx +6 -6
  274. package/docs/sandbox/index.mdx +5 -5
  275. package/docs/sandbox/just-bash.mdx +30 -21
  276. package/docs/subagents/index.mdx +4 -4
  277. package/docs/tools/human-in-the-loop.md +1 -1
  278. package/docs/tools/workflows.mdx +52 -8
  279. package/docs/tutorial/first-agent.mdx +1 -1
  280. package/package.json +36 -9
  281. package/dist/CHANGELOG.md +0 -38
  282. package/dist/src/public/channels/discord/gateway/index.js +0 -1
@@ -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
 
@@ -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
@@ -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
 
@@ -249,7 +249,7 @@ See [Resume a saved session](./use-eve-agent#resume-a-saved-session) for exactly
249
249
  ## Start a new conversation
250
250
 
251
251
  - `newSession()` clears the chat and starts fresh. The old conversation stays on the server.
252
- - `reset()` ends the conversation on the server. Call `newSession()` afterward to clear it locally.
252
+ - `end()` ends the conversation on the server. Call `newSession()` afterward to clear it locally.
253
253
 
254
254
  To make the first reply faster, pass `prewarm: true`. eve then creates the next session before the user sends anything. Turn it on only after your auth headers are ready. See [Prewarming](./use-eve-agent#prewarming).
255
255
 
@@ -45,15 +45,15 @@ Call the binding once for a conversation and read its reactive getters directly.
45
45
 
46
46
  The state fields are reactive getters; the commands are ordinary methods:
47
47
 
48
- | Property | Svelte shape |
49
- | ------------------------------------------------------------------------------------------- | -------------------------------------------------- |
50
- | `messages`, `agents` | Reactive getters for each projected snapshot field |
51
- | `view` | `SessionView` |
52
- | `status` | `UseEveAgentStatus` |
53
- | `error` | `Error \| undefined` |
54
- | `events` | `readonly SessionStreamEvent[]` |
55
- | `session` | `ClientSessionState \| undefined` |
56
- | `send`, `respond`, `prewarm`, `resume`, `cancel`, `clear`, `compact`, `reset`, `newSession` | Methods |
48
+ | Property | Svelte shape |
49
+ | ----------------------------------------------------------------------------------------- | -------------------------------------------------- |
50
+ | `messages`, `agents` | Reactive getters for each projected snapshot field |
51
+ | `view` | `SessionView` |
52
+ | `status` | `UseEveAgentStatus` |
53
+ | `error` | `Error \| undefined` |
54
+ | `events` | `readonly SessionStreamEvent[]` |
55
+ | `session` | `ClientSessionState \| undefined` |
56
+ | `send`, `respond`, `prewarm`, `resume`, `cancel`, `clear`, `compact`, `end`, `newSession` | Methods |
57
57
 
58
58
  Read the getters directly in templates, `$derived`, or `$effect`. The [`useEveAgent` reference](./use-eve-agent#returned-state) describes what each value and command does.
59
59
 
@@ -91,14 +91,16 @@ an interaction; its response rows and eventual settlement are authoritative.
91
91
 
92
92
  See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
93
93
 
94
- ## Cancel, reset, and resume
94
+ <a id="cancel-reset-and-resume" />
95
+
96
+ ## Cancel, end, and resume
95
97
 
96
98
  Pass `prewarm: true` to prepare an owned workflow on mount and after `newSession()`. It defaults
97
99
  to `false`, so the first send creates the session. The binding waits for create acceptance,
98
100
  retries while the inbox starts, and keeps the session stream open across turns. See [Prewarming](./use-eve-agent#prewarming) for creation, failure, and
99
101
  connection behavior.
100
102
 
101
- Call `agent.cancel()` to stop the durable server-side turn while the binding remains attached through settlement. Offer it while `activeTurn(agent.view)` from `eve/events` returns a turn: `agent.status` reports outstanding work, so it is `"idle"` while a turn waits only on a person. Destroying the component only disconnects its local stream; it does not cancel server execution. Call `agent.newSession()` to clear local state and start a new session. `agent.reset()` instead retires the server-side session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `agent.status` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"idle"` or `"busy"`, and inspect the separate `error` field. Use `agent.resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./use-eve-agent#resume-a-saved-session) for the persistence contract and [Cancelling](./use-eve-agent#cancelling) for cancellation behavior.
103
+ Call `agent.cancel()` to stop the durable server-side turn while the binding remains attached through settlement. Offer it while `activeTurn(agent.view)` from `eve/events` returns a turn: `agent.status` reports outstanding work, so it is `"idle"` while a turn waits only on a person. Destroying the component only disconnects its local stream; it does not cancel server execution. Call `agent.newSession()` to clear local state and start a new session. `agent.end()` instead retires the server-side session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `agent.status` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"idle"` or `"busy"`, and inspect the separate `error` field. Use `agent.resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./use-eve-agent#resume-a-saved-session) for the persistence contract and [Cancelling](./use-eve-agent#cancelling) for cancellation behavior.
102
104
 
103
105
  ## Custom host and credentials
104
106
 
@@ -44,15 +44,15 @@ async function handleSubmit() {
44
44
 
45
45
  The state fields are computed refs; the commands are ordinary methods:
46
46
 
47
- | Property | Vue shape |
48
- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
49
- | `messages`, `agents` | Computed refs for each projected snapshot field |
50
- | `view` | `ComputedRef<SessionView>` |
51
- | `status` | `ComputedRef<UseEveAgentStatus>` |
52
- | `error` | `ComputedRef<Error \| undefined>` |
53
- | `events` | `ComputedRef<readonly SessionStreamEvent[]>` |
54
- | `session` | `ComputedRef<ClientSessionState \| undefined>` |
55
- | `send`, `respond`, `prewarm`, `resume`, `cancel`, `clear`, `compact`, `reset`, `newSession` | Methods |
47
+ | Property | Vue shape |
48
+ | ----------------------------------------------------------------------------------------- | ----------------------------------------------- |
49
+ | `messages`, `agents` | Computed refs for each projected snapshot field |
50
+ | `view` | `ComputedRef<SessionView>` |
51
+ | `status` | `ComputedRef<UseEveAgentStatus>` |
52
+ | `error` | `ComputedRef<Error \| undefined>` |
53
+ | `events` | `ComputedRef<readonly SessionStreamEvent[]>` |
54
+ | `session` | `ComputedRef<ClientSessionState \| undefined>` |
55
+ | `send`, `respond`, `prewarm`, `resume`, `cancel`, `clear`, `compact`, `end`, `newSession` | Methods |
56
56
 
57
57
  Destructuring preserves reactivity because each state value remains a ref. Read refs with `.value` in `<script>` and without `.value` in a template. The [`useEveAgent` reference](./use-eve-agent#returned-state) describes what each value and command does.
58
58
 
@@ -100,14 +100,16 @@ const pendingRequests = computed(() =>
100
100
 
101
101
  See [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) for request semantics and rendering guidance.
102
102
 
103
- ## Cancel, reset, and resume
103
+ <a id="cancel-reset-and-resume" />
104
+
105
+ ## Cancel, end, and resume
104
106
 
105
107
  Pass `prewarm: true` to prepare an owned workflow on mount and after `newSession()`. It defaults
106
108
  to `false`, so the first send creates the session. The binding waits for create acceptance,
107
109
  retries while the inbox starts, and keeps the session stream open across turns. See [Prewarming](./use-eve-agent#prewarming) for creation, failure, and
108
110
  connection behavior.
109
111
 
110
- Call `cancel()` to stop the durable server-side turn while the composable remains attached through settlement. Offer it while `activeTurn(view.value)` from `eve/events` returns a turn: `status` reports outstanding work, so it is `"idle"` while a turn waits only on a person. Disposing the component only disconnects its local stream; it does not cancel server execution. Call `newSession()` to clear local state and start a new session. `reset()` instead retires the server-side session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `status.value` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"idle"` or `"busy"`, and inspect the separate `error` field. Use `resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./use-eve-agent#resume-a-saved-session) for the persistence contract and [Cancelling](./use-eve-agent#cancelling) for cancellation behavior.
112
+ Call `cancel()` to stop the durable server-side turn while the composable remains attached through settlement. Offer it while `activeTurn(view.value)` from `eve/events` returns a turn: `status` reports outstanding work, so it is `"idle"` while a turn waits only on a person. Disposing the component only disconnects its local stream; it does not cancel server execution. Call `newSession()` to clear local state and start a new session. `end()` instead retires the server-side session. Pass `initialSession`, `initialEvents`, and `resume: true` to restore a saved conversation and follow an in-flight turn. During bounded catch-up, `status.value` is `"resuming"`; keep the hydrated conversation visible, disable submission, and wait for `"idle"` or `"busy"`, and inspect the separate `error` field. Use `resume()` directly when restoration is controlled imperatively. See [Resumable sessions](./use-eve-agent#resume-a-saved-session) for the persistence contract and [Cancelling](./use-eve-agent#cancelling) for cancellation behavior.
111
113
 
112
114
  ## Custom host and credentials
113
115
 
@@ -24,7 +24,7 @@ React, [Vue](./use-eve-agent-vue), and [Svelte](./use-eve-agent-svelte) share th
24
24
  | `resume` | Catch up to the durable tail. Later following obeys `followWhile` |
25
25
  | `follow` | Follow a delivery receipt from this or another store on the same session |
26
26
  | `clear`, `compact` | Queue a context change and return its delivery |
27
- | `reset` | Retire the server-side session and return its delivery |
27
+ | `end` | Retire the server-side session and return its delivery |
28
28
  | `newSession` | Clear local state and the local session cursor |
29
29
 
30
30
  About snapshots:
@@ -184,7 +184,7 @@ function useSessionPanels(session: ClientSession) {
184
184
  ### Follow a receipt
185
185
 
186
186
  - `follow(receipt)` tracks an accepted receipt until it settles, even if the stream caught up before the server admitted it.
187
- - Pass only receipts from `send`, `respond`, `clear`, `compact`, or `reset` on the same session. A receipt the stream never admits keeps the store `"busy"` until the session ends or you call `newSession()`.
187
+ - Pass only receipts from `send`, `respond`, `clear`, `compact`, or `end` on the same session. A receipt the stream never admits keeps the store `"busy"` until the session ends or you call `newSession()`.
188
188
  - `follow()` doesn't create a session or grant access.
189
189
  - Limit retries after stream errors, and resolve authorization failures before retrying.
190
190
 
@@ -230,9 +230,9 @@ For an existing idle session, `prewarm()` can move it to the deployment that acc
230
230
  | Command | Effect |
231
231
  | -------------- | ---------------------------------------------------------------------------------------------- |
232
232
  | `newSession()` | Clears the local conversation and reuses the hook. The old session keeps running on the server |
233
- | `reset()` | Retires the server-side session and returns its delivery |
233
+ | `end()` | Retires the server-side session and returns its delivery |
234
234
 
235
- After `reset()`, call `newSession()` to clear the retired conversation. With `prewarm` on, that prepares the next session; otherwise the next send creates it. A `session` you passed in stays yours: prewarming and `newSession()` never replace it.
235
+ After `end()`, call `newSession()` to clear the retired conversation. With `prewarm` on, that prepares the next session; otherwise the next send creates it. A `session` you passed in stays yours: prewarming and `newSession()` never replace it.
236
236
 
237
237
  ## Resume a saved session
238
238
 
@@ -128,7 +128,9 @@ export default otelIntegration({
128
128
  ```
129
129
 
130
130
  Pass `spanProcessors` to `otelIntegration()` when a custom destination needs
131
- filtering or transformation. The example's `exportPolicy` preserves span
131
+ filtering or transformation. Processors and exporters from any `@opentelemetry/*` build
132
+ satisfy the `SpanProcessor` and `SpanExporter` types from `eve/instrumentation/otel`;
133
+ `SpanProcessorOrName` also accepts `"auto"`. The example's `exportPolicy` preserves span
132
134
  metadata while removing inputs and outputs from this destination.
133
135
 
134
136
  ## Add runtime context
@@ -0,0 +1,255 @@
1
+ ---
2
+ title: "Prepare for 1.0"
3
+ description: "Update session controls, authoring definitions, imports, public types, client errors, retry options, and terminal flags for the pre-1.0 API cleanup."
4
+ url: /guides/prepare-for-1-0
5
+ ---
6
+
7
+ Use this checklist when upgrading an existing project to the coordinated pre-1.0 API cleanup release. These changes do not make the release 1.0; the [stability policy](../reference/typescript-api#stability-policy) still distinguishes stable and experimental APIs.
8
+
9
+ Upgrade eve in your agent server and apply the authored-file changes below so it builds. Deploy it before upgrading clients: new clients call the `/end` endpoint, which older servers do not serve. Then update frontend code and scripts.
10
+
11
+ ## End a session or start a new conversation
12
+
13
+ Replace retirement methods named `reset()` with `end()` on client sessions, `SessionStore`, React/Vue/Svelte bindings, channel session handles, `ChannelSource` from `eve/channels`, and the Slack handler context (`ctx.end()`):
14
+
15
+ ```diff
16
+ -await session.reset({ reason: "Conversation finished" });
17
+ +await session.end({ reason: "Conversation finished" });
18
+ ```
19
+
20
+ `end()` resolves with a delivery receipt, like the other session controls. The stream still records the control as `source: { control: "reset" }` on `delivery.admitted` for compatibility with recorded history, so code that matches that value does not change.
21
+
22
+ The HTTP endpoint changes from `POST /eve/v1/session/:sessionId/reset` to `POST /eve/v1/session/:sessionId/end`. Upgraded servers still serve `POST …/reset` beside `/end`, so existing HTTP callers keep working, but move them to `/end`.
23
+
24
+ Ending permanently retires the session and leaves the handle on the retired ID. Do not use `end()` for a **New chat** button. Use `newSession()` when the frontend binding or store owns session creation. When you supply an external `session`, `newSession()` only clears local state and keeps that handle; create a new client session and bind a new store or component to it instead:
25
+
26
+ ```ts
27
+ import { Client } from "eve/client";
28
+
29
+ const client = new Client({ baseUrl: "https://agent.example" });
30
+ const { session } = await client.sessions.create();
31
+ await session.send("Start a new conversation.");
32
+ ```
33
+
34
+ Use `clear()` to clear model context in the same active session instead. See [Session controls](./client/overview#sessions) for the differences.
35
+
36
+ The remote-agent cleanup path and persisted session-history encodings remain compatible with older deployments. This does not let a new client call `/end` on an old server; upgrade the server first.
37
+
38
+ ## Rename the compaction threshold
39
+
40
+ `compaction.threshold` is a fraction from `0` through `1`, not a percentage. Rename the authored field without changing its value:
41
+
42
+ ```diff
43
+ export default defineAgent({
44
+ - compaction: { thresholdPercent: 0.7 },
45
+ + compaction: { threshold: 0.7 },
46
+ });
47
+ ```
48
+
49
+ The old field fails validation with migration guidance. The default remains `0.9`. See [Compaction](../agent-config#compaction).
50
+
51
+ `limits.sessionUsage: false` is now accepted when you want to disable the token-usage limit, including an inherited limit. Omitting it keeps the normal default; no migration is required.
52
+
53
+ ## Export defineAgent from agent.ts
54
+
55
+ Every local `agent.ts`, root or subagent, must export the value `defineAgent` returns. A plain object now fails the build with `Export defineAgent({...}) from "<path>".`:
56
+
57
+ ```diff
58
+ -export default { model: "anthropic/claude-sonnet-5" };
59
+ +import { defineAgent } from "eve";
60
+ +
61
+ +export default defineAgent({ model: "anthropic/claude-sonnet-5" });
62
+ ```
63
+
64
+ A dynamic subagent resolver that selects a local agent must also return `defineAgent({...})`, `defineRemoteAgent(...)`, or `null`.
65
+
66
+ `DynamicSentinel`, `DisabledToolSentinel`, and `DisabledRouteSentinel` are opaque and no longer expose `kind` or `evaluate`. Create them only with `defineDynamic()`, `disableTool()`, and `disableRoute()`; hand-written objects of the same shape are rejected.
67
+
68
+ ## Wrap connection definitions
69
+
70
+ Every connection must use the helper for its protocol. A plain object is no longer assumed to be an MCP connection:
71
+
72
+ ```diff
73
+ -export default { url: "https://issues.example/mcp" };
74
+ +import { defineMcpClientConnection } from "eve/connections";
75
+ +
76
+ +export default defineMcpClientConnection({ url: "https://issues.example/mcp" });
77
+ ```
78
+
79
+ Use `defineOpenAPIConnection` for OpenAPI connections. Keep the helper inside the dynamic factory when authoring a dynamic connection. See [Connections](../connections).
80
+
81
+ ## Choose one sandbox layout
82
+
83
+ If both `agent/sandbox.ts` and `agent/sandbox/` exist, move the definition to `agent/sandbox/sandbox.ts`. The combination now fails discovery instead of silently ignoring the root definition.
84
+
85
+ A standalone `agent/sandbox.ts` remains supported. See [Sandbox layout](../sandbox#define-an-environment).
86
+
87
+ ## Move experimental imports
88
+
89
+ Import workspace helpers from the experimental entry:
90
+
91
+ ```diff
92
+ -import { defineWorkspaceAgent } from "eve";
93
+ +import { defineWorkspaceAgent } from "eve/experimental/workspace";
94
+ ```
95
+
96
+ Move `WorkspaceAgentDefinition` and `WorkspaceAgentTransport` type imports to the same entry. The `agents/<name>/` workspace layout and `withEve` from `eve/vercel` stay stable; the helper's experimental status does not change them.
97
+
98
+ Move just-bash `customCommands` and `filesystem` under `experimental`, and import their types, such as `JustBashCommand` and `JustBashFilesystem`, from `eve/experimental/sandbox/just-bash`. `JustBashSandbox` itself, `autoInstall`, and `prepare` stay on `eve/sandbox/just-bash`:
99
+
100
+ ```diff
101
+ export const environment = JustBashSandbox.environment({
102
+ - customCommands: [today],
103
+ + experimental: { customCommands: [today] },
104
+ });
105
+ ```
106
+
107
+ The Discord Gateway relay moves and drops its prefix:
108
+
109
+ ```diff
110
+ -import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
111
+ +import { runDiscordGatewayRelay } from "eve/experimental/channels/discord/gateway";
112
+ ```
113
+
114
+ See [just-bash](../sandbox/just-bash) and [Discord](../channels/discord).
115
+
116
+ ## Flatten reconnect options
117
+
118
+ Replace `streamReconnectPolicy` with `reconnect`, move open-retry fields directly into that object, and rename `retryableErrorStatuses`:
119
+
120
+ ```diff
121
+ const delivery = await session.send("Continue the review.", {
122
+ - streamReconnectPolicy: {
123
+ - streamOpenReconnectPolicy: { maxAttempts: 3, baseDelayMs: 250, maxDelayMs: 5000 },
124
+ - retryableErrorStatuses: [429, 503],
125
+ + reconnect: {
126
+ + maxAttempts: 3,
127
+ + baseDelayMs: 250,
128
+ + maxDelayMs: 5000,
129
+ + retryableStatuses: [429, 503],
130
+ },
131
+ });
132
+ ```
133
+
134
+ To disable automatic reconnects:
135
+
136
+ ```diff
137
+ -streamReconnectPolicy: { reconnect: false }
138
+ +reconnect: false
139
+ ```
140
+
141
+ Use the exported `ReconnectOptions` type from `eve/client` instead of `StreamReconnectPolicy` or `StreamReconnectRetryPolicy`. The option also applies to client session and event readers. Defaults and cursor recovery are unchanged; following reads keep reconnecting, and server-side readers do not reconnect. See [Streaming](./client/streaming#reconnection).
142
+
143
+ ## Update client error handling and saved state
144
+
145
+ Every error `eve/client` throws now extends `EveError` and carries a stable snake_case `code`. Import the error classes from `eve/client` and narrow with their static `is()` rather than `instanceof`, so errors from a separately bundled copy of eve still match:
146
+
147
+ ```diff
148
+ -if (error instanceof SessionNotActiveError && error.code === "EVE_SESSION_NOT_ACTIVE") {
149
+ +if (SessionNotActiveError.is(error) && error.code === "session_not_active") {
150
+ // Start a new session.
151
+ }
152
+ ```
153
+
154
+ `SessionNotActiveError.code` is `session_not_ready` (with `retryable: true`) while a session is still starting, otherwise `session_not_active`; `EVE_SESSION_NOT_ACTIVE` is gone. `ClientError.code` is now `http_error` instead of `undefined` when the response carried no code.
155
+
156
+ `session.snapshot()` now returns the full `ClientSessionState`, including the opaque `inbox` value, instead of only `sessionId` and `streamIndex`. Persist it as is and pass it back unchanged, for example with `client.sessions.attach(saved.sessionId, saved)`. See [Faster sends with `inbox`](./client/overview#faster-sends-with-inbox).
157
+
158
+ ## Update Workflow imports
159
+
160
+ Import durable primitives from `eve/workflow`, and run/hook operations from `eve/workflow/api`:
161
+
162
+ ```diff
163
+ -import { createHook, createWebhook, sleep, FatalError, RetryableError, getWorkflowMetadata } from "workflow";
164
+ -import { start, getRun, resumeHook } from "workflow/api";
165
+ +import { createHook, createWebhook, sleep, FatalError, RetryableError, getWorkflowMetadata } from "eve/workflow";
166
+ +import { start, getRun, resumeHook } from "eve/workflow/api";
167
+ ```
168
+
169
+ Bare `workflow` and `workflow/*` imports in authored modules now fail the build. Only the exports listed above are public; other SDK subpaths, helpers, and options are not supported by these entries. The previously removed `agent` and `ask` helpers stay removed: importing them from `eve/workflow` fails with a pointer to `defineWorkflowTool()` from `eve/tools`.
170
+
171
+ Both entries declare eve-owned types instead of the SDK's:
172
+
173
+ - `getHookByToken` is removed. Pass a deterministic `token` to `createHook({ token })`, and resume the hook with `resumeHook(token, payload)`. `resumeHook` accepts only a token, not a hook record or an encryption-key override, and resolves to `void`.
174
+ - `start(workflow, args?)` takes a `"use workflow"` function, not a source string, and no options such as `deploymentId` or `world`; eve routes runs to the agent's own queue and deployment.
175
+ - `start` and `getRun` return a `WorkflowRun` with only `runId`, `status`, `returnValue`, and `cancel()`.
176
+
177
+ ```diff
178
+ -const hook = await getHookByToken(token);
179
+ -await resumeHook(hook, payload);
180
+ +await resumeHook(token, payload);
181
+ ```
182
+
183
+ Use `WorkflowHook`, `WorkflowWebhook`, and `WorkflowMetadata` from `eve/workflow`, and `WorkflowRun` and `WorkflowRunStatus` from `eve/workflow/api`, for explicit annotations. Call `eve/workflow/api` operations from routes or `"use step"` helpers, not replayed workflow bodies. Both entries use eve's bundled SDK; do not install another SDK to make these imports resolve.
184
+
185
+ You can remove `eve/workflow-modules` from tsconfig `types` and reference directives. Existing references remain resolvable through 1.x, but the entry no longer declares bare modules. See [Workflow imports](../tools/workflows#workflow-imports).
186
+
187
+ ## Replace third-party types in eve signatures
188
+
189
+ eve's authoring and configuration types no longer expose AI SDK, zod, OpenTelemetry, or channel-adapter types; only the model helpers still return AI SDK models. Any AI SDK language model or OpenTelemetry processor still type-checks wherever eve accepts one, so most projects only change annotations:
190
+
191
+ - Agent `model` fields accept `EveLanguageModel` (exported from `eve` and `eve/models`); any AI SDK language model satisfies it. `anthropic()`, `openai()`, `chatgpt()`, and `mockModel()` still return AI SDK language models, so nothing changes where you pass them to AI SDK functions.
192
+ - `DecisionModel` instances must declare `specificationVersion: "v4"`.
193
+ - `TokenUsage`, the usage record `limits.sessionUsage` callbacks receive, is now exported from `eve` for annotations.
194
+ - `MemoryToolDefinition` is removed. Type memory provider tools as `MemoryToolSet`, a map of `defineTool()` values (`ToolDefinition` from `eve/tools`).
195
+ - Import `SpanProcessor`, `SpanExporter`, and `SpanProcessorOrName` from `eve/instrumentation/otel`, `LinqWebhookVerifier` from `eve/channels/linq`, and `PhotonIMessageWebhookVerifier` and `PhotonProjectCredentials` from `eve/channels/photon`.
196
+
197
+ ## Keep custom data out of channel state bookkeeping
198
+
199
+ Built-in channel state types no longer include the default handlers' bookkeeping, such as Slack `taskCards` and `threadStatus`, Chat SDK streaming fields, `pendingSignIns`, posted prompt cards, `shownPromptId`, `undeliveredReplyErrorId`, and Discord's `interactionToken`, `initialResponseSent`, and `hasMessageAnchor` (read the interaction token from the Discord handle). `TelegramHitlState` is no longer exported. Addressing, identity, and audience fields are unchanged. Keep custom handler data in your own state keys instead of reading or writing these fields.
200
+
201
+ ## Remove unsupported Slack card imports
202
+
203
+ Remove these exports from `eve/channels/slack` imports:
204
+
205
+ - `Modal*`, `TextInput*`, and `ExternalSelect*` builders and their associated types.
206
+ - `CardJSXElement` and `CardJSXProps`.
207
+ - `isCardElement` and `cardChildToFallbackText`.
208
+ - `ChatElement`, `ContainerProps`, and the builder props types: `ButtonProps`, `CardLinkProps`, `CardProps`, `DividerProps`, `FieldProps`, `ImageProps`, `LinkButtonProps`, `SelectOptionProps`, `SelectProps`, and `TextProps`.
209
+
210
+ Card builders no longer accept JSX-style props with `children`. Call their data forms instead:
211
+
212
+ ```diff
213
+ -Actions({ children: [Button({ id: "approve", children: "Approve" })] });
214
+ +Actions([Button({ id: "approve", label: "Approve" })]);
215
+ ```
216
+
217
+ Use `CardText` for labels and `cardToFallbackText` for whole cards. Use native Slack view data for custom modals; the removed builders did not have a supported eve delivery path. Built-in human-in-the-loop modals are unchanged.
218
+
219
+ Supported message cards remain available. An existing `initialMessage: { card }` continues to work; proactive messages can now also use `{ text }`, `{ markdown }`, or `{ blocks, text? }`. Optional files upload into the root message's thread. Retrying a proactive send can repeat both the root post and its uploads. See [Slack cards](../channels/slack#cards) and [proactive sends](../channels/slack#proactive-sessions).
220
+
221
+ ## Replace undocumented helper imports
222
+
223
+ | Entry | Removed export | Migration |
224
+ | --------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
225
+ | `eve/tools` | `isDisabledToolSentinel` | Export `disableTool()` from a tool file; let the compiler handle the sentinel. |
226
+ | `eve/channels` | `isDisabledRouteSentinel` | Export `disableRoute()` from a route file instead of inspecting the sentinel. |
227
+ | `eve/instrumentation` | `isInstrumentationDisabled` | Export `disableInstrumentation()` instead of inspecting the sentinel. |
228
+ | `eve/client` | `failureOf` | Use `failure(view, turnId)` from `eve/events`. |
229
+ | `eve/channels` | `answerFromText` | Parse your channel's input and answer through its authorized session handle; see [Custom channels](../channels/custom). |
230
+ | `eve/channels/linear` | `defaultOnAgentSession` | Omit the override to use the built-in callback, or provide your own `onAgentSession`. |
231
+
232
+ ## Rename terminal display flags
233
+
234
+ Update scripts that call `eve dev` or `eve remote connect`:
235
+
236
+ | Old flag | New flag |
237
+ | ------------------- | ------------------------ |
238
+ | `--tools` | `--show-tools` |
239
+ | `--reasoning` | `--show-reasoning` |
240
+ | `--subagents` | `--show-subagents` |
241
+ | `--connection-auth` | `--show-connection-auth` |
242
+
243
+ Values are unchanged, and the old display names are not aliases. For example:
244
+
245
+ ```bash
246
+ eve dev --show-reasoning full --show-tools auto-collapsed
247
+ ```
248
+
249
+ Model-effort `--reasoning` on `eve init` and `eve set model` is unchanged. `--assistant-response-stats`, `--context-size`, and `--logs` are unchanged too. See the [CLI reference](../reference/cli).
250
+
251
+ ## Check the resulting project
252
+
253
+ Run your project's typecheck and `eve build`, then check the workflows you use: create a conversation, send a message, end it, and start another. Restore a saved session state and send to it. Test any proactive Slack messages and durable workflow waits your project defines.
254
+
255
+ Review [run-data retention](../agent-config#run-data-retention) before depending on a completed transcript remaining readable. This cleanup does not change the retention default: outside development, the default trace policy for private and unknown-audience sessions requests deletion when the session ends. Backend support determines whether deletion occurs; the current override remains experimental.
@@ -20,15 +20,15 @@ export default defineRemoteAgent({
20
20
 
21
21
  `defineRemoteAgent` accepts:
22
22
 
23
- | Parameter | Type | Required | Default | Description |
24
- | ------------------ | ----------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
25
- | `url` | `string` | Yes | n/a | Base URL of the remote eve deployment. Compute runtime URLs in a dynamic definition (see [Runtime URLs](#runtime-urls)). |
26
- | `description` | `string` | Yes | n/a | Model-visible delegation description. |
27
- | `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
28
- | `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
29
- | `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
30
- | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
31
- | `tool` | `boolean \| "deferred"` | No | `true` | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools. |
23
+ | Parameter | Type | Required | Default | Description |
24
+ | ------------------ | --------------------------------------------- | -------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
25
+ | `url` | `string \| (() => string \| Promise<string>)` | Yes | n/a | Base URL of the remote eve deployment. Use a function for [runtime URLs](#runtime-urls). |
26
+ | `description` | `string` | Yes | n/a | Model-visible delegation description. |
27
+ | `auth` | `OutboundAuthFn` | No | none | Outbound auth hook from `eve/agents/auth`. |
28
+ | `forwardPrincipal` | `boolean` | No | `false` | Forward the dispatching turn's session principal to the remote deployment (see [Forwarding the caller identity](#forwarding-the-caller-identity)). |
29
+ | `headers` | `HeadersValue` | No | none | Static or lazily resolved request headers. |
30
+ | `path` | `string` | No | `/eve/v1/session` | Route appended to `url` for the create-session request. |
31
+ | `tool` | `boolean \| "deferred"` | No | `true` | Expose the remote agent as a tool to the parent model. Set `false` to allow only `ctx.agent()` calls from authored workflow tools. |
32
32
 
33
33
  ## Dynamic remote agents
34
34
 
@@ -71,7 +71,7 @@ export default defineDynamic((ctx) => {
71
71
  ```
72
72
 
73
73
  A child keeps the parent context and memo results used to select its remote configuration.
74
- Later messages, answers, cancellation, reset, and stream reads use that original selection when
74
+ Later messages, answers, cancellation, session retirement, and stream reads use that original selection when
75
75
  rebuilding transport credentials. Only saved memo results are available: a missing result or a
76
76
  changed child name or URL fails before credentials are sent. `ctx.messages()` is unavailable
77
77
  during this reconstruction, including when eve opens the child; keep conversation-based
@@ -81,20 +81,22 @@ selection inside a memo. This does not change the per-message caller identity de
81
81
 
82
82
  ## Runtime URLs
83
83
 
84
- A static `url` is read at compile time. When an environment variable supplies the URL only at runtime, compute it inside `defineDynamic`:
84
+ A string `url` is read at compile time. Use a function when an environment variable
85
+ supplies the URL only at runtime. eve invokes it when resolving the runtime agent graph;
86
+ it can return a string or a promise:
85
87
 
86
88
  ```ts title="agent/subagents/weather.ts"
87
- import { defineDynamic, defineRemoteAgent } from "eve";
89
+ import { defineRemoteAgent } from "eve";
88
90
 
89
- export default defineDynamic(() =>
90
- defineRemoteAgent({
91
- url: process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
92
- description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
93
- }),
94
- );
91
+ export default defineRemoteAgent({
92
+ url: () => process.env.WEATHER_AGENT_URL ?? "https://weather-agent.example.com",
93
+ description: "Answers weather, temperature, forecast, wind, rain, and snow questions.",
94
+ });
95
95
  ```
96
96
 
97
- `url` must be a non-empty string. `auth` and `headers` remain lazy callbacks resolved per request.
97
+ The resolved `url` must be a non-empty string. Use `defineDynamic` when the current
98
+ session determines which agent is exposed or whether it is available.
99
+ `auth` and `headers` remain lazy callbacks resolved per request.
98
100
 
99
101
  ## Calling a remote agent
100
102
 
@@ -236,7 +238,7 @@ Clients follow a remote child through the parent. [`session.agent(opened).stream
236
238
 
237
239
  Cancelling the parent turn or the agent task with `eve__task_cancel` also cancels the remote child's current turn. eve resolves the remote's `headers` and `auth` again for every cancellation attempt, so rotating credentials work the same way as they do for session creation. Cancellation always uses the standard eve cancel path on `url`, even when `path` customizes only the create-session endpoint. The remote child reports `turn.settled` with `outcome: "cancelled"` on its own stream; an older or unreachable remote is logged but cannot turn the parent's cancellation into a failure.
238
240
 
239
- When the workflow run that opened a remote child finishes, eve sends an authenticated `POST /eve/v1/session/:childSessionId/reset` for it. An agent task's run finishes when the parent session ends. Reset retires the parked remote session and recursively cleans up its descendants. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
241
+ When the workflow run that opened a remote child finishes, eve sends an authenticated request to end it. An agent task's run finishes when the parent session ends. Ending retires the parked remote session and recursively cleans up its descendants. Parent cleanup retains its earlier wire path so independently deployed parents and children can run different eve versions. The request uses freshly resolved `headers` and `auth`; failures are logged so an unreachable remote cannot block parent finalization.
240
242
 
241
243
  The parent names its remote agent protocol version when it creates the child, and the remote
242
244
  answers with the version it serves. This release serves protocols 2 and 3. A protocol-3 parent
@@ -82,7 +82,7 @@ See [Dynamic capabilities](./guides/dynamic-capabilities) for examples and failu
82
82
 
83
83
  ## History controls and prompt caching
84
84
 
85
- [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-reset) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
85
+ [Compaction](./concepts/sessions-runs-and-streaming#compact-clear-and-end) treats user-role instructions like ordinary conversation history, so a summary may replace their original text. Clear removes them with the rest of model-message history and does not rerun static or dynamic instructions. System-role instructions remain because they are outside history.
86
86
 
87
87
  Keep system-role content stable and place it before frequently changing context when practical. That gives providers the best opportunity to reuse a prompt prefix, but cache behavior and billing remain provider-specific. User-role instructions preserve the normal append-only message prefix. Framework announcements about available skills and parked agents are retained in user-role history: changed snapshots append after earlier steps instead of replacing the context sent with those steps. Unchanged announcements are skipped until history is cleared or compacted. eve does not promise a cache hit.
88
88
 
@@ -148,7 +148,7 @@ context. The `id` also identifies the record in
148
148
 
149
149
  ### Tools
150
150
 
151
- `tools()` returns a map of `defineTool()` values or `null`. eve qualifies each
151
+ `tools()` returns a `MemoryToolSet`, a map of `defineTool()` values, or `null`. eve qualifies each
152
152
  key as `<slot>__<key>`; the qualified name must start with a letter, contain
153
153
  only letters, digits, underscores, or dashes, and be at most 64 characters.
154
154
  Schemas, `approval`, `outputSchema`, and `toModelOutput` work as they do for