base.py 270 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833
  1. """Base platform adapter interface; every platform adapter inherits from BasePlatformAdapter."""
  2. import asyncio
  3. import contextlib
  4. import inspect
  5. import ipaddress
  6. import logging
  7. import math
  8. import os
  9. import random
  10. import re
  11. import socket as _socket
  12. import subprocess
  13. import sys
  14. import tempfile
  15. import threading
  16. import time
  17. import uuid
  18. import weakref
  19. from abc import ABC, abstractmethod
  20. from hermes_dir_acl import make_user_dir, unusable_dir_remedy
  21. from gateway.platforms.base_log_safety import safe_url_for_log
  22. from utils import normalize_proxy_url, unlink_files_older_than
  23. from agent.i18n import t
  24. from agent.retry_utils import jittered_backoff
  25. from agent.proxy_bypass import first_proxy_env_value, should_bypass_proxy as _should_bypass_proxy
  26. logger = logging.getLogger(__name__)
  27. def _consume_detached_handler_exception(task: asyncio.Task) -> None:
  28. """Done-callback for a detached fatal-error handler task (carrier cancelled in
  29. ``_notify_fatal_error``): retrieve its exception so asyncio never logs "never retrieved"."""
  30. if task.cancelled():
  31. return
  32. exc = task.exception()
  33. if exc is not None:
  34. logger.error("Detached fatal-error handler task failed: %s", exc, exc_info=exc)
  35. # Audio exts for native audio delivery; Telegram's narrower sets stay separate (.m2a is audio to
  36. # Hermes but not to sendAudio).
  37. _AUDIO_MIME_TYPES = {
  38. ".ogg": "audio/ogg", ".opus": "audio/opus", ".mp3": "audio/mpeg", ".m2a": "audio/mpeg",
  39. ".wav": "audio/wav", ".m4a": "audio/m4a", ".flac": "audio/flac"}
  40. _AUDIO_EXTS = frozenset(_AUDIO_MIME_TYPES)
  41. # Outbound dispatch partition for MEDIA/local files (image batch vs send_video).
  42. _VIDEO_EXTS = frozenset({".mp4", ".mov", ".avi", ".mkv", ".webm", ".3gp"})
  43. _IMAGE_EXTS = frozenset({".jpg", ".jpeg", ".png", ".webp", ".gif"})
  44. # Telegram sendAudio accepts only MP3 / M4A; others go via sendVoice (Opus/OGG) or as a document.
  45. _TELEGRAM_AUDIO_ATTACHMENT_EXTS = frozenset({'.mp3', '.m4a'})
  46. _TELEGRAM_VOICE_EXTS = frozenset({'.ogg', '.opus'})
  47. def transcode_to_ogg_opus(path: str, *, bitrate: str = "32k", timeout: int = 60,
  48. output_path: str | None = None) -> str | None:
  49. """Best-effort ffmpeg transcode to Ogg/Opus (voip-tuned) for native voice bubbles: the written
  50. ``.ogg`` path (a NEW temp file unless ``output_path`` is given; caller cleans up), or None when
  51. ffmpeg is missing/fails. ``output_path`` may equal ``path`` (in-place container repair) — the
  52. encode goes through a sidecar so a failed run never truncates the source. Blocking (to_thread)."""
  53. import shutil as _shutil
  54. ffmpeg = _shutil.which("ffmpeg")
  55. if not ffmpeg:
  56. return None
  57. if output_path is None:
  58. fd, ogg_path = tempfile.mkstemp(prefix="voice_transcode_", suffix=".ogg")
  59. os.close(fd)
  60. else:
  61. ogg_path = output_path
  62. in_place = os.path.abspath(str(path)) == os.path.abspath(ogg_path)
  63. work_path = ogg_path + ".tmp.ogg" if in_place else ogg_path
  64. try:
  65. result = subprocess.run(
  66. [ffmpeg, "-v", "error", "-y", "-i", str(path),
  67. "-acodec", "libopus", "-ac", "1", "-b:a", bitrate, "-vbr", "on",
  68. "-application", "voip", "-compression_level", "10", "-f", "ogg", work_path],
  69. capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL, check=False)
  70. if result.returncode == 0 and os.path.getsize(work_path) > 0:
  71. if in_place:
  72. os.replace(work_path, ogg_path)
  73. return ogg_path
  74. logger.warning("ffmpeg Ogg/Opus transcode of %s failed (returncode=%s): %s", path, result.returncode,
  75. (result.stderr or b"").decode("utf-8", errors="replace")[:500])
  76. except Exception:
  77. logger.warning("voice transcode to Ogg/Opus failed for %s", path, exc_info=True)
  78. with contextlib.suppress(OSError):
  79. os.unlink(work_path)
  80. return None
  81. _POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS = 30.0
  82. # History dedup is best-effort: stay well below the Discord heartbeat watchdog and fail open.
  83. _HISTORY_MEDIA_LOOKUP_TIMEOUT_SECONDS = 5.0
  84. # Timed-out reads can't be cancelled mid-SQLite: cap the isolated threads so wedged lookups
  85. # can't exhaust the shared executor.
  86. _HISTORY_MEDIA_LOOKUP_MAX_WORKERS = 2
  87. _HISTORY_MEDIA_LOOKUP_ADMISSION = threading.BoundedSemaphore(_HISTORY_MEDIA_LOOKUP_MAX_WORKERS)
  88. def _platform_name(platform) -> str:
  89. """Normalize a Platform enum / raw string into a lowercase name."""
  90. value = getattr(platform, "value", platform)
  91. return str(value or "").lower()
  92. def _or_default(thunk, default, exc=(TypeError, ValueError)):
  93. """``thunk()``, or ``default`` when it raises one of ``exc`` (numeric config/env coercion)."""
  94. try:
  95. return thunk()
  96. except exc:
  97. return default
  98. DEFAULT_BUSY_TEXT_DEBOUNCE_SECONDS = 0.35
  99. DEFAULT_BUSY_TEXT_HARD_CAP_SECONDS = 1.0
  100. def _thread_metadata_for_source(source, reply_to_message_id: str | None = None) -> dict | None:
  101. """Platform-aware thread metadata for adapter sends. Telegram DM topics route with
  102. ``message_thread_id`` + a reply anchor; anchorless synthetic/resumed sends fall back to
  103. ``direct_messages_topic_id`` when supported."""
  104. thread_id = getattr(source, "thread_id", None)
  105. platform = _platform_name(getattr(source, "platform", None))
  106. metadata = {"thread_id": thread_id} if thread_id is not None else {}
  107. # Slack workspace identity is routing state: carry it so a multi-workspace Socket Mode
  108. # gateway never falls back to its primary WebClient.
  109. scope_id = getattr(source, "scope_id", None) if platform == "slack" else None
  110. if scope_id:
  111. metadata["slack_team_id"] = str(scope_id)
  112. if not metadata:
  113. return None
  114. if platform == "telegram" and getattr(source, "chat_type", None) == "dm":
  115. metadata["telegram_dm_topic_reply_fallback"] = True
  116. if str(thread_id) not in {"", "1"}:
  117. metadata["direct_messages_topic_id"] = str(thread_id)
  118. anchor = reply_to_message_id or getattr(source, "message_id", None)
  119. if anchor is not None:
  120. metadata["telegram_reply_to_message_id"] = str(anchor)
  121. # Routed profile (multiplex / profile_routes): outbound prune paths must not assume the
  122. # adapter's static profile stamp.
  123. profile = str(getattr(source, "profile", None) or "").strip()
  124. if profile:
  125. metadata["hermes_profile"] = profile
  126. return metadata
  127. def _thread_metadata_for_event(event) -> dict | None:
  128. """``_thread_metadata_for_source`` for an event, anchored on its reply id."""
  129. return _thread_metadata_for_source(event.source, _reply_anchor_for_event(event))
  130. def _mark_notify_metadata(metadata: dict | None) -> dict:
  131. """Clone metadata and mark a user-visible reply as notify-worthy."""
  132. notify_metadata = dict(metadata) if metadata else {}
  133. notify_metadata["notify"] = True
  134. return notify_metadata
  135. def _reply_anchor_for_event(event) -> str | None:
  136. """Return reply_to id for platforms that need reply semantics."""
  137. override = getattr(event, "reply_anchor_override", None)
  138. if override is not None:
  139. return override # the turn was redirected onto another message (#115001)
  140. source = getattr(event, "source", None)
  141. platform = _platform_name(getattr(source, "platform", None))
  142. thread_id = getattr(source, "thread_id", None)
  143. raw_message = getattr(event, "raw_message", None)
  144. if getattr(event, "internal", False) or (platform == "slack" and isinstance(raw_message, dict)
  145. and raw_message.get("_hermes_no_thread_response")):
  146. # A synthetic wake's message_id is its producer identity, not a platform id (Telegram int()s
  147. # it; #52694). A Slack reaction handoff is a new top-level message, not a thread reply.
  148. return None
  149. if platform == "telegram" and thread_id:
  150. # Forum topics route by topic metadata (no reply); DM-topic lanes reply to the triggering
  151. # message — replying to the topic seed/anchor can render outside the active lane.
  152. if getattr(source, "chat_type", None) != "dm":
  153. return None
  154. return getattr(event, "message_id", None) or getattr(event, "reply_to_message_id", None)
  155. if platform == "feishu" and thread_id and getattr(event, "reply_to_message_id", None):
  156. return getattr(event, "reply_to_message_id", None)
  157. return getattr(event, "message_id", None)
  158. _MEDIA_KIND_KEYS = frozenset({"audio", "video", "file", "image"})
  159. def _media_failure_text(kind: str, file_name: str | None = None) -> str:
  160. """User-facing "couldn't deliver" notice; ``file_name`` is the only name ever shown."""
  161. kind_label = t(f"gateway.notify.media_kind.{kind}") if kind in _MEDIA_KIND_KEYS else kind
  162. if file_name:
  163. return t("gateway.notify.media_delivery_failed_with_name", kind=kind_label, file_name=file_name)
  164. return t("gateway.notify.media_delivery_failed", kind=kind_label)
  165. def should_send_media_as_audio(platform, ext: str, is_voice: bool = False) -> bool:
  166. """True when a media file should use the platform's audio sender. Telegram: explicit
  167. ``is_voice`` ([[audio_as_voice]]) routes ANY format to the voice sender (adapter transcodes
  168. non-Opus); otherwise only sendAudio's MP3/M4A qualify — a plain Opus/OGG attachment is never
  169. turned into a voice bubble, everything else → document. Other platforms: any audio ext."""
  170. normalized_ext = (ext or "").lower()
  171. if normalized_ext not in _AUDIO_EXTS:
  172. return False
  173. if _platform_name(platform) != "telegram":
  174. return True
  175. return is_voice or normalized_ext in _TELEGRAM_AUDIO_ATTACHMENT_EXTS
  176. def build_auto_tts_output_path(platform) -> str:
  177. """Unique temp output path for gateway auto-TTS: ``.ogg`` for ``OPUS_VOICE_PLATFORMS``
  178. (the tool's ``_repair_ogg_container`` then guarantees real Opus bytes), else ``.mp3``.
  179. Platform-awareness lives HERE because ``_clear_session_env`` wipes the TTS tool's
  180. ``HERMES_SESSION_PLATFORM`` contextvar before the post-handler auto-TTS block runs.
  181. Platforms whose native voice bubbles require Ogg/Opus (``tools.tts_tool.OPUS_VOICE_PLATFORMS`` — the
  182. single source of truth) get an explicit ``.ogg`` path; the tool's central container repair
  183. (``_repair_ogg_container``) then guarantees real Ogg/Opus bytes for every provider, including MP3-only
  184. backends like Edge TTS. Everything else keeps the MP3 default. See #36685, #57049.
  185. """
  186. from tools.tts_tool import OPUS_VOICE_PLATFORMS
  187. ext = "ogg" if _platform_name(platform) in OPUS_VOICE_PLATFORMS else "mp3"
  188. audio_path = os.path.join(
  189. tempfile.gettempdir(), "hermes_voice", f"tts_reply_{uuid.uuid4().hex[:12]}.{ext}")
  190. os.makedirs(os.path.dirname(audio_path), exist_ok=True)
  191. return audio_path
  192. def utf16_len(s: str) -> int:
  193. """UTF-16 code units in *s* — Telegram's 4 096 limit counts those, so astral chars
  194. (emoji, CJK Ext B) cost **two** units although Python's ``len()`` counts one.
  195. Ported from nearai/ironclaw#2304 which discovered the same discrepancy in Rust's ``chars().count()``.
  196. """
  197. return len(s.encode("utf-16-le")) // 2
  198. def _custom_unit_to_cp(s: str, budget: int, len_fn) -> int:
  199. """Largest codepoint offset *n* with ``len_fn(s[:n]) <= budget`` (binary search)."""
  200. if len_fn(s) <= budget:
  201. return len(s)
  202. lo, hi = 0, len(s)
  203. while lo < hi:
  204. mid = (lo + hi + 1) // 2
  205. if len_fn(s[:mid]) <= budget:
  206. lo = mid
  207. else:
  208. hi = mid - 1
  209. return lo
  210. def fit_prefix(text: str, budget: int, measure, suffix: str = "...") -> str:
  211. """``text``, or its longest prefix within ``budget`` ``measure`` units plus ``suffix`` (outside it)."""
  212. n = _custom_unit_to_cp(text, budget, measure)
  213. return text if n == len(text) else text[:n] + suffix
  214. def _prefix_within_utf16_limit(s: str, limit: int) -> str:
  215. """Longest prefix of *s* with UTF-16 length ≤ *limit*; never splits a surrogate pair."""
  216. return s[:_custom_unit_to_cp(s, limit, utf16_len)]
  217. def is_network_accessible(host: str) -> bool:
  218. """True if *host* would expose the server beyond loopback (incl. IPv4-mapped
  219. ::ffff:127.0.0.1); hostnames are resolved and DNS failure fails closed (True)."""
  220. with contextlib.suppress(ValueError): # ValueError: hostname — resolve below
  221. addr = ipaddress.ip_address(host)
  222. # ::ffff:127.0.0.1 reports is_loopback=False; check the mapped IPv4 explicitly.
  223. mapped = getattr(addr, "ipv4_mapped", None)
  224. return not (addr.is_loopback or (mapped and mapped.is_loopback))
  225. try:
  226. resolved = _socket.getaddrinfo(host, None, _socket.AF_UNSPEC, _socket.SOCK_STREAM)
  227. # Network-accessible if any resolved address is non-loopback.
  228. return any(not ipaddress.ip_address(sockaddr[0]).is_loopback for *_, sockaddr in resolved)
  229. except (_socket.gaierror, OSError):
  230. return True
  231. # ``scutil --proxy`` is a fork+exec (~11 ms measured) and resolve_proxy_url runs it on the SEND path —
  232. # per chunk of an outbound message and per media attachment, not once per adapter. The answer is an
  233. # OS-level network setting that changes when someone edits Network Settings or joins a VPN, so it is
  234. # cached briefly rather than per call. The TTL is the staleness a proxy change can suffer; a send that
  235. # goes out on a stale answer fails and is retried, which is the same outcome as any transient proxy error.
  236. # No lock: a race costs one extra fork and both answers are equally current.
  237. _MACOS_PROXY_TTL_SECONDS = 60.0
  238. _macos_proxy_cache: tuple[float, str | None] | None = None
  239. def _detect_macos_system_proxy() -> str | None:
  240. """Read the macOS system HTTP(S) proxy via ``scutil --proxy``: ``http://host:port``
  241. when an HTTP(S) proxy is enabled, else None (non-macOS or any subprocess error).
  242. Memoised for ``_MACOS_PROXY_TTL_SECONDS``; call :func:`reset_macos_proxy_cache` to force a re-read.
  243. """
  244. global _macos_proxy_cache
  245. if sys.platform != "darwin":
  246. return None
  247. cached = _macos_proxy_cache
  248. now = time.monotonic()
  249. if cached is not None and (now - cached[0]) < _MACOS_PROXY_TTL_SECONDS:
  250. return cached[1]
  251. try:
  252. out = subprocess.check_output(["scutil", "--proxy"], timeout=3, text=True, encoding='utf-8',
  253. errors='replace', stderr=subprocess.DEVNULL)
  254. except Exception:
  255. # Cache the failure too: a broken/slow scutil must not re-fork on every chunk.
  256. _macos_proxy_cache = (now, None)
  257. return None
  258. props = {
  259. key.strip(): val.strip()
  260. for key, sep, val in (line.strip().partition(" : ") for line in out.splitlines()) if sep}
  261. # Prefer HTTPS, fall back to HTTP
  262. resolved = None
  263. for enable_key, host_key, port_key in (
  264. ("HTTPSEnable", "HTTPSProxy", "HTTPSPort"), ("HTTPEnable", "HTTPProxy", "HTTPPort")):
  265. if props.get(enable_key) == "1" and props.get(host_key) and props.get(port_key):
  266. resolved = f"http://{props[host_key]}:{props[port_key]}"
  267. break
  268. _macos_proxy_cache = (now, resolved)
  269. return resolved
  270. def reset_macos_proxy_cache() -> None:
  271. """Drop the memoised ``scutil --proxy`` answer so the next call re-reads it."""
  272. global _macos_proxy_cache
  273. _macos_proxy_cache = None
  274. def should_bypass_proxy(target_hosts: str | list[str] | tuple[str, ...] | set[str] | None) -> bool:
  275. """True when NO_PROXY/no_proxy matches at least one target host (exact hosts, domain /
  276. wildcard suffixes, IP literals, CIDR ranges, optional host:port entries, ``*``)."""
  277. return _should_bypass_proxy(target_hosts)
  278. def resolve_proxy_url(
  279. platform_env_var: str | None = None, *,
  280. target_hosts: str | list[str] | tuple[str, ...] | set[str] | None = None,
  281. configured: str | None = None) -> str | None:
  282. """Proxy URL: *platform_env_var* (e.g. ``DISCORD_PROXY``) first, then the adapter's own YAML
  283. value *configured* (``telegram.proxy_url``), then HTTPS_PROXY / HTTP_PROXY / ALL_PROXY (any
  284. case), then the macOS system proxy — the latter two only when ``gateway.trust_env`` is true.
  285. None when nothing is found or NO_PROXY matches a target.
  286. *platform_env_var* is a per-adapter, per-profile-configurable setting (each proxy URL can
  287. embed credentials, e.g. ``http://user:pass@host``) so it is read scope-aware: under a
  288. secondary multiplex profile it comes from that profile's own ``.env``, not the shared
  289. process env another profile's ``TELEGRAM_PROXY``/``DISCORD_PROXY``/etc. may hold; the YAML
  290. value is the same profile's, so a secondary keeps its configured route without any env
  291. bridge (#108440). The generic ``HTTPS_PROXY``/``HTTP_PROXY``/``ALL_PROXY`` fallback stays a raw
  292. process-env read — those are OS/system-level network settings, not a per-profile Hermes concept."""
  293. from gateway.platforms._shared import get_scoped_secret as _get_scoped_proxy_var
  294. value = (_get_scoped_proxy_var(platform_env_var, "") or "").strip() if platform_env_var else ""
  295. if not value:
  296. value = str(configured or "").strip()
  297. if not value:
  298. if not gateway_trust_env(): # only the explicit per-platform var is honored
  299. return None
  300. value = first_proxy_env_value()
  301. proxy = normalize_proxy_url(value or _detect_macos_system_proxy())
  302. return None if proxy and should_bypass_proxy(target_hosts) else proxy
  303. def _aiohttp_socks_connector(proxy_url: str):
  304. """``aiohttp_socks.ProxyConnector`` for ``proxy_url``, or None when aiohttp_socks is missing
  305. (SOCKS logs a warning; HTTP callers fall back to ``proxy=``). ``rdns=True`` forces remote DNS
  306. through the proxy — required by Shadowrocket/Clash-style SOCKS and against GFW DNS pollution."""
  307. try:
  308. from aiohttp_socks import ProxyConnector
  309. return ProxyConnector.from_url(proxy_url, rdns=True)
  310. except ImportError:
  311. if proxy_url.lower().startswith("socks"):
  312. logger.warning("aiohttp_socks not installed — SOCKS proxy %s ignored. "
  313. "Use an HTTP proxy instead.", proxy_url)
  314. return None
  315. def proxy_kwargs_for_bot(proxy_url: str | None) -> dict:
  316. """Kwargs for ``commands.Bot()`` / ``discord.Client()``: SOCKS → ``{"connector"}``,
  317. HTTP → ``{"proxy": url}``, None → ``{}``."""
  318. if not proxy_url:
  319. return {}
  320. if proxy_url.lower().startswith("socks"):
  321. connector = _aiohttp_socks_connector(proxy_url)
  322. return {"connector": connector} if connector is not None else {}
  323. return {"proxy": proxy_url}
  324. def _config_section(name: str) -> dict:
  325. """Read-only ``config.yaml`` section ``name``; ``{}`` when unreadable/missing/not a dict."""
  326. try:
  327. from hermes_cli.config import load_config_readonly as _load_config
  328. cfg = _load_config() # read-only: .get() only, never mutated
  329. except Exception:
  330. return {}
  331. section = cfg.get(name) if isinstance(cfg, dict) else None
  332. return section if isinstance(section, dict) else {}
  333. def gateway_trust_env() -> bool:
  334. """``gateway.trust_env`` from config.yaml (default True): whether gateway
  335. ``aiohttp.ClientSession``s honor HTTP(S)_PROXY / NO_PROXY / SSL_CERT_FILE. Set false
  336. when the gateway inherits a proxy env it must not use. Fail-open to default."""
  337. value = _config_section("gateway").get("trust_env", True)
  338. if isinstance(value, str):
  339. return value.strip().lower() not in {"0", "false", "no", "off"}
  340. return bool(value) if value is not None else True
  341. def proxy_kwargs_for_aiohttp(proxy_url: str | None) -> tuple[dict, dict]:
  342. """``(session_kwargs, request_kwargs)`` for a standalone ``aiohttp.ClientSession``. With
  343. aiohttp-socks every scheme uses a connector (mautrix-style libs never forward per-request
  344. ``proxy=``); without it HTTP falls back to ``({}, {"proxy": url})`` and SOCKS is ignored."""
  345. if not proxy_url:
  346. return {}, {}
  347. connector = _aiohttp_socks_connector(proxy_url)
  348. if connector is not None:
  349. return {"connector": connector}, {}
  350. return ({}, {}) if proxy_url.lower().startswith("socks") else ({}, {"proxy": proxy_url})
  351. def is_host_excluded_by_no_proxy(hostname: str, no_proxy_value: str | None = None) -> bool:
  352. """Return True when ``hostname`` matches a ``NO_PROXY`` entry (``no_proxy_value`` overrides the
  353. environment); same matcher as :func:`should_bypass_proxy`."""
  354. return _should_bypass_proxy(hostname, no_proxy_value=no_proxy_value)
  355. import dataclasses
  356. from dataclasses import dataclass
  357. from pathlib import Path
  358. from typing import TYPE_CHECKING, Dict, List, Optional, Any, Callable, Awaitable, Tuple, Union
  359. sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
  360. from gateway.config import Platform, PlatformConfig
  361. from gateway.platforms.helpers import fence_state_after, typing_metadata_for_turn
  362. from gateway.platforms.base_post_delivery import run_post_delivery_callback
  363. from gateway.platforms.base_exec_approval import (
  364. approval_timeout_seconds, ea_action_labels, ea_default_reason_text, ea_header_text,
  365. ea_reason_label_text, ea_smart_deny_line_text, format_approval_deadline_line)
  366. from gateway.platforms.base_streaming_tts import (
  367. AudioFormat, StreamingTTSHandle, streaming_tts_should_skip_whole_file, streaming_tts_turn_key)
  368. from gateway.platforms.event import MessageEvent, MessageType, ProcessingOutcome
  369. from gateway.warning_notifications import diagnostic_wake_muted
  370. from hermes_cli.observability.shared_metrics_gateway import records_delivery, stop_reply_clock
  371. from hermes_cli.home_data_layout import SECRET_CACHE_STORES
  372. from gateway.session import SessionSource, build_session_key
  373. from gateway.session_transcript import TranscriptReadError
  374. from hermes_constants import CONNECTOR_DOWNLOADS_SUBDIR, get_default_hermes_root, get_hermes_dir, get_hermes_home
  375. from agent.provider_media import GENERATED_SUBDIR, MEDIA_CACHE_MAX_AGE_HOURS
  376. if TYPE_CHECKING:
  377. from agent.display import ToolPreview
  378. GATEWAY_SECRET_CAPTURE_UNSUPPORTED_MESSAGE = (
  379. "Secure secret entry is not supported over messaging. "
  380. "Load this skill in the local CLI to be prompted, or add the key to ~/.hermes/.env manually.")
  381. # One sentence for every "you may not press/run this" refusal on every platform (slash commands,
  382. # approval buttons, pickers, prompts). ``{platform}`` is the ``Platform.value`` for the
  383. # ``hermes pairing approve`` command (hermes_cli/subcommands/pairing.py) that lets the owner fix it.
  384. # Kept under 200 chars: Telegram's answerCallbackQuery truncates longer text.
  385. UNAUTHORIZED_ACTION_NOTICE = (
  386. "This bot is private and you're not on its allowed list. If you own it, run "
  387. "`hermes pairing approve {platform} <request-id>` on the host (`hermes pairing list` shows the id).")
  388. def unauthorized_action_notice(platform: Any) -> str:
  389. """Localized ``UNAUTHORIZED_ACTION_NOTICE`` for a ``Platform`` member or its string name.
  390. Call it per refusal — never bind the result at import, or the language freezes."""
  391. name = getattr(platform, "value", platform)
  392. return t("gateway.unauthorized.action_notice", platform=str(name or "<platform>"))
  393. async def ssrf_redirect_guard(response):
  394. """Re-validate each redirect target (a public URL 302-ing to http://169.254.169.254/ would
  395. bypass the pre-flight is_safe_url()). Async because httpx awaits response event hooks."""
  396. from tools.url_safety import is_safe_url, redirect_target_from_response
  397. redirect_url = redirect_target_from_response(response)
  398. if redirect_url and not is_safe_url(redirect_url):
  399. raise ValueError(f"Blocked redirect to private/internal address: {safe_url_for_log(redirect_url)}")
  400. # Inbound images are cached locally for the vision tool (platform URLs are ephemeral).
  401. # Import-time default; tests monkeypatch it, getters re-resolve per call.
  402. IMAGE_CACHE_DIR = get_hermes_dir("cache/images", "image_cache")
  403. # Inbound media cap (``gateway.max_inbound_media_bytes``): payloads are buffered fully in memory,
  404. # so an uncapped upload (Discord Nitro: 500 MB) could OOM-kill the gateway.
  405. # Inbound image / audio / video payloads are buffered fully into process memory before being written to the
  406. # cache directory. With no cap, a single large upload (Discord Nitro allows 500 MB) — or a remote URL in an
  407. # inbound message payload pointing at an arbitrarily large file — can spike RAM and OOM-kill the gateway.
  408. # The ``cache_*_from_bytes`` helpers (the shared funnel every platform reaches eventually) and the
  409. # ``cache_*_from_url`` downloaders enforce this cap, so the protection holds regardless of which platform
  410. # adapter or code path produced the bytes. Configurable via ``gateway.max_inbound_media_bytes`` in
  411. # config.yaml. ``0`` disables the cap. Default 128 MiB — generous enough for ordinary photos/voice
  412. # notes/short clips while still bounding a hostile upload.
  413. # --------------------------------------------------------------------------- See #13145.
  414. DEFAULT_INBOUND_MEDIA_MAX_BYTES = 128 * 1024 * 1024
  415. def get_inbound_media_max_bytes() -> int:
  416. """Max inbound media bytes held in memory (``gateway.max_inbound_media_bytes``);
  417. ``0`` / negative / unparseable disables the cap; unreadable config → default."""
  418. return _or_default(lambda: int(_config_section("gateway")["max_inbound_media_bytes"]),
  419. DEFAULT_INBOUND_MEDIA_MAX_BYTES, (KeyError, TypeError, ValueError))
  420. def validate_inbound_media_size(
  421. size: int, *, media_type: str = "media", max_bytes: Optional[int] = None) -> None:
  422. """Raise ``ValueError`` if an inbound payload exceeds the cap (``max_bytes`` of ``0``
  423. disables it; pass it explicitly to resolve the limit once across an incremental read)."""
  424. limit = get_inbound_media_max_bytes() if max_bytes is None else max_bytes
  425. if limit and size > limit:
  426. raise ValueError(f"Inbound {media_type} payload is too large ({size} bytes > {limit} bytes)")
  427. async def _read_httpx_body_with_limit(response, *, media_type: str) -> bytes:
  428. """Read an httpx streaming body under the media cap: reject an oversized ``Content-Length``
  429. early, then re-check the running total per chunk (a lying/absent header can't smuggle more)."""
  430. max_bytes = get_inbound_media_max_bytes()
  431. content_length = response.headers.get("content-length")
  432. if content_length:
  433. try:
  434. declared_size = int(content_length)
  435. except ValueError:
  436. logger.debug("Ignoring invalid Content-Length for inbound %s: %r", media_type, content_length)
  437. else:
  438. validate_inbound_media_size(declared_size, media_type=media_type, max_bytes=max_bytes)
  439. chunks: list[bytes] = []
  440. total = 0
  441. async for chunk in response.aiter_bytes():
  442. total += len(chunk)
  443. validate_inbound_media_size(total, media_type=media_type, max_bytes=max_bytes)
  444. chunks.append(chunk)
  445. return b"".join(chunks)
  446. def _cache_dir_accessors(kind: str, constant_name: str, new_subpath: str, old_name: str):
  447. """``(get_<kind>_cache_dir, cleanup_<kind>_cache)`` pair. The getter resolves fresh via
  448. get_hermes_dir (active profile) unless a test monkeypatched the module constant away from
  449. its import-time default, and creates the directory; ``cleanup(max_age_hours=MEDIA_CACHE_MAX_AGE_HOURS)`` deletes
  450. older files and returns the count."""
  451. def get_dir() -> Path:
  452. d = get_hermes_dir(new_subpath, old_name)
  453. current = globals().get(constant_name)
  454. default = _CACHE_DIR_IMPORT_DEFAULTS.get(constant_name)
  455. if current is not None and default is not None and current != default:
  456. d = Path(current)
  457. _secure_media_cache_dir(d)
  458. return d
  459. def cleanup(max_age_hours: int = MEDIA_CACHE_MAX_AGE_HOURS) -> int:
  460. return unlink_files_older_than(get_dir(), "*", max_age_hours * 3600)
  461. get_dir.__name__ = get_dir.__qualname__ = f"get_{kind}_cache_dir"
  462. cleanup.__name__ = cleanup.__qualname__ = f"cleanup_{kind}_cache"
  463. return get_dir, cleanup
  464. get_image_cache_dir, cleanup_image_cache = _cache_dir_accessors(
  465. "image", "IMAGE_CACHE_DIR", "cache/images", "image_cache")
  466. def _looks_like_image(data: bytes) -> bool:
  467. """Return True if *data* starts with a known image magic-byte sequence."""
  468. return len(data) >= 4 and (data[:8] == b"\x89PNG\r\n\x1a\n" or data[:3] == b"\xff\xd8\xff"
  469. or data[:6] in {b"GIF87a", b"GIF89a"} or data[:2] == b"BM"
  470. or (data[:4] == b"RIFF" and len(data) >= 12 and data[8:12] == b"WEBP"))
  471. def _secure_media_cache_dir(cache_dir: Path) -> None:
  472. """Create/reconcile a gateway media-cache dir owner-only (0700), except managed.
  473. Inbound media (photos, voice notes, documents a user sent through a
  474. messaging platform) is user content, not regenerable cache: the
  475. umask-derived 0755 these dirs inherited made them readable by every other
  476. local account whenever ``HERMES_HOME`` is traversable — the documented
  477. ``HERMES_HOME_MODE=0701`` web-server hatch. The mode is passed to ``mkdir``
  478. so it is set at creation, then reconciled by the house policy helper
  479. ``hermes_cli.config._secure_dir`` (managed/NixOS installs keep their
  480. group-share design: these lazily-created dirs are not covered by the
  481. module's ``systemd.tmpfiles`` rules, so the mode is left to the
  482. configured umask/setgid). Best-effort: never fails a media write.
  483. """
  484. try:
  485. managed = False
  486. try:
  487. from hermes_cli.config import is_managed
  488. managed = bool(is_managed())
  489. except Exception: # pragma: no cover - defensive
  490. pass
  491. if managed:
  492. cache_dir.mkdir(parents=True, exist_ok=True)
  493. return
  494. make_user_dir(cache_dir, parents=True, exist_ok=True, mode=0o700)
  495. try:
  496. from hermes_cli.config import _secure_dir
  497. _secure_dir(cache_dir)
  498. except Exception as exc: # pragma: no cover - defensive
  499. logger.debug("media cache dir chmod skipped: %s", exc)
  500. except Exception as exc: # pragma: no cover - defensive
  501. logger.debug("media cache dir creation failed for %s: %s", cache_dir, exc)
  502. cache_dir.mkdir(parents=True, exist_ok=True)
  503. def _write_cache_file(cache_dir: Path, prefix: str, ext: str, data: bytes) -> str:
  504. """Write ``data`` to ``<cache_dir>/<prefix>_<uuid12><ext>``; return the path string.
  505. The file is written owner-only (0600) — inbound media is private user
  506. content and the cache dir is hardened to 0700 by ``_secure_media_cache_dir``;
  507. one directory should not carry two file-mode conventions. Best-effort on
  508. platforms where POSIX mode bits are advisory (Windows): falls back to a
  509. plain write rather than failing the media write.
  510. """
  511. filepath = cache_dir / f"{prefix}_{uuid.uuid4().hex[:12]}{ext}"
  512. try:
  513. fd = os.open(str(filepath), os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
  514. except OSError:
  515. filepath.write_bytes(data)
  516. return str(filepath)
  517. with os.fdopen(fd, "wb") as handle:
  518. handle.write(data)
  519. return str(filepath)
  520. def cache_image_from_bytes(data: bytes, ext: str = ".jpg") -> str:
  521. """Save raw image bytes to the cache and return the absolute path; raises
  522. ValueError when *data* isn't an image (e.g. an upstream HTML error page)."""
  523. validate_inbound_media_size(len(data), media_type="image")
  524. if not _looks_like_image(data):
  525. snippet = data[:80].decode("utf-8", errors="replace")
  526. raise ValueError(f"Refusing to cache non-image data as {ext} (starts with: {snippet!r})")
  527. return _write_cache_file(get_image_cache_dir(), "img", ext, data)
  528. async def cache_image_from_bytes_async(data: bytes, ext: str = ".jpg") -> str:
  529. """Cache image bytes without blocking the caller's event loop."""
  530. return await asyncio.to_thread(cache_image_from_bytes, data, ext)
  531. async def _cache_media_from_url(url: str, ext: str, retries: int, *, media_type: str, accept: str,
  532. cache_fn, log_label: str) -> str:
  533. """Shared downloader behind ``cache_*_from_url``: SSRF-checked (pre-flight + per-redirect;
  534. raises ValueError), size-capped, linear-backoff retries on timeouts / 429 / 5xx."""
  535. from tools.url_safety import create_ssrf_safe_async_client, is_safe_url
  536. import httpx
  537. if not is_safe_url(url):
  538. raise ValueError(f"Blocked unsafe URL (SSRF protection): {safe_url_for_log(url)}")
  539. headers = {"User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)", "Accept": accept}
  540. async with create_ssrf_safe_async_client(
  541. timeout=30.0, follow_redirects=True, event_hooks={"response": [ssrf_redirect_guard]},
  542. ) as client:
  543. for attempt in range(retries + 1):
  544. try:
  545. async with client.stream("GET", url, headers=headers) as response:
  546. response.raise_for_status()
  547. content = await _read_httpx_body_with_limit(response, media_type=media_type)
  548. return await asyncio.to_thread(cache_fn, content, ext)
  549. except (httpx.TimeoutException, httpx.HTTPStatusError) as exc:
  550. if isinstance(exc, httpx.HTTPStatusError) and exc.response.status_code < 429:
  551. raise
  552. if attempt < retries:
  553. wait = 1.5 * (attempt + 1)
  554. logger.debug("%s cache retry %d/%d for %s (%.1fs): %s", log_label, attempt + 1,
  555. retries, safe_url_for_log(url), wait, exc)
  556. await asyncio.sleep(wait)
  557. continue
  558. raise
  559. async def cache_image_from_url(url: str, ext: str = ".jpg", retries: int = 2) -> str:
  560. """Download an image URL into the image cache; return the absolute path."""
  561. return await _cache_media_from_url(
  562. url, ext, retries, media_type="image", accept="image/*,*/*;q=0.8",
  563. cache_fn=cache_image_from_bytes, log_label="Media")
  564. # Audio cache utilities (same pattern as images; feeds the STT tool).
  565. AUDIO_CACHE_DIR = get_hermes_dir("cache/audio", "audio_cache")
  566. get_audio_cache_dir, cleanup_audio_cache = _cache_dir_accessors(
  567. "audio", "AUDIO_CACHE_DIR", "cache/audio", "audio_cache")
  568. def cache_audio_from_bytes(data: bytes, ext: str = ".ogg") -> str:
  569. """Save raw audio bytes to the cache (container-sniffed ext); return the path."""
  570. # tools.audio_container is the ONE owner of container detection (outbound TTS repair + here).
  571. from tools.audio_container import sniff_audio_ext
  572. validate_inbound_media_size(len(data), media_type="audio")
  573. return _write_cache_file(get_audio_cache_dir(), "audio", sniff_audio_ext(data, ext), data)
  574. async def cache_audio_from_bytes_async(data: bytes, ext: str = ".ogg") -> str:
  575. """Cache audio bytes without blocking the caller's event loop."""
  576. return await asyncio.to_thread(cache_audio_from_bytes, data, ext)
  577. async def cache_audio_from_url(url: str, ext: str = ".ogg", retries: int = 2) -> str:
  578. """Download an audio URL into the audio cache; return the absolute path."""
  579. return await _cache_media_from_url(
  580. url, ext, retries, media_type="audio", accept="audio/*,*/*;q=0.8",
  581. cache_fn=cache_audio_from_bytes, log_label="Audio")
  582. # Video cache utilities (same pattern; referenced by local path).
  583. VIDEO_CACHE_DIR = get_hermes_dir("cache/videos", "video_cache")
  584. get_video_cache_dir, cleanup_video_cache = _cache_dir_accessors(
  585. "video", "VIDEO_CACHE_DIR", "cache/videos", "video_cache")
  586. SUPPORTED_VIDEO_TYPES = {
  587. ".mp4": "video/mp4", ".mov": "video/quicktime", ".webm": "video/webm",
  588. ".mkv": "video/x-matroska", ".avi": "video/x-msvideo"}
  589. def cache_video_from_bytes(data: bytes, ext: str = ".mp4") -> str:
  590. """Save raw video bytes to the cache and return the absolute file path."""
  591. validate_inbound_media_size(len(data), media_type="video")
  592. return _write_cache_file(get_video_cache_dir(), "video", ext, data)
  593. async def cache_video_from_bytes_async(data: bytes, ext: str = ".mp4") -> str:
  594. """Cache video bytes without blocking the caller's event loop."""
  595. return await asyncio.to_thread(cache_video_from_bytes, data, ext)
  596. # Document / screenshot cache utilities (same pattern; referenced by local path).
  597. DOCUMENT_CACHE_DIR = get_hermes_dir("cache/documents", "document_cache")
  598. SCREENSHOT_CACHE_DIR = get_hermes_dir("cache/screenshots", "browser_screenshots")
  599. get_document_cache_dir, cleanup_document_cache = _cache_dir_accessors(
  600. "document", "DOCUMENT_CACHE_DIR", "cache/documents", "document_cache")
  601. get_screenshot_cache_dir, cleanup_screenshot_cache = _cache_dir_accessors(
  602. "screenshot", "SCREENSHOT_CACHE_DIR", "cache/screenshots", "browser_screenshots")
  603. # Import-time defaults; _resolve_cache_dir compares against these to detect a test monkeypatch.
  604. _CACHE_DIR_IMPORT_DEFAULTS = {
  605. "IMAGE_CACHE_DIR": IMAGE_CACHE_DIR, "AUDIO_CACHE_DIR": AUDIO_CACHE_DIR,
  606. "VIDEO_CACHE_DIR": VIDEO_CACHE_DIR, "DOCUMENT_CACHE_DIR": DOCUMENT_CACHE_DIR,
  607. "SCREENSHOT_CACHE_DIR": SCREENSHOT_CACHE_DIR}
  608. # Launch-time homes: fine for the static ALLOW roots below (per-profile cache roots are
  609. # enumerated at check time), never for the credential DENY side — see _credential_home_roots.
  610. _HERMES_HOME = get_hermes_home()
  611. _HERMES_ROOT = get_default_hermes_root()
  612. MEDIA_DELIVERY_ALLOW_DIRS_ENV = "HERMES_MEDIA_ALLOW_DIRS"
  613. MEDIA_DELIVERY_TRUST_RECENT_ENV = "HERMES_MEDIA_TRUST_RECENT_FILES"
  614. MEDIA_DELIVERY_TRUST_RECENT_SECONDS_ENV = "HERMES_MEDIA_TRUST_RECENT_SECONDS"
  615. # Strict mode = allowlist+recency validation; off by default (the denylist still blocks
  616. # credential / system paths). Set true on public-facing gateways.
  617. MEDIA_DELIVERY_STRICT_ENV = "HERMES_MEDIA_DELIVERY_STRICT"
  618. # Canonical cache subdirs of deliverable artifacts; also enumerates per-profile cache roots.
  619. _MEDIA_DELIVERY_CACHE_SUBDIRS = (
  620. "images", "audio", "videos", "documents", "screenshots", GENERATED_SUBDIR)
  621. MEDIA_DELIVERY_SAFE_ROOTS = (
  622. IMAGE_CACHE_DIR, AUDIO_CACHE_DIR, VIDEO_CACHE_DIR, DOCUMENT_CACHE_DIR, SCREENSHOT_CACHE_DIR,
  623. *(_HERMES_HOME / d for d in (
  624. "image_cache", "audio_cache", "video_cache", "document_cache", "browser_screenshots")),
  625. # Canonical cache layout, alongside the legacy *_cache dirs (installs may have both).
  626. *(_HERMES_HOME / "cache" / d for d in _MEDIA_DELIVERY_CACHE_SUBDIRS))
  627. # Recency window (s) for trusting fresh files: artifacts land seconds before delivery,
  628. # pre-existing host files (/etc/passwd, ~/.ssh/id_rsa) are days/months old.
  629. _MEDIA_DELIVERY_TRUST_RECENT_DEFAULT_SECONDS = 600
  630. # Hard denylist even for "recent" files (credentials, system state, /proc); the cache-dir
  631. # allowlist still beats it.
  632. _MEDIA_DELIVERY_DENIED_PREFIXES = (
  633. "/etc", "/proc", "/sys", "/dev", "/root", "/boot", "/var/log", "/var/lib", "/var/run")
  634. # Credential / config dirs denied under $HOME (Library/Keychains = macOS), resolved at check time.
  635. _MEDIA_DELIVERY_DENIED_HOME_SUBPATHS = (
  636. ".ssh", ".aws", ".gnupg", ".kube", ".docker", ".config", ".azure", ".gcloud",
  637. "Library/Keychains")
  638. def _sqlite_files(name: str) -> tuple[str, ...]:
  639. """A SQLite store plus its WAL/SHM/rollback-journal sidecars."""
  640. return (name, f"{name}-wal", f"{name}-shm", f"{name}-journal")
  641. # Credential stores at the HERMES_HOME root, denied per-file so skills/, logs/ and agent-written
  642. # files stay deliverable (cache subdirs are allowlisted BEFORE this). A superset of the
  643. # agent/file_safety.py read+write denies so exfil never trails the read guard. google_token.json's mtime bumps every turn (defeats the
  644. # recency window); pairing/, mcp-tokens/ (live OAuth tokens) and webapp/ (the Webapp's credential) are whole trees.
  645. _ROOT_CREDENTIAL_PATHS = (
  646. ".env", "auth.json", "auth.lock", "credentials", "config.yaml", ".anthropic_oauth.json",
  647. "google_token.json", "google_oauth_pending.json", os.path.join("auth", "google_oauth.json"),
  648. "webhook_subscriptions.json", *SECRET_CACHE_STORES, "pairing", "mcp-tokens", "webapp",
  649. # Whole conversation history (every secret ever pasted into a chat) and the copied browser
  650. # cookie/login store; sessions/ is the legacy transcript dir. SQLite sidecars are listed
  651. # too: WAL mode touches state.db-wal on every write, so recency trust alone would leak them.
  652. "sessions", "browser-profile", *_sqlite_files("state.db"), *_sqlite_files("kanban.db"))
  653. def _profile_cache_roots() -> list[Path]:
  654. """Per-profile cache roots ``<root>/profiles/<name>/cache/{images,...}`` and every home's connector
  655. downloads dir (the static safe roots cover only the launch HERMES_HOME). Enumerated at check
  656. time so profiles created after startup count, and allowlisted BEFORE the ``/root`` denylist,
  657. which otherwise wins when HERMES_HOME is symlinked under a denied prefix (#31733).
  658. """
  659. return [*(p / "cache" / subdir for p in _profile_dirs() for subdir in _MEDIA_DELIVERY_CACHE_SUBDIRS),
  660. *(p / CONNECTOR_DOWNLOADS_SUBDIR for p in (get_hermes_home(), *_profile_dirs()))]
  661. def _profile_dirs() -> list[Path]:
  662. """Every ``<root>/profiles/<name>`` directory, read at check time."""
  663. try:
  664. return [p for p in (_HERMES_ROOT / "profiles").iterdir() if p.is_dir()]
  665. except OSError:
  666. return []
  667. def _credential_home_roots() -> list[Path]:
  668. """Every Hermes home whose credential stores the denylist must cover: the ACTIVE home
  669. (the per-turn HERMES_HOME override under ``gateway.multiplex_profiles``), the shared root
  670. and every ``<root>/profiles/*``. Enumerated at check time like ``_profile_cache_roots`` on
  671. the allow side — a denylist frozen at import covers only the launch profile, so a
  672. ``MEDIA:<root>/profiles/<other>/.env`` emitted in any profile's turn would upload it."""
  673. return list(dict.fromkeys((get_hermes_home(), _HERMES_ROOT, *_profile_dirs())))
  674. def _kanban_root() -> Path:
  675. """Kanban is root-shared across profiles by design (``kanban_db.kanban_home``)."""
  676. return Path(os.environ.get("HERMES_KANBAN_HOME", "").strip() or _HERMES_ROOT).expanduser()
  677. def _kanban_board_dirs() -> list[Path]:
  678. """Every directory under ``<root>/kanban/boards`` (lax on purpose: the DENY side must catch a
  679. board whatever its name; the allow side filters further)."""
  680. with contextlib.suppress(OSError):
  681. return [p for p in (_kanban_root() / "kanban" / "boards").iterdir() if p.is_dir()]
  682. return []
  683. def _kanban_attachment_roots() -> list[Path]:
  684. """Return durable Kanban attachment roots without importing kanban_db."""
  685. override = os.environ.get("HERMES_KANBAN_ATTACHMENTS_ROOT", "").strip()
  686. if override:
  687. return [Path(override).expanduser()]
  688. roots = [_kanban_root() / "kanban" / "attachments"]
  689. roots.extend(path / "attachments" for path in _kanban_board_dirs()
  690. if not path.is_symlink() and re.fullmatch(r"[a-z0-9][a-z0-9_-]{0,63}", path.name)
  691. and (path / "kanban.db").is_file())
  692. return roots
  693. def _media_delivery_allowed_roots() -> list[Path]:
  694. """Return roots from which model-emitted local media may be delivered."""
  695. from gateway.media_policy import media_delivery_allow_dirs
  696. operator_roots = (
  697. root for chunk in media_delivery_allow_dirs().split(os.pathsep)
  698. for raw_root in chunk.split(",")
  699. if (root := Path(os.path.expanduser(raw_root.strip()))).is_absolute())
  700. return [*map(Path, MEDIA_DELIVERY_SAFE_ROOTS), *_profile_cache_roots(),
  701. *_kanban_attachment_roots(), *operator_roots]
  702. def _media_delivery_recency_seconds() -> float:
  703. """Recency window (seconds) for trusting fresh files; 0 = pure-allowlist mode."""
  704. from gateway.media_policy import media_delivery_trust_recent, media_delivery_trust_recent_seconds
  705. if not media_delivery_trust_recent():
  706. return 0.0
  707. custom = media_delivery_trust_recent_seconds().strip()
  708. default = float(_MEDIA_DELIVERY_TRUST_RECENT_DEFAULT_SECONDS)
  709. return _or_default(lambda: max(0.0, float(custom)) if custom else default, default)
  710. def _kanban_board_db_paths() -> list[Path]:
  711. """Named-board ``kanban.db`` stores (+ sidecars): they sit beside the ATTACHMENTS dir
  712. ``_kanban_attachment_roots`` allowlists and hold every task, comment and run transcript."""
  713. return [board / name for board in _kanban_board_dirs() for name in _sqlite_files("kanban.db")]
  714. def _media_delivery_denied_paths() -> list[Path]:
  715. """Return absolute denylist paths under which delivery is never allowed."""
  716. home = Path(os.path.expanduser("~"))
  717. return [*map(Path, _MEDIA_DELIVERY_DENIED_PREFIXES),
  718. *(home / sub for sub in _MEDIA_DELIVERY_DENIED_HOME_SUBPATHS),
  719. *(r / rel for r in _credential_home_roots() for rel in _ROOT_CREDENTIAL_PATHS),
  720. *_kanban_board_db_paths()]
  721. def _resolve_path(path: Path, *, strict: bool = False, expand: bool = False) -> Optional[Path]:
  722. """``path[.expanduser()].resolve(strict)`` or None when it fails (OSError / RuntimeError /
  723. ValueError — embedded NUL, symlink loop, undeterminable home, missing file under ``strict``)."""
  724. try:
  725. return (path.expanduser() if expand else path).resolve(strict=strict)
  726. except (OSError, RuntimeError, ValueError):
  727. return None
  728. def _path_under_denied_prefix(resolved: Path) -> bool:
  729. """True if ``resolved`` lives under a deny-listed system path — except a denied prefix that
  730. IS the running user's own home: ``/root`` is listed so a non-root gateway can't deliver
  731. another user's home, but a root-run gateway's own deliverables live under ``$HOME=/root``.
  732. Credential sub-dirs (``~/.ssh``, ``~/.hermes/.env``) stay blocked (more-specific entries)."""
  733. home = _resolve_path(Path(os.path.expanduser("~")))
  734. for denied in _media_delivery_denied_paths():
  735. resolved_denied = _resolve_path(denied, expand=True)
  736. if resolved_denied is None:
  737. continue
  738. hit = resolved == resolved_denied or _path_is_within(resolved, resolved_denied)
  739. if hit and resolved_denied != home:
  740. return True
  741. return False
  742. def _file_is_recently_produced(resolved: Path, window_seconds: float) -> bool:
  743. """True if mtime is within ``window_seconds`` — a session-scoped trust signal: agents
  744. produce artifacts seconds before sending; pre-existing host files are days/months old."""
  745. if window_seconds <= 0:
  746. return False
  747. try:
  748. return (time.time() - resolved.stat().st_mtime) <= window_seconds
  749. except OSError:
  750. return False
  751. def _path_is_within(path: Path, root: Path) -> bool:
  752. with contextlib.suppress(ValueError):
  753. path.relative_to(root)
  754. return True
  755. return False
  756. def _tenv(name: str, default: str = "") -> str:
  757. """Scope-aware TERMINAL_* read: the per-turn scope carries the ACTIVE profile's settings while
  758. os.getenv reads whatever a prior turn pinned into the process env. Only ImportError falls
  759. back — a refusal scope must raise rather than rebuild another profile's policy from the env."""
  760. try:
  761. from tools.terminal_scope import terminal_env
  762. except ImportError:
  763. return os.getenv(name, default)
  764. return terminal_env(name, default)
  765. def _parse_docker_volume_mounts() -> list[tuple[Path, Path]]:
  766. """Parse ``TERMINAL_DOCKER_VOLUMES`` (JSON list of ``host:container[:mode]``) into
  767. ``(host_path, container_path)``; named volumes / non-absolute hosts can't resolve here."""
  768. raw = _tenv("TERMINAL_DOCKER_VOLUMES", "").strip()
  769. try:
  770. import json as _json
  771. parsed = _json.loads(raw) if raw else []
  772. except Exception:
  773. return []
  774. mounts: list[tuple[Path, Path]] = []
  775. for entry in parsed if isinstance(parsed, list) else ():
  776. spec = entry.strip() if isinstance(entry, str) else ""
  777. # First ':/' past any Windows drive colon (``C:/data:/workspace``) splits host from container.
  778. sep = spec.find(":/", 2 if re.match(r"[A-Za-z]:[/\\]", spec) else 0)
  779. if sep <= 0:
  780. continue
  781. container_raw = spec[sep + 1:].split(":", 1)[0] # starts with /
  782. # Skip named volumes (no absolute/drive host path).
  783. host_expanded = os.path.expanduser(spec[:sep])
  784. if not (host_expanded.startswith("/") or (len(host_expanded) > 1 and host_expanded[1] == ":")):
  785. continue
  786. if (host_path := _resolve_path(Path(host_expanded))) is not None: # container_raw is POSIX on any OS
  787. mounts.append((host_path, Path(container_raw)))
  788. return mounts
  789. _TRUTHY = {"1", "true", "yes", "on"}
  790. def _docker_env_active() -> bool:
  791. return _tenv("TERMINAL_ENV", "").strip().lower() == "docker"
  792. def _docker_persistent_active() -> bool:
  793. """Docker backend with persistent containers (the default) enabled."""
  794. return _docker_env_active() and _tenv("TERMINAL_CONTAINER_PERSISTENT", "true").strip().lower() in _TRUTHY
  795. def _cache_dir_container_mounts() -> list[tuple[Path, Path]]:
  796. """(host, container) pairs for the auto-mounted Hermes cache dirs (``/root/.hermes/...`` in
  797. MEDIA tags); longer prefixes than the ``/root`` home mount, so longest-prefix match wins."""
  798. if not _docker_env_active():
  799. return []
  800. try:
  801. from tools.credential_files import get_cache_directory_mounts
  802. return [(Path(m["host_path"]), Path(m["container_path"])) for m in get_cache_directory_mounts()]
  803. except Exception:
  804. return []
  805. def _warn_unresolved_docker_media(candidate: Path, session_key: str, reason: str, quiet: bool = False) -> None:
  806. """Name WHY a container-absolute MEDIA path failed translation (otherwise the only signal is
  807. the generic "Skipping unsafe MEDIA directive path" line). Docker-only; host rejections and ``quiet``
  808. callers (fs routes, which also see ordinary host paths) stay silent.
  809. See #93950.
  810. """
  811. if quiet or not _docker_env_active():
  812. return
  813. logger.warning("Docker MEDIA path %s did not resolve to a host sandbox file (%s%s); "
  814. "the producing container's sandbox directory may not exist yet or "
  815. "was pruned", _log_safe_path(str(candidate)), reason,
  816. f", session_key={session_key}" if session_key else "")
  817. def _translate_docker_container_media_path(
  818. candidate: Path, session_key: str = "", workspace_key: str = "", *, quiet: bool = False, workspace_cwd: str = "",
  819. ) -> Optional[Path]:
  820. """Container-absolute path -> host path via longest-prefix match over ``docker_volumes``, the
  821. auto-mounted cache dirs (``/root/.hermes/...``), persistent ``/workspace`` and ``/root``.
  822. ``workspace_key`` is the 16-hex digest of one session's host cwd ``workspace_cwd`` (its cwd
  823. mount). It selects that session's ``<base>:ws:<digest>`` sandbox and is empty for MEDIA delivery.
  824. """
  825. if not candidate.as_posix().startswith("/"): # POSIX even on Windows gateways (not is_absolute)
  826. return None
  827. # In-process gateways (Desktop, `hermes serve`) may not have bridged terminal.* config into
  828. # TERMINAL_* env yet; the bridge is idempotent.
  829. with contextlib.suppress(Exception):
  830. from tools.terminal_tool import _ensure_terminal_env_bridged
  831. _ensure_terminal_env_bridged()
  832. from gateway.platforms.docker_media_paths import (
  833. _default_docker_workspace_host_roots, _docker_persistent_sandbox_roots,
  834. )
  835. mounts = [*_parse_docker_volume_mounts(), *_cache_dir_container_mounts()]
  836. mounted = {c.as_posix() for _, c in mounts}
  837. # Synthetic /workspace mounts: this session's workspace sandbox, then the
  838. # shared profile layout, then the legacy per-session dir.
  839. if "/workspace" not in mounted:
  840. mounts.extend(
  841. (root, Path("/workspace"))
  842. for root in _default_docker_workspace_host_roots(session_key, workspace_key, workspace_cwd))
  843. # Synthetic /root mounts catch stray home writes (/root/out.png; cache mounts are longer
  844. # prefixes). /root/.hermes/* that missed a cache mount is the container's credential surface —
  845. # translating it via the home mount would dodge the host denylist.
  846. if "/root" not in mounted and not candidate.as_posix().startswith("/root/.hermes"):
  847. mounts.extend(
  848. (root, Path("/root"))
  849. for root in _docker_persistent_sandbox_roots(session_key, "home", workspace_key))
  850. if not mounts:
  851. _warn_unresolved_docker_media(candidate, session_key, "no sandbox mounts resolved", quiet)
  852. return None
  853. # Longest container-prefix match; equal-length prefixes are tried in insertion order.
  854. candidate_posix = candidate.as_posix()
  855. matched = [(host_root, container_root, len(prefix)) for host_root, container_root in mounts
  856. for prefix in (container_root.as_posix().rstrip("/") or "/",)
  857. if candidate_posix == prefix or candidate_posix.startswith(prefix + "/")]
  858. if not matched:
  859. _warn_unresolved_docker_media(candidate, session_key, "no mounted prefix matches", quiet)
  860. return None
  861. for host_root, container_root, _score in sorted(matched, key=lambda m: -m[2]):
  862. translated = _resolve_path(host_root / candidate.relative_to(container_root), strict=True)
  863. if translated is not None and (
  864. translated == host_root or _path_is_within(translated, host_root)):
  865. return translated
  866. _warn_unresolved_docker_media(candidate, session_key, "host file missing from sandbox", quiet)
  867. return None
  868. def validate_media_delivery_path(path: str, session_key: str = "") -> Optional[str]:
  869. """Safe absolute file path for native media delivery, else None. Default: any existing
  870. regular file outside the credential / system denylist (symmetric with inbound). Strict
  871. (``HERMES_MEDIA_DELIVERY_STRICT=1``, public bots where prompt injection must not exfiltrate
  872. host secrets): MUST be under a Hermes cache, an operator root (``HERMES_MEDIA_ALLOW_DIRS``),
  873. or freshly produced within the recency window. Symlinks are resolved before any check."""
  874. candidate = _normalize_media_tag_path(path)
  875. if not candidate:
  876. return None
  877. try:
  878. expanded = Path(os.path.expanduser(candidate))
  879. except (OSError, RuntimeError, ValueError):
  880. # expanduser raises ValueError("embedded null byte") for a ~\x00 path.
  881. return None
  882. if not expanded.is_absolute():
  883. return None
  884. # Docker agents emit MEDIA:/workspace/... — map container paths to host paths first.
  885. resolved = _translate_docker_container_media_path(expanded, session_key=session_key)
  886. if resolved is None:
  887. resolved = _resolve_path(expanded, strict=True)
  888. if resolved is None or not resolved.is_file():
  889. return None
  890. # Cache / operator allowlist is trusted unconditionally, regardless of mode.
  891. for root in _media_delivery_allowed_roots():
  892. resolved_root = _resolve_path(root, expand=True)
  893. if resolved_root is not None and _path_is_within(resolved, resolved_root):
  894. return str(resolved)
  895. # Non-strict (default): anything not denylisted (/etc, /proc, ~/.ssh, Hermes-root secrets).
  896. from gateway.media_policy import media_delivery_strict
  897. if not media_delivery_strict():
  898. return None if _path_under_denied_prefix(resolved) else str(resolved)
  899. # Strict: recency trust for fresh files (pandoc -o /tmp/x.pdf); denylist still applies.
  900. window = _media_delivery_recency_seconds()
  901. if (window > 0 and not _path_under_denied_prefix(resolved)
  902. and _file_is_recently_produced(resolved, window)):
  903. return str(resolved)
  904. return None
  905. # Control chars + Unicode line separators (NEL, LS, PS) that log aggregators treat as breaks: a
  906. # model-emitted path must not forge a log line.
  907. _LOG_UNSAFE_CHARS = re.compile(r"[\x00-\x1f\x7f\x85\u2028\u2029]")
  908. def _log_safe_path(path: str) -> str:
  909. """Return a single-line, length-bounded path for log output."""
  910. return _LOG_UNSAFE_CHARS.sub("?", str(path))[:200]
  911. def _validated_delivery_path(raw_path, session_key: str, label: str,
  912. dropped: Optional[list[dict]] = None) -> Optional[str]:
  913. """``validate_media_delivery_path`` plus the shared "Skipping unsafe ..." warning. A path the
  914. host cannot see is retried against the active remote sandbox (ssh/modal/...; #466). When
  915. ``dropped`` is a list, a rejected path is appended as ``{"path", "reason"}`` so the caller can
  916. report the drop instead of booking a delivery that never happened (#115908)."""
  917. raw = str(raw_path)
  918. safe_path = validate_media_delivery_path(raw, session_key=session_key)
  919. if not safe_path:
  920. from gateway.media_fetch import fetch_remote_media
  921. safe_path = fetch_remote_media(raw)
  922. if not safe_path:
  923. # Say WHY: a path that does not exist on the host is the common case (a model hallucinated or
  924. # a sandbox path failed to translate) and is not a security rejection.
  925. reason = "not found on this host" if not _existing_regular_file(raw) else "denied by the delivery policy"
  926. logger.warning("Skipping %s (%s): %s", label, reason, _log_safe_path(raw))
  927. if dropped is not None:
  928. dropped.append({"path": raw, "reason": reason})
  929. return safe_path
  930. def _existing_regular_file(raw: str) -> bool:
  931. try:
  932. return Path(os.path.expanduser(raw)).is_file()
  933. except (OSError, RuntimeError, ValueError):
  934. return False
  935. SUPPORTED_DOCUMENT_TYPES = {
  936. ".pdf": "application/pdf", ".md": "text/markdown", ".txt": "text/plain", ".csv": "text/csv",
  937. ".log": "text/plain", ".json": "application/json", ".xml": "application/xml",
  938. ".yaml": "application/yaml", ".yml": "application/yaml", ".toml": "application/toml",
  939. ".ini": "text/plain", ".cfg": "text/plain", ".zip": "application/zip",
  940. ".doc": "application/msword", ".xls": "application/vnd.ms-excel",
  941. ".ppt": "application/vnd.ms-powerpoint",
  942. ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
  943. ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
  944. ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
  945. ".ts": "text/plain", ".py": "text/plain", ".sh": "text/plain"}
  946. # Files safe to inline into the prompt when small. An extension gate, NOT a blind UTF-8 decode
  947. # (PDF/zip/docx can start with decodable ASCII). Non-members are still cached by path.
  948. _TEXT_INJECT_EXTENSIONS = {
  949. ".txt", ".md", ".markdown", ".csv", ".tsv", ".log", ".json", ".jsonl", ".ndjson", ".xml",
  950. ".yaml", ".yml", ".toml", ".ini", ".cfg", ".conf", ".env", ".properties", ".html", ".htm",
  951. ".css", ".scss", ".sass", ".less", ".py", ".pyi", ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx",
  952. ".sh", ".bash", ".zsh", ".fish", ".ps1", ".bat", ".c", ".h", ".cpp", ".cc", ".hpp", ".cs",
  953. ".java", ".kt", ".go", ".rs", ".rb", ".php", ".pl", ".lua", ".r", ".jl", ".swift", ".m",
  954. ".scala", ".clj", ".ex", ".exs", ".erl", ".sql", ".graphql", ".proto", ".tf", ".hcl",
  955. ".dockerfile", ".makefile", ".cmake", ".gradle", ".rst", ".tex", ".srt", ".vtt", ".diff",
  956. ".patch"}
  957. # Image exts platforms may deliver as "documents" (file-picker uploads); routed to the image cache.
  958. SUPPORTED_IMAGE_DOCUMENT_TYPES = {
  959. ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".webp": "image/webp",
  960. ".gif": "image/gif"}
  961. # Media-delivery ext allowlist — SINGLE SOURCE OF TRUTH for both extractors and the cleanup
  962. # regexes: a tag is stripped only when deliverable, unknown-ext paths survive in the body.
  963. # Both extractors that turn response text into native attachments derive their extension set from this
  964. # tuple: * ``extract_media()`` — explicit ``MEDIA:<path>`` tags * ``extract_local_files()`` — bare
  965. # absolute/home paths the agent mentions Historically these two carried independently-maintained extension
  966. # lists. ``extract_media`` had a narrow list (no .md/.json/.yaml/.xml/.html/...) while
  967. # ``extract_local_files`` had a broad one. Combined with the unconditional ``MEDIA:\\s*\\S+`` cleanup at the
  968. # dispatch sites, that mismatch created a silent black hole: a ``MEDIA:/report.md`` tag failed the narrow
  969. # extract_media match, got stripped from the body by the loose cleanup regex, and was then invisible to
  970. # extract_local_files — the file was never delivered (issue #34517). Keeping one list eliminates the drift;
  971. # building the cleanup regexes from the same set means a tag is only stripped when its extension is one we
  972. # can actually deliver, so an unknown-extension path survives in the body instead of vanishing. Covers
  973. # images (inline), video (inline where supported), audio (voice/audio), documents/spreadsheets/presentations
  974. # (send_document), archives, and rendered web output. The dispatch partition (image vs video vs document)
  975. # lives in ``gateway/run.py``. ---------------------------------------------------------------------------
  976. MEDIA_DELIVERY_EXTS: tuple[str, ...] = (
  977. ".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp", ".tiff", ".svg", # images (embed inline)
  978. ".mp4", ".mov", ".avi", ".mkv", ".webm", ".3gp", # video (embed inline where supported)
  979. ".mp3", ".m2a", ".wav", ".ogg", ".opus", ".m4a", ".flac", # audio (voice/audio where supported)
  980. ".pdf", ".docx", ".doc", ".odt", ".rtf", ".txt", ".md", ".epub", # documents (file attachments)
  981. ".xlsx", ".xls", ".ods", ".csv", ".tsv", ".json", ".xml", ".yaml", ".yml", # spreadsheets/data
  982. ".kmz", ".kml", ".geojson", ".gpx", # geospatial / GIS
  983. ".pptx", ".ppt", ".odp", ".key", # presentations
  984. ".zip", ".tar", ".gz", ".tgz", ".bz2", ".xz", ".7z", ".rar", ".apk", ".ipa", # archives
  985. ".html", ".htm") # web / rendered output
  986. # Bare extensions (no dot) longest-first so a shorter ext never matches as a prefix of a longer one.
  987. _MEDIA_EXT_ALTERNATION = "|".join(sorted((e.lstrip(".") for e in MEDIA_DELIVERY_EXTS), key=len, reverse=True))
  988. # Anchored ``MEDIA:<path>`` cleanup pattern (dispatch path + streaming consumer). Strips only tags
  989. # whose path ends in a deliverable extension (optionally quoted/backticked); unknown-ext tags stay
  990. # for the bare-path detector. Rules: anchors ``~/``, ``/``, ``X:\`` / ``X:/``; up to 3 quote/
  991. # emphasis markers each side (code/blockquote contexts are masked earlier); non-greedy with
  992. # ``MEDIA:`` as a boundary so glued tags (``MEDIA:/a.pngMEDIA:/b.png``) never merge; sentence-final
  993. # ``.`` is a boundary only before whitespace/EOL (``data.csv.`` -> ``data.csv``, ``archive.tar.gz``
  994. # extends past ``.tar``); CJK full-width punctuation terminates paths (``早报.pdf(782.6 KB)``).
  995. # A ``MEDIA:`` tag with an unknown extension is left in the text so it can still be picked up by the
  996. # bare-path detector (extract_local_files) downstream rather than silently deleted. Path anchors: ``~/``
  997. # (Unix home-relative), ``/`` (Unix absolute), ``X:\\`` or ``X:/`` (Windows drive-letter absolute — #34632).
  998. # Emphasis tolerance: models routinely wrap the tag in Markdown emphasis (``**MEDIA:/x.pdf**``,
  999. # ``*MEDIA:/x.pdf*``, ``_MEDIA:/x.pdf_``) when they present a file to the user. The old single-quote anchor
  1000. # (``[`"']?``) and the closing lookahead (which lacked ``*``/``_``) failed to match such tags, so the file
  1001. # was silently never delivered and the literal ``MEDIA:`` text leaked into the chat. Allow a short run of
  1002. # emphasis/quote markers on both sides so the tag is recognised regardless of cosmetic Markdown. Code-block
  1003. # / inline-code / blockquote contexts are still neutralised earlier by ``_mask_protected_spans`` (#35695),
  1004. # so example tags remain non-deliverable. The trailing lookahead also accepts ``MEDIA:`` as a boundary, so
  1005. # the next tag stops the current match cleanly (#68773). The whitespace guard keeps multi-part extensions
  1006. # intact — for ``archive.tar.gz`` the ``.`` after ``tar`` is followed by ``g``, so the match must extend to
  1007. # ``.gz`` instead of stopping early at ``.tar``. CJK full-width punctuation accepted as MEDIA path
  1008. # terminators, mirroring the ASCII set in the looka below. Chinese-language agent output naturally writes
  1009. # ``MEDIA:D:\path\早报.pdf(782.6 KB)`` or ``MEDIA:...pdf:内容`` — without these, the lookahead fails and the
  1010. # attachment is silently dropped (#88038).
  1011. _MEDIA_CJK_TERMINATORS = "()〈〉《》:,。;!?、\u201c\u201d\u2018\u2019【】"
  1012. # Image tags ``extract_images`` turns into attachments (the streamed display hides the same tags).
  1013. MD_IMAGE_TAG_PATTERN = r'!\[([^\]]*)\]\((https?://[^\s\)]+)\)'
  1014. HTML_IMAGE_TAG_PATTERN = r'<img\s+src=["\']?(https?://[^\s"\'<>]+)["\']?\s*/?>\s*(?:</img>)?'
  1015. _IMAGE_URL_MARKERS = ('.png', '.jpg', '.jpeg', '.gif', '.webp', 'fal.media', 'fal-cdn', 'replicate.delivery')
  1016. MEDIA_TAG_CLEANUP_RE = re.compile(
  1017. r'''[`"'*_]{0,3}MEDIA:\s*'''
  1018. r'''(?P<path>`[^`\n]+?`|"[^"\n]+?"|'[^'\n]+?'|'''
  1019. r'''(?:~/|/|[A-Za-z]:[/\\])\S+?(?:[^\S\n]+\S+?)*?\.(?:''' + _MEDIA_EXT_ALTERNATION + r'''))'''
  1020. r'''(?=[\s`"'*_,;:)\]}\[''' + _MEDIA_CJK_TERMINATORS + r''']|MEDIA:|\.(?:\s|$)|$)[`"'*_]{0,3}\.?''',
  1021. re.IGNORECASE)
  1022. # Extension-less (Caddyfile) / unknown-ext (.py, .log) tags deliver only after
  1023. # ``validate_media_delivery_path`` accepts them, so injected paths that don't validate stay visible.
  1024. # The bare path class is whitespace-bounded (a tag glued to the next ``MEDIA:`` or prose must not
  1025. # absorb it); spaced paths are recovered by ``_match_extensionless_path`` with on-disk validation.
  1026. # Paths NOT covered by MEDIA_TAG_CLEANUP_RE's extension alternation — both extension-less files (Caddyfile,
  1027. # Dockerfile, Makefile) and files with an unknown extension (.py, .log, .weirdext, ...) — are validated and
  1028. # delivered via MEDIA_EXTENSIONLESS_TAG_RE. Every ``MEDIA:`` path is therefore deliverable regardless of
  1029. # file type (#36060): known extensions extract unconditionally via the anchored pattern above, everything
  1030. # else extracts only after ``validate_media_delivery_path`` accepts it (exists on disk, not under the
  1031. # credential/system denylist, strict-mode rules honored), so prompt-injection paths that do not validate are
  1032. # left visible instead of silently dropped. The path class uses a tempered-greedy token (``[^\s\n`"']+?``
  1033. # followed by a ``(?=...)`` lookahead) instead of the prior ``[^\s\n`"']+`` so a tag glued to the next
  1034. # ``MEDIA:`` keyword (``MEDIA:/a.pngMEDIA:/b.png``) or to arbitrary following text (``MEDIA:/a.pngSome
  1035. # text``) cannot silently absorb the next path — that earlier behavior merged the two paths into one invalid
  1036. # string and dropped the file (#68773). The bare form stays non-greedy and whitespace-bounded — spaced paths
  1037. # are NOT absorbed at the regex level, because greedy space-tolerance would reintroduce the #68773 bug class
  1038. # (gluing the next MEDIA: tag or trailing prose into one invalid path). Instead, unknown-extension paths
  1039. # containing spaces (``MEDIA:/data/map data.kmz``, ``C:\...\My Documents\x.log``) are recovered by
  1040. # ``_match_extensionless_path`` (#24032): when the bare match fails validation, the candidate is
  1041. # progressively extended forward across single spaces — bounded, stopping at newline / the next ``MEDIA:``
  1042. # keyword — and the first extension that validates on disk wins.
  1043. MEDIA_EXTENSIONLESS_TAG_RE = re.compile(
  1044. r'''[`"'*_]{0,3}MEDIA:\s*'''
  1045. r'''(?P<path>`[^`\n]+`|"[^"\n]+"|'[^'\n]+'|'''
  1046. r'''(?:~/|/|[A-Za-z]:[/\\])[^\s\n`"']+?)'''
  1047. r'''(?=[`"'\s,;:)\]}''' + _MEDIA_CJK_TERMINATORS + r''']|MEDIA:|$)'''
  1048. r'''[`"'*_]{0,3}\s*''',
  1049. re.IGNORECASE)
  1050. def _match_extensionless_path(scan_text: str, match: re.Match) -> Optional[tuple[str, int]]:
  1051. """Extensionless MEDIA tag match -> validated on-disk ``(safe_path, end_offset)`` or None: the
  1052. captured path first, then extended across single spaces (max 8 tokens, never past a newline
  1053. or the next ``MEDIA:``).
  1054. When that fails validation, the candidate is progressively extended forward across single spaces
  1055. (validation-gated, bounded at 8 tokens, never past a newline or a subsequent ``MEDIA:`` keyword) so
  1056. unknown-extension paths containing spaces deliver (#24032). Returns ``(safe_path, end_offset)`` where
  1057. ``end_offset`` is the index in ``scan_text`` just past the matched path, or ``None`` when nothing
  1058. validates.
  1059. """
  1060. path = _normalize_media_tag_path(match.group("path"))
  1061. if not path:
  1062. return None
  1063. safe = validate_media_delivery_path(path)
  1064. if safe:
  1065. return safe, match.end("path")
  1066. start = match.start("path")
  1067. segment = scan_text[start:].split("\n", 1)[0]
  1068. nxt = segment.find("MEDIA:", 1)
  1069. if nxt != -1:
  1070. segment = segment[:nxt]
  1071. pos = match.end("path") - start
  1072. for _ in range(8):
  1073. token = re.match(r"[ \t]*[^ \t]+", segment[pos:])
  1074. if not token:
  1075. break
  1076. tok_end = pos + token.end()
  1077. safe = validate_media_delivery_path(_normalize_media_tag_path(segment[:tok_end]))
  1078. if safe:
  1079. return safe, start + tok_end
  1080. pos = tok_end
  1081. return None
  1082. def _normalize_media_tag_path(raw: str) -> str:
  1083. path = str(raw or "").strip()
  1084. if len(path) >= 2 and path[0] == path[-1] and path[0] in "`\"'":
  1085. path = path[1:-1].strip()
  1086. return path.lstrip("`\"'").rstrip("`\"',.;:)}]")
  1087. def _path_lacks_deliverable_extension(path: str) -> bool:
  1088. """True when ``path`` has no extension or one outside MEDIA_DELIVERY_EXTS — such paths
  1089. take the validated delivery pass so nonexistent / denylisted ones stay visible.
  1090. ``path`` — either the basename has no extension at all (Caddyfile, Makefile, …) or the extension is not
  1091. in MEDIA_DELIVERY_EXTS (.py, .log, .weirdext, …). Such paths route through the validated delivery pass
  1092. (``validate_media_delivery_path``) instead of the unconditional one, so every file type is deliverable
  1093. (#36060) while nonexistent / denylisted paths stay visible in the text.
  1094. """
  1095. return Path(path).suffix.lower() not in MEDIA_DELIVERY_EXTS
  1096. def _has_media_directives(text: str) -> bool:
  1097. return "MEDIA:" in text or "[[audio_as_voice]]" in text or "[[as_document]]" in text
  1098. # A provider can leak its exact end-of-sequence control token glued to the last MEDIA path
  1099. # (``MEDIA:/x.png<|eos|>``). Neither tag regex accepts ``<`` as a path terminator — deliberately,
  1100. # since widening the delimiter set re-opens the glue classes #68773/#88038 — so the attachment was
  1101. # silently dropped (#111046). The one exact token is recognised here, at the seam every scan shares
  1102. # (extraction, display strip, stream cleanup), and only when it terminates the whole response.
  1103. _TERMINAL_SENTINEL = "<|eos|>"
  1104. def _terminal_sentinel_start(text: str) -> int:
  1105. """Offset where the run of exact ``<|eos|>`` tokens closing ``text`` (trailing whitespace
  1106. ignored) begins, else -1; the run ends at ``len(text.rstrip())``."""
  1107. end = start = len(text.rstrip())
  1108. while start >= len(_TERMINAL_SENTINEL) and text[start - len(_TERMINAL_SENTINEL):start] == _TERMINAL_SENTINEL:
  1109. start -= len(_TERMINAL_SENTINEL)
  1110. return start if start < end else -1
  1111. def _mask_media_scan_text(text: str) -> str:
  1112. """Offset-preserving mask of protected spans (code, quotes, JSON string values) and of a
  1113. terminal ``<|eos|>`` sentinel, so a tag glued to it ends on whitespace like any other.
  1114. BasePlatformAdapter is defined later in this module; resolved at call time."""
  1115. A = BasePlatformAdapter
  1116. masked = A._mask_json_string_media(A._mask_protected_spans(text))
  1117. start = _terminal_sentinel_start(text)
  1118. if start >= 0:
  1119. masked = _blank_spans(masked, [(start, len(text.rstrip()))])
  1120. return masked
  1121. def _deliverable_tag_spans(text: str) -> list:
  1122. """Spans to delete from ``text``: its deliverable MEDIA tags (located on the masked copy)
  1123. plus a terminal ``<|eos|>`` sentinel, which is a control token and never user content."""
  1124. spans = _real_media_tag_spans(_mask_media_scan_text(text))
  1125. start = _terminal_sentinel_start(text)
  1126. if spans and start >= 0:
  1127. spans.append((start, len(text.rstrip())))
  1128. return spans
  1129. def _extensionless_media_matches(masked: str):
  1130. """Yield ``(match, safe_path, end_offset)`` for every extension-less / unknown-extension
  1131. MEDIA tag in ``masked`` that ``validate_media_delivery_path`` accepts."""
  1132. for match in MEDIA_EXTENSIONLESS_TAG_RE.finditer(masked):
  1133. path = _normalize_media_tag_path(match.group("path"))
  1134. if path and _path_lacks_deliverable_extension(path):
  1135. resolved = _match_extensionless_path(masked, match)
  1136. if resolved is not None:
  1137. yield match, resolved[0], resolved[1]
  1138. def _real_media_tag_spans(masked: str) -> list:
  1139. """(start, end) spans of deliverable MEDIA tags on a masked copy: known-extension tags
  1140. unconditionally, extension-less / unknown ones only if validate_media_delivery_path accepts."""
  1141. spans: list = [m.span() for m in MEDIA_TAG_CLEANUP_RE.finditer(masked)]
  1142. spans.extend((match.start(), end) for match, _, end in _extensionless_media_matches(masked))
  1143. return spans
  1144. _FENCED_CODE_RE = re.compile(r'```[^\n]*\n.*?```', re.DOTALL)
  1145. _INLINE_CODE_RE = re.compile(r'`[^`\n]+`')
  1146. def _code_spans(content: str) -> list:
  1147. """(start, end) spans of fenced code blocks and inline code in ``content``."""
  1148. return [m.span() for rx in (_FENCED_CODE_RE, _INLINE_CODE_RE) for m in rx.finditer(content)]
  1149. def _blank_spans(text: str, spans: list) -> str:
  1150. """Replace every non-newline char inside ``spans`` with a space (offsets preserved)."""
  1151. chars = list(text)
  1152. for start, end in spans:
  1153. chars[start:end] = [c if c == '\n' else ' ' for c in chars[start:end]]
  1154. return ''.join(chars)
  1155. def _delete_spans(text: str, spans: list) -> str:
  1156. """Delete ``spans`` from ``text``, merging overlapping/nested ones first so multi-pattern
  1157. matches over the same tag never double-delete adjacent text."""
  1158. if not spans:
  1159. return text
  1160. merged: list = []
  1161. for s, e in sorted(spans):
  1162. if merged and s <= merged[-1][1]:
  1163. merged[-1] = (merged[-1][0], max(merged[-1][1], e))
  1164. else:
  1165. merged.append((s, e))
  1166. chars = list(text)
  1167. for start, end in reversed(merged):
  1168. del chars[start:end]
  1169. return "".join(chars)
  1170. def _strip_media_tag_directives(text: str) -> str:
  1171. """Remove MEDIA: tags and [[audio_as_voice]] / [[as_document]] markers so they never render
  1172. as text (backstop after ``extract_media``). Protected spans are mask-located only — tags
  1173. inside them are neither stripped nor mangled, matching ``extract_media`` so display and
  1174. delivery agree. Empty/None text is returned as-is.
  1175. See #16434.
  1176. """
  1177. if not text or not _has_media_directives(text):
  1178. return text
  1179. cleaned = text.replace("[[audio_as_voice]]", "").replace("[[as_document]]", "")
  1180. return _delete_spans(cleaned, _deliverable_tag_spans(cleaned))
  1181. def cache_document_from_bytes(data: bytes, filename: str) -> str:
  1182. """Save raw document bytes to the cache as ``doc_{uuid12}_{original_name}`` and return
  1183. the absolute path; raises ValueError if the sanitized path escapes the cache directory."""
  1184. cache_dir = get_document_cache_dir()
  1185. # Sanitize: strip directory components, null bytes, and control characters
  1186. safe_name = (Path(filename).name if filename else "document").replace("\x00", "").strip()
  1187. if not safe_name or safe_name in {".", ".."}:
  1188. safe_name = "document"
  1189. filepath = cache_dir / f"doc_{uuid.uuid4().hex[:12]}_{safe_name}"
  1190. # Final safety check: ensure path stays inside cache dir
  1191. if not filepath.resolve().is_relative_to(cache_dir.resolve()):
  1192. raise ValueError(f"Path traversal rejected: {filename!r}")
  1193. filepath.write_bytes(data)
  1194. return str(filepath)
  1195. async def cache_document_from_bytes_async(data: bytes, filename: str) -> str:
  1196. """Cache document bytes without blocking the caller's event loop."""
  1197. return await asyncio.to_thread(cache_document_from_bytes, data, filename)
  1198. # Unified media caching: classify attachment bytes by ext/MIME, route to cache_*_from_bytes.
  1199. @dataclass
  1200. class CachedMedia:
  1201. """Result of caching one attachment's bytes."""
  1202. path: str # absolute HOST cache path (same coordinate system as cache_*_from_bytes)
  1203. media_type: str # MIME type recorded on the MessageEvent
  1204. kind: str # "image" | "video" | "audio" | "document"
  1205. display_name: str # human-readable name for transcript notes
  1206. def context_note(self) -> str:
  1207. """One-line transcript annotation pointing the agent at the file (sandbox-translated at
  1208. render time, never baked into ``path``: ``event.media_urls`` must hold one coordinate
  1209. system so the routed turn can re-home and translate every entry alike, #101134)."""
  1210. from tools.credential_files import to_agent_visible_cache_path
  1211. return f"[{self.kind} '{self.display_name}' saved at: {to_agent_visible_cache_path(self.path)}]"
  1212. # MIME -> extension reverse lookup; FIRST match across image, video, document tables wins
  1213. # (built in reverse so the earliest extension is the one that survives).
  1214. _MIME_TO_EXT: dict[str, str] = {
  1215. mime: ext
  1216. for table in (SUPPORTED_DOCUMENT_TYPES, SUPPORTED_VIDEO_TYPES, SUPPORTED_IMAGE_DOCUMENT_TYPES)
  1217. for ext, mime in reversed(table.items())}
  1218. def _resolve_media_ext(filename: str, mime_type: str) -> str:
  1219. """Best-effort file extension from filename, then MIME fallback."""
  1220. ext = os.path.splitext(filename)[1].lower() if filename else ""
  1221. return ext or _MIME_TO_EXT.get((mime_type or "").lower(), "")
  1222. def cache_media_bytes(data: bytes, *, filename: str = "", mime_type: str = "",
  1223. default_kind: Optional[str] = None) -> Optional[CachedMedia]:
  1224. """Classify and cache raw attachment bytes -> CachedMedia (None only for images failing
  1225. validation). ``default_kind`` biases ambiguous ext/MIME (Telegram native photo, no name);
  1226. anything not image/video/audio is a document."""
  1227. ext = _resolve_media_ext(filename, mime_type)
  1228. mime = (mime_type or "").lower()
  1229. display = re.sub(r"[^\w.\- ]", "_", filename) if filename else (ext.lstrip(".") or "file")
  1230. # (kind, ext->mime table, default ext, cache fn, whether a matching caller MIME passes through)
  1231. for kind, table, default_ext, cache_fn, passthrough in (
  1232. ("image", SUPPORTED_IMAGE_DOCUMENT_TYPES, ".jpg", cache_image_from_bytes, True),
  1233. ("video", SUPPORTED_VIDEO_TYPES, ".mp4", cache_video_from_bytes, False),
  1234. ("audio", _AUDIO_MIME_TYPES, ".ogg", cache_audio_from_bytes, True)):
  1235. if not (mime.startswith(f"{kind}/") or ext in table or default_kind == kind):
  1236. continue
  1237. kind_ext = ext if ext in table else default_ext
  1238. try:
  1239. path = cache_fn(data, ext=kind_ext)
  1240. except ValueError:
  1241. if kind != "image":
  1242. raise
  1243. return None
  1244. out_mime = mime if passthrough and mime.startswith(f"{kind}/") else table[kind_ext]
  1245. return CachedMedia(path, out_mime, kind, display)
  1246. # Any other type is cached and surfaced as a path — an authorized user's uploads must never be
  1247. # silently dropped. Unknown types get octet-stream so the agent reaches for terminal tools.
  1248. fallback_name = filename or (f"document{ext}" if ext else "document.bin")
  1249. path = cache_document_from_bytes(data, fallback_name)
  1250. out_mime = SUPPORTED_DOCUMENT_TYPES.get(ext) or mime or "application/octet-stream"
  1251. return CachedMedia(path, out_mime, "document", display or fallback_name)
  1252. async def cache_media_bytes_async(
  1253. data: bytes,
  1254. *,
  1255. filename: str = "",
  1256. mime_type: str = "",
  1257. default_kind: Optional[str] = None,
  1258. ) -> Optional[CachedMedia]:
  1259. """Classify and cache attachment bytes without blocking the event loop."""
  1260. return await asyncio.to_thread(
  1261. cache_media_bytes,
  1262. data,
  1263. filename=filename,
  1264. mime_type=mime_type,
  1265. default_kind=default_kind,
  1266. )
  1267. @dataclass
  1268. class TextDebounceState:
  1269. event: MessageEvent
  1270. task: asyncio.Task | None
  1271. first_ts: float
  1272. last_ts: float
  1273. def cancel_timer(self, *, unless: asyncio.Task | None = None) -> None:
  1274. """Cancel the pending flush timer (if live and not ``unless``)."""
  1275. if self.task is not None and self.task is not unless and not self.task.done():
  1276. self.task.cancel()
  1277. def _append_text(existing: Optional[str], new: Optional[str]) -> str:
  1278. """``existing\\nnew`` when both non-empty; the non-empty one otherwise."""
  1279. return f"{existing}\n{new}" if existing else new
  1280. @dataclass
  1281. class _ExtractedResponse:
  1282. """Deliverable parts of a handler response (see ``_extract_response_content``)."""
  1283. text_content: str
  1284. images: list
  1285. media_files: list
  1286. local_files: list
  1287. force_document_attachments: bool
  1288. pre_extract: str
  1289. _PLAINTEXT_GATEWAY_RESTART_PATTERNS: tuple[re.Pattern[str], ...] = (
  1290. re.compile(r"^(?:please\s+)?restart\s+(?:the\s+)?gateway[.!?\s]*$", re.IGNORECASE),
  1291. re.compile(r"^(?:please\s+)?restart\s+(?:the\s+)?hermes\s+gateway[.!?\s]*$", re.IGNORECASE),
  1292. re.compile(r"^(?:please\s+)?restart\s+hermes[.!?\s]*$", re.IGNORECASE))
  1293. def coerce_plaintext_gateway_command(event: MessageEvent) -> None:
  1294. """Rewrite a tiny set of DM plaintext admin phrases (exact matches only) into slash commands so
  1295. ``restart gateway`` never reaches the LLM/tool path (a self-restart from inside the running
  1296. agent leaves the gateway stuck in ``draining`` waiting on that agent)."""
  1297. with contextlib.suppress(Exception):
  1298. if event is None or event.message_type != MessageType.TEXT:
  1299. return
  1300. text = (event.text or "").strip()
  1301. if not text or text.startswith("/"):
  1302. return
  1303. if getattr(getattr(event, "source", None), "chat_type", None) != "dm":
  1304. return
  1305. if any(pattern.match(text) for pattern in _PLAINTEXT_GATEWAY_RESTART_PATTERNS):
  1306. event.text = "/restart"
  1307. @dataclass
  1308. class ExecApprovalPrompt:
  1309. """One exec-approval prompt, ready for a platform to render natively (see
  1310. ``BasePlatformAdapter.send_exec_approval``). ``actions`` rows are ``(label, choice, style)``
  1311. with ``choice`` in ``once`` / ``session`` / ``always`` / ``deny`` — the vocabulary
  1312. ``tools.approval.resolve_gateway_approval`` accepts — and ``style`` in ``primary`` /
  1313. ``danger`` / ``""``."""
  1314. chat_id: str
  1315. session_key: str
  1316. text: str
  1317. actions: list[tuple[str, str, str]]
  1318. command: str
  1319. description: str
  1320. smart_denied: bool
  1321. metadata: Optional[dict[str, Any]] = None
  1322. request_id: Optional[str] = None # the ``tools.approval`` request this card answers (and only that one)
  1323. @property
  1324. def choices(self) -> list[str]:
  1325. return [choice for _, choice, _ in self.actions]
  1326. @dataclass
  1327. class SendResult:
  1328. """Result of sending a message."""
  1329. success: bool
  1330. message_id: Optional[str] = None
  1331. error: Optional[str] = None
  1332. # Adapter-specific metadata. Contracts: raw_response["partial_overflow"] (Telegram edit-overflow partial: the stream
  1333. # consumer sends the missing tail); raw_response["failure_notice_sent"] (a failed media send already posted a notice).
  1334. raw_response: Any = None
  1335. retryable: bool = False # transient connection error — base retries automatically
  1336. retry_after: Optional[float] = None # server-requested delay (Telegram FloodWait) beats our backoff
  1337. # Extra ids (send order) when a payload was split; ``message_id`` is then the LAST id so
  1338. # later edits target the newest chunk.
  1339. continuation_message_ids: tuple = ()
  1340. # SEND_ERROR_KINDS member (failures only) via :func:`classify_send_error`, so consumers
  1341. # branch without substring-matching ``error``.
  1342. error_kind: Optional[str] = None
  1343. # Longest server ``retry_after`` ``_send_with_retry`` will sleep inline. Longer penalties return the
  1344. # typed failure so the delivery ledger owns the wait (#91969: a 97-minute FloodWait slept verbatim
  1345. # pinned the send coroutine and froze inbound on every platform).
  1346. _SEND_RETRY_INLINE_WAIT_CAP_SECS = 60.0
  1347. # Platform-neutral send-failure kinds for ``SendResult.error_kind``: too_long (size cap),
  1348. # bad_format (markup rejected; plain-text retry fixes), forbidden (the bot CANNOT reach the user),
  1349. # not_found (chat/thread/message gone), rate_limited, transient (connection-level, retry-safe),
  1350. # unknown.
  1351. SEND_ERROR_KINDS = frozenset(
  1352. {"too_long", "bad_format", "forbidden", "not_found", "rate_limited", "transient", "unknown"})
  1353. # ``not_found`` substrings by blast radius: chat-level = target dead; thread/topic/message-level
  1354. # leaves the parent chat reachable.
  1355. _CHAT_LEVEL_NOT_FOUND_SUBSTRINGS = ("chat not found",)
  1356. _SUBCHAT_NOT_FOUND_SUBSTRINGS = (
  1357. "message to edit not found", "message to reply not found", "thread not found", "topic_deleted",
  1358. "message_id_invalid")
  1359. def _error_blob(exc: Optional[BaseException] = None, error_text: str = "") -> str:
  1360. """Lowercased blob (error_text + str(exc) + exception class name) that both
  1361. send-error classifiers match against — one builder so they can never drift."""
  1362. parts = [error_text] if error_text else []
  1363. if exc is not None:
  1364. parts.extend(p for p in (str(exc), exc.__class__.__name__) if p)
  1365. return " ".join(parts).lower()
  1366. def _any_in(blob: str, *needles: str) -> bool:
  1367. return any(n in blob for n in needles)
  1368. # Ordered (kind, predicate) table for classify_send_error — first match wins.
  1369. _SEND_ERROR_CLASSIFIERS: tuple[tuple[str, Callable[[str], bool]], ...] = (
  1370. ("too_long", lambda b: _any_in(b, "message_too_long", "too long", "message is too long")),
  1371. ("bad_format", lambda b: (
  1372. _any_in(b, "can't parse entities", "cant parse entities", "can't find end", "unsupported start tag")
  1373. or ("entity" in b and "parse" in b)
  1374. or ("bad request" in b and "entit" in b))),
  1375. ("forbidden", lambda b: _any_in(
  1376. b, "forbidden", "bot was blocked", "blocked by the user", "user is deactivated",
  1377. "not enough rights", "have no rights", "not a member")),
  1378. ("not_found", lambda b: _any_in(b, *_CHAT_LEVEL_NOT_FOUND_SUBSTRINGS, *_SUBCHAT_NOT_FOUND_SUBSTRINGS)),
  1379. ("rate_limited", lambda b: _any_in(b, "flood", "too many requests", "retry after", "rate limit")),
  1380. ("transient", lambda b: _any_in(b, *_RETRYABLE_ERROR_PATTERNS, "connecttimeout")))
  1381. def classify_send_error(exc: Optional[BaseException], error_text: str = "") -> str:
  1382. """Map a send exception / error string to a :data:`SEND_ERROR_KINDS` value; anything
  1383. unrecognized is ``"unknown"`` so an unclassified failure is never mistaken for a benign one."""
  1384. blob = _error_blob(exc, error_text)
  1385. return next((kind for kind, matches in _SEND_ERROR_CLASSIFIERS if matches(blob)), "unknown")
  1386. def is_chat_level_not_found(exc: Optional[BaseException] = None, error_text: str = "") -> bool:
  1387. """Whether a ``not_found`` failure means the *whole chat* is gone (only that marks a target
  1388. dead; a deleted topic / edited-away message leaves the parent chat reachable). When both
  1389. markers are present the sub-chat reading wins."""
  1390. blob = _error_blob(exc, error_text)
  1391. return (not _any_in(blob, *_SUBCHAT_NOT_FOUND_SUBSTRINGS)
  1392. and _any_in(blob, *_CHAT_LEVEL_NOT_FOUND_SUBSTRINGS))
  1393. class EphemeralReply(str):
  1394. """System-notice reply that auto-deletes after ``ttl_seconds`` on platforms implementing
  1395. ``delete_message`` (others leave it). ``None`` ttl uses ``display.ephemeral_system_ttl``
  1396. (``0`` disables globally). Subclassing ``str`` keeps it transparent to everything that
  1397. treats handler results as text; ``isinstance`` lets the send path schedule deletion."""
  1398. ttl_seconds: Optional[int]
  1399. def __new__(cls, text: str, ttl_seconds: Optional[int] = None):
  1400. instance = super().__new__(cls, text)
  1401. instance.ttl_seconds = ttl_seconds
  1402. return instance
  1403. @property
  1404. def text(self) -> str:
  1405. """The underlying text (explicit form of ``str(reply)``)."""
  1406. return str.__str__(self)
  1407. def merge_pending_message_event(pending_messages: dict[str, MessageEvent], session_key: str,
  1408. event: MessageEvent, *, merge_text: bool = False) -> None:
  1409. """Store or merge a pending event: photo bursts/albums merge into the queued event so the next
  1410. turn sees the whole burst; with ``merge_text`` rapid TEXT follow-ups append instead of
  1411. replace."""
  1412. existing = pending_messages.get(session_key)
  1413. if existing:
  1414. existing_type = getattr(existing, "message_type", None)
  1415. existing_is_photo = existing_type == MessageType.PHOTO
  1416. incoming_is_photo = event.message_type == MessageType.PHOTO
  1417. both_photo = existing_is_photo and incoming_is_photo
  1418. incoming_has_media = bool(event.media_urls)
  1419. def _padded_inline_flags(msg: MessageEvent) -> list[Optional[bool]]:
  1420. flags = list(getattr(msg, "media_text_inlined", []) or [])
  1421. return flags + [None] * (len(msg.media_urls) - len(flags))
  1422. incoming_inline_flags: list[Optional[bool]] = []
  1423. if incoming_has_media:
  1424. existing.media_text_inlined = _padded_inline_flags(existing)
  1425. incoming_inline_flags = _padded_inline_flags(event)
  1426. # A photo burst always absorbs; otherwise merge only when media is involved on either
  1427. # side. Captions merge in every absorbing case.
  1428. if both_photo or existing.media_urls or incoming_has_media:
  1429. if both_photo or incoming_has_media:
  1430. existing.extend_media(event)
  1431. existing.media_text_inlined.extend(incoming_inline_flags)
  1432. if event.text:
  1433. existing.text = BasePlatformAdapter._merge_caption(existing.text, event.text)
  1434. existing.absorb_reply_expected(event)
  1435. if existing_is_photo or incoming_is_photo:
  1436. existing.message_type = MessageType.PHOTO
  1437. elif existing_type == MessageType.TEXT and event.message_type != MessageType.TEXT:
  1438. existing.message_type = event.message_type
  1439. # Drop the *derived* STT cache (event changed); the echo ledger must survive or
  1440. # notes echo twice.
  1441. for attr in ("_gateway_pending_stt_text", "_gateway_pending_stt_transcripts"):
  1442. if hasattr(existing, attr):
  1443. delattr(existing, attr)
  1444. return
  1445. both_text = existing_type == MessageType.TEXT and event.message_type == MessageType.TEXT
  1446. if merge_text and both_text:
  1447. if event.text:
  1448. existing.text = _append_text(existing.text, event.text)
  1449. existing.absorb_reply_expected(event)
  1450. return
  1451. pending_messages[session_key] = event
  1452. # Transient *connection* failures worth retrying. Plain/read/write "timeout" excluded on purpose:
  1453. # the send may have reached the server (retry = duplicate); "connecttimeout" never connected.
  1454. _RETRYABLE_ERROR_PATTERNS = (
  1455. "connecterror", "connectionerror", "connectionreset", "connectionrefused", "connecttimeout",
  1456. "network", "broken pipe", "remotedisconnected", "eoferror")
  1457. # Handler result: str (reply), ``EphemeralReply`` (auto-delete) or None (already delivered).
  1458. MessageHandler = Callable[[MessageEvent], Awaitable[Optional[Union[str, "EphemeralReply"]]]]
  1459. def resolve_channel_prompt(config_extra: dict, channel_id: str, parent_id: str | None = None) -> str | None:
  1460. """Per-channel ephemeral prompt from ``config.extra["channel_prompts"]``: exact *channel_id*
  1461. first, then *parent_id* (threads inherit the parent prompt). Blank prompts count as absent."""
  1462. prompts = config_extra.get("channel_prompts") or {}
  1463. if not isinstance(prompts, dict):
  1464. return None
  1465. for key in (channel_id, parent_id):
  1466. prompt = prompts.get(key) if key else None
  1467. if prompt is not None and (prompt := str(prompt).strip()):
  1468. return prompt
  1469. return None
  1470. def resolve_channel_skills(
  1471. config_extra: dict, channel_id: str, parent_id: str | None = None) -> list[str] | None:
  1472. """Auto-loaded skill(s) for a channel/thread from ``channel_skill_bindings`` (entries
  1473. ``{id: "<channel/forum id>", skills: [...]}``; ``skill: "<name>"`` also accepted). Exact
  1474. *channel_id* first, then *parent_id* (threads inherit). Deduplicated ordered list or None."""
  1475. bindings = config_extra.get("channel_skill_bindings") or []
  1476. if not isinstance(bindings, list) or not bindings:
  1477. return None
  1478. # One pass per id, not one pass matching either: the parent's entry may be listed first.
  1479. for wanted in (str(key) for key in (channel_id, parent_id) if key):
  1480. for entry in bindings:
  1481. if not isinstance(entry, dict) or str(entry.get("id", "")) != wanted:
  1482. continue
  1483. skills = entry.get("skills") or entry.get("skill")
  1484. if isinstance(skills, str):
  1485. return [skills.strip()] if skills.strip() else None
  1486. if isinstance(skills, list) and skills:
  1487. seen = dict.fromkeys(
  1488. nm for name in skills if isinstance(name, str) and (nm := name.strip()))
  1489. return list(seen) or None
  1490. return None
  1491. def _split_post_delivery_entry(entry: Any) -> tuple[Optional[int], Any]:
  1492. """``(generation, callback)`` from a post-delivery slot; legacy bare callbacks have no
  1493. generation."""
  1494. return entry if isinstance(entry, tuple) and len(entry) == 2 else (None, entry)
  1495. def _lazy_attr(obj: Any, name: str, factory: Callable[[], Any]) -> Any:
  1496. """``getattr(obj, name)`` or create it via ``factory`` — the getattr-guard for
  1497. tests that build adapters via ``object.__new__`` and never run ``__init__``."""
  1498. value = getattr(obj, name, None)
  1499. if value is None:
  1500. value = factory()
  1501. setattr(obj, name, value)
  1502. return value
  1503. _strip_media_directives = _strip_media_tag_directives
  1504. class BasePlatformAdapter(ABC):
  1505. """Base class for platform adapters: connect/auth, receive, send, handle media."""
  1506. # ``format_message`` renders ``` fences as real code blocks (tool-progress then sends a bare
  1507. # fenced terminal command; plain-text platforms get the preview).
  1508. supports_code_blocks: bool = False
  1509. # Typing indicator renders TEXT (status line); the gateway then feeds set_status_text().
  1510. supports_status_text: bool = False
  1511. def set_status_text(self, chat_id: str, text: Optional[str]) -> None:
  1512. """Set or clear (``None``) the live working-state phrase for a chat. In-memory only: the
  1513. next typing refresh renders it; a no-op store on adapters that never read
  1514. ``_status_text``."""
  1515. store = _lazy_attr(self, "_status_text", dict)
  1516. if text:
  1517. store[str(chat_id)] = text
  1518. else:
  1519. store.pop(str(chat_id), None)
  1520. # Can wake a fresh turn AFTER a turn ends (detached-subagent completions); False for stateless
  1521. # adapters (API server). Propagated to ``HERMES_SESSION_ASYNC_DELIVERY`` so tools never promise
  1522. # a delivery they can't keep.
  1523. supports_async_delivery: bool = True
  1524. # ``send()`` chunks natively via ``truncate_message()`` -> the router skips its truncation.
  1525. splits_long_messages: bool = False
  1526. # Prefix users can always TYPE for Hermes commands ("!" where the client eats a leading "/").
  1527. typed_command_prefix: str = "/"
  1528. # ``in_channel`` continuable-cron surface: job delivered FLAT, plain replies continue it via
  1529. # the whole-channel bucket ``(platform, chat_id, None)``; needs a flat-reply outbound gate too
  1530. # (Slack ``reply_in_thread: false``). False fails SAFE -> ``thread``.
  1531. supports_inchannel_continuable: bool = False
  1532. # A human can answer "session restored — what next?"; webhook-style platforms set False so
  1533. # auto-resume finishes the work instead of asking nobody.
  1534. # The startup auto-resume turn (``_schedule_resume_pending_sessions`` → the ``_is_resume_pending``
  1535. # branch in ``_handle_message_with_agent``) reads this to pick its guidance: interactive platforms
  1536. # (Telegram, Slack, Discord DMs, …) get "report the restore and ask what the user wants next";
  1537. # non-interactive event platforms (webhook) get "finish the interrupted work" because nobody is there to
  1538. # answer, and an acknowledgement would silently abandon the task (#57056). Read generically via
  1539. # ``getattr(adapter, "interactive_resume", True)`` — no per-platform branching at the call site.
  1540. interactive_resume: bool = True
  1541. # Port-binding adapter that answers ``/p/<profile>/...`` for every served profile on the default
  1542. # listener under ``gateway.multiplex_profiles``. Declared per adapter (not in a central list) so
  1543. # ``hermes gateway migrate`` can tell "URL changes" from "this profile would be skipped" as new
  1544. # HTTP-inbound adapters gain the prefix.
  1545. serves_profile_prefix: bool = False
  1546. # Back-reference to the running ``GatewayRunner`` (set by gateway/run.py); ``build_source``
  1547. # resolves the inbound profile via ``runner._profile_name_for_source``.
  1548. gateway_runner = None # type: ignore[assignment]
  1549. def __init__(self, config: PlatformConfig, platform: Platform):
  1550. self.config = config
  1551. self.platform = platform
  1552. self._message_handler: Optional[MessageHandler] = None
  1553. self._no_message_handler_logged: bool = False
  1554. self._reaction_handler: Optional[Callable[[dict[str, Any]], Awaitable[None]]] = None
  1555. # Runner-owned boundary for normalized events: auth/profile state never lives in an adapter.
  1556. self._platform_event_handler: Optional[Callable[[dict[str, Any], Any], Awaitable[None]]] = None
  1557. # Rewrites ``event.source.thread_id`` before session keying (Telegram DM topics).
  1558. self._topic_recovery_fn: Optional[Callable[[Any], Optional[str]]] = None
  1559. self._running, self._fatal_error_retryable = False, True
  1560. self._fatal_error_code: Optional[str] = None
  1561. self._fatal_error_message: Optional[str] = None
  1562. self._fatal_error_handler: Optional[Callable[[BasePlatformAdapter], Awaitable[None] | None]] = None
  1563. # Strong refs to shielded fatal-error handler tasks that outlive their carrier task
  1564. # (asyncio keeps only weak refs); without them the loop can GC the detached handler
  1565. # mid-flight — the "handler killed mid-flight" class (#81335).
  1566. # See #81335.
  1567. self._detached_fatal_tasks: set = set()
  1568. # Lock takeover armed only for the initial connect of ``gateway run --replace``.
  1569. self._platform_lock_takeover_allowed = self._platform_lock_takeover_attempted = False
  1570. # Per-session interrupt Event + owner Task: without the owner map an old task's finally
  1571. # could drop a newer guard.
  1572. self._active_sessions: dict[str, asyncio.Event] = {}
  1573. self._pending_messages: dict[str, MessageEvent] = {}
  1574. # Consecutive in-band drains per session of the just-dispatched event bouncing straight
  1575. # back into the queue (session busy elsewhere); drives the drain back-off (#123229).
  1576. self._requeue_counts: dict[str, int] = {}
  1577. self._pending_text_batches: dict[str, MessageEvent] = {}
  1578. self._pending_text_batch_tasks: dict[str, asyncio.Task] = {}
  1579. self._session_tasks: dict[str, asyncio.Task] = {}
  1580. # Busy-text policy is a per-profile config decision the runner installs after construction
  1581. # (``_wire_adapter_handlers``); a constructor-time process-env read would freeze the launch
  1582. # profile's values into every profile's adapter under multiplexing (#116893). Defaults here
  1583. # only cover a pre-sync read so it never silently queues.
  1584. self._busy_text_mode: str = "interrupt"
  1585. self._busy_text_debounce_seconds: float = DEFAULT_BUSY_TEXT_DEBOUNCE_SECONDS
  1586. self._busy_text_hard_cap_seconds: float = DEFAULT_BUSY_TEXT_HARD_CAP_SECONDS
  1587. # ``human_delay`` pacing range in ms, or None (off); per-profile config installed by the
  1588. # runner, never process env (#116895).
  1589. self._human_delay_range_ms: Optional[tuple[int, int]] = None
  1590. self._text_debounce: dict[str, TextDebounceState] = {}
  1591. # handle_message() tasks; shutdown cancels them so a replaced gateway stops working.
  1592. self._background_tasks: set[asyncio.Task] = set()
  1593. # Post-delivery one-shots per session_key: bare callback (legacy) or ``(generation,
  1594. # callback)`` so a stale run can't clear a fresher run's callback.
  1595. self._post_delivery_callbacks: dict[str, Any] = {}
  1596. self._expected_cancelled_tasks: set[asyncio.Task] = set()
  1597. self._busy_session_handler: Optional[Callable[[MessageEvent, str], Awaitable[bool]]] = None
  1598. # Owning multiplex profile (None on primary); see _session_key_profile.
  1599. self._owner_profile: Optional[str] = None
  1600. # Set by the runner on a secondary's port-binding adapter: serve via the default profile's
  1601. # shared listener (/p/<profile>/...) instead of binding a port (gateway/platforms/shared_ingress.py).
  1602. self._shared_listener_profile: Optional[str] = None
  1603. # Registered by GatewayRunner (see set_authorization_check).
  1604. self._authorization_check: Optional[Callable[[str, Optional[str], Optional[str]], bool]] = None
  1605. # Auto-TTS on voice input: ``voice.auto_tts`` default plus per-chat /voice on|tts / off.
  1606. self._auto_tts_default: bool = False
  1607. self._auto_tts_enabled_chats, self._auto_tts_disabled_chats = set(), set()
  1608. # Turn keys where streaming TTS already delivered audio; whole-file auto-TTS skips them.
  1609. # When the gateway streaming-TTS consumer successfully delivers audio, it adds the turn key here so
  1610. # the base adapter's whole-file auto-TTS path skips the duplicate. Cleared after the turn completes.
  1611. # See #60671.
  1612. self._streaming_tts_completed_turns: set[str] = set()
  1613. # Chats whose typing indicator is paused (approval waits); _keep_typing skips them.
  1614. self._typing_paused: set = set()
  1615. # Per-chat status phrase; the regular _keep_typing refresh renders it (no extra API calls).
  1616. self._status_text: dict[str, str] = {}
  1617. @property
  1618. def message_len_fn(self) -> Callable[[str], int]:
  1619. """Length function for message size; override where the platform counts
  1620. differently from ``len`` (Telegram: UTF-16 code units)."""
  1621. return len
  1622. def max_message_length_for_chat(self, chat_id: str) -> int:
  1623. """Per-chat max length in ``message_len_fn_for_chat`` units: the adapter's
  1624. ``MAX_MESSAGE_LENGTH`` (4096 when absent); the relay adapter overrides since it fronts N
  1625. platforms with different caps."""
  1626. return _or_default(lambda: int(getattr(self, "MAX_MESSAGE_LENGTH", 4096) or 4096), 4096)
  1627. def message_len_fn_for_chat(self, chat_id: str) -> Callable[[str], int]:
  1628. """Per-chat length function (companion to max_message_length_for_chat); the relay
  1629. adapter overrides it per the chat's fronting platform."""
  1630. return self.message_len_fn
  1631. @property
  1632. def enforces_own_access_policy(self) -> bool:
  1633. """Whether this adapter enforces its own config-driven access policy at intake
  1634. (``dm_policy``/``group_policy``/``allow_from``: WeCom, Weixin, QQBot, WhatsApp…). The
  1635. gateway env allowlist runs *after* the adapter; without one it trusts this flag ONLY when
  1636. the effective policy is a real ``"allowlist"`` — never ``"open"`` (the default), which would
  1637. be a network-exposed fail-open (SECURITY.md §2.6). Open access still requires
  1638. ``{PLATFORM}_ALLOW_ALL_USERS`` / ``GATEWAY_ALLOW_ALL_USERS``."""
  1639. return False
  1640. @property
  1641. def authorization_is_upstream(self) -> bool:
  1642. """Whether inbound was already authorized by a TRUSTED UPSTREAM (relay only): the Team
  1643. Gateway connector authenticates the WebSocket and resolves owner-only author binding BEFORE
  1644. delivery, so the no-allowlist default-deny would be wrong. Authorization DELEGATED, not
  1645. ABSENT — every network-exposed direct adapter leaves it False."""
  1646. return False
  1647. def supports_draft_streaming(
  1648. self, chat_type: Optional[str] = None, metadata: Optional[dict[str, Any]] = None,
  1649. chat_id: Optional[str] = None) -> bool:
  1650. """Whether native streaming-draft updates (``send_draft``) work for this chat type;
  1651. ``chat_id`` lets the relay adapter answer per negotiated capabilities. Consumers
  1652. fall back to ``send`` + ``edit_message`` when False or ``send_draft`` raises."""
  1653. return False
  1654. def prefers_fresh_final_streaming(self, content: str, metadata: Optional[dict[str, Any]] = None) -> bool:
  1655. """Whether the stream consumer should finalize with a *fresh* final message (best-effort
  1656. deleting the preview) instead of final-editing it (Telegram: keeps rich rendering)."""
  1657. return False
  1658. def streaming_overflow_limit(self) -> Optional[int]:
  1659. """Max single-message length (``message_len_fn`` units) the stream consumer may
  1660. accumulate before splitting, for rich send/draft paths exceeding the legacy cap
  1661. (Telegram Rich Messages: 32,768 vs 4,096). ``None`` = use ``MAX_MESSAGE_LENGTH``."""
  1662. return None
  1663. async def send_draft(self, chat_id: str, draft_id: int, content: str,
  1664. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  1665. """Send or update an animated streaming-draft preview. Reuse one non-zero ``draft_id``
  1666. across a response so the platform animates (different responses need different ids). Drafts
  1667. have no message_id (no edit/reply/delete) — the final answer goes out as a regular ``send``.
  1668. Must be overridden by adapters returning True from :meth:`supports_draft_streaming`."""
  1669. raise NotImplementedError(f"{type(self).__name__} does not implement send_draft")
  1670. # ── Structured stream-event rendering (gateway/stream_events.py): presentation-only,
  1671. # nothing rendered here is persisted, so what an adapter "eats" never changes history.
  1672. def render_message_event(self, event: Any, sink: Any) -> None:
  1673. """Render a MessageChunk / MessageStop / Commentary onto the sink (a
  1674. GatewayStreamConsumer), mapping 1:1 onto its existing primitives."""
  1675. from gateway.stream_events import MessageChunk, MessageStop, Commentary
  1676. if isinstance(event, MessageChunk) and event.text:
  1677. sink.on_delta(event.text)
  1678. elif isinstance(event, MessageStop) and not event.final:
  1679. # Intermediate stop (text → tool → text) = segment break; the terminal stop is finish().
  1680. sink.on_segment_break()
  1681. elif isinstance(event, Commentary) and event.text:
  1682. sink.on_commentary(event.text)
  1683. def format_tool_event(self, event: Any, *, mode: str = "all", preview_max_len: int = 40) -> Optional[str]:
  1684. """Rendered chrome for a ToolCallChunk, or None to eat it (adapters without editing/rich
  1685. text override to None). ``mode``: tool-progress mode ("all"/"new"/"verbose");
  1686. ``preview_max_len`` mirrors ``tool_preview_length`` (0 = no cap in verbose)."""
  1687. from gateway.stream_events import ToolCallChunk
  1688. if not isinstance(event, ToolCallChunk):
  1689. return None
  1690. from agent.display import get_tool_emoji, prepare_tool_preview, verbose_tool_args_text
  1691. emoji, tool = get_tool_emoji(event.tool_name, default='⚙️'), event.tool_name
  1692. if mode == "verbose" and event.args:
  1693. args_str = verbose_tool_args_text(event.args, preview_max_len, self.supports_code_blocks)
  1694. return t("gateway.progress.tool_verbose", emoji=emoji, tool=tool, keys=list(event.args.keys()), args=args_str)
  1695. if not event.preview:
  1696. return t("gateway.progress.tool_pending", emoji=emoji, tool=tool)
  1697. if mode == "verbose":
  1698. return t("gateway.progress.tool_preview", emoji=emoji, tool=tool, preview=event.preview)
  1699. # "all" / "new": short capped preview (default 40; progress bubbles persist as messages).
  1700. cap = preview_max_len if preview_max_len > 0 else 40
  1701. prepared = prepare_tool_preview(
  1702. event.tool_name, event.args, fallback=event.preview, max_len=cap)
  1703. return t("gateway.progress.tool_preview", emoji=emoji, tool=tool, preview=self.format_tool_preview(prepared))
  1704. def format_tool_preview(self, preview: "ToolPreview") -> str:
  1705. """Platform-native formatting of a compact tool preview; rich-text adapters may use
  1706. the preview's metadata (e.g. a URL shortened for display)."""
  1707. return preview.text
  1708. has_fatal_error = property(lambda self: self._fatal_error_message is not None)
  1709. fatal_error_message = property(lambda self: self._fatal_error_message)
  1710. fatal_error_code = property(lambda self: self._fatal_error_code)
  1711. fatal_error_retryable = property(lambda self: self._fatal_error_retryable)
  1712. def _should_auto_tts_for_chat(self, chat_id: str) -> bool:
  1713. """Whether auto-TTS fires for ``chat_id``: explicit ``/voice on|tts`` wins,
  1714. then explicit ``/voice off``, then the global ``voice.auto_tts`` default.
  1715. Decision layers (Issue #16007): 1. Explicit ``/voice on`` or ``/voice tts`` → always fire (even if
  1716. ``voice.auto_tts`` is False). 2. 3.
  1717. """
  1718. return chat_id in self._auto_tts_enabled_chats or (
  1719. chat_id not in self._auto_tts_disabled_chats and bool(self._auto_tts_default))
  1720. def set_fatal_error_handler(self, handler: "Callable[[BasePlatformAdapter], Awaitable[None] | None]") -> None:
  1721. self._fatal_error_handler = handler
  1722. #: Published when an adapter is installed and running but its receive
  1723. #: path is not yet confirmed (e.g. Telegram polling has not proven a
  1724. #: getUpdates round-trip). Same ``retrying`` platform_state the runner
  1725. #: uses for queued reconnects, so readers see "not delivering" (#101391).
  1726. DEGRADED_STATUS_MESSAGE = "connected but not yet confirmed active; recovering in background"
  1727. @property
  1728. def send_path_degraded(self) -> bool:
  1729. """True while connect() succeeded but delivery is not confirmed.
  1730. Adapters with a separately-proven receive path override this; the
  1731. default adapter is either connected or not.
  1732. """
  1733. return False
  1734. def _mark_connected(self, *, listener_base: Optional[str] = None) -> None:
  1735. """``listener_base`` (``http://host:port``) is stamped by port-binders after a REAL bind: under the
  1736. multiplexer it is the shared listener a served profile's ``/p/<profile>/`` mirror hangs off, and
  1737. what the dashboard/Desktop report as that profile's api_server/webhook URL."""
  1738. self._running = True
  1739. self._fatal_error_code = self._fatal_error_message = None
  1740. self._fatal_error_retryable = True
  1741. if self.send_path_degraded:
  1742. self._mark_degraded()
  1743. else:
  1744. extra = {"listener_base": listener_base} if listener_base else {}
  1745. self._write_runtime_status_safe(
  1746. "connected", platform_state="connected", error_code=None, error_message=None, **extra)
  1747. def _mark_degraded(self) -> None:
  1748. """Publish ``retrying`` for a running adapter whose delivery path is unproven."""
  1749. self._write_runtime_status_safe(
  1750. "connected_degraded",
  1751. platform_state="retrying",
  1752. error_code=None,
  1753. error_message=self.DEGRADED_STATUS_MESSAGE,
  1754. )
  1755. def _mark_disconnected(self) -> None:
  1756. self._running = False
  1757. if not self.has_fatal_error:
  1758. self._write_runtime_status_safe(
  1759. "disconnected", platform_state="disconnected", error_code=None, error_message=None)
  1760. def _set_fatal_error(self, code: str, message: str, *, retryable: bool) -> None:
  1761. self._running = False
  1762. self._fatal_error_code, self._fatal_error_message = code, message
  1763. self._fatal_error_retryable = retryable
  1764. self._write_runtime_status_safe("fatal", platform_state="fatal", error_code=code, error_message=message)
  1765. def _write_runtime_status_safe(self, context: str, **kwargs) -> None:
  1766. """Publish runtime status; log preparation failures without disrupting the adapter."""
  1767. try:
  1768. from gateway.status import publish_runtime_status
  1769. # Multiplexed adapters share the status file; the runner stamps
  1770. # ``<profile>:<platform>``.
  1771. platform_key = getattr(self, "_runtime_status_platform_key", None) or self.platform.value
  1772. publish_runtime_status(platform=platform_key, **kwargs)
  1773. except Exception as exc:
  1774. logged = _lazy_attr(self, "_status_write_logged", set) # object.__new__ in tests
  1775. first = (self.platform.value, context) not in logged
  1776. logged.add((self.platform.value, context))
  1777. (logger.warning if first else logger.debug)(
  1778. "Failed to write runtime status (%s) for %s: %s" + (" (further failures at debug level)" if first else ""),
  1779. context, self.platform.value, exc)
  1780. async def _notify_fatal_error(self) -> None:
  1781. handler = self._fatal_error_handler
  1782. if not handler:
  1783. return
  1784. result = handler(self)
  1785. if asyncio.iscoroutine(result):
  1786. # Detached + shielded: often awaited from an adapter-owned task (e.g. Telegram
  1787. # ``_polling_error_task``) that the gateway fatal handler's ``disconnect()``
  1788. # cancels; unshielded, the handler died mid-flight — adapter popped from the
  1789. # gateway map but never queued for background reconnect, leaving a zombie
  1790. # gateway with no platforms and no pending retries (#81335).
  1791. # See #81335.
  1792. task = asyncio.ensure_future(result)
  1793. # Strong ref: asyncio only keeps weak refs to tasks ("save a reference ... to
  1794. # avoid a task disappearing mid-execution"); matches
  1795. # GatewayRunner._handle_adapter_fatal_error.
  1796. _tasks = _lazy_attr(self, "_detached_fatal_tasks", set)
  1797. _tasks.add(task)
  1798. task.add_done_callback(_tasks.discard)
  1799. try:
  1800. await asyncio.shield(task)
  1801. except asyncio.CancelledError:
  1802. # Carrier cancelled (our own teardown inside the handler): let it finish detached.
  1803. if not task.done():
  1804. task.add_done_callback(_consume_detached_handler_exception)
  1805. raise
  1806. def _acquire_platform_lock(self, scope: str, identity: str, resource_desc: str) -> bool:
  1807. """Acquire a scoped lock for this adapter; True on success. A live cross-HERMES_HOME
  1808. holder is replaced only when the runner armed this adapter for its initial
  1809. ``--replace`` connect (the status module validates ownership and terminates)."""
  1810. from gateway.status import acquire_scoped_lock, scoped_lock_owner_label, take_over_scoped_lock_holder
  1811. from gateway.status_lock_dir import ScopedLockDirUnusable
  1812. self._platform_lock_scope, self._platform_lock_identity = scope, identity
  1813. lock_meta = {"platform": self.platform.value}
  1814. try:
  1815. acquired, existing = acquire_scoped_lock(scope, identity, metadata=lock_meta)
  1816. except ScopedLockDirUnusable as exc:
  1817. # An ACL an elevated install left on the lock dir (#134889 W2): name the repair. Stay
  1818. # RETRYABLE: the dir is shared by every token-locked adapter, so a non-retryable park
  1819. # on a gateway that runs only those exits 78 and takes cron and the Desktop attach
  1820. # endpoint down with it. The status module logs the WARNING once per dir (DEBUG after),
  1821. # so the watcher's backoff retries quietly and picks the repair up without a restart.
  1822. self._platform_lock_identity = None
  1823. self._set_fatal_error(
  1824. "lock_dir_unusable",
  1825. f"{resource_desc} lock cannot be taken: the gateway lock directory {exc.filename} is not "
  1826. f"usable by this user (likely created by an elevated Hermes). To repair, "
  1827. f"{unusable_dir_remedy(exc.filename)}; the gateway retries on its own.",
  1828. retryable=True)
  1829. return False
  1830. if acquired:
  1831. return True
  1832. if (self._platform_lock_takeover_allowed and not self._platform_lock_takeover_attempted
  1833. and isinstance(existing, dict)):
  1834. # Consume the authority before any I/O: at most one termination attempt per connect.
  1835. self._platform_lock_takeover_allowed = False
  1836. self._platform_lock_takeover_attempted = True
  1837. owner_pid = take_over_scoped_lock_holder(existing)
  1838. if owner_pid is not None:
  1839. logger.warning(
  1840. "[%s] %s was held by gateway PID %d — explicit --replace handoff completed",
  1841. self.name, resource_desc, owner_pid)
  1842. acquired, existing = acquire_scoped_lock(scope, identity, metadata=lock_meta)
  1843. if acquired:
  1844. logger.info("[%s] Acquired %s after taking over PID %d", self.name, resource_desc, owner_pid)
  1845. return True
  1846. owner_pid = existing.get('pid') if isinstance(existing, dict) else None
  1847. # Scoped locks are machine-global: name the owning profile so the operator knows WHICH
  1848. # gateway.
  1849. owner_profile = scoped_lock_owner_label(existing)
  1850. pid_part = f" (PID {owner_pid})" if owner_pid else ""
  1851. holder = f" by the '{owner_profile}' profile gateway{pid_part}" if owner_profile else pid_part
  1852. remedy = (f" Stop that gateway first (hermes --profile {owner_profile} gateway stop)."
  1853. if owner_profile else " Stop the other gateway first.")
  1854. message = f"{resource_desc} already in use{holder}.{remedy}"
  1855. logger.error('[%s] %s', self.name, message)
  1856. self._set_fatal_error(f'{scope}_lock', message, retryable=True)
  1857. return False
  1858. def _release_platform_lock(self) -> None:
  1859. """Release the scoped lock acquired by _acquire_platform_lock."""
  1860. identity = getattr(self, '_platform_lock_identity', None)
  1861. if not identity:
  1862. return
  1863. from gateway.status_scoped_locks import release_scoped_lock
  1864. release_scoped_lock(self._platform_lock_scope, identity)
  1865. self._platform_lock_identity = None
  1866. # Plugin handler factories wired on the live native client: ``(plugin, qualname)`` keys, reset when
  1867. # the native client is rebuilt. ``None`` = ``connect()`` has not wired yet (class defaults so
  1868. # subclasses that skip ``super().__init__`` still re-wire safely).
  1869. _plugin_handler_native: Any = None
  1870. _plugin_handlers_wired: Optional[set] = None
  1871. def _wire_plugin_handlers(self, native: Any = None) -> None:
  1872. """Invoke plugin-registered native handler factories (``ctx.register_platform_handler``)
  1873. with ``(native, adapter)``; adapters call this from ``connect()`` once the native
  1874. client exists and :meth:`rewire_plugin_handlers` re-runs it for plugins loaded later.
  1875. Idempotent per native client: a factory is keyed by ``(plugin, qualname)`` and skipped once
  1876. wired on this ``native`` (a force re-discovery hands back NEW function objects for the same
  1877. plugin, so identity alone would double-register). Each factory is isolated so a bad plugin
  1878. can't block connecting."""
  1879. try:
  1880. from hermes_cli.plugins import get_plugin_manager
  1881. factories = get_plugin_manager().get_platform_handler_factories(
  1882. getattr(self.platform, "value", str(self.platform)))
  1883. except Exception as e: # pragma: no cover - defensive
  1884. logger.warning("[%s] Could not load plugin handler factories: %s", self.name, e)
  1885. return
  1886. if self._plugin_handler_native is not native or self._plugin_handlers_wired is None:
  1887. # A rebuilt native client (transient-init rebuild, reconnect) starts with nothing wired.
  1888. self._plugin_handler_native = native
  1889. self._plugin_handlers_wired = set()
  1890. for factory, plugin_name in factories:
  1891. key = (plugin_name, getattr(factory, "__qualname__", None) or repr(factory))
  1892. if key in self._plugin_handlers_wired:
  1893. continue
  1894. try:
  1895. factory(native, self)
  1896. logger.info("[%s] Wired native handlers from plugin '%s'", self.name, plugin_name)
  1897. except Exception as exc:
  1898. logger.error("[%s] Plugin '%s' handler factory raised: %s", self.name, plugin_name,
  1899. exc, exc_info=True)
  1900. # A raising factory is recorded too: re-wire must not re-raise it on every plugin load.
  1901. self._plugin_handlers_wired.add(key)
  1902. def rewire_plugin_handlers(self) -> None:
  1903. """Register handlers of plugins loaded AFTER ``connect()`` wired the first batch (#87770);
  1904. the gateway runner calls this on every plugin-loaded event. Safe to call repeatedly: only
  1905. factories not yet wired on the live native client run. Before ``connect()`` has wired once
  1906. there is nothing to re-wire — connect will pick everything up. Adapters with extra plugin
  1907. registries (Slack action handlers) extend this."""
  1908. if self._plugin_handlers_wired is None:
  1909. return
  1910. self._wire_plugin_handlers(self._plugin_handler_native)
  1911. @property
  1912. def name(self) -> str:
  1913. """Human-readable name for this adapter."""
  1914. return self.platform.value.title()
  1915. @property
  1916. def is_connected(self) -> bool:
  1917. """Check if adapter is currently connected."""
  1918. return self._running
  1919. def set_message_handler(self, handler: MessageHandler) -> None:
  1920. """Set the incoming-message handler (MessageEvent -> optional response str)."""
  1921. self._message_handler = handler
  1922. def set_platform_event_handler(
  1923. self, handler: Optional[Callable[[dict[str, Any], Any], Awaitable[None]]]) -> None:
  1924. """Install the gateway-owned normalized platform-event boundary (stable dicts + internal
  1925. ``SessionSource``); the runner owns authorization and plugin dispatch: no callback = fail
  1926. closed."""
  1927. self._platform_event_handler = handler
  1928. def set_topic_recovery_fn(self, fn: Optional[Callable[[Any], Optional[str]]]) -> None:
  1929. """Install a thread_id-recovery hook (Telegram DM topic mode): called with ``event.source``
  1930. before session keying; a non-None return replaces ``source.thread_id``. ``None`` clears
  1931. it."""
  1932. self._topic_recovery_fn = fn
  1933. def _apply_topic_recovery(self, event: MessageEvent) -> None:
  1934. """Rewrite ``event.source.thread_id`` in place if the hook returns one."""
  1935. recover = getattr(self, "_topic_recovery_fn", None)
  1936. source = getattr(event, "source", None)
  1937. if recover is None or source is None:
  1938. return
  1939. try:
  1940. recovered = recover(source)
  1941. if recovered is None or str(recovered) == str(source.thread_id or ""):
  1942. return
  1943. except Exception:
  1944. logger.debug("topic recovery hook failed", exc_info=True)
  1945. return
  1946. try:
  1947. from gateway.session_identity import replace_source
  1948. event.source = replace_source(source, thread_id=str(recovered)) # keeps the pinned identity
  1949. except Exception:
  1950. logger.debug("topic recovery rewrite failed", exc_info=True)
  1951. def set_busy_session_handler(self, handler: Optional[Callable[[MessageEvent, str], Awaitable[bool]]]) -> None:
  1952. """Set an optional handler for messages arriving during active sessions."""
  1953. self._busy_session_handler = handler
  1954. def set_reaction_handler(self, handler: Optional[Callable[[dict[str, Any]], Awaitable[None]]]) -> None:
  1955. """Set the handler for platform-native emoji-reaction events: a normalised dict
  1956. (``platform``, ``event_name`` "reaction:added"/"reaction:removed", ``reaction``,
  1957. ``user_id``, ``item_user_id``, ``channel_id``, ``message_ts``, ``event_ts``, ``raw_event``)
  1958. fanned out via ``HookRegistry.emit``."""
  1959. self._reaction_handler = handler
  1960. def set_authorization_check(
  1961. self, callback: Optional[Callable[[str, Optional[str], Optional[str]], bool]]) -> None:
  1962. """Register ``(user_id, chat_type, chat_id) -> bool``; adapters pulling external context
  1963. (Slack thread replies) use it to flag non-allowlisted senders as unverified background."""
  1964. self._authorization_check = callback
  1965. def _is_sender_authorized(self, user_id: Optional[str], chat_type: Optional[str] = None,
  1966. chat_id: Optional[str] = None, *, is_bot: bool = False,
  1967. thread_id: Optional[str] = None) -> Optional[bool]:
  1968. """True/False from the registered check, or None when no check exists ("trust unknown",
  1969. legacy). ``is_bot``/``thread_id`` are forwarded as keywords only when set so legacy
  1970. three-positional callbacks keep working. Only literal booleans propagate: a truthy
  1971. non-boolean is "unknown", never an authorization that gates a credentialed side effect."""
  1972. if not user_id or self._authorization_check is None:
  1973. return None
  1974. extra: dict[str, Any] = {}
  1975. if is_bot:
  1976. extra["is_bot"] = True
  1977. if thread_id is not None:
  1978. extra["thread_id"] = thread_id
  1979. try:
  1980. result = self._authorization_check(user_id, chat_type, chat_id, **extra)
  1981. except Exception:
  1982. logger.warning("[%s] Authorization check raised for user %s; treating as unknown",
  1983. self.name, user_id, exc_info=True)
  1984. return None
  1985. if result is True or result is False:
  1986. return result
  1987. logger.warning("[%s] Authorization check returned %s for user %s; treating as unknown",
  1988. self.name, type(result).__name__, user_id)
  1989. return None
  1990. def set_session_store(self, session_store: Any) -> None:
  1991. """Set the session store (e.g. Slack checks for an active thread session
  1992. before handling un-mentioned replies)."""
  1993. self._session_store = session_store
  1994. def set_owner_profile(self, profile_name: Optional[str]) -> None:
  1995. """Declare the owning multiplex profile (secondary profiles only); read by
  1996. :meth:`_session_key_profile` so adapter-level keys leave ``agent:main:``."""
  1997. self._owner_profile = None if (name := (profile_name or "").strip() or None) == "default" else name
  1998. def _owner_transport_profile(self) -> Optional[str]:
  1999. """Transport profile for :func:`resolve_identity`: the owner name, or ``None`` = derive it
  2000. from the registry (the primary's identity then spells ``"default"`` out itself)."""
  2001. owner = getattr(self, "_owner_profile", None)
  2002. return owner if isinstance(owner, str) and owner.strip() else None
  2003. def _canonicalize(self, source: Optional[SessionSource]):
  2004. """Pin the source's :class:`RoutingIdentity` before anything derives a key from it. Every
  2005. ingress path (fresh event, batch merge, busy path, control command, callback) calls this
  2006. FIRST. Returns the identity, or ``None`` when it cannot be resolved (a rejected route under
  2007. multiplexing marks ``source.profile_route_rejected``; ``_drop_unresolved`` reads it) or when
  2008. no runner seam exists (hand-built adapters, restored sources: the legacy readers stay)."""
  2009. if source is None:
  2010. return None
  2011. from gateway.session_identity import canonical_identity, identity_of
  2012. identity = identity_of(source)
  2013. if identity is not None:
  2014. return identity
  2015. runner = getattr(self, "gateway_runner", None)
  2016. if runner is None or not callable(getattr(runner, "_transport_owner", None)):
  2017. return None
  2018. try:
  2019. return canonical_identity(
  2020. source, runner=runner, adapter=self, transport_profile=self._owner_transport_profile())
  2021. except Exception:
  2022. # Duck-typed runners (SimpleNamespace / MagicMock rigs) have no registry to resolve
  2023. # against; the key then falls back to the pre-identity readers instead of failing ingress.
  2024. logger.debug("[%s] identity resolution failed; using legacy key readers", self.name, exc_info=True)
  2025. return None
  2026. def _drop_unresolved(self, event: MessageEvent) -> bool:
  2027. """True when *event* must be dropped: its identity could not be resolved because the route
  2028. targets an unserved profile. Same disposition as the runner's ingress gate — one WARNING,
  2029. never a fall-through to ``agent:main``."""
  2030. source = getattr(event, "source", None)
  2031. if self._canonicalize(source) is not None:
  2032. return False
  2033. if getattr(source, "profile_route_rejected", False) is not True:
  2034. return False
  2035. from gateway.parked_route_refusal import drop_rejected_route
  2036. drop_rejected_route(self, source) # one WARNING; a parked target is also refused to the sender
  2037. return True
  2038. def _session_key_profile(self, source: Optional[Any] = None) -> Optional[str]:
  2039. """Profile namespace for an adapter-derived session key. Ingress runs BEFORE the runner
  2040. stamps ``source.profile``, so without this every bot in a multiplexed gateway shares one
  2041. ``agent:main:`` lane. Order: pinned ``RoutingIdentity`` → ``source.profile`` →
  2042. ``_owner_profile`` → session-store resolver; getattr-guarded (object.__new__ in tests),
  2043. type-checked (no MagicMock in the key)."""
  2044. from gateway.session_identity import identity_of
  2045. identity = identity_of(source)
  2046. if identity is not None:
  2047. return identity.session_key_profile
  2048. for candidate in (
  2049. getattr(source, "profile", None) if source is not None else None,
  2050. getattr(self, "_owner_profile", None)):
  2051. if isinstance(candidate, str) and candidate.strip():
  2052. return candidate
  2053. store = getattr(self, "_session_store", None)
  2054. resolver = getattr(store, "_resolve_profile_for_key", None) if store else None
  2055. if not callable(resolver):
  2056. return None
  2057. try:
  2058. resolved = resolver(source)
  2059. except Exception:
  2060. return None
  2061. return resolved if isinstance(resolved, str) and resolved.strip() else None
  2062. # ── Inbound text batching. Chat clients split one long message into several inbound
  2063. # chunks; ``_enqueue_text_event`` merges chunks per session key and ``_flush_text_batch``
  2064. # dispatches after a quiet period (longer when the last chunk sits near the platform's
  2065. # split point, i.e. a continuation is almost certain). Adapters set the delay attrs and
  2066. # ``_SPLIT_THRESHOLD``; ``_text_batch_delay_for`` / ``_pop_text_batch`` /
  2067. # ``_dispatch_text_batch`` are the override seams for platform-specific policy.
  2068. _SPLIT_THRESHOLD: int = 4000
  2069. _text_batch_delay_seconds: float = 0.0
  2070. _text_batch_split_delay_seconds: float = 0.0
  2071. # Shared cadence for adapters that batch: a quiet period long enough to merge a client-side
  2072. # split (Telegram's measured envelope), short enough that a single short message is not
  2073. # visibly delayed (#44883). Ceilings bound a misconfigured value fed to asyncio.sleep().
  2074. _TEXT_BATCH_DEFAULT_DELAY_S: float = 0.3
  2075. _TEXT_BATCH_MAX_DELAY_S: float = 2.0
  2076. _TEXT_BATCH_DEFAULT_SPLIT_DELAY_S: float = 1.0
  2077. _TEXT_BATCH_MAX_SPLIT_DELAY_S: float = 4.0
  2078. def _coerce_float_extra(self, key: str, default: float, *, min_value: float = 0.0, max_value: Optional[float] = None) -> float:
  2079. """Float from ``config.extra``; NaN/Inf/negative/unparseable → ``default``; clamped to ``[min_value, max_value]``."""
  2080. extra = getattr(self.config, "extra", None) or {}
  2081. try: # float(None) → TypeError → default
  2082. parsed = float(extra.get(key))
  2083. except (TypeError, ValueError):
  2084. parsed = float(default)
  2085. if not math.isfinite(parsed) or parsed < 0:
  2086. parsed = float(default)
  2087. parsed = max(parsed, min_value)
  2088. if max_value is not None and parsed > max_value:
  2089. logger.warning("%s=%s exceeds the %s ceiling; clamped", key, parsed, max_value)
  2090. parsed = max_value
  2091. return parsed
  2092. def _configure_text_batch_delays(self) -> None:
  2093. """Read ``text_batch_delay_seconds`` / ``text_batch_split_delay_seconds`` from ``config.extra`` at the shared cadence."""
  2094. self._text_batch_delay_seconds = self._coerce_float_extra(
  2095. "text_batch_delay_seconds", self._TEXT_BATCH_DEFAULT_DELAY_S, max_value=self._TEXT_BATCH_MAX_DELAY_S)
  2096. self._text_batch_split_delay_seconds = self._coerce_float_extra(
  2097. "text_batch_split_delay_seconds", self._TEXT_BATCH_DEFAULT_SPLIT_DELAY_S,
  2098. min_value=self._text_batch_delay_seconds, max_value=self._TEXT_BATCH_MAX_SPLIT_DELAY_S)
  2099. def _event_session_key(self, event: MessageEvent) -> str:
  2100. """Adapter-level session key for ``event``, profile-namespaced like the agent run."""
  2101. return self._source_session_key(event.source)
  2102. def _source_session_key(self, source: SessionSource) -> str:
  2103. self._canonicalize(source) # identity FIRST; no key derivation before it
  2104. extra = self.config.extra
  2105. return build_session_key(
  2106. source, group_sessions_per_user=extra.get("group_sessions_per_user", True),
  2107. thread_sessions_per_user=extra.get("thread_sessions_per_user", False),
  2108. profile=self._session_key_profile(source))
  2109. def _text_batch_key(self, event: MessageEvent) -> str:
  2110. """Session-scoped key for text batching (subclasses may override)."""
  2111. return self._event_session_key(event)
  2112. def _enqueue_text_event(self, event: MessageEvent) -> None:
  2113. """Buffer a text event (merging into a pending one) and restart the flush timer."""
  2114. if self._drop_unresolved(event):
  2115. return
  2116. key = self._text_batch_key(event)
  2117. existing = self._pending_text_batches.get(key)
  2118. if existing is None:
  2119. existing = self._pending_text_batches[key] = event
  2120. else:
  2121. if event.text:
  2122. existing.text = _append_text(existing.text, event.text)
  2123. if event.media_urls:
  2124. existing.extend_media(event)
  2125. existing.absorb_reply_expected(event)
  2126. existing._last_chunk_len = len(event.text or "") # type: ignore[attr-defined]
  2127. prior_task = self._pending_text_batch_tasks.get(key)
  2128. if prior_task and not prior_task.done():
  2129. prior_task.cancel()
  2130. self._pending_text_batch_tasks[key] = asyncio.create_task(self._flush_text_batch(key))
  2131. def _text_batch_delay_for(self, pending: Optional[MessageEvent]) -> float:
  2132. """Quiet period before ``pending`` is dispatched; near-split chunks wait longer."""
  2133. last_len = getattr(pending, "_last_chunk_len", 0) if pending is not None else 0
  2134. return self._text_batch_split_delay_seconds if last_len >= self._SPLIT_THRESHOLD else self._text_batch_delay_seconds
  2135. def _pop_text_batch(self, key: str) -> Optional[MessageEvent]:
  2136. """Remove and return the pending batch for ``key`` (adapters with side tables override)."""
  2137. return self._pending_text_batches.pop(key, None)
  2138. async def _dispatch_text_batch(self, event: MessageEvent) -> None:
  2139. """Hand a flushed batch to the pipeline (adapters with per-chat guards override)."""
  2140. await self.handle_message(event)
  2141. async def _flush_text_batch_now(self, key: str) -> None:
  2142. """Dispatch the pending batch for ``key`` immediately (no quiet period)."""
  2143. event = self._pop_text_batch(key)
  2144. if event is not None:
  2145. await self._dispatch_text_batch(event)
  2146. async def _flush_text_batch(self, key: str) -> None:
  2147. """Wait for the quiet period, then dispatch the batch for ``key``.
  2148. Two races share this body. (1) ``_enqueue_text_event`` cancels the prior flush task
  2149. on each new chunk; when ``Task.cancel()`` lands after ``sleep()`` already completed,
  2150. CancelledError is delivered at the *next* await — after a superseded task would have
  2151. popped the event, so the successor finds nothing and the message is lost. The identity
  2152. check therefore runs synchronously between the sleep and the pop. (2) A cancel that
  2153. lands while the dispatch is in flight would abort the agent turn (#12444), so the
  2154. dispatch is shielded and the outer CancelledError swallowed."""
  2155. current_task = asyncio.current_task()
  2156. try:
  2157. await asyncio.sleep(self._text_batch_delay_for(self._pending_text_batches.get(key)))
  2158. owner = self._pending_text_batch_tasks.get(key)
  2159. if owner is not None and owner is not current_task:
  2160. return
  2161. event = self._pop_text_batch(key)
  2162. if event is None:
  2163. return
  2164. logger.info("[%s] Flushing text batch %s (%d chars)", self.name, key, len(event.text or ""))
  2165. await asyncio.shield(self._dispatch_text_batch(event))
  2166. except asyncio.CancelledError:
  2167. pass
  2168. finally:
  2169. if self._pending_text_batch_tasks.get(key) is current_task:
  2170. self._pending_text_batch_tasks.pop(key, None)
  2171. def _history_media_paths_for_session(self, session_key: str) -> Optional[set]:
  2172. """Return media paths already delivered in prior turns of this session
  2173. (MEDIA: tags / image_generate payloads), so an echoed old tag isn't re-sent."""
  2174. store = getattr(self, "_session_store", None)
  2175. if not store:
  2176. return None
  2177. try:
  2178. # Transcripts are keyed by session_id; map via the routing index, else the raw key.
  2179. peek = getattr(store, "peek_session_id", None)
  2180. session_id = peek(session_key) if callable(peek) else None
  2181. transcript = store.load_transcript(session_id or session_key)
  2182. except TranscriptReadError:
  2183. logger.warning(
  2184. "Transcript read failed for session %s; media dedup runs "
  2185. "with no history this turn (#100788)", session_key,
  2186. )
  2187. return None
  2188. except Exception:
  2189. return None
  2190. if not transcript:
  2191. return None
  2192. # Exclude the CURRENT TURN (from the last user message on): rows persist as produced, so a
  2193. # text_to_speech media_tag would otherwise dedup away its own attachment.
  2194. history = list(transcript)
  2195. last_user_idx = next(
  2196. (i for i in range(len(history) - 1, -1, -1) if history[i].get("role") == "user"), None)
  2197. if last_user_idx is not None:
  2198. history = history[:last_user_idx]
  2199. else:
  2200. # No user row (unusual store shape): at least drop the trailing reply.
  2201. last_reply = next((msg for msg in reversed(history) if msg.get("role") == "assistant"), None)
  2202. if last_reply is not None:
  2203. history.remove(last_reply)
  2204. if not history:
  2205. return None
  2206. from gateway.run import _collect_history_media_paths # lazy: gateway.run imports us
  2207. return _collect_history_media_paths(history)
  2208. async def _bounded_history_media_paths_for_session(self, session_key: str) -> Optional[set]:
  2209. """Run best-effort history lookup in a bounded isolated daemon thread."""
  2210. def _fail_open(reason: str, *, exc_info: bool = False) -> None:
  2211. logger.warning(
  2212. "[%s] " + reason + " %s; delivering bare local file path(s) without history dedup",
  2213. self.name, session_key, exc_info=exc_info)
  2214. admission = _HISTORY_MEDIA_LOOKUP_ADMISSION
  2215. if not admission.acquire(blocking=False):
  2216. _fail_open("Media-delivery history lookup capacity exhausted for")
  2217. return None
  2218. loop = asyncio.get_running_loop()
  2219. result_future = loop.create_future()
  2220. def _publish_result(result=None, error=None):
  2221. if not result_future.done():
  2222. (result_future.set_exception(error) if error is not None
  2223. else result_future.set_result(result))
  2224. def _worker():
  2225. result, error = None, None
  2226. try:
  2227. result = self._history_media_paths_for_session(session_key)
  2228. except BaseException as exc:
  2229. error = exc
  2230. try:
  2231. with contextlib.suppress(RuntimeError): # loop already closed (gateway shutdown)
  2232. loop.call_soon_threadsafe(_publish_result, result, error)
  2233. finally:
  2234. admission.release()
  2235. try:
  2236. threading.Thread(target=_worker, name="media-history-lookup", daemon=True).start()
  2237. except Exception:
  2238. # start() failed (thread exhaustion): the worker never ran, so release the permit here.
  2239. admission.release()
  2240. _fail_open("Could not start media-delivery history lookup worker for", exc_info=True)
  2241. return None
  2242. try:
  2243. return await asyncio.wait_for(result_future, timeout=_HISTORY_MEDIA_LOOKUP_TIMEOUT_SECONDS)
  2244. except TimeoutError:
  2245. _fail_open("Timed out loading media-delivery history for")
  2246. return None
  2247. except Exception:
  2248. # Best-effort/fail-open: never let a lookup failure kill media delivery.
  2249. _fail_open("Media-delivery history lookup failed for", exc_info=True)
  2250. return None
  2251. @abstractmethod
  2252. async def connect(self, *, is_reconnect: bool = False) -> bool:
  2253. """Connect and start receiving; True on success. ``is_reconnect``: the reconnect watcher is
  2254. re-establishing a dropped platform — adapters with a server-side update queue (Telegram)
  2255. must preserve it so outage-time messages aren't discarded."""
  2256. @abstractmethod
  2257. async def disconnect(self) -> None:
  2258. """Disconnect from the platform."""
  2259. @abstractmethod
  2260. async def send(self, chat_id: str, content: str, reply_to: Optional[str] = None,
  2261. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2262. """Send ``content`` (may be markdown) to a chat; returns SendResult with message id."""
  2263. # Surfaces needing an explicit finalize edit (DingTalk AI Cards): the consumer never skips it.
  2264. REQUIRES_EDIT_FINALIZE: bool = False
  2265. async def create_handoff_thread(self, parent_chat_id: str, name: str) -> Optional[str]:
  2266. """Create a fresh thread under ``parent_chat_id`` for a CLI→platform session handoff; its id
  2267. as str, or None when unsupported/failed (the watcher then uses ``parent_chat_id``
  2268. directly)."""
  2269. return None
  2270. async def edit_message(
  2271. self, chat_id: str, message_id: str, content: str, *, finalize: bool = False) -> SendResult:
  2272. """Edit a sent message (optional: success=False makes callers send anew). ``finalize`` marks
  2273. the last edit of a streamed response; surfaces with a distinct "in progress" state (DingTalk
  2274. AI Cards) close the message on it and set ``REQUIRES_EDIT_FINALIZE`` so it's routed even
  2275. when content is unchanged."""
  2276. return SendResult(success=False, error="Not supported")
  2277. async def delete_message(self, chat_id: str, message_id: str) -> bool:
  2278. """Delete a sent message; True on success (platforms without a deletion API return False and
  2279. callers leave it). Used by the stream consumer's fresh-final cleanup to remove stale
  2280. previews.
  2281. Used by the stream consumer's fresh-final cleanup path (see openclaw/openclaw#72038) to remove
  2282. long-lived preview messages after sending the completed reply as a fresh message so the platform's
  2283. visible timestamp reflects completion time.
  2284. """
  2285. return False
  2286. def _get_ephemeral_system_ttl_default(self) -> int:
  2287. """Default :class:`EphemeralReply` TTL from ``display.ephemeral_system_ttl``
  2288. (``0`` = no auto-delete); non-fatal if config is unreadable."""
  2289. return _or_default(
  2290. lambda: int(_config_section("display").get("ephemeral_system_ttl", 0)), 0)
  2291. def _schedule_ephemeral_delete(self, chat_id: str, message_id: str, ttl_seconds: int) -> None:
  2292. """Spawn a detached task that deletes ``message_id`` after ``ttl_seconds``; best-effort
  2293. (gateway restart, permission denied, Telegram 48h window) swallowed at debug level."""
  2294. async def _run_delete() -> None:
  2295. try:
  2296. await asyncio.sleep(max(1, int(ttl_seconds)))
  2297. await self.delete_message(chat_id=chat_id, message_id=message_id)
  2298. except Exception as e:
  2299. logger.debug("[%s] Ephemeral delete failed for %s/%s: %s", self.name, chat_id, message_id, e)
  2300. coro = _run_delete()
  2301. try:
  2302. asyncio.create_task(coro)
  2303. except RuntimeError:
  2304. # No running loop (unit tests): close the coroutine to avoid a never-awaited warning.
  2305. coro.close()
  2306. # ── ``_format_exec_approval`` templates; adapters override only the MARKUP (bold, HTML,
  2307. # fences) — the words come from ``gateway.platforms.base_exec_approval`` so every surface
  2308. # says the same thing.
  2309. # ``_EA_HEADER`` / ``_EA_REASON_LABEL`` / ``_EA_SMART_DENY_LINE`` / ``_EA_ACTION_LABELS`` are
  2310. # properties (not class attrs) so the active ``display.language`` is read per render;
  2311. # subclasses may still shadow them with plain class attributes carrying their own markup.
  2312. _EA_CODE_OPEN: str = "```\n"
  2313. _EA_CODE_CLOSE: str = "\n```\n"
  2314. _EA_DEADLINE_PREFIX: str = "\n\n" # separates the deadline line from the reason line
  2315. _EA_CMD_BUDGET: int = 3000
  2316. _EA_REASON_BUDGET: int = 0 # 0 = the reason is never truncated
  2317. @property
  2318. def _EA_HEADER(self) -> str:
  2319. return f"⚠️ {ea_header_text()}\n\n"
  2320. @property
  2321. def _EA_REASON_LABEL(self) -> str:
  2322. return f"{ea_reason_label_text()}: "
  2323. @property
  2324. def _EA_SMART_DENY_LINE(self) -> str:
  2325. return f"\n\n{ea_smart_deny_line_text()}"
  2326. @staticmethod
  2327. def _truncate_preview(text: str, budget: int, suffix: str = "...") -> str:
  2328. """Truncate ``text`` to ``budget`` chars, appending ``suffix`` when cut."""
  2329. text = str(text or "")
  2330. return text[:budget] + suffix if len(text) > budget else text
  2331. def _ea_escape(self, text: str) -> str:
  2332. """Escape hook for command preview/reason; HTML-mode platforms (Telegram) override."""
  2333. return text
  2334. def _ea_fit(self, text: str, budget: int, suffix: str = "...", escape: Optional[Callable[[str], str]] = None) -> str:
  2335. """``_truncate_preview`` measured after ``escape`` (default ``_ea_escape``) in
  2336. ``message_len_fn`` units: the platform cap applies to the wire payload, and escaping
  2337. expands (``&`` → ``&amp;``), so a raw-length cut can still overflow. Returns raw text (the
  2338. caller escapes); ``suffix`` rides outside ``budget`` like ``_truncate_preview``."""
  2339. escape = escape or self._ea_escape
  2340. return fit_prefix(str(text or ""), budget, lambda s: self.message_len_fn(escape(s)), suffix)
  2341. def _exec_approval_cmd_budget(self, description: str, smart_denied: bool) -> int:
  2342. """Chars of command preview that fit; platforms with a hard message cap compute it."""
  2343. return self._EA_CMD_BUDGET
  2344. def _ea_deadline_line(self) -> str:
  2345. """The "doing nothing means it will NOT run" line, with the configured approvals.timeout."""
  2346. return self._EA_DEADLINE_PREFIX + self._ea_escape(format_approval_deadline_line(approval_timeout_seconds()))
  2347. def _format_exec_approval(
  2348. self, command: str, description: Optional[str] = None, smart_denied: bool = False) -> str:
  2349. """Shared exec-approval prompt text: header + fenced (truncated) command + why it was
  2350. flagged + the deadline line, plus the smart-deny line. Buttons/trailing instructions stay
  2351. platform-local. ``description=None`` renders the localized default reason."""
  2352. if description is None:
  2353. description = ea_default_reason_text()
  2354. if self._EA_REASON_BUDGET:
  2355. description = self._ea_fit(str(description or ""), self._EA_REASON_BUDGET)
  2356. cmd_preview = self._ea_fit(
  2357. str(command or ""), self._exec_approval_cmd_budget(description, smart_denied))
  2358. text = (f"{self._EA_HEADER}"
  2359. f"{self._EA_CODE_OPEN}{self._ea_escape(cmd_preview)}{self._EA_CODE_CLOSE}"
  2360. f"{self._EA_REASON_LABEL}{self._ea_escape(description)}"
  2361. f"{self._ea_deadline_line()}")
  2362. return text + self._EA_SMART_DENY_LINE if smart_denied else text
  2363. # ── Exec-approval prompt (template method). The choice set is one rule for every button
  2364. # surface — three separate "same fix × N adapters" commits motivated lifting it here.
  2365. _EA_ACTION_STYLES: dict[str, str] = {"once": "primary", "deny": "danger"}
  2366. @property
  2367. def _EA_ACTION_LABELS(self) -> dict[str, str]:
  2368. return ea_action_labels()
  2369. def _exec_approval_actions(
  2370. self, *, allow_permanent: bool, allow_session: bool, smart_denied: bool) -> list[tuple[str, str, str]]:
  2371. """``(label, choice, style)`` rows for the approval buttons. A smart deny is an owner
  2372. override for one operation only, so it offers neither the session nor the permanent tier;
  2373. the permanent tier is never offered without the session tier."""
  2374. choices = ["once"]
  2375. if not smart_denied and allow_session:
  2376. choices.append("session")
  2377. if allow_permanent:
  2378. choices.append("always")
  2379. choices.append("deny")
  2380. return [(self._EA_ACTION_LABELS[c], c, self._EA_ACTION_STYLES.get(c, "")) for c in choices]
  2381. @classmethod
  2382. def supports_exec_approval_buttons(cls) -> bool:
  2383. """True when the adapter renders native approval buttons (overrides the prompt hook);
  2384. the runner otherwise sends the plain-text ``/approve`` prompt."""
  2385. return cls._send_exec_approval_prompt is not BasePlatformAdapter._send_exec_approval_prompt
  2386. async def send_exec_approval(
  2387. self, chat_id: str, command: str, session_key: str, description: Optional[str] = None,
  2388. metadata: Optional[dict[str, Any]] = None, allow_permanent: bool = True, allow_session: bool = True,
  2389. smart_denied: bool = False, request_id: Optional[str] = None,
  2390. ) -> SendResult:
  2391. """Interactive exec-approval prompt; a press resolves via ``tools.approval.resolve_gateway_approval``.
  2392. Text and choice set are shared; adapters render them natively in ``_send_exec_approval_prompt``."""
  2393. if description is None:
  2394. description = ea_default_reason_text()
  2395. prompt = ExecApprovalPrompt(
  2396. chat_id=chat_id, session_key=session_key, metadata=metadata, command=str(command or ""),
  2397. description=description, smart_denied=smart_denied, request_id=request_id,
  2398. text=self._format_exec_approval(command, description, smart_denied),
  2399. actions=self._exec_approval_actions(
  2400. allow_permanent=allow_permanent, allow_session=allow_session, smart_denied=smart_denied))
  2401. return await self._send_exec_approval_prompt(prompt)
  2402. async def _send_exec_approval_prompt(self, prompt: ExecApprovalPrompt) -> SendResult:
  2403. """Render ``prompt`` with the platform's native buttons; the default has none."""
  2404. return SendResult(success=False, error="Not supported")
  2405. @staticmethod
  2406. def _format_choice_page(options: list, page: int, per_page: int) -> tuple[list, dict[str, Any]]:
  2407. """Shared picker pagination: clamp ``page``, slice ``options`` -> ``(page_options, meta)``
  2408. with ``page``/``total_pages``/``start``/``end``/``total``/``page_info`` (`` (N–M of T)``,
  2409. empty for one page)."""
  2410. total = len(options)
  2411. total_pages = max(1, (total + per_page - 1) // per_page)
  2412. page = max(0, min(page, total_pages - 1))
  2413. start, end = page * per_page, min(page * per_page + per_page, total)
  2414. page_info = t("gateway.picker.page_info", start=start + 1, end=end, total=total) if total_pages > 1 else ""
  2415. meta: dict[str, Any] = {"page": page, "total_pages": total_pages, "start": start,
  2416. "end": end, "total": total, "page_info": page_info}
  2417. return options[start:end], meta
  2418. async def send_slash_confirm(
  2419. self, chat_id: str, title: str, message: str, session_key: str, confirm_id: str,
  2420. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2421. """Three-option slash-command confirmation (e.g. ``/reload-mcp``). Button adapters render
  2422. Approve Once / Always Approve / Cancel and MUST resolve via
  2423. ``GatewayRunner._resolve_slash_confirm(confirm_id, "once"|"always"|"cancel")``. Default (not
  2424. supported) falls through to the gateway text fallback
  2425. (``/approve``/``/always``/``/cancel``)."""
  2426. return SendResult(success=False, error="Not supported")
  2427. async def send_clarify(
  2428. self, chat_id: str, question: str, choices: Optional[list], clarify_id: str,
  2429. session_key: str, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2430. """Clarify prompt; button-capable adapters SHOULD override. Multiple choice (``choices``):
  2431. one button per choice plus "Other"; callbacks MUST resolve via
  2432. ``tools.clarify_gateway.resolve_gateway_clarify(clarify_id, response)``, "Other" calls
  2433. ``mark_awaiting_text(clarify_id)``. Open-ended: send the question as text (the gateway
  2434. text-intercept resolves the next message). Default: numbered list +
  2435. ``mark_awaiting_text``. Adapters whose prompt is a persistent card MAY define
  2436. ``async retire_clarify_card(clarify_id, notice)``; the gateway calls it when the clarify
  2437. ends without a click (timeout, session reset, superseding free prose)."""
  2438. if choices:
  2439. # Multi-select flag lives on the pending entry (signature stays adapter-compatible).
  2440. try:
  2441. from tools.clarify_gateway import get_pending
  2442. _is_multi = bool(getattr(get_pending(clarify_id), "multi_select", False))
  2443. except Exception:
  2444. _is_multi = False
  2445. hint = t("gateway.clarify.hint_multi") if _is_multi else t("gateway.clarify.hint_single")
  2446. numbered = [t("gateway.clarify.option_line", index=i, choice=choice)
  2447. for i, choice in enumerate(choices, start=1)]
  2448. text = "\n".join([t("gateway.clarify.question", question=question), "", *numbered, "", hint])
  2449. # Text fallback: let the gateway intercept capture the typed reply.
  2450. from tools.clarify_gateway import mark_awaiting_text
  2451. mark_awaiting_text(clarify_id)
  2452. else:
  2453. text = t("gateway.clarify.question", question=question)
  2454. return await self.send(chat_id=chat_id, content=text, metadata=metadata)
  2455. async def send_private_notice(
  2456. self, chat_id: str, user_id: Optional[str], content: str, reply_to: Optional[str] = None,
  2457. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2458. """Send a notice privately when the platform supports it; default is a normal send."""
  2459. return await self.send(chat_id=chat_id, content=content, reply_to=reply_to, metadata=metadata)
  2460. async def send_typing(self, chat_id: str, metadata=None) -> None:
  2461. """Send a typing indicator; ``metadata`` carries platform context (Slack thread_id)."""
  2462. async def stop_typing(self, chat_id: str) -> None:
  2463. """Stop a persistent typing indicator; override where typing runs as a loop."""
  2464. @staticmethod
  2465. def _accepts_kwarg(fn: Callable, name: str, *, var_kw: bool, unknown: bool) -> bool:
  2466. """Whether ``fn``'s signature takes keyword ``name`` (``var_kw``: a ``**kwargs`` also
  2467. counts); ``unknown`` when the signature can't be introspected."""
  2468. try:
  2469. params = inspect.signature(fn).parameters
  2470. except (TypeError, ValueError):
  2471. return unknown
  2472. return name in params or (var_kw and any(
  2473. p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()))
  2474. async def _stop_typing_with_metadata(self, chat_id: str, metadata=None) -> None:
  2475. """Stop typing, forwarding ``metadata`` only if ``stop_typing`` accepts it (Slack AI
  2476. status is per thread, so dropping metadata could clear a sibling thread; introspecting
  2477. keeps legacy ``stop_typing(chat_id)`` adapters working)."""
  2478. if metadata and self._accepts_kwarg(
  2479. self.stop_typing, "metadata", var_kw=True, unknown=False):
  2480. await self.stop_typing(chat_id, metadata=metadata)
  2481. return
  2482. await self.stop_typing(chat_id)
  2483. async def send_multiple_images(
  2484. self, chat_id: str, images: list[tuple[str, str]],
  2485. metadata: Optional[dict[str, Any]] = None, human_delay: float = 0.0) -> SendResult:
  2486. """Send ``(url, alt)`` images (``http(s)://`` or ``file://``) one by one (GIFs via
  2487. ``send_animation``, local files via ``send_image_file``); override to bundle natively
  2488. (Signal). Returns success when at least one image was delivered — the outcome
  2489. the turn-level delivery tracker records; every override must return the same
  2490. aggregate, or a media-only turn on that platform reports FAILURE (#106153)."""
  2491. delivered = False
  2492. for image_url, alt_text in images:
  2493. if human_delay > 0:
  2494. await asyncio.sleep(human_delay)
  2495. try:
  2496. logger.info("[%s] Sending image: %s (alt=%s)", self.name,
  2497. safe_url_for_log(image_url), alt_text[:30] if alt_text else "")
  2498. if image_url.startswith("file://"):
  2499. from urllib.request import url2pathname
  2500. sender, url_kw = self.send_image_file, {"image_path": url2pathname(image_url[7:])}
  2501. elif self._is_animation_url(image_url):
  2502. sender, url_kw = self.send_animation, {"animation_url": image_url}
  2503. else:
  2504. sender, url_kw = self.send_image, {"image_url": image_url}
  2505. img_result = await sender(
  2506. chat_id=chat_id, **url_kw, caption=alt_text or None, metadata=metadata)
  2507. if not img_result.success:
  2508. logger.error("[%s] Failed to send image: %s", self.name, img_result.error)
  2509. else:
  2510. delivered = True
  2511. except Exception as img_err:
  2512. logger.error("[%s] Error sending image: %s", self.name, img_err, exc_info=True)
  2513. if not images:
  2514. return SendResult(success=False, error="no images to send")
  2515. return SendResult(
  2516. success=delivered,
  2517. error=None if delivered else "all images failed to send")
  2518. async def send_image(
  2519. self, chat_id: str, image_url: str, caption: Optional[str] = None,
  2520. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2521. """Send an image natively; default falls back to sending the URL as text."""
  2522. text = f"{caption}\n{image_url}" if caption else image_url
  2523. return await self.send(chat_id=chat_id, content=text, reply_to=reply_to, metadata=metadata)
  2524. async def send_animation(
  2525. self, chat_id: str, animation_url: str, caption: Optional[str] = None,
  2526. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None) -> SendResult:
  2527. """Send a GIF as a native animation (auto-plays inline); default falls back to
  2528. send_image."""
  2529. return await self.send_image(
  2530. chat_id=chat_id, image_url=animation_url, caption=caption, reply_to=reply_to, metadata=metadata)
  2531. @staticmethod
  2532. def _is_animation_url(url: str) -> bool:
  2533. """Check if a URL points to an animated GIF (vs a static image)."""
  2534. return url.lower().split('?')[0].endswith('.gif')
  2535. @staticmethod
  2536. def extract_images(content: str) -> tuple[list[tuple[str, str]], str]:
  2537. """Extract ``![alt](url)`` and ``<img src=...>`` image URLs from a response;
  2538. returns ``([(url, alt_text), ...], content with those tags removed)``."""
  2539. md_pattern, html_pattern = MD_IMAGE_TAG_PATTERN, HTML_IMAGE_TAG_PATTERN
  2540. images = [(m.group(2), m.group(1)) for m in re.finditer(md_pattern, content)
  2541. if any(m.group(2).lower().endswith(ext) or ext in m.group(2).lower()
  2542. for ext in _IMAGE_URL_MARKERS)] # only URLs that look like actual images
  2543. images.extend((match.group(1), "") for match in re.finditer(html_pattern, content))
  2544. if not images:
  2545. return images, content
  2546. # Remove only the tags we extracted, not every markdown image.
  2547. extracted_urls = {url for url, _ in images}
  2548. def _remove_if_extracted(match):
  2549. url = match.group(2) if match.lastindex >= 2 else match.group(1)
  2550. return '' if url in extracted_urls else match.group(0)
  2551. cleaned = content
  2552. for pattern in (md_pattern, html_pattern):
  2553. cleaned = re.sub(pattern, _remove_if_extracted, cleaned)
  2554. return images, re.sub(r'\n{3,}', '\n\n', cleaned).strip() # leftover blank lines
  2555. async def send_voice(
  2556. self, chat_id: str, audio_path: str, caption: Optional[str] = None,
  2557. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  2558. """Send audio as a native voice message (Telegram bubble / Discord attachment).
  2559. Default: friendly failure notice."""
  2560. return await self._send_media_fallback_notice(
  2561. "send_voice", "audio", audio_path, chat_id, caption, reply_to, metadata)
  2562. async def _send_media_fallback_notice(
  2563. self, method: str, kind: str, path: str, chat_id: str, caption: Optional[str],
  2564. reply_to: Optional[str], metadata: Optional[dict[str, Any]], *, file_name: Optional[str] = None,
  2565. ) -> SendResult:
  2566. """Shared default for send_voice/send_video/send_document/send_image_file. The local path is
  2567. logged but NEVER echoed into chat (host layout leak); only the caller's ``file_name`` is
  2568. shown."""
  2569. logger.warning("[%s] %s fallback: native %s send unavailable for %s", self.name, method, kind, path)
  2570. text = _media_failure_text(kind, file_name)
  2571. return await self.emit_media_warning(chat_id, text, caption=caption, reply_to=reply_to, metadata=metadata,
  2572. shown_metadata=metadata)
  2573. async def emit_warning(
  2574. self, chat_id: str, content: str, *, reply_to=None, metadata=None, logical_platform=None,
  2575. ) -> Optional[SendResult]:
  2576. """Present a classified channel diagnostic in the caller's owning scope.
  2577. None means suppressed, NOT successfully sent. Transport receipts/exceptions
  2578. pass through unchanged; logs and producer state belong outside this boundary.
  2579. Existing routing/stream metadata is preserved, never inferred from text.
  2580. """
  2581. if not self.warning_notifications_enabled(logical_platform, chat_id=chat_id, metadata=metadata):
  2582. return None
  2583. return await self.send(chat_id, content, reply_to=reply_to, metadata=metadata)
  2584. async def emit_media_warning(
  2585. self, chat_id: str, notice: str, *, caption=None, reply_to=None, metadata=None,
  2586. shown_metadata=None,
  2587. ) -> SendResult:
  2588. """Present an optional media diagnostic without losing the requested caption.
  2589. Preserve the legacy fallback-text receipt when shown (``shown_metadata`` is the exact
  2590. metadata the legacy shown path passed; default None keeps callers that sent none
  2591. byte-identical). When hidden, preserve the media failure even if the independent
  2592. caption itself was delivered.
  2593. """
  2594. result = await self.emit_warning(chat_id, f"{caption}\n{notice}" if caption else notice,
  2595. reply_to=reply_to, metadata=shown_metadata)
  2596. if result is not None:
  2597. return result
  2598. if caption:
  2599. await self.send(chat_id, caption, reply_to=reply_to, metadata=metadata)
  2600. return SendResult(success=False, error=notice)
  2601. def warning_text(self, visible: str, hidden: Optional[str] = "", *, logical_platform=None, chat_id=None, metadata=None) -> Optional[str]:
  2602. """Project mixed content: the diagnostic variant when visible, else the requested remainder.
  2603. For payloads that combine a requested result (caption, answer) with an automatic
  2604. diagnostic. The requested part must be present in BOTH variants; never hide it.
  2605. """
  2606. if self.warning_notifications_enabled(logical_platform, chat_id=chat_id, metadata=metadata):
  2607. return visible
  2608. return hidden
  2609. def warning_notifications_enabled(self, logical_platform=None, *, chat_id=None, metadata=None) -> bool:
  2610. """Presentation policy under the caller's owning profile; old plugins inherit it."""
  2611. from gateway.warning_notifications import warning_notifications_enabled
  2612. return warning_notifications_enabled(logical_platform or self.platform)
  2613. def prepare_tts_text(self, text: str) -> str:
  2614. """Chat Markdown -> transcript-like spoken script (reasoning blocks removed,
  2615. headings/bullets flattened, units expanded). Chunking and delivery limits are the TTS tool's
  2616. job."""
  2617. try:
  2618. from tools.tts_text_normalize import prepare_spoken_text
  2619. return prepare_spoken_text(text, max_chars=None)
  2620. except Exception:
  2621. # Keep auto-TTS best-effort if the normalizer ever fails.
  2622. text = re.sub(r'<think[\s>].*?</think>', ' ', text, flags=re.DOTALL)
  2623. return re.sub(r'[*_`#\[\]()]', '', text).strip()
  2624. async def play_tts(self, chat_id: str, audio_path: str, **kwargs) -> SendResult:
  2625. """Play auto-TTS audio; override for invisible playback (Web UI). Default: send_voice."""
  2626. return await self.send_voice(chat_id=chat_id, audio_path=audio_path, **kwargs)
  2627. # ── Streaming TTS contract: voice adapters accept PCM chunks while the LLM generates.
  2628. # Defaults report "unsupported" (whole-file fallback).
  2629. # ------------------------------------------------------------------ Streaming TTS adapter contract
  2630. # (#60671) ------------------------------------------------------------------ Voice-capable adapters
  2631. # (LiveKit, Discord voice, …) override these to accept PCM audio chunks while the LLM is still
  2632. # generating. The default implementations report "unsupported" so existing adapters are
  2633. # source-compatible and keep the whole-file auto-TTS fallback.
  2634. def supports_streaming_tts(self, chat_id: str, audio_format: AudioFormat) -> bool:
  2635. """Return True when this adapter can accept streaming PCM for *chat_id*."""
  2636. return False
  2637. async def begin_streaming_tts(
  2638. self, chat_id: str, audio_format: AudioFormat, metadata: Optional[dict[str, Any]] = None,
  2639. ) -> Optional[StreamingTTSHandle]:
  2640. """Open a streaming-audio session; returns an opaque handle for the
  2641. write/finish/abort calls, or ``None`` to decline (whole-file fallback)."""
  2642. return None
  2643. async def write_streaming_tts(self, handle: StreamingTTSHandle, chunk: bytes) -> None:
  2644. """Write one PCM chunk to the adapter's outbound audio track."""
  2645. async def finish_streaming_tts(self, handle: StreamingTTSHandle, *, interrupted: bool = False) -> None:
  2646. """Signal normal end of the audio stream."""
  2647. async def abort_streaming_tts(self, handle: StreamingTTSHandle, error: Optional[str] = None) -> None:
  2648. """Abort the stream due to an error or cancellation. Must be idempotent: late producer
  2649. chunks after abort are silently dropped, not raised. Restores state to "not streaming"."""
  2650. def _streaming_tts_turn_key(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> str | None:
  2651. return streaming_tts_turn_key(session_key, turn_marker, event=event)
  2652. def _mark_streaming_tts_completed_turn(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> None:
  2653. turn_key = self._streaming_tts_turn_key(session_key, turn_marker, event=event)
  2654. if turn_key is not None:
  2655. _lazy_attr(self, "_streaming_tts_completed_turns", set).add(turn_key)
  2656. def _streaming_tts_turn_completed(self, session_key: str | None, turn_marker: Any = None, *, event: Any = None) -> bool:
  2657. return streaming_tts_should_skip_whole_file(
  2658. getattr(self, "_streaming_tts_completed_turns", set()), session_key, turn_marker, event=event)
  2659. async def send_video(
  2660. self, chat_id: str, video_path: str, caption: Optional[str] = None,
  2661. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  2662. """Send a video natively (inline playable). Default: friendly failure notice."""
  2663. return await self._send_media_fallback_notice(
  2664. "send_video", "video", video_path, chat_id, caption, reply_to, metadata)
  2665. async def send_document(self, chat_id: str, file_path: str, caption: Optional[str] = None,
  2666. file_name: Optional[str] = None, reply_to: Optional[str] = None,
  2667. metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  2668. """Send a document/file natively. Default: friendly failure notice."""
  2669. return await self._send_media_fallback_notice(
  2670. "send_document", "file", file_path, chat_id, caption, reply_to, metadata, file_name=file_name)
  2671. async def _notify_media_delivery_failure(
  2672. self, chat_id: str, media_path: str, *, is_voice: bool = False,
  2673. metadata: Optional[dict[str, Any]] = None) -> None:
  2674. """User-visible notice when a MEDIA attachment upload failed: the tag was
  2675. already stripped from the text, so silence would be a silent drop.
  2676. The non-streaming dispatch loop strips ``MEDIA:`` tags before sending attachments. When the
  2677. subsequent upload returns ``success=False`` (for example Discord accepted the message but attached
  2678. nothing), the user must see a failure notice instead of a silent drop (#66797).
  2679. """
  2680. ext = Path(media_path).suffix.lower()
  2681. if is_voice or should_send_media_as_audio(self.platform, ext, is_voice=is_voice):
  2682. text = _media_failure_text("audio")
  2683. elif ext in _VIDEO_EXTS:
  2684. text = _media_failure_text("video")
  2685. else:
  2686. text = _media_failure_text("file", os.path.basename(media_path))
  2687. try:
  2688. notice = await self.emit_warning(chat_id, text, metadata=metadata)
  2689. problem = None if notice is None or notice.success else notice.error
  2690. except Exception as notify_err:
  2691. problem = notify_err
  2692. if problem is not None:
  2693. logger.debug("[%s] Could not send media-delivery-failure notice: %s", self.name, problem)
  2694. async def send_image_file(
  2695. self, chat_id: str, image_path: str, caption: Optional[str] = None,
  2696. reply_to: Optional[str] = None, metadata: Optional[dict[str, Any]] = None, **kwargs) -> SendResult:
  2697. """Send a local image file natively (send_image takes a URL). Default: friendly notice."""
  2698. return await self._send_media_fallback_notice(
  2699. "send_image_file", "image", image_path, chat_id, caption, reply_to, metadata)
  2700. @staticmethod
  2701. def validate_media_delivery_path(path: str, session_key: str = "") -> Optional[str]:
  2702. """Return a resolved path if it is safe for native attachment upload."""
  2703. return validate_media_delivery_path(path, session_key=session_key)
  2704. @staticmethod
  2705. def filter_media_delivery_paths(media_files, session_key: str = "",
  2706. dropped: Optional[list[dict]] = None) -> list[tuple[str, bool]]:
  2707. """Drop unsafe MEDIA paths and normalize accepted paths; ``dropped`` collects the rejects."""
  2708. return [
  2709. (safe_path, bool(is_voice)) for media_path, is_voice in media_files or []
  2710. if (safe_path := _validated_delivery_path(media_path, session_key, "MEDIA directive path", dropped))]
  2711. @staticmethod
  2712. def filter_local_delivery_paths(file_paths, session_key: str = "") -> list[str]:
  2713. """Drop unsafe bare local file paths and normalize accepted paths."""
  2714. safe_paths = (_validated_delivery_path(p, session_key, "local file path") for p in file_paths or [])
  2715. return [p for p in safe_paths if p]
  2716. @staticmethod
  2717. def _mask_protected_spans(content: str) -> str:
  2718. """Blank fenced code, inline code and blockquotes (length-preserving so regex offsets stay
  2719. valid) against MEDIA: false positives; backtick-quoted paths inside MEDIA: tags stay
  2720. scannable."""
  2721. spans: list = [m.span() for m in _FENCED_CODE_RE.finditer(content)]
  2722. for m in _INLINE_CODE_RE.finditer(content):
  2723. start = m.start()
  2724. if re.search(r'MEDIA:\s*$', content[max(0, start - 20):start]):
  2725. continue # This is a MEDIA path quote, not inline code
  2726. # A whole tag in inline code (`MEDIA:/path.csv`) is a real directive (models format
  2727. # paths as code): deliver IF it validates; non-existent examples stay masked.
  2728. # See #35695.
  2729. inner = m.group(0)[1:-1].strip()
  2730. if inner.upper().startswith("MEDIA:"):
  2731. candidate = _normalize_media_tag_path(inner[6:])
  2732. if candidate and validate_media_delivery_path(candidate):
  2733. continue # Real deliverable tag in inline code — keep it scannable
  2734. spans.append((start, m.end()))
  2735. spans.extend(m.span() for m in re.finditer(r'^>.*$', content, re.MULTILINE))
  2736. return _blank_spans(content, spans)
  2737. @staticmethod
  2738. def _mask_json_string_media(content: str) -> str:
  2739. """Blank ``MEDIA:<bare-path>`` tags inside JSON string *values* (stored tool-result text
  2740. like ``{"result": "MEDIA:/x/stale.png"}``) so they are never re-delivered. Only
  2741. value-context strings (``:,{[`` before the ``"``) and bare paths (``/``, ``~/``, ``X:\\``)
  2742. count; ``MEDIA:"..."`` quoted tags and line-start/prose tags are untouched. Offsets
  2743. preserved.
  2744. Here the ``MEDIA:`` is part of stored text, not an outbound directive, but the bare-path branch of
  2745. ``MEDIA_TAG_CLEANUP_RE`` would still match it and re-deliver a stale file. (Regression report
  2746. #34375.)
  2747. """
  2748. if '"' not in content or "MEDIA:" not in content:
  2749. return content
  2750. # Value-context string: quote preceded by : , { or [; escape-aware body to the closing
  2751. # quote.
  2752. spans = [
  2753. m.span(1) for m in re.finditer(r'(?<=[:,{\[])\s*"((?:[^"\\\n]|\\.)*)"', content)
  2754. if re.search(r'MEDIA:\s*(?:~/|/|[A-Za-z]:[/\\])', m.group(1))]
  2755. return _blank_spans(content, spans)
  2756. @staticmethod
  2757. def extract_media(content: str) -> tuple[list[tuple[str, bool]], str]:
  2758. """Extract ``MEDIA:<path>`` tags and strip ``[[audio_as_voice]]`` / ``[[as_document]]`` ->
  2759. ``([(path, is_voice), ...], cleaned)``. Both directives are message-global;
  2760. ``[[as_document]]`` (unmodified sendDocument for large images) is detected by dispatch sites
  2761. on the ORIGINAL response and only stripped here."""
  2762. media = []
  2763. has_voice_tag = "[[audio_as_voice]]" in content
  2764. cleaned = content.replace("[[audio_as_voice]]", "").replace("[[as_document]]", "")
  2765. # Scan a masked copy so example/stored MEDIA paths (code, quotes, JSON values) are never
  2766. # delivered; dedupe on the expanded path so a file referenced twice uploads once.
  2767. scan_content = _mask_media_scan_text(content)
  2768. # - code blocks / inline code / blockquotes hold prose examples (#35695) - serialized JSON string
  2769. # values hold stored tool-result text (#34375) Both maskers are offset-preserving (chars ->
  2770. # spaces) so match offsets stay valid; chaining them masks the union of both protected regions.
  2771. # Dedupe on the expanded path (first occurrence wins) so the same file referenced twice in one
  2772. # response — e.g. a MEDIA tag inline AND in a summary footer — is uploaded once, not twice (#29131).
  2773. seen_paths: set = set()
  2774. def _add(path: str) -> None:
  2775. # is_voice only for audio: a voice-flagged image would leave the photo batch.
  2776. if path not in seen_paths:
  2777. seen_paths.add(path)
  2778. media.append((path, has_voice_tag and os.path.splitext(path)[1].lower() in _AUDIO_EXTS))
  2779. for match in MEDIA_TAG_CLEANUP_RE.finditer(scan_content):
  2780. path = _normalize_media_tag_path(match.group("path"))
  2781. if path:
  2782. try:
  2783. _add(os.path.expanduser(path))
  2784. except (OSError, RuntimeError, ValueError):
  2785. continue # crafted ~\x00 path: skip it, keep the rest
  2786. for _, safe_path, _ in _extensionless_media_matches(scan_content):
  2787. _add(safe_path)
  2788. # Locate tag spans on a masked copy, delete them from the unmasked text (protected spans
  2789. # survive).
  2790. if media:
  2791. spans = _deliverable_tag_spans(cleaned)
  2792. if spans:
  2793. cleaned = re.sub(r'\n{3,}', '\n\n', _delete_spans(cleaned, spans)).strip()
  2794. return media, cleaned
  2795. @staticmethod
  2796. def strip_media_directives_for_display(text: str) -> str:
  2797. """Strip MEDIA: directives from streamed/display text. Known-extension tags are
  2798. removed unconditionally (as ``MEDIA_TAG_CLEANUP_RE``); extension-less tags only when
  2799. ``validate_media_delivery_path`` accepts the path, so undeliverable paths stay visible."""
  2800. if not _has_media_directives(text):
  2801. return text
  2802. return re.sub(r'\n{3,}', '\n\n', _strip_media_tag_directives(text)).rstrip()
  2803. @staticmethod
  2804. def extract_local_files(content: str) -> tuple[list[str], str]:
  2805. """Bare local file paths (absolute, ``~/`` or drive-letter) with deliverable extensions ->
  2806. ``(expanded_paths, cleaned_text)``. Candidates must exist on disk (URLs / hallucinated paths
  2807. ignored); paths inside fenced or inline code are skipped so code samples are never
  2808. mutilated. Dispatch by type lives in ``gateway/run.py``."""
  2809. ext_part = '|'.join(e.lstrip('.') for e in MEDIA_DELIVERY_EXTS)
  2810. # Lookbehind rejects URL/relative matches (https://…/img.png, ./foo.png).
  2811. # (?<![/:\w.]) prevents matching inside URLs (e.g. https://…/img.png) and relative paths (./foo.png)
  2812. # (?:~/|/) anchors to absolute or home-relative Unix paths (?:[A-Za-z]:[/\\]) anchors to Windows
  2813. # drive-letter paths (#34632)
  2814. path_re = re.compile(
  2815. r'(?<![/:\w.])(?:~/|/|[A-Za-z]:[/\\])(?:[\w.\-]+[/\\])*[\w.\-]+\.(?:' + ext_part + r')\b',
  2816. re.IGNORECASE)
  2817. code_spans = _code_spans(content)
  2818. unique: dict = {} # expanded_path -> raw_match_text, deduped in discovery order
  2819. for match in path_re.finditer(content):
  2820. if any(s <= match.start() < e for s, e in code_spans):
  2821. continue
  2822. raw = match.group(0)
  2823. expanded = os.path.expanduser(raw)
  2824. if os.path.isfile(expanded):
  2825. unique.setdefault(expanded, raw)
  2826. else:
  2827. # Most common reason a promised file never arrives — log the gap.
  2828. logger.info("Skipping bare file path in reply (no file on disk): %s", _log_safe_path(raw))
  2829. if not unique:
  2830. return [], content
  2831. cleaned = content
  2832. for raw in unique.values():
  2833. cleaned = cleaned.replace(raw, '')
  2834. return list(unique), re.sub(r'\n{3,}', '\n\n', cleaned).strip()
  2835. async def _keep_typing(self, chat_id: str, interval: float = 2.0, metadata=None,
  2836. stop_event: asyncio.Event | None = None) -> None:
  2837. """Refresh the typing indicator every ``interval`` seconds until cancelled (platform typing
  2838. state expires after ~5s). Chats in ``_typing_paused`` are skipped (approval waits — Slack's
  2839. setStatus disables the compose box). Each ``send_typing`` is bounded by a sub-interval
  2840. timeout so one slow round-trip is abandoned before the next tick, not the bubble lapsing."""
  2841. _send_typing_timeout = max(0.25, min(1.5, interval - 0.25))
  2842. try:
  2843. while True:
  2844. if stop_event is not None and stop_event.is_set():
  2845. return
  2846. if chat_id not in self._typing_paused:
  2847. try:
  2848. await asyncio.wait_for(self.send_typing(chat_id, metadata=metadata),
  2849. timeout=_send_typing_timeout)
  2850. except TimeoutError:
  2851. pass # Slow network — abandon this tick, stay on schedule.
  2852. except Exception as typing_err:
  2853. logger.debug("[%s] send_typing error (non-fatal): %s", self.name, typing_err)
  2854. if stop_event is None:
  2855. await asyncio.sleep(interval)
  2856. continue
  2857. loop = asyncio.get_running_loop()
  2858. deadline = loop.time() + interval
  2859. while not stop_event.is_set():
  2860. remaining = deadline - loop.time()
  2861. if remaining <= 0:
  2862. break
  2863. # Poll, not wait_for(stop_event.wait()): cancelling that wedges
  2864. # 3.11/pytest-asyncio.
  2865. await asyncio.sleep(min(0.25, remaining))
  2866. except asyncio.CancelledError:
  2867. pass # Normal cancellation when handler completes
  2868. finally:
  2869. # A send_typing after an outer stop_typing() may have recreated the platform loop.
  2870. await self._stop_typing_quietly(chat_id, metadata)
  2871. self._typing_paused.discard(chat_id)
  2872. # getattr-guard: tests build adapters via object.__new__ without _status_text.
  2873. getattr(self, "_status_text", {}).pop(str(chat_id), None)
  2874. async def _stop_typing_refresh(
  2875. self, chat_id: str, typing_task: asyncio.Task | None = None, *, metadata=None,
  2876. timeout: float = 0.5, stop_attempts: int = 2) -> None:
  2877. """Stop the refresh task and platform typing state as one operation."""
  2878. self._typing_paused.add(chat_id)
  2879. try:
  2880. if typing_task is not None and not typing_task.done():
  2881. typing_task.cancel()
  2882. # Slow adapter cleanup must not block delivery/shutdown.
  2883. with contextlib.suppress(asyncio.CancelledError, asyncio.TimeoutError):
  2884. await asyncio.wait_for(asyncio.shield(typing_task), timeout=timeout)
  2885. for attempt in range(max(1, stop_attempts)):
  2886. if attempt:
  2887. await asyncio.sleep(0)
  2888. await self._stop_typing_quietly(chat_id, metadata)
  2889. finally:
  2890. self._typing_paused.discard(chat_id)
  2891. async def _stop_typing_quietly(self, chat_id: str, metadata=None) -> None:
  2892. """Best-effort platform stop_typing; adapter errors are swallowed."""
  2893. with contextlib.suppress(Exception):
  2894. await self._stop_typing_with_metadata(chat_id, metadata)
  2895. def pause_typing_for_chat(self, chat_id: str) -> None:
  2896. """Pause typing for a chat (approval waits); GIL-safe from the sync agent thread."""
  2897. self._typing_paused.add(chat_id)
  2898. def resume_typing_for_chat(self, chat_id: str) -> None:
  2899. """Resume typing indicator for a chat after approval resolves."""
  2900. self._typing_paused.discard(chat_id)
  2901. async def interrupt_session_activity(self, session_key: str, chat_id: str, metadata=None) -> None:
  2902. """Signal the active session loop to stop and clear typing immediately."""
  2903. if session_key and session_key in self._active_sessions:
  2904. self._active_sessions[session_key].set()
  2905. await self._stop_typing_quietly(chat_id, metadata)
  2906. def register_post_delivery_callback(
  2907. self, session_key: str, callback: Callable, *, generation: int | None = None) -> None:
  2908. """Register a deferred callback to fire after the main response. Same-key registrations are
  2909. chained (both fire in order, per-callback exception isolation) so independent features
  2910. coexist; ``generation`` ties it to a gateway run — stale generations never overwrite a
  2911. fresher slot."""
  2912. if not session_key or not callable(callback):
  2913. return
  2914. existing = self._post_delivery_callbacks.get(session_key)
  2915. if existing is not None:
  2916. existing_gen, existing_cb = _split_post_delivery_entry(existing)
  2917. if existing_gen is not None and generation is not None and int(generation) < int(existing_gen):
  2918. return
  2919. # Same-or-newer generation: chain so both fire in registration order.
  2920. if callable(existing_cb) and (
  2921. existing_gen is None or generation is None or int(existing_gen) == int(generation)):
  2922. callback = self._chain_callbacks(existing_cb, callback)
  2923. self._post_delivery_callbacks[session_key] = (
  2924. callback if generation is None else (int(generation), callback))
  2925. @staticmethod
  2926. def _chain_callbacks(*callbacks: Callable) -> Callable[[], Awaitable[None]]:
  2927. """Async wrapper running ``callbacks`` in order with per-callback exception isolation;
  2928. async so coroutines returned by async hooks are awaited, not dropped."""
  2929. async def _chained() -> None:
  2930. for _cb in callbacks:
  2931. try:
  2932. _result = _cb()
  2933. if inspect.isawaitable(_result):
  2934. await _result
  2935. except Exception:
  2936. logger.debug("Post-delivery callback failed", exc_info=True)
  2937. return _chained
  2938. def pop_post_delivery_callback(
  2939. self, session_key: str, *, generation: int | None = None) -> Callable | None:
  2940. """Pop a deferred callback, optionally requiring generation ownership."""
  2941. entry = self._post_delivery_callbacks.get(session_key) if session_key else None
  2942. if entry is None:
  2943. return None
  2944. entry_generation, callback = _split_post_delivery_entry(entry)
  2945. if generation is not None and (entry_generation is None or int(entry_generation) != int(generation)):
  2946. return None
  2947. self._post_delivery_callbacks.pop(session_key, None)
  2948. return callback if callable(callback) else None
  2949. # ── Processing lifecycle hooks (Discord 👀/✅/❌ reactions). Adapters exposing
  2950. # ``_add_reaction(chat_id, message_id, emoji)`` / ``_remove_reaction(chat_id, message_id)``
  2951. # can just set the emoji attributes; left ``None`` the hook is a no-op.
  2952. _ACK_EMOJI: Optional[str] = None
  2953. _OK_EMOJI: Optional[str] = None
  2954. _FAIL_EMOJI: Optional[str] = None
  2955. async def on_processing_start(self, event: MessageEvent) -> None:
  2956. """Hook called when background processing begins."""
  2957. async def on_processing_complete(self, event: MessageEvent, outcome: ProcessingOutcome) -> None:
  2958. """Hook called when background processing completes. Default: opt-in reaction ack — with
  2959. ``_OK_EMOJI``/``_FAIL_EMOJI`` set and ``_add_reaction``/``_remove_reaction`` present, swap
  2960. the in-progress reaction for the outcome one. Remove-then-add is deterministic whether the
  2961. platform replaces or stacks a sender's reactions. CANCELLED leaves it unreacted."""
  2962. if self._OK_EMOJI is None and self._FAIL_EMOJI is None:
  2963. return
  2964. add: Any = getattr(self, "_add_reaction", None)
  2965. remove: Any = getattr(self, "_remove_reaction", None)
  2966. enabled = getattr(self, "_reactions_enabled", None)
  2967. chat_id = getattr(event.source, "chat_id", None)
  2968. message_id = getattr(event, "message_id", None)
  2969. if (not callable(add) or not callable(remove) or (callable(enabled) and not enabled())
  2970. or not chat_id or not message_id):
  2971. return
  2972. await remove(chat_id, message_id)
  2973. emoji = {ProcessingOutcome.SUCCESS: self._OK_EMOJI,
  2974. ProcessingOutcome.FAILURE: self._FAIL_EMOJI}.get(outcome)
  2975. if emoji:
  2976. await add(chat_id, message_id, emoji)
  2977. async def _run_processing_hook(self, hook_name: str, *args: Any, **kwargs: Any) -> None:
  2978. """Run a lifecycle hook without letting failures break message flow."""
  2979. hook = getattr(self, hook_name, None)
  2980. if not callable(hook):
  2981. return
  2982. try:
  2983. await hook(*args, **kwargs)
  2984. except Exception as e:
  2985. logger.warning("[%s] %s hook failed: %s", self.name, hook_name, e)
  2986. @staticmethod
  2987. def _is_retryable_error(error: Optional[str]) -> bool:
  2988. """Return True if the error string looks like a transient network failure."""
  2989. lowered = (error or "").lower()
  2990. return any(pat in lowered for pat in _RETRYABLE_ERROR_PATTERNS)
  2991. @staticmethod
  2992. def _is_rate_limited_error(error: Optional[str]) -> bool:
  2993. """Return True if the error string classifies as a rate limit / flood cap.
  2994. Single wrapper around :func:`classify_send_error` so the call sites in
  2995. :meth:`_send_with_retry` share one notion of "is this a rate limit" instead
  2996. of inline copies that could drift.
  2997. """
  2998. return classify_send_error(None, error or "") == "rate_limited"
  2999. @staticmethod
  3000. def _is_timeout_error(error: Optional[str]) -> bool:
  3001. """Return True for read/write timeouts — NOT retryable and NOT a plain-text
  3002. fallback trigger, because the request may already have been delivered."""
  3003. lowered = (error or "").lower()
  3004. return any(pat in lowered for pat in ("timed out", "readtimeout", "writetimeout"))
  3005. def _unwrap_ephemeral(self, response: Any) -> tuple[Optional[str], int]:
  3006. """Unwrap a str/None/:class:`EphemeralReply` response into ``(text, ttl)``. ``ttl > 0``
  3007. means schedule ``_schedule_ephemeral_delete`` after a successful send; forced to 0 when the
  3008. adapter doesn't override ``delete_message`` so non-supporting platforms degrade to normal
  3009. sends."""
  3010. if not isinstance(response, EphemeralReply):
  3011. return response, 0
  3012. ttl = response.ttl_seconds
  3013. if ttl is None:
  3014. ttl = _or_default(lambda: int(self._get_ephemeral_system_ttl_default()), 0, Exception)
  3015. if ttl and ttl > 0 and type(self).delete_message is BasePlatformAdapter.delete_message:
  3016. ttl = 0
  3017. return response.text, int(ttl or 0)
  3018. async def _dispatch_inline_reply(self, event: MessageEvent, *, log_cmd: Optional[str] = None) -> None:
  3019. """Call the handler and send its reply inline, with retry, threading and
  3020. ephemeral deletion — no session lifecycle (active-session bypass paths)."""
  3021. thread_meta = _thread_metadata_for_event(event)
  3022. response = await self._message_handler(event)
  3023. text, eph_ttl = self._unwrap_ephemeral(response)
  3024. if not text:
  3025. return
  3026. if log_cmd is not None:
  3027. logger.info("[%s] Sending command '/%s' response (%d chars) to %s", self.name, log_cmd,
  3028. len(text), event.source.chat_id)
  3029. result = await self._send_with_retry(
  3030. chat_id=event.source.chat_id, content=text, reply_to=_reply_anchor_for_event(event),
  3031. metadata=_mark_notify_metadata(thread_meta))
  3032. if eph_ttl > 0 and result.success and result.message_id:
  3033. self._schedule_ephemeral_delete(event.source.chat_id, result.message_id, eph_ttl)
  3034. def _media_delivery_scope(self, source: Optional[SessionSource]):
  3035. """Routed home + terminal policy for post-handler text, media and error delivery;
  3036. a no-op without a runner or outside multiplexing."""
  3037. resolve = getattr(self.gateway_runner, "_media_delivery_scope_for_source", None)
  3038. if not callable(resolve) or source is None:
  3039. return contextlib.nullcontext()
  3040. try:
  3041. return resolve(source)
  3042. except Exception:
  3043. logger.debug("[%s] Failed to resolve media delivery scope", self.name, exc_info=True)
  3044. return contextlib.nullcontext()
  3045. def _final_delivery_adapter(self, source: Optional[SessionSource]) -> "BasePlatformAdapter":
  3046. """The runner's CURRENT adapter for a new final-response send: a reconnect can swap the
  3047. registry adapter mid-task; an unsent final response belongs on the replacement transport,
  3048. while message IDs, edits and deletes stay owned by the old one (nothing is migrated)."""
  3049. resolve = getattr(self.gateway_runner, "_delivery_adapter_for", None)
  3050. if not callable(resolve):
  3051. return self
  3052. try:
  3053. live_adapter = resolve(source)
  3054. except Exception:
  3055. logger.debug("[%s] Failed to resolve live adapter for final delivery", self.name)
  3056. return self
  3057. if isinstance(live_adapter, BasePlatformAdapter) and live_adapter.platform == self.platform:
  3058. return live_adapter
  3059. return self
  3060. @records_delivery
  3061. async def _send_with_retry(
  3062. self, chat_id: str, content: str, reply_to: Optional[str] = None, metadata: Any = None,
  3063. max_retries: int = 2, base_delay: float = 2.0) -> SendResult:
  3064. """Send with exponential-backoff retry on transient network errors; permanent
  3065. failures fall back to a plain-text send, exhausted retries notify the user."""
  3066. async def _send(text: str) -> SendResult:
  3067. return await self.send(chat_id=chat_id, content=text, reply_to=reply_to, metadata=metadata)
  3068. async def _send_again(previous: SendResult) -> Optional[SendResult]:
  3069. """Retry: the whole payload normally; only the undelivered remainder after a partial split
  3070. delivery (``raw_response["partial_overflow"]``). ``None`` when the adapter cannot resume — the
  3071. caller then keeps the partial failure rather than re-sending the already-visible head."""
  3072. if not self._is_partial_delivery(previous):
  3073. return await _send(content)
  3074. return await self._resume_partial_send(chat_id, previous, reply_to=reply_to, metadata=metadata)
  3075. result = await _send(content)
  3076. if result.success or self._send_retry_is_final(result):
  3077. return result
  3078. error_str = result.error or ""
  3079. # A rate-limited / flood-capped send is transient: it should back off
  3080. # (honoring the server's retry_after when present) rather than fall
  3081. # through to the plain-text fallback, which re-enters the ban and can
  3082. # truncate content. Gate on the platform-neutral classifier as well so
  3083. # platforms that surface a rate limit without a retry_after field
  3084. # (e.g. Weixin raising a bare RuntimeError) get the same treatment.
  3085. is_rate_limited = self._is_rate_limited_error(error_str)
  3086. is_network = (
  3087. result.retryable
  3088. or is_rate_limited
  3089. or result.retry_after is not None
  3090. or self._is_retryable_error(error_str)
  3091. )
  3092. # Timeouts: not safe to retry (may have delivered) and not a formatting error.
  3093. if not is_network and self._is_timeout_error(error_str):
  3094. return result
  3095. if is_network:
  3096. # A server-requested retry_after (Telegram FloodWait) overrides backoff, once per send.
  3097. server_retry_after = result.retry_after
  3098. for attempt in range(1, max_retries + 1):
  3099. backoff = server_retry_after
  3100. if backoff is None:
  3101. backoff = base_delay * (2 ** (attempt - 1))
  3102. elif backoff > _SEND_RETRY_INLINE_WAIT_CAP_SECS:
  3103. # Never hold this coroutine open for a long server penalty: a 97-minute
  3104. # FloodWait slept verbatim once froze inbound on every platform (#91969).
  3105. # Return the typed failure; the delivery ledger redelivers after the cooldown.
  3106. logger.error(
  3107. "[%s] Server asked to retry after %.0fs (> %.0fs inline cap); returning "
  3108. "typed failure for redelivery instead of sleeping: %s",
  3109. self.name, backoff, _SEND_RETRY_INLINE_WAIT_CAP_SECS, error_str,
  3110. )
  3111. return result
  3112. delay = backoff + random.uniform(0, 1)
  3113. server_retry_after = None
  3114. logger.warning("[%s] Send failed (attempt %d/%d, retrying in %.1fs): %s", self.name,
  3115. attempt, max_retries, delay, error_str)
  3116. await asyncio.sleep(delay)
  3117. resumed = await _send_again(result)
  3118. if resumed is None:
  3119. logger.warning(
  3120. "[%s] Split send partly delivered and the remainder cannot be resumed safely; "
  3121. "not re-sending the whole payload (would duplicate the visible head): %s", self.name, error_str)
  3122. return result
  3123. result = resumed
  3124. if result.success:
  3125. logger.info("[%s] Send succeeded on retry %d", self.name, attempt)
  3126. return result
  3127. error_str = result.error or ""
  3128. if self._send_retry_is_final(result):
  3129. return result
  3130. if result.retry_after is not None:
  3131. server_retry_after = result.retry_after
  3132. # The failure kind can change between attempts (a transient error may
  3133. # later surface as a flood/rate-limit, or a rate-limited send may give
  3134. # way to a permanent formatting error). Reclassify from the refreshed
  3135. # error_str on every attempt so the break/continue decision below
  3136. # reflects the current attempt, not a stale first-send classification.
  3137. is_rate_limited = self._is_rate_limited_error(error_str)
  3138. if not (
  3139. result.retryable
  3140. or is_rate_limited
  3141. or result.retry_after is not None
  3142. or self._is_retryable_error(error_str)
  3143. ):
  3144. break # error switched to non-transient — fall through to plain-text fallback
  3145. else:
  3146. # All retries exhausted (loop completed without break) — notify user.
  3147. # If the final failure is a rate-limit / still carries a server
  3148. # retry_after, do NOT send the delivery-failure notice now: the notice
  3149. # send would land inside the same flood penalty and re-enter the ban
  3150. # (a fourth send at t=378 in an [0, 189, 378, 378] sequence). Return
  3151. # the typed failure so the delivery ledger owns redelivery after the
  3152. # cooldown instead — no extra sleep or request needed.
  3153. if self._is_rate_limited_error(error_str) or result.retry_after is not None:
  3154. logger.error(
  3155. "[%s] Rate-limited send exhausted retries; returning typed failure "
  3156. "for redelivery (no notice sent inside active flood penalty): %s",
  3157. self.name, error_str,
  3158. )
  3159. return result
  3160. logger.error("[%s] Failed to deliver response after %d retries: %s", self.name, max_retries, error_str)
  3161. # Not a diagnostic: the requested result itself was lost and this is its only signal.
  3162. notice = t("gateway.notify.delivery_failed_retry")
  3163. try:
  3164. await _send(notice)
  3165. except Exception as notify_err:
  3166. logger.debug("[%s] Could not send delivery-failure notice: %s", self.name, notify_err)
  3167. return result
  3168. # Non-network / post-retry formatting failure: try plain text as fallback. A
  3169. # rate-limited error never reaches here: it classifies as network above and the
  3170. # loop only breaks on a non-transient, non-rate-limited error.
  3171. if self._is_partial_delivery(result):
  3172. # Part of a split payload is already on screen; a plain-text re-send of the whole would duplicate it.
  3173. logger.warning("[%s] Send failed after partial delivery: %s — not re-sending as plain text", self.name, error_str)
  3174. return result
  3175. logger.warning("[%s] Send failed: %s — trying plain-text fallback", self.name, error_str)
  3176. fallback_result = await self._send_plain_fallback(chat_id, content, reply_to=reply_to, metadata=metadata)
  3177. if not fallback_result.success:
  3178. logger.error("[%s] Fallback send also failed: %s", self.name, fallback_result.error)
  3179. return fallback_result
  3180. def _send_retry_is_final(self, result: SendResult) -> bool:
  3181. """True when a failed send must be returned as-is: neither a retry nor the plain-text
  3182. fallback can fix it (a structured auth/target refusal). Default: never."""
  3183. return False
  3184. @staticmethod
  3185. def _is_partial_delivery(result: SendResult) -> bool:
  3186. """True when a split payload was PARTLY delivered (``raw_response["partial_overflow"]``, the
  3187. contract Telegram's send/edit-overflow paths set and the stream consumer reads): the visible
  3188. head must never be sent again."""
  3189. raw = getattr(result, "raw_response", None)
  3190. return isinstance(raw, dict) and bool(raw.get("partial_overflow"))
  3191. async def _resume_partial_send(
  3192. self, chat_id: str, result: SendResult, *, reply_to: Optional[str], metadata: Any) -> Optional[SendResult]:
  3193. """Deliver only the remainder of a partially delivered split payload. ``None`` (the default) means
  3194. this adapter cannot resume; ``_send_with_retry`` then returns the partial failure instead of
  3195. re-sending the whole payload. Override only where non-delivery of the remainder is CERTAIN."""
  3196. return None
  3197. async def _send_plain_fallback(
  3198. self, chat_id: str, content: str, *, reply_to: Optional[str], metadata: Any) -> SendResult:
  3199. """Last-resort send after a non-transient failure; platforms whose markup is not the
  3200. likely culprit override it (Photon drops rich links instead of adding the banner)."""
  3201. return await self.send(
  3202. chat_id=chat_id, content=self.warning_text(
  3203. t("gateway.notify.plain_fallback_prefix", content=content[:3500]), content[:3500],
  3204. chat_id=chat_id, metadata=metadata),
  3205. reply_to=reply_to, metadata=metadata)
  3206. @staticmethod
  3207. def _merge_caption(existing_text: Optional[str], new_text: str) -> str:
  3208. """Merge a new caption into existing text unless an identical (stripped) caption already
  3209. exists — exact match per caption, not substring ("Meeting" isn't swallowed by "Meeting
  3210. agenda")."""
  3211. if not existing_text:
  3212. return new_text
  3213. if new_text.strip() in [c.strip() for c in existing_text.split("\n\n")]:
  3214. return existing_text
  3215. return f"{existing_text}\n\n{new_text}".strip()
  3216. def _text_debounce_store(self) -> dict[str, TextDebounceState]:
  3217. return _lazy_attr(self, "_text_debounce", dict)
  3218. def _is_queue_text_debounce_candidate(self, event: MessageEvent) -> bool:
  3219. """Return True for normal text eligible for queue-mode debounce."""
  3220. result = (
  3221. getattr(self, "_busy_text_mode", "interrupt") == "queue"
  3222. and event.message_type == MessageType.TEXT and not getattr(event, "internal", False)
  3223. and not event.is_command() and bool((event.text or "").strip()))
  3224. if result:
  3225. logger.debug("[%s] Queue-text debounce candidate accepted: session=%s text_len=%d",
  3226. self.name, getattr(event, "session_key", "?"), len(event.text or ""))
  3227. return result
  3228. def _can_merge_text_debounce_events(self, existing: MessageEvent, event: MessageEvent) -> bool:
  3229. """Return True when two text debounce events came from the same sender."""
  3230. def _identity(candidate: MessageEvent) -> tuple[str, ...] | None:
  3231. source = getattr(candidate, "source", None)
  3232. if source is None:
  3233. return None
  3234. platform = _platform_name(getattr(source, "platform", None))
  3235. sender = getattr(source, "user_id_alt", None) or getattr(source, "user_id", None)
  3236. if sender:
  3237. return (platform, str(sender))
  3238. if getattr(source, "chat_type", None) in {"dm", "private"} and getattr(source, "chat_id", None):
  3239. return (platform, "dm", str(source.chat_id))
  3240. return None
  3241. existing_sender = _identity(existing)
  3242. return existing_sender is not None and existing_sender == _identity(event)
  3243. def _text_debounce_delay(self, session_key: str) -> float:
  3244. """Return bounded busy-text debounce delay for ``session_key``."""
  3245. state = self._text_debounce_store().get(session_key)
  3246. if state is None:
  3247. return 0.0
  3248. deadline = min(state.last_ts + self._busy_text_debounce_seconds,
  3249. state.first_ts + self._busy_text_hard_cap_seconds)
  3250. return max(0.0, deadline - time.monotonic())
  3251. async def _queue_text_debounce(self, session_key: str, event: MessageEvent) -> None:
  3252. """Buffer normal queue-mode busy text and schedule a bounded flush."""
  3253. store = self._text_debounce_store()
  3254. state = store.get(session_key)
  3255. if state is not None and not self._can_merge_text_debounce_events(state.event, event):
  3256. # Preserve sender attribution: flush the buffer as the next turn, new sender starts
  3257. # fresh.
  3258. await self._flush_text_debounce_now(session_key)
  3259. state = store.get(session_key)
  3260. if state is not None and not self._can_merge_text_debounce_events(state.event, event):
  3261. existing_pending = self._pending_messages.get(session_key)
  3262. if existing_pending is not None and self._can_merge_text_debounce_events(existing_pending, event):
  3263. merge_pending_message_event(self._pending_messages, session_key, event, merge_text=True)
  3264. return
  3265. now = time.monotonic()
  3266. if state is None:
  3267. state = TextDebounceState(event=event, task=None, first_ts=now, last_ts=now)
  3268. store[session_key] = state
  3269. else:
  3270. if event.text:
  3271. state.event.text = _append_text(state.event.text, event.text)
  3272. state.event.absorb_reply_expected(event)
  3273. latest_message_id = getattr(event, "message_id", None)
  3274. latest_anchor = latest_message_id or getattr(event, "reply_to_message_id", None)
  3275. if latest_message_id is not None:
  3276. state.event.message_id = str(latest_message_id)
  3277. if latest_anchor is not None and hasattr(state.event, "reply_to_message_id"):
  3278. state.event.reply_to_message_id = str(latest_anchor)
  3279. state.last_ts = now
  3280. state.cancel_timer()
  3281. delay = self._text_debounce_delay(session_key)
  3282. state.task = asyncio.create_task(self._flush_text_debounce(session_key, delay))
  3283. async def _flush_text_debounce(self, session_key: str, delay: float) -> None:
  3284. """Timer task that flushes the debounced text buffer."""
  3285. try:
  3286. await asyncio.sleep(delay)
  3287. await self._flush_text_debounce_now(session_key)
  3288. except asyncio.CancelledError:
  3289. return
  3290. finally:
  3291. current = asyncio.current_task()
  3292. state = self._text_debounce_store().get(session_key)
  3293. if state is not None and state.task is current:
  3294. state.task = None
  3295. async def _flush_text_debounce_now(self, session_key: str) -> bool:
  3296. """Force-flush one debounced busy-text burst into the pending slot."""
  3297. store = self._text_debounce_store()
  3298. state = store.get(session_key)
  3299. if state is None:
  3300. return False
  3301. state.cancel_timer(unless=asyncio.current_task())
  3302. state.task = None
  3303. pending = self._pending_messages.get(session_key)
  3304. if pending is not None and not self._can_merge_text_debounce_events(pending, state.event):
  3305. return False
  3306. store.pop(session_key, None)
  3307. merge_pending_message_event(self._pending_messages, session_key, state.event, merge_text=True)
  3308. return True
  3309. def _discard_text_debounce(self, session_key: str) -> None:
  3310. """Cancel and drop pending text debounce state for control commands."""
  3311. state = self._text_debounce_store().pop(session_key, None)
  3312. if state is not None:
  3313. state.cancel_timer()
  3314. from gateway.session_ingress_burst import discard_busy_burst
  3315. discard_busy_burst(self, session_key)
  3316. # ── Session task + guard ownership helpers: paired with the _session_tasks owner map so
  3317. # reconciliation is deterministic across completion, /stop /new /reset, and stale-lock heal.
  3318. def _release_session_guard(self, session_key: str, *, guard: Optional[asyncio.Event] = None) -> None:
  3319. """Release the session guard; with ``guard`` given, only if the entry is still that exact
  3320. Event (an old task's unwind must not clear the guard a reset-like command swapped in)."""
  3321. current_guard = self._active_sessions.get(session_key)
  3322. if current_guard is None or (guard is not None and current_guard is not guard):
  3323. return
  3324. del self._active_sessions[session_key]
  3325. def _session_task_is_stale(self, session_key: str) -> bool:
  3326. """True if the recorded owner task for ``session_key`` has exited. No owner task at all is
  3327. NOT stale (guards installed outside handle_message, as tests do, must not be healed)."""
  3328. done = getattr(self._session_tasks.get(session_key), "done", None)
  3329. return bool(done and done())
  3330. def _heal_stale_session_lock(self, session_key: str) -> bool:
  3331. """Clear a stale session lock; True if healed. On-entry safety net: without it a split-brain
  3332. (guard held, nothing processing) traps the chat in "Interrupting..." until restart."""
  3333. if session_key not in self._active_sessions or not self._session_task_is_stale(session_key):
  3334. return False
  3335. logger.warning("[%s] Healing stale session lock for %s (owner task is done/absent)",
  3336. self.name, session_key)
  3337. self._active_sessions.pop(session_key, None)
  3338. self._pending_messages.pop(session_key, None)
  3339. self._requeue_counts.pop(session_key, None)
  3340. self._session_tasks.pop(session_key, None)
  3341. self._discard_text_debounce(session_key)
  3342. return True
  3343. def _start_session_processing(self, event: MessageEvent, session_key: str, *,
  3344. interrupt_event: Optional[asyncio.Event] = None) -> bool:
  3345. """Spawn a background processing task under the session guard; True on success. If
  3346. ``create_task`` is stubbed with a non-Task sentinel (tests), the guard is rolled back
  3347. (False)."""
  3348. guard = interrupt_event or asyncio.Event()
  3349. self._active_sessions[session_key] = guard
  3350. task = asyncio.create_task(self._process_message_background(event, session_key))
  3351. if not self._track_session_task(session_key, task):
  3352. self._session_tasks.pop(session_key, None)
  3353. self._release_session_guard(session_key, guard=guard)
  3354. return False
  3355. return True
  3356. def _track_session_task(self, session_key: str, task: Any) -> bool:
  3357. """Record ``task`` as the session owner and track it for shutdown; False when
  3358. ``create_task`` was stubbed with an unhashable sentinel (tests) — the owner entry is left
  3359. for the caller."""
  3360. self._session_tasks[session_key] = task
  3361. try:
  3362. self._background_tasks.add(task)
  3363. except TypeError:
  3364. return False
  3365. if hasattr(task, "add_done_callback"):
  3366. task.add_done_callback(self._background_tasks.discard)
  3367. task.add_done_callback(self._expected_cancelled_tasks.discard)
  3368. return True
  3369. async def cancel_session_processing(self, session_key: str, *, release_guard: bool = True,
  3370. discard_pending: bool = True) -> None:
  3371. """Cancel in-flight processing for one session. ``release_guard=False`` keeps the guard so
  3372. reset-like commands finish atomically; the await is bounded (5s) so a wedged finally can't
  3373. stall."""
  3374. self._requeue_counts.pop(session_key, None)
  3375. task = self._session_tasks.pop(session_key, None)
  3376. if task is not None and not task.done():
  3377. logger.debug("[%s] Cancelling active processing for session %s", self.name, session_key)
  3378. self._expected_cancelled_tasks.add(task)
  3379. task.cancel()
  3380. try:
  3381. await asyncio.wait_for(asyncio.shield(task), timeout=5.0)
  3382. except asyncio.CancelledError:
  3383. pass
  3384. except TimeoutError:
  3385. logger.warning("[%s] Cancelled task for %s did not exit within 5s; "
  3386. "unblocking dispatch and letting the task unwind in the background",
  3387. self.name, session_key)
  3388. except Exception:
  3389. logger.debug("[%s] Session cancellation raised while unwinding %s", self.name,
  3390. session_key, exc_info=True)
  3391. if discard_pending:
  3392. self._pending_messages.pop(session_key, None)
  3393. self._discard_text_debounce(session_key)
  3394. if release_guard:
  3395. self._release_session_guard(session_key)
  3396. async def _drain_pending_after_session_command(
  3397. self, session_key: str, command_guard: asyncio.Event) -> None:
  3398. """Tail of /stop, /new, /reset: release the command-scoped guard, then
  3399. spawn a fresh processing task for any follow-up queued meanwhile."""
  3400. await self._flush_text_debounce_now(session_key)
  3401. pending_event = self._pending_messages.pop(session_key, None)
  3402. self._release_session_guard(session_key, guard=command_guard)
  3403. if pending_event is not None:
  3404. self._start_session_processing(pending_event, session_key)
  3405. async def _dispatch_active_session_command(self, event: MessageEvent, session_key: str, cmd: str) -> None:
  3406. """Dispatch a reset-like bypass command (/stop, /new, /reset): keep a guard installed while
  3407. the runner handles it (follow-ups stay queued), cancel the old task AFTER the response,
  3408. drain once."""
  3409. logger.debug("[%s] Command '/%s' bypassing active-session guard for %s", self.name, cmd, session_key)
  3410. current_guard = self._active_sessions.get(session_key)
  3411. command_guard = asyncio.Event()
  3412. self._active_sessions[session_key] = command_guard
  3413. try:
  3414. # Send BEFORE cancelling so cancellation side effects can't drop the "/new"
  3415. # confirmation.
  3416. await self._dispatch_inline_reply(event, log_cmd=cmd)
  3417. await self.cancel_session_processing(session_key, release_guard=False, discard_pending=False)
  3418. except Exception:
  3419. # On failure restore the original guard so the session isn't left half-reset.
  3420. if self._active_sessions.get(session_key) is command_guard:
  3421. if session_key in self._session_tasks and current_guard is not None:
  3422. self._active_sessions[session_key] = current_guard
  3423. else:
  3424. self._release_session_guard(session_key, guard=command_guard)
  3425. raise
  3426. await self._drain_pending_after_session_command(session_key, command_guard)
  3427. async def handle_message(self, event: MessageEvent) -> None:
  3428. """Process an incoming message; returns quickly by spawning a background
  3429. task so new messages (and interrupts) can arrive while an agent runs."""
  3430. event._gateway_accepted = False
  3431. if not self._message_handler:
  3432. # No handler = every inbound silently discarded on an adapter that still polls and sends;
  3433. # say so once per adapter (#102260).
  3434. if not getattr(self, "_no_message_handler_logged", False):
  3435. self._no_message_handler_logged = True
  3436. logger.error(
  3437. "[%s] Dropping inbound message: no gateway message handler "
  3438. "is installed on this adapter. The adapter is connected and "
  3439. "can send, but every inbound message is discarded.",
  3440. self.name,
  3441. )
  3442. return
  3443. if event.allow_gateway_control:
  3444. coerce_plaintext_gateway_command(event)
  3445. # Identity FIRST: every key below (routing check, guard lookup, batch lane) derives from it.
  3446. if self._drop_unresolved(event):
  3447. return
  3448. expected_session_key = str((event.metadata or {}).get("gateway_session_key") or "").strip()
  3449. # Explicitly routed events already name their destination; recovering a
  3450. # different topic would redirect them and yield before the session claim.
  3451. if (not expected_session_key and getattr(self, "_topic_recovery_fn", None) is not None
  3452. and event.source.platform == Platform.TELEGRAM and event.source.chat_type == "dm"):
  3453. await asyncio.to_thread(self._apply_topic_recovery, event)
  3454. session_key = self._event_session_key(event)
  3455. if expected_session_key and session_key != expected_session_key:
  3456. logger.warning("Dropping internally routed event: expected session=%s derived=%s",
  3457. expected_session_key, session_key)
  3458. return
  3459. from gateway.session_ingress_burst import burst_gate
  3460. behind_burst = await burst_gate(self, event, session_key) # a serial reader's command waits too
  3461. # On-entry self-heal: clear a guard whose owner task already exited.
  3462. if session_key in self._active_sessions:
  3463. self._heal_stale_session_lock(session_key)
  3464. if session_key in self._active_sessions or behind_burst:
  3465. await self._handle_message_while_active(event, session_key)
  3466. return
  3467. # Guard installed synchronously BEFORE the task spawns so a second message can't race in.
  3468. event._gateway_accepted = self._start_session_processing(event, session_key)
  3469. def _shared_runtime_owns_input(self, event: MessageEvent) -> bool:
  3470. """True when a non-command input belongs to the shared runtime's session authority."""
  3471. runner = getattr(self._message_handler, '__self__', None)
  3472. return getattr(runner, 'session_authority', None) is not None and not event.get_command()
  3473. def _pending_recovery_owners(self, event: MessageEvent, session_key: str) -> list:
  3474. """Adapters whose pending slot may hold *event* after busy admission: this one, plus the
  3475. runner's current delivery adapter for its source when that replacement has no live guard."""
  3476. owners = [self]
  3477. runner = getattr(self, "gateway_runner", None)
  3478. if runner is not None:
  3479. try:
  3480. delivery_adapter = runner._delivery_adapter_for(event.source)
  3481. except Exception:
  3482. delivery_adapter = None
  3483. logger.debug("[%s] Delivery-adapter lookup failed during pending recovery",
  3484. self.name, exc_info=True)
  3485. if (delivery_adapter is not None and delivery_adapter is not self
  3486. and session_key not in delivery_adapter._active_sessions):
  3487. owners.append(delivery_adapter)
  3488. return owners
  3489. async def _handle_message_while_active(self, event: MessageEvent, session_key: str) -> None:
  3490. """Route a message that arrived while ``session_key`` is busy: bypass
  3491. commands / clarify replies dispatch inline, everything else is queued."""
  3492. # The shared runtime's durable FIFO replaces the adapter's busy-message slot.
  3493. if self._shared_runtime_owns_input(event):
  3494. from gateway.session_ingress_burst import dispatch_busy_burst
  3495. await dispatch_busy_burst(self, event, session_key) # main's photo/text burst merge
  3496. return
  3497. # Bypass commands run inline: queued they'd leak as user text (/new) or deadlock
  3498. # (/approve, /deny — the agent is blocked on Event.wait). Dispatch inline by
  3499. # calling the message handler directly and sending the response. Do NOT use
  3500. # _process_message_background — it manages session lifecycle and its cleanup
  3501. # races with the running task (split-brain, see PR #4926).
  3502. # Certain commands must bypass the active-session guard and be dispatched directly to the gateway
  3503. # runner. Without this, they are queued as pending messages and either: See #4926.
  3504. self._canonicalize(event.source) # identity FIRST (direct callers may skip handle_message)
  3505. cmd = event.get_command()
  3506. from hermes_cli.commands import (is_interrupt_then_dispatch, should_bypass_active_session)
  3507. if should_bypass_active_session(cmd):
  3508. try:
  3509. # /stop, /new, /reset: cancel + response + drain; other bypasses don't cancel.
  3510. if cmd and is_interrupt_then_dispatch(cmd):
  3511. self._discard_text_debounce(session_key)
  3512. await self._dispatch_active_session_command(event, session_key, cmd)
  3513. else:
  3514. logger.debug("[%s] Command '/%s' bypassing active-session guard for %s",
  3515. self.name, cmd, session_key)
  3516. await self._dispatch_inline_reply(event)
  3517. except Exception as e:
  3518. logger.error("[%s] Command '/%s' dispatch failed: %s", self.name, cmd, e, exc_info=True)
  3519. return
  3520. # Clarify bypass: while blocked on clarify_tool the next message must reach the
  3521. # text-intercept so numeric/exact/"Other" answers resolve it and unblock the agent.
  3522. # Otherwise it lands in _pending_messages as a follow-up turn and the answer is
  3523. # discarded. Same shape as the /approve deadlock fix (PR #4926): agent thread
  3524. # blocked on Event.wait, message must reach the resolver before being a new turn.
  3525. # See #4926.
  3526. if not cmd and event.allow_gateway_control:
  3527. try:
  3528. from tools import clarify_gateway as _clarify_mod
  3529. _has_text_clarify = _clarify_mod.get_pending_for_session(
  3530. session_key, include_choice_prompts=True) is not None
  3531. except Exception:
  3532. _has_text_clarify = False
  3533. if _has_text_clarify:
  3534. logger.debug("[%s] Routing message to clarify text-intercept for %s", self.name, session_key)
  3535. try:
  3536. await self._dispatch_inline_reply(event)
  3537. except Exception as e:
  3538. logger.error("[%s] Clarify text-intercept dispatch failed: %s", self.name, e, exc_info=True)
  3539. return
  3540. if self._busy_session_handler is not None:
  3541. try:
  3542. handled = await self._busy_session_handler(event, session_key)
  3543. except Exception as e:
  3544. logger.error("[%s] Busy-session handler failed: %s", self.name, e, exc_info=True)
  3545. # It may have stored the event before raising: queuing or starting it again below
  3546. # would run it twice.
  3547. handled = event._gateway_accepted is True
  3548. # The handler awaits (profile scope load, compression-lock read). If the owner task
  3549. # finished meanwhile, it found the slot empty and released the guard, so nothing would
  3550. # drain what the handler queued: start that now. If the handler left this event to the
  3551. # base path instead (returned False, or raised before storing it) and nothing is
  3552. # queued, start this event.
  3553. if session_key not in self._active_sessions:
  3554. # Busy admission queues through the delivery adapter resolved when it stored the
  3555. # event; a reconnect during the handler's later awaits can replace that adapter.
  3556. # Recover from whichever slot actually holds it — this one, or the replacement —
  3557. # and start it on that slot's owner. A replacement with a live guard drains its
  3558. # own slot, so leave that one alone.
  3559. orphan = None
  3560. for owner in self._pending_recovery_owners(event, session_key):
  3561. orphan = owner.get_pending_message(session_key)
  3562. if orphan is not None:
  3563. owner._start_session_processing(orphan, session_key)
  3564. break
  3565. if orphan is None and not handled:
  3566. event._gateway_accepted = self._start_session_processing(event, session_key)
  3567. return
  3568. if handled:
  3569. return
  3570. # Without a runner FIFO, do not merge a wake into an occupied human slot
  3571. # (or collapse distinct wakes into one turn). Its caller can retry admission.
  3572. if event.internal and session_key in self._pending_messages:
  3573. return
  3574. # Photo bursts/albums: queue without interrupting; they run after the current task.
  3575. if event.message_type == MessageType.PHOTO:
  3576. logger.debug("[%s] Queuing photo follow-up for session %s without interrupt", self.name, session_key)
  3577. merge_pending_message_event(self._pending_messages, session_key, event)
  3578. event._gateway_accepted = True
  3579. return
  3580. if self._is_queue_text_debounce_candidate(event):
  3581. logger.debug("[%s] New text message while session %s is active — "
  3582. "debouncing follow-up (busy_text_mode=queue, window=%.2fs)", self.name,
  3583. session_key, self._busy_text_debounce_seconds)
  3584. await self._queue_text_debounce(session_key, event)
  3585. else:
  3586. logger.debug("[%s] New message while session %s is active — queuing follow-up "
  3587. "(no interrupt, will cascade after current turn)", self.name, session_key)
  3588. merge_pending_message_event(self._pending_messages, session_key, event,
  3589. merge_text=event.message_type == MessageType.TEXT)
  3590. event._gateway_accepted = True
  3591. def _get_human_delay(self) -> float:
  3592. """Random human-like pacing delay (s) from this adapter's ``human_delay`` config range
  3593. (ms), installed per profile by the runner (``_wire_adapter_handlers``); ``None`` = off."""
  3594. bounds = self._human_delay_range_ms
  3595. if not bounds:
  3596. return 0.0
  3597. lo, hi = bounds
  3598. return random.uniform(lo / 1000.0, hi / 1000.0)
  3599. async def _synthesize_auto_tts(self, text_content: str) -> tuple[list[str], Optional[str]]:
  3600. """Synthesize auto-TTS audio -> ``(existing_paths, requested_path)``; empty/None on failure
  3601. (logged, never raised). Path built platform-aware HERE: HERMES_SESSION_PLATFORM is cleared
  3602. post-handler."""
  3603. paths: list[str] = []
  3604. requested_path = None
  3605. try:
  3606. from tools.tts_tool import text_to_speech_tool, check_tts_requirements
  3607. if check_tts_requirements():
  3608. import json as _json
  3609. speech_text = self.prepare_tts_text(text_content)
  3610. if not speech_text:
  3611. raise ValueError("Empty text after markdown cleanup")
  3612. requested_path = build_auto_tts_output_path(self.platform)
  3613. tts_data = _json.loads(await asyncio.to_thread(
  3614. text_to_speech_tool, text=speech_text, output_path=requested_path))
  3615. if tts_data.get("success", True):
  3616. raw_tts_paths = tts_data.get("file_paths") or [tts_data.get("file_path")]
  3617. paths = [str(path) for path in raw_tts_paths if path and Path(path).exists()]
  3618. except Exception as tts_err:
  3619. logger.warning("[%s] Auto-TTS failed: %s", self.name, tts_err)
  3620. return paths, requested_path
  3621. def _wants_auto_tts(self, event: MessageEvent, session_key: str, interrupt_event: asyncio.Event,
  3622. text_content: str, media_files: list) -> bool:
  3623. """Auto-TTS on voice input (voice-first), gated by /voice or voice.auto_tts;
  3624. skipped when streaming TTS already delivered audio this turn."""
  3625. generation = getattr(interrupt_event, "_hermes_run_generation", None)
  3626. return bool(
  3627. self._should_auto_tts_for_chat(event.source.chat_id)
  3628. and event.message_type == MessageType.VOICE and text_content and not media_files
  3629. and not self._streaming_tts_turn_completed(session_key, generation, event=event))
  3630. async def _play_tts_file(
  3631. self, event: MessageEvent, text_content: str, tts_path: str, first: bool,
  3632. metadata: dict[str, Any], record_delivery: Callable) -> bool:
  3633. """Play one synthesized TTS file. Returns True when the ORIGINAL reply text rode
  3634. along as a Telegram caption (first file, ≤1024 chars) so the text send is skipped."""
  3635. caption = None
  3636. if first and self.platform == Platform.TELEGRAM and text_content and text_content[:1024] == text_content:
  3637. caption = text_content
  3638. tts_result = await self.play_tts(
  3639. chat_id=event.source.chat_id, audio_path=tts_path, caption=caption, metadata=metadata)
  3640. record_delivery(tts_result)
  3641. return bool(caption and getattr(tts_result, "success", False))
  3642. async def _record_delivery_obligation(
  3643. self, event: MessageEvent, session_key: str, text_content: str,
  3644. delivery_adapter: "BasePlatformAdapter", is_ephemeral_response: bool) -> Optional[str]:
  3645. """Ledger the final response BEFORE the send so a crash before platform ACK redelivers on
  3646. next boot; best-effort, skips slash-command and ephemeral replies. Returns the obligation id
  3647. or None."""
  3648. if is_ephemeral_response or str(event.text or "").lstrip().startswith(
  3649. ("/", self.typed_command_prefix or "!")):
  3650. return None
  3651. try:
  3652. from gateway.delivery_ledger import (
  3653. compute_obligation_id, ledger_enabled, mark_attempting, record_obligation)
  3654. if not await asyncio.to_thread(ledger_enabled):
  3655. return None
  3656. source = event.source
  3657. # ``ledger_message_id`` wins when set: a queued chain's final answers the last message
  3658. # of the chain, not the event that opened it (see ``MessageEvent.ledger_message_id``).
  3659. _ledger_id = getattr(event, "ledger_message_id", None)
  3660. if _ledger_id is None:
  3661. _ledger_id = getattr(event, "message_id", "")
  3662. obligation_id = compute_obligation_id(
  3663. session_key, str(_ledger_id or ""), text_content)
  3664. await asyncio.to_thread(
  3665. record_obligation, obligation_id=obligation_id, session_key=session_key,
  3666. platform=str(getattr(source.platform, "value", source.platform)),
  3667. chat_id=source.chat_id, thread_id=getattr(source, "thread_id", None),
  3668. content=text_content,
  3669. adapter_profile=getattr(delivery_adapter, "_owner_profile", None))
  3670. await asyncio.to_thread(mark_attempting, obligation_id)
  3671. return obligation_id
  3672. except Exception:
  3673. logger.debug("delivery ledger record failed", exc_info=True)
  3674. return None
  3675. async def _finalize_delivery_obligation(
  3676. self, obligation_id: str, result: Any, event: MessageEvent,
  3677. delivery_adapter: "BasePlatformAdapter") -> None:
  3678. """Mark the ledger row delivered/failed (best-effort). On ``send_path_degraded`` with a
  3679. replacement adapter live, trigger another redelivery sweep (the watcher's may have run
  3680. before this failure landed; atomic claiming keeps it idempotent). On any other rejection arm
  3681. the runner's timed redelivery, so the reply goes out once the flood penalty or the retry
  3682. backoff has passed instead of waiting for the next restart (#91653)."""
  3683. try:
  3684. from gateway.dead_targets import classify_dead_error
  3685. from gateway.delivery_ledger import is_reconnect_only, mark_delivered, mark_failed
  3686. if getattr(result, "success", False):
  3687. await asyncio.to_thread(mark_delivered, obligation_id)
  3688. return
  3689. error = str(getattr(result, "error", "") or "")
  3690. await asyncio.to_thread(mark_failed, obligation_id, error)
  3691. if is_reconnect_only(error):
  3692. redeliver = getattr(
  3693. self.gateway_runner, "_redeliver_failed_obligations_for_platform", None)
  3694. live = self._final_delivery_adapter(event.source)
  3695. if live is not delivery_adapter and callable(redeliver):
  3696. await redeliver(event.source.platform,
  3697. profile=getattr(delivery_adapter, "_owner_profile", None))
  3698. elif classify_dead_error(error) is None: # a dead chat is never retried: no timer to wake
  3699. schedule = getattr(self.gateway_runner, "_schedule_flood_redelivery", None)
  3700. if callable(schedule):
  3701. schedule(event.source.platform,
  3702. profile=getattr(delivery_adapter, "_owner_profile", None))
  3703. except Exception:
  3704. logger.debug("delivery ledger update failed", exc_info=True)
  3705. async def _deliver_media_attachments(
  3706. self, event: MessageEvent, media_files: list, local_files: list, *,
  3707. force_document_attachments: bool, human_delay: float, metadata: dict[str, Any],
  3708. record_delivery: Callable) -> None:
  3709. """Deliver MEDIA-tag files and detected local files by type: images batched via
  3710. ``send_multiple_images`` unless ``[[as_document]]``; otherwise audio → send_voice (MEDIA
  3711. tags only, never bare local files), video → send_video, else send_document. Every failure is
  3712. reported. Each send feeds ``record_delivery`` so media-only turns report SUCCESS."""
  3713. from urllib.parse import quote as _quote
  3714. def _as_image(path: str) -> bool:
  3715. return Path(path).suffix.lower() in _IMAGE_EXTS and not force_document_attachments
  3716. _image_paths = [p for p, is_voice in media_files if not is_voice and _as_image(p)]
  3717. _image_paths += [p for p in local_files if _as_image(p)]
  3718. if _image_paths:
  3719. await self._send_image_batch(
  3720. event, [(f"file://{_quote(p)}", "") for p in _image_paths], metadata, human_delay,
  3721. record_delivery)
  3722. chat_id = event.source.chat_id
  3723. async def _send_one(path: str, *, is_voice: bool, media_tag: bool) -> SendResult:
  3724. """MEDIA tags may route to send_voice (bare files never); an adapter's own failure notice is not repeated."""
  3725. ext = Path(path).suffix.lower()
  3726. if media_tag and should_send_media_as_audio(self.platform, ext, is_voice=is_voice):
  3727. result = await self.send_voice(chat_id=chat_id, audio_path=path, metadata=metadata, is_voice=is_voice)
  3728. elif ext in _VIDEO_EXTS:
  3729. if media_tag:
  3730. logger.info("[%s] Sending video attachment (%s) to %s", self.name, ext, chat_id)
  3731. result = await self.send_video(chat_id=chat_id, video_path=path, metadata=metadata)
  3732. else:
  3733. result = await self.send_document(chat_id=chat_id, file_path=path, metadata=metadata)
  3734. if not result.success:
  3735. logger.warning("[%s] Failed to send %s (%s): %s", self.name,
  3736. "media" if media_tag else "local file", ext, result.error)
  3737. if not (isinstance(result.raw_response, dict) and result.raw_response.get("failure_notice_sent")):
  3738. await self._notify_media_delivery_failure(chat_id, path, is_voice=is_voice, metadata=metadata)
  3739. return result
  3740. queue = [(p, v, True) for p, v in media_files if v or not _as_image(p)]
  3741. if queue:
  3742. logger.info("[%s] Delivering %d non-image MEDIA attachment(s)", self.name, len(queue))
  3743. queue += [(p, False, False) for p in local_files if not _as_image(p)]
  3744. for path, is_voice, media_tag in queue:
  3745. if human_delay > 0:
  3746. await asyncio.sleep(human_delay)
  3747. try:
  3748. record_delivery(await _send_one(path, is_voice=is_voice, media_tag=media_tag))
  3749. except Exception as err:
  3750. record_delivery(SendResult(success=False, error=str(err)))
  3751. if media_tag:
  3752. logger.warning("[%s] Error sending media: %s", self.name, err)
  3753. else:
  3754. logger.error("[%s] Error sending local file %s: %s", self.name, path, err)
  3755. async def _send_image_batch(
  3756. self, event: MessageEvent, images: list, metadata: dict[str, Any], human_delay: float,
  3757. record_delivery: Callable) -> None:
  3758. """Batch-send images; a failure is logged (never raised) so other attachments still go.
  3759. The batch result feeds ``record_delivery`` so media-only turns report their real
  3760. outcome instead of FAILURE."""
  3761. try:
  3762. result = await self.send_multiple_images(
  3763. chat_id=event.source.chat_id, images=images, metadata=metadata, human_delay=human_delay)
  3764. except Exception as batch_err:
  3765. logger.warning("[%s] Error batching images: %s", self.name, batch_err, exc_info=True)
  3766. record_delivery(SendResult(success=False, error=str(batch_err)))
  3767. return
  3768. record_delivery(result)
  3769. async def send_final_ledgered(
  3770. self, event: MessageEvent, session_key: str, text_content: str, metadata: dict[str, Any], *,
  3771. reply_to: Optional[str], is_ephemeral_response: bool = False,
  3772. ) -> "tuple[SendResult, BasePlatformAdapter]":
  3773. """The delivery-ledger bracket every final text goes through, on the CURRENT transport
  3774. (a reconnect may have replaced this adapter): record the obligation before the send,
  3775. send with retry, finalize from the result — so a refused final (flood control, a dead
  3776. transport) leaves a ledger row the boot sweep / runtime redelivery can act on. ``event``
  3777. supplies the source and the ledger identity (``ledger_message_id`` or ``message_id``).
  3778. Returns the result with the adapter that sent it: that adapter owns ``result.message_id``
  3779. (an ephemeral delete must go to the same transport)."""
  3780. delivery_adapter = self._final_delivery_adapter(event.source)
  3781. logger.info("[%s] Sending response (%d chars) to %s", delivery_adapter.name,
  3782. len(text_content), event.source.chat_id)
  3783. obligation_id = await self._record_delivery_obligation(
  3784. event, session_key, text_content, delivery_adapter, is_ephemeral_response)
  3785. if obligation_id is not None:
  3786. await self._release_turn_marker(event) # the ledger now owns the crash recovery
  3787. result = await delivery_adapter._send_with_retry(
  3788. chat_id=event.source.chat_id, content=text_content, reply_to=reply_to, metadata=metadata)
  3789. stop_reply_clock(delivery_adapter, event.source.chat_id, result)
  3790. if obligation_id is not None:
  3791. await self._finalize_delivery_obligation(obligation_id, result, event, delivery_adapter)
  3792. return result, delivery_adapter
  3793. async def _release_turn_marker(self, event: MessageEvent) -> None:
  3794. """Clear the crash marker handed to this delivery lifecycle only once the final reply is ledgered or
  3795. nothing more is owed (no kill leaves a persisted reply with neither), then wake the drain. Idempotent."""
  3796. if (getattr(event, "_turn_marker_handoff", False) and getattr(event, "_gateway_active_turn_token", None)
  3797. and self.gateway_runner is not None):
  3798. await self.gateway_runner._clear_durable_active_turn(event)
  3799. getattr(event, "_gateway_marker_released", asyncio.Event()).set()
  3800. async def _send_final_text(
  3801. self, event: MessageEvent, session_key: str, text_content: str, metadata: dict[str, Any],
  3802. is_ephemeral_response: bool, ephemeral_ttl: int, record_delivery: Callable) -> None:
  3803. """Normal-lane final: the ledger bracket plus the message-id owner's ephemeral delete."""
  3804. result, delivery_adapter = await self.send_final_ledgered(
  3805. event, session_key, text_content, metadata,
  3806. reply_to=_reply_anchor_for_event(event), is_ephemeral_response=is_ephemeral_response)
  3807. record_delivery(result)
  3808. if ephemeral_ttl and ephemeral_ttl > 0 and result.success and result.message_id:
  3809. delivery_adapter._schedule_ephemeral_delete(event.source.chat_id, result.message_id, ephemeral_ttl)
  3810. async def _notify_turn_error(self, event: MessageEvent, e: BaseException) -> Optional[dict]:
  3811. """Tell the user a turn failed rather than leaving radio silence (last resort:
  3812. a failing notice is logged, never raised). Returns the thread metadata used."""
  3813. _thread_metadata = None
  3814. try:
  3815. _thread_metadata = _thread_metadata_for_event(event)
  3816. error_detail = str(e)[:300] if str(e) else t("gateway.notify.turn_error_no_details")
  3817. # Only the policy reads bind the routed profile; the send stays in the launch scope
  3818. # as before, so delivery bookkeeping keeps landing where boot-time recovery reads it.
  3819. with self._media_delivery_scope(event.source):
  3820. content = None if diagnostic_wake_muted(event) else self.warning_text(
  3821. t("gateway.notify.turn_error_detailed", error_type=type(e).__name__, error_detail=error_detail),
  3822. t("gateway.notify.turn_error"),
  3823. logical_platform=event.source.platform, chat_id=event.source.chat_id, metadata=_thread_metadata)
  3824. if content is None:
  3825. return _thread_metadata
  3826. await self.send(chat_id=event.source.chat_id, content=content, metadata=_thread_metadata)
  3827. except Exception as notify_err:
  3828. logger.error(
  3829. "[%s] Failed to send error notification to user: %s", self.name, notify_err, exc_info=True)
  3830. return _thread_metadata
  3831. async def _deliver_attachments(self, event: MessageEvent, extracted: _ExtractedResponse,
  3832. metadata: dict[str, Any], *, anything_sent: bool,
  3833. record_delivery: Callable) -> None:
  3834. """Send extracted image URLs, MEDIA files and bare local files (human-paced),
  3835. then fail loudly if a non-empty response produced nothing deliverable. Attachment
  3836. results feed ``record_delivery`` so the turn outcome reflects them."""
  3837. human_delay = self._get_human_delay()
  3838. images, media_files, local_files = extracted.images, extracted.media_files, extracted.local_files
  3839. if images:
  3840. logger.info("[%s] Extracted %d image(s) to send as attachments", self.name, len(images))
  3841. await self._send_image_batch(event, images, metadata, human_delay, record_delivery)
  3842. await self._deliver_media_attachments(
  3843. event, media_files, local_files,
  3844. force_document_attachments=extracted.force_document_attachments,
  3845. human_delay=human_delay, metadata=metadata, record_delivery=record_delivery)
  3846. if not (anything_sent or images or local_files or media_files) and extracted.pre_extract.strip():
  3847. logger.error("[%s] response_delivery_dropped: non-empty response "
  3848. "(%d chars) produced no delivered message or attachment "
  3849. "for %s (empty after extract, recovery yielded nothing).", self.name,
  3850. len(extracted.pre_extract), event.source.chat_id)
  3851. def _start_typing_refresh(self, event: MessageEvent, interrupt_event: asyncio.Event,
  3852. metadata: Optional[dict]) -> Optional[asyncio.Task]:
  3853. """Spawn the typing-refresh task, or None when ``typing_indicator=False``.
  3854. ``stop_event`` is passed only when the (possibly overridden) ``_keep_typing`` accepts it."""
  3855. # A scheduled heartbeat is proactive work: no typing indicator until it has something to say.
  3856. if not getattr(self.config, "typing_indicator", True) or getattr(event, "_heartbeat_session_id", None):
  3857. return None
  3858. kwargs: dict[str, Any] = {"metadata": metadata}
  3859. if self._accepts_kwarg(self._keep_typing, "stop_event", var_kw=False, unknown=True):
  3860. kwargs["stop_event"] = interrupt_event
  3861. return asyncio.create_task(self._keep_typing(event.source.chat_id, **kwargs))
  3862. async def _extract_response_content(self, response: str, event: MessageEvent, session_key: str,
  3863. *, is_ephemeral_response: bool) -> _ExtractedResponse:
  3864. """Split a handler response into deliverable text + attachments. Order matters: MEDIA tags →
  3865. image URLs → residual directives → bare local paths (skipped for ephemeral notices so config
  3866. paths stay text; unknown-extension MEDIA tags survive for the bare-path detector). History
  3867. dedup is bare-path only, off-loop, fail-open. An emptied non-empty response is recovered."""
  3868. # Captured before extract_media strips it: images then go via send_document (no recompression).
  3869. force_document = "[[as_document]]" in response
  3870. pre_extract = response
  3871. # The handler's routed profile scope is gone by now; Docker MEDIA translation and the
  3872. # bare-path validator infer the sandbox from the ACTIVE profile (#109024).
  3873. with self._media_delivery_scope(event.source):
  3874. media_files, response = self.extract_media(response)
  3875. media_files = self.filter_media_delivery_paths(media_files, session_key=session_key)
  3876. images, text_content = self.extract_images(response)
  3877. # Strip any remaining internal directives from message body (fixes #1561). _strip_media_directives
  3878. # shares MEDIA_TAG_CLEANUP_RE, so a MEDIA: tag with an unknown extension is intentionally left in
  3879. # the body for extract_local_files below to pick up rather than silently dropped (#34517).
  3880. text_content = _strip_media_directives(text_content).strip()
  3881. if images:
  3882. logger.info("[%s] extract_images found %d image(s) in response (%d chars)", self.name, len(images), len(response))
  3883. local_files = []
  3884. if not is_ephemeral_response:
  3885. local_files, text_content = self.extract_local_files(text_content)
  3886. local_files = self.filter_local_delivery_paths(local_files, session_key=session_key)
  3887. history = (await self._bounded_history_media_paths_for_session(session_key)
  3888. if local_files else None)
  3889. if history:
  3890. suppressed = [p for p in local_files if p in history]
  3891. if suppressed:
  3892. logger.info("[%s] Suppressing %d bare local file path(s) already delivered in "
  3893. "this session: %s", self.name, len(suppressed), suppressed)
  3894. local_files = [p for p in local_files if p not in history]
  3895. if local_files:
  3896. logger.info("[%s] extract_local_files found %d file(s) in response", self.name, len(local_files))
  3897. # A2 (#29346): extraction can reduce a non-empty response to empty text with no attachment, and the
  3898. # `if text_content` guard below then drops it silently. Recover on every platform (#33842 was
  3899. # Discord-only); the guard avoids duplicating an attachment.
  3900. if not (text_content or images or local_files or media_files):
  3901. _recovered = _strip_media_directives(response).strip()
  3902. if _recovered:
  3903. logger.warning("[%s] response_delivery_recovered: extract pipeline "
  3904. "reduced a non-empty response (%d chars) to empty with "
  3905. "no attachment; delivering recovered original to %s", self.name,
  3906. len(pre_extract), event.source.chat_id)
  3907. text_content = _recovered
  3908. return _ExtractedResponse(
  3909. text_content=text_content, images=images, media_files=media_files,
  3910. local_files=local_files, force_document_attachments=force_document, pre_extract=pre_extract)
  3911. async def _fire_post_delivery_callback(self, session_key: str, interrupt_event: asyncio.Event) -> None:
  3912. """Run the one-shot post-delivery callback (bounded, errors swallowed). The generation is
  3913. read HERE — stamped on the interrupt event DURING the handler await; an earlier snapshot
  3914. would let stale runs fire a fresher run's callbacks."""
  3915. await run_post_delivery_callback(self.pop_post_delivery_callback(
  3916. session_key, generation=getattr(interrupt_event, "_hermes_run_generation", None)),
  3917. _POST_DELIVERY_CALLBACK_TIMEOUT_SECONDS)
  3918. def _finish_session_task(self, session_key: str, interrupt_event: asyncio.Event) -> None:
  3919. """End-of-task guard/ownership reconciliation. A late ``_pending_messages`` arrival must not
  3920. drop: re-queue it if another task already owns the session (drain handoff), else spawn the
  3921. drain task and leave it the guard. Nothing pending: release the guard only if we still own
  3922. it."""
  3923. late_pending = self._pending_messages.pop(session_key, None)
  3924. current_task = asyncio.current_task()
  3925. if late_pending is not None:
  3926. existing_task = self._session_tasks.get(session_key)
  3927. if existing_task is not None and existing_task is not current_task:
  3928. # The in-band drain (or an earlier late-arrival drain) already spawned a follow-up task that
  3929. # owns this session. Re-queue the late-arrival event so that task picks it up — avoids
  3930. # spawning two concurrent _process_message_background tasks for the same key (#17758
  3931. # follow-up: prevents the create_task path from racing with itself across the
  3932. # in-band/finally boundary).
  3933. self._pending_messages[session_key] = late_pending
  3934. else:
  3935. logger.debug(
  3936. "[%s] Late-arrival pending message during cleanup — spawning drain task",
  3937. self.name)
  3938. self._spawn_drain_task(late_pending, session_key)
  3939. elif current_task is not None and self._session_tasks.get(session_key) is current_task:
  3940. self._cleanup_finished_session_task(session_key, interrupt_event)
  3941. async def _process_message_background(self, event: MessageEvent, session_key: str) -> None:
  3942. """Background task that actually processes the message."""
  3943. delivery_attempted = delivery_succeeded = False # feeds the processing-complete hook
  3944. def _record_delivery(result):
  3945. nonlocal delivery_attempted, delivery_succeeded
  3946. if result is not None:
  3947. delivery_attempted = True
  3948. delivery_succeeded = delivery_succeeded or bool(getattr(result, "success", False))
  3949. # Reuse the interrupt event handle_message() installed; new Event only if removed externally.
  3950. interrupt_event = self._active_sessions.get(session_key) or asyncio.Event()
  3951. self._active_sessions[session_key] = interrupt_event
  3952. _thread_metadata = _thread_metadata_for_event(event)
  3953. _typing_metadata = typing_metadata_for_turn( # fixed now: a later inbound must not move it
  3954. self, event.source.chat_id, _reply_anchor_for_event(event), _thread_metadata)
  3955. typing_task = self._start_typing_refresh(event, interrupt_event, _typing_metadata)
  3956. try:
  3957. await self._run_processing_hook("on_processing_start", event)
  3958. event._turn_marker_handoff = self.gateway_runner is not None # it can release the marker
  3959. response = await self._message_handler(event)
  3960. # A muted diagnostic wake ran for the session; its reply is not presented. The
  3961. # policy read binds the routed profile; delivery itself stays in the launch scope.
  3962. with self._media_delivery_scope(event.source):
  3963. if diagnostic_wake_muted(event):
  3964. response = None
  3965. is_ephemeral_response = isinstance(response, EphemeralReply)
  3966. # Unwrap EphemeralReply for downstream text processing; TTL applies after send.
  3967. response, _ephemeral_ttl = self._unwrap_ephemeral(response)
  3968. # None/empty is normal (streamed/queued). Suppress a stale response after an interrupt.
  3969. if response and interrupt_event.is_set() and session_key in self._pending_messages:
  3970. logger.info("[%s] Suppressing stale response for interrupted session %s", self.name,
  3971. session_key)
  3972. response = None
  3973. if not response:
  3974. logger.debug("[%s] Handler returned empty/None response for %s", self.name, event.source.chat_id)
  3975. else:
  3976. extracted = await self._extract_response_content(
  3977. response, event, session_key, is_ephemeral_response=is_ephemeral_response)
  3978. text_content, media_files = extracted.text_content, extracted.media_files
  3979. # Final content gets notify=True; typing metadata stays unmarked (thread-strict).
  3980. _final_thread_metadata = _mark_notify_metadata(_thread_metadata)
  3981. _tts_paths, _tts_requested_path = [], None
  3982. if self._wants_auto_tts(
  3983. event, session_key, interrupt_event, text_content, media_files):
  3984. _tts_paths, _tts_requested_path = await self._synthesize_auto_tts(text_content)
  3985. # TTS plays before text; generated files are removed afterwards.
  3986. _tts_caption_delivered = False
  3987. for _tts_index, _tts_path in enumerate(_tts_paths):
  3988. try:
  3989. _tts_caption_delivered |= await self._play_tts_file(
  3990. event, text_content, _tts_path, _tts_index == 0, _final_thread_metadata,
  3991. _record_delivery)
  3992. finally:
  3993. with contextlib.suppress(OSError):
  3994. os.remove(_tts_path)
  3995. if not _tts_paths and _tts_requested_path is not None:
  3996. with contextlib.suppress(OSError):
  3997. os.remove(_tts_requested_path)
  3998. # Suspend the typing refresh before the first delivery attempt, not just in
  3999. # the turn's finally (#117300): if the final send stalls (platform accepted it
  4000. # but the HTTP ack never returns), control never reaches the finally, and
  4001. # _keep_typing keeps refreshing sendChatAction forever while the agent is
  4002. # already idle and the user can read the answer. Reuse the existing
  4003. # _typing_paused mechanism: _keep_typing skips paused chats each tick and
  4004. # _stop_typing_refresh's finally discards it, so it cannot leak into the next
  4005. # turn. No new await on the delivery path (a fire-and-forget stop task was
  4006. # measured to have no effect).
  4007. if text_content or extracted.images or extracted.media_files or extracted.local_files \
  4008. or _tts_paths or _tts_caption_delivered:
  4009. self.pause_typing_for_chat(event.source.chat_id)
  4010. if text_content and not _tts_caption_delivered:
  4011. await self._send_final_text(
  4012. event, session_key, text_content, _final_thread_metadata,
  4013. is_ephemeral_response, _ephemeral_ttl, _record_delivery)
  4014. await self._deliver_attachments(
  4015. event, extracted, _final_thread_metadata,
  4016. anything_sent=delivery_attempted or _tts_caption_delivered,
  4017. record_delivery=_record_delivery)
  4018. await self._release_turn_marker(event)
  4019. processing_ok = delivery_succeeded if delivery_attempted else not bool(response)
  4020. # Clean up the per-turn streaming-TTS flag.
  4021. self._streaming_tts_completed_turns.discard(self._streaming_tts_turn_key(
  4022. session_key, getattr(interrupt_event, "_hermes_run_generation", None),
  4023. event=event) or "")
  4024. await self._run_processing_hook(
  4025. "on_processing_complete", event,
  4026. ProcessingOutcome.SUCCESS if processing_ok else ProcessingOutcome.FAILURE)
  4027. # Force-flush an unfired debounce timer so this task hands off to a fresh drain task.
  4028. # Clear the Event BEFORE the stop-typing await so concurrent inbound sees a live guard.
  4029. await self._flush_text_debounce_now(session_key)
  4030. if session_key in self._pending_messages:
  4031. pending_event = self._pending_messages[session_key]
  4032. delay = self._requeue_backoff_delay(session_key, pending_event, event)
  4033. if not delay: # a backed-off event stays queued until the drain task wakes
  4034. self._pending_messages.pop(session_key)
  4035. logger.debug("[%s] Processing queued follow-up message", self.name)
  4036. self._clear_session_guard(session_key)
  4037. await self._stop_typing_refresh(event.source.chat_id, typing_task, metadata=_typing_metadata)
  4038. self._spawn_drain_task(pending_event, session_key, delay=delay)
  4039. return # Drain task owns the session now.
  4040. except asyncio.CancelledError:
  4041. expected = asyncio.current_task() in self._expected_cancelled_tasks
  4042. await self._run_processing_hook(
  4043. "on_processing_complete", event,
  4044. ProcessingOutcome.CANCELLED if expected else ProcessingOutcome.FAILURE)
  4045. raise
  4046. except BaseException as e:
  4047. await self._run_processing_hook("on_processing_complete", event, ProcessingOutcome.FAILURE)
  4048. logger.error("[%s] Error handling message: %s", self.name, e, exc_info=True)
  4049. await self._notify_turn_error(event, e)
  4050. from hermes_cli.config_backend import ConfigBackendUnavailable as _outage # this turn only
  4051. if isinstance(e, (SystemExit, KeyboardInterrupt)) and not isinstance(e, _outage): # rest contained
  4052. raise
  4053. finally:
  4054. await self._release_turn_marker(event)
  4055. event._turn_marker_handoff = False # a later run of this object clears its own marker
  4056. # Stop typing BEFORE the post-delivery callback: a stuck callback must not keep it alive.
  4057. await self._stop_typing_refresh(event.source.chat_id, typing_task, metadata=_typing_metadata)
  4058. await self._fire_post_delivery_callback(session_key, interrupt_event)
  4059. # Callback work or a late refresh may have recreated typing — one final bounded stop.
  4060. await self._stop_typing_refresh(event.source.chat_id, None, metadata=_typing_metadata, stop_attempts=1)
  4061. # Flush any timer that missed the in-band drain, then reconcile ownership.
  4062. await self._flush_text_debounce_now(session_key)
  4063. self._finish_session_task(session_key, interrupt_event)
  4064. _REQUEUE_BACKOFF_INITIAL_SECONDS = 0.25
  4065. # Kept at 1s: nothing wakes the back-off sleep, so a genuine message merged into the slot
  4066. # meanwhile waits out the remainder; 1 dispatch/s is still ~250x below the unbounded loop.
  4067. _REQUEUE_BACKOFF_MAX_SECONDS = 1.0
  4068. def _requeue_backoff_delay(self, session_key: str, pending_event: MessageEvent,
  4069. dispatched_event: MessageEvent) -> float:
  4070. """Delay before re-dispatching the queued follow-up.
  4071. Only the event this task just dispatched coming straight back backs off: the same
  4072. ``message_id``, or for an id-less event the same ``timestamp`` (rewrite-hook
  4073. ``dataclasses.replace`` copies keep both; a genuine new message gets a fresh timestamp).
  4074. The handler put it back because the session is busy elsewhere, and re-dispatching it at
  4075. once hot-loops for the whole busy window (#123229). Any other follow-up resets the counter
  4076. and runs immediately. The first bounce stays immediate (restart auto-resume relies on one
  4077. self-bounce), then back off exponentially to a cap. Defers, never drops."""
  4078. # The identical object always matches too: its id equals itself, and when empty the
  4079. # timestamp comparison does.
  4080. same = (pending_event.message_id == dispatched_event.message_id
  4081. and (bool(pending_event.message_id)
  4082. or pending_event.timestamp == dispatched_event.timestamp))
  4083. if not same:
  4084. self._requeue_counts.pop(session_key, None)
  4085. return 0.0
  4086. attempts = self._requeue_counts.get(session_key, 0)
  4087. self._requeue_counts[session_key] = attempts + 1
  4088. if attempts == 0:
  4089. return 0.0
  4090. delay = jittered_backoff(attempts, base_delay=self._REQUEUE_BACKOFF_INITIAL_SECONDS,
  4091. max_delay=self._REQUEUE_BACKOFF_MAX_SECONDS, jitter_ratio=0.0)
  4092. (logger.info if attempts == 1 else logger.debug)(
  4093. "[%s] Handler re-queued a pending event for %s again (session busy elsewhere); "
  4094. "backing off %.2fs", self.name, session_key, delay)
  4095. return delay
  4096. def _spawn_drain_task(self, pending_event: MessageEvent, session_key: str,
  4097. delay: float = 0.0) -> None:
  4098. """Hand the session to a fresh task for a queued follow-up — never recurse (chained
  4099. follow-ups grew the C stack to SIGSEGV). Clearing (not deleting) the Event keeps the guard
  4100. live for concurrent inbound; ownership moves so stale-lock detection works. With ``delay``
  4101. the event stays in ``_pending_messages`` and the new owner task pops the slot only after
  4102. sleeping, so a cancel/discard during the back-off needs no put-back and can't drop a
  4103. newer message."""
  4104. self._clear_session_guard(session_key)
  4105. # Capture the guard this drain owns now: a /stop//new guard swapped in during the
  4106. # back-off must survive the slot-empty exit (#48300).
  4107. guard = self._active_sessions.get(session_key)
  4108. self._track_session_task(
  4109. session_key,
  4110. asyncio.create_task(self._drain_after(pending_event, session_key, delay, guard)))
  4111. async def _drain_after(self, pending_event: MessageEvent, session_key: str, delay: float,
  4112. guard: Optional[asyncio.Event]) -> None:
  4113. if delay > 0:
  4114. await asyncio.sleep(delay)
  4115. await self._flush_text_debounce_now(session_key) # as every other task exit does
  4116. pending_event = self._pending_messages.pop(session_key, None)
  4117. if pending_event is None: # consumed elsewhere during the back-off
  4118. self._cleanup_finished_session_task(session_key, guard)
  4119. return
  4120. await self._process_message_background(pending_event, session_key)
  4121. def _clear_session_guard(self, session_key: str) -> None:
  4122. """Clear (not delete) the session's interrupt Event so the guard stays live for inbound."""
  4123. _active = self._active_sessions.get(session_key)
  4124. if _active is not None:
  4125. _active.clear()
  4126. def _cleanup_finished_session_task(
  4127. self, session_key: str, interrupt_event: Optional[asyncio.Event]) -> None:
  4128. """Release a finished owner task's guard, dropping its ``_session_tasks`` entry ONLY if the
  4129. guard was released: after a concurrent guard swap the done-task entry lets
  4130. ``_session_task_is_stale`` heal the orphan.
  4131. Release-then-conditional-delete is the #48300 fix: when a concurrent path (reset/new command, drain
  4132. handoff) swapped ``_active_sessions[key]`` to a different guard, ``_release_session_guard`` skips on
  4133. the guard mismatch and the lock stays installed. If we deleted ``_session_tasks`` unconditionally
  4134. (the old order), ``_session_task_is_stale`` would later see no owner task and report "not stale", so
  4135. the orphaned guard would never be healed — a permanent session deadlock. Keeping the done-task entry
  4136. when the guard survives lets the on-entry self-heal detect the stale lock and clear it on the next
  4137. inbound message.
  4138. """
  4139. self._release_session_guard(session_key, guard=interrupt_event)
  4140. if session_key not in self._active_sessions:
  4141. self._session_tasks.pop(session_key, None)
  4142. self._requeue_counts.pop(session_key, None)
  4143. async def cancel_background_tasks(self) -> None:
  4144. """Cancel in-flight background tasks (shutdown/replacement); 5s bound each,
  4145. stragglers are untracked and left to unwind."""
  4146. # Re-drain (max 5 rounds): a message arriving mid-gather spawns a task clear() would
  4147. # untrack.
  4148. for _ in range(5):
  4149. tasks = [task for task in self._background_tasks if not task.done()]
  4150. if not tasks:
  4151. break
  4152. for task in tasks:
  4153. self._expected_cancelled_tasks.add(task)
  4154. task.cancel()
  4155. try:
  4156. await asyncio.wait_for(
  4157. asyncio.gather(*(asyncio.shield(t) for t in tasks), return_exceptions=True),
  4158. timeout=5.0)
  4159. except TimeoutError:
  4160. logger.warning("[%s] %d background task(s) did not exit within 5s; "
  4161. "releasing tracking and letting them unwind in the background",
  4162. self.name, sum(not t.done() for t in tasks))
  4163. break
  4164. with contextlib.suppress(Exception): # flush pending messages to disk before clearing
  4165. from gateway.shutdown_flush import flush_pending_to_file
  4166. flush_pending_to_file(self._pending_messages, reason="adapter_shutdown")
  4167. for state in self._text_debounce_store().values():
  4168. state.cancel_timer()
  4169. for bucket in (self._background_tasks, self._expected_cancelled_tasks, self._session_tasks,
  4170. self._pending_messages, self._active_sessions, self._requeue_counts,
  4171. self._text_debounce_store()):
  4172. bucket.clear()
  4173. def has_pending_interrupt(self, session_key: str) -> bool:
  4174. """Check if there's a pending interrupt for a session."""
  4175. return session_key in self._active_sessions and self._active_sessions[session_key].is_set()
  4176. def get_pending_message(self, session_key: str) -> Optional[MessageEvent]:
  4177. """Get and clear any pending message for a session."""
  4178. return self._pending_messages.pop(session_key, None)
  4179. def build_source(
  4180. self, chat_id: str, chat_name: Optional[str] = None, chat_type: str = "dm",
  4181. user_id: Optional[str] = None, user_name: Optional[str] = None,
  4182. thread_id: Optional[str] = None, chat_topic: Optional[str] = None,
  4183. user_id_alt: Optional[str] = None, chat_id_alt: Optional[str] = None, is_bot: bool = False,
  4184. scope_id: Optional[str] = None, guild_id: Optional[str] = None,
  4185. parent_chat_id: Optional[str] = None, message_id: Optional[str] = None,
  4186. role_authorized: bool = False, auto_thread_created: bool = False,
  4187. auto_thread_initial_name: Optional[str] = None) -> SessionSource:
  4188. """Build a SessionSource (``gateway.profile_routes`` stamps the matching ``source.profile``)."""
  4189. from gateway.bot_loop_guard import configured_bot_user
  4190. def _opt(value) -> Optional[str]:
  4191. return str(value) if value else None
  4192. fields = dict(
  4193. platform=self.platform, chat_id=str(chat_id), chat_name=chat_name, chat_type=chat_type,
  4194. user_id=None if user_id is None or user_id == "" else str(user_id),
  4195. user_name=user_name, thread_id=_opt(thread_id),
  4196. chat_topic=(chat_topic or "").strip() or None, user_id_alt=user_id_alt,
  4197. chat_id_alt=chat_id_alt, is_bot=is_bot or configured_bot_user(getattr(self, "config", None), user_id),
  4198. scope_id=_opt(scope_id), guild_id=_opt(guild_id), parent_chat_id=_opt(parent_chat_id),
  4199. message_id=_opt(message_id))
  4200. # Profile from configured routes, else the owning profile of a dedicated secondary bot (so no
  4201. # later ``source.profile``-less fallback can re-route the message through the default bot's routes).
  4202. owner_profile = getattr(self, "_owner_profile", None)
  4203. profile, profile_route_rejected, rejected_profile = owner_profile, False, None
  4204. if self.gateway_runner is not None:
  4205. from gateway.profile_routing import ProfileRouteRejected
  4206. try:
  4207. profile = self.gateway_runner._profile_name_for_source(
  4208. SessionSource(**fields), adapter_profile=owner_profile) or owner_profile
  4209. except ProfileRouteRejected as exc:
  4210. profile_route_rejected, rejected_profile = True, exc.profile
  4211. except Exception:
  4212. logger.warning("Profile resolution failed for %s/%s, defaulting to active profile",
  4213. self.platform, chat_id, exc_info=True)
  4214. source = SessionSource(**fields, profile=profile, role_authorized=role_authorized,
  4215. auto_thread_created=auto_thread_created,
  4216. auto_thread_initial_name=auto_thread_initial_name)
  4217. # Transport-only, kept out of to_dict(): the receiving adapter is authoritative this turn
  4218. # even if profile_routes picks another runtime; the reject flag is consumed before auth.
  4219. source._transport_adapter_ref = weakref.ref(self)
  4220. source.profile_route_rejected, source._rejected_route_profile = profile_route_rejected, rejected_profile
  4221. return source
  4222. @abstractmethod
  4223. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  4224. """Get information about a chat/channel; dict with at least ``name``
  4225. and ``type`` ("dm", "group", "channel")."""
  4226. def toolsets_for_source(self, source: SessionSource) -> Optional[list[str]]:
  4227. """Per-source toolset override REPLACING ``platform_toolsets.<platform>``, or None
  4228. (default); validated via ``_get_platform_tools`` (webhook adapter pins per-route)."""
  4229. return None
  4230. def format_message(self, content: str) -> str:
  4231. """Format a message for this platform (override for e.g. Telegram
  4232. MarkdownV2); default returns content as-is."""
  4233. return content
  4234. @staticmethod
  4235. def truncate_message(content: str, max_length: int = 4096,
  4236. len_fn: Optional[Callable[[str], int]] = None) -> list[str]:
  4237. """Split a long message into chunks preserving code blocks: a split inside a fence closes it
  4238. at the chunk end and reopens it (same language tag) in the next; multi-chunk output gets
  4239. ``(1/3)`` indicators. ``len_fn`` overrides ``len`` (``utf16_len`` for Telegram)."""
  4240. _len = len_fn or len
  4241. if _len(content) <= max_length:
  4242. return [content]
  4243. INDICATOR_RESERVE = 10 # room for " (XX/XX)"
  4244. FENCE_CLOSE = "\n```"
  4245. chunks: list[str] = []
  4246. remaining = content
  4247. carry_lang: Optional[str] = None # language tag ("" ok) when previous chunk ended mid-fence
  4248. while remaining:
  4249. prefix = f"```{carry_lang}\n" if carry_lang is not None else ""
  4250. # Body budget after prefix/fence/indicator; floored so a tiny max_length can't stall.
  4251. headroom = max_length - INDICATOR_RESERVE - _len(prefix) - _len(FENCE_CLOSE)
  4252. if headroom < 1:
  4253. headroom = max(1, max_length // 2)
  4254. # Remainder fits in one final chunk; close a reopened fence if still open.
  4255. if _len(prefix) + _len(remaining) <= max_length - INDICATOR_RESERVE:
  4256. final_chunk = prefix + remaining
  4257. if carry_lang is not None and fence_state_after(remaining, True, carry_lang)[0]:
  4258. final_chunk += FENCE_CLOSE
  4259. chunks.append(final_chunk)
  4260. break
  4261. # Natural split (newline, then space); a custom _len budget maps to a codepoint offset.
  4262. _cp_limit = (
  4263. _custom_unit_to_cp(remaining, headroom, _len) if _len is not len else headroom)
  4264. region = remaining[:_cp_limit]
  4265. split_at = region.rfind("\n")
  4266. if split_at < _cp_limit // 2:
  4267. split_at = region.rfind(" ")
  4268. if split_at < 1:
  4269. # Floor at one codepoint: a zero _cp_limit (max_length 0/1, or a surrogate pair
  4270. # wider than the utf16 budget) would never shrink ``remaining``; overshooting beats
  4271. # a hang.
  4272. split_at = max(1, _cp_limit)
  4273. # Don't split inside an inline code span: an unpaired backtick breaks MarkdownV2.
  4274. candidate = remaining[:split_at]
  4275. backtick_count = candidate.count("`") - candidate.count("\\`")
  4276. if backtick_count % 2 == 1:
  4277. last_bt = candidate.rfind("`")
  4278. while last_bt > 0 and candidate[last_bt - 1] == "\\":
  4279. last_bt = candidate.rfind("`", 0, last_bt)
  4280. if last_bt > 0:
  4281. safe_split = max(
  4282. candidate.rfind(" ", 0, last_bt), candidate.rfind("\n", 0, last_bt))
  4283. if safe_split > _cp_limit // 4:
  4284. split_at = safe_split
  4285. chunk_body = remaining[:split_at]
  4286. remaining = remaining[split_at:].lstrip()
  4287. full_chunk = prefix + chunk_body
  4288. # Walk only chunk_body (not the prepended prefix) for the fence state.
  4289. in_code, lang = fence_state_after(chunk_body, carry_lang is not None, carry_lang or "")
  4290. carry_lang = lang if in_code else None
  4291. # Close the orphaned fence so the chunk stands alone.
  4292. chunks.append(full_chunk + FENCE_CLOSE if in_code else full_chunk)
  4293. if len(chunks) > 1:
  4294. chunks = [f"{chunk} ({i + 1}/{len(chunks)})" for i, chunk in enumerate(chunks)]
  4295. return chunks