Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(discord): service reference, node cards and index entries
trohitge9753aeeac94
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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 Servicesdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 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.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdindex f9bd9396..acac67b9 100644--- a/server/nodes/README.md+++ b/server/nodes/README.md@@ -114,8 +114,13 @@ android/ — Android device servicesgoogle/ — 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 CLIsearch/ — 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 |