eve 0.86.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 (261) hide show
  1. package/CHANGELOG.md +67 -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/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  81. package/dist/src/instrumentation/providers.d.ts +1 -38
  82. package/dist/src/instrumentation/providers.js +1 -1
  83. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  84. package/dist/src/internal/application/package.d.ts +1 -0
  85. package/dist/src/internal/application/package.js +1 -1
  86. package/dist/src/internal/application/stamped-package-version.js +1 -1
  87. package/dist/src/internal/authored-definition/core.js +1 -1
  88. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  89. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  90. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  91. package/dist/src/internal/runtime-model.d.ts +9 -4
  92. package/dist/src/internal/runtime-model.js +1 -1
  93. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  94. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  95. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  96. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  97. package/dist/src/models/auto.js +1 -1
  98. package/dist/src/protocol/delivery.d.ts +1 -0
  99. package/dist/src/protocol/reset-session.d.ts +0 -2
  100. package/dist/src/protocol/routes.d.ts +9 -2
  101. package/dist/src/protocol/routes.js +1 -1
  102. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  103. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  104. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  105. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  106. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  107. package/dist/src/public/channels/github/state.d.ts +0 -2
  108. package/dist/src/public/channels/index.d.ts +1 -2
  109. package/dist/src/public/channels/index.js +1 -1
  110. package/dist/src/public/channels/linear/index.d.ts +1 -1
  111. package/dist/src/public/channels/linear/index.js +1 -1
  112. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  113. package/dist/src/public/channels/linq/index.d.ts +1 -1
  114. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  115. package/dist/src/public/channels/photon/index.d.ts +1 -1
  116. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  117. package/dist/src/public/channels/slack/api.d.ts +1 -1
  118. package/dist/src/public/channels/slack/api.js +1 -1
  119. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  120. package/dist/src/public/channels/slack/blocks.js +2 -2
  121. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  122. package/dist/src/public/channels/slack/cards.js +1 -1
  123. package/dist/src/public/channels/slack/index.d.ts +2 -2
  124. package/dist/src/public/channels/slack/index.js +1 -1
  125. package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
  126. package/dist/src/public/channels/slack/session-operations.js +1 -1
  127. package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
  128. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  129. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  130. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  131. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  132. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  133. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  134. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  135. package/dist/src/public/definitions/agent.d.ts +15 -7
  136. package/dist/src/public/definitions/agent.js +1 -1
  137. package/dist/src/public/definitions/channel.d.ts +7 -5
  138. package/dist/src/public/definitions/channel.js +1 -1
  139. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  140. package/dist/src/public/definitions/connections/protocol.js +1 -1
  141. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  142. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  143. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  144. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  145. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  146. package/dist/src/public/experimental/workspace/index.js +1 -0
  147. package/dist/src/public/index.d.ts +2 -2
  148. package/dist/src/public/index.js +1 -1
  149. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  150. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  151. package/dist/src/public/instrumentation/provider.js +1 -1
  152. package/dist/src/public/memory/file/backend.d.ts +1 -1
  153. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  154. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  155. package/dist/src/public/memory/file/provider.js +1 -1
  156. package/dist/src/public/memory/index.d.ts +3 -11
  157. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  158. package/dist/src/public/models/index.d.ts +1 -0
  159. package/dist/src/public/models/openai/index.d.ts +2 -2
  160. package/dist/src/public/next/index.d.ts +2 -2
  161. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  162. package/dist/src/public/sandbox/just-bash.d.ts +0 -1
  163. package/dist/src/public/sessions/index.d.ts +1 -0
  164. package/dist/src/public/sessions/index.js +1 -1
  165. package/dist/src/public/tools/index.d.ts +1 -1
  166. package/dist/src/public/tools/index.js +1 -1
  167. package/dist/src/public/workflow/api.d.ts +25 -0
  168. package/dist/src/public/workflow/api.js +1 -0
  169. package/dist/src/public/workflow/index.d.ts +76 -0
  170. package/dist/src/public/workflow/index.js +1 -0
  171. package/dist/src/public/workflow-modules.d.ts +2 -17
  172. package/dist/src/react/use-eve-agent.d.ts +3 -2
  173. package/dist/src/react/use-eve-agent.js +1 -1
  174. package/dist/src/reactions/kinds/model.js +1 -1
  175. package/dist/src/runtime/agent/resolve-model.js +1 -1
  176. package/dist/src/runtime/resolve-agent.js +1 -1
  177. package/dist/src/runtime/resolve-dynamic.js +1 -1
  178. package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
  179. package/dist/src/runtime/subagents/workflow.js +1 -1
  180. package/dist/src/sandbox/providers/default.js +1 -1
  181. package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
  182. package/dist/src/self-modification/sandbox.js +1 -1
  183. package/dist/src/setup/integrations/discord/daemon.js +2 -2
  184. package/dist/src/setup/scaffold/create/project.js +2 -2
  185. package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
  186. package/dist/src/setup/scaffold/create/web-template.js +2 -2
  187. package/dist/src/setup/verified-remote-agent.d.ts +1 -3
  188. package/dist/src/shared/agent-definition.d.ts +18 -9
  189. package/dist/src/shared/eve-error.d.ts +22 -0
  190. package/dist/src/shared/eve-error.js +1 -0
  191. package/dist/src/shared/session.d.ts +2 -2
  192. package/dist/src/shared/token-usage.d.ts +7 -1
  193. package/dist/src/svelte/index.js +1 -1
  194. package/dist/src/svelte/use-eve-agent.d.ts +2 -1
  195. package/dist/src/svelte/use-eve-agent.js +1 -1
  196. package/dist/src/tools/definition.d.ts +7 -5
  197. package/dist/src/tools/definition.js +1 -1
  198. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  199. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  200. package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
  201. package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
  202. package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
  203. package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
  204. package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
  205. package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
  206. package/dist/src/tracing/local/traces.d.ts +0 -13
  207. package/dist/src/vue/index.js +1 -1
  208. package/dist/src/vue/use-eve-agent.d.ts +3 -2
  209. package/dist/src/vue/use-eve-agent.js +1 -1
  210. package/docs/agent-config.md +15 -11
  211. package/docs/channels/custom.mdx +26 -10
  212. package/docs/channels/discord.mdx +10 -10
  213. package/docs/channels/eve.mdx +14 -8
  214. package/docs/channels/linear.mdx +11 -0
  215. package/docs/channels/linq.mdx +5 -1
  216. package/docs/channels/photon.mdx +6 -1
  217. package/docs/channels/slack.mdx +73 -14
  218. package/docs/channels/telegram.mdx +6 -0
  219. package/docs/code-extension.mdx +25 -0
  220. package/docs/concepts/default-harness.md +2 -2
  221. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  222. package/docs/concepts/security-model.md +2 -2
  223. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  224. package/docs/concepts/upgrade-to-v27-events.md +2 -1
  225. package/docs/connections/overview.mdx +4 -0
  226. package/docs/evals/reporters.mdx +21 -0
  227. package/docs/extensions.md +12 -0
  228. package/docs/getting-started.mdx +5 -1
  229. package/docs/guides/auth-and-route-protection.md +1 -1
  230. package/docs/guides/client/continuations.mdx +12 -10
  231. package/docs/guides/client/messages.mdx +24 -1
  232. package/docs/guides/client/overview.mdx +8 -6
  233. package/docs/guides/client/streaming.mdx +24 -6
  234. package/docs/guides/decide.md +3 -3
  235. package/docs/guides/deployment/vercel.mdx +1 -1
  236. package/docs/guides/dev-tui.md +2 -2
  237. package/docs/guides/frontend/overview.mdx +1 -1
  238. package/docs/guides/frontend/use-eve-agent-svelte.mdx +13 -11
  239. package/docs/guides/frontend/use-eve-agent-vue.mdx +13 -11
  240. package/docs/guides/frontend/use-eve-agent.mdx +4 -4
  241. package/docs/guides/instrumentation/otel.mdx +3 -1
  242. package/docs/guides/prepare-for-1-0.md +255 -0
  243. package/docs/guides/remote-agents.md +22 -20
  244. package/docs/instructions.mdx +1 -1
  245. package/docs/memory/custom-provider.md +1 -1
  246. package/docs/memory/file.md +11 -2
  247. package/docs/meta.json +1 -0
  248. package/docs/reference/agent-files.md +17 -17
  249. package/docs/reference/cli.md +14 -9
  250. package/docs/reference/typescript-api.md +46 -20
  251. package/docs/sandbox/custom-providers.mdx +2 -0
  252. package/docs/sandbox/default.mdx +6 -6
  253. package/docs/sandbox/index.mdx +5 -5
  254. package/docs/sandbox/just-bash.mdx +30 -21
  255. package/docs/subagents/index.mdx +4 -4
  256. package/docs/tools/human-in-the-loop.md +1 -1
  257. package/docs/tools/workflows.mdx +52 -8
  258. package/docs/tutorial/first-agent.mdx +1 -1
  259. package/package.json +36 -9
  260. package/dist/CHANGELOG.md +0 -38
  261. package/dist/src/public/channels/discord/gateway/index.js +0 -1
@@ -59,10 +59,15 @@ export default photonIMessageChannel({
59
59
  ```
60
60
 
61
61
  Set `route` to override the webhook path or `webhookVerifier` to use a different
62
- trusted-forwarder verifier.
62
+ trusted-forwarder verifier. `eve/channels/photon` exports the `PhotonIMessageWebhookVerifier`,
63
+ `PhotonIMessageChannelCredentials`, and `PhotonProjectCredentials` types for these options.
63
64
 
64
65
  ## Tapbacks
65
66
 
67
+ `IMESSAGE_TAPBACKS` from `eve/channels/photon` lists the built-in tapback names.
68
+ Use it to populate a picker or validate a named reaction. Tapback APIs can also
69
+ accept a single emoji; the list does not enumerate those.
70
+
66
71
  eve ignores tapbacks people send unless you pass `onTapback`. It receives the
67
72
  tapback and returns the same result as `onMessage`, or `null` to ignore it:
68
73
 
@@ -278,7 +278,7 @@ async onAppMention(ctx) {
278
278
  await ctx.cancel();
279
279
  await ctx.compact();
280
280
  await ctx.clear();
281
- await ctx.reset({ reason: "Start over" });
281
+ await ctx.end({ reason: "Start over" });
282
282
  const session = await ctx.resolveSession();
283
283
  return { auth: null };
284
284
  }
@@ -286,9 +286,11 @@ async onAppMention(ctx) {
286
286
 
287
287
  These calls are independent examples; a handler normally chooses one. `ctx.send()` is the only method that can create a session when the thread is unowned. It derives Slack auth from the inbound user unless `auth` is supplied explicitly. Use `await ctx.resolveSession()` only when later work must stay pinned to the currently owning durable session ID.
288
288
 
289
- #### Reset a conversation
289
+ <a id="reset-a-conversation" />
290
290
 
291
- Use the thread-bound `ctx.reset({ reason? })` method when the conversation should start over instead. Reset terminally retires the session that currently owns the thread, including any in-flight turn. The next delivered message starts a new session with fresh history, state, and a new session-scoped sandbox:
291
+ #### End a conversation
292
+
293
+ Use the thread-bound `ctx.end({ reason? })` method to retire the conversation. End terminally retires the session that currently owns the thread, including any in-flight turn. The next delivered message starts a new session with fresh history, state, and a new session-scoped sandbox:
292
294
 
293
295
  ```ts title="agent/channels/slack.ts"
294
296
  export default slackChannel({
@@ -296,14 +298,14 @@ export default slackChannel({
296
298
  async onMessage(ctx, message) {
297
299
  if (message.text.trim() !== "/new") return null;
298
300
 
299
- await ctx.reset({ reason: "Slack user requested /new" });
301
+ await ctx.end({ reason: "Slack user requested /new" });
300
302
  await ctx.thread.post("Started a fresh conversation.");
301
303
  return null;
302
304
  },
303
305
  });
304
306
  ```
305
307
 
306
- Reset returns a `Delivery` for the retiring session; `await delivery.result()` waits for retirement and address release. An already unowned thread throws `SessionNotActiveError`. Returning `null` after reset consumes the triggering message as a command; return `{ auth }` instead to deliver that message as the first turn of the fresh session. Custom `onInteraction` handlers receive the same flat operations, which is useful for a New conversation button.
308
+ End returns a `Delivery` for the retiring session; `await delivery.result()` waits for retirement and address release. An already unowned thread throws `SessionNotActiveError`. Returning `null` after end consumes the triggering message as a command; return `{ auth }` instead to deliver that message as the first turn of the fresh session. Custom `onInteraction` handlers receive the same flat operations, which is useful for a New conversation button.
307
309
 
308
310
  #### Serve Slack code channels
309
311
 
@@ -465,7 +467,7 @@ await ctx.respond(answers, { auth: null, target });
465
467
  await ctx.cancel({ target, turnId });
466
468
  await ctx.compact({ target });
467
469
  await ctx.clear({ target });
468
- await ctx.reset({ reason: "Start over", target });
470
+ await ctx.end({ reason: "Start over", target });
469
471
  const session = await ctx.resolveSession({ target });
470
472
  ```
471
473
 
@@ -900,23 +902,80 @@ renderers: [
900
902
 
901
903
  The private authorization button uses the label **Sign in**, so long connection display names do not make the button invalid. The public status identifies the connection.
902
904
 
905
+ ### Cards
906
+
907
+ Use the card builders from `eve/channels/slack` for typed message layouts, or pass raw Slack blocks with `{ blocks, text }`. Cards are plain data, not JSX components.
908
+
909
+ | Builders | Use |
910
+ | --------------------------------------- | -------------------------------------------- |
911
+ | `Card`, `CardText`, `CardLink` | Build a card with text and links. |
912
+ | `Section`, `Divider`, `Image` | Group content, separate it, or add an image. |
913
+ | `Fields`, `Field`, `Table` | Display labeled values or tabular data. |
914
+ | `Actions`, `Button`, `LinkButton` | Group action buttons and links. |
915
+ | `Select`, `SelectOption`, `RadioSelect` | Add fixed-choice controls inside `Actions`. |
916
+
917
+ For example, post a review link from a message hook:
918
+
919
+ ```ts title="agent/channels/slack.ts"
920
+ import { Actions, Card, CardText, LinkButton, slackChannel } from "eve/channels/slack";
921
+
922
+ export default slackChannel({
923
+ async onAppMention(ctx) {
924
+ await ctx.thread.post({
925
+ card: Card({
926
+ title: "Review ready",
927
+ children: [
928
+ CardText("Alice's draft is ready for review."),
929
+ Actions([LinkButton({ label: "Open draft", url: "https://example.com/draft" })]),
930
+ ],
931
+ }),
932
+ fallbackText: "Alice's draft is ready for review.",
933
+ });
934
+ return null;
935
+ },
936
+ });
937
+ ```
938
+
939
+ Handle your own button and select callbacks in `onInteraction`. To build eve-owned approval or question controls, use the [HITL helpers](#render-and-decode-hitl-controls-yourself). `cardToBlocks(card)` converts a card to Slack blocks; `cardToFallbackText(card)` produces notification and accessibility text. `thread.post({ card })` runs `cardToBlocks` automatically, and runs `cardToFallbackText` unless you supply `fallbackText`.
940
+
941
+ Message cards do not support modals, text inputs, or external selects. Use `CardText` for labels. For custom modals, send native Slack view data with `ctx.slack.request("views.open", ...)`; see [interactive callbacks](#message-hooks).
942
+
903
943
  ### Proactive sessions
904
944
 
905
945
  Start a Slack conversation from a [webhook on another channel](./custom#cross-channel-hand-off), a [schedule](../schedules#handler-form-run), or a [tool](../tools#start-channel-sessions-ctxto), without waiting for someone to message the app. To copy an existing conversation into a new thread or someone's direct messages, see [Fork conversations into a new thread](../patterns/fork-conversations-into-new-threads).
906
946
 
907
947
  Pass `{ channelId }` as the target to start a new thread. The agent's first post becomes the thread's root message. You can also set these target fields:
908
948
 
909
- | Field | Use |
910
- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
911
- | `threadTs` | Continue an existing thread instead of creating one. |
912
- | `initialMessage` | Post a card as the thread root before the agent runs. Cannot be combined with `threadTs`. |
913
- | `installationTeamId` | Select the app installation workspace when using a function-form bot token. |
914
- | `codeChannel` | Open a [code channel](#build-your-own-code-channel-tool) from a message in `channelId` and start the session there. Requires `codeChannels: true`. |
915
- | `audience` | Set the destination's visibility when you know it. Defaults to `unknown`. |
949
+ | Field | Use |
950
+ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
951
+ | `threadTs` | Continue an existing thread instead of creating one. |
952
+ | `initialMessage` | Post a `SlackPostInput` as the thread root before the agent runs: `{ markdown }`, `{ text }`, `{ blocks, text? }`, or `{ card, fallbackText? }`. Cannot be combined with `threadTs` or `codeChannel`. |
953
+ | `installationTeamId` | Select the app installation workspace when using a function-form bot token. |
954
+ | `codeChannel` | Open a [code channel](#build-your-own-code-channel-tool) from a message in `channelId` and start the session there. Requires `codeChannels: true`. |
955
+ | `audience` | Set the destination's visibility when you know it. Defaults to `unknown`. |
916
956
 
917
957
  A send with an `idempotencyKey` and no `threadTs` or `initialMessage` derives the new thread's session from the key, so a retry with the same key reaches the same session instead of starting a second thread. Because the key chooses the session, two different sends that reuse a key land in the same thread and the second is ignored. Use a key that identifies the delivery across every sender to this channel, not only across retries of one sender.
918
958
 
919
- The default mention handler lets teammates continue the session by mentioning the app in the thread. To accept replies without a mention, [configure an `onMessage` hook and the required Slack subscriptions and scopes](#continue-conversations-without-repeated-mentions).
959
+ `initialMessage` uses the same explicit inputs as `thread.post`, including cards and optional files. It always posts a root message first, then uploads files into that thread. A retried proactive send repeats both the root post and any uploads, so don't use it as an exactly-once notification. For example, start a thread with a Markdown root:
960
+
961
+ ```ts title="agent/channels/slack.ts"
962
+ import { slackChannel } from "eve/channels/slack";
963
+
964
+ export default slackChannel({
965
+ async onEvent(ctx, event) {
966
+ if (event.type !== "team_join") return;
967
+ await ctx.send("Prepare a welcome message for the new teammate.", {
968
+ auth: null,
969
+ target: {
970
+ channelId: "C0123ABC",
971
+ initialMessage: { markdown: "A new teammate joined. Preparing their welcome." },
972
+ },
973
+ });
974
+ },
975
+ });
976
+ ```
977
+
978
+ The root is posted before the agent runs; the agent's replies appear under it. The default mention handler lets teammates continue the session by mentioning the app in the thread. To accept replies without a mention, [configure an `onMessage` hook and the required Slack subscriptions and scopes](#continue-conversations-without-repeated-mentions).
920
979
 
921
980
  For a Slack post without an agent turn, use `ctx.thread.post(...)` in an inbound handler or `ctx.channel.thread.post(...)` in a renderer's event handler. Outside a handler, use [`callSlackApi(...)`](#slack-api-calls-outside-a-handler).
922
981
 
@@ -43,6 +43,12 @@ Forum topics carry `message_thread_id` in the continuation token, so each topic
43
43
 
44
44
  To customize auth or filtering, override `onMessage`. Return `title` alongside `auth` to set the title when the dispatch starts a run. Group privacy mode itself lives in BotFather, not here.
45
45
 
46
+ Custom `onMessage` hooks can import `defaultTelegramAuth` from
47
+ `eve/channels/telegram` and return `{ auth: defaultTelegramAuth(message) }` to
48
+ keep the default actor identity. The helper uses the message's `from` user,
49
+ scopes group identities to the chat, and returns `null` when no user is present.
50
+ For a button press, pass the button presser as `from`, not the message's author.
51
+
46
52
  ### Delivery
47
53
 
48
54
  The default `content.completed` handler sends each reply part as plain text via `sendMessage`. It passes no `parse_mode`, so any Markdown shows up literally. Replies longer than Telegram's 4096-char limit are split across messages. Custom handlers use `ctx.channel.telegram`.
@@ -164,6 +164,31 @@ export default git({
164
164
 
165
165
  `code({ github })` is rejected. Move the `github` option to `git({ github })`, and import `gh` and the GitHub sandbox helpers from `eve/extensions/git/tools` and `eve/extensions/git/sandbox`.
166
166
 
167
+ ## Override bundled tools
168
+
169
+ `eve/extensions/code/tools` exports the reusable `apply_patch` and `grep` tool
170
+ definitions. Import one in an override to change approval or other tool options
171
+ without copying its implementation. With the file mount above, put the override
172
+ in the agent-root slot named after the qualified tool, `code__apply_patch`:
173
+
174
+ ```ts title="agent/tools/code__apply_patch.ts"
175
+ import { apply_patch } from "eve/extensions/code/tools";
176
+ import { defineTool } from "eve/tools";
177
+ import { always } from "eve/tools/approval";
178
+
179
+ export default defineTool({ ...apply_patch, approval: always() });
180
+ ```
181
+
182
+ `agent/extensions/code/tools/apply_patch.ts` works only when the mount is a
183
+ directory, `agent/extensions/code/extension.ts`.
184
+
185
+ For a custom GitHub command tool, `eve/extensions/git/sandbox` exports
186
+ `executeGitHubShell(input, config, dependencies)` and `githubShellApproval(input)`.
187
+ The execution helper enforces repository and command constraints and brokers a
188
+ credential lease; dependencies supply the session ID and sandbox access. Reuse
189
+ `githubShellApproval` to reject invalid command inputs through the approval
190
+ policy rather than bypassing those constraints.
191
+
167
192
  ## Prepare the sandbox
168
193
 
169
194
  Install the CLI tooling in your sandbox environment's `prepare` callback:
@@ -7,13 +7,13 @@ The default harness is eve's built-in agent loop. It manages model calls, compac
7
7
 
8
8
  ## Compaction
9
9
 
10
- The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `thresholdPercent` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
10
+ The harness keeps a long session from overflowing the model's context window. Before comparing the conversation with `compaction.threshold` (`0.9` by default), it adds the estimated fixed envelope of the checkpoint prompt used for compaction. It then summarizes the older turns and keeps going. The prompt asks the compaction model to distinguish completed progress and decisions from remaining work and to retain the constraints, preferences, data, and references needed to continue. When eve compacts again, it passes the previous checkpoint separately and without the transcript's per-message truncation, then replaces it with the updated checkpoint. The summary uses the active turn model unless you override it. After compacting, the harness keeps the most recent messages word for word next to the summary, up to 20,000 tokens (or half of the threshold, if that is smaller), with tool results shortened to 2,000 characters. The current user message is always part of that, so when it alone is larger than the budget the harness keeps only its start and its end, with a note where the middle was cut, and summarizes the cut-out middle with the older turns. If a compaction cannot bring the history under the threshold, the session fails with an error instead of compacting again, and the step is not retried: start a new session or send a smaller message. Tune when and how it kicks in under [`compaction`](../agent-config#compaction) in `agent.ts`:
11
11
 
12
12
  ```ts title="agent/agent.ts"
13
13
  export default defineAgent({
14
14
  model: "anthropic/claude-opus-5.5",
15
15
  compaction: {
16
- thresholdPercent: 0.75,
16
+ threshold: 0.75,
17
17
  },
18
18
  });
19
19
  ```
@@ -58,7 +58,7 @@ eve treats every world other than Vercel Workflow as running one eve version at
58
58
 
59
59
  eve ends a stranded session without running any of its code. When that happens depends on the kind of run:
60
60
 
61
- - **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, a reset ends it, or its session timeout elapses, whichever comes first.
61
+ - **A root session**, one that a channel or client started, stays where it is. It keeps its address and executes nothing until a new channel message replaces it, an explicit end retires it, or its session timeout elapses, whichever comes first.
62
62
  - **A subagent session or workflow tool run**, including a task, is cancelled the next time the world delivers work to it, for example when the local world or Postgres recovers active runs at startup. No later message could resume its interrupted work, so eve does not wait.
63
63
 
64
64
  See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
@@ -66,18 +66,18 @@ See [How a stranded session ends](#how-a-stranded-session-ends) for the details.
66
66
  For a root session, what happens next depends on how the message is addressed:
67
67
 
68
68
  - **A channel address**, such as a Slack thread or any `from(address).send(...)`, resets the stranded session and starts a fresh session at the same address. The message becomes the fresh session's first turn. Concurrent messages to the address produce one fresh session. The fresh session names the session it replaced, whose recorded conversation your instructions can read; see [What a replacement session receives](#what-a-replacement-session-receives). A delivery that carries input responses, with or without a message, throws `SessionStrandedError` and leaves the stranded session in place, because a fresh session has no request for them to answer. See [custom channels](../channels/custom#channel-operations-and-session-handles).
69
- - **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `reset()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
69
+ - **`create()` on a channel address** throws `SessionStrandedError` and leaves the stranded session in place. Call `end()` on the address, then `create()` again; see [Start from prior history](../channels/eve#start-from-prior-history).
70
70
  - **A session ID** is never reset implicitly. The eve HTTP channel returns `409` with `code: "session_stranded"` and the `eveVersion` that built the session when it recorded one. `Session.send()` and `Session.respond()` throw `SessionStrandedError` from `eve/channels`, and the TypeScript client's `ClientSession.send()` and `respond()` throw `ClientSessionStrandedError` from `eve/client`. Nothing is delivered, and the stranded run keeps its status and event log. See [Start and continue a session](../channels/eve#start-and-continue-a-session).
71
71
  - **Following a stream** of a stranded session returns the same `409 session_stranded`. The TypeScript client stops reconnecting and reports `ClientSessionStrandedError`; the TUI explains how to recover. An existing connection learns this when it reconnects. Messages accepted before the upgrade are not redelivered.
72
- - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to reset it.
73
- - **Reset** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. Reset the session instead.
74
- - **Session timeouts** end a stranded session the same way a reset does; see [How a stranded session ends](#how-a-stranded-session-ends).
72
+ - **Reading recorded history** still works. A bounded read (`stream({ follow: false })`, or `follow=false` on the stream route) returns the events recorded so far without inspecting or changing the session, so you can read a stranded conversation before deciding to end it.
73
+ - **End** works on a stranded session through a channel address or a session ID. **Clear** would keep a session that cannot run, so it is refused: `Session.clear()` throws `SessionStrandedError`, the eve HTTP channel returns `409 session_stranded`, and nothing changes. End the session instead.
74
+ - **Session timeouts** end a stranded session the same way an explicit end does; see [How a stranded session ends](#how-a-stranded-session-ends).
75
75
 
76
- A reset ends the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, the reset fails without ending the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the reset delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. A reset that fails partway through can be retried.
76
+ An explicit `end()` retires the stranded session without running any of its code and waits for its channel addresses to be released. If another run has taken ownership in the meantime, ending fails without retiring the new owner and can be retried. The stranded session's `session.ended` hooks do not run; a replacement session runs `session.started` as usual. eve attempts to record the end delivery and a `session.ended` fact with `outcome: "failed"` and error code `session_stranded`, then close the old stream. Publication is best effort: unavailable storage or a stalled write does not prevent retirement, so a terminal fact may be missing. An end that fails partway through can be retried.
77
77
 
78
- Each reset logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`.
78
+ Each retirement logs a `warn` record, `Reset stranded session`, with the previous session ID, both eve versions, and the `trigger`: `message`, `reset`, or `timeout`. The internal command and log value remain `reset` for compatibility; the public control is `end()`.
79
79
 
80
- A reset cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit reset leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session is reset. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
80
+ Ending a session cannot be undone. A fresh session started by a message can read at most the stranded conversation's text; an explicit end leaves the next session no link to the stranded one. Rolling back to the eve version that built a session helps only before the session ends. On a world other than Vercel Workflow, pin the exact eve version in `package.json` so upgrades happen only when you choose them.
81
81
 
82
82
  #### What a replacement session receives
83
83
 
@@ -135,9 +135,9 @@ The transcript is context only: tools, approvals, files, sandbox contents, autho
135
135
 
136
136
  #### How a stranded session ends
137
137
 
138
- A stranded root session ends on its next channel message, a reset, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
138
+ A stranded root session ends on its next channel message, an explicit end, or its [session timeout](../agent-config#runtime-limits), whichever comes first. It executes nothing while it waits. When the local world or Postgres recovers active runs at startup, eve acknowledges the root session's delivery without replaying it and logs a warning naming the run and both eve versions. The run keeps its `pending` or `running` status and its addresses. A later restart skips it the same way.
139
139
 
140
- The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or a reset, just as a healthy one would stay open.
140
+ The timeout is the session's own durable timer, which its last owner armed for the end of an idle window (30 days by default). An owner re-arms the timer only when the timer fires before the window ends, so a stranded session ends at most `sessionTimeoutMs` after its last turn settled, and possibly sooner. The timer still works after the upgrade. When it fires on a stranded session, it retires the session without starting a fresh one. The next message to the address then starts an ordinary session. A session with `sessionTimeoutMs: false` has no timer, so a stranded one stays until a message or an explicit end, just as a healthy one would stay open.
141
141
 
142
142
  Ending a root session does not immediately cancel its subagent sessions and workflow tool runs. Each is retired when a delivery for it reaches the current deployment, and the runtime logs identify the stranded run. A run that never receives a delivery, such as one parked in a dormant `eve dev` generation, can stay active; cancel it in your Workflow world if you need to. Cancellation does not run authored cleanup or lifecycle hooks, undo side effects, or stop independent external jobs, and results and approvals do not carry over to a replacement session.
143
143
 
@@ -262,7 +262,7 @@ session claims both its stable session-ID inbox and its initial channel address
262
262
  before processing the first turn, and fails creation if another run already
263
263
  owns the channel address. Aliasing adds another continuation address to the
264
264
  same session; every previously claimed address remains active until the session
265
- ends or resets. An ID-only HTTP session has the stable inbox and no channel
265
+ ends. An ID-only HTTP session has the stable inbox and no channel
266
266
  continuation address. When cold starts race for the same address, the losing
267
267
  candidate forwards its accepted message to the owner and exits.
268
268
 
@@ -18,7 +18,7 @@ The app runtime is the trusted side. Your tool implementations, model calls, con
18
18
 
19
19
  The sandbox is the isolated side. The model runs shell commands and accesses files there through the default `bash`, `read_file`, and `write_file` tools and any opt-in sandbox tools such as `glob` and `grep`. It gets its own `/workspace` filesystem, but no `process.env`, no secrets, and no path back into the app runtime. (On Vercel, each sandbox is a [Vercel Sandbox](https://vercel.com/docs/sandbox) microVM with hardware-level isolation.) Only shell commands execute in the sandbox. Even the built-in `bash`/`read_file`/`write_file` tools live in the app runtime and _proxy_ into the sandbox. The model sees tool definitions and results, never your secrets.
20
20
 
21
- The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
21
+ The [just-bash provider](../sandbox/just-bash) has a weaker boundary. Its shell is a JavaScript interpreter with a virtual filesystem that runs inside the app runtime process, not a separate container or VM. It provides no network isolation, and any `experimental.customCommands` you register run as host application code outside the virtual filesystem. Use a Vercel or Docker sandbox when the model runs commands you would not run in the app runtime.
22
22
 
23
23
  A concrete trace makes the boundary clear. When the model calls a custom `charge_card` tool, its `execute` runs in the app runtime, reads `process.env.STRIPE_KEY`, calls Stripe, and returns `{ ok: true }`. The model sees only `{ ok: true }`: the key never leaves the app runtime, and nothing about the call touches the sandbox. The built-in `write_file` is the mirror image, running in the app runtime and proxying the write into the sandbox `/workspace`. Either way the model drives the work through tool calls and their results, never by holding a credential or reaching the runtime directly.
24
24
 
@@ -41,7 +41,7 @@ flowchart LR
41
41
  eve sends data where your agent configuration and runtime choices send it:
42
42
 
43
43
  - Inbound channel data flows through the channel provider you configure, then into the eve app runtime.
44
- - Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider-authored `LanguageModel`.
44
+ - Model inputs and outputs flow to the model or routing path selected in `agent.ts`, such as a Vercel AI Gateway model id or a provider model instance (`EveLanguageModel`).
45
45
  - Tool and connection calls flow to the external services, MCP servers, OpenAPI endpoints, and channels you configure.
46
46
  - Sandbox commands can reach network destinations allowed by the sandbox network policy.
47
47
  - Telemetry flows to destinations configured under `agent/instrumentation/`.
@@ -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
 
@@ -120,7 +120,7 @@ export default defineHook({
120
120
 
121
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).
122
122
 
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; `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).
124
124
 
125
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).
126
126
 
@@ -134,6 +134,7 @@ export default defineHook({
134
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).
135
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).
136
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).
137
138
  - `grep` lists matching files by default. Set `outputMode: "content"` when the caller needs matching lines; see [Built-in tools](./built-in-tools#grep).
138
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).
139
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).
@@ -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,7 +84,11 @@ 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
- When present, the installed package's `node_modules/eve/dist/CHANGELOG.md` contains that version's release notes and a link to the full changelog through that version. Older packages contain the full history at `node_modules/eve/CHANGELOG.md` instead. 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`.
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.
88
92
 
89
93
  ## Continue with the tutorial
90
94
 
@@ -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()`.
@@ -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);