eve 0.90.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.
- package/CHANGELOG.md +34 -23
- package/dist/src/channel/auth/http-basic.js +1 -1
- package/dist/src/channel/channel-operations.d.ts +1 -1
- package/dist/src/channel/types.d.ts +2 -0
- package/dist/src/cli/dev/tui/prompt-commands.d.ts +1 -1
- package/dist/src/client/session.d.ts +1 -1
- package/dist/src/compiled/.vendor-stamp.json +1 -1
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/sandbox/bash.js +2 -2
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/admission.d.ts +6 -0
- package/dist/src/execution/session/admission.js +1 -1
- package/dist/src/execution/session/delivery-facts.js +1 -1
- package/dist/src/execution/session/next-input.d.ts +2 -2
- package/dist/src/execution/session/next-input.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session-inbox/inbox.d.ts +2 -2
- package/dist/src/execution/session-inbox/inbox.js +1 -1
- package/dist/src/execution/session-inbox/protocol.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/compaction/engine.js +2 -2
- package/dist/src/harness/current-messages.js +1 -1
- package/dist/src/harness/emission.d.ts +3 -0
- package/dist/src/harness/emission.js +1 -1
- package/dist/src/harness/facts.d.ts +5 -2
- package/dist/src/harness/facts.js +1 -1
- package/dist/src/harness/model-call/call.d.ts +7 -1
- package/dist/src/harness/model-call/call.js +3 -1
- package/dist/src/harness/provider-tool-history.d.ts +8 -0
- package/dist/src/harness/provider-tool-history.js +1 -1
- package/dist/src/harness/session-machine/transitions.d.ts +3 -2
- package/dist/src/harness/step/after-model.js +1 -1
- package/dist/src/harness/step/context.js +1 -1
- package/dist/src/harness/step/intake.js +1 -1
- package/dist/src/harness/step/prompt.js +1 -1
- package/dist/src/harness/tool-history-repair.d.ts +2 -0
- package/dist/src/harness/tool-history-repair.js +1 -1
- package/dist/src/harness/tool-loop.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/protocol/session-events/families/delivery.d.ts +5 -3
- package/dist/src/protocol/session-events/families/delivery.js +1 -1
- package/dist/src/protocol/session-projection/fold.js +1 -1
- package/dist/src/public/channels/discord/hitl.js +1 -1
- package/dist/src/public/channels/slack/hitl.d.ts +2 -1
- package/dist/src/public/channels/slack/hitl.js +3 -3
- package/dist/src/public/channels/slack/interaction-cards.js +1 -1
- package/dist/src/public/channels/slack/request-card-render.js +1 -1
- package/dist/src/public/channels/teams/hitl.js +1 -1
- package/dist/src/public/channels/teams/verify.js +1 -1
- package/dist/src/public/definitions/hook.d.ts +90 -7
- package/dist/src/public/definitions/hook.js +1 -1
- package/dist/src/public/hooks/index.d.ts +3 -2
- package/dist/src/reactions/continuation.d.ts +19 -0
- package/dist/src/reactions/continuation.js +1 -0
- package/dist/src/reactions/intents.d.ts +10 -4
- package/dist/src/reactions/intents.js +1 -1
- package/dist/src/reactions/kinds/hook.js +1 -1
- package/dist/src/reactions/runner.js +1 -1
- package/dist/src/reactions/state.d.ts +15 -2
- package/dist/src/reactions/state.js +1 -1
- package/dist/src/runtime/resolve-connection.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/primitives/open-url.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/shared/value-delta.d.ts +5 -4
- package/dist/src/shared/value-delta.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/dist/src/tools/provided/web-fetch.js +1 -1
- package/docs/agent-config.md +199 -222
- package/docs/channels/chat-sdk.mdx +60 -64
- package/docs/channels/custom.mdx +264 -281
- package/docs/channels/discord.mdx +176 -123
- package/docs/channels/eve.mdx +136 -206
- package/docs/channels/github.mdx +24 -22
- package/docs/channels/linear.mdx +30 -30
- package/docs/channels/linq.mdx +25 -13
- package/docs/channels/mcp.mdx +154 -116
- package/docs/channels/overview.mdx +31 -32
- package/docs/channels/photon.mdx +32 -56
- package/docs/channels/slack.mdx +538 -375
- package/docs/channels/teams.mdx +40 -26
- package/docs/channels/telegram.mdx +13 -13
- package/docs/channels/twilio.mdx +11 -11
- package/docs/code-extension.mdx +40 -42
- package/docs/concepts/built-in-tools.md +89 -57
- package/docs/concepts/context-control.md +20 -20
- package/docs/concepts/default-harness.md +20 -36
- package/docs/concepts/execution-model-and-durability.mdx +96 -160
- package/docs/concepts/project-structure.mdx +21 -14
- package/docs/concepts/security-model.md +27 -27
- package/docs/concepts/sessions-runs-and-streaming.md +184 -198
- package/docs/concepts/state.md +7 -15
- package/docs/connections/mcp.mdx +109 -93
- package/docs/connections/openapi.mdx +57 -59
- package/docs/connections/overview.mdx +175 -170
- package/docs/evals/assertions.mdx +36 -29
- package/docs/evals/cases.mdx +38 -42
- package/docs/evals/judge.mdx +21 -29
- package/docs/evals/overview.mdx +42 -38
- package/docs/evals/reporters.mdx +54 -27
- package/docs/evals/running.mdx +15 -8
- package/docs/evals/targets.mdx +16 -19
- package/docs/evals/tool-stubs.mdx +111 -97
- package/docs/experimental/dynamic-schedules.mdx +118 -63
- package/docs/extensions.md +58 -65
- package/docs/getting-started.mdx +4 -6
- package/docs/guides/auth-and-route-protection.md +87 -70
- package/docs/guides/client/continuations.mdx +23 -26
- package/docs/guides/client/messages.mdx +47 -66
- package/docs/guides/client/output-schema.mdx +8 -8
- package/docs/guides/client/overview.mdx +45 -43
- package/docs/guides/client/streaming.mdx +62 -71
- package/docs/guides/decide.md +24 -79
- package/docs/guides/deployment/meta.json +1 -1
- package/docs/guides/deployment/overview.md +27 -18
- package/docs/guides/deployment/self-hosted-operations.md +99 -0
- package/docs/guides/deployment/self-hosting.md +63 -80
- package/docs/guides/deployment/vercel.mdx +31 -27
- package/docs/guides/deployment/workflow-worlds.md +100 -0
- package/docs/guides/dev-tui.md +48 -41
- package/docs/guides/dynamic-capabilities.md +49 -50
- package/docs/guides/frontend/nextjs.mdx +2 -2
- package/docs/guides/frontend/nuxt.mdx +11 -11
- package/docs/guides/frontend/overview.mdx +1 -1
- package/docs/guides/frontend/sveltekit.mdx +11 -11
- package/docs/guides/frontend/tanstack.mdx +16 -16
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +21 -21
- package/docs/guides/frontend/use-eve-agent-vue.mdx +22 -22
- package/docs/guides/frontend/use-eve-agent.mdx +25 -25
- package/docs/guides/hooks.md +152 -106
- package/docs/guides/instrumentation/agent-runs.mdx +26 -30
- package/docs/guides/instrumentation/instrumentation.mdx +49 -76
- package/docs/guides/instrumentation/meta.json +1 -1
- package/docs/guides/instrumentation/otel.mdx +113 -179
- package/docs/guides/remote-agents.md +125 -187
- package/docs/guides/self-modification.md +18 -18
- package/docs/guides/session-context.md +16 -16
- package/docs/install-integrations.mdx +26 -24
- package/docs/instructions.mdx +37 -42
- package/docs/memory/custom-provider.md +35 -41
- package/docs/memory/file.md +93 -76
- package/docs/memory/overview.mdx +145 -156
- package/docs/patterns/durable-cross-channel-notifications.md +15 -19
- package/docs/patterns/dynamic-scheduling.md +19 -23
- package/docs/patterns/multi-tenant-approvals.md +17 -22
- package/docs/patterns/multi-tenant-auth.md +43 -42
- package/docs/patterns/multi-tenant-memory.md +39 -36
- package/docs/patterns/voice-notes.md +3 -3
- package/docs/protocols/acp.md +13 -13
- package/docs/protocols/ucp.mdx +7 -7
- package/docs/reference/agent-files.md +6 -6
- package/docs/reference/cli.md +99 -98
- package/docs/reference/telemetry.md +1 -1
- package/docs/reference/typescript-api.md +52 -53
- package/docs/responsible-use.md +2 -2
- package/docs/sandbox/custom-providers.mdx +60 -56
- package/docs/sandbox/default.mdx +23 -24
- package/docs/sandbox/docker.mdx +16 -10
- package/docs/sandbox/index.mdx +93 -61
- package/docs/sandbox/just-bash.mdx +17 -11
- package/docs/sandbox/troubleshooting.mdx +29 -23
- package/docs/sandbox/vercel.mdx +45 -52
- package/docs/schedules.mdx +65 -54
- package/docs/skills.mdx +74 -49
- package/docs/subagents/index.mdx +97 -136
- package/docs/tools/human-in-the-loop.md +160 -90
- package/docs/tools/meta.json +1 -1
- package/docs/tools/overview.mdx +229 -237
- package/docs/tools/tasks.md +118 -117
- package/docs/tools/workflows.mdx +447 -543
- package/docs/tutorial/connect-a-warehouse.mdx +11 -13
- package/docs/tutorial/first-agent.mdx +14 -16
- package/docs/tutorial/guard-the-spend.mdx +6 -8
- package/docs/tutorial/how-it-runs.mdx +8 -8
- package/docs/tutorial/query-sample-data.mdx +8 -8
- package/docs/tutorial/remember-definitions.mdx +4 -4
- package/docs/tutorial/run-analysis.mdx +20 -22
- package/docs/tutorial/ship-it.mdx +19 -19
- package/docs/tutorial/team-playbooks.mdx +9 -9
- package/docs/use-cases.mdx +13 -11
- package/package.json +1 -1
- package/docs/guides/instrumentation/migration.md +0 -96
- 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
|
|
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
|
-
|
|
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
|
|
21
|
+
- signs you in to Vercel and links or creates a project;
|
|
20
22
|
- validates the bot token;
|
|
21
|
-
- creates a Vercel Connect client
|
|
22
|
-
-
|
|
23
|
-
- for DMs, mentions, and threads, writes the [Gateway relay](#run-the-relay-as-a-vercel-daemon) in `daemon
|
|
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
|
-
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
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
|
|
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)
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
-
|
|
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
|
|
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
|
|
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,
|
|
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.**
|
|
151
|
-
- **URL.**
|
|
152
|
-
- **Auth.** The route's default auth accepts only your Vercel project's
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
326
|
+
#### Choose which messages run the agent
|
|
211
327
|
|
|
212
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
320
|
-
- `runDiscordGatewayRelay`
|
|
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):
|
|
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
|