Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs: bring the telegram cards and CLAUDE.md in line with the code
trohitg5a587b4410e1
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mdindex 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.mdindex 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 triggerevent. `TelegramReceiveNode` subclasses `TriggerNode`; its `execute` overridefirst 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 loopinside `_on_message_received`. In controlled deployment mode, the triggerdefinition and queued CloudEvents live in `WorkflowControlWorkflow`; thecontroller 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` whenfrom_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 timestampreply_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 reconstructsit 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 anevent match, an explicit `cancel_event_wait` WebSocket call, or the serverrestarting.+- **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.## Relateddiff --git a/docs-internal/node-logic-flows/telegram_social/telegramSend.md b/docs-internal/node-logic-flows/telegram_social/telegramSend.mdindex 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 connectedTelegram 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 severalchat_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 TDD3 -- missing --> EfailC -- 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 --> OkTsend --> 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 whentruthy. A non-numeric string here raises `ValueError`, which `BaseNode.execute()`catches and surfaces as an error envelope.@@ -157,6 +178,13 @@ flowchart TDsees 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 rejectsany other value at param validation. For `user`/`group` an empty `chat_id`raises `RuntimeError("chat_id is required")`.