| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195 |
- """Inbound message event types shared by every gateway platform adapter.
- A leaf module: adapters, helpers and the runner import it, so it must not import from
- gateway.platforms.*.
- """
- import re
- import unicodedata
- from dataclasses import dataclass, field
- from datetime import datetime
- from enum import Enum
- from typing import Any, Dict, List, Optional
- from gateway.session import SessionSource
- # Desktop attachment reference tags prepended by buildContextText before the
- # user's visible text (e.g. "@image:/tmp/foo.png\n\n/moa ask something").
- # Strip these when detecting slash commands so a media-ref prefix does not hide
- # a slash token from MessageEvent.is_command() / get_command().
- # The pattern matches to end-of-line (not just whitespace-bounded) to handle
- # Windows paths that may contain spaces (e.g. "C:\Users\John Doe\image.png").
- _ATTACHMENT_REF_RE = re.compile(r"^(?:@(?:image|file|url):[^\n]+\n?)+", re.IGNORECASE)
- _MAX_FILENAME_CHARS = 255
- def clean_attachment_filename(name: object) -> str:
- """An untrusted attachment filename reduced to a display-safe basename; ``""`` when unusable.
- Directory parts (either separator), control and format characters (CR/LF, NUL, bidi
- overrides) are dropped and the length is capped with the extension kept. Never a storage
- path: callers keep their own random cache names."""
- if not isinstance(name, str):
- return ""
- base = name.replace("\\", "/").rsplit("/", 1)[-1]
- base = "".join(ch for ch in base if unicodedata.category(ch) not in {"Cc", "Cf"}).strip()
- if base in {"", ".", ".."}:
- return ""
- if len(base) > _MAX_FILENAME_CHARS:
- stem, dot, ext = base.rpartition(".")
- keep = f"{dot}{ext}" if stem and len(ext) <= 16 else ""
- base = base[: _MAX_FILENAME_CHARS - len(keep)] + keep
- return base
- class MessageType(Enum):
- """Types of incoming messages."""
- TEXT = "text"
- LOCATION = "location"
- PHOTO = "photo"
- VIDEO = "video"
- AUDIO = "audio"
- VOICE = "voice"
- DOCUMENT = "document"
- STICKER = "sticker"
- COMMAND = "command" # /command style
- class ProcessingOutcome(Enum):
- """Result classification for message-processing lifecycle hooks."""
- SUCCESS = "success"
- FAILURE = "failure"
- CANCELLED = "cancelled"
- @dataclass
- class MessageEvent:
- """Incoming message from a platform — the normalized shape all adapters produce."""
- text: str
- message_type: MessageType = MessageType.TEXT
- # Author, mirrored from ``source`` for per-message prompt builders; None for non-IM sources.
- user_id: Optional[str] = None
- user_name: Optional[str] = None
- # None only in isolated unit tests; production always sets it. Typing it Optional
- # exposes ~60 unguarded ``.source.<attr>`` reads, so that is a separate change.
- source: SessionSource = None
- raw_message: Any = None
- message_id: Optional[str] = None
- # Delivery-ledger identity for the final send, when it differs from ``message_id``. A queued
- # (/queue) chain answers the LAST message of the chain, so its final send has to be ledgered
- # under that message's id. Keyed on the opening event's id instead, two chained turns carrying
- # the same text collide on one obligation id and the earlier turn's row is overwritten (a
- # refused first reply then reads as delivered). Reply routing is unaffected: the reply anchor
- # still comes from this event.
- ledger_message_id: Optional[str] = None
- # Reply anchor for the final send when the answer is to a DIFFERENT message than the one that
- # opened the turn: a successful busy redirect turns the running turn onto the redirecting
- # message, so its reply must quote that message (#115001). ``_reply_anchor_for_event``
- # honours this over ``message_id``; None = derive from the event as usual.
- reply_anchor_override: Optional[str] = None
- # Platform update id (Telegram ``update_id``): ``/restart`` records it so the new gateway
- # advances past it even if PTB's shutdown ACK times out.
- platform_update_id: Optional[int] = None
- # Media attachments: local file paths (for vision tool access)
- media_urls: list[str] = field(default_factory=list)
- media_types: list[str] = field(default_factory=list)
- # Per-attachment text-inlining contract; None = legacy "text/* already inlined into ``text``".
- media_text_inlined: list[Optional[bool]] = field(default_factory=list)
- reply_to_message_id: Optional[str] = None
- reply_to_text: Optional[str] = None # Text of the replied-to message (for context injection)
- reply_to_author_id: Optional[str] = None
- reply_to_author_name: Optional[str] = None
- reply_to_is_own_message: bool = False # True when the user replied to this bot/assistant's message
- # Structured interactive-prompt reply (relay only): {prompt_id, option_id, label?,
- # prompt_message_id?}; routed to the approval/slash-confirm/clarify resolvers BEFORE dispatch.
- prompt_response: Optional[dict[str, Any]] = None
- # Auto-loaded skill(s) for topic/channel bindings; a single name or ordered list.
- auto_skill: Optional[str | list[str]] = None
- # Per-channel ephemeral system prompt; applied at API call time, never persisted to transcript.
- channel_prompt: Optional[str] = None
- # History-backfilled channel context (missed under require_mention); kept out of ``text`` so
- # run.py's sender-prefix logic sees only the trigger message.
- channel_context: Optional[str] = None
- # Set for synthetic events (e.g. background-process notifications) that must bypass user authorization.
- internal: bool = False
- # Free-form per-event metadata (e.g. ``whatsapp_from_owner=True``); plugins must ``.get()``.
- metadata: dict[str, Any] = field(default_factory=dict)
- timestamp: datetime = field(default_factory=datetime.now)
- # May this event resolve gateway commands / control prompts? Proactive plugin events set False
- # so untrusted payload text stays conversational. New fields append after it (positional compat).
- allow_gateway_control: bool = True
- # Was this message addressed to this bot? False lets a bare silence marker stand (the adapter
- # knows the message was meant for someone else); None means unknown and keeps the visible
- # fallback, like True.
- reply_expected: Optional[bool] = None
- # Set for synthetic turns that carry no channel inputs of their own (goal continuation,
- # heartbeat due-prompts, /goal resume) so the turn reuses the session's pinned channel
- # prompt/parent instead of overwriting it with this event's own None (#126109). Independent
- # of ``internal``: these events still go through user authorization. Appended after
- # ``reply_expected`` for positional compat (see the field-order rule above).
- inherit_channel_pin: bool = False
- # Identity of one edit of a message (Telegram: its ``update_id``). An edit re-sends its message's own
- # ``message_id`` with new text, so native admission keys it apart from the original send.
- # Appended for positional compat (see the field-order rule above).
- edit_revision: Optional[str] = None
- # Original filename per attachment, parallel to ``media_urls`` like ``media_types`` ("" =
- # unknown). For adapters whose ``media_urls`` are random cache names (relay); the name is
- # display data only, never a path. Appended for positional compat.
- media_filenames: list[str] = field(default_factory=list)
- # Process-local admission receipt, never routing metadata or execution acknowledgement.
- _gateway_accepted: bool = field(default=False, init=False, repr=False, compare=False)
- # Set when ``admit_internal_event`` hands its producer a receipt before any drain began. The
- # producer will not retry, so a restart drain runs this event instead of refusing it at the
- # drain gate or discarding it as a queued follow-up (#138123).
- _admitted_before_drain: bool = field(default=False, init=False, repr=False, compare=False)
- # Run-owned final presentation snapshot; never deserialized from ingress metadata.
- _notification_reply_muted: Optional[bool] = field(default=None, init=False, repr=False, compare=False)
- def absorb_reply_expected(self, other: "MessageEvent") -> None:
- """One turn now answers *other* too: an addressed message wins, then an unknown one."""
- if self.reply_expected is not True and other.reply_expected is not False:
- self.reply_expected = other.reply_expected
- def extend_media(self, other: "MessageEvent") -> None:
- """Append *other*'s attachments (urls, types and original names) to this event's. Names are
- padded with ``""`` on either side so each stays on its own attachment; events without names
- (native adapters keep the name in the cache path) leave ``media_filenames`` untouched."""
- if self.media_filenames or other.media_filenames:
- def pad(msg: "MessageEvent") -> list[str]:
- return (list(msg.media_filenames) + [""] * len(msg.media_urls))[: len(msg.media_urls)]
- self.media_filenames = pad(self) + pad(other)
- self.media_urls.extend(other.media_urls)
- self.media_types.extend(other.media_types)
- def _command_text(self) -> str:
- """Return the message text with leading Desktop attachment refs stripped.
- Desktop's buildContextText prepends ``@image:<path>``, ``@file:<path>``,
- or ``@url:<url>`` tags before the user's visible text. Stripping these
- lets is_command / get_command / get_command_args work correctly even
- when the payload is prefixed with one or more media refs.
- """
- return _ATTACHMENT_REF_RE.sub("", (self.text or "").lstrip()).lstrip()
- def is_command(self) -> bool:
- """Check if this is a command message (e.g., /new, /reset)."""
- return self.allow_gateway_control and self._command_text().startswith("/")
- def get_command(self) -> Optional[str]:
- """Extract command name if this is a command message."""
- if not self.is_command():
- return None
- raw = self._command_text().split(maxsplit=1)[0][1:].lower().split("@", 1)[0]
- # Reject file paths: valid command names never contain /
- return None if "/" in raw else raw
- def get_command_args(self) -> str:
- """Get the arguments after a command."""
- if not self.is_command():
- return self.text
- parts = self._command_text().lstrip().split(maxsplit=1)
- args = parts[1] if len(parts) > 1 else ""
- # iOS auto-corrects -- to — (em dash) and - to – (en dash)
- return args.replace("\u2014\u2014", "--").replace("\u2014", "--").replace("\u2013", "-")
|