eve 0.85.0 → 0.87.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (290) hide show
  1. package/CHANGELOG.md +34 -3073
  2. package/README.md +7 -4
  3. package/dist/src/acp/adapter.d.ts +2 -26
  4. package/dist/src/acp/adapter.js +1 -1
  5. package/dist/src/acp/server.d.ts +0 -3
  6. package/dist/src/ai/decision-adapter.d.ts +5 -3
  7. package/dist/src/ai/decision-adapter.js +1 -1
  8. package/dist/src/ai/decision-types.d.ts +4 -3
  9. package/dist/src/channel/adapter.d.ts +0 -14
  10. package/dist/src/channel/auth/definitions.d.ts +0 -4
  11. package/dist/src/channel/channel-address.d.ts +1 -1
  12. package/dist/src/channel/channel-address.js +1 -1
  13. package/dist/src/channel/channel-operations.d.ts +2 -2
  14. package/dist/src/channel/channel-operations.js +1 -1
  15. package/dist/src/channel/prompt-queue.d.ts +0 -2
  16. package/dist/src/channel/session-not-active-error.d.ts +10 -5
  17. package/dist/src/channel/session-not-active-error.js +1 -1
  18. package/dist/src/channel/session-stranded-error.d.ts +1 -1
  19. package/dist/src/channel/session.d.ts +3 -4
  20. package/dist/src/channel/session.js +1 -1
  21. package/dist/src/channel/types.d.ts +5 -14
  22. package/dist/src/chunks/{use-eve-agent-B2jCfcnG.js → use-eve-agent-BExXjBv6.js} +82 -72
  23. package/dist/src/chunks/{use-eve-agent-DCLFi26P.js → use-eve-agent-C0KHCyb9.js} +82 -72
  24. package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
  25. package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
  26. package/dist/src/cli/dev/command-options.d.ts +4 -4
  27. package/dist/src/cli/dev/command.js +1 -1
  28. package/dist/src/cli/dev/tui/runner.d.ts +1 -1
  29. package/dist/src/cli/dev/tui/runner.js +2 -2
  30. package/dist/src/cli/dev/tui/test/fake-eve-server.js +1 -1
  31. package/dist/src/cli/dev/tui/tool-format.d.ts +2 -2
  32. package/dist/src/cli/dev/ui-options.d.ts +4 -4
  33. package/dist/src/cli/dev/ui-options.js +1 -1
  34. package/dist/src/cli/run.js +1 -1
  35. package/dist/src/client/agent-info-error.d.ts +4 -1
  36. package/dist/src/client/agent-info-error.js +1 -1
  37. package/dist/src/client/agent-session.d.ts +1 -4
  38. package/dist/src/client/agent-session.js +1 -1
  39. package/dist/src/client/agent-stream-follower.js +1 -1
  40. package/dist/src/client/client-error.d.ts +13 -4
  41. package/dist/src/client/client-error.js +1 -1
  42. package/dist/src/client/delivery.d.ts +2 -17
  43. package/dist/src/client/health-response-error.d.ts +4 -1
  44. package/dist/src/client/health-response-error.js +1 -1
  45. package/dist/src/client/index.d.ts +5 -3
  46. package/dist/src/client/index.js +1 -1
  47. package/dist/src/client/open-stream.d.ts +7 -12
  48. package/dist/src/client/open-stream.js +1 -1
  49. package/dist/src/client/session-controls.d.ts +2 -2
  50. package/dist/src/client/session-controls.js +1 -1
  51. package/dist/src/client/session-event-stream.d.ts +2 -2
  52. package/dist/src/client/session-event-stream.js +1 -1
  53. package/dist/src/client/session-store.d.ts +2 -6
  54. package/dist/src/client/session-store.js +1 -1
  55. package/dist/src/client/session.d.ts +4 -13
  56. package/dist/src/client/session.js +1 -1
  57. package/dist/src/client/sessions.d.ts +3 -6
  58. package/dist/src/client/types.d.ts +23 -32
  59. package/dist/src/compiled/.vendor-stamp.json +4 -4
  60. package/dist/src/compiled/@vercel/agent-runs/LICENSE +202 -0
  61. package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
  62. package/dist/src/compiled/@vercel/schedules/index.js +2 -2
  63. package/dist/src/compiler/manifest.js +1 -1
  64. package/dist/src/compiler/normalize-agent-config.js +1 -1
  65. package/dist/src/compiler/normalize-connection.d.ts +1 -1
  66. package/dist/src/compiler/normalize-connection.js +1 -1
  67. package/dist/src/compiler/normalize-instructions.js +1 -1
  68. package/dist/src/compiler/normalize-skill.js +1 -1
  69. package/dist/src/compiler/resolve-workspace-subagent.js +1 -1
  70. package/dist/src/context/memory-tools.d.ts +9 -5
  71. package/dist/src/discover/sandbox.js +1 -1
  72. package/dist/src/dynamic/definition.d.ts +11 -5
  73. package/dist/src/dynamic/definition.js +1 -1
  74. package/dist/src/evals/mock-model.d.ts +1 -1
  75. package/dist/src/evals/session-manager.d.ts +0 -2
  76. package/dist/src/evals/session.d.ts +1 -11
  77. package/dist/src/evals/session.js +1 -1
  78. package/dist/src/eve-channel/index.js +1 -1
  79. package/dist/src/eve-channel/support.js +1 -1
  80. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  81. package/dist/src/execution/effective-agent-config.js +1 -1
  82. package/dist/src/execution/proxied-deliver-step.js +1 -1
  83. package/dist/src/execution/sandbox/bindings/just-bash-runtime.d.ts +1 -2
  84. package/dist/src/execution/sandbox/bindings/just-bash-runtime.js +1 -1
  85. package/dist/src/execution/sandbox/bindings/just-bash.js +1 -1
  86. package/dist/src/execution/session/active-turn.js +1 -1
  87. package/dist/src/execution/session/answer-caller.d.ts +9 -5
  88. package/dist/src/execution/session/answer-caller.js +1 -1
  89. package/dist/src/execution/session/principal.d.ts +8 -0
  90. package/dist/src/execution/session/principal.js +1 -1
  91. package/dist/src/execution/session/program.js +1 -1
  92. package/dist/src/execution/session/turn-step.js +1 -1
  93. package/dist/src/execution/session/turn.js +1 -1
  94. package/dist/src/execution/session-callback-request.js +1 -1
  95. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  96. package/dist/src/harness/attachment-staging.d.ts +2 -2
  97. package/dist/src/harness/attachment-staging.js +1 -1
  98. package/dist/src/instrumentation/ai-sdk-telemetry.d.ts +0 -2
  99. package/dist/src/instrumentation/providers.d.ts +1 -38
  100. package/dist/src/instrumentation/providers.js +1 -1
  101. package/dist/src/instrumentation/setup-context.d.ts +1 -7
  102. package/dist/src/internal/application/package.d.ts +1 -0
  103. package/dist/src/internal/application/package.js +1 -1
  104. package/dist/src/internal/application/stamped-package-version.js +1 -1
  105. package/dist/src/internal/authored-definition/core.js +1 -1
  106. package/dist/src/internal/authored-definition/schema-backed.js +1 -1
  107. package/dist/src/internal/classify-model-routing.d.ts +2 -3
  108. package/dist/src/internal/nitro/host/create-application-nitro.js +1 -1
  109. package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
  110. package/dist/src/internal/runtime-model.d.ts +9 -4
  111. package/dist/src/internal/runtime-model.js +1 -1
  112. package/dist/src/internal/workflow-bundle/authored-workflow-directives.js +1 -1
  113. package/dist/src/internal/workflow-bundle/builder-support.d.ts +1 -1
  114. package/dist/src/internal/workflow-bundle/builder-support.js +1 -1
  115. package/dist/src/internal/workflow-bundle/workflow-transformer.js +1 -1
  116. package/dist/src/models/auto.js +1 -1
  117. package/dist/src/protocol/delivery.d.ts +1 -0
  118. package/dist/src/protocol/reset-session.d.ts +0 -2
  119. package/dist/src/protocol/routes.d.ts +9 -2
  120. package/dist/src/protocol/routes.js +1 -1
  121. package/dist/src/public/channels/chat-sdk/chatSdkChannel.d.ts +1 -22
  122. package/dist/src/public/channels/discord/discordChannel.d.ts +3 -12
  123. package/dist/src/public/channels/discord/gateway/{index.d.ts → relay.d.ts} +2 -2
  124. package/dist/src/public/channels/discord/gateway/relay.js +1 -0
  125. package/dist/src/public/channels/discord/messages.d.ts +4 -4
  126. package/dist/src/public/channels/github/state.d.ts +0 -2
  127. package/dist/src/public/channels/index.d.ts +1 -2
  128. package/dist/src/public/channels/index.js +1 -1
  129. package/dist/src/public/channels/linear/index.d.ts +1 -1
  130. package/dist/src/public/channels/linear/index.js +1 -1
  131. package/dist/src/public/channels/linear/linearChannel.d.ts +0 -5
  132. package/dist/src/public/channels/linq/index.d.ts +1 -1
  133. package/dist/src/public/channels/linq/linqChannel.d.ts +7 -5
  134. package/dist/src/public/channels/photon/index.d.ts +1 -1
  135. package/dist/src/public/channels/photon/photonIMessageChannel.d.ts +15 -4
  136. package/dist/src/public/channels/slack/api.d.ts +1 -1
  137. package/dist/src/public/channels/slack/api.js +1 -1
  138. package/dist/src/public/channels/slack/blocks.d.ts +1 -1
  139. package/dist/src/public/channels/slack/blocks.js +2 -2
  140. package/dist/src/public/channels/slack/cards.d.ts +2 -297
  141. package/dist/src/public/channels/slack/cards.js +1 -1
  142. package/dist/src/public/channels/slack/index.d.ts +2 -2
  143. package/dist/src/public/channels/slack/index.js +1 -1
  144. package/dist/src/public/channels/slack/session-operations.d.ts +2 -2
  145. package/dist/src/public/channels/slack/session-operations.js +1 -1
  146. package/dist/src/public/channels/slack/slackChannel.d.ts +11 -72
  147. package/dist/src/public/channels/slack/slackChannel.js +1 -1
  148. package/dist/src/public/channels/teams/teamsChannel.d.ts +4 -3
  149. package/dist/src/public/channels/telegram/hitl.d.ts +2 -9
  150. package/dist/src/public/channels/telegram/index.d.ts +1 -1
  151. package/dist/src/public/channels/telegram/telegramChannel.d.ts +0 -2
  152. package/dist/src/public/channels/twilio/twilioChannel.d.ts +0 -2
  153. package/dist/src/public/channels/undelivered-reply.d.ts +0 -5
  154. package/dist/src/public/definitions/agent.d.ts +15 -7
  155. package/dist/src/public/definitions/agent.js +1 -1
  156. package/dist/src/public/definitions/channel.d.ts +7 -5
  157. package/dist/src/public/definitions/channel.js +1 -1
  158. package/dist/src/public/definitions/connections/protocol.d.ts +1 -7
  159. package/dist/src/public/definitions/connections/protocol.js +1 -1
  160. package/dist/src/public/experimental/channels/discord/gateway.d.ts +1 -0
  161. package/dist/src/public/experimental/channels/discord/gateway.js +1 -0
  162. package/dist/src/public/experimental/sandbox/just-bash.d.ts +1 -0
  163. package/dist/src/public/experimental/sandbox/just-bash.js +1 -0
  164. package/dist/src/public/experimental/workspace/index.d.ts +1 -0
  165. package/dist/src/public/experimental/workspace/index.js +1 -0
  166. package/dist/src/public/index.d.ts +2 -2
  167. package/dist/src/public/index.js +1 -1
  168. package/dist/src/public/instrumentation/otel.d.ts +1 -1
  169. package/dist/src/public/instrumentation/provider.d.ts +1 -1
  170. package/dist/src/public/instrumentation/provider.js +1 -1
  171. package/dist/src/public/memory/file/backend.d.ts +1 -1
  172. package/dist/src/public/memory/file/backends/in-memory.js +1 -1
  173. package/dist/src/public/memory/file/backends/vercel-blob.js +1 -1
  174. package/dist/src/public/memory/file/provider.js +1 -1
  175. package/dist/src/public/memory/index.d.ts +3 -11
  176. package/dist/src/public/models/anthropic/index.d.ts +1 -1
  177. package/dist/src/public/models/index.d.ts +1 -0
  178. package/dist/src/public/models/openai/index.d.ts +2 -2
  179. package/dist/src/public/next/index.d.ts +2 -2
  180. package/dist/src/public/sandbox/just-bash-sandbox.d.ts +27 -20
  181. package/dist/src/public/sandbox/just-bash.d.ts +0 -1
  182. package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
  183. package/dist/src/public/schedules/providers/vercel.js +1 -1
  184. package/dist/src/public/sessions/index.d.ts +1 -0
  185. package/dist/src/public/sessions/index.js +1 -1
  186. package/dist/src/public/tools/index.d.ts +1 -1
  187. package/dist/src/public/tools/index.js +1 -1
  188. package/dist/src/public/workflow/api.d.ts +25 -0
  189. package/dist/src/public/workflow/api.js +1 -0
  190. package/dist/src/public/workflow/index.d.ts +76 -0
  191. package/dist/src/public/workflow/index.js +1 -0
  192. package/dist/src/public/workflow-modules.d.ts +2 -17
  193. package/dist/src/react/use-eve-agent.d.ts +3 -2
  194. package/dist/src/react/use-eve-agent.js +1 -1
  195. package/dist/src/reactions/kinds/model.js +1 -1
  196. package/dist/src/runtime/agent/resolve-model.js +1 -1
  197. package/dist/src/runtime/resolve-agent.js +1 -1
  198. package/dist/src/runtime/resolve-dynamic.js +1 -1
  199. package/dist/src/runtime/subagents/dynamic-agent-config.js +1 -1
  200. package/dist/src/runtime/subagents/workflow.js +1 -1
  201. package/dist/src/sandbox/providers/default.js +1 -1
  202. package/dist/src/self-modification/extension/subagents/agent/agent.d.ts +2 -2
  203. package/dist/src/self-modification/sandbox.js +1 -1
  204. package/dist/src/setup/integrations/discord/daemon.js +2 -2
  205. package/dist/src/setup/scaffold/create/project.js +2 -2
  206. package/dist/src/setup/scaffold/create/web-template.d.ts +2 -2
  207. package/dist/src/setup/scaffold/create/web-template.js +2 -2
  208. package/dist/src/setup/verified-remote-agent.d.ts +1 -3
  209. package/dist/src/shared/agent-definition.d.ts +18 -9
  210. package/dist/src/shared/eve-error.d.ts +22 -0
  211. package/dist/src/shared/eve-error.js +1 -0
  212. package/dist/src/shared/session.d.ts +2 -2
  213. package/dist/src/shared/token-usage.d.ts +7 -1
  214. package/dist/src/svelte/index.js +1 -1
  215. package/dist/src/svelte/use-eve-agent.d.ts +2 -1
  216. package/dist/src/svelte/use-eve-agent.js +1 -1
  217. package/dist/src/tools/definition.d.ts +7 -5
  218. package/dist/src/tools/definition.js +1 -1
  219. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  220. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  221. package/dist/src/tracing/eve/batch-span-processor.d.ts +1 -1
  222. package/dist/src/tracing/eve/content-span-processor.d.ts +1 -19
  223. package/dist/src/tracing/eve/otel-configuration.d.ts +6 -0
  224. package/dist/src/tracing/eve/otel-declaration.d.ts +6 -19
  225. package/dist/src/tracing/eve/span-export-policy.d.ts +0 -2
  226. package/dist/src/tracing/local/instrumentation-runtime.d.ts +0 -3
  227. package/dist/src/tracing/local/traces.d.ts +0 -13
  228. package/dist/src/vue/index.js +1 -1
  229. package/dist/src/vue/use-eve-agent.d.ts +3 -2
  230. package/dist/src/vue/use-eve-agent.js +1 -1
  231. package/docs/agent-config.md +15 -11
  232. package/docs/channels/custom.mdx +26 -10
  233. package/docs/channels/discord.mdx +10 -10
  234. package/docs/channels/eve.mdx +15 -13
  235. package/docs/channels/linear.mdx +11 -0
  236. package/docs/channels/linq.mdx +5 -1
  237. package/docs/channels/photon.mdx +6 -1
  238. package/docs/channels/slack.mdx +73 -14
  239. package/docs/channels/telegram.mdx +6 -0
  240. package/docs/code-extension.mdx +25 -0
  241. package/docs/concepts/default-harness.md +2 -2
  242. package/docs/concepts/execution-model-and-durability.mdx +11 -11
  243. package/docs/concepts/project-structure.mdx +1 -1
  244. package/docs/concepts/security-model.md +6 -2
  245. package/docs/concepts/sessions-runs-and-streaming.md +23 -10
  246. package/docs/concepts/upgrade-to-v27-events.md +70 -1
  247. package/docs/connections/overview.mdx +4 -0
  248. package/docs/evals/reporters.mdx +21 -0
  249. package/docs/extensions.md +12 -0
  250. package/docs/getting-started.mdx +6 -0
  251. package/docs/guides/auth-and-route-protection.md +2 -1
  252. package/docs/guides/client/continuations.mdx +12 -10
  253. package/docs/guides/client/messages.mdx +24 -1
  254. package/docs/guides/client/overview.mdx +8 -6
  255. package/docs/guides/client/streaming.mdx +25 -7
  256. package/docs/guides/decide.md +3 -3
  257. package/docs/guides/deployment/self-hosting.md +1 -1
  258. package/docs/guides/deployment/vercel.mdx +1 -1
  259. package/docs/guides/dev-tui.md +2 -2
  260. package/docs/guides/frontend/meta.json +1 -0
  261. package/docs/guides/frontend/nextjs.mdx +329 -121
  262. package/docs/guides/frontend/overview.mdx +115 -335
  263. package/docs/guides/frontend/tanstack.mdx +1 -1
  264. package/docs/guides/frontend/use-eve-agent-svelte.mdx +18 -16
  265. package/docs/guides/frontend/use-eve-agent-vue.mdx +18 -16
  266. package/docs/guides/frontend/use-eve-agent.mdx +385 -0
  267. package/docs/guides/hooks.md +1 -1
  268. package/docs/guides/instrumentation/otel.mdx +3 -1
  269. package/docs/guides/prepare-for-1-0.md +255 -0
  270. package/docs/guides/remote-agents.md +26 -22
  271. package/docs/guides/self-modification.md +6 -0
  272. package/docs/instructions.mdx +1 -1
  273. package/docs/memory/custom-provider.md +1 -1
  274. package/docs/memory/file.md +11 -2
  275. package/docs/meta.json +1 -0
  276. package/docs/reference/agent-files.md +17 -17
  277. package/docs/reference/cli.md +15 -11
  278. package/docs/reference/typescript-api.md +46 -20
  279. package/docs/sandbox/custom-providers.mdx +2 -0
  280. package/docs/sandbox/default.mdx +6 -6
  281. package/docs/sandbox/index.mdx +6 -6
  282. package/docs/sandbox/just-bash.mdx +30 -21
  283. package/docs/subagents/index.mdx +4 -4
  284. package/docs/tools/human-in-the-loop.md +1 -1
  285. package/docs/tools/workflows.mdx +52 -8
  286. package/docs/tutorial/first-agent.mdx +1 -1
  287. package/package.json +46 -27
  288. package/dist/src/public/channels/discord/gateway/index.js +0 -1
  289. package/dist/src/self-modification/agent.d.ts +0 -12
  290. package/dist/src/self-modification/agent.js +0 -1
@@ -60,7 +60,7 @@ Then configure the public `https://…/eve/v1/discord` route as the application'
60
60
 
61
61
  ## Reply to DMs and mentions (experimental)
62
62
 
63
- Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway), not as HTTP Interactions. Gateway support is experimental, and its API may change. To receive them, run `experimental_runDiscordGatewayRelay` from `eve/channels/discord/gateway` in a process that stays connected, and enable the matching route on the channel. The relay forwards each `MESSAGE_CREATE` dispatch to the agent unchanged, and the channel replies through the same handlers it uses for commands, including HITL buttons and error messages.
63
+ Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway), not as HTTP Interactions. Gateway support is experimental, and its API may change. To receive them, run `runDiscordGatewayRelay` from `eve/experimental/channels/discord/gateway` in a process that stays connected, and enable the matching route on the channel. The relay forwards each `MESSAGE_CREATE` dispatch to the agent unchanged, and the channel replies through the same handlers it uses for commands, including HITL buttons and error messages.
64
64
 
65
65
  ```text
66
66
  Discord Gateway ── WebSocket ──▶ relay (Vercel Daemon) ── POST /eve/v1/discord/gateway ──▶ agent ── REST ──▶ Discord
@@ -88,9 +88,9 @@ A Vercel Daemon keeps the relay connected. Vercel Daemons are in beta. When you
88
88
 
89
89
  ```ts title="daemon/main.ts"
90
90
  import { connectDiscordCredentials } from "@vercel/connect/eve";
91
- import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
91
+ import { runDiscordGatewayRelay } from "eve/experimental/channels/discord/gateway";
92
92
 
93
- await experimental_runDiscordGatewayRelay({
93
+ await runDiscordGatewayRelay({
94
94
  credentials: connectDiscordCredentials("discord/my-agent"),
95
95
  messageContent: false,
96
96
  url: process.env.EVE_URL,
@@ -145,7 +145,7 @@ https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applic
145
145
 
146
146
  ### Run the relay outside Vercel
147
147
 
148
- `experimental_runDiscordGatewayRelay` runs on any host that keeps a Node.js 24 process up, such as a VM, a container platform, or a home server, while the agent stays on Vercel. Run exactly one relay per bot. Three things change off Vercel:
148
+ `runDiscordGatewayRelay` runs on any host that keeps a Node.js 24 process up, such as a VM, a container platform, or a home server, while the agent stays on Vercel. Run exactly one relay per bot. Three things change off Vercel:
149
149
 
150
150
  - **Credentials.** Vercel Connect authenticates callers with your project's Vercel OIDC token, which other hosts don't have, so give the relay the bot token directly. The agent can keep using Connect.
151
151
  - **URL.** The relay can't read `VERCEL_PROJECT_PRODUCTION_URL`, so pass the agent's URL as `url`.
@@ -173,9 +173,9 @@ On the relay, set `DISCORD_BOT_TOKEN` to the token from **Bot** → **Reset Toke
173
173
 
174
174
  ```ts title="relay/main.ts"
175
175
  import { httpBasic } from "eve/agents/auth";
176
- import { experimental_runDiscordGatewayRelay } from "eve/channels/discord/gateway";
176
+ import { runDiscordGatewayRelay } from "eve/experimental/channels/discord/gateway";
177
177
 
178
- await experimental_runDiscordGatewayRelay({
178
+ await runDiscordGatewayRelay({
179
179
  // Reads DISCORD_BOT_TOKEN when `credentials` is omitted.
180
180
  url: process.env.EVE_URL,
181
181
  auth: httpBasic({ username: "discord-relay", password: process.env.DISCORD_RELAY_SECRET! }),
@@ -207,7 +207,7 @@ A mention in a text channel starts a thread, as the Slack channel does, so each
207
207
 
208
208
  Mention the bot's user, not the role with the same name that Discord creates for it. Discord's autocomplete offers both, and a role mention doesn't address the bot.
209
209
 
210
- Discord sends the text of messages that neither mention the bot nor arrive as a DM only to bots with the privileged **Message Content** intent. Without it, thread follow-ups that skip the mention, and replies whose author turned off the reply ping, arrive empty and are ignored. `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, which it does for bots in fewer than 100 servers. Otherwise, enable **Message Content Intent** under **Bot** in the Discord Developer Portal, then pass `messageContent: true` to `experimental_runDiscordGatewayRelay`. Discord refuses the relay's connection if you request the intent before enabling it, and the relay stops with an error naming the close code.
210
+ Discord sends the text of messages that neither mention the bot nor arrive as a DM only to bots with the privileged **Message Content** intent. Without it, thread follow-ups that skip the mention, and replies whose author turned off the reply ping, arrive empty and are ignored. `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, which it does for bots in fewer than 100 servers. Otherwise, enable **Message Content Intent** under **Bot** in the Discord Developer Portal, then pass `messageContent: true` to `runDiscordGatewayRelay`. Discord refuses the relay's connection if you request the intent before enabling it, and the relay stops with an error naming the close code.
211
211
 
212
212
  To choose which messages run the agent, under what `auth`, or which session they join, set `gateway.onMessage(ctx, message)`. It runs for every message from a person and returns `{ auth }` to dispatch or `null` to ignore. `message.addressed` reports whether the default would answer, and `message.referencedMessageId` names the message it replies to. `defaultDiscordMessageAuth(message)` gives the author the same principal `defaultDiscordAuth` gives them for commands and button presses, so requester-only approvals work across both:
213
213
 
@@ -278,7 +278,7 @@ export default discordChannel({
278
278
 
279
279
  ### Forward messages from your own relay
280
280
 
281
- The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot, so you don't have to run `experimental_runDiscordGatewayRelay`. Forward each Gateway dispatch payload unchanged, as the JSON body of a `POST` to `/eve/v1/discord/gateway`:
281
+ The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot, so you don't have to run `runDiscordGatewayRelay`. Forward each Gateway dispatch payload unchanged, as the JSON body of a `POST` to `/eve/v1/discord/gateway`:
282
282
 
283
283
  ```json
284
284
  {
@@ -301,7 +301,7 @@ The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without
301
301
  | `429` | Rate limited before the route ran. | Retry with backoff. |
302
302
  | `5xx` | Unknown. The route answers `500` before dispatch when `onMessage` throws, but a platform `502` or `504` can come after a turn started. | Not retry, unless your relay deduplicates. |
303
303
 
304
- eve does not deduplicate messages. If the relay retries after eve already started a turn, for example because the response was lost, the agent answers twice. `experimental_runDiscordGatewayRelay` retries only a `429`, or a connection that failed before the request reached eve.
304
+ eve does not deduplicate messages. If the relay retries after eve already started a turn, for example because the response was lost, the agent answers twice. `runDiscordGatewayRelay` retries only a `429`, or a connection that failed before the request reached eve.
305
305
 
306
306
  ### Run the relay locally
307
307
 
@@ -317,7 +317,7 @@ Scale the production daemon to zero while you do this. Every connection receives
317
317
 
318
318
  - Run one relay per bot. Each connection receives every message. Bots large enough to need Discord's sharding are out of scope.
319
319
  - Messages sent while no relay is connected are not delivered. On a deploy, Vercel sends `SIGTERM` to the old daemon and starts the new one at the same time. The old relay disconnects right away, so messages sent while the new daemon boots and connects, usually a few seconds, are lost. A crash or restart leaves the same gap. The relay does not resume the previous Gateway session in a new process, so Discord does not replay these messages.
320
- - `experimental_runDiscordGatewayRelay` drops a message, rather than retrying it, when eve answers with a `5xx`, takes longer than 30 seconds to accept it, or the connection fails after the request is sent. eve may have started the turn already, and a retry could answer twice. The relay logs each dropped message.
320
+ - `runDiscordGatewayRelay` drops a message, rather than retrying it, when eve answers with a `5xx`, takes longer than 30 seconds to accept it, or the connection fails after the request is sent. eve may have started the turn already, and a retry could answer twice. The relay logs each dropped message.
321
321
 
322
322
  ## How the channel handles messages
323
323
 
@@ -35,10 +35,6 @@ eve link
35
35
  eve add channel/web
36
36
  ```
37
37
 
38
- `eve init --channel-web-nextjs` keeps its existing scaffolding behavior and does
39
- not provision authentication. Sign-in setup runs through `eve add channel/web`
40
- or the terminal UI's channel picker.
41
-
42
38
  The generated Next.js app uses Better Auth sessions. The selected agent's HTTP
43
39
  channel verifies the same session, while retaining Vercel OIDC and local
44
40
  development access. In an agent workspace, setup configures only the selected
@@ -95,7 +91,7 @@ The default eve channel inspects the agent, creates sessions, accepts callbacks
95
91
  - `POST /eve/v1/session/:sessionId/cancel` (cancel the in-flight turn)
96
92
  - `POST /eve/v1/session/:sessionId/clear` (clear the session's model history)
97
93
  - `POST /eve/v1/session/:sessionId/compact` (compact the session's context)
98
- - `POST /eve/v1/session/:sessionId/reset` (retire the session)
94
+ - `POST /eve/v1/session/:sessionId/end` (retire the session)
99
95
  - `GET /eve/v1/session/:sessionId/stream` (stream events as NDJSON)
100
96
 
101
97
  The session routes use only durable session IDs. Create a session explicitly, then put its returned ID in every follow-up, control, and stream path.
@@ -109,7 +105,7 @@ deployment, `accepted` (HTTP 202) when a background preparation hint has been qu
109
105
  `unsupported` when the World or owner cannot prepare, or `no_active_session` when no live
110
106
  owner exists. Other successful statuses use HTTP 200. Acceptance does not mean the handoff
111
107
  has completed. Idle preparation preserves the session ID, stream, history, and expiry;
112
- active work is not interrupted. See the [frontend guide](../guides/frontend/overview#returned-state)
108
+ active work is not interrupted. See the [frontend guide](../guides/frontend/use-eve-agent#prewarming)
113
109
  for client usage and deployment routing.
114
110
 
115
111
  `GET /eve/v1/health` is public and returns `{ ok: true, status: "ready", workflowId: string }`. `GET /eve/v1/info` uses the channel's auth policy and returns agent-info version 6. The TypeScript client validates both successful payloads: malformed health JSON throws `HealthResponseError`, malformed inspection JSON throws `AgentInfoResponseError`, and a non-success response from either route throws `ClientError`.
@@ -130,7 +126,7 @@ repeating the request with the same key returns the same `deliveryId`, and the i
130
126
  again. Unlike a channel's [retried deliveries](./custom#retried-deliveries), whose duplicates get a
131
127
  new receipt settled `ignored`, the repeat's receipt is the original's. The session remembers its
132
128
  last 1,024 keys, so use a new key for new input. The compact and clear routes
133
- accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; reset accepts `reason`.
129
+ accept no body fields; omit the body or send `{}`. Cancel accepts `turnId`; end accepts `reason`.
134
130
 
135
131
  Open payload objects such as `clientContext` keep their existing contracts. Delegated requests
136
132
  with a `callback` accept, and ignore, the retired `activityObserver` field so older senders keep
@@ -242,7 +238,7 @@ export default eveChannel({
242
238
 
243
239
  Stream a session as newline-delimited JSON from `GET /eve/v1/session/:sessionId/stream`. The [session protocol](../concepts/sessions-runs-and-streaming#stream-a-session) defines the event set, envelopes, cursors, and reconnection behavior.
244
240
 
245
- Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before a reset. A reset attempts to append its control delivery's `delivery.admitted` (`source: { control: "reset" }`) and `delivery.settled`, then `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }` naming that delivery, then close the stream. Existing readers finish when the stream ends.
241
+ Following a stranded session's stream returns `409 session_stranded`, just like a send. The TypeScript client reports `ClientSessionStrandedError` without retrying. Pass `follow=false` to read the recorded history instead: the response ends at the durable tail, carries the `x-eve-stream-tail-index` header, and never inspects or changes the session, so it works before ending the session. End attempts to append its control delivery's `delivery.admitted` (`source: { control: "reset" }`) and `delivery.settled`, then `session.ended` with `outcome: "failed"`, error code `session_stranded`, and cause `{ deliveryId }` naming that delivery, then close the stream. Existing readers finish when the stream ends.
246
242
 
247
243
  A session started by an eve version before v27 stores v26 events. Its stream route serves them as the v27 lines they record, so v27 clients render that history: messages, reasoning, tool calls and results, approvals, questions, sign-ins, subagents, clears, and compactions. Streamed text previews aren't translated, so a v26 session that is still running shows each part once it completes.
248
244
 
@@ -258,15 +254,17 @@ See [Cancel the in-flight turn](../concepts/sessions-runs-and-streaming#cancel-t
258
254
 
259
255
  ### Clear context
260
256
 
261
- Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `reset` route to end it instead. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
257
+ Post to `/eve/v1/session/:sessionId/clear` to remove model-message history while preserving the session ID, system prompt, tools, skills, durable state, limits, and sandbox. A stranded session cannot run the clear, so the route returns `409 session_stranded` and changes nothing; post to the `end` route instead. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
262
258
 
263
259
  ### Compact context
264
260
 
265
- Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
261
+ Post to `/eve/v1/session/:sessionId/compact` to summarize context without sending a user message. The operation waits for an active turn to settle and reports its result on the stream. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
262
+
263
+ <a id="reset-a-session" />
266
264
 
267
- ### Reset a session
265
+ ### End a session
268
266
 
269
- Post to `/eve/v1/session/:sessionId/reset` to terminally retire that session. Reset never replaces the ID automatically; create a new session explicitly for a fresh conversation. Reset also works on a stranded session: eve cancels the stranded workflow run directly instead of delivering the command to it. See [Compact, clear, and reset](../concepts/sessions-runs-and-streaming#compact-clear-and-reset).
267
+ Post to `/eve/v1/session/:sessionId/end` to terminally retire that session. End never replaces the ID automatically; create a new session explicitly for a fresh conversation. End also works on a stranded session: eve cancels the stranded workflow run directly instead of delivering the command to it. See [Compact, clear, and end](../concepts/sessions-runs-and-streaming#compact-clear-and-end).
270
268
 
271
269
  ## Replace or disable the defaults
272
270
 
@@ -344,6 +342,10 @@ export default eveChannel({
344
342
  });
345
343
  ```
346
344
 
345
+ Audience also selects the default [run-data retention](../agent-config#run-data-retention).
346
+ Outside development, private and unknown-audience sessions request deletion when
347
+ they end. The Workflow World must support deletion to enforce it.
348
+
347
349
  `audience` controls observability content capture; it does not change who may
348
350
  call the endpoint. `auth` still controls access. For a classification that
349
351
  depends on channel state or application-specific verified data, use a [custom
@@ -448,7 +450,7 @@ export default defineChannel({
448
450
 
449
451
  The client then resumes that session by id, for example with `useEveAgent({ initialSession: { sessionId, streamIndex: 0 }, resume: true })`. `created` is `false` when a session already owned the address, or another `create()` or `send()` claimed it first. That session comes back unchanged and your `history` was not added, so check `created` before treating the session as seeded. Use a new address for each new conversation or branch.
450
452
 
451
- When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `reset()` on the address, then `create()` again.
453
+ When the session at the address is [stranded](../guides/deployment/self-hosting#recover-a-stranded-session), `create()` throws `SessionStrandedError` instead of replacing it, because that session may hold the conversation you meant to import. Call `end()` on the address, then `create()` again.
452
454
 
453
455
  `create()` returns once the new session claims its address, so a `send()` right after it reaches that session. It throws if no session claims the address within 15 seconds.
454
456
 
@@ -101,6 +101,17 @@ Files uploaded to Linear and referenced in an Agent Session prompt, whether as m
101
101
 
102
102
  Event handlers receive `channel.linear`, which exposes `createActivity`, `listActivities`, and `updateSession` for custom Agent Activity delivery and Agent Session metadata.
103
103
 
104
+ ### Low-level API helpers
105
+
106
+ Import `callLinearGraphQL` and `createLinearAgentActivity` from
107
+ `eve/channels/linear` when a custom integration needs a direct API call.
108
+ `callLinearGraphQL<T>({ query, queryName, variables?, credentials?, api? })`
109
+ returns the response's `data` as `T` and throws `LinearApiError` for HTTP or
110
+ GraphQL errors. `createLinearAgentActivity({ activity, credentials?, api? })`
111
+ posts an activity to a Linear Agent Session and returns `{ id, success }`.
112
+ Both accept `credentials.accessToken` and optional API overrides; prefer the
113
+ channel context's API handle when it already has the configured credentials.
114
+
104
115
  ## Custom hooks
105
116
 
106
117
  Return `{ auth }` to dispatch, or `null` to acknowledge without waking the agent. Return `title` alongside `auth` to set the title when the dispatch starts a run.
@@ -37,10 +37,14 @@ export default linqChannel({
37
37
  });
38
38
  ```
39
39
 
40
- Set `route` to override the webhook path or `webhookVerifier` to use a different trusted-forwarder verifier. A verifier rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
40
+ Set `route` to override the webhook path or `webhookVerifier` (typed `LinqWebhookVerifier` from `eve/channels/linq`) to use a different trusted-forwarder verifier. A verifier receives the request and its raw body bytes, and rejects a webhook by throwing or returning a falsy value such as `null` or `false`.
41
41
 
42
42
  ## Tapbacks
43
43
 
44
+ `IMESSAGE_TAPBACKS` from `eve/channels/linq` lists the built-in tapback names.
45
+ Use it to populate a picker or validate a named reaction. Tapback APIs can also
46
+ accept a single emoji; the list does not enumerate those.
47
+
44
48
  eve ignores tapbacks people send unless you pass `onTapback`. It receives the tapback and returns the same result as `onMessage`, or `null` to ignore it:
45
49
 
46
50
  ```ts title="agent/channels/linq.ts"
@@ -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
 
@@ -95,7 +95,7 @@ Move its `evals/` directory, if present, to `agents/support/evals/`. Keep `packa
95
95
  Before adding the next agent:
96
96
 
97
97
  - Update `tsconfig.json` to include `agents/**/*.ts`, preserving any application includes. Update moved-file imports and path aliases, including scaffolded `package.json#imports` entries that point at `./agent/*` or `./evals/*`.
98
- - Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#dev-vs-deploy-topology).
98
+ - Update scripts that assume one agent. Use `--agent support` for agent-scoped commands; build an agent-only Vercel workspace with root `eve build`. For a Next.js app, keep the framework scripts and follow its [build instructions](/docs/guides/frontend/nextjs#run-build-and-deploy).
99
99
  - Update HTTP clients and webhook registrations for the named agent's public routes. In a root Next.js app, remove a single-agent `eveRoot` override to enable workspace discovery, and select `support` in the client hook. Store the agent name alongside durable-session links.
100
100
 
101
101
  Then add the second agent and check discovery:
@@ -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/`.
@@ -75,6 +75,10 @@ A [channel](../channels/overview) is your agent's front door, so authenticating
75
75
 
76
76
  A custom channel that accepts dashboard-style webhooks should follow the same shape: authenticate the raw body with an HMAC, compare signatures in constant time, and trust any body-supplied principal only after the signature verifies.
77
77
 
78
+ ## A turn runs as one principal
79
+
80
+ A turn's principal (its authenticator, issuer, principal type and id) never changes while the turn runs; only its claims may update. Only that principal's messages steer the turn or answer its pending questions by text. In a shared thread, another person's message waits for the turn to end and then runs as their own turn, so their text never drives the turn's credentials and the turn never continues under their identity. Another person can still settle a pending request with a button or structured answer; they are recorded as its responder, and the turn keeps its caller. See [What reaches `ctx.session.auth`](../guides/auth-and-route-protection#what-reaches-ctxsessionauth).
81
+
78
82
  ## Authored markdown is data
79
83
 
80
84
  [Skill](../skills) and [schedule](../schedules) files are markdown with YAML frontmatter, and eve treats that frontmatter strictly as data. The code-capable engines (`---js` / `---javascript`, which would `eval()` the frontmatter body the moment the file is parsed) are disabled, so such a fence throws rather than running. Frontmatter has to parse to a plain YAML object.