Skip to content

Self-improving AI Employees for everyone

docs(discord): service reference, node cards and index entries

trohitge9753aeeac94
diff --git a/CLAUDE.md b/CLAUDE.md
index 0f12b7c2..c9881b8c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -33,6 +33,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[GitHub Service](./docs-internal/github_service.md)** | GitHub CLI integration — `githubAction` (repo_clone / pr_create / pr_list / pr_merge / issue_create / issue_list + `custom` passthrough; AI tool `github`). **Strict Stripe pattern: the gh CLI owns its own auth** — no token stored/injected by OpenCompany, no auth pre-flight (gh's own error surfaces), marker OAuth row for the modal badge, fieldless catalogue entry. Login = spawned `gh auth login --hostname github.com --git-protocol https --web` — source-verified: headless takes the `isInteractive=false` branch (no Press-Enter), prints one-time code + `github.com/login/device` URL on stderr; the modal shows the code via the generic `verificationCode` plumbing (`useCredentialPanel` → `OAuthConnect`). `login_env()` strips `GH_TOKEN`/`GITHUB_TOKEN` (login aborts otherwise). Success gate = `gh auth status` exit 0, then best-effort **`gh auth setup-git`** (official bridge — the future git node needs zero auth code). gh binary: **project-local, pooch-driven** (temporal `_install.py` idiom) — pinned release under `package_dir("gh")`, system gh never consulted (auth state still shared: gh config paths are user-level). Palette group `vcs`. |
| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / zones_list / dns_records CRUD / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, technical preview — "the next version of Wrangler"). **Two cf-specific variants of the CLI-managed-auth pattern**: (1) the CLI opens the browser ITSELF (loopback PKCE callback on fixed port 8877) so the login handler proxies nothing — single-flight guard (concurrent logins collide on the fixed port) + never-kill-the-shim invariant (killing the npm `.cmd` wrapper orphans the node child holding 8877); success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). (2) **Fixed 86-scope OAuth grant with no `--scopes` flag** — only `dns_analytics:read` for analytics; no RUM/zone-analytics OAuth scope exists anywhere, so the optional `cloudflare_api_token` field (injected as `CLOUDFLARE_API_TOKEN`, cf's documented first-priority credential) is the only path to Web Analytics/RUM + the GraphQL Analytics API. `graphql_query` op POSTs the official `client/v4/graphql` endpoint directly (outside the OpenAPI schema cf/SDKs are generated from) — the replacement for the sunsetted Zone Analytics REST API; needs `Account > Account Analytics > Read`. Pinned npm install into the shared packages tree, system cf never consulted (preview argv surface drifts across versions). Palette group `deployment`. |
| **[Google Cloud Service](./docs-internal/gcloud_service.md)** | Google Cloud CLI integration — `gcloudAction` (auth/config/projects + set_project / Compute Engine instances list-start-stop-describe / Cloud Run deploy-list-describe / Cloud Storage ls-cp-rm / `custom` passthrough; AI tool `gcloud`) wrapping the official gcloud CLI (pinned versioned archive via pooch into `package_dir("gcloud")` — NOT npm; the Windows bundled-python zip keeps the legacy `google-cloud-sdk-` filename prefix, the `-cli-` spelling 404s, locked by test). Cloudflare login variant (CLI opens the browser itself, random loopback port — no fixed-port hazard) + the gh marker-token pattern; success gate = `gcloud auth list --filter=status:ACTIVE --format=json` non-empty (exit codes never trusted). **Config isolation divergence from gh**: every invocation pins `CLOUDSDK_CONFIG=<DATA_DIR>/gcloud/`, so terminal logins against the operator's global gcloud are deliberately NOT visible to the node. ADC note: node login mints gcloud USER creds only (CLI commands never read ADC); client-library code gets ADC via the `custom` op `auth application-default login` (lands isolated in the pinned dir). Cold install ~100 MB → login answers `pending: True` within the 22 s WS budget. Provider id `gcloud` is orthogonal to the Workspace `google` OAuth2 provider. Palette group `deployment`. |
+| **[Discord Service](./docs-internal/discord_service.md)** | Discord bot integration — `discordSend` / `discordAction` (AI tools) + `discordReceive` / `discordInteraction` triggers. **discord.py owns the gateway, REST is plugin-owned** (nodes must work with no gateway, `discordAction` needs arbitrary routes, and the invalid-request guard is process-wide across accounts). **Multi-account rides the existing `session_id` credential column** — `_accounts.py` is the only file that knows `account_id -> "discord:<app_id>"`, `"default"` is the row the modal already writes, and `credential_customer_id` is deliberately NOT used (it is per-execution-context tenancy, so two nodes in one workflow could never target different bots). **`AccountScopedNode` exists because `server_controlled_fields` is enforced only in `execute_as_tool`'s ToolNode branch** — a dual-purpose ActionNode takes an earlier `{**node_params, **tool_args}` merge with model args winning, so locked fields are stripped before it. Attachments are metadata on the trigger and downloaded by `discordAction` (deployed triggers never run their node body). Interaction tokens never leave the server — the trigger emits an opaque ref. The interactions endpoint is a plugin router, not a `WebhookSource`: Discord's validation probe requires **401** (the generic intake raises 400) and the 3-second ACK deadline precludes awaiting `emit`. Rate limiting is reactive; the invalid-request guard is **process-global** because Cloudflare bans the source IP, not the token. |
| **[Sarvam AI Service](./docs-internal/sarvam_service.md)** | Sarvam AI (Indic-first). **`nodes/sarvam/` no longer exists** — every capability it served is now a *provider* inside an abstracted node: speech in `nodes/speech/`, and translate / transliterate / detect-language in `nodes/translate/`. What remains Sarvam-specific is `sarvamChatModel` (an **OpenAI-compat provider**: one `_COMPAT_PROVIDERS` entry + a JSON block, no provider subclass) under `nodes/model/`. **One stored key spans two auth styles** — the chat route takes `Authorization: Bearer` (what the openai SDK sends) while every other endpoint takes only `api-subscription-key`, so `SarvamCredential` declares the native header and every surface shares it. Introduces the generic **`supports_model_listing: false`** flag: Sarvam ships no `/v1/models` route, and unhandled that 404 becomes a `NodeUserError` that `AIService.fetch_models` re-raises *before* its curated fallback, breaking key validation and the model dropdown — so `OpenAIProvider.fetch_models` serves the curated list and probes with a one-token completion instead (defaults `true`; the other 12 providers are untouched, locked by test). Also added generic **`Connection.request(files=)`** multipart support. |
| **[Speech Provider RFC](./docs-internal/speech_provider_rfc.md)** | Provider-abstracted speech — two nodes (`textToSpeech`, `speechToText`) with a `provider` dropdown, backed by **two registries, one per direction** (registry membership IS the capability: a synthesis-only vendor simply never appears in the transcription enum). Everything vendor-specific lives in the plugin folder [`server/nodes/speech/`](./server/nodes/speech/) — protocol, registries, dispatch, per-vendor modules; only the generic `services/provider_registry.py` and the vendor-neutral `services/media/` are shared. v1 providers: OpenAI (both directions), ElevenLabs (TTS), Deepgram + Groq (STT), Sarvam (both). Capabilities are JSON (`server/config/speech_defaults.json`) with per-model overrides, so no shared code branches on a provider name. **Audio never travels as bytes** — nodes return an `AudioRef` (a ~400 B reference) because a 12 MB base64 result blows Temporal's 2 MiB blob limit and retries 3× re-billing the provider each time. Backing routes: `GET/POST /api/workspace/{workflow_id}/…` in [`routers/workspace.py`](./server/routers/workspace.py). |
| **[Media Transport](./docs-internal/media_transport.md)** | How files move through the engine, and why they move as **references rather than bytes**. `services/media/` — `FileRef` (the base; `FileKind = file\|audio\|image\|video\|document`) with `AudioRef(FileRef)` as the probed-container narrowing (~400 B, `extra="forbid"` so adding a bytes field is a `ValidationError` rather than a silent regression), `write_audio` / `resolve_media` / `coerce_file_param` (the one nodes should call — accepts a `FileRef`/`AudioRef`, a bare path, or the legacy base64 envelope), `inspect_audio` (tinytag → stdlib `wave` → PCM arithmetic, **never raises**), `limits.py`, and **`preview.py` — the single owner of the inline-vs-attachment rule**, with two consumers: `routers/workspace.py` picks its `Content-Disposition` from `serves_inline`, and the gallery listing sets each row's `preview` from `preview_kind`, so the panel can never offer a preview the route refuses to serve. Containment runs through `resolve_within`, which closed a live vulnerability: a node joined a user path onto the workspace root unchecked, so `audio_file="../../credentials.db"` read the encrypted credential store and uploaded it. **The id/slug asymmetry is the trap** — workspace dirs are named by the mutable `Workflow.slug` while a ref stores the immutable `workflow_id` so refs survive rename; the lookup lives in [`services/workspace_locator.py`](./server/services/workspace_locator.py) (`resolve_workspace_root(..., allow_default=)`), and **every mutating caller must pass `allow_default=False`** or an unresolvable id silently lands the write in the shared anonymous workspace. HTTP surface in [`routers/workspace.py`](./server/routers/workspace.py): Range support comes free from Starlette's `FileResponse`; `NEVER_INLINE` is `{image/svg+xml, text/html, text/xml, application/xhtml+xml}` because `shell` / `fileDownloader` / `fileModify` can write arbitrary files into a workspace. |
@@ -656,7 +657,7 @@ The project uses WebSocket as the primary communication method between frontend
> The authoritative, per-node reference is the backend plugin registry plus the per-node "logic-flow" cards under [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) (one card per node, grouped by category, with handles / params / outputs / side-effects / edge-cases). Live node list = the plugin registry (one folder per node under `server/nodes/<group>/`; read the total from `len(services.node_registry.NODE_METADATA)` rather than hardcoding it here — a bare `__init__.py` glob overcounts by also matching the group packages). Do NOT maintain a per-node catalogue here — it drifts on every plugin add.
-Node groups (palette categories): agent, model, skill, tool, trigger, workflow, search, google, android, whatsapp, telegram, twitter, social, email, proxy, chat, scheduler, text, code, document, location, utility, browser, scraper, filesystem, stripe, vercel, github (palette group `vcs`), cloudflare and gcloud (palette group `deployment`), speech and translate (both palette group `language` — provider-abstracted `textToSpeech` / `speechToText` and `translateText` / `transliterateText` / `detectLanguage`; `nodes/sarvam/` was retired into them, and only `sarvamChatModel` under `nodes/model/` remains vendor-named). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
+Node groups (palette categories): agent, model, skill, tool, trigger, workflow, search, google, android, whatsapp, whatsapp_business, telegram, discord, twitter, social, email, proxy, chat, scheduler, text, code, document, location, utility, browser, scraper, filesystem, stripe, vercel, github (palette group `vcs`), cloudflare and gcloud (palette group `deployment`), speech and translate (both palette group `language` — provider-abstracted `textToSpeech` / `speechToText` and `translateText` / `transliterateText` / `detectLanguage`; `nodes/sarvam/` was retired into them, and only `sarvamChatModel` under `nodes/model/` remains vendor-named). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
## Backend Services
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c1aac4ef..5e241205 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -163,6 +163,7 @@ Full setup and scripts reference: [SETUP.md](docs-internal/SETUP.md) - [SCRIPTS.
| [stripe_service.md](docs-internal/stripe_service.md) | Reference Wave 12 plugin — signed webhooks + CLI-managed auth, file-by-file |
| [vercel_service.md](docs-internal/vercel_service.md) | CLI-managed auth, device-flow variant |
| [github_service.md](docs-internal/github_service.md) | gh CLI integration — CLI owns auth entirely |
+| [discord_service.md](docs-internal/discord_service.md) | Discord bot — gateway/REST split, multi-account on the credential `session_id` scope, Ed25519 interactions endpoint |
| [event_waiter_system.md](docs-internal/event_waiter_system.md) | Push-based trigger waiters *(historical, pre-Wave-11 — canvas-Run path only)* |
| [status_broadcaster.md](docs-internal/status_broadcaster.md) | WebSocket broadcaster (live handler count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`) |
| [credentials_encryption.md](docs-internal/credentials_encryption.md) | Fernet + PBKDF2 credentials system |
diff --git a/docs-internal/discord_service.md b/docs-internal/discord_service.md
new file mode 100644
index 00000000..4cf8dbe1
--- /dev/null
+++ b/docs-internal/discord_service.md
@@ -0,0 +1,273 @@
+# Discord Service
+
+Bot messaging, REST actions, gateway message triggers and slash commands.
+Plugin folder: [`server/nodes/discord/`](../server/nodes/discord/).
+
+Reference plugins this one follows: [`nodes/whatsapp_business/`](../server/nodes/whatsapp_business/)
+for the media-on-the-deploy-path question and the webhook shape, and
+[`nodes/telegram/`](../server/nodes/telegram/) for the long-lived-connection
+lifecycle.
+
+## Nodes
+
+| Node | Kind | Purpose |
+|---|---|---|
+| `discordSend` | ActionNode, `usable_as_tool` | Messages, embeds, one file attachment. Splits past 2000 characters. |
+| `discordAction` | ActionNode, `usable_as_tool` | Guilds/channels/messages/reactions/threads, `download_attachments`, `interaction_respond`, `execute_webhook`, `custom`. |
+| `discordReceive` | TriggerNode (event) | Fires on an inbound message. |
+| `discordInteraction` | TriggerNode (event) | Fires on a slash command or component click. |
+
+Palette group `discord`, colour `#5865F2`. Icon is a local `icon.svg` (the
+brand mark); the credential tile resolves `discord.svg`.
+
+**Why send is separate from action.** The single-`<service>Action` convention
+belongs to the CLI wrappers (`githubAction`, `cloudflareAction`, …). Both
+messaging plugins here — telegram and whatsapp_business — keep send separate,
+because send is the high-frequency agent-facing operation and a twenty-operation
+union makes a poor LLM tool schema.
+
+**Why there is no media node.** `whatsappBusinessMedia` exists because Meta
+requires upload-then-reference. Discord attaches files directly in the send
+multipart, so only the download side needs an operation.
+
+**Why interactions are a second trigger.** [`canary_registry`](../server/services/deployment/canary_registry.py)
+maps one node type to exactly one CloudEvents type, because that string becomes
+the Temporal `EventType` Search Attribute the listener is discovered by. One
+node cannot subscribe to both. The payloads also share almost nothing, so
+merging would mean a union output schema and weaker `{{trigger.field}}`
+resolution. Same split, same reasons, as `whatsappBusinessReceive` vs
+`whatsappBusinessStatus`.
+
+## Multi-account
+
+API keys are stored under a `{session_id}_{provider}` key, so the `session_id`
+column is a free scoping axis:
+
+```
+account_id "default" -> session_id "default" (what the modal writes)
+account_id "<app_id>" -> session_id "discord:<app_id>"
+```
+
+[`_accounts.py`](../server/nodes/discord/_accounts.py) is the only file that
+knows this mapping. `"default"` is the row the unmodified credentials modal
+already writes, so a single-bot install needs no account concept and
+multi-account is purely additive. Every node carries an `account_id` param
+backed by the `discordAccounts` option loader; blank means default.
+
+Enumeration needs `AuthService.list_key_scopes(provider)` — added for this
+plugin, generic, index-backed.
+
+**`credential_customer_id` is deliberately not used.** It is per-execution-context
+tenancy, so two nodes in one workflow could never target two different bots. It
+is the tenancy axis, not the account axis, and
+[`test_identity_namespaces.py`](../server/tests/test_identity_namespaces.py)
+exists to keep them apart.
+
+## Security invariants
+
+**`account_id` is stripped from model arguments.** `server_controlled_fields`
+is enforced only in `BaseNode.execute_as_tool`'s ToolNode branch; a dual-purpose
+ActionNode takes an earlier return that merges `{**node_params, **tool_args}`
+with model arguments winning ([base.py:637-652](../server/services/plugin/base.py)).
+Since inbound Discord messages are the realistic source of hostile tool
+arguments and `account_id` selects which bot identity sends, `AccountScopedNode`
+in [`_base.py`](../server/nodes/discord/_base.py) removes locked fields before
+the merge. A test drives the real tool path rather than asserting the
+declaration.
+
+**The interaction token never leaves the server.** It is a 15-minute bearer
+credential that can post as the app, and trigger output is persisted three ways,
+broadcast twice, retained in the status cache and replayed into LLM context each
+turn. `discordInteraction` emits an opaque `interaction_ref`;
+`discordAction[interaction_respond]` trades it back through a process-local TTL
+map. Refs do not survive a restart, which is not a gap — a workflow that
+outlived a restart mid-interaction has already missed the window.
+
+**`custom` route paths are validated in `_base.build_url`,** not at the call
+site, so no future caller can skip it. Without the guard that operation would
+send the bot token to any host a workflow named. Webhook URLs are host-whitelisted
+by `assert_discord_host`, and neither a webhook URL nor an interaction URL is
+ever echoed in an error — both embed credentials.
+
+**Snowflakes are stringified** at the dispatch boundary. discord.py exposes them
+as `int` while Discord's own JSON uses strings; past 2^53 a numeric comparison
+collapses two distinct ids, and comparing an id is the most natural edge
+condition a user writes (see commit `20d00a07`).
+
+## Rate limiting
+
+[`_ratelimit.py`](../server/nodes/discord/_ratelimit.py) is pure state, no IO.
+Reactive rather than predictive: it reads 429s and holds what follows, but does
+not track `X-RateLimit-Remaining` to sleep before hitting zero. Three scopes,
+and conflating any two is a bug:
+
+- **per account** — the 50 req/s ceiling is per bot token.
+- **per account** — a global 429 pauses that token entirely.
+- **per process** — the invalid-request ban is enforced by Cloudflare on the
+ source IP, not the token. Three misconfigured bots on one host share one
+ budget and blowing it takes out the healthy accounts too. This is the piece
+ most likely to be "simplified" into the per-account limiter later. It must
+ not be.
+
+A 429 with a non-JSON body is the Cloudflare edge ban, not a Discord rate limit,
+and is reported as such. Any wait over ~30s becomes a retryable `RuntimeError`
+(never `NodeUserError`, which is non-retryable) so Temporal's backoff releases
+the worker slot instead of pinning it.
+
+## Gateway
+
+`discord.Client` owns the socket. What it handles is exactly the part that
+fails silently when hand-rolled: zlib framing, heartbeat/ACK with jitter,
+RESUME versus IDENTIFY on the right close codes, `resume_gateway_url`, and
+IDENTIFY concurrency. `Client.start()` is used, never `run()` — the latter
+installs signal handlers and would fight uvicorn.
+
+REST does **not** go through discord.py. The nodes must work with no gateway
+connection at all, `discordAction` needs arbitrary routes the typed methods do
+not expose, and the invalid-request guard has to be process-wide across
+accounts, which a per-client limiter cannot express. Gateway and REST never
+cross; calling `client.http` from node code would bypass the limiter that knows
+the shared budget.
+
+`BaseSupervisor.get_instance()` is a per-subclass singleton and cannot hold N
+connections, so gateways live in a module-level registry keyed by account, each
+registering its own label with `services._supervisor` so
+`shutdown_all_supervisors()` still reaches them.
+
+**Terminal failures are not retried.** `PrivilegedIntentsRequired` and
+`LoginFailure` fail identically every attempt; backing off spends the
+1000-IDENTIFY daily budget, which ends in a reset token and an email to the
+app owner. Both are translated into actionable errors and the gateway refuses
+further retries. Readiness races the connection task rather than awaiting
+`wait_until_ready()` alone, because login failures raise inside `start()` —
+awaiting readiness would sit out the full 60s timeout and then report "not
+ready" for a bad credential.
+
+## Attachments
+
+`discordReceive` emits attachment **metadata only**;
+`discordAction[operation="download_attachments"]` fetches them via
+[`fetch_to_workspace`](../server/services/media/fetch.py) (SSRF guard, streaming,
+25 MB cap, contained write, `FileRef` out).
+
+The reason is the deploy path: the engine marks a deployed trigger
+`_pre_executed` and passes `_trigger_output` through verbatim
+([models.py:378-392](../server/services/execution/models.py)), so the node body
+never runs and a download flag there would work on the canvas and silently do
+nothing once deployed. `whatsappBusinessMedia` exists for the same reason and
+documents it in its own module docstring.
+
+`kind` is never `"audio"`: that asserts a real container probe, and a download
+measures nothing. Discord CDN URLs are signed and expire, so they are resolved
+immediately before fetching and never trusted from a stored output.
+
+## Interactions endpoint
+
+`POST /api/discord/interactions[/{account_id}]`, a plugin-owned router rather
+than a `WebhookSource`, for three reasons the generic intake cannot express:
+
+- Discord's endpoint-validation probe sends a deliberately invalid signature
+ and requires **401**. `WebhookSource.handle` raises 400, and a 400 makes
+ Discord refuse to save the endpoint URL at all.
+- The initial response is due within **three seconds**, but `handle()` awaits
+ shaping, `emit` (a Visibility query plus a Signal per consumer) and dispatch
+ before the router writes a byte.
+- PING must be answered with `{"type": 1}`, while the generic route returns a
+ fixed envelope.
+
+Flow: raw-body Ed25519 verify → 401 on failure → **503 fail-closed** when no
+public key is stored → PING answers PONG → anything else defers (type 5, or
+type 6 for a component so the existing message is edited) and fans out in a
+background task whose reference is held, since the loop keeps only a weak one.
+
+Per-account paths exist so the server never trial-verifies against every stored
+public key, which would be both a timing oracle and an availability multiplier.
+
+[`DiscordEd25519Verifier`](../server/nodes/discord/_verifier.py) is the first
+asymmetric verifier in the tree — the four shipped ones are HMAC — and uses
+`cryptography`, already a dependency. **Do not add PyNaCl.** It verifies over
+the raw body, never re-serialised JSON: any difference in key order or
+separators breaks authentic requests.
+
+**Gateway and HTTP interaction delivery are mutually exclusive per application.**
+Setting an Interactions Endpoint URL stops `INTERACTION_CREATE` arriving over
+the socket.
+
+## Router mounting
+
+The interaction routes are added onto the router
+`make_oauth_callback_router` builds, rather than into a fresh `APIRouter` with
+the factory's router included into it. On an `APIRouter` — unlike on an app —
+`include_router` records a pathless placeholder instead of flattening the
+child's routes: the callback silently never mounts, and the pathless entry
+reads as an ungated route to `TestPublicSurfaceInvariant`. That test is what
+caught it.
+
+## Credentials
+
+One provider entry, `kind: "apiKey"`, fields:
+
+| Key | Required | Purpose |
+|---|---|---|
+| `apiKey` | yes | Bot token. Stored under provider id `discord`. |
+| `discord_application_id` | no | Labels the bot when several are connected. |
+| `discord_public_key` | no | Ed25519 public key; slash commands only. |
+| `discord_client_id` / `discord_client_secret` | no | OAuth2 user-context. |
+
+`DiscordBotCredential` **overrides `inject()`**: the inherited `bearer` mode
+hardcodes the literal `Bearer ` prefix and Discord bot auth is `Bot <token>`,
+which otherwise fails as a silent 401.
+
+The probe calls `/users/@me` then `/applications/@me` and reports whether the
+**Message Content** privileged intent is enabled. Without it the gateway still
+connects and delivers empty `content` with no error anywhere — which surfaces
+as "the Discord node returns blank text".
+
+`DiscordUserCredential` (`discord_oauth`) is the user-context identity, stored
+under a separate id so connecting a user never overwrites the bot token. Scopes
+are `identify` and `guilds` only.
+
+## Registration surfaces
+
+Everything self-registers from [`__init__.py`](../server/nodes/discord/__init__.py):
+WS handlers, router, OAuth callback path, three option loaders, four output
+schemas, two filter builders, a trigger precheck, service refresh, two canary
+trigger types, the social send adapter, and a shutdown hook.
+
+Outside the folder: `nodes/groups.py`, `config/credential_providers.json`,
+`config/node_allowlist.json`, `constants.py` (both trigger frozensets), and the
+three lists in `tests/test_plugin_self_containment.py`.
+
+**`import discord` never appears at module scope** in any file the plugin
+walker touches. [`nodes/__init__.py`](../server/nodes/__init__.py) swallows
+import errors during discovery, so a failing library import would make the
+whole plugin silently disappear rather than report anything.
+
+**Both trigger frozensets matter.** Omitting a trigger from
+`EVENT_TRIGGER_TYPES` / `WORKFLOW_TRIGGER_TYPES` is a silent failure: deploy
+filters on them and ignores the node with no listener and no warning
+([constants.py:400](../server/constants.py)). Tests assert the membership.
+
+## Testing
+
+[`server/tests/nodes/test_discord.py`](../server/tests/nodes/test_discord.py) —
+121 tests, no live bot required. Covers account scoping, the path guard, error
+classification, rate-limit parsing, content splitting, the tool-path account
+lock, send/action shapes, event shaping, filters, gateway lifecycle, the
+Ed25519 verifier, the endpoint's 401/503/PONG/defer behaviour, and route
+mounting.
+
+**Not testable without a live bot:** the gateway handshake, IDENTIFY limits,
+session resume, sharding, and Discord's own intent gating. Manual smoke
+checklist:
+
+1. Add a bot token in Credentials; confirm the probe reports the Message
+ Content intent state.
+2. Connect from the modal; confirm the status shows the bot username and guild
+ count.
+3. Send to a channel, with and without an attachment.
+4. Post a message in that channel and confirm `discordReceive` fires on Run.
+5. Deploy the workflow and confirm it still fires — this is the path the
+ frozensets gate.
+6. For slash commands, set the Interactions Endpoint URL and confirm Discord
+ accepts it (that is the 401 path being exercised).
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index 93a2b54b..9ab8fa75 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -102,6 +102,13 @@ match its doc here, and each doc must still describe what the code does.
- [Shell (`shell`)](./code_fs_process/shell.md)
- [TypeScript Executor (`typescriptExecutor`)](./code_fs_process/typescriptExecutor.md)
+### discord
+
+- [Discord (`discordAction`)](./discord/discordAction.md)
+- [Discord Interaction (`discordInteraction`)](./discord/discordInteraction.md)
+- [Discord Receive (`discordReceive`)](./discord/discordReceive.md)
+- [Discord Send (`discordSend`)](./discord/discordSend.md)
+
### document
- [Document Parser (`documentParser`)](./document/documentParser.md)
diff --git a/docs-internal/node-logic-flows/discord/discordAction.md b/docs-internal/node-logic-flows/discord/discordAction.md
new file mode 100644
index 00000000..fccb8b62
--- /dev/null
+++ b/docs-internal/node-logic-flows/discord/discordAction.md
@@ -0,0 +1,128 @@
+# Discord (`discordAction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | discord |
+| **Backend handler** | [`server/nodes/discord/discord_action.py`](../../../server/nodes/discord/discord_action.py) (`DiscordActionNode`, on `AccountScopedNode`) |
+| **Tests** | [`server/tests/nodes/test_discord.py`](../../../server/tests/nodes/test_discord.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | yes — tool name `discord` |
+
+## Purpose
+
+The REST surface beyond sending: servers, channels, messages, reactions,
+threads. Also the two operations that exist for structural reasons rather than
+API symmetry — `download_attachments` (because a deployed trigger never runs
+its node body) and `interaction_respond` (because the interaction token must
+never travel through node output).
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data; typically a `discordReceive` payload |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `operation` | enum (14) | `list_channels` | yes | – | See below |
+| `account_id` | string | `""` | no | – | Which bot acts. **Stripped from model arguments.** |
+| `guild_id` | string | `""` | yes* | `list_channels` | Server snowflake |
+| `channel_id` | string | `""` | yes* | most ops | Channel snowflake |
+| `message_id` | string | `""` | yes* | message ops | Message snowflake |
+| `content` | string | `""` | yes* | `edit_message` | Replacement body |
+| `emoji` | string | `""` | yes* | `add_reaction` | Unicode emoji or `name:id` |
+| `thread_name` | string | `""` | yes* | `create_thread` | New thread name |
+| `limit` | int (1–100) | `50` | no | `list_messages` | Page size |
+| `attachments` | list[dict] | `[]` | yes* | `download_attachments` | Rows from a trigger |
+| `interaction_ref` | string | `""` | yes* | `interaction_respond` | Opaque handle from `discordInteraction` |
+| `interaction_message` | string | `""` | yes* | `interaction_respond` | Response body |
+| `webhook_url` | password | `""` | yes* | `execute_webhook` | Discord webhook URL |
+| `webhook_content` | string | `""` | yes* | `execute_webhook` | Body |
+| `method` / `path` / `body` | – | – | yes* | `custom` | Raw route escape hatch |
+
+Operations: `list_guilds`, `list_channels`, `get_channel`, `create_thread`,
+`list_messages`, `get_message`, `edit_message`, `delete_message`,
+`add_reaction`, `pin_message`, `download_attachments`, `interaction_respond`,
+`execute_webhook`, `custom`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `DiscordActionOutput` |
+| `output-tool` | – | Auto-appended |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ result?: object; // single-object responses
+ items: any[]; // list responses, so the declared shape stays an object
+ count?: number;
+ files: FileRef[]; // download_attachments; references, never bytes
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[operation] --> B{kind}
+ B -- read/write --> C[_base.request with account token]
+ B -- download_attachments --> D[resolve each url] --> E[fetch_to_workspace] --> F[FileRef rows]
+ B -- interaction_respond --> G[resolve_token ref] --> H[PATCH webhooks/app/token/messages/@original]
+ B -- execute_webhook --> I[assert_discord_host] --> J[POST webhook url]
+ B -- custom --> K[build_url validates path] --> C
+ C --> L{status}
+ L -- 429 --> M[Cloudflare ban? -> NodeUserError : RateLimitExceeded]
+ L -- >=400 --> N[raise_for_discord_error]
+ L -- ok --> O[shape output]
+```
+
+## Decision Logic
+
+- **Validation**: every id/name goes through `_require`, which raises
+ `NodeUserError` naming the missing field.
+- **`custom` paths** are validated in `_base.build_url` — relative only, no
+ scheme, no `//`, no `..`. The guard lives there, not at the call site, so no
+ future caller can skip it; without it this operation would send the bot token
+ to any host a workflow named.
+- **`download_attachments`** never claims `kind="audio"`: that asserts a real
+ container probe and a download measures nothing. Rows without a `url` are
+ skipped rather than failing the batch.
+- **`interaction_respond`** PATCHes `@original` because the endpoint already
+ deferred within Discord's three-second window; an unknown or expired ref is a
+ `NodeUserError` naming the 15-minute limit.
+- **Error paths**: auth → annotated `PermissionError` (credential envelope +
+ reconnect affordance); permission/not-found → `NodeUserError` (terminal);
+ 429/5xx → `RuntimeError` (retryable).
+
+## Side Effects
+
+- **File I/O**: `download_attachments` writes into the workflow workspace via
+ `fetch_to_workspace` (SSRF guard, streaming, 25 MB cap, contained write).
+- **External API calls**: many; all through `_base` except the two that carry
+ their own auth (webhook URL, interaction token), which deliberately bypass
+ the account path.
+
+## External Dependencies
+
+- **Credentials**: `DiscordBotCredential`; the webhook and interaction routes
+ carry their own auth and use none.
+- **Python packages**: `httpx`.
+
+## Edge cases & known limits
+
+- List responses can be large; `limit` caps messages at 100. `BaseNode`
+ warns at 512 KB and hard-fails at the 2 MiB Temporal ceiling.
+- Webhook URLs and interaction URLs are never echoed in errors — both embed
+ credentials.
+- `interaction_ref` does not survive a restart, by design.
+
+## Related
+
+- **Consumes**: `discordReceive.attachments`, `discordInteraction.interaction_ref`.
+- **Architecture docs**: [discord_service.md](../../discord_service.md),
+ [media_transport.md](../../media_transport.md)
diff --git a/docs-internal/node-logic-flows/discord/discordInteraction.md b/docs-internal/node-logic-flows/discord/discordInteraction.md
new file mode 100644
index 00000000..79f9edc1
--- /dev/null
+++ b/docs-internal/node-logic-flows/discord/discordInteraction.md
@@ -0,0 +1,121 @@
+# Discord Interaction (`discordInteraction`)
+
+| Field | Value |
+|------|-------|
+| **Category** | discord / trigger |
+| **Backend handler** | [`server/nodes/discord/discord_interaction.py`](../../../server/nodes/discord/discord_interaction.py); endpoint in [`_router.py`](../../../server/nodes/discord/_router.py), shaping + token store in [`_interactions.py`](../../../server/nodes/discord/_interactions.py), signatures in [`_verifier.py`](../../../server/nodes/discord/_verifier.py) |
+| **Tests** | [`server/tests/nodes/test_discord.py`](../../../server/tests/nodes/test_discord.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | no (trigger) |
+
+## Purpose
+
+Fire on a slash command, component click or modal submit. Interactions arrive
+over HTTP at `POST /api/discord/interactions[/{account_id}]`, are Ed25519
+verified, acknowledged inside Discord's three-second deadline, and emitted as
+`com.opencompany.discord.interaction.created`.
+
+A second trigger node rather than a mode on `discordReceive`:
+`canary_registry` maps one node type to exactly one CloudEvents type, because
+that string becomes the Temporal `EventType` Search Attribute the listener is
+found by. One node cannot subscribe to both.
+
+## Inputs (handles)
+
+None — this is a trigger.
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `account_id` | string | `""` | no | – | Which app to accept interactions for |
+| `interaction_kind` | `all \| command \| component \| modal` | `all` | no | – | Maps to Discord types 2 / 3 / 5 |
+| `command_name` | string | `""` | no | `all\|command` | Leading `/` is tolerated |
+| `custom_id` | string | `""` | no | `all\|component\|modal` | Component identifier |
+| `guild_id` | string | `""` | no | – | Only this server |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `DiscordInteractionOutput` |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ account_id: string;
+ interaction_id: string;
+ interaction_type: number; // 2 command, 3 component, 5 modal
+ application_id: string;
+ command_name?: string;
+ custom_id?: string;
+ component_type?: number;
+ options: Record<string, unknown>; // slash-command options, flattened
+ channel_id?: string; guild_id?: string;
+ user_id?: string; user_name?: string;
+ interaction_ref: string; // opaque handle. NEVER the token.
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[POST /api/discord/interactions] --> B[read RAW body]
+ B --> C{public key stored}
+ C -- no --> R503[503 + Retry-After: fail closed]
+ C -- yes --> D[Ed25519 verify over timestamp + body]
+ D -- mismatch --> R401[401 - required by Discord's probe]
+ D -- ok --> E{type}
+ E -- 1 PING --> P[respond type 1 PONG]
+ E -- other --> F[shape_interaction: token -> ref]
+ F --> G[respond type 5, or 6 for a component]
+ G --> H[background task: dispatch.emit]
+ H --> I[Temporal listener matched by EventType SA]
+```
+
+## Decision Logic
+
+- **401, not 400, on a bad signature.** Discord's endpoint-validation probe
+ sends an invalid signature on purpose and refuses to save the URL unless it
+ gets a 401. This is why the generic `WebhookSource` intake cannot host this
+ endpoint — it raises 400.
+- **Fail closed with 503** when no public key is stored; accepting unverified
+ requests would let anyone trigger workflows.
+- **Defer, then work.** A workflow cannot run in three seconds, so the endpoint
+ ACKs and fans out afterwards. A component defers as type 6
+ (`DEFERRED_UPDATE_MESSAGE`) so the existing message is edited rather than an
+ empty new one being posted.
+- **Verification is over the raw body**, never re-serialised JSON: any change
+ in key order or separators breaks authentic requests.
+- **Per-account paths** avoid trial-verifying against every stored public key,
+ which would be a timing oracle and an availability multiplier.
+
+## Side Effects
+
+- **In-memory**: `interaction_ref -> (application_id, token)` in a TTL map
+ (14 minutes, just inside Discord's 15).
+- **Broadcasts**: `discord_interaction_created`.
+
+## External Dependencies
+
+- **Credentials**: `discord_public_key` on the account's credential scope.
+- **Python packages**: `cryptography` (already a dependency). **Not PyNaCl.**
+
+## Edge cases & known limits
+
+- **Gateway and HTTP delivery are mutually exclusive per application.** Setting
+ an Interactions Endpoint URL stops `INTERACTION_CREATE` over the socket.
+- The interaction token never appears in node output — it is a bearer
+ credential and trigger output is persisted, broadcast and replayed into LLM
+ context. `discordAction[interaction_respond]` trades the ref back.
+- Refs do not survive a restart. A workflow that outlived one mid-interaction
+ has already missed the 15-minute window.
+- Requires a publicly reachable server.
+- Must appear in both trigger frozensets or deploy ignores it silently.
+
+## Related
+
+- **Downstream**: `discordAction[interaction_respond]` completes the reply.
+- **Architecture docs**: [discord_service.md](../../discord_service.md)
diff --git a/docs-internal/node-logic-flows/discord/discordReceive.md b/docs-internal/node-logic-flows/discord/discordReceive.md
new file mode 100644
index 00000000..ccf18cd7
--- /dev/null
+++ b/docs-internal/node-logic-flows/discord/discordReceive.md
@@ -0,0 +1,120 @@
+# Discord Receive (`discordReceive`)
+
+| Field | Value |
+|------|-------|
+| **Category** | discord / trigger |
+| **Backend handler** | [`server/nodes/discord/discord_receive.py`](../../../server/nodes/discord/discord_receive.py); connection in [`_gateway.py`](../../../server/nodes/discord/_gateway.py), shaping in [`_dispatch.py`](../../../server/nodes/discord/_dispatch.py), filtering in [`_filters.py`](../../../server/nodes/discord/_filters.py) |
+| **Tests** | [`server/tests/nodes/test_discord.py`](../../../server/tests/nodes/test_discord.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | no (trigger) |
+
+## Purpose
+
+Fire when a message arrives in a server channel or a DM. Messages come over a
+persistent gateway connection held per bot account, are flattened, and emitted
+as CloudEvents of type `com.opencompany.discord.message.received`.
+
+## Inputs (handles)
+
+None — this is a trigger; it is the head of a run.
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `account_id` | string | `""` | no | – | Which bot listens |
+| `scope` | `all \| guild \| dm` | `all` | no | – | Server channels, DMs, or both |
+| `guild_id` | string | `""` | no | `scope=all\|guild` | Only this server |
+| `channel_id` | string | `""` | no | – | Only this channel |
+| `author_id` | string | `""` | no | – | Only this user |
+| `keywords` | string | `""` | no | – | Comma-separated; fires if any appears |
+| `require_mention` | bool | `false` | no | – | Only when the bot is mentioned |
+| `require_attachment` | bool | `false` | no | – | Only messages with a file |
+| `ignore_bots` | bool | `true` | no | – | Off invites bot-to-bot loops |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `DiscordReceiveOutput` |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ account_id: string;
+ message_id: string; // every snowflake is a STRING
+ channel_id: string; channel_name?: string;
+ guild_id?: string; guild_name?: string;
+ is_dm: boolean; // guild_id is null for a DM
+ author_id: string; author_name?: string;
+ author_display_name?: string; author_is_bot: boolean;
+ content: string; // empty without the Message Content intent
+ timestamp?: string;
+ attachments: Array<{ id, filename, size, url, content_type, width?, height? }>;
+ has_attachments: boolean;
+ mentions_me: boolean;
+ reply_to_message_id?: string;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[discord.Client on_message] --> B{author is me}
+ B -- yes --> Z[drop: would loop]
+ B -- no --> C[shape_message: stringify snowflakes]
+ C --> D[dispatch.emit CloudEvent]
+ D --> E[Temporal listener matched by EventType SA]
+ E --> F[node filter gates the spawn]
+ F --> G[child MachinaWorkflow run]
+ D --> H[in-process WS broadcast for canvas Run]
+```
+
+## Decision Logic
+
+- **Self-messages are dropped** at the gateway handler — a workflow that
+ replies would otherwise trigger itself.
+- **Filtering** is built once at deploy time and closes over its parameters;
+ the per-event path is plain comparisons. Account scoping is not a
+ convenience: without it, connecting a second bot makes every trigger fire
+ twice.
+- **Run-button pre-flight**: `execute` refuses when no gateway is connected for
+ the selected account, rather than registering a waiter that can never
+ resolve (which reads as a hung node). `precheck_discord_trigger` does the
+ same for deploy.
+- **Error paths**: one malformed message is logged and dropped; it must not
+ kill the receive loop.
+
+## Side Effects
+
+- **Broadcasts**: `plugin_connection_status` on connect/disconnect;
+ `discord_message_received` per message.
+- **External**: a persistent WSS gateway connection per account.
+
+## External Dependencies
+
+- **Credentials**: `DiscordBotCredential`.
+- **Python packages**: `discord.py` (imported inside functions only —
+ `nodes/__init__.py` swallows import errors, so a module-scope import would
+ make the whole plugin vanish silently).
+
+## Edge cases & known limits
+
+- **`content` is empty without the Message Content privileged intent**, with no
+ error anywhere. The credential probe reports the flag; this is the single
+ most confusing failure mode.
+- Attachments are metadata only. `discordAction[download_attachments]` fetches
+ them, because a deployed trigger never runs its node body.
+- CDN URLs are signed and expire; do not persist one and fetch it later.
+- Snowflakes are strings. A numeric comparison past 2^53 collapses distinct
+ ids (see commit `20d00a07`).
+- Must appear in both `EVENT_TRIGGER_TYPES` and `WORKFLOW_TRIGGER_TYPES` or
+ deploy silently ignores the node.
+
+## Related
+
+- **Downstream**: `discordAction` (download attachments), `discordSend` (reply).
+- **Architecture docs**: [discord_service.md](../../discord_service.md),
+ [event_framework.md](../../event_framework.md)
diff --git a/docs-internal/node-logic-flows/discord/discordSend.md b/docs-internal/node-logic-flows/discord/discordSend.md
new file mode 100644
index 00000000..6c226df2
--- /dev/null
+++ b/docs-internal/node-logic-flows/discord/discordSend.md
@@ -0,0 +1,116 @@
+# Discord Send (`discordSend`)
+
+| Field | Value |
+|------|-------|
+| **Category** | discord |
+| **Backend handler** | [`server/nodes/discord/discord_send.py`](../../../server/nodes/discord/discord_send.py) (`DiscordSendNode`, on `AccountScopedNode`); HTTP in [`_base.py`](../../../server/nodes/discord/_base.py) |
+| **Tests** | [`server/tests/nodes/test_discord.py`](../../../server/tests/nodes/test_discord.py) |
+| **Skill (if any)** | none |
+| **Dual-purpose tool** | yes — tool name `discord_send` |
+
+## Purpose
+
+Post a message to a channel or open a DM with a user. Text, rich embeds and a
+file attachment. Kept separate from `discordAction` because it is the
+high-frequency agent-facing operation and a twenty-operation union makes a poor
+LLM tool schema — the same split telegram and whatsapp_business make.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data for template resolution |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `account_id` | string | `""` | no | – | Which bot sends. Blank = default credential. **Stripped from model arguments.** |
+| `target_type` | `channel \| user` | `channel` | no | – | Post in a channel or DM a user |
+| `channel_id` | string | `""` | yes* | `target_type=channel` | Channel snowflake |
+| `user_id` | string | `""` | yes* | `target_type=user` | User snowflake; a DM channel is opened |
+| `message` | string | `""` | no | – | Body; split past 2000 characters |
+| `embeds` | list[dict] | `[]` | no | – | Up to 10 embed objects |
+| `attachment` | file | `None` | no | – | One file, sent as multipart |
+| `reply_to_message_id` | string | `""` | no | – | Quote a message |
+| `suppress_embeds` | bool | `false` | no | – | Message flag `1 << 2` |
+| `tts` | bool | `false` | no | – | Text-to-speech |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | `DiscordSendOutput` |
+| `output-tool` | – | Auto-appended for `usable_as_tool` |
+
+### Output payload (TypeScript shape)
+
+```ts
+{
+ message_id: string; // the FIRST message when split
+ channel_id: string;
+ parts?: number; // present only when split
+ message_ids: string[]; // every message id, in order
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Validate params] --> B{target_type}
+ B -- user --> C[POST users/@me/channels -> dm channel id]
+ B -- channel --> D[channel_id]
+ C --> E{content, embeds or attachment present}
+ D --> E
+ E -- none --> ERR[NodeUserError]
+ E -- ok --> F{embeds > 10}
+ F -- yes --> ERR
+ F -- no --> G[split_content at 2000]
+ G --> H[for each chunk]
+ H --> I{last chunk and attachment}
+ I -- yes --> J[multipart: files[0] + payload_json]
+ I -- no --> K[POST channels/id/messages]
+ J --> L[collect message id]
+ K --> L
+ L --> M[Return first id + parts + message_ids]
+```
+
+## Decision Logic
+
+- **Validation**: empty send (no text, embed or attachment) → `NodeUserError`;
+ >10 embeds → `NodeUserError` (Discord rejects the whole message, so failing
+ locally is clearer); missing channel/user id → `NodeUserError`.
+- **Branches**: DM opens a channel first — Discord has no send-to-user route.
+- **Splitting**: `split_content` prefers a paragraph → line → sentence → space
+ boundary past the halfway mark, else hard-cuts. Length is `len()`: Discord
+ counts code points, unlike Telegram's UTF-16 units.
+- **Ordering**: the reply reference rides only the first chunk; embeds and the
+ attachment ride the last, so they render after the text they belong to.
+
+## Side Effects
+
+- **Broadcasts**: standard node status via `BaseNode.execute`.
+- **External API calls**: `POST /channels/{id}/messages`, `POST /users/@me/channels`,
+ `Authorization: Bot <token>`.
+- **Cost tracking**: `{"service": "discord", "action": "send", "count": 1}`.
+
+## External Dependencies
+
+- **Credentials**: `DiscordBotCredential` (`discord`), resolved per account via
+ `_accounts.resolve_secrets`.
+- **Python packages**: `httpx`.
+
+## Edge cases & known limits
+
+- One attachment per message. Discord allows 10; multiple would need a list
+ param and multi-file panel support.
+- `account_id` is removed from tool arguments by `AccountScopedNode` —
+ `server_controlled_fields` alone does nothing on a dual-purpose ActionNode.
+- A 429 over ~30s raises a retryable `RuntimeError` so Temporal re-dispatches
+ rather than pinning a worker slot.
+
+## Related
+
+- **Consumes**: `discordReceive` output (channel/author ids).
+- **Architecture docs**: [discord_service.md](../../discord_service.md)
diff --git a/server/nodes/README.md b/server/nodes/README.md
index f9bd9396..acac67b9 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -114,8 +114,13 @@ android/ — Android device services
google/ — Google Workspace (gmail / calendar / drive / sheets / …)
twitter/ — Twitter/X (send / search / user / receive)
telegram/ — Telegram bot (send / receive)
+discord/ — Discord bot (send / action / receive / interaction).
+ Multi-account: _accounts.py maps an account id onto the
+ session_id credential scope; nothing else knows about it.
whatsapp/ — WhatsApp (send / db / receive)
-social/ — Unified social (send / receive)
+social/ — Unified social (send / receive). Names no platform: each
+ plugin registers a _social.py adapter and owns the mapping
+ onto its own parameter shape.
email/ — IMAP/SMTP via Himalaya CLI
search/ — Web search APIs (brave / serper / perplexity / duckduckgo)
scraper/ — Apify / Crawlee
@@ -204,6 +209,7 @@ from ._credentials import TwitterCredential # shared with 3 sibling
| `nodes/location/` | `GoogleMapsCredential` (API key via `?key=`) | gmaps_create / gmaps_locations / gmaps_nearby_places |
| `nodes/twitter/` | `TwitterCredential` (OAuth2 + PKCE) | twitter_send / _search / _user / _receive |
| `nodes/telegram/` | `TelegramCredential` (bot token + owner chat id) | telegram_send / _receive |
+| `nodes/discord/` | `DiscordBotCredential` (bot token; overrides `inject()` because Discord uses `Bot <token>`, not the inherited `Bearer `) + `DiscordUserCredential` (OAuth2 user context, separate id so connecting a user never overwrites the bot) | discord_send / _action / _receive / _interaction |
| `nodes/scraper/` | `ApifyCredential` (Bearer) | apify_actor |
| `nodes/model/` | 13 LLM credential classes: 11 cloud (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / xAI / Sarvam`) plus Ollama / LM Studio | 12 chat models (xAI has no standalone chat-model node) **plus the 5 `nodes/sarvam/` service nodes**, which import `SarvamCredential` from here — one stored key serves Sarvam's OpenAI-compatible chat endpoint *and* its `api-subscription-key` REST APIs |
| `nodes/search/` | `BraveSearch / Serper / Perplexity` inlined in each plugin file | single-use per plugin |