Skip to content

Self-improving AI Employees for everyone

docs: bring the telegram cards and CLAUDE.md in line with the code

trohitg5a587b4410e1
diff --git a/CLAUDE.md b/CLAUDE.md
index 005781e3..952164c1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2656,7 +2656,8 @@ This function:
- **`NodeUserError` (services.plugin)**: typed exception for user/LLM-correctable failures (string not found, command not found, bad cwd, missing required field, operator-only Twitter query, Python sandbox `import`, Node.js sidecar down). `BaseNode.execute()` catches it specifically: single WARN line in the operator log (no traceback) + structured `{success: False, error_type: "NodeUserError", error: ...}` envelope. Genuine bugs still flow through the generic `except Exception` branch and keep their full stacktrace via `logger.exception`. Adopted across `fileRead` / `fileModify` / `fsSearch` / `process_manager` / `pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`. Reach for it whenever the LLM (or user) can fix the input and retry — never for actual server bugs.
- **Process manager Windows shim resolution**: `process_service.start()` resolves `argv[0]` via `shutil.which()` before `asyncio.create_subprocess_exec`. On Windows, `shutil.which` honours `PATHEXT` and returns the absolute `.cmd` path (e.g. `C:\...\npm.cmd`); `CreateProcessW` then launches it directly. No `cmd /c` wrap — same canonical idiom used by `browser_service`, `claude_code_service`, `claude_oauth`, `himalaya_service`. Without this, bare `argv[0]="npm"` raises `WinError 2` because `CreateProcessW` does NOT apply `PATHEXT` to bare names. Missing binary → early `Command not found: '<bin>'. Check spelling or ensure the binary is on PATH.` envelope (no traceback).
- **Process manager port admission + middle panel**: server commands declare listener `ports` (with compatibility inference for `--port`, `-p`, `PORT`, and `*_PORT`). `ProcessService.start()` serializes admission, checks managed reservations plus OS TCP listeners, and returns structured `PORT_IN_USE` without killing the owner or allowing framework auto-port fallback. Explicit ports/environment survive restart. The `isProcessManagerPanel` UI hint gives only `processManager` a full-height workflow-scoped process table with PID/ports/timestamps/elapsed/output and stop/restart controls. See [docs-internal/process_manager.md](./docs-internal/process_manager.md).
-- **Telegram message auto-split**: Telegram Bot API caps `sendMessage.text` at 4096 chars (per https://core.telegram.org/bots/api). `TelegramService.send_message` splits longer text at paragraph → line → sentence → space → hard-cut boundaries via `_split_text` helper, sends each chunk threaded under the previous (`reply_to_message_id` cascade), returns first message's metadata + `parts` + `message_ids[]`. Captions on `send_photo` / `send_document` still take the legacy path and will fail on >1024 chars — separate fix once needed (constants `_TG_TEXT_LIMIT=3500`, `_TG_CAPTION_LIMIT=900` in `_service.py` already account for ~20% HTML expansion from markdown→HTML conversion in `_resolve_body`).
+- **Telegram message auto-split + caption spill**: the Bot API caps `sendMessage.text` at 4096 and media captions at 1024 (constants `_TG_TEXT_LIMIT` / `_TG_CAPTION_LIMIT` in `nodes/telegram/_service.py`; per https://core.telegram.org/bots/api). **Both limits are measured in UTF-16 code units, not characters** — an emoji costs 2 — so length goes through `_tg_len`, never `len()`. `_split_head` cuts one chunk at the cleanest paragraph → line → sentence → space boundary past the halfway mark, else hard-cuts; `_split_text` loops it. `send_message` chunks long text and threads each part under the previous (`reply_to_message_id` cascade), returning the first message's metadata + `parts` + `message_ids[]`. `_send_captioned_media` (used by `send_photo` / `send_document`) truncates an over-long caption at the cap and sends the remainder as a threaded reply with `disable_notification=True`, reporting `caption_truncated` + `follow_up_message_ids` — previously the whole send just failed with `BadRequest("Message caption is too long")`. **Ordering invariant: split the RAW body before `_resolve_body` runs markdown→HTML.** Splitting after conversion can separate a `<b>` from its closing tag, which Telegram rejects with "can't find end of the entity"; Telegram measures the cap against entity-parsed text, so truncating raw markdown is conservative. Locked by `tests/nodes/test_telegram_service.py`.
+- **Telegram inbound content types**: `_format_message` extracts detail dicts for all 11 types via the `_CONTENT_PROBES` / `_DETAIL_EXTRACTORS` tables, plus a normalized `media` block (`kind` / `file_id` / `mime_type` / `file_name` / …) that downstream nodes read instead of branching per type; MIME and filename are synthesised where Telegram omits them. **Probe order is load-bearing**: Telegram sets `message.document` on animation messages too, so `animation` and `video_note` must be probed before `document` and `video` or every GIF classifies as a document. The trigger never downloads — media travels as a `file_id`, never bytes or base64, because node results are persisted, broadcast, and replayed into the LLM conversation every turn.
- **Google OAuth scope expansion**: Google's authorisation server legitimately returns a wider scope set than requested when the OAuth Client's "Data Access" page lists extra scopes (commonly `cloud-platform`) or when `include_granted_scopes` replays a previously-granted scope. `oauthlib` does strict set-equality and aborts with `Warning: Scope has changed`. As of 2026 (`google-auth-oauthlib` 1.2.4, `oauthlib` upstream issue #562 still open), no constructor flag, context manager, or `expected_scopes` argument exists — the documented relief is the env var. `services/google_oauth.py` sets `OAUTHLIB_RELAX_TOKEN_SCOPE=1` via `os.environ.setdefault` BEFORE the `google_auth_oauthlib.flow` import (oauthlib reads it once at parameters-module import; request-time setting races under uvicorn workers), paired with `warnings.filterwarnings(message=r"Scope has changed.*")` to keep the operator log clean. Long-term root cause: audit the Cloud Console Data Access page and remove `cloud-platform` if no handler uses it.
- **Code-executor error mapping** (`pythonExecutor` / `javascriptExecutor` / `typescriptExecutor`): wrap user-code execution and sidecar calls in `try/except`. Python: detect `ImportError("__import__ not found")` (the LLM tried `import X` against the sandboxed builtins) and surface the pre-injected names list (`math, json, datetime, timedelta, re, random, Counter, defaultdict`) plus the suggestion to use `process_manager` for unsupported modules; other exceptions get formatted as `<ErrorName> at line N: <message>` (line N walked from `<string>` frame in the traceback) plus any captured stdout. JS/TS: detect `aiohttp.ClientConnectorError` and surface "JavaScript executor not running on NODEJS_EXECUTOR_PORT. Start the dev runner or fall back to python_executor." All raise `NodeUserError` so the framework logs one WARN line — no aiohttp/CreateProcessW noise in the operator log.
- **Workflow-scoped chat + console history**: chat messages persist with `chat_messages.session_id == <workflow_id>` (or `"default"` when no workflow is open); console logs persist with `console_logs.workflow_id`. Backend `database.get_console_logs(limit, workflow_id=None)` and `clear_console_logs(workflow_id=None)` filter by workflow when given. `handle_clear_console_logs` broadcasts `console_logs_cleared` carrying the `workflow_id` so the existing frontend filter in `WebSocketContext` keeps other workflows' panels intact. Frontend reads `currentWorkflow.id` via the documented Zustand escape hatch (`useAppStore.getState().currentWorkflow?.id`) at call time for `clearChatMessages` / `clearConsoleLogs` / `sendChatMessage` so the callbacks don't re-create on every workflow switch. A dedicated `useEffect([currentWorkflowId, isReady])` resets local `chatMessages` / `consoleLogs` and refetches both when the user opens / switches workflow. Incoming `console_log` broadcasts are filtered by `currentWorkflow.id` so a parallel run on another workflow never bleeds into the active panel. Legacy logs without `workflow_id` still surface (transition guard).
diff --git a/docs-internal/frontend_architecture.md b/docs-internal/frontend_architecture.md
index 93440746..8220a369 100644
--- a/docs-internal/frontend_architecture.md
+++ b/docs-internal/frontend_architecture.md
@@ -526,6 +526,8 @@ Frontend does **not** declare output shapes anymore. The backend owns them exclu
**Adding a new node type's output shape:** define a Pydantic model in `node_output_schemas.py`, register it in `NODE_OUTPUT_SCHEMAS`. The frontend picks it up automatically — no client change, no rebuild. Research and rationale in [docs-internal/schema_source_of_truth_rfc.md](./schema_source_of_truth_rfc.md).
+**`jsonSchemaToShape` must resolve Pydantic's indirection.** `model_json_schema()` does not emit a flat `{field: {type}}` map: `Optional[X]` becomes `{anyOf: [<X>, {type: 'null'}]}` with **no top-level `type`**, and a nested `BaseModel` becomes `{$ref: '#/$defs/Name'}` with the body in `$defs`. A reader that only inspects `prop.type` types both as `'any'`. Since every field on the trigger output models is Optional, that mistyped *every* field and left nested blocks (`telegramReceive.media`, `whatsappReceive.group_info`) with no drillable leaves — the useful drag target is `media.file_id`, not `media`. `resolveSchemaNode` unwraps unions (first non-null branch) and follows local `#/$defs/` pointers, threading the expanded-ref chain through the mutual recursion so a self-referencing model cannot recurse until the stack blows and takes the panel with it. Locked by [jsonSchemaToShape.test.ts](../client/src/components/parameterPanel/__tests__/jsonSchemaToShape.test.ts).
+
### Renderer registry shape (Phase 6 — pending)
When the backend `get_node_spec` handler lands, the inspector will own a 4-file colocated layout under `client/src/components/inspector/`:
diff --git a/docs-internal/node-logic-flows/telegram_social/telegramReceive.md b/docs-internal/node-logic-flows/telegram_social/telegramReceive.md
index abcf17f6..0e13491a 100644
--- a/docs-internal/node-logic-flows/telegram_social/telegramReceive.md
+++ b/docs-internal/node-logic-flows/telegram_social/telegramReceive.md
@@ -3,8 +3,8 @@
| Field | Value |
|------|-------|
| **Category** | social / trigger |
-| **Backend handler** | [`server/nodes/telegram/telegram_receive.py`](../../../server/nodes/telegram/telegram_receive.py) (`TelegramReceiveNode`, a `TriggerNode` with `event_type = "telegram_message_received"`); filter via `build_filter` -> [`build_telegram_filter`](../../../server/services/event_waiter.py) |
-| **Tests** | [`server/tests/nodes/test_telegram_social.py`](../../../server/tests/nodes/test_telegram_social.py) |
+| **Backend handler** | [`server/nodes/telegram/telegram_receive.py`](../../../server/nodes/telegram/telegram_receive.py) (`TelegramReceiveNode`, a `TriggerNode` with `event_type = "telegram_message_received"`); filter via `build_filter` -> [`build_telegram_filter`](../../../server/nodes/telegram/_filters.py) |
+| **Tests** | [`server/tests/nodes/test_telegram_social.py`](../../../server/tests/nodes/test_telegram_social.py) (node level), [`test_telegram_service.py`](../../../server/tests/nodes/test_telegram_service.py) (service level: `_format_message` per content type) |
| **Skill (if any)** | none |
| **Dual-purpose tool** | no (trigger only) |
@@ -14,8 +14,13 @@ Wait for an incoming Telegram message and emit it as the workflow trigger
event. `TelegramReceiveNode` subclasses `TriggerNode`; its `execute` override
first refuses to register if the bot is not connected, then defers to
`TriggerNode.execute`. The Telegram-specific `build_filter` pre-compiles a
-`matches()` closure (via the legacy `build_telegram_filter`) from the node
-parameters. Events are produced by the `TelegramService` long-polling loop
+`matches()` closure (via `build_telegram_filter`, which lives in this plugin
+folder's [`_filters.py`](../../../server/nodes/telegram/_filters.py) — Wave
+11.F moved it out of `services/event_waiter.py`) from the node parameters.
+In practice `__init__.py` pre-registers the builder, so `build_filter` is only
+reached for types absent from `FILTER_BUILDERS`; its import previously still
+pointed at the old `services.event_waiter` location and would have raised
+`ImportError` had that path ever been taken. Events are produced by the `TelegramService` long-polling loop
inside `_on_message_received`. In controlled deployment mode, the trigger
definition and queued CloudEvents live in `WorkflowControlWorkflow`; the
controller filters/deduplicates the stream and starts only actual graph runs.
@@ -31,7 +36,7 @@ All field names are snake_case (no camelCase aliases on the Pydantic model).
| Name | Type | Default | Required | displayOptions.show | Description |
|------|------|---------|----------|---------------------|-------------|
-| `content_type_filter` | options | `all` | no | - | One of `all`/`text`/`photo`/`video`/`audio`/`voice`/`document`/`sticker`/`location`/`contact`/`poll` |
+| `content_type_filter` | options | `all` | no | - | One of `all`/`media`/`text`/`photo`/`video`/`audio`/`voice`/`animation`/`video_note`/`document`/`sticker`/`location`/`contact`/`poll`. `media` matches any message carrying a downloadable file (the eight media kinds), so a workflow can react to "any attachment" without enumerating types |
| `sender_filter` | options | `all` | no | - | `all`/`self`/`private`/`group`/`supergroup`/`channel`/`specific_chat`/`specific_user`/`keywords` |
| `chat_id` | string | `""` | yes when `sender_filter=specific_chat` | `sender_filter: ['specific_chat']` | Numeric chat id or `@username` |
| `from_user` | string | `""` | yes when `sender_filter=specific_user` | `sender_filter: ['specific_user']` | Numeric user id |
@@ -60,20 +65,67 @@ Legacy alias: `chatTypeFilter` is still read by `build_telegram_filter` when
from_first_name: string | null;
from_last_name: string | null;
is_bot: boolean;
- text: string; // msg.text or msg.caption or ''
- content_type: 'text' | 'photo' | 'video' | 'audio' | 'voice'
- | 'document' | 'sticker' | 'location' | 'contact' | 'poll';
+ text: string; // msg.text or msg.caption or '' (unchanged)
+ caption: string; // the caption alone, '' when there is none
+ content_type: 'text' | 'photo' | 'video' | 'audio' | 'voice' | 'animation'
+ | 'video_note' | 'document' | 'sticker' | 'location'
+ | 'contact' | 'poll';
date: string; // ISO timestamp
reply_to_message_id: number | null;
- photo?: { file_id; file_unique_id; width; height; file_size };
- document?: { file_id; file_name; mime_type; file_size };
- location?: { latitude; longitude };
- contact?: { phone_number; first_name; last_name; user_id };
+ media_group_id: string | null;// shared by messages sent as one album
+ has_media: boolean;
+
+ // Normalized view — READ THIS, not the per-type blocks below.
+ media: {
+ kind: 'photo'|'video'|'audio'|'voice'|'animation'|'video_note'|'sticker'|'document';
+ file_id: string; // re-send via telegramSend without re-uploading
+ file_unique_id: string; // stable across bots — a dedup key
+ mime_type: string; // synthesised when Telegram omits it
+ file_name: string; // synthesised when Telegram omits it
+ file_size: number | null;
+ duration: number | null;
+ width: number | null;
+ height: number | null;
+ caption: string;
+ file_path: null; // set only after an explicit download
+ downloaded: false;
+ download_error?: string;
+ } | null;
+
+ // Bounded summary of the quoted message, so an agent asked to
+ // "transcribe this" can see what "this" refers to.
+ reply_to?: {
+ message_id: number;
+ content_type: string;
+ text: string; // capped at 500 chars
+ media?: { kind; file_id; mime_type };
+ };
+
+ // Telegram-native detail blocks, one populated per message.
+ photo?: { file_id; file_unique_id; width; height; file_size };
+ video?: { file_id; file_unique_id; width; height; duration; file_name; mime_type; file_size };
+ animation?: { file_id; file_unique_id; width; height; duration; file_name; mime_type; file_size };
+ video_note?: { file_id; file_unique_id; length; duration; file_size };
+ audio?: { file_id; file_unique_id; duration; performer; title; file_name; mime_type; file_size };
+ voice?: { file_id; file_unique_id; duration; mime_type; file_size };
+ sticker?: { file_id; file_unique_id; width; height; emoji; set_name; is_animated; is_video; file_size };
+ document?: { file_id; file_unique_id; file_name; mime_type; file_size };
+ location?: { latitude; longitude; horizontal_accuracy; live_period };
+ contact?: { phone_number; first_name; last_name; user_id };
+ poll?: { id; question; options; type; is_anonymous; allows_multiple_answers; is_closed; total_voter_count };
}
```
Wrapped in the standard success envelope when an event is received.
+**The trigger never downloads.** `media.file_path` stays `null` and no bytes or
+base64 ever appear: a node result is persisted, broadcast, and — for a
+tool-exposed node — serialized into an LLM message and replayed every turn.
+Media travels as a `file_id`; fetching bytes is a separate, explicit step.
+
+Detail blocks are deliberately scalar-only — no thumbnails, no `PhotoSize`
+arrays, no vcard blobs — so a worst-case event stays around 2 KB.
+
## Logic Flow
```mermaid
@@ -108,8 +160,19 @@ flowchart TD
- `specific_chat` / `specific_user`: string-compared to `chat_id` / `from_user`.
- `keywords`: lower-cased substring match against `m.text`.
- `all`: accepts everything (subject to `ignore_bots`).
-- **Content type filter**: Always applied first; if set and not `all`, rejects
- anything with a non-matching `content_type`.
+- **Content type filter**: Always applied first. `media` accepts any of the
+ eight downloadable kinds; any other non-`all` value is an exact
+ `content_type` match.
+- **Content type detection order matters**: `_CONTENT_PROBES` in
+ [`_service.py`](../../../server/nodes/telegram/_service.py) probes
+ most-specific-first. Telegram sets `message.document` on animation messages
+ as well (an animation *is* a document carrying an extra `animation` field),
+ so probing `document` first classified every GIF as a document and discarded
+ its animation metadata. `animation` and `video_note` are therefore probed
+ ahead of `document` and `video`.
+- **Detail extraction never drops the message**: a malformed or partial
+ provider payload is caught per-message, logged at WARNING, and the event is
+ still delivered without its detail block.
- **`ignore_bots`**: Applied last; silently skipped when `sender_filter == 'self'`.
- **Legacy fallback**: If `sender_filter` is unset the filter builder reconstructs
it from `chat_id`/`from_user`/`keywords`/`chatTypeFilter` so old workflows keep
@@ -152,6 +215,21 @@ flowchart TD
- **No timeout**: The node waits indefinitely. The only exit routes are an
event match, an explicit `cancel_event_wait` WebSocket call, or the server
restarting.
+- **GIFs changed category**: they now arrive as `content_type: "animation"`
+ rather than `"document"`. A workflow filtering on `document` to catch GIFs
+ stops matching — switch it to `animation`, or to `media` for any attachment.
+- **`text` keeps its caption fallback**: it remains `msg.text or msg.caption`
+ so workflows reading `text` on a photo message are unaffected. The new
+ `caption` field is additive, never a replacement.
+- **The op body does not run in a deployed workflow.** `event_framework_enabled`
+ defaults to `True` and `telegramReceive` is canary-registered, so the
+ controller marks the trigger `_pre_executed` with `event.data` as its output.
+ Any per-node behaviour added to the operation body would work when you press
+ Run and silently do nothing once deployed — which is why fetching media is a
+ separate node rather than a flag on this one.
+- **Media is metadata only**: `media.file_id` identifies the file but the bytes
+ are never fetched here. `file_id` values are also bot-scoped — one bot cannot
+ use another's.
## Related
diff --git a/docs-internal/node-logic-flows/telegram_social/telegramSend.md b/docs-internal/node-logic-flows/telegram_social/telegramSend.md
index dbb16314..9bed813f 100644
--- a/docs-internal/node-logic-flows/telegram_social/telegramSend.md
+++ b/docs-internal/node-logic-flows/telegram_social/telegramSend.md
@@ -3,8 +3,8 @@
| Field | Value |
|------|-------|
| **Category** | social (workflow-only) |
-| **Backend handler** | [`server/nodes/telegram/telegram_send.py`](../../../server/nodes/telegram/telegram_send.py) (`TelegramSendNode`); dispatch via `BaseNode.execute()` -> `@Operation("send")` |
-| **Tests** | [`server/tests/nodes/test_telegram_social.py`](../../../server/tests/nodes/test_telegram_social.py) |
+| **Backend handler** | [`server/nodes/telegram/telegram_send.py`](../../../server/nodes/telegram/telegram_send.py) (`TelegramSendNode`); dispatch via `BaseNode.execute()` -> `@Operation("send")` -> [`_send.py`](../../../server/nodes/telegram/_send.py) (`resolve_chat_id` + `perform_send`) |
+| **Tests** | [`server/tests/nodes/test_telegram_social.py`](../../../server/tests/nodes/test_telegram_social.py) (node level), [`test_telegram_service.py`](../../../server/tests/nodes/test_telegram_service.py) (service level: split / caption spill) |
| **Skill (if any)** | none |
| **Dual-purpose tool** | no - group is `("social",)` only; `usable_as_tool` not set (AI-tool exposure was dropped in Wave 11) |
@@ -12,9 +12,16 @@
Send text, photo, document, location, or contact messages through a connected
Telegram bot (python-telegram-bot v22.x). The node leans on the `TelegramService`
-singleton for the actual Bot API calls; the `send` operation only does recipient
-resolution, parameter validation, and envelope packaging. The operation body is
-inlined directly in the plugin file (no `handlers/telegram.py` shim).
+singleton for the actual Bot API calls; the `send` operation only resolves the
+recipient and packages the envelope.
+
+**Validation and message-type dispatch live in [`_send.py`](../../../server/nodes/telegram/_send.py)**,
+not in the operation body. The direct WebSocket command
+(`_handlers.py::handle_telegram_send`) routes through the same `perform_send`,
+so the two entry points cannot diverge. They previously carried independent
+copies and had already drifted — the socket path never forwarded `silent` or
+`reply_to_message_id`. Dispatch is a table keyed by message type, so adding a
+type is one entry plus one `Literal` member rather than a branch in two files.
## Inputs (handles)
@@ -49,18 +56,32 @@ inlined directly in the plugin file (no `handlers/telegram.py` shim).
### Output payload
-The operation returns this dict (validated against `TelegramSendOutput`, which
-declares `message_id` / `chat_id` / `sent` and `extra="allow"`):
+The operation returns this dict (validated against `TelegramSendOutput`,
+`extra="allow"`):
```ts
{
- message_id: number;
+ message_id: number; // first message when the send became several
chat_id: number;
message_type: 'text' | 'photo' | 'document' | 'location' | 'contact';
- date: string; // ISO timestamp from Telegram
+ date: string; // ISO timestamp from Telegram
+ sent: true;
+
+ // Present only when one logical send became several Telegram messages.
+ parts?: number; // text over 4096 -> chunk count
+ message_ids?: number[]; // every id in the chunk chain
+ caption_truncated?: boolean; // caption over 1024 spilled
+ follow_up_message_ids?: number[];// ids of the threaded caption remainder
}
```
+`sent` was declared on the model from the start but never populated, and
+`_serialize_result` dumps with `exclude_unset=True`, so until it was emitted
+the data picker advertised a field that never materialised. `message_type` and
+`date` were always returned but undeclared, surviving only through
+`extra="allow"`; declaring them changed nothing at runtime and made them
+visible in the picker.
+
`BaseNode.execute()` wraps it as `{ success: true, result: <payload>, execution_time, timestamp, node_id, node_type }`.
## Logic Flow
@@ -77,30 +98,19 @@ flowchart TD
D3 -- missing --> Efail
C -- user/group --> E{chat_id truthy?}
E -- no --> Efail
- E -- yes --> F[Read message_type / parse_mode / silent / reply_to]
- F --> G{message_type}
- G -- text --> T{text set?}
- T -- no --> Efail
- T -- yes --> Tsend[service.send_message]
- G -- photo --> P{media_url set?}
- P -- no --> Efail
- P -- yes --> Psend[service.send_photo]
- G -- document --> Doc{media_url set?}
- Doc -- no --> Efail
- Doc -- yes --> Dsend[service.send_document]
- G -- location --> L{lat and lng<br/>not None?}
- L -- no --> Efail
- L -- yes --> Lsend[service.send_location]
- G -- contact --> Ct{phone + first_name?}
- Ct -- no --> Efail
- Ct -- yes --> Ctsend[service.send_contact]
- G -- other --> Efail
+ E -- yes --> F[_send.perform_send<br/>table lookup on message_type]
+ F --> G{known type?}
+ G -- no --> Efail
+ G -- yes --> H[Per-type validation<br/>NodeUserError when unmet]
+ H --> I{captioned media?}
+ I -- no --> Tsend[service.send_message / location / contact]
+ I -- yes --> Msend[service.send_photo / send_document<br/>-> _send_captioned_media]
+ Msend --> J{caption over 1024<br/>UTF-16 units?}
+ J -- no --> Ok
+ J -- yes --> K[Truncate at boundary<br/>send remainder as threaded reply]
+ K --> Ok
Tsend --> Ok
- Psend --> Ok
- Dsend --> Ok
- Lsend --> Ok
- Ctsend --> Ok
- Ok[Return success=true<br/>with message_id, chat_id, message_type, date]
+ Ok[Return success=true<br/>message_id, chat_id, message_type, date, sent]
```
## Decision Logic
@@ -118,9 +128,20 @@ flowchart TD
`Auto` (GFM -> Telegram HTML via `markdown_formatter.to_telegram_html`) plus the
`BadRequest "can't parse entities"` fallback that retries with `parse_mode=None`
and the original unescaped text.
-- **Message type dispatch**: Uses an `if/elif/else` chain on `message_type`. An
- unknown value falls into the `else` and raises
- `RuntimeError("Unsupported message type: <x>")`.
+- **Message type dispatch**: `_send.perform_send` looks the type up in a
+ module-level table. An unknown value raises
+ `NodeUserError("Unsupported message type: <x>")`. Per-type validation
+ (`text` present, `media_url` present, both coordinates set, phone plus first
+ name) also raises `NodeUserError`, so the operator log gets one WARN line
+ with no traceback — these are user-correctable inputs, not server bugs.
+- **Caption spill**: Telegram caps captions at 1024 units and rejects the whole
+ send past that. `_send_captioned_media` truncates at the cap and sends the
+ remainder as a reply threaded under the media message, reusing the chunking
+ `send_message` already performs. The split runs on the **raw** caption before
+ `_resolve_body` converts markdown to HTML — splitting after conversion could
+ separate a `<b>` from its closing tag, which Telegram rejects with
+ "can't find end of the entity". Telegram measures the cap against
+ entity-parsed text, so truncating raw markdown is conservative.
- **Reply-to coercion**: `reply_to_message_id` is cast via `int(...)` only when
truthy. A non-numeric string here raises `ValueError`, which `BaseNode.execute()`
catches and surfaces as an error envelope.
@@ -157,6 +178,13 @@ flowchart TD
sees the downstream "Bot owner not detected" error.
- **Silent ValueError on `reply_to_message_id`**: A non-numeric value raises
`ValueError`, surfaced by `BaseNode.execute()` as the error message.
+- **Long captions arrive as two messages**: A caption over 1024 units produces
+ the media message plus one or more threaded follow-ups. The follow-up carries
+ `disable_notification=True` so a single logical send still pings once.
+ `caption_truncated` and `follow_up_message_ids` report it.
+- **Length is counted in UTF-16 units, not characters**: an emoji costs 2. A
+ 1024-character caption of emoji is 2048 units and will spill. This matches
+ how the Bot API measures its own limits; `len()` under-counts.
- **`recipient_type` is a `Literal["self","user","group"]`**: Pydantic rejects
any other value at param validation. For `user`/`group` an empty `chat_id`
raises `RuntimeError("chat_id is required")`.