eve 0.89.0 → 0.91.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (247) hide show
  1. package/CHANGELOG.md +39 -9
  2. package/dist/src/channel/adapter.d.ts +12 -3
  3. package/dist/src/channel/adapter.js +1 -1
  4. package/dist/src/channel/auth/definitions.d.ts +7 -20
  5. package/dist/src/channel/auth/definitions.js +1 -1
  6. package/dist/src/channel/auth/http-basic.js +1 -1
  7. package/dist/src/channel/auth/jwt-ecdsa.js +1 -1
  8. package/dist/src/channel/auth/jwt-hmac.js +1 -1
  9. package/dist/src/channel/auth/oidc.js +1 -1
  10. package/dist/src/channel/auth/result.d.ts +2 -3
  11. package/dist/src/channel/auth/result.js +1 -1
  12. package/dist/src/channel/channel-address.d.ts +1 -1
  13. package/dist/src/channel/channel-address.js +1 -1
  14. package/dist/src/channel/channel-operations.d.ts +1 -1
  15. package/dist/src/channel/schedule.js +1 -1
  16. package/dist/src/channel/types.d.ts +2 -0
  17. package/dist/src/chunks/{use-eve-agent-Bbl4H5aA.js → use-eve-agent-Bwloorf8.js} +77 -63
  18. package/dist/src/chunks/{use-eve-agent-CNpxgKEH.js → use-eve-agent-XCB0-tLX.js} +77 -63
  19. package/dist/src/cli/dev/environment.js +1 -1
  20. package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
  21. package/dist/src/cli/dev/tui/remote-connection-probe.js +1 -1
  22. package/dist/src/cli/dev/tui/remote-connection-types.d.ts +1 -0
  23. package/dist/src/cli/dev/tui/runner.js +2 -2
  24. package/dist/src/cli/dev/tui/status-line.d.ts +2 -2
  25. package/dist/src/cli/dev/tui/status-line.js +1 -1
  26. package/dist/src/client/agent-info-schema.d.ts +341 -326
  27. package/dist/src/client/agent-info-schema.js +1 -1
  28. package/dist/src/client/agent-info-types.d.ts +13 -10
  29. package/dist/src/client/client-error.d.ts +1 -1
  30. package/dist/src/client/client.d.ts +5 -3
  31. package/dist/src/client/client.js +1 -1
  32. package/dist/src/client/session.d.ts +1 -1
  33. package/dist/src/compiled/.vendor-stamp.json +1 -1
  34. package/dist/src/evals/target.js +1 -1
  35. package/dist/src/eve-channel/auth.d.ts +19 -0
  36. package/dist/src/eve-channel/auth.js +1 -0
  37. package/dist/src/eve-channel/index.d.ts +1 -0
  38. package/dist/src/eve-channel/index.js +1 -1
  39. package/dist/src/eve-channel/types.d.ts +23 -4
  40. package/dist/src/execution/catalog/connection-entry.js +1 -1
  41. package/dist/src/execution/coordination-dispatch-shared.js +1 -1
  42. package/dist/src/execution/dynamic-workflow/tool.js +1 -1
  43. package/dist/src/execution/proxied-deliver-step.js +1 -1
  44. package/dist/src/execution/sandbox/bash.js +2 -2
  45. package/dist/src/execution/session/active-turn.js +1 -1
  46. package/dist/src/execution/session/admission.d.ts +6 -0
  47. package/dist/src/execution/session/admission.js +1 -1
  48. package/dist/src/execution/session/delivery-facts.js +1 -1
  49. package/dist/src/execution/session/next-input.d.ts +2 -2
  50. package/dist/src/execution/session/next-input.js +1 -1
  51. package/dist/src/execution/session/program.js +1 -1
  52. package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
  53. package/dist/src/execution/session-inbox/inbox.js +1 -1
  54. package/dist/src/execution/session-inbox/protocol.js +1 -1
  55. package/dist/src/execution/tools/agent-router-workflow.js +1 -1
  56. package/dist/src/harness/compaction/engine.js +2 -2
  57. package/dist/src/harness/current-messages.js +1 -1
  58. package/dist/src/harness/emission.d.ts +3 -0
  59. package/dist/src/harness/emission.js +1 -1
  60. package/dist/src/harness/facts.d.ts +5 -2
  61. package/dist/src/harness/facts.js +1 -1
  62. package/dist/src/harness/model-call/call.d.ts +7 -1
  63. package/dist/src/harness/model-call/call.js +3 -1
  64. package/dist/src/harness/provider-tool-history.d.ts +8 -0
  65. package/dist/src/harness/provider-tool-history.js +1 -1
  66. package/dist/src/harness/session-machine/transitions.d.ts +3 -2
  67. package/dist/src/harness/step/after-model.js +1 -1
  68. package/dist/src/harness/step/context.js +1 -1
  69. package/dist/src/harness/step/intake.js +1 -1
  70. package/dist/src/harness/step/prompt.js +1 -1
  71. package/dist/src/harness/tool-history-repair.d.ts +2 -0
  72. package/dist/src/harness/tool-history-repair.js +1 -1
  73. package/dist/src/harness/tool-loop.js +1 -1
  74. package/dist/src/internal/application/stamped-package-version.js +1 -1
  75. package/dist/src/internal/authored-module-graph.js +1 -1
  76. package/dist/src/internal/nitro/routes/agent-info/build-agent-info-response.d.ts +2 -2
  77. package/dist/src/protocol/routes.d.ts +7 -1
  78. package/dist/src/protocol/routes.js +1 -1
  79. package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
  80. package/dist/src/protocol/session-events/families/delivery.js +1 -1
  81. package/dist/src/protocol/session-projection/fold.js +1 -1
  82. package/dist/src/public/channels/discord/hitl.js +1 -1
  83. package/dist/src/public/channels/github/githubChannel.js +1 -1
  84. package/dist/src/public/channels/github/state.d.ts +7 -0
  85. package/dist/src/public/channels/github/state.js +1 -1
  86. package/dist/src/public/channels/mcp.js +1 -1
  87. package/dist/src/public/channels/slack/hitl.d.ts +2 -1
  88. package/dist/src/public/channels/slack/hitl.js +3 -3
  89. package/dist/src/public/channels/slack/interaction-cards.js +1 -1
  90. package/dist/src/public/channels/slack/request-card-render.js +1 -1
  91. package/dist/src/public/channels/teams/hitl.js +1 -1
  92. package/dist/src/public/channels/teams/verify.js +1 -1
  93. package/dist/src/public/channels/telegram/telegramChannel.js +1 -1
  94. package/dist/src/public/connections/index.d.ts +1 -1
  95. package/dist/src/public/definitions/channel.js +1 -1
  96. package/dist/src/public/definitions/connections/tool-call.d.ts +2 -2
  97. package/dist/src/public/definitions/hook.d.ts +90 -7
  98. package/dist/src/public/definitions/hook.js +1 -1
  99. package/dist/src/public/hooks/index.d.ts +3 -2
  100. package/dist/src/reactions/continuation.d.ts +19 -0
  101. package/dist/src/reactions/continuation.js +1 -0
  102. package/dist/src/reactions/frame.js +1 -1
  103. package/dist/src/reactions/intents.d.ts +10 -4
  104. package/dist/src/reactions/intents.js +1 -1
  105. package/dist/src/reactions/kinds/hook.js +1 -1
  106. package/dist/src/reactions/runner.js +1 -1
  107. package/dist/src/reactions/state.d.ts +15 -2
  108. package/dist/src/reactions/state.js +1 -1
  109. package/dist/src/runtime/channels/registry.d.ts +2 -2
  110. package/dist/src/runtime/channels/registry.js +1 -1
  111. package/dist/src/runtime/connections/approval-scope.d.ts +9 -0
  112. package/dist/src/runtime/connections/approval-scope.js +1 -0
  113. package/dist/src/runtime/connections/mcp-client.d.ts +1 -1
  114. package/dist/src/runtime/connections/mcp-client.js +1 -1
  115. package/dist/src/runtime/connections/provided-arguments.js +1 -1
  116. package/dist/src/runtime/resolve-connection.js +1 -1
  117. package/dist/src/runtime/subagents/workflow.js +1 -1
  118. package/dist/src/setup/primitives/open-url.js +1 -1
  119. package/dist/src/setup/scaffold/create/project.js +1 -1
  120. package/dist/src/shared/agent-info-access.d.ts +5 -0
  121. package/dist/src/shared/agent-info-access.js +1 -0
  122. package/dist/src/shared/connection-types.d.ts +21 -4
  123. package/dist/src/shared/value-delta.d.ts +5 -4
  124. package/dist/src/shared/value-delta.js +1 -1
  125. package/dist/src/svelte/index.js +1 -1
  126. package/dist/src/svelte/use-eve-agent.js +1 -1
  127. package/dist/src/tools/provided/ask-question-workflow.js +1 -1
  128. package/dist/src/tools/provided/sleep-workflow.js +1 -1
  129. package/dist/src/tools/provided/web-fetch.js +1 -1
  130. package/dist/src/vue/index.js +1 -1
  131. package/dist/src/vue/use-eve-agent.js +1 -1
  132. package/docs/agent-config.md +199 -222
  133. package/docs/channels/chat-sdk.mdx +60 -64
  134. package/docs/channels/custom.mdx +265 -280
  135. package/docs/channels/discord.mdx +176 -123
  136. package/docs/channels/eve.mdx +136 -204
  137. package/docs/channels/github.mdx +24 -22
  138. package/docs/channels/linear.mdx +30 -30
  139. package/docs/channels/linq.mdx +25 -13
  140. package/docs/channels/mcp.mdx +154 -116
  141. package/docs/channels/overview.mdx +31 -32
  142. package/docs/channels/photon.mdx +32 -56
  143. package/docs/channels/slack.mdx +538 -375
  144. package/docs/channels/teams.mdx +40 -26
  145. package/docs/channels/telegram.mdx +13 -13
  146. package/docs/channels/twilio.mdx +11 -11
  147. package/docs/code-extension.mdx +40 -42
  148. package/docs/concepts/built-in-tools.md +89 -57
  149. package/docs/concepts/context-control.md +20 -20
  150. package/docs/concepts/default-harness.md +20 -36
  151. package/docs/concepts/execution-model-and-durability.mdx +96 -160
  152. package/docs/concepts/project-structure.mdx +21 -14
  153. package/docs/concepts/security-model.md +27 -27
  154. package/docs/concepts/sessions-runs-and-streaming.md +184 -194
  155. package/docs/concepts/state.md +7 -15
  156. package/docs/connections/mcp.mdx +109 -93
  157. package/docs/connections/openapi.mdx +57 -59
  158. package/docs/connections/overview.mdx +205 -170
  159. package/docs/evals/assertions.mdx +36 -29
  160. package/docs/evals/cases.mdx +38 -42
  161. package/docs/evals/judge.mdx +21 -29
  162. package/docs/evals/overview.mdx +42 -38
  163. package/docs/evals/reporters.mdx +54 -27
  164. package/docs/evals/running.mdx +15 -8
  165. package/docs/evals/targets.mdx +17 -18
  166. package/docs/evals/tool-stubs.mdx +111 -97
  167. package/docs/experimental/dynamic-schedules.mdx +118 -63
  168. package/docs/extensions.md +58 -65
  169. package/docs/getting-started.mdx +4 -6
  170. package/docs/guides/auth-and-route-protection.md +100 -70
  171. package/docs/guides/client/continuations.mdx +23 -26
  172. package/docs/guides/client/messages.mdx +47 -66
  173. package/docs/guides/client/output-schema.mdx +8 -8
  174. package/docs/guides/client/overview.mdx +47 -41
  175. package/docs/guides/client/streaming.mdx +62 -71
  176. package/docs/guides/decide.md +24 -79
  177. package/docs/guides/deployment/meta.json +1 -1
  178. package/docs/guides/deployment/overview.md +27 -18
  179. package/docs/guides/deployment/self-hosted-operations.md +99 -0
  180. package/docs/guides/deployment/self-hosting.md +63 -80
  181. package/docs/guides/deployment/vercel.mdx +31 -27
  182. package/docs/guides/deployment/workflow-worlds.md +100 -0
  183. package/docs/guides/dev-tui.md +48 -41
  184. package/docs/guides/dynamic-capabilities.md +49 -50
  185. package/docs/guides/frontend/nextjs.mdx +2 -2
  186. package/docs/guides/frontend/nuxt.mdx +11 -11
  187. package/docs/guides/frontend/overview.mdx +1 -1
  188. package/docs/guides/frontend/sveltekit.mdx +11 -11
  189. package/docs/guides/frontend/tanstack.mdx +16 -16
  190. package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
  191. package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
  192. package/docs/guides/frontend/use-eve-agent.mdx +25 -25
  193. package/docs/guides/hooks.md +152 -106
  194. package/docs/guides/instrumentation/agent-runs.mdx +26 -30
  195. package/docs/guides/instrumentation/instrumentation.mdx +49 -76
  196. package/docs/guides/instrumentation/meta.json +1 -1
  197. package/docs/guides/instrumentation/otel.mdx +113 -179
  198. package/docs/guides/prepare-for-1-0.md +23 -1
  199. package/docs/guides/remote-agents.md +125 -187
  200. package/docs/guides/self-modification.md +18 -18
  201. package/docs/guides/session-context.md +16 -16
  202. package/docs/install-integrations.mdx +26 -24
  203. package/docs/instructions.mdx +37 -42
  204. package/docs/memory/custom-provider.md +35 -41
  205. package/docs/memory/file.md +93 -76
  206. package/docs/memory/overview.mdx +145 -156
  207. package/docs/patterns/durable-cross-channel-notifications.md +15 -19
  208. package/docs/patterns/dynamic-scheduling.md +19 -23
  209. package/docs/patterns/multi-tenant-approvals.md +17 -22
  210. package/docs/patterns/multi-tenant-auth.md +43 -42
  211. package/docs/patterns/multi-tenant-memory.md +39 -36
  212. package/docs/patterns/voice-notes.md +3 -3
  213. package/docs/protocols/acp.md +13 -13
  214. package/docs/protocols/ucp.mdx +7 -7
  215. package/docs/reference/agent-files.md +6 -6
  216. package/docs/reference/cli.md +99 -98
  217. package/docs/reference/telemetry.md +1 -1
  218. package/docs/reference/typescript-api.md +52 -53
  219. package/docs/responsible-use.md +2 -2
  220. package/docs/sandbox/custom-providers.mdx +60 -56
  221. package/docs/sandbox/default.mdx +23 -24
  222. package/docs/sandbox/docker.mdx +16 -10
  223. package/docs/sandbox/index.mdx +93 -61
  224. package/docs/sandbox/just-bash.mdx +17 -11
  225. package/docs/sandbox/troubleshooting.mdx +29 -23
  226. package/docs/sandbox/vercel.mdx +45 -52
  227. package/docs/schedules.mdx +65 -54
  228. package/docs/skills.mdx +74 -49
  229. package/docs/subagents/index.mdx +97 -136
  230. package/docs/tools/human-in-the-loop.md +160 -90
  231. package/docs/tools/meta.json +1 -1
  232. package/docs/tools/overview.mdx +229 -237
  233. package/docs/tools/tasks.md +118 -117
  234. package/docs/tools/workflows.mdx +447 -543
  235. package/docs/tutorial/connect-a-warehouse.mdx +11 -13
  236. package/docs/tutorial/first-agent.mdx +14 -16
  237. package/docs/tutorial/guard-the-spend.mdx +6 -8
  238. package/docs/tutorial/how-it-runs.mdx +8 -8
  239. package/docs/tutorial/query-sample-data.mdx +8 -8
  240. package/docs/tutorial/remember-definitions.mdx +4 -4
  241. package/docs/tutorial/run-analysis.mdx +20 -22
  242. package/docs/tutorial/ship-it.mdx +19 -19
  243. package/docs/tutorial/team-playbooks.mdx +9 -9
  244. package/docs/use-cases.mdx +13 -11
  245. package/package.json +1 -1
  246. package/docs/guides/instrumentation/migration.md +0 -96
  247. package/docs/tools/tasks-upgrade.md +0 -218
@@ -4,7 +4,9 @@ description: "Reach your agent from Discord messages, DMs, and mentions, and fro
4
4
  type: integration
5
5
  ---
6
6
 
7
- The Discord channel wires your agent into Discord's HTTP Interactions, including slash and application commands, message components, and modal submissions. Discord enforces a three-second ACK deadline, so the channel acknowledges the command right away and runs the eve work in the background. Credentials and inbound request verification run through [Vercel Connect](../guides/auth-and-route-protection), so Discord's bot token stays out of your environment and Connect verifies Discord's signature before forwarding an interaction to eve. To also answer DMs and mentions, add a [Discord Gateway relay](#reply-to-dms-and-mentions-experimental). See [Channels](./overview) for the contract this builds on.
7
+ The Discord channel lets people reach your agent from Discord slash commands, buttons, selects, and modals. It lives in `agent/channels/discord.ts`. To also answer DMs, mentions, and thread replies, add the experimental [Gateway relay](#reply-to-dms-and-mentions-experimental).
8
+
9
+ Discord requires an answer within three seconds, so the channel acknowledges each command at once and runs the agent in the background. [Vercel Connect](../guides/auth-and-route-protection) holds the bot token and checks Discord's signature before it forwards a request to eve.
8
10
 
9
11
  ## Set up Discord
10
12
 
@@ -14,39 +16,40 @@ Run the guided setup from your eve project:
14
16
  pnpm eve add channel/discord
15
17
  ```
16
18
 
17
- The setup first asks how people should reach the agent: through **DMs, mentions, and threads**, or through **a slash command**. It then guides you through creating a Discord application and bot, and:
19
+ Setup asks whether people reach the agent through **DMs, mentions, and threads** or **a slash command**. It guides you through creating a Discord application and bot, then:
18
20
 
19
- - signs you in to Vercel and creates or links a project when needed;
21
+ - signs you in to Vercel and links or creates a project;
20
22
  - validates the bot token;
21
- - creates a Vercel Connect client and attaches `/eve/v1/discord` as its trigger destination;
22
- - configures the Discord application's Interactions Endpoint URL, which buttons such as HITL choices and sign-ins use either way;
23
- - for DMs, mentions, and threads, writes the [Gateway relay](#run-the-relay-as-a-vercel-daemon) in `daemon/`, registers it in `vercel.json` in the project's first function region, and turns on the bot's Message Content intent when Discord allows it;
23
+ - creates a Vercel Connect client with `/eve/v1/discord` as its trigger destination;
24
+ - sets the application's Interactions Endpoint URL, which buttons such as approvals and sign-ins need in both modes;
25
+ - for DMs, mentions, and threads, writes the [Gateway relay](#run-the-relay-as-a-vercel-daemon) in `daemon/` and registers it in `vercel.json` in the project's first function region;
26
+ - for DMs, mentions, and threads, turns on the Message Content intent when Discord allows it;
24
27
  - for a slash command, registers it with a required `message` option and an optional `file` attachment option;
25
- - scaffolds the channel with Connect-managed credentials; and
28
+ - writes the channel file with Connect-managed credentials; and
26
29
  - prints the bot installation URL.
27
30
 
28
- The slash command defaults to `/ask` with the description **Ask the eve agent**. You can edit both during setup. Discord global commands can take up to an hour to appear after registration. A bot that answers messages can take slash commands too: register one as described in [Configure Discord manually](#configure-discord-manually), and the channel handles it.
29
-
30
- In a non-interactive run, answer `discord-messages` with `"gateway"` for DMs, mentions, and threads, or `"commands"` for a slash command. `--yes` picks the slash command, because the relay is experimental and runs as an always-on Vercel Daemon.
31
+ The slash command defaults to `/ask` with the description **Ask the eve agent**, and you can edit both during setup. Discord global commands can take up to an hour to appear. A bot that answers messages can also take slash commands, as in [Configure Discord manually](#configure-discord-manually).
31
32
 
32
- If your project configures Vercel in `vercel.ts`, setup leaves it alone and prints the `daemons` entry to add to it.
33
+ In a non-interactive run, answer `discord-messages` with `"gateway"` for DMs, mentions, and threads, or `"commands"` for a slash command. `--yes` picks the slash command, because the relay is experimental and runs as an always-on Vercel Daemon. If your project configures Vercel in `vercel.ts`, setup leaves it alone and prints the `daemons` entry to add.
33
34
 
34
- The generated channel looks like this, plus `gateway: {}` when the agent answers messages:
35
+ The generated channel looks like this:
35
36
 
36
37
  ```ts title="agent/channels/discord.ts"
37
38
  import { connectDiscordCredentials } from "@vercel/connect/eve";
38
39
  import { discordChannel } from "eve/channels/discord";
39
40
 
40
41
  export default discordChannel({
42
+ // Connect supplies the application ID and bot token.
41
43
  credentials: connectDiscordCredentials("discord/my-agent"),
44
+ // Setup adds `gateway: {}` when the agent answers DMs and mentions.
42
45
  });
43
46
  ```
44
47
 
45
- The route is `POST /eve/v1/discord` by default. Connect resolves the application ID and bot token lazily and verifies forwarded interactions with same-project Vercel OIDC.
48
+ The route is `POST /eve/v1/discord` by default. Forwarded requests from Connect are verified with a Vercel OIDC token from the same project.
46
49
 
47
50
  ### Configure Discord manually
48
51
 
49
- If you do not use the guided Connect setup, register a command with Discord's API or the Developer Portal. A string option named `message` lines up with eve's default prompt extraction, and an attachment option lets people send a file with the command:
52
+ Without the guided setup, register a command with Discord's API or the Developer Portal. The channel reads the prompt from a string option named `message`, and an attachment option lets people send a file:
50
53
 
51
54
  ```bash
52
55
  curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/commands" \
@@ -56,11 +59,107 @@ curl -X PUT "https://discord.com/api/v10/applications/$DISCORD_APPLICATION_ID/co
56
59
  {"name":"file","description":"A file for the agent to read","type":11,"required":false}]}]'
57
60
  ```
58
61
 
59
- Then configure the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set the corresponding `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY` environment variables.
62
+ Then set the public `https://…/eve/v1/discord` route as the application's Interactions Endpoint URL. Pass `credentials: { applicationId, botToken, publicKey }` to `discordChannel`, or set `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, and `DISCORD_PUBLIC_KEY`.
63
+
64
+ ## How the channel handles messages
65
+
66
+ ### Dispatch
67
+
68
+ `onCommand(ctx, interaction)` decides whether a command runs the agent, and as whom. Return `{ auth }` to run it, optionally with `title` to set the run title, or `null` to ignore the command. Omit `onCommand` to run as the Discord user who sent the command.
69
+
70
+ The model sees a `<discord_context>` block with `user_id` and the receiving application's `application_id`.
71
+
72
+ Event handlers receive `(event, ctx)`, with Discord API helpers on `ctx.channel.discord`:
73
+
74
+ ```ts
75
+ import { discordChannel } from "eve/channels/discord";
76
+
77
+ export default discordChannel({
78
+ onCommand: (ctx, interaction) => ({
79
+ auth: {
80
+ principalId: interaction.user.id,
81
+ principalType: "user",
82
+ authenticator: "discord",
83
+ attributes: { channel_id: interaction.channelId, guild_id: interaction.guildId ?? "" },
84
+ },
85
+ }),
86
+ events: {
87
+ "content.completed"(event, ctx) {
88
+ if (event.data.phase !== "reply" || typeof event.data.value !== "string") return;
89
+ return ctx.channel.discord.post(event.data.value);
90
+ },
91
+ },
92
+ });
93
+ ```
94
+
95
+ ### Delivery
96
+
97
+ The first reply replaces the command's deferred "thinking" response, and later replies post as follow-ups. If Discord rejects the command's interaction token, the bot posts a normal channel message instead. Text over Discord's 2000-character limit is split across messages. Replies mention nobody by default (`allowed_mentions: { parse: [] }`).
98
+
99
+ With a bot token, the bot shows typing when a turn starts and when it calls a tool. In custom handlers, call `ctx.channel.discord.startTyping()`.
100
+
101
+ ### Human-in-the-loop (HITL)
102
+
103
+ Approvals and questions render as Discord components. Confirmations and options become buttons, `display: "select"` becomes a string select, and free-text input becomes a button that opens a modal. The session resumes when the user responds. Discord caps a select option's value at 100 characters, so a `display: "select"` request with a longer option `id` fails to post with an error.
104
+
105
+ A press, select, or modal submission answers as the Discord user who made it, with the same `defaultDiscordAuth` identity their commands get. Approvals are requester-only by default, so only the person whose command asked can approve.
106
+
107
+ `onAnswers(ctx, interaction)` decides who an answer comes from. Return `{ auth }` to accept the answer, or `null` (or throw) to drop it and keep the request open. `ctx.defaultAuth` is the presser's `defaultDiscordAuth`. It identifies the presser but doesn't authorize them.
108
+
109
+ If you customize `onCommand`, eve drops every press and submission, with a warning, until you also set `onAnswers`. Otherwise requester-only approvals would refuse the requester, and people your `onCommand` turns away could answer. Give both hooks the same mapping and checks:
110
+
111
+ ```ts
112
+ import { discordChannel } from "eve/channels/discord";
113
+
114
+ // One mapping for commands and answers, so requester-only approvals match.
115
+ const auth = (interaction: { user: { id: string } }) => ({
116
+ auth: {
117
+ principalId: `user:${interaction.user.id}`,
118
+ principalType: "user" as const,
119
+ authenticator: "discord",
120
+ attributes: {},
121
+ },
122
+ });
123
+
124
+ export default discordChannel({
125
+ onCommand: (_ctx, interaction) => auth(interaction),
126
+ onAnswers: (_ctx, interaction) => auth(interaction),
127
+ });
128
+ ```
129
+
130
+ ### Connection sign-ins
131
+
132
+ When a connection needs the person to sign in, eve posts the sign-in to the conversation:
133
+
134
+ - **In a DM**, the message has a link button to the sign-in page and any confirmation code.
135
+ - **In a server**, the shared message says who has to sign in and has a **Sign in** button. eve identifies whoever presses it through `onAnswers`, as for approval presses. The person who has to sign in gets an ephemeral message with the link and code. Anyone else gets an ephemeral note that they can't open it, so no other member can save their account under the requester's identity.
136
+
137
+ When the sign-in completes or is cancelled, eve edits the message and removes its button.
138
+
139
+ If `onCommand` or `gateway.onMessage` returns custom identities, set `onAnswers` to the same mapping. Otherwise eve can't match a press to the person who has to sign in, and nobody can open the sign-in in a server.
140
+
141
+ ### Proactive sessions
142
+
143
+ To start a session without an incoming command, call `to(discord, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(discord, target).send(message, { auth })` from another channel. The target is `{ channelId, conversationId?, initialMessage? }`. Both need a bot token from Connect or `DISCORD_BOT_TOKEN`.
144
+
145
+ ### Attachments
146
+
147
+ Files sent through a command's attachment options (type `11`) reach the agent as files. eve downloads them without credentials from Discord's signed CDN URLs (`cdn.discordapp.com` or `media.discordapp.net`). A file over 25 MB, or one whose download fails, reaches the agent as a short note. Each command starts its own session, so a file is available only in that session.
148
+
149
+ ## Options
150
+
151
+ | Option | Default | What it does |
152
+ | ----------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------- |
153
+ | `credentials` | `DISCORD_APPLICATION_ID`, `DISCORD_BOT_TOKEN`, `DISCORD_PUBLIC_KEY` | `{ applicationId, botToken, publicKey }`, or `connectDiscordCredentials()`. |
154
+ | `route` | `/eve/v1/discord` | Path of the command and button route. |
155
+ | `onCommand(ctx, interaction)` | Runs as the user who sent the command | Returns `{ auth }` to run the agent, or `null` to ignore the command. |
156
+ | `onAnswers(ctx, interaction)` | Accepts as the presser, or drops all answers with a custom `onCommand` | Returns `{ auth }` to accept a button, select, or modal answer. |
157
+ | `events` | Built-in handlers | Replaces the default handler for each event you set. |
158
+ | `gateway` | Off | Accepts DMs and mentions from a [Gateway relay](#enable-the-gateway-route). |
60
159
 
61
160
  ## Reply to DMs and mentions (experimental)
62
161
 
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.
162
+ Discord sends ordinary messages, such as DMs, mentions, and thread replies, only over its [Gateway WebSocket](https://discord.com/developers/docs/events/gateway). Gateway support is experimental, and its API may change. Run `runDiscordGatewayRelay` from `eve/experimental/channels/discord/gateway` in a process that stays connected, and turn on the matching route on the channel. The bot replies to these messages as it replies to commands, including approval buttons and error messages.
64
163
 
65
164
  ```text
66
165
  Discord Gateway ── WebSocket ──▶ relay (Vercel Daemon) ── POST /eve/v1/discord/gateway ──▶ agent ── REST ──▶ Discord
@@ -68,7 +167,7 @@ Discord Gateway ── WebSocket ──▶ relay (Vercel Daemon) ── POST /ev
68
167
 
69
168
  ### Enable the Gateway route
70
169
 
71
- Add `gateway` to the channel. It mounts `POST /eve/v1/discord/gateway`. Because each forwarded message names its author, the route by default accepts only `localDev()` and Vercel OIDC tokens from the same project and environment, which excludes preview deployments calling production:
170
+ Add `gateway` to mount `POST /eve/v1/discord/gateway`:
72
171
 
73
172
  ```ts title="agent/channels/discord.ts"
74
173
  import { connectDiscordCredentials } from "@vercel/connect/eve";
@@ -80,11 +179,20 @@ export default discordChannel({
80
179
  });
81
180
  ```
82
181
 
83
- Vercel Connect is optional here too: without `credentials`, the channel reads `DISCORD_APPLICATION_ID` and `DISCORD_BOT_TOKEN`, and the relay reads `DISCORD_BOT_TOKEN`. Pass `gateway.auth` to accept a relay that [runs outside Vercel](#run-the-relay-outside-vercel), and `gateway.route` to change the path. Whoever passes `gateway.auth` can send messages as any Discord user, so keep it as narrow as the default.
182
+ Each forwarded message names its author, so whoever passes `gateway.auth` can send messages as any Discord user. The default accepts only `localDev()` and Vercel OIDC tokens from the same project and environment, so a preview deployment can't call production. Keep a custom `gateway.auth` as narrow.
183
+
184
+ | `gateway` option | Default | What it does |
185
+ | ------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
186
+ | `auth` | `localDev()` and same-environment Vercel OIDC tokens | Accepts a relay that [runs outside Vercel](#run-the-relay-outside-vercel). |
187
+ | `route` | `/eve/v1/discord/gateway` | Path of the relay route. |
188
+ | `onMessage(ctx, message)` | Answers [addressed messages](#who-the-bot-answers) | Returns `{ auth }` to run the agent, or `null` to ignore the message. |
189
+ | `startThread` | `true` | Answers a mention in a text channel in a [new thread](#reply-in-threads). Set `false` to answer in the channel. |
190
+
191
+ Omit `credentials` to read `DISCORD_APPLICATION_ID` and `DISCORD_BOT_TOKEN` in the channel and `DISCORD_BOT_TOKEN` in the relay.
84
192
 
85
193
  ### Run the relay as a Vercel Daemon
86
194
 
87
- A Vercel Daemon keeps the relay connected. Vercel Daemons are in beta. When you choose to answer messages, `eve add channel/discord` writes these files for you. To add them yourself, put the relay in its own directory with the same credentials as the agent:
195
+ A Vercel Daemon, in beta, keeps the relay connected. `eve add channel/discord` writes these files when you choose to answer messages. To add them yourself, put the relay in its own directory with the same credentials as the agent:
88
196
 
89
197
  ```ts title="daemon/main.ts"
90
198
  import { connectDiscordCredentials } from "@vercel/connect/eve";
@@ -108,7 +216,7 @@ await runDiscordGatewayRelay({
108
216
  }
109
217
  ```
110
218
 
111
- The image installs from `package-lock.json` too, if you commit one in `daemon/`:
219
+ If you commit a `package-lock.json` in `daemon/`, the image installs from it too:
112
220
 
113
221
  ```dockerfile title="daemon/Dockerfile"
114
222
  FROM node:24-slim
@@ -135,9 +243,9 @@ Register the daemon in `vercel.json` with exactly one instance:
135
243
  }
136
244
  ```
137
245
 
138
- On Vercel, the relay sends messages to `https://$VERCEL_PROJECT_PRODUCTION_URL` and signs each request with the project's Vercel OIDC token, so the agent and relay need no shared secret. Set `url` to send them elsewhere.
246
+ On Vercel, the relay posts to `https://$VERCEL_PROJECT_PRODUCTION_URL`, signed with the project's Vercel OIDC token, so no shared secret is needed. Set `url` to post elsewhere.
139
247
 
140
- The bot needs the **Send Messages in Threads** permission to reply in threads, in addition to **View Channels** and **Send Messages**, and **Create Public Threads** to [start threads](#reply-in-threads). This install URL grants all four plus **Read Message History**; replace `<APPLICATION_ID>`:
248
+ The bot needs **View Channels**, **Send Messages**, **Send Messages in Threads**, and **Create Public Threads** to [start threads](#reply-in-threads). This install URL grants all four plus **Read Message History**. Replace `<APPLICATION_ID>`:
141
249
 
142
250
  ```text
143
251
  https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applications.commands&permissions=309237713920
@@ -145,13 +253,13 @@ https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applic
145
253
 
146
254
  ### Run the relay outside Vercel
147
255
 
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:
256
+ `runDiscordGatewayRelay` runs on any host that keeps a Node.js 24 process up, such as a VM, container platform, or home server. The agent can stay on Vercel. Off Vercel, change three things:
149
257
 
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
- - **URL.** The relay can't read `VERCEL_PROJECT_PRODUCTION_URL`, so pass the agent's URL as `url`.
152
- - **Auth.** The route's default auth accepts only your Vercel project's own runtime. Use a shared secret instead: `httpBasic()` from `eve/agents/auth` signs the relay's requests, and `httpBasic()` from `eve/channels/auth` on `gateway.auth` checks them.
258
+ - **Credentials.** Other hosts have no Vercel OIDC token for Connect, so give the relay the bot token directly. The agent can keep using Connect.
259
+ - **URL.** Pass the agent's URL as `url`, because `VERCEL_PROJECT_PRODUCTION_URL` isn't set.
260
+ - **Auth.** The route's default auth accepts only your Vercel project's runtime. Use a shared secret: `httpBasic()` from `eve/agents/auth` signs the relay's requests, and `httpBasic()` from `eve/channels/auth` on `gateway.auth` checks them.
153
261
 
154
- Generate a long random secret, for example with `openssl rand -hex 32`, and set it as `DISCORD_RELAY_SECRET` on both the agent's Vercel project and the relay's host. On the agent:
262
+ Generate a long random secret, for example with `openssl rand -hex 32`. Set it as `DISCORD_RELAY_SECRET` on both the agent's Vercel project and the relay's host. On the agent:
155
263
 
156
264
  ```ts title="agent/channels/discord.ts"
157
265
  import { connectDiscordCredentials } from "@vercel/connect/eve";
@@ -182,7 +290,7 @@ await runDiscordGatewayRelay({
182
290
  });
183
291
  ```
184
292
 
185
- The relay's `package.json` needs only `eve`. Build the image from the same Dockerfile as the [daemon](#run-the-relay-as-a-vercel-daemon), then run it with a restart policy so a crash or host reboot brings it back:
293
+ The relay's `package.json` needs only `eve`. Build the image from the [daemon](#run-the-relay-as-a-vercel-daemon)'s Dockerfile, and run it with a restart policy:
186
294
 
187
295
  ```bash
188
296
  docker run -d --restart unless-stopped \
@@ -190,11 +298,13 @@ docker run -d --restart unless-stopped \
190
298
  discord-relay
191
299
  ```
192
300
 
193
- The relay stops on `SIGTERM` after delivering what it has in flight. It exits with an error when Discord refuses the bot token or intents, and restarting it won't help until you fix the configuration. If Deployment Protection covers the URL the relay posts to, create a Protection Bypass for Automation secret, and pass `auth` a function that returns the Basic `authorization` header together with an `x-vercel-protection-bypass` header carrying that secret.
301
+ The relay stops on `SIGTERM` after it forwards the messages it has in flight. It exits with an error when Discord refuses the bot token or intents, so fix the configuration before you restart it.
302
+
303
+ If Deployment Protection covers the relay's URL, create a Protection Bypass for Automation secret. Then pass `auth` a function that returns the Basic `authorization` header and an `x-vercel-protection-bypass` header with that secret.
194
304
 
195
305
  ### Who the bot answers
196
306
 
197
- By default the channel answers a message when it is a DM, mentions the bot, replies to one of the bot's messages, or arrives in a thread where the bot already has a conversation. It strips the bot's mention from the text, and it never answers messages from bots, including its own. Messages group into sessions this way:
307
+ By default the bot answers DMs, mentions of the bot, replies to its messages, and messages in threads where it already has a conversation. It strips its own mention from the text and never answers bots, including itself. Messages group into sessions this way:
198
308
 
199
309
  | Message | Session |
200
310
  | ------------------------------------ | -------------------------------------------------------------------------------------- |
@@ -203,19 +313,30 @@ By default the channel answers a message when it is a DM, mentions the bot, repl
203
313
  | A mention in a text channel | A new [thread](#reply-in-threads) started from the message, one session for the thread |
204
314
  | A reply to the bot in a text channel | The session that posted the replied-to message |
205
315
 
206
- A mention in a text channel starts a thread, as the Slack channel does, so each conversation stays out of the channel and two people, or one person's unrelated questions, don't share context. Every message the bot posts continues its session when someone replies to it, including slash command responses in the channel. A reply to a bot message that no live session owns starts a new thread.
316
+ Threads keep each conversation out of the channel, so two people, or one person's unrelated questions, don't share context. A reply to any bot message, including a slash command response, continues that message's session. A reply to a bot message that no live session posted starts a new thread.
317
+
318
+ Mention the bot's user, not the role with the same name that Discord creates for it. A role mention doesn't address the bot.
319
+
320
+ #### Message Content intent
321
+
322
+ Discord sends message text only to bots with the privileged **Message Content** intent, unless the message mentions the bot or is a DM. Without the intent, the bot ignores thread follow-ups that skip the mention, and replies whose author turned off the reply ping, because they arrive empty.
207
323
 
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.
324
+ `eve add channel/discord` turns the intent on and sets `messageContent: true` when Discord allows it, for bots in fewer than 100 servers. Otherwise, turn on **Message Content Intent** under **Bot** in the Discord Developer Portal. Then pass `messageContent: true` to `runDiscordGatewayRelay`. If you request the intent before you turn it on, Discord refuses the connection. The relay then stops with an error that names the close code.
209
325
 
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.
326
+ #### Choose which messages run the agent
211
327
 
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:
328
+ Set `gateway.onMessage(ctx, message)` to choose which messages run the agent, as whom, and in which session. It runs for every message from a person.
329
+
330
+ - `message.addressed` reports whether the default would answer.
331
+ - `message.referencedMessageId` names the message it replies to.
332
+ - `defaultDiscordMessageAuth(message)` gives the author the same identity that `defaultDiscordAuth` gives for commands and button presses, so requester-only approvals work across both.
213
333
 
214
334
  ```ts
215
335
  import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
216
336
 
217
337
  export default discordChannel({
218
338
  gateway: {
339
+ // Answer only addressed messages in one server.
219
340
  onMessage: (_ctx, message) =>
220
341
  message.addressed && message.guildId === "123456789012345678"
221
342
  ? { auth: defaultDiscordMessageAuth(message) }
@@ -224,7 +345,15 @@ export default discordChannel({
224
345
  });
225
346
  ```
226
347
 
227
- Return `conversation` to change how messages group. Messages with the same key share a session within their Discord channel. A message ID is the key of the session that owns that message, `"channel"` is one session for the whole channel, and any other string is your own grouping. Omit it to keep the default above. For example, to give each person one ongoing session per channel:
348
+ Return `conversation` to change how messages group into sessions. Omit it to keep the default.
349
+
350
+ | `conversation` value | Session |
351
+ | -------------------- | --------------------------------------------------------- |
352
+ | A message ID | The session that posted that message |
353
+ | `"channel"` | One session for the whole Discord channel |
354
+ | Any other string | Your own grouping: one session per key within the channel |
355
+
356
+ To give each person one session per channel:
228
357
 
229
358
  ```ts
230
359
  import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
@@ -241,9 +370,9 @@ export default discordChannel({
241
370
 
242
371
  ### Reply in threads
243
372
 
244
- By default, the bot answers a mention in a text channel in a new thread. The channel starts a public thread from the person's message, named after its first line, and adds the person to it. The thread holds one session, so later messages in it continue the conversation. Threads apply only to messages that would start a new session in a text channel. DMs, messages already in a thread, and replies that continue a session stay where they are. If Discord refuses to create the thread, for example because the bot lacks **Create Public Threads**, the bot answers in the channel instead.
373
+ By default, the bot answers a mention in a text channel by starting a public thread from the message. eve names the thread after the message's first line, adds the person, and gives the thread one session. Only messages that would start a new session in a text channel get a thread. DMs, thread messages, and replies that continue a session stay where they are. If Discord refuses to create the thread, for example because the bot lacks **Create Public Threads**, the bot answers in the channel.
245
374
 
246
- To answer in the channel instead, set `gateway.startThread` to `false`. A mention then starts a session in the channel, and replies to the bot's messages continue it:
375
+ Set `gateway.startThread` to `false` to answer in the channel. A mention then starts a session in the channel, and replies to the bot's messages continue it:
247
376
 
248
377
  ```ts title="agent/channels/discord.ts"
249
378
  import { connectDiscordCredentials } from "@vercel/connect/eve";
@@ -255,7 +384,7 @@ export default discordChannel({
255
384
  });
256
385
  ```
257
386
 
258
- `onMessage` can decide per message by returning `startThread`, which overrides `gateway.startThread`. Return `false` to answer in the channel, `true` for a thread, or options to name the thread and set how long Discord waits before archiving it:
387
+ To choose per message, return `startThread` from `onMessage`. It overrides `gateway.startThread`. Return `false` for the channel, `true` for a thread, or options that set the thread name and auto-archive delay:
259
388
 
260
389
  ```ts
261
390
  import { defaultDiscordMessageAuth, discordChannel } from "eve/channels/discord";
@@ -278,7 +407,7 @@ export default discordChannel({
278
407
 
279
408
  ### Forward messages from your own relay
280
409
 
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`:
410
+ The route accepts any relay that holds a Gateway connection, such as an existing discord.js bot. Forward each Gateway dispatch payload unchanged as the JSON body of a `POST` to `/eve/v1/discord/gateway`:
282
411
 
283
412
  ```json
284
413
  {
@@ -289,7 +418,7 @@ The route accepts any relay that holds a Gateway connection, such as an existing
289
418
  }
290
419
  ```
291
420
 
292
- The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without acting on them. Authenticate the request as `gateway.auth` requires; by default, that is a Vercel OIDC token from the same project and environment. The relay needs the `GUILD_MESSAGES` (`1 << 9`) and `DIRECT_MESSAGES` (`1 << 12`) intents, plus `MESSAGE_CONTENT` (`1 << 15`) for messages that don't mention the bot. Use the response status to decide whether to retry:
421
+ The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without acting on them. Authenticate as `gateway.auth` requires, by default with a Vercel OIDC token from the same project and environment. The relay needs the `GUILD_MESSAGES` (`1 << 9`) and `DIRECT_MESSAGES` (`1 << 12`) intents, plus `MESSAGE_CONTENT` (`1 << 15`) for messages that don't mention the bot. Use the response status to decide whether to retry:
293
422
 
294
423
  | Status | Meaning | Relay should |
295
424
  | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
@@ -301,102 +430,26 @@ The route handles `MESSAGE_CREATE` and acknowledges other dispatch types without
301
430
  | `429` | Rate limited before the route ran. | Retry with backoff. |
302
431
  | `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
432
 
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.
433
+ eve doesn't deduplicate messages. A retry after a turn started, for example because the response was lost, makes the agent answer twice. `runDiscordGatewayRelay` retries only a `429`, or a connection that failed before the request reached eve.
305
434
 
306
435
  ### Run the relay locally
307
436
 
308
- Pull a development OIDC token with `vercel env pull .env.local`, start `eve dev`, then run the relay against it from another terminal:
437
+ Pull a development OIDC token with `vercel env pull .env.local`, and start `eve dev`. Then run the relay against it from another terminal:
309
438
 
310
439
  ```bash
311
440
  EVE_URL=http://localhost:2000 node --env-file=.env.local daemon/main.ts
312
441
  ```
313
442
 
314
- Scale the production daemon to zero while you do this. Every connection receives every message, so two relays make the agent answer twice.
443
+ Scale the production daemon to zero meanwhile. Every connection receives every message, so two relays make the agent answer twice.
315
444
 
316
445
  ### Limitations
317
446
 
318
447
  - Run one relay per bot. Each connection receives every message. Bots large enough to need Discord's sharding are out of scope.
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
- - `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
-
322
- ## How the channel handles messages
323
-
324
- ### Dispatch
325
-
326
- `onCommand(ctx, interaction)` decides whether to dispatch and under what `auth`. Return `{ auth }` to proceed, `null` to drop the interaction, or `title` alongside `auth` to set the title when the dispatch starts a run. By default, auth comes from the invoking user.
327
-
328
- The model-visible `<discord_context>` includes `user_id` and the receiving application's `application_id`.
329
-
330
- Event handlers receive `(event, ctx)`, with Discord platform handles on `ctx.channel.discord`:
331
-
332
- ```ts
333
- import { discordChannel } from "eve/channels/discord";
334
-
335
- export default discordChannel({
336
- onCommand: (ctx, interaction) => ({
337
- auth: {
338
- principalId: interaction.user.id,
339
- principalType: "user",
340
- authenticator: "discord",
341
- attributes: { channel_id: interaction.channelId, guild_id: interaction.guildId ?? "" },
342
- },
343
- }),
344
- events: {
345
- "content.completed"(event, ctx) {
346
- if (event.data.phase !== "reply" || typeof event.data.value !== "string") return;
347
- return ctx.channel.discord.post(event.data.value);
348
- },
349
- },
350
- });
351
- ```
352
-
353
- ### Delivery
354
-
355
- The default `content.completed` handler edits the deferred response for the first reply part and sends followups after that. If the interaction token is rejected, it falls back to a bot-authenticated channel message. Long text is split to Discord's 2000-char limit, and generated messages default to `allowed_mentions: { parse: [] }`.
356
-
357
- Typing fires on `turn.started` and `call.requested`, but only when a bot token is present. In custom handlers, call `ctx.channel.discord.startTyping()` yourself.
358
-
359
- ### Human-in-the-loop (HITL)
360
-
361
- HITL renders as Discord components. Confirmations and options become buttons, `display: "select"` becomes a string select, and freeform input becomes a button that opens a modal. When the user responds, the parked session (paused awaiting input) resumes.
362
-
363
- A press, select, or modal submission answers as the Discord user who made it, with the same `defaultDiscordAuth` principal a command from them gets by default. Approval response policies compare against that principal. Approvals are requester-only by default, so only the person whose command asked can approve. `onAnswers(ctx, interaction)` decides the answer's `auth`: return `{ auth }` to accept it, or `null` (or throw) to drop it and keep the request pending. `ctx.defaultAuth` is the presser's `defaultDiscordAuth`; it identifies them but doesn't authorize them by itself.
364
-
365
- If you customize `onCommand`, eve drops every press and submission until you also set `onAnswers`, and logs a warning saying so. The default Discord principal wouldn't match the principals your `onCommand` returns, so a requester-only approval would refuse the requester. It would also let someone your `onCommand` turns away answer open approvals. Give both hooks the same mapping and gating:
366
-
367
- ```ts
368
- import { discordChannel } from "eve/channels/discord";
369
-
370
- const auth = (interaction: { user: { id: string } }) => ({
371
- auth: {
372
- principalId: `user:${interaction.user.id}`,
373
- principalType: "user" as const,
374
- authenticator: "discord",
375
- attributes: {},
376
- },
377
- });
378
-
379
- export default discordChannel({
380
- onCommand: (_ctx, interaction) => auth(interaction),
381
- onAnswers: (_ctx, interaction) => auth(interaction),
382
- });
383
- ```
384
-
385
- ### Connection sign-ins
386
-
387
- When a connection needs the person to sign in, the default `authorization.required` handler posts it to the conversation. In a DM, the message includes a link button to the sign-in page and any confirmation code. In a server, the shared message only says who has to sign in and has a **Sign in** button. When someone presses it, eve identifies them the same way it does for HITL presses (`onInputResponse`). If that's the person who has to sign in, eve answers with an ephemeral message holding the link and code, which only they can see. Anyone else gets an ephemeral note that they can't open it. That way another member can't finish the sign-in with their own account and have it saved under the requester's identity. Once the sign-in completes or is cancelled, eve edits the message to say so and removes its button.
388
-
389
- If `onCommand` or `gateway.onMessage` gives people principals other than the default, set `onInputResponse` to the same mapping. Otherwise eve can't match a press to the person who has to sign in, and nobody can open the sign-in in a server.
390
-
391
- ### Proactive sessions
392
-
393
- Start a session without an inbound interaction through `to(discord, target).send(message, { auth })` from a schedule `run` handler, or `ctx.to(discord, target).send(message, { auth })` from another channel. The proactive target shape is `{ channelId, conversationId?, initialMessage? }`. Either path needs a bot token, supplied by Connect or `DISCORD_BOT_TOKEN`.
394
-
395
- ### Attachments
396
-
397
- Files attached through a command's attachment options (type `11`) reach the agent as file parts. eve downloads each one from Discord's signed CDN URL (`cdn.discordapp.com` or `media.discordapp.net`) without credentials. A file over 25 MB, or one whose download fails, reaches the agent as a short note instead. Each command starts its own session, so a file is available in the conversation that command starts.
448
+ - Messages sent while no relay is connected are lost, and Discord doesn't replay them. On a deploy, the old relay disconnects at `SIGTERM` while the new daemon boots, usually a few seconds. A crash or restart leaves the same gap.
449
+ - `runDiscordGatewayRelay` doesn't retry a message that may have started a turn, because a retry could answer twice. It drops and logs the message on a `5xx`, on no acceptance within 30 seconds, or on a connection failure after sending.
398
450
 
399
451
  ## What to read next
400
452
 
401
- - [Channels overview](./overview): the channel contract and every built-in channel
453
+ - [Channels overview](./overview): what every channel shares, and every built-in channel
454
+ - [Chat SDK](./chat-sdk): reach Discord through a Chat SDK adapter, with your own credentials and state store
402
455
  - [Auth & route protection](../guides/auth-and-route-protection): authenticating inbound traffic