api_server.py 224 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252125312541255125612571258125912601261126212631264126512661267126812691270127112721273127412751276127712781279128012811282128312841285128612871288128912901291129212931294129512961297129812991300130113021303130413051306130713081309131013111312131313141315131613171318131913201321132213231324132513261327132813291330133113321333133413351336133713381339134013411342134313441345134613471348134913501351135213531354135513561357135813591360136113621363136413651366136713681369137013711372137313741375137613771378137913801381138213831384138513861387138813891390139113921393139413951396139713981399140014011402140314041405140614071408140914101411141214131414141514161417141814191420142114221423142414251426142714281429143014311432143314341435143614371438143914401441144214431444144514461447144814491450145114521453145414551456145714581459146014611462146314641465146614671468146914701471147214731474147514761477147814791480148114821483148414851486148714881489149014911492149314941495149614971498149915001501150215031504150515061507150815091510151115121513151415151516151715181519152015211522152315241525152615271528152915301531153215331534153515361537153815391540154115421543154415451546154715481549155015511552155315541555155615571558155915601561156215631564156515661567156815691570157115721573157415751576157715781579158015811582158315841585158615871588158915901591159215931594159515961597159815991600160116021603160416051606160716081609161016111612161316141615161616171618161916201621162216231624162516261627162816291630163116321633163416351636163716381639164016411642164316441645164616471648164916501651165216531654165516561657165816591660166116621663166416651666166716681669167016711672167316741675167616771678167916801681168216831684168516861687168816891690169116921693169416951696169716981699170017011702170317041705170617071708170917101711171217131714171517161717171817191720172117221723172417251726172717281729173017311732173317341735173617371738173917401741174217431744174517461747174817491750175117521753175417551756175717581759176017611762176317641765176617671768176917701771177217731774177517761777177817791780178117821783178417851786178717881789179017911792179317941795179617971798179918001801180218031804180518061807180818091810181118121813181418151816181718181819182018211822182318241825182618271828182918301831183218331834183518361837183818391840184118421843184418451846184718481849185018511852185318541855185618571858185918601861186218631864186518661867186818691870187118721873187418751876187718781879188018811882188318841885188618871888188918901891189218931894189518961897189818991900190119021903190419051906190719081909191019111912191319141915191619171918191919201921192219231924192519261927192819291930193119321933193419351936193719381939194019411942194319441945194619471948194919501951195219531954195519561957195819591960196119621963196419651966196719681969197019711972197319741975197619771978197919801981198219831984198519861987198819891990199119921993199419951996199719981999200020012002200320042005200620072008200920102011201220132014201520162017201820192020202120222023202420252026202720282029203020312032203320342035203620372038203920402041204220432044204520462047204820492050205120522053205420552056205720582059206020612062206320642065206620672068206920702071207220732074207520762077207820792080208120822083208420852086208720882089209020912092209320942095209620972098209921002101210221032104210521062107210821092110211121122113211421152116211721182119212021212122212321242125212621272128212921302131213221332134213521362137213821392140214121422143214421452146214721482149215021512152215321542155215621572158215921602161216221632164216521662167216821692170217121722173217421752176217721782179218021812182218321842185218621872188218921902191219221932194219521962197219821992200220122022203220422052206220722082209221022112212221322142215221622172218221922202221222222232224222522262227222822292230223122322233223422352236223722382239224022412242224322442245224622472248224922502251225222532254225522562257225822592260226122622263226422652266226722682269227022712272227322742275227622772278227922802281228222832284228522862287228822892290229122922293229422952296229722982299230023012302230323042305230623072308230923102311231223132314231523162317231823192320232123222323232423252326232723282329233023312332233323342335233623372338233923402341234223432344234523462347234823492350235123522353235423552356235723582359236023612362236323642365236623672368236923702371237223732374237523762377237823792380238123822383238423852386238723882389239023912392239323942395239623972398239924002401240224032404240524062407240824092410241124122413241424152416241724182419242024212422242324242425242624272428242924302431243224332434243524362437243824392440244124422443244424452446244724482449245024512452245324542455245624572458245924602461246224632464246524662467246824692470247124722473247424752476247724782479248024812482248324842485248624872488248924902491249224932494249524962497249824992500250125022503250425052506250725082509251025112512251325142515251625172518251925202521252225232524252525262527252825292530253125322533253425352536253725382539254025412542254325442545254625472548254925502551255225532554255525562557255825592560256125622563256425652566256725682569257025712572257325742575257625772578257925802581258225832584258525862587258825892590259125922593259425952596259725982599260026012602260326042605260626072608260926102611261226132614261526162617261826192620262126222623262426252626262726282629263026312632263326342635263626372638263926402641264226432644264526462647264826492650265126522653265426552656265726582659266026612662266326642665266626672668266926702671267226732674267526762677267826792680268126822683268426852686268726882689269026912692269326942695269626972698269927002701270227032704270527062707270827092710271127122713271427152716271727182719272027212722272327242725272627272728272927302731273227332734273527362737273827392740274127422743274427452746274727482749275027512752275327542755275627572758275927602761276227632764276527662767276827692770277127722773277427752776277727782779278027812782278327842785278627872788278927902791279227932794279527962797279827992800280128022803280428052806280728082809281028112812281328142815281628172818281928202821282228232824282528262827282828292830283128322833283428352836283728382839284028412842284328442845284628472848284928502851285228532854285528562857285828592860286128622863286428652866286728682869287028712872287328742875287628772878287928802881288228832884288528862887288828892890289128922893289428952896289728982899290029012902290329042905290629072908290929102911291229132914291529162917291829192920292129222923292429252926292729282929293029312932293329342935293629372938293929402941294229432944294529462947294829492950295129522953295429552956295729582959296029612962296329642965296629672968296929702971297229732974297529762977297829792980298129822983298429852986298729882989299029912992299329942995299629972998299930003001300230033004300530063007300830093010301130123013301430153016301730183019302030213022302330243025302630273028302930303031303230333034303530363037303830393040304130423043304430453046304730483049305030513052305330543055305630573058305930603061306230633064306530663067306830693070307130723073307430753076307730783079308030813082308330843085308630873088308930903091309230933094309530963097309830993100310131023103310431053106310731083109311031113112311331143115311631173118311931203121312231233124312531263127312831293130313131323133313431353136313731383139314031413142314331443145314631473148314931503151315231533154315531563157315831593160316131623163316431653166316731683169317031713172317331743175317631773178317931803181318231833184318531863187318831893190319131923193319431953196319731983199320032013202320332043205320632073208320932103211321232133214321532163217321832193220322132223223322432253226322732283229323032313232323332343235323632373238323932403241324232433244324532463247324832493250325132523253325432553256325732583259326032613262326332643265326632673268326932703271327232733274327532763277327832793280328132823283328432853286328732883289329032913292329332943295329632973298329933003301330233033304330533063307330833093310331133123313331433153316331733183319332033213322332333243325332633273328332933303331333233333334333533363337333833393340334133423343334433453346334733483349335033513352335333543355335633573358335933603361336233633364336533663367336833693370337133723373337433753376337733783379338033813382338333843385338633873388338933903391339233933394339533963397339833993400340134023403340434053406340734083409341034113412341334143415341634173418341934203421342234233424342534263427342834293430343134323433343434353436343734383439344034413442344334443445344634473448344934503451345234533454345534563457345834593460346134623463346434653466346734683469347034713472347334743475347634773478347934803481348234833484348534863487348834893490349134923493349434953496349734983499350035013502350335043505350635073508350935103511351235133514351535163517351835193520352135223523352435253526352735283529353035313532353335343535353635373538353935403541354235433544354535463547354835493550355135523553355435553556355735583559356035613562356335643565356635673568356935703571357235733574357535763577357835793580358135823583358435853586358735883589359035913592359335943595359635973598359936003601360236033604360536063607360836093610361136123613361436153616361736183619362036213622362336243625362636273628362936303631363236333634363536363637363836393640364136423643364436453646364736483649365036513652365336543655365636573658365936603661366236633664366536663667366836693670367136723673367436753676367736783679368036813682368336843685368636873688368936903691369236933694369536963697369836993700370137023703370437053706370737083709371037113712371337143715371637173718371937203721372237233724372537263727372837293730373137323733373437353736373737383739374037413742374337443745374637473748374937503751375237533754375537563757375837593760376137623763376437653766376737683769377037713772377337743775377637773778377937803781378237833784378537863787378837893790379137923793379437953796379737983799380038013802380338043805380638073808380938103811381238133814381538163817381838193820382138223823382438253826382738283829383038313832383338343835383638373838383938403841384238433844384538463847384838493850385138523853385438553856385738583859386038613862386338643865386638673868386938703871387238733874387538763877387838793880388138823883388438853886388738883889389038913892389338943895389638973898389939003901390239033904390539063907390839093910391139123913391439153916391739183919392039213922392339243925392639273928392939303931393239333934393539363937393839393940394139423943394439453946394739483949395039513952395339543955395639573958395939603961396239633964396539663967396839693970397139723973397439753976397739783979398039813982398339843985398639873988398939903991399239933994399539963997399839994000400140024003400440054006400740084009401040114012401340144015401640174018401940204021402240234024402540264027402840294030403140324033403440354036403740384039404040414042404340444045404640474048404940504051405240534054405540564057405840594060406140624063406440654066406740684069407040714072407340744075407640774078407940804081408240834084408540864087408840894090409140924093409440954096409740984099410041014102410341044105410641074108410941104111
  1. """OpenAI-compatible API server platform adapter (aiohttp).
  2. Serves /v1/chat/completions, /v1/responses, /v1/models, /v1/capabilities, /api/sessions,
  3. /v1/runs, /api/jobs and /health* (full table: ``APIServerAdapter._http_route_table``); any
  4. OpenAI-compatible frontend connects at http://localhost:8642/v1 with API_SERVER_KEY. Under
  5. ``gateway.multiplex_profiles`` secondary profiles live at ``/p/<profile>/...``.
  6. """
  7. import asyncio
  8. import errno
  9. import hashlib
  10. import hmac
  11. import itertools
  12. import json
  13. from contextlib import contextmanager, nullcontext, suppress
  14. from contextvars import ContextVar, copy_context
  15. from functools import wraps
  16. import logging
  17. import os
  18. import re
  19. import sys
  20. import threading
  21. import time
  22. import uuid
  23. from datetime import datetime, timezone, UTC
  24. from pathlib import Path
  25. from typing import Any, Dict, List, Optional, Tuple
  26. # _resolve_request_profile result for a /p/<profile>/ prefix this gateway does not serve (-> 404);
  27. # distinct from None (no prefix / multiplexing off -> default profile).
  28. _PROFILE_REJECTED = object()
  29. def _prefix_names_served_profile(profile: str) -> bool:
  30. """True when a /p/<profile>/ prefix names the profile this gateway serves. Fail closed: a
  31. single-profile gateway answering /p/<x>/ served the owner's toolsets under another URL."""
  32. try:
  33. from hermes_cli.profiles import profile_matches_home
  34. return profile_matches_home(profile)
  35. except Exception:
  36. return False
  37. # Per-request /p/<profile>/ selection: set by the profile-prefix middleware, read by handlers.
  38. _api_request_profile: ContextVar[Optional[str]] = ContextVar(
  39. "api_server_request_profile", default=None)
  40. # /v1/capabilities static feature flags (order is part of the JSON shape).
  41. _STATIC_FEATURE_FLAGS = {
  42. "run_status": True, "run_events_sse": True, "run_stop": True, "run_steer": True,
  43. "run_approval_response": True, "tool_progress_events": True, "approval_events": True,
  44. "session_resources": True, "model_options": True, "session_chat": True,
  45. "session_chat_streaming": True, "session_fork": True, "session_model_lock": True,
  46. "reasoning_streaming": True,
  47. "admin_config_rw": False, "jobs_admin": False, "memory_write_api": False,
  48. "skills_api": True, "audio_api": False, "realtime_voice": False,
  49. "session_continuity_header": "X-Hermes-Session-Id",
  50. "session_key_header": "X-Hermes-Session-Key"}
  51. # /v1/capabilities "endpoints" table: name -> (method, path[, feature]). An entry naming a
  52. # feature is advertised only while that "features" flag is truthy on this listener.
  53. _CAPABILITY_ENDPOINTS = (
  54. ("health", ("GET", "/health")), ("health_detailed", ("GET", "/health/detailed")),
  55. ("models", ("GET", "/v1/models")), ("model_options", ("GET", "/api/model/options")),
  56. ("chat_completions", ("POST", "/v1/chat/completions")),
  57. ("responses", ("POST", "/v1/responses")), ("runs", ("POST", "/v1/runs")),
  58. ("run_status", ("GET", "/v1/runs/{run_id}")),
  59. ("run_events", ("GET", "/v1/runs/{run_id}/events")),
  60. ("run_approval", ("POST", "/v1/runs/{run_id}/approval")),
  61. ("run_steer", ("POST", "/v1/runs/{run_id}/steer")),
  62. ("run_unknown_resolution", ("POST", "/v1/runs/{run_id}/resolve-unknown", "run_unknown_resolution")),
  63. ("run_stop", ("POST", "/v1/runs/{run_id}/stop")), ("skills", ("GET", "/v1/skills")),
  64. ("toolsets", ("GET", "/v1/toolsets")), ("sessions", ("GET", "/api/sessions")),
  65. ("session_create", ("POST", "/api/sessions")),
  66. ("session", ("GET", "/api/sessions/{session_id}")),
  67. ("session_update", ("PATCH", "/api/sessions/{session_id}")),
  68. ("session_delete", ("DELETE", "/api/sessions/{session_id}")),
  69. ("session_messages", ("GET", "/api/sessions/{session_id}/messages")),
  70. ("session_fork", ("POST", "/api/sessions/{session_id}/fork")),
  71. ("session_chat", ("POST", "/api/sessions/{session_id}/chat")),
  72. ("session_chat_stream", ("POST", "/api/sessions/{session_id}/chat/stream")),
  73. ("session_model_lock", ("POST", "/api/sessions/{session_id}/model")))
  74. def _approval_event_choices(*, smart_denied: bool, allow_session: bool, allow_permanent: bool) -> list[str]:
  75. if smart_denied or not allow_session:
  76. return ["once", "deny"]
  77. return ["once", "session", "always", "deny"] if allow_permanent else ["once", "session", "deny"]
  78. def _approval_request_event(run_id: str, approval_data: Optional[dict[str, Any]], **fields: Any) -> dict[str, Any]:
  79. """The ``approval.request`` payload every approval surface emits (runs bridge, session stream,
  80. chat completions): the flagged command redacted before egress (#48456), the ``_run_event``
  81. envelope, and the ``choices`` the client may send back to ``POST /v1/runs/{id}/approval``."""
  82. from gateway.platforms.api_server_runs import _run_event
  83. from gateway.run import _redact_approval_command
  84. event = dict(approval_data or {}) # consent prompts (MCP, vault) carry server/model text in the description
  85. event.update({k: _redact_approval_command(event[k]) for k in ("command", "description") if k in event})
  86. event.update(_run_event(run_id, "approval.request", **fields, choices=_approval_event_choices(
  87. smart_denied=bool(event.get("smart_denied")),
  88. allow_session=event.get("allow_session") is not False,
  89. allow_permanent=event.get("allow_permanent") is not False)))
  90. return event
  91. try:
  92. from aiohttp import web
  93. AIOHTTP_AVAILABLE = True
  94. except ImportError:
  95. AIOHTTP_AVAILABLE = False
  96. web = None # type: ignore[assignment]
  97. from gateway.config import Platform, PlatformConfig
  98. from gateway.display_config import resolve_display_setting
  99. from gateway.platforms import api_server_room_dispatch as _room_dispatch
  100. from gateway.platforms import api_server_room_grants as _room_grants
  101. from gateway.platforms import api_server_runs as _api_runs
  102. from gateway.platforms.api_server_openai_routes import OpenAICompatRoutesMixin
  103. from gateway.platforms.api_server_memory_sessions import ApiServerMemorySessions
  104. from gateway.platforms.api_server_bot_chat import reset_local_title_owner
  105. from gateway.platforms.base import (
  106. MEDIA_TAG_CLEANUP_RE, BasePlatformAdapter, SendResult, _terminal_sentinel_start, is_network_accessible,
  107. validate_media_delivery_path)
  108. from gateway.platforms.api_server_run_idempotency import RunIdempotencyStore
  109. from gateway.platforms.api_server_response_store import ResponseStore
  110. from agent.i18n import t
  111. from agent.redact import redact_sensitive_text
  112. from agent.interrupt_compat import request_hard_interrupt
  113. from gateway.readiness import collect_runtime_readiness
  114. from gateway.parked_route_refusal import ParkedRouteRefused
  115. from gateway.platforms._shared import coerce_port as _coerce_port, get_scoped_secret as _get_scoped_secret
  116. from gateway.platforms.tcp_site import start_tcp_site
  117. from hermes_state_errors import SessionActiveWriteGuardError
  118. logger = logging.getLogger(__name__)
  119. async def _call_verifier(verifier, *args, **kwargs):
  120. """Await a sync-or-async verifier; sync ones may do blocking network I/O (signing-cert / JWKS
  121. fetches), so they run off the loop."""
  122. if asyncio.iscoroutinefunction(verifier):
  123. return await verifier(*args, **kwargs)
  124. return await asyncio.to_thread(verifier, *args, **kwargs)
  125. def _hermes_version() -> str:
  126. """Canonical base version for API protocol and compatibility payloads."""
  127. from hermes_cli.version_info import get_version_info
  128. return get_version_info().base_version
  129. # Default settings
  130. DEFAULT_HOST = "127.0.0.1"
  131. DEFAULT_PORT = 8642
  132. _BIND_ATTEMPTS = 5 # EADDRINUSE retries while a restart's predecessor releases the port (#91547)
  133. def listen_address(extra: dict[str, Any]) -> tuple[str, int]:
  134. """Host/port the adapter binds: config.yaml ``platforms.api_server`` wins over the env fallbacks.
  135. Shared with the CLI restart path, which must wait on the SAME address the replacement will
  136. bind — an env-only reading missed every config.yaml port (#91547).
  137. """
  138. host = extra.get("host", os.getenv("API_SERVER_HOST", DEFAULT_HOST))
  139. raw_port = extra.get("port")
  140. if raw_port is None:
  141. raw_port = os.getenv("API_SERVER_PORT", str(DEFAULT_PORT))
  142. return host, _coerce_port(raw_port, DEFAULT_PORT)
  143. MAX_REQUEST_BYTES = 10_000_000 # 10 MB — accommodates long agent conversations with tool calls
  144. # Send a comment before remote API clients' common 20-second idle deadline.
  145. # This constant is shared by OpenAI chat/Responses and native session SSE.
  146. CHAT_COMPLETIONS_SSE_KEEPALIVE_SECONDS = 10.0
  147. API_SERVER_HEARTBEAT_SECONDS = 30.0
  148. API_SERVER_LATENCY_SAMPLE_LIMIT = 512
  149. MAX_NORMALIZED_TEXT_LENGTH = 65_536 # 64 KB cap for normalized content parts
  150. MAX_CONTENT_LIST_SIZE = 1_000 # Max items when content is an array
  151. RESPONSES_AUTO_TRUNCATION_HISTORY_LIMIT = 100
  152. class ThreadSafeAsyncQueue(asyncio.Queue):
  153. """``asyncio.Queue`` a non-loop thread (run_conversation's executor) can push into via
  154. ``put_threadsafe``; the SSE consumer's ``await get()`` is woken by ``call_soon_threadsafe``."""
  155. def put_threadsafe(self, item, *, loop: asyncio.AbstractEventLoop | None = None) -> None:
  156. (loop or self._loop_ref).call_soon_threadsafe(self.put_nowait, item)
  157. def __init__(self, *args, **kwargs):
  158. super().__init__(*args, **kwargs)
  159. # Always constructed inside a running async handler (the SSE
  160. # request handlers below), so get_running_loop() is safe here.
  161. self._loop_ref = asyncio.get_running_loop()
  162. def _sse_frame(
  163. data: Any, *, event: str | None = None, ensure_ascii: bool = True, id: Optional[int] = None
  164. ) -> bytes:
  165. """Encode one SSE frame (``id:``/``event:`` lines if given, then ``data: <json>\n\n``) for
  166. every SSE writer. ``ensure_ascii=False`` keeps raw non-ASCII on the wire."""
  167. prefix = (f"id: {id}\n" if id is not None else "") + (f"event: {event}\n" if event else "")
  168. return f"{prefix}data: {json.dumps(data, ensure_ascii=ensure_ascii)}\n\n".encode()
  169. _TRUE_REQUEST_BOOL_STRINGS = frozenset({"1", "true", "yes", "on"})
  170. _FALSE_REQUEST_BOOL_STRINGS = frozenset({"0", "false", "no", "off"})
  171. def _coerce_request_bool(value: Any, default: bool = False) -> bool:
  172. """Normalize boolean-like payload values; only explicit bool-ish scalars count (some
  173. frontends send ``"false"`` for ``stream``, which is truthy), else ``default``."""
  174. if isinstance(value, bool):
  175. return value
  176. if value is None:
  177. return default
  178. if isinstance(value, str):
  179. normalized = value.strip().lower()
  180. if normalized in _TRUE_REQUEST_BOOL_STRINGS:
  181. return True
  182. return False if normalized in _FALSE_REQUEST_BOOL_STRINGS else default
  183. return bool(value) if isinstance(value, (int, float)) else default
  184. _REQUEST_OPTION_MISSING = object()
  185. # Full internal ladder + "none" (what /reasoning and config.yaml accept); provider
  186. # vocabulary clamping happens downstream in agent.reasoning_effort.
  187. _REASONING_EFFORTS = frozenset({"none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"})
  188. _RUNTIME_AGENT_OVERRIDE_KEYS = (
  189. "api_key", "base_url", "provider", "api_mode", "command", "args", "credential_pool")
  190. def _clean_request_string(value: Any) -> Optional[str]:
  191. """Return a stripped request string, or None for absent/non-string values."""
  192. return (value.strip() or None) if isinstance(value, str) else None
  193. # model_options decoding lives in the topical sibling (line-cap offset);
  194. # re-exported here so importers are unaffected.
  195. from gateway.platforms.api_server_request_options import _request_reasoning_config, _request_service_tier
  196. def _apply_runtime_agent_overrides(
  197. runtime_kwargs: dict[str, Any], overrides: Optional[dict[str, Any]]) -> dict[str, Any]:
  198. """Merge resolved provider/runtime fields into ``runtime_kwargs`` in place."""
  199. if not isinstance(overrides, dict):
  200. return runtime_kwargs
  201. for key in _RUNTIME_AGENT_OVERRIDE_KEYS:
  202. value = overrides.get(key)
  203. if value is None:
  204. continue
  205. runtime_kwargs[key] = list(value) if key == "args" and isinstance(value, (list, tuple)) else value
  206. return runtime_kwargs
  207. def _resolve_request_runtime_agent_kwargs(provider: str, target_model: Optional[str] = None) -> dict[str, Any]:
  208. """gateway.run._resolve_runtime_agent_kwargs() for an explicit provider/model, so an API
  209. caller uses the same authenticated provider catalog without mutating config.yaml."""
  210. from hermes_cli.runtime_provider import resolve_runtime_provider, format_runtime_provider_error, _get_model_config
  211. try:
  212. runtime = resolve_runtime_provider(requested=provider, target_model=target_model)
  213. except Exception as exc:
  214. raise RuntimeError(format_runtime_provider_error(exc)) from exc
  215. return {
  216. **{k: runtime.get(k) for k in ("api_key", "base_url", "provider", "api_mode", "command")},
  217. "args": list(runtime.get("args") or []),
  218. "credential_pool": runtime.get("credential_pool")}
  219. def _request_agent_overrides(
  220. body: Any, *, virtual_model: Optional[str] = None, allow_bare_model: bool = True
  221. ) -> dict[str, Any]:
  222. """Extract per-request model/provider/options for _run_agent.
  223. The virtual model (``hermes-agent``) means "gateway default". A bare ``model`` without
  224. ``provider`` is honored only when ``allow_bare_model`` (generic clients hardcode "gpt-4o";
  225. OpenAI-compatible handlers pass the ``direct_model_requests`` opt-in, Hermes-native
  226. endpoints always allow it). An explicit ``provider`` is always honored.
  227. """
  228. if not isinstance(body, dict):
  229. return {}
  230. overrides: dict[str, Any] = {}
  231. provider = _clean_request_string(body.get("provider"))
  232. if provider:
  233. overrides["requested_provider"] = provider
  234. model = _clean_request_string(body.get("model"))
  235. if model and model != virtual_model and (provider or allow_bare_model):
  236. overrides["requested_model"] = model
  237. model_options = body.get("model_options")
  238. if isinstance(model_options, dict):
  239. overrides["model_options"] = dict(model_options)
  240. return overrides
  241. def _request_relay_metadata(body: Any) -> dict[str, Any]:
  242. """Extract Relay metadata from an OpenAI request body."""
  243. if not isinstance(body, dict):
  244. return {}
  245. metadata = body.get("metadata")
  246. if not isinstance(metadata, dict):
  247. return {}
  248. return dict(metadata)
  249. def _is_compressed_summary_message(message: Any) -> bool:
  250. """Recognize every compaction carrier shape via the compressor's own classifier
  251. (SessionDB drops the in-process marker; a prefix scan misses merge-into-tail carriers)."""
  252. if not isinstance(message, dict):
  253. return False
  254. from agent.context_compressor import is_compaction_summary_message
  255. return is_compaction_summary_message(message)
  256. def _project_client_message(message: dict[str, Any]) -> dict[str, Any]:
  257. """Strip compaction scaffolding: standalone handoffs become hidden empty rows (stable
  258. ids), merged handoffs keep only the real prior-tail content; inherited tool calls dropped."""
  259. from agent.compaction_display import (
  260. _COMPACTION_INTERNAL_FIELDS, project_compaction_message_for_display)
  261. if (message.get("display_kind") == "hidden"
  262. and (message.get("display_metadata") or {}).get("notification_category") == "diagnostic"):
  263. # Retain row identity and execution evidence in storage, not in the notification UI.
  264. return {k: v for k, v in message.items() if k in {
  265. "id", "session_id", "role", "timestamp", "display_kind", "platform_message_id",
  266. }} | {"content": ""}
  267. projected = project_compaction_message_for_display(message)
  268. if projected is None:
  269. projected = {k: v for k, v in message.items() if k not in _COMPACTION_INTERNAL_FIELDS}
  270. projected["content"] = ""
  271. projected["display_kind"] = "hidden"
  272. return projected
  273. def _auto_truncate_response_history(
  274. conversation_history: list[dict[str, Any]],
  275. *,
  276. limit: int = RESPONSES_AUTO_TRUNCATION_HISTORY_LIMIT) -> list[dict[str, Any]]:
  277. """Keep the most recent ``limit`` messages, always preserving compaction summaries
  278. wherever they sit (the /compress path can leave them after a retained system head)."""
  279. if limit <= 0 or len(conversation_history) <= limit:
  280. return conversation_history
  281. summary_indices = [i for i, m in enumerate(conversation_history) if _is_compressed_summary_message(m)]
  282. if not summary_indices:
  283. return conversation_history[-limit:]
  284. kept_indices = set(summary_indices[:limit])
  285. remaining = limit - len(kept_indices)
  286. if remaining > 0:
  287. summary_index_set = set(summary_indices)
  288. for index in range(len(conversation_history) - 1, -1, -1):
  289. if index in summary_index_set:
  290. continue
  291. kept_indices.add(index)
  292. remaining -= 1
  293. if remaining <= 0:
  294. break
  295. return [conversation_history[index] for index in sorted(kept_indices)]
  296. def _cap_text(text: str) -> str:
  297. return text[:MAX_NORMALIZED_TEXT_LENGTH] if len(text) > MAX_NORMALIZED_TEXT_LENGTH else text
  298. def _cap_list(items: list) -> list:
  299. return items[:MAX_CONTENT_LIST_SIZE] if len(items) > MAX_CONTENT_LIST_SIZE else items
  300. def _normalize_chat_content(content: Any, *, _max_depth: int = 10, _depth: int = 0) -> str:
  301. """Flatten OpenAI chat content (string or typed-part array) into one plain string; non-text
  302. parts are skipped, recursion depth / list size / output length are bounded."""
  303. if _depth > _max_depth or content is None:
  304. return ""
  305. if isinstance(content, str):
  306. return _cap_text(content)
  307. if isinstance(content, list):
  308. parts: list[str] = []
  309. total_len = 0
  310. for item in _cap_list(content):
  311. part = ""
  312. if isinstance(item, str):
  313. part = item
  314. elif isinstance(item, dict):
  315. if str(item.get("type") or "").strip().lower() in _TEXT_PART_TYPES:
  316. text = item.get("text", "")
  317. if text:
  318. with suppress(Exception):
  319. part = str(text)
  320. elif isinstance(item, list):
  321. part = _normalize_chat_content(item, _max_depth=_max_depth, _depth=_depth + 1)
  322. if part:
  323. part = _cap_text(part)
  324. parts.append(part)
  325. total_len += len(part)
  326. if total_len >= MAX_NORMALIZED_TEXT_LENGTH:
  327. break
  328. return _cap_text("\n".join(parts))
  329. try:
  330. return _cap_text(str(content))
  331. except Exception:
  332. return ""
  333. # Chat Completions / Responses part-type spellings; emitted shape is always the canonical
  334. # ``{"type": "text", ...}`` / ``{"type": "image_url", ...}`` the agent pipeline understands.
  335. _TEXT_PART_TYPES = frozenset({"text", "input_text", "output_text"})
  336. _IMAGE_PART_TYPES = frozenset({"image_url", "input_image"})
  337. _FILE_PART_TYPES = frozenset({"file", "input_file"})
  338. def _normalize_image_part(part: dict[str, Any]) -> dict[str, Any]:
  339. """Validate one image part (Responses top-level ``image_url`` string or Chat Completions
  340. ``{"url", "detail"}`` dict) into the canonical vision shape; raises ValueError."""
  341. detail = part.get("detail")
  342. image_ref = part.get("image_url")
  343. if isinstance(image_ref, dict):
  344. url_value = image_ref.get("url")
  345. detail = image_ref.get("detail", detail)
  346. else:
  347. url_value = image_ref
  348. if not isinstance(url_value, str) or not url_value.strip():
  349. raise ValueError("invalid_image_url:Image parts must include a non-empty image URL.")
  350. url_value = url_value.strip()
  351. lowered = url_value.lower()
  352. if lowered.startswith("data:"):
  353. if not lowered.startswith("data:image/") or "," not in url_value:
  354. raise ValueError(
  355. "unsupported_content_type:Only image data URLs are supported. "
  356. "Non-image data payloads are not supported.")
  357. elif not (lowered.startswith("http://") or lowered.startswith("https://")):
  358. raise ValueError(
  359. "invalid_image_url:Image inputs must use http(s) URLs or data:image/... URLs.")
  360. image_part: dict[str, Any] = {"type": "image_url", "image_url": {"url": url_value}}
  361. if detail is not None:
  362. if not isinstance(detail, str) or not detail.strip():
  363. raise ValueError("invalid_content_part:Image detail must be a non-empty string when provided.")
  364. image_part["image_url"]["detail"] = detail.strip()
  365. return image_part
  366. def _normalize_multimodal_content(content: Any) -> Any:
  367. """Validate multimodal content: a plain string when text-only, else canonical ``text`` /
  368. ``image_url`` parts (native OpenAI vision shape; Anthropic conversion happens downstream).
  369. Raises ``ValueError("<code>:<message>")`` with codes ``unsupported_content_type`` (file
  370. parts, non-image data URLs, unknown types), ``invalid_image_url``, ``invalid_content_part``.
  371. """
  372. if content is None:
  373. return ""
  374. if isinstance(content, str):
  375. return _cap_text(content)
  376. if not isinstance(content, list):
  377. return _normalize_chat_content(content)
  378. normalized_parts: list[dict[str, Any]] = []
  379. for part in _cap_list(content):
  380. if isinstance(part, str):
  381. if part:
  382. normalized_parts.append({"type": "text", "text": _cap_text(part)})
  383. continue
  384. if not isinstance(part, dict):
  385. continue # unknown scalars are ignored for forward compatibility (e.g. ``refusal``)
  386. raw_type = part.get("type")
  387. part_type = str(raw_type or "").strip().lower()
  388. if part_type in _TEXT_PART_TYPES:
  389. text = part.get("text")
  390. if text is not None and str(text):
  391. normalized_parts.append({"type": "text", "text": _cap_text(str(text))})
  392. elif part_type in _IMAGE_PART_TYPES:
  393. normalized_parts.append(_normalize_image_part(part))
  394. elif part_type in _FILE_PART_TYPES:
  395. raise ValueError(
  396. "unsupported_content_type:Inline image inputs are supported, "
  397. "but uploaded files and document inputs are not supported on this endpoint.")
  398. else:
  399. raise ValueError(
  400. f"unsupported_content_type:Unsupported content part type {raw_type!r}. "
  401. "Only text and image_url/input_image parts are supported.")
  402. if not normalized_parts:
  403. return ""
  404. # Text-only collapses to a plain string so trajectory logging and prompt caching see
  405. # the native shape.
  406. if all(p.get("type") == "text" for p in normalized_parts):
  407. return "\n".join(p["text"] for p in normalized_parts if p.get("text"))
  408. return normalized_parts
  409. def _content_has_visible_payload(content: Any) -> bool:
  410. """True when content has any text or image attachment. Used to reject empty turns."""
  411. if isinstance(content, str):
  412. return bool(content.strip())
  413. if isinstance(content, list):
  414. for part in content:
  415. if isinstance(part, dict):
  416. ptype = str(part.get("type") or "").strip().lower()
  417. if ptype in _IMAGE_PART_TYPES or (
  418. ptype in _TEXT_PART_TYPES and str(part.get("text") or "").strip()):
  419. return True
  420. return False
  421. def _multimodal_validation_error(exc: ValueError, *, param: str) -> web.Response:
  422. """Translate a ``_normalize_multimodal_content`` ValueError into a 400 response."""
  423. raw = str(exc)
  424. code, _, message = raw.partition(":")
  425. if not message:
  426. code, message = "invalid_content_part", raw
  427. return _error_response(message, 400, code=code, param=param)
  428. def _reap_disconnected_agent_processes(
  429. agent: Any, *, source: str = "api_server_sse_disconnect") -> None:
  430. """Reap background processes an abandoned API-server turn created (these turns bypass
  431. ``TurnRunner``). Daemon-thread fire-and-forget; epoch-gated so a stale reaper never kills
  432. a newer run's process on a shared task_id.
  433. Mirrors the gateway-turn cleanup in ``gateway/run.py`` (#76115) for this API-server surface, which runs
  434. its own agent lifecycle via ``_run_agent`` and never passes through ``TurnRunner`` — so it needs its own
  435. trigger for the same baseline-diff reap.
  436. """
  437. process_task_id = getattr(agent, "_gateway_turn_process_task_id", "")
  438. process_baseline = getattr(agent, "_gateway_turn_process_baseline", None)
  439. if not process_task_id or process_baseline is None:
  440. return
  441. epoch = getattr(agent, "_gateway_turn_process_epoch", None)
  442. is_still_current: Optional[Any] = None
  443. if epoch is not None:
  444. def _epoch_still_current(_task_id=process_task_id, _epoch=epoch):
  445. # Skip only when a NEWER run claimed this task_id. A missing entry means
  446. # our own clear pruned it — no newer claimant, so the reap must proceed.
  447. with _TURN_PROCESS_EPOCH_LOCK:
  448. current = _TURN_PROCESS_EPOCHS.get(_task_id)
  449. return current is None or current == _epoch
  450. is_still_current = _epoch_still_current
  451. from gateway.run import _reap_gateway_turn_processes
  452. threading.Thread(
  453. target=copy_context().run, args=(_reap_gateway_turn_processes, process_task_id, process_baseline),
  454. kwargs={"source": source, "is_still_current": is_still_current},
  455. name=f"api-turn-reaper-{process_task_id[:12]}", daemon=True).start()
  456. # Per-task-id run epochs for the reap gate: monotonic counter (never reused),
  457. # pruned on clear while still current, so the dict is bounded to in-flight runs.
  458. _TURN_PROCESS_EPOCHS: dict[str, int] = {}
  459. _TURN_PROCESS_EPOCH_LOCK = threading.Lock()
  460. _TURN_PROCESS_EPOCH_COUNTER = itertools.count(1)
  461. def _publish_turn_process_ownership(agent: Any, task_id: str) -> None:
  462. """Snapshot the process baseline and claim the task_id's epoch — the single place every
  463. API-server agent lifecycle records turn ownership (marker names cannot drift)."""
  464. from tools.process_registry import process_registry
  465. with _TURN_PROCESS_EPOCH_LOCK:
  466. epoch = next(_TURN_PROCESS_EPOCH_COUNTER)
  467. _TURN_PROCESS_EPOCHS[task_id] = epoch
  468. agent._gateway_turn_process_task_id = task_id
  469. agent._gateway_turn_process_baseline = process_registry.snapshot_running_ids(task_id)
  470. agent._gateway_turn_process_epoch = epoch
  471. def _clear_turn_process_ownership(agent: Any) -> None:
  472. """Clear turn ownership as soon as the turn ends: a later disconnect/cancel must not reap
  473. background work the turn deliberately left running (same guard as gateway/run.py)."""
  474. task_id = getattr(agent, "_gateway_turn_process_task_id", "")
  475. epoch = getattr(agent, "_gateway_turn_process_epoch", None)
  476. if task_id and epoch is not None:
  477. with _TURN_PROCESS_EPOCH_LOCK:
  478. # Prune only when this run is still the current claimant; a
  479. # newer concurrent run owns the entry otherwise.
  480. if _TURN_PROCESS_EPOCHS.get(task_id) == epoch:
  481. del _TURN_PROCESS_EPOCHS[task_id]
  482. agent._gateway_turn_process_task_id = ""
  483. agent._gateway_turn_process_baseline = frozenset()
  484. agent._gateway_turn_process_epoch = None
  485. def _session_chat_user_message(body: dict[str, Any], *, param: str = "message") -> tuple[Any, Optional[web.Response]]:
  486. """Parse and normalize session chat ``message`` / ``input`` like chat completions."""
  487. user_message = body.get("message") or body.get("input")
  488. if not _content_has_visible_payload(user_message):
  489. return None, _error_response("Missing 'message' field", 400, code="missing_message")
  490. try:
  491. return _normalize_multimodal_content(user_message), None
  492. except ValueError as exc:
  493. return None, _multimodal_validation_error(exc, param=param)
  494. def _request_turn_author(body: dict[str, Any]) -> Optional[dict[str, Any]]:
  495. """Normalized body ``author``, None when absent or null, ValueError when not an object. It only labels memory."""
  496. raw = body.get("author")
  497. if raw is None:
  498. return None
  499. if not isinstance(raw, dict):
  500. raise ValueError("author must be an object")
  501. from agent.turn_author import parse_turn_author
  502. return parse_turn_author(raw)
  503. _USAGE_TOKEN_KEYS = ("input_tokens", "output_tokens", "total_tokens")
  504. def _chat_usage_payload(usage: dict[str, Any]) -> dict[str, int]:
  505. """OpenAI Chat Completions ``usage`` block (prompt/completion/total) from the agent's usage."""
  506. values = (usage.get(key, 0) for key in _USAGE_TOKEN_KEYS)
  507. return dict(zip(("prompt_tokens", "completion_tokens", "total_tokens"), values))
  508. def _responses_usage_payload(usage: dict[str, Any]) -> dict[str, int]:
  509. """OpenAI Responses ``usage`` block from the agent's usage dict."""
  510. return {key: usage.get(key, 0) for key in _USAGE_TOKEN_KEYS}
  511. async def _abandon_agent_task(
  512. agent_ref, agent_task, reason: str, *,
  513. reap_source: str = "api_server_sse_disconnect", await_cancel: bool = True) -> None:
  514. """Interrupt + reap an abandoned SSE agent run, then cancel its task wrapper.
  515. ``await_cancel=False`` on the CancelledError path, which must not await in the handler."""
  516. agent = agent_ref[0] if agent_ref else None
  517. if agent is not None:
  518. with suppress(Exception):
  519. # The abandoning client/server is the issuer, not the user (#112647).
  520. request_hard_interrupt(agent, reason, tool_reason=reason.lower())
  521. _reap_disconnected_agent_processes(agent, source=reap_source)
  522. if not agent_task.done():
  523. agent_task.cancel()
  524. if await_cancel:
  525. with suppress(asyncio.CancelledError, Exception):
  526. await agent_task
  527. def check_api_server_requirements() -> bool:
  528. """Check if API server dependencies are available."""
  529. return AIOHTTP_AVAILABLE
  530. _CORS_HEADERS = {
  531. "Access-Control-Allow-Methods": "GET, POST, DELETE, OPTIONS",
  532. "Access-Control-Allow-Headers": "Authorization, Content-Type, Idempotency-Key, X-Hermes-Session-Id"}
  533. _SECURITY_HEADERS = {
  534. "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'",
  535. "Permissions-Policy": "camera=(), microphone=(), geolocation=()",
  536. "Strict-Transport-Security": "max-age=31536000; includeSubDomains",
  537. "X-Content-Type-Options": "nosniff",
  538. "X-Frame-Options": "DENY",
  539. "X-XSS-Protection": "0",
  540. "Referrer-Policy": "no-referrer"}
  541. if AIOHTTP_AVAILABLE:
  542. @web.middleware
  543. async def cors_middleware(request, handler):
  544. """Add CORS headers for explicitly allowed origins; handle OPTIONS preflight."""
  545. adapter = request.app.get("api_server_adapter")
  546. origin = request.headers.get("Origin", "")
  547. cors_headers = None
  548. if adapter is not None:
  549. if not adapter._origin_allowed(origin):
  550. return web.Response(status=403)
  551. cors_headers = adapter._cors_headers_for_origin(origin)
  552. if request.method == "OPTIONS":
  553. if cors_headers is None:
  554. return web.Response(status=403)
  555. return web.Response(status=200, headers=cors_headers)
  556. response = await handler(request)
  557. if cors_headers is not None:
  558. response.headers.update(cors_headers)
  559. return response
  560. @web.middleware
  561. async def body_limit_middleware(request, handler):
  562. """Reject overly large request bodies early based on Content-Length."""
  563. if request.method in {"POST", "PUT", "PATCH"}:
  564. cl = request.headers.get("Content-Length")
  565. if cl is not None:
  566. try:
  567. if int(cl) > MAX_REQUEST_BYTES:
  568. return _error_response("Request body too large.", 413, code="body_too_large")
  569. except ValueError:
  570. return _error_response("Invalid Content-Length header.", 400, code="invalid_content_length")
  571. try:
  572. return await handler(request)
  573. except web.HTTPRequestEntityTooLarge:
  574. # client_max_size tripped mid-read (chunked bodies carry no Content-Length): a
  575. # proper 413, not the handler's 400 "Invalid JSON".
  576. return _error_response("Request body too large.", 413, code="body_too_large")
  577. @web.middleware
  578. async def security_headers_middleware(request, handler):
  579. """Add security headers to all responses (including errors)."""
  580. response = await handler(request)
  581. for k, v in _SECURITY_HEADERS.items():
  582. response.headers.setdefault(k, v)
  583. return response
  584. else:
  585. cors_middleware = body_limit_middleware = security_headers_middleware = None # type: ignore
  586. _MEDIA_MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
  587. ".webp": "image/webp", ".bmp": "image/bmp"}
  588. _MEDIA_IMG_EXT = set(_MEDIA_MIME)
  589. _MEDIA_DATA_URL_MAX_BYTES = 5 * 1024 * 1024 # skip images larger than 5MB
  590. def _resolve_media_to_data_urls(text: str) -> str:
  591. """Replace ``MEDIA:<path>`` tags with inline base64 data URLs (remote frontends can't read
  592. server paths); non-image/unreadable paths stay untouched. Security: the shared
  593. ``MEDIA_TAG_CLEANUP_RE`` anchor + ``validate_media_delivery_path`` denylist — a bare-token
  594. match would let a traversal path in the reply exfiltrate any readable image."""
  595. if not text or "MEDIA:" not in text:
  596. return text
  597. import base64
  598. def _to_data_url(path_str: str) -> Optional[str]:
  599. # validate_media_delivery_path() strips wrapping quotes/trailing punctuation itself.
  600. safe_path = validate_media_delivery_path(path_str)
  601. p = Path(safe_path) if safe_path else None
  602. suffix = p.suffix.lower() if p else ""
  603. if suffix not in _MEDIA_IMG_EXT:
  604. return None
  605. try:
  606. if p.stat().st_size > _MEDIA_DATA_URL_MAX_BYTES:
  607. return None
  608. b64 = base64.b64encode(p.read_bytes()).decode()
  609. except OSError:
  610. return None
  611. return f"![image](data:{_MEDIA_MIME[suffix]};base64,{b64})"
  612. def _repl(m: re.Match[str]) -> str:
  613. return _to_data_url(m.group("path")) or m.group(0)
  614. try:
  615. # A leaked terminal <|eos|> glued to the last tag is not a path terminator (#111046):
  616. # scan without it, and drop it (control token, never content) only when a tag resolved.
  617. sentinel_start = _terminal_sentinel_start(text)
  618. scan = text[:sentinel_start] if sentinel_start >= 0 else text
  619. resolved = MEDIA_TAG_CLEANUP_RE.sub(_repl, scan)
  620. return text if resolved == scan else resolved
  621. except Exception:
  622. return text
  623. def _redact_api_error_text(value: Any, *, limit: int | None = None) -> str:
  624. """Redact API-bound error text before it crosses the HTTP boundary."""
  625. redacted = redact_sensitive_text(str(value), force=True)
  626. return redacted[:limit] if limit is not None else redacted
  627. def _openai_error(message: str, err_type: str = "invalid_request_error", param: str | None = None, code: str | None = None) -> dict[str, Any]:
  628. """OpenAI-style error envelope."""
  629. return {"error": {
  630. "message": _redact_api_error_text(message), "type": err_type, "param": param, "code": code}}
  631. def _error_response(
  632. message: str, status: int, *, err_type: str = "invalid_request_error",
  633. param: str | None = None, code: str | None = None, headers: Optional[dict[str, str]] = None,
  634. ) -> web.Response:
  635. """``web.json_response(_openai_error(...), status=...)`` in one call."""
  636. return web.json_response(_openai_error(message, err_type, param, code), status=status, headers=headers)
  637. def _invalid_request(message: str) -> web.Response:
  638. """400 with the bare ``{message, type}`` envelope the OpenAI-compatible validators use."""
  639. return web.json_response({"error": {"message": message, "type": "invalid_request_error"}}, status=400)
  640. _api_agent_request_reservation: ContextVar[Optional[dict[str, bool]]] = ContextVar(
  641. "api_agent_request_reservation", default=None)
  642. def _admit_api_agent_request(handler):
  643. """Reserve an authenticated API turn before its handler first awaits: drain check +
  644. reservation in one non-awaiting block so a request admitted just before shutdown can't go
  645. invisible while parsing its body. The mutable reservation releases the slot exactly once."""
  646. @wraps(handler)
  647. async def _wrapped(self, request, *args, **kwargs):
  648. auth_err = (
  649. self._check_run_auth(request, permission="dispatch")
  650. if _api_runs._uses_room_run_auth(self, request)
  651. else self._check_auth(request))
  652. if auth_err:
  653. return auth_err
  654. draining = self._draining_response()
  655. if draining is not None:
  656. return draining
  657. reservation = {"active": True}
  658. token = _api_agent_request_reservation.set(reservation)
  659. self._pending_agent_requests += 1
  660. try:
  661. return await handler(self, request, *args, **kwargs)
  662. finally:
  663. _release_pending_api_work(self, reservation)
  664. _api_agent_request_reservation.reset(token)
  665. return _wrapped
  666. def _release_pending_api_work(adapter, reservation: dict[str, bool]) -> None:
  667. """Release a pending-work reservation exactly once."""
  668. if reservation["active"]:
  669. reservation["active"] = False
  670. adapter._pending_agent_requests = max(0, adapter._pending_agent_requests - 1)
  671. def _require_auth(handler):
  672. """Run ``self._check_auth`` first and return its 401 instead of the handler."""
  673. @wraps(handler)
  674. async def _wrapped(self, request, *args, **kwargs):
  675. auth_err = self._check_auth(request)
  676. if auth_err:
  677. return auth_err
  678. return await handler(self, request, *args, **kwargs)
  679. return _wrapped
  680. @contextmanager
  681. def _reserve_pending_api_work(adapter):
  682. """Keep externally-triggered background work visible across awaits; a handler may detach
  683. the reservation to a task whose done callback then owns release."""
  684. reservation = {"active": True, "detached": False}
  685. adapter._pending_agent_requests += 1
  686. try:
  687. yield reservation
  688. finally:
  689. if not reservation["detached"]:
  690. _release_pending_api_work(adapter, reservation)
  691. class _IdempotencyCache:
  692. """In-memory idempotency cache with TTL and basic LRU semantics."""
  693. def __init__(self, max_items: int = 1000, ttl_seconds: int = 300):
  694. from collections import OrderedDict
  695. self._store = OrderedDict()
  696. self._inflight: dict[tuple[str, str], asyncio.Task[Any]] = {}
  697. self._ttl = ttl_seconds
  698. self._max = max_items
  699. def _purge(self):
  700. now = time.time()
  701. expired = [k for k, v in self._store.items() if now - v["ts"] > self._ttl]
  702. for k in expired:
  703. self._store.pop(k, None)
  704. while len(self._store) > self._max:
  705. self._store.popitem(last=False)
  706. async def get_or_set(self, key: str, fingerprint: str, compute_coro):
  707. self._purge()
  708. item = self._store.get(key)
  709. if item and item["fp"] == fingerprint:
  710. return item["resp"]
  711. inflight_key = (key, fingerprint)
  712. task = self._inflight.get(inflight_key)
  713. if task is None:
  714. async def _compute_and_store():
  715. resp = await compute_coro()
  716. self._store[key] = {"resp": resp, "fp": fingerprint, "ts": time.time()}
  717. self._purge()
  718. return resp
  719. task = asyncio.create_task(_compute_and_store())
  720. self._inflight[inflight_key] = task
  721. def _clear_inflight(done_task: asyncio.Task[Any]) -> None:
  722. if self._inflight.get(inflight_key) is done_task:
  723. self._inflight.pop(inflight_key, None)
  724. task.add_done_callback(_clear_inflight)
  725. return await asyncio.shield(task)
  726. _idem_cache = _IdempotencyCache()
  727. def _make_request_fingerprint(body: dict[str, Any], keys: list[str]) -> str:
  728. subset = {k: body.get(k) for k in keys}
  729. return hashlib.sha256(repr(subset).encode("utf-8")).hexdigest()
  730. def _names_launch_profile(profile: str) -> bool:
  731. """True when a /p/<profile>/ prefix names the profile this process was LAUNCHED as: its
  732. un-prefixed and prefixed requests are one profile and must key one session."""
  733. try:
  734. from hermes_cli.profiles import profile_matches_home
  735. from hermes_constants import get_routing_process_hermes_home
  736. return profile_matches_home(profile, home=get_routing_process_hermes_home())
  737. except Exception:
  738. return False
  739. def _derive_chat_session_id(system_prompt: Optional[str], first_user_message: str,
  740. profile: Optional[str] = None) -> str:
  741. """Stable session id from the system prompt + first user message (constant across all
  742. turns of an Open WebUI-style conversation), so one Hermes session/sandbox is reused.
  743. A routed ``/p/<profile>/`` prefix namespaces the seed: the id keys process-wide state
  744. (session store, per-session sandbox), so two profiles opening with identical text must not
  745. collide (#123989). Default/standalone ids are unchanged so live conversations survive, and
  746. the launch profile addressed through its own ``/p/<launch>/`` prefix keeps the un-prefixed id."""
  747. seed = f"{system_prompt or ''}\n{first_user_message}"
  748. if profile and profile != "default" and not _names_launch_profile(profile):
  749. seed = f"{profile}\0{seed}"
  750. digest = hashlib.sha256(seed.encode("utf-8")).hexdigest()[:16]
  751. return f"api-{digest}"
  752. _CRON_AVAILABLE = False
  753. try:
  754. from cron.jobs import (
  755. list_jobs as _cron_list, get_job as _cron_get, update_job as _cron_update,
  756. remove_job as _cron_remove, pause_job as _cron_pause, resume_job as _cron_resume,
  757. trigger_job as _cron_trigger)
  758. from cron.scheduler import (
  759. CronSchedulerRegistrationError as _CronSchedulerRegistrationError,
  760. create_job_with_scheduler_registration as _cron_create)
  761. _CRON_AVAILABLE = True
  762. except ImportError:
  763. _cron_list = _cron_get = _cron_create = _cron_update = None
  764. _cron_remove = _cron_pause = _cron_resume = _cron_trigger = None
  765. class _CronSchedulerRegistrationError(RuntimeError):
  766. pass
  767. def _notify_cron_provider_jobs_changed() -> None:
  768. """Best-effort notify of the active cron provider after a REST mutation (built-in: no-op)."""
  769. with suppress(Exception):
  770. from cron.scheduler import _notify_provider_jobs_changed
  771. _notify_provider_jobs_changed()
  772. # Defense-in-depth parity with the cronjob tool's prompt injection scan (the REST
  773. # endpoints are authenticated, so this is not the trust boundary). Optional import:
  774. # a missing scanner must not disable the cron REST API.
  775. try:
  776. from tools.cronjob_tools import _scan_cron_prompt
  777. except Exception: # pragma: no cover - scanner is optional hardening
  778. _scan_cron_prompt = None
  779. # English labels stay as constants: ``gateway.run._GATEWAY_AUTH_ERROR_RE`` / ``_GATEWAY_RATE_LIMIT_RE``
  780. # sniff these words in failure envelopes, so matchers and tests key off them regardless of the
  781. # display language. ``user_text()`` renders the human-facing line through ``t()``.
  782. PROVIDER_AUTH_FAILED_LABEL = "Provider authentication failed"
  783. PROVIDER_RATE_LIMITED_LABEL = "Provider rate-limited"
  784. class _ProviderAuthResolutionError(RuntimeError):
  785. """Provider credential resolution failed. Typed so callers never mislabel other
  786. RuntimeErrors from run_conversation() (e.g. a closed OpenAI client) as auth failures."""
  787. def is_rate_limited(self) -> bool:
  788. """A quota/429 cap with valid credentials must not be labelled an authentication
  789. failure — the cause chain (RuntimeError -> AuthError) tells them apart (#89401)."""
  790. from hermes_cli.auth import is_rate_limited_auth_error
  791. cause = self.__cause__
  792. cause = getattr(cause, "__cause__", None) if isinstance(cause, RuntimeError) else cause
  793. return bool(is_rate_limited_auth_error(cause))
  794. def user_text(self) -> str:
  795. """Raw-surface failure line shown as the assistant reply in API-backed chat UIs."""
  796. label = t("platform.api_server.provider_rate_limited" if self.is_rate_limited()
  797. else "platform.api_server.provider_auth_failed")
  798. return t("platform.api_server.provider_error_line", label=label, error=self)
  799. class _SessionEventQueue:
  800. """Ordered SSE event queue for one /api/sessions/{id}/chat/stream run. ``payload`` stamps
  801. session_id/run_id/seq/ts; ``enqueue`` is executor-thread safe (hops onto the owning loop)."""
  802. def __init__(self, session_id: str, run_id: str):
  803. self.loop = asyncio.get_running_loop()
  804. self.queue: asyncio.Queue[Optional[tuple[str, dict[str, Any]]]] = asyncio.Queue()
  805. self.session_id = session_id
  806. self.run_id = run_id
  807. self.seq = 0
  808. # Cross-thread puts handed to the loop and not yet applied. The loop does not order them
  809. # against the worker future's completion, so the turn's terminal frames wait on flush().
  810. self._inflight = 0
  811. self._inflight_lock = threading.Lock()
  812. def payload(self, name: str, payload: dict[str, Any]) -> tuple[str, dict[str, Any]]:
  813. self.seq += 1
  814. payload.setdefault("session_id", self.session_id)
  815. payload.setdefault("run_id", self.run_id)
  816. payload.setdefault("seq", self.seq)
  817. payload.setdefault("ts", time.time())
  818. return name, payload
  819. def enqueue(self, name: str, payload: dict[str, Any]) -> None:
  820. event = self.payload(name, payload)
  821. try:
  822. running_loop = asyncio.get_running_loop()
  823. except RuntimeError:
  824. running_loop = None
  825. if running_loop is self.loop:
  826. self.queue.put_nowait(event)
  827. return
  828. with self._inflight_lock:
  829. self._inflight += 1
  830. def _apply() -> None:
  831. try:
  832. self.queue.put_nowait(event)
  833. finally:
  834. self._settle_one()
  835. try:
  836. self.loop.call_soon_threadsafe(_apply)
  837. except RuntimeError: # loop closed: the stream is gone, nothing left to deliver to
  838. self._settle_one()
  839. def _settle_one(self) -> None:
  840. with self._inflight_lock:
  841. self._inflight -= 1
  842. async def flush(self) -> None:
  843. """Wait until every event a worker thread enqueued has reached the queue. Call it before
  844. the terminal frames: a commentary/delta/approval handed over before the worker returned
  845. otherwise lands after ``done``/``None`` and the reader never sees it."""
  846. while True:
  847. with self._inflight_lock:
  848. if not self._inflight:
  849. return
  850. await asyncio.sleep(0)
  851. def _room_grant_delegate(name: str):
  852. """Adapter method forwarding to ``api_server_room_grants.<name>`` (looked up at call time so
  853. test patches on that module take effect) with this module's error/profile bindings."""
  854. async def _handler(self, request: web.Request) -> web.Response:
  855. return await getattr(_room_grants, name)(
  856. self, request, _openai_error=_openai_error, _api_request_profile=_api_request_profile)
  857. _handler.__name__ = name
  858. return _handler
  859. def _run_route_delegate(name: str):
  860. """Adapter method forwarding to ``api_server_runs.<name>`` (call-time lookup) with this
  861. module's namespace as ``_api_server``."""
  862. async def _handler(self, request: web.Request) -> web.StreamResponse:
  863. return await getattr(_api_runs, name)(self, request, _api_server=sys.modules[__name__])
  864. _handler.__name__ = name
  865. return _handler
  866. class APIServerAdapter(OpenAICompatRoutesMixin, BasePlatformAdapter):
  867. """aiohttp server routing OpenAI-format requests through hermes-agent's AIAgent."""
  868. # Stateless request/response (``send()`` is a stub): async-delivery tools must not promise
  869. # delivery here, and a resumed turn completes the work rather than asking.
  870. supports_async_delivery: bool = False
  871. # ``/p/<profile>/v1/...`` on the shared listener (``_make_profile_prefix_middleware``).
  872. serves_profile_prefix: bool = True
  873. # Same statelessness applies to the startup auto-resume prompt: no client is waiting to answer "session
  874. # restored — what next?", so a resumed turn should complete the interrupted work rather than acknowledge
  875. # (#57056).
  876. interactive_resume: bool = False
  877. # Opt-in cap (chars) on tool outputs / tool-call arguments in the stored /v1/responses
  878. # transcript; 0 = store verbatim (gateway.api_server.history_tool_output_max_chars, #82513).
  879. _history_tool_output_max_chars: int = 0
  880. # Admission-gated OpenAI-compatible entry points (bodies live in the mixin).
  881. _handle_chat_completions = _admit_api_agent_request(OpenAICompatRoutesMixin._handle_chat_completions)
  882. _handle_responses = _admit_api_agent_request(OpenAICompatRoutesMixin._handle_responses)
  883. def __init__(self, config: PlatformConfig):
  884. super().__init__(config, Platform.API_SERVER)
  885. extra = config.extra or {}
  886. self._host, self._port = listen_address(extra)
  887. self._api_key: str = extra.get("key", _get_scoped_secret("API_SERVER_KEY", ""))
  888. self._cors_origins: tuple[str, ...] = self._parse_cors_origins(
  889. extra.get("cors_origins", os.getenv("API_SERVER_CORS_ORIGINS", "")))
  890. self._model_name: str = self._resolve_model_name(
  891. extra.get("model_name", _get_scoped_secret("API_SERVER_MODEL_NAME", "")))
  892. # alias (client "model") -> {model, provider?, api_key? (UPSTREAM, never logged), base_url?}
  893. self._model_routes: dict[str, dict[str, Any]] = self._parse_model_routes(extra.get("model_routes"))
  894. # Opt-in bare ``model`` passthrough on OpenAI-compatible surfaces (generic clients
  895. # hardcode "gpt-4o" etc., hence off by default).
  896. # Off by default: generic OpenAI clients routinely hardcode model names ("gpt-4o", ...), and
  897. # existing deployments rely on those falling back to the gateway default rather than switching the
  898. # executing model. Requests that send an explicit ``provider`` — and the Hermes-native session-chat
  899. # and /v1/runs endpoints — are always honored regardless of this flag. (Idea credit: PR #22825 by
  900. # @mssteuer.)
  901. self._direct_model_requests: bool = _coerce_request_bool(
  902. extra.get("direct_model_requests"), default=False)
  903. # ``platforms.api_server.tool_progress_events: false`` drops the custom
  904. # ``hermes.tool.progress`` SSE frames from Chat Completions streams for strict OpenAI
  905. # clients that choke on named events (#12020). Default on.
  906. self._tool_progress_events: bool = _coerce_request_bool(
  907. extra.get("tool_progress_events"), default=True)
  908. self._app: Optional[web.Application] = None
  909. self._runner: Optional[web.AppRunner] = None
  910. self._site: Optional[web.TCPSite] = None
  911. from hermes_constants import get_hermes_home
  912. self._response_store = ResponseStore() # this home's; a /p/<profile>/ route gets its own
  913. self._response_store_home = str(get_hermes_home())
  914. self._response_stores: dict[str, ResponseStore] = {}
  915. self._response_store_lock = threading.Lock()
  916. _api_runs._initialize_run_state(self, store_factory=RunIdempotencyStore)
  917. self._session_db: Optional[Any] = None # explicit override (tests/manual wiring)
  918. self._session_dbs: dict[str, Any] = {} # per-profile-home SessionDB cache
  919. self._session_db_cache_lock = threading.Lock()
  920. self._session_db_cache_closed = False
  921. # Last-known-good model per gateway_session_key ("*" = process-wide; never session_id,
  922. # which is per request -> unbounded). Recovers a transient empty model resolution.
  923. self._last_resolved_model: dict[str, str] = {}
  924. self._session_db_lock: Optional[asyncio.Lock] = None # single-flight for lazy init
  925. self._max_concurrent_runs: int = self._resolve_max_concurrent_runs() # 0 disables
  926. self._history_tool_output_max_chars = self._resolve_api_server_int(
  927. "history_tool_output_max_chars", default=0)
  928. # In-flight _run_agent() turns (/v1/runs tracks its own via _active_run_tasks).
  929. # Concurrency cap shared across all agent-serving endpoints (/v1/chat/completions, /v1/responses,
  930. # /v1/runs, /api/sessions/{id}/chat[/stream]). Read from config.yaml
  931. # gateway.api_server.max_concurrent_runs; 0 disables the cap.
  932. # Bounds CPU / memory / upstream-LLM-quota exhaustion from a request flood (#7483).
  933. self._inflight_agent_runs: int = 0
  934. # Every agent inside _run_agent() for shutdown interrupt, keyed by id() (the strong ref
  935. # keeps the id() from recycling); distinct from the run_id-keyed _active_run_agents.
  936. self._shutdown_interruptible_agents: dict[int, Any] = {}
  937. # One memory provider per session across requests (this surface rebuilds the agent per turn).
  938. self._memory_sessions = ApiServerMemorySessions()
  939. self.gateway_runner: Optional[Any] = None # set by gateway/run.py
  940. # Admitted requests not yet in agent bookkeeping, so shutdown drain counts them.
  941. self._pending_agent_requests: int = 0
  942. # Daily API metrics + heartbeat stamps published to gateway runtime status (#52323).
  943. self._metrics_day: str = self._metrics_day_key()
  944. self._metrics_requests_today: int = 0
  945. self._metrics_messages_today: int = 0
  946. self._metrics_tokens_today: int = 0
  947. self._metrics_latency_ms: list[float] = []
  948. self._metrics_last_request_at: Optional[float] = None
  949. self._metrics_last_heartbeat_at: Optional[float] = None
  950. def active_agent_work_count(self) -> int:
  951. """All live agent work: pending admissions + in-flight turns + live /v1/runs tasks
  952. (task-based, since ``_active_run_agents`` has a queued-before-agent gap)."""
  953. try:
  954. return (int(getattr(self, "_pending_agent_requests", 0))
  955. + int(self._inflight_agent_runs)
  956. + sum(not task.done() for task in self._active_run_tasks.values()))
  957. except Exception:
  958. return 0
  959. def interrupt_active_runs(self, reason: str) -> int:
  960. """Interrupt every adapter-owned agent during shutdown (they are not in
  961. ``GatewayRunner._running_agents``): exactly the set the drain waits on. Returns count."""
  962. run_ids = {
  963. run_id for run_id, task in self._active_run_tasks.items() if not task.done()
  964. } | set(self._active_run_agents)
  965. _api_runs._mark_shutdown_interrupted_runs(self, run_ids)
  966. # Dedupe by identity: an agent in both registries must be interrupted once.
  967. agents = {id(agent): agent for agent in (
  968. *self._active_run_agents.values(), *self._shutdown_interruptible_agents.values())
  969. if agent is not None}
  970. interrupted = 0
  971. for agent in agents.values():
  972. try:
  973. if request_hard_interrupt(agent, reason, tool_reason="gateway shutdown"):
  974. interrupted += 1
  975. except Exception as exc:
  976. logger.debug("[api_server] failed interrupting active agent: %s", exc)
  977. return interrupted
  978. def mark_shutdown_requested(self) -> int:
  979. """Persist the gateway drain start on every nonterminal API run."""
  980. return _api_runs._mark_shutdown_requested(self)
  981. @staticmethod
  982. def _gateway_is_draining() -> bool:
  983. """Whether the owning gateway currently refuses new agent turns."""
  984. try:
  985. from gateway.platforms.api_server_fire_startup import runner_is_draining
  986. from gateway.run import _gateway_runner_ref
  987. runner = _gateway_runner_ref()
  988. return bool(runner) and runner_is_draining(runner)
  989. except Exception:
  990. return False
  991. def _draining_response(self) -> Optional[web.Response]:
  992. """Return a retryable response while the gateway drains existing work."""
  993. if not self._gateway_is_draining():
  994. return None
  995. return _error_response(
  996. "Gateway is draining existing work; retry shortly.", 503, code="gateway_draining",
  997. headers={"Retry-After": "1"})
  998. def _activate_admitted_request(self) -> None:
  999. """Transfer this request's drain reservation to agent bookkeeping."""
  1000. reservation = _api_agent_request_reservation.get()
  1001. if reservation:
  1002. _release_pending_api_work(self, reservation)
  1003. def _readiness_work_counts(self) -> tuple[int, int, int]:
  1004. """Return bounded work counts from each subsystem's public state."""
  1005. active_api_runs = self._active_structured_run_count()
  1006. process_depth = 0
  1007. active_delegations = 0
  1008. with suppress(Exception):
  1009. from tools.process_registry import process_registry
  1010. process_depth = process_registry.completion_queue.qsize()
  1011. with suppress(Exception):
  1012. from tools.async_delegation import active_count
  1013. active_delegations = active_count()
  1014. return active_api_runs, process_depth, active_delegations
  1015. def _active_structured_run_count(self) -> int:
  1016. """Count structured runs that still have executable work."""
  1017. # "stopping" is not terminal: executor work continues until the agent notices.
  1018. return sum(
  1019. 1
  1020. for status in self._run_statuses.values()
  1021. if status.get("status") in {"queued", "running", "waiting_for_approval", "stopping"}
  1022. )
  1023. @staticmethod
  1024. def _parse_cors_origins(value: Any) -> tuple[str, ...]:
  1025. """Normalize configured CORS origins into a stable tuple."""
  1026. if not value:
  1027. return ()
  1028. items = (
  1029. value.split(",") if isinstance(value, str)
  1030. else value if isinstance(value, (list, tuple, set)) else [str(value)])
  1031. return tuple(str(item).strip() for item in items if str(item).strip())
  1032. @staticmethod
  1033. def _resolve_max_concurrent_runs() -> int:
  1034. """gateway.api_server.max_concurrent_runs (0 disables; default 10; negatives -> 0)."""
  1035. return APIServerAdapter._resolve_api_server_int("max_concurrent_runs", default=10)
  1036. @staticmethod
  1037. def _resolve_api_server_int(key: str, *, default: int) -> int:
  1038. """Integer setting under gateway.api_server (unreadable config -> default; negatives -> 0)."""
  1039. try:
  1040. from hermes_cli.config import cfg_get, load_config
  1041. value = int(cfg_get(load_config(), "gateway", "api_server", key, default=default))
  1042. except Exception:
  1043. return default
  1044. return max(0, value)
  1045. @staticmethod
  1046. def _metrics_day_key(timestamp: Optional[float] = None) -> str:
  1047. """Return the UTC day bucket for daily API metrics."""
  1048. return time.strftime("%Y-%m-%d", time.gmtime(timestamp or time.time()))
  1049. @staticmethod
  1050. def _iso_timestamp(timestamp: Optional[float]) -> Optional[str]:
  1051. if timestamp is None:
  1052. return None
  1053. return datetime.fromtimestamp(timestamp, UTC).isoformat()
  1054. def _reset_metrics_if_needed(self) -> None:
  1055. current_day = self._metrics_day_key()
  1056. if self._metrics_day == current_day:
  1057. return
  1058. self._metrics_day = current_day
  1059. self._metrics_requests_today = 0
  1060. self._metrics_messages_today = 0
  1061. self._metrics_tokens_today = 0
  1062. self._metrics_latency_ms.clear()
  1063. @staticmethod
  1064. def _total_tokens_from_usage(usage: Optional[dict[str, Any]]) -> int:
  1065. if not isinstance(usage, dict):
  1066. return 0
  1067. try:
  1068. return max(0, int(usage.get("total_tokens") or 0))
  1069. except (TypeError, ValueError):
  1070. return 0
  1071. @staticmethod
  1072. def _latency_p95_ms(samples: list[float]) -> Optional[float]:
  1073. if not samples:
  1074. return None
  1075. ordered = sorted(samples)
  1076. index = max(0, min(len(ordered) - 1, int(len(ordered) * 0.95 + 0.999999) - 1))
  1077. return round(ordered[index], 2)
  1078. def _api_server_status_payload(self, *, heartbeat_at: Optional[float] = None) -> dict[str, Any]:
  1079. self._reset_metrics_if_needed()
  1080. heartbeat = self._metrics_last_heartbeat_at if heartbeat_at is None else heartbeat_at
  1081. return {
  1082. "host": self._host,
  1083. "port": self._port,
  1084. "active_runs": self._active_structured_run_count() + self._inflight_agent_runs,
  1085. "stored_runs": len(self._run_statuses),
  1086. "last_request_at": self._iso_timestamp(self._metrics_last_request_at),
  1087. "last_heartbeat": self._iso_timestamp(heartbeat),
  1088. "metrics_today": {
  1089. "day": self._metrics_day,
  1090. "requests": self._metrics_requests_today,
  1091. "messages": self._metrics_messages_today,
  1092. "tokens": self._metrics_tokens_today,
  1093. "latency_p95_ms": self._latency_p95_ms(self._metrics_latency_ms),
  1094. },
  1095. }
  1096. def _publish_runtime_status(self) -> None:
  1097. self._metrics_last_heartbeat_at = time.time()
  1098. self._write_runtime_status_safe(
  1099. "api_server_heartbeat",
  1100. platform_state="connected" if self.is_connected else "disconnected",
  1101. platform_metrics=self._api_server_status_payload(),
  1102. )
  1103. def _record_api_metrics(self, usage: Optional[dict[str, Any]], latency_seconds: float) -> None:
  1104. self._reset_metrics_if_needed()
  1105. self._metrics_requests_today += 1
  1106. self._metrics_messages_today += 1
  1107. self._metrics_tokens_today += self._total_tokens_from_usage(usage)
  1108. self._metrics_last_request_at = time.time()
  1109. self._metrics_latency_ms.append(max(0.0, latency_seconds * 1000.0))
  1110. if len(self._metrics_latency_ms) > API_SERVER_LATENCY_SAMPLE_LIMIT:
  1111. del self._metrics_latency_ms[:-API_SERVER_LATENCY_SAMPLE_LIMIT]
  1112. self._publish_runtime_status()
  1113. async def _heartbeat_loop(self) -> None:
  1114. while self.is_connected:
  1115. self._publish_runtime_status()
  1116. if not self.is_connected:
  1117. break
  1118. await asyncio.sleep(API_SERVER_HEARTBEAT_SECONDS)
  1119. @staticmethod
  1120. def _resolve_model_name(explicit: str) -> str:
  1121. """Advertised /v1/models name: explicit override > active profile name > "hermes-agent"
  1122. (precedence owned by ``hermes_cli.model_switch.resolve_effective_model``)."""
  1123. from hermes_cli.model_switch import resolve_effective_model
  1124. profile_name = ""
  1125. with suppress(Exception):
  1126. from hermes_cli.profiles import get_active_profile_name
  1127. profile = get_active_profile_name() # launch profile, pre-identity (advertised model name)
  1128. if profile and profile not in {"default", "custom"}:
  1129. profile_name = profile
  1130. return resolve_effective_model(explicit, profile_name, "hermes-agent")
  1131. def _cors_headers_for_origin(self, origin: str) -> Optional[dict[str, str]]:
  1132. """Return CORS headers for an allowed browser origin."""
  1133. if not origin or not self._cors_origins:
  1134. return None
  1135. if "*" in self._cors_origins:
  1136. return {**_CORS_HEADERS, "Access-Control-Allow-Origin": "*", "Access-Control-Max-Age": "600"}
  1137. if origin not in self._cors_origins:
  1138. return None
  1139. return {**_CORS_HEADERS, "Access-Control-Allow-Origin": origin, "Vary": "Origin",
  1140. "Access-Control-Max-Age": "600"}
  1141. def _sse_headers(self, request: web.Request, extra: Optional[dict[str, str]] = None) -> dict[str, str]:
  1142. """Headers for an SSE StreamResponse prepared inside a handler: the CORS middleware only
  1143. touches the response after the handler returns, by which point ``prepare()`` has already
  1144. flushed the head, so CORS must be resolved up front (#72892, #6358)."""
  1145. headers = {"Content-Type": "text/event-stream", "Cache-Control": "no-cache", "X-Accel-Buffering": "no"}
  1146. headers.update(self._cors_headers_for_origin(request.headers.get("Origin", "")) or {})
  1147. if extra:
  1148. headers.update(extra)
  1149. return headers
  1150. def _origin_allowed(self, origin: str) -> bool:
  1151. """Allow non-browser clients and explicitly configured browser origins."""
  1152. return not origin or "*" in self._cors_origins or origin in self._cors_origins
  1153. @staticmethod
  1154. def _clean_log_value(value: Any, *, max_len: int = 200) -> str:
  1155. """Sanitize request metadata before it reaches security logs."""
  1156. if value is None:
  1157. return ""
  1158. text = str(value).replace("\r", " ").replace("\n", " ").strip()
  1159. return text[:max_len]
  1160. def _request_audit_context(self, request: web.Request) -> dict[str, str]:
  1161. """Return non-secret source metadata for security/audit warnings."""
  1162. peer_ip = ""
  1163. with suppress(Exception):
  1164. peer = request.transport.get_extra_info("peername") if request.transport else None
  1165. if isinstance(peer, (tuple, list)) and peer:
  1166. peer_ip = str(peer[0])
  1167. return {
  1168. "remote": self._clean_log_value(getattr(request, "remote", "") or peer_ip),
  1169. "peer_ip": self._clean_log_value(peer_ip),
  1170. "forwarded_for": self._clean_log_value(request.headers.get("X-Forwarded-For", "")),
  1171. "real_ip": self._clean_log_value(request.headers.get("X-Real-IP", "")),
  1172. "method": self._clean_log_value(request.method, max_len=16),
  1173. "path": self._clean_log_value(request.path_qs, max_len=500),
  1174. "user_agent": self._clean_log_value(request.headers.get("User-Agent", ""), max_len=300)}
  1175. def _request_audit_log_suffix(self, request: web.Request) -> str:
  1176. ctx = self._request_audit_context(request)
  1177. fields = [f"{key}={value!r}" for key, value in ctx.items() if value]
  1178. return " ".join(fields) if fields else "source='unknown'"
  1179. def _cron_origin_from_request(self, request: web.Request) -> dict[str, str]:
  1180. """Persist safe API source metadata on cron jobs created over HTTP."""
  1181. ctx = self._request_audit_context(request)
  1182. origin = {"platform": "api_server", "chat_id": "api"}
  1183. for ctx_key, origin_key in (("remote", "source_ip"), ("peer_ip", "peer_ip"),
  1184. ("forwarded_for", "forwarded_for"), ("real_ip", "real_ip"),
  1185. ("user_agent", "user_agent")):
  1186. if ctx.get(ctx_key):
  1187. origin[origin_key] = ctx[ctx_key]
  1188. return origin
  1189. def _expected_api_key(self) -> str:
  1190. """Return the API key authorized for the URL-selected profile."""
  1191. profile = _api_request_profile.get()
  1192. if not profile or profile == "default":
  1193. return self._api_key
  1194. try:
  1195. from agent.secret_scope import get_secret
  1196. from hermes_cli.auth import has_usable_secret
  1197. key = get_secret("API_SERVER_KEY", "") or ""
  1198. return key if has_usable_secret(key, min_length=16) else ""
  1199. except Exception as exc:
  1200. # Fail closed; never log the key or exception text.
  1201. logger.warning(
  1202. "Failed to resolve a usable profile-scoped API_SERVER_KEY for %r: %s",
  1203. profile, type(exc).__name__)
  1204. return ""
  1205. @staticmethod
  1206. def _auth_failed_response() -> web.Response:
  1207. return web.json_response(
  1208. {"error": {"message": "Invalid gateway API key (API_SERVER_KEY)", "type": "gateway_auth_error",
  1209. "code": "gateway_auth_failed"}},
  1210. status=401)
  1211. def _check_auth(self, request: web.Request) -> Optional[web.Response]:
  1212. """Validate the Bearer token; None when OK, else a 401. The no-key branch (connect()
  1213. refuses to start without API_SERVER_KEY) exists for tests/manual wiring on the default
  1214. listener only; named profiles fail closed rather than inherit the owner's key."""
  1215. profile = _api_request_profile.get()
  1216. expected_key = self._expected_api_key()
  1217. if not expected_key:
  1218. if not (profile and profile != "default"):
  1219. return None
  1220. logger.warning(
  1221. "API server rejected request for profile %r: no profile-scoped "
  1222. "API_SERVER_KEY is configured; %s",
  1223. profile, self._request_audit_log_suffix(request))
  1224. return self._auth_failed_response()
  1225. auth_header = request.headers.get("Authorization", "")
  1226. if auth_header.startswith("Bearer "):
  1227. token = auth_header[7:].strip()
  1228. # Compare as bytes: compare_digest raises TypeError on non-ASCII str, and the
  1229. # token is raw client input — a stray byte must 401, not 500.
  1230. if hmac.compare_digest(token.encode(), expected_key.encode()):
  1231. return None
  1232. logger.warning("API server rejected invalid API key: %s", self._request_audit_log_suffix(request))
  1233. return self._auth_failed_response()
  1234. @staticmethod
  1235. def _normalize_callback_platform(value: str) -> str:
  1236. normalized = (value or "").strip().lower().replace("-", "_")
  1237. return normalized if re.fullmatch(r"[a-z0-9_]+", normalized) else ""
  1238. def _get_platform_callback_adapter(
  1239. self, request: web.Request, platform_name: str) -> Optional[Any]:
  1240. injected = request.app.get("platform_event_adapters")
  1241. adapter = injected.get(platform_name) if isinstance(injected, dict) else None
  1242. if adapter is None:
  1243. adapter = request.app.get(f"{platform_name}_adapter")
  1244. if adapter is not None:
  1245. return adapter
  1246. runner = self.gateway_runner or request.app.get("gateway_runner")
  1247. if runner is None:
  1248. return None
  1249. # ``/p/<profile>/`` binds the callback to that profile's adapter map; a missing adapter there is a
  1250. # 503, never the primary profile's adapter (verifying/dispatching a secondary's events under the
  1251. # default bot's credentials, #84266). ``_authorization_adapter`` is the shared fail-closed resolver.
  1252. try:
  1253. platform = Platform(platform_name)
  1254. except Exception:
  1255. return None
  1256. return runner._authorization_adapter(platform, _api_request_profile.get())
  1257. async def _handle_platform_event_callback(self, request: web.Request) -> web.Response:
  1258. platform_name = self._normalize_callback_platform(request.match_info.get("platform", ""))
  1259. if not platform_name:
  1260. return _error_response("Invalid platform name", 400, code="invalid_platform")
  1261. adapter = self._get_platform_callback_adapter(request, platform_name)
  1262. if adapter is None:
  1263. return _error_response("Platform adapter is not connected", 503, code="platform_unavailable")
  1264. verifier = getattr(adapter, "verify_http_event_request", None)
  1265. dispatcher = getattr(adapter, "dispatch_http_event", None)
  1266. if verifier is None or dispatcher is None:
  1267. return _error_response(
  1268. "Platform adapter does not support HTTP events", 503, code="platform_http_events_unsupported")
  1269. auth_header = request.headers.get("Authorization", "")
  1270. try:
  1271. ok, code = await _call_verifier(verifier, auth_header)
  1272. except Exception:
  1273. # Fail closed: a crashing verifier must never admit the event.
  1274. logger.exception("Platform HTTP event verifier failed for %s", platform_name)
  1275. ok, code = False, "platform_event_verifier_error"
  1276. if not ok:
  1277. return _error_response(
  1278. "Invalid platform event authorization", 401, code=code or "invalid_platform_event_authorization")
  1279. try:
  1280. payload = await request.json()
  1281. except Exception:
  1282. return _error_response("Invalid JSON in platform event", 400, code="invalid_json")
  1283. if not isinstance(payload, dict):
  1284. return _error_response("Platform event must be a JSON object", 400, code="invalid_request")
  1285. try:
  1286. result = await dispatcher(payload)
  1287. except ParkedRouteRefused as exc: # nothing admitted, nothing acknowledged: the platform retries it
  1288. return _error_response(str(exc), exc.status, err_type="server_error", code=exc.code, headers=exc.headers)
  1289. except Exception:
  1290. logger.exception("Platform HTTP event dispatch failed for %s", platform_name)
  1291. return _error_response("Platform event dispatch failed", 500, err_type="server_error", code="platform_event_dispatch_failed")
  1292. return web.json_response(result if isinstance(result, dict) else {})
  1293. # -- Multi-profile multiplexing (/p/<profile>/...) --------------------------------
  1294. def _resolve_request_profile(self, request: web.Request):
  1295. from gateway.platforms.api_server_profile_prefix import resolve_request_profile
  1296. return resolve_request_profile(self, request)
  1297. @staticmethod
  1298. def _profile_scope(profile: Optional[str]):
  1299. """Enter the multiplex profile runtime scope, or a no-op when unset. No prefix AND
  1300. multiplexing active enters the DEFAULT profile's scope (an unscoped run would raise
  1301. UnscopedSecretError on its first credential read); single-profile gateways no-op.
  1302. Single-profile gateways keep the no-op — ``get_secret`` falls through to ``os.environ`` there,
  1303. unchanged. See #61276.
  1304. """
  1305. if not profile:
  1306. with suppress(Exception):
  1307. from agent.secret_scope import is_multiplex_active
  1308. if is_multiplex_active():
  1309. from gateway.run import _profile_runtime_scope
  1310. from hermes_constants import get_hermes_home
  1311. return _profile_runtime_scope(get_hermes_home())
  1312. return nullcontext()
  1313. from gateway.run import _profile_runtime_scope
  1314. from hermes_cli.profiles import get_profile_dir
  1315. return _profile_runtime_scope(get_profile_dir(profile))
  1316. async def _handle_profile_ingress(self, request: web.Request) -> web.StreamResponse:
  1317. """``/p/<profile>/<tail>`` → the served profile's shared-listener adapter (already scoped by the
  1318. prefix middleware); a profile with no adapter for the path is a 404, never the default's."""
  1319. from gateway.platforms.shared_ingress import dispatch_profile_ingress
  1320. return await dispatch_profile_ingress(
  1321. self.gateway_runner, _api_request_profile.get(), request.match_info.get("tail", ""), request,
  1322. scoped=True)
  1323. def _make_profile_prefix_middleware(self):
  1324. """Reject unknown /p/<profile>/ prefixes and scope the request home."""
  1325. @web.middleware
  1326. async def profile_prefix_middleware(request: web.Request, handler):
  1327. profile = self._resolve_request_profile(request)
  1328. if profile is _PROFILE_REJECTED:
  1329. from gateway.platforms.api_server_profile_prefix import rejection_response
  1330. return rejection_response(request)
  1331. token = _api_request_profile.set(profile)
  1332. try:
  1333. with self._profile_scope(profile):
  1334. return await handler(request)
  1335. finally:
  1336. _api_request_profile.reset(token)
  1337. return profile_prefix_middleware
  1338. def _http_route_table(self) -> list[tuple]:
  1339. """(method, path, handler) rows registered by ``connect()`` (a method so multiplex tests
  1340. can assert the /p/<profile>/ mirrors without a listener)."""
  1341. routes: list[tuple] = [
  1342. ("GET", "/health", self._handle_health),
  1343. ("GET", "/health/detailed", self._handle_health_detailed),
  1344. ("GET", "/v1/health", self._handle_health),
  1345. ("GET", "/v1/models", self._handle_models),
  1346. ("GET", "/api/model/options", self._handle_model_options),
  1347. ("GET", "/v1/capabilities", self._handle_capabilities),
  1348. ("GET", "/v1/skills", self._handle_skills),
  1349. ("GET", "/v1/toolsets", self._handle_toolsets),
  1350. ("GET", "/api/sessions", self._handle_list_sessions),
  1351. ("POST", "/api/sessions", self._handle_create_session),
  1352. ("GET", "/api/sessions/{session_id}", self._handle_get_session),
  1353. ("PATCH", "/api/sessions/{session_id}", self._handle_patch_session),
  1354. ("DELETE", "/api/sessions/{session_id}", self._handle_delete_session),
  1355. ("GET", "/api/sessions/{session_id}/messages", self._handle_session_messages),
  1356. ("POST", "/api/sessions/{session_id}/fork", self._handle_fork_session),
  1357. ("POST", "/api/sessions/{session_id}/chat", self._handle_session_chat),
  1358. ("POST", "/api/sessions/{session_id}/chat/stream", self._handle_session_chat_stream),
  1359. ("POST", "/api/sessions/{session_id}/model", self._handle_session_model_lock),
  1360. ("POST", "/v1/chat/completions", self._handle_chat_completions),
  1361. ("POST", "/v1/responses", self._handle_responses),
  1362. ("GET", "/v1/responses/{response_id}", self._handle_get_response),
  1363. ("DELETE", "/v1/responses/{response_id}", self._handle_delete_response),
  1364. # Platform event ingress: authenticated by the target adapter's own verifier,
  1365. # NOT API_SERVER_KEY (external platforms hold no API server key).
  1366. ("POST", "/api/platforms/{platform}/events", self._handle_platform_event_callback),
  1367. ("GET", "/api/jobs", self._handle_list_jobs),
  1368. ("POST", "/api/jobs", self._handle_create_job),
  1369. ("GET", "/api/jobs/{job_id}", self._handle_get_job),
  1370. ("PATCH", "/api/jobs/{job_id}", self._handle_update_job),
  1371. ("DELETE", "/api/jobs/{job_id}", self._handle_delete_job),
  1372. ("POST", "/api/jobs/{job_id}/pause", self._handle_pause_job),
  1373. ("POST", "/api/jobs/{job_id}/resume", self._handle_resume_job),
  1374. ("POST", "/api/jobs/{job_id}/run", self._handle_run_job)]
  1375. routes.extend(_room_grants._http_routes(self))
  1376. routes.extend(_api_runs._http_routes(self))
  1377. if _CRON_AVAILABLE:
  1378. # Chronos fire webhook (NAS -> agent): authenticated by a NAS-minted JWT.
  1379. routes.append(("POST", "/api/cron/fire", self._handle_cron_fire))
  1380. return routes
  1381. # -- Session header helpers -------------------------------------------------------
  1382. # Cap on session headers: above any realistic channel id, safe for Honcho / state.db.
  1383. _MAX_SESSION_HEADER_LEN = 256
  1384. # Source stamped on every session row this platform owns (also hardwired in
  1385. # _bind_api_server_session and _create_agent) so peer lookups can filter on it.
  1386. _SESSION_SOURCE = "api_server"
  1387. def _declared_conversation_session(self, gateway_session_key: Optional[str]) -> Optional[str]:
  1388. """Resolve the live session a client declared with ``X-Hermes-Session-Key`` (the key
  1389. names the conversation, ``session_id`` its current transcript). Same reset-fenced
  1390. recovery as ``SessionStore._recover_session_for_peer``; concurrent first requests
  1391. converge (later row wins). None when undeclared, no live row, or DB error."""
  1392. key = (gateway_session_key or "").strip()
  1393. db = self._ensure_session_db() if key else None
  1394. if db is None:
  1395. return None
  1396. if getattr(self.gateway_runner, 'session_authority', None) is not None:
  1397. from gateway.session_api import declared_api_session
  1398. return declared_api_session(db, key)
  1399. try:
  1400. row = db.find_latest_gateway_session_for_peer(
  1401. source=self._SESSION_SOURCE, session_key=key)
  1402. except Exception:
  1403. logger.debug("[%s] declared-conversation lookup failed", self.name, exc_info=True)
  1404. return None
  1405. return str(row["id"]) if row and row.get("id") else None
  1406. def _bind_declared_conversation(
  1407. self, session_id: Optional[str], gateway_session_key: Optional[str]) -> None:
  1408. """Record the declared conversation key on the session row (AIAgent writes it unkeyed);
  1409. ``include_compression_ancestors`` covers a mid-turn rotation. UPDATE: no-op w/o a row.
  1410. ``include_compression_ancestors`` carries the key up a mid-turn compression rotation so the pre- and
  1411. post-rotation rows of one conversation share it, while that same walk deliberately stops at
  1412. ``/branch``, delegate and tool children (#79161). The statement is an UPDATE, so it is a harmless
  1413. no-op on a turn that failed before the row was created.
  1414. """
  1415. key = (gateway_session_key or "").strip()
  1416. sid = str(session_id or "").strip()
  1417. db = self._ensure_session_db() if key and sid else None
  1418. if db is None:
  1419. return
  1420. try:
  1421. # Never rewrite a row that already belongs to a different conversation
  1422. # (record_gateway_session_peer does SET session_key = ?).
  1423. existing = db.get_session(sid) or {}
  1424. current = str(existing.get("session_key") or "").strip()
  1425. if current and current != key:
  1426. logger.debug(
  1427. "[%s] refusing to rebind session %s from a different declared conversation",
  1428. self.name, sid)
  1429. return
  1430. db.record_gateway_session_peer(
  1431. sid, source=self._SESSION_SOURCE, session_key=key,
  1432. include_compression_ancestors=True)
  1433. except Exception:
  1434. logger.debug(
  1435. "[%s] declared-conversation bind failed for %s", self.name, sid, exc_info=True)
  1436. def _parse_session_key_header(
  1437. self, request: web.Request) -> tuple[Optional[str], Optional[web.Response]]:
  1438. """Validate ``X-Hermes-Session-Key`` (per-channel memory scope) -> ``(key_or_None, None)``
  1439. or ``(None, error)``. Requires API-key auth so a client can't guess another scope."""
  1440. raw = request.headers.get("X-Hermes-Session-Key", "").strip()
  1441. if not raw:
  1442. return None, None
  1443. if not self._api_key:
  1444. logger.warning(
  1445. "X-Hermes-Session-Key rejected: no API key configured. "
  1446. "Set API_SERVER_KEY to enable long-term memory scoping.")
  1447. return None, _error_response(
  1448. "X-Hermes-Session-Key requires API key authentication. "
  1449. "Configure API_SERVER_KEY to enable this feature.", 403)
  1450. # Control characters could enable header injection on the echo path.
  1451. if re.search(r'[\r\n\x00]', raw):
  1452. return None, _invalid_request("Invalid session key")
  1453. if len(raw) > self._MAX_SESSION_HEADER_LEN:
  1454. return None, _invalid_request("Session key too long")
  1455. return raw, None
  1456. # -- Responses state ----------------------------------------------------------------
  1457. def _current_response_store(self) -> ResponseStore:
  1458. """Responses state of the routed profile's home. Conversation names are client-chosen, so one
  1459. shared store let any profile's key read, chain onto and overwrite another's (#84253)."""
  1460. from hermes_constants import get_hermes_home
  1461. home = get_hermes_home()
  1462. if str(home) == self._response_store_home:
  1463. return self._response_store
  1464. with self._response_store_lock:
  1465. store = self._response_stores.get(str(home))
  1466. if store is None:
  1467. store = self._response_stores[str(home)] = ResponseStore(db_path=str(home / "response_store.db"))
  1468. return store
  1469. # -- Session DB -------------------------------------------------------------------
  1470. def _open_and_cache_session_db(self, home) -> Optional[Any]:
  1471. """Cached SessionDB for ``home`` (shared by both ``_ensure_session_db*``). Never writes
  1472. ``self._session_db`` (explicit override only), so no profile pins later requests."""
  1473. if self.gateway_runner is not None:
  1474. from gateway.platforms.api_server_store import selected_session_db
  1475. return selected_session_db(self, home)
  1476. from hermes_state_registry import acquire
  1477. key = str(home)
  1478. with self._session_db_cache_lock:
  1479. if self._session_db_cache_closed:
  1480. return None
  1481. db = self._cached_session_db_locked(key)
  1482. if db is None:
  1483. db = acquire(home / "state.db")
  1484. self._session_dbs[key] = db
  1485. return db
  1486. def _cached_session_db_locked(self, key: str) -> Optional[Any]:
  1487. """Caller holds ``_session_db_cache_lock``. A profile unserve/delete tears the home's
  1488. generation down through ``hermes_state_registry.close_all_under`` (clearing
  1489. ``_shared_registry_owned``) without telling this cache; serving that handle would keep
  1490. raising ``StateDbReplacedError`` after a recreate, so drop it and let the caller reopen."""
  1491. db = self._session_dbs.get(key)
  1492. if db is not None and getattr(db, "_shared_registry_owned", True) is False:
  1493. del self._session_dbs[key]
  1494. return None
  1495. return db
  1496. def _close_cached_session_dbs(self) -> None:
  1497. """Close SessionDB handles owned by this adapter's profile cache."""
  1498. with self._session_db_cache_lock:
  1499. self._session_db_cache_closed = True
  1500. cached = list(self._session_dbs.values())
  1501. self._session_dbs.clear()
  1502. shared_db = getattr(self, "_session_db", None)
  1503. for db in cached:
  1504. if db is shared_db:
  1505. continue
  1506. try:
  1507. from hermes_state_registry import release_or_close
  1508. release_or_close(db)
  1509. except Exception:
  1510. logger.debug("Failed to close API-server SessionDB", exc_info=True)
  1511. def _ensure_session_db(self):
  1512. """SessionDB for the active profile home (the runtime scope redirects ``get_hermes_home()``
  1513. per profile). Sync, for ``_create_agent``; handlers use ``_ensure_session_db_async``."""
  1514. if self.gateway_runner is not None:
  1515. from hermes_constants import get_hermes_home
  1516. from gateway.platforms.api_server_store import selected_session_db
  1517. return selected_session_db(self, get_hermes_home())
  1518. if self._session_db is not None:
  1519. return self._session_db
  1520. try:
  1521. from hermes_constants import get_hermes_home
  1522. return self._open_and_cache_session_db(get_hermes_home())
  1523. except Exception as e:
  1524. logger.debug("SessionDB unavailable for API server: %s", e)
  1525. return None
  1526. async def _ensure_session_db_async(self):
  1527. """Async variant: the profile home is captured on the loop thread (its scope is invisible
  1528. inside ``to_thread``), only the blocking open runs in the worker, single-flight locked."""
  1529. if self.gateway_runner is not None:
  1530. from hermes_constants import get_hermes_home
  1531. from gateway.platforms.api_server_store import selected_session_db
  1532. return selected_session_db(self, get_hermes_home())
  1533. if self._session_db is not None:
  1534. return self._session_db
  1535. try:
  1536. from hermes_constants import get_hermes_home
  1537. home = get_hermes_home()
  1538. key = str(home)
  1539. with self._session_db_cache_lock:
  1540. cached = self._cached_session_db_locked(key)
  1541. if cached is not None:
  1542. return cached
  1543. if self._session_db_lock is None:
  1544. self._session_db_lock = asyncio.Lock()
  1545. async with self._session_db_lock:
  1546. with self._session_db_cache_lock:
  1547. cached = self._cached_session_db_locked(key)
  1548. if cached is not None:
  1549. return cached
  1550. return await asyncio.to_thread(self._open_and_cache_session_db, home)
  1551. except Exception as e:
  1552. logger.debug("SessionDB unavailable for API server: %s", e)
  1553. return None
  1554. # -- Agent creation ---------------------------------------------------------------
  1555. @staticmethod
  1556. def _parse_model_routes(raw: Any) -> dict[str, dict[str, Any]]:
  1557. """Validate ``model_routes`` (``alias -> {model, provider?, api_key?, base_url?}``); invalid
  1558. shapes are dropped, never raised. Route ``api_key`` is an UPSTREAM credential: never log."""
  1559. if not isinstance(raw, dict):
  1560. if raw:
  1561. logger.warning(
  1562. "api_server model_routes ignored: expected a mapping, got %s", type(raw).__name__)
  1563. return {}
  1564. allowed_keys = ("model", "provider", "api_key", "base_url")
  1565. routes: dict[str, dict[str, Any]] = {}
  1566. for alias, cfg in raw.items():
  1567. alias_str = str(alias).strip()
  1568. if not alias_str or not isinstance(cfg, dict):
  1569. logger.warning(
  1570. "api_server model_routes: dropping invalid route entry %r", alias_str or alias)
  1571. continue
  1572. route = {
  1573. key: str(cfg[key]).strip()
  1574. for key in allowed_keys
  1575. if cfg.get(key) is not None and str(cfg[key]).strip()}
  1576. if not route.get("model"):
  1577. logger.warning(
  1578. "api_server model_routes: route %r has no 'model'; dropping", alias_str)
  1579. continue
  1580. routes[alias_str] = route
  1581. return routes
  1582. def _resolve_route(self, model_alias: Any) -> Optional[dict[str, Any]]:
  1583. """Return the model_routes entry for *model_alias*, or None."""
  1584. return self._model_routes.get(model_alias) if isinstance(model_alias, str) else None
  1585. def _stored_session_model(self, session: Any) -> Optional[str]:
  1586. """The model persisted on a session row, minus the virtual alias (replaying
  1587. "hermes-agent" upstream as a provider model id 400s)."""
  1588. stored = session.get("model") if isinstance(session, dict) else None
  1589. if not stored or stored == self._model_name:
  1590. return None
  1591. return stored
  1592. @staticmethod
  1593. def _clean_runtime_id(value: Any, *, max_len: int = 200) -> str:
  1594. text = "" if value is None else str(value).strip()
  1595. return "" if len(text) > max_len or re.search(r"[\r\n\x00]", text) else text
  1596. @classmethod
  1597. def _split_provider_prefixed_model(cls, model: str) -> tuple[str, str]:
  1598. text = cls._clean_runtime_id(model)
  1599. if "::" in text:
  1600. provider, raw = text.split("::", 1)
  1601. if re.match(r"^[a-zA-Z0-9_.-]{2,64}$", provider) and raw.strip():
  1602. return provider, raw.strip()
  1603. return "", text
  1604. @classmethod
  1605. def _runtime_options_from_model_options(cls, model_options: Any) -> dict[str, Any]:
  1606. if not isinstance(model_options, dict):
  1607. return {}
  1608. runtime_options: dict[str, Any] = {}
  1609. reasoning = model_options.get("reasoning")
  1610. if isinstance(reasoning, dict):
  1611. enabled = reasoning.get("enabled")
  1612. effort = cls._clean_runtime_id(reasoning.get("effort"), max_len=32)
  1613. if enabled is False:
  1614. runtime_options["reasoning_config"] = {"enabled": False}
  1615. elif effort:
  1616. runtime_options["reasoning_config"] = {"enabled": True, "effort": effort}
  1617. elif enabled is True:
  1618. runtime_options["reasoning_config"] = {"enabled": True}
  1619. service_tier = cls._clean_runtime_id(model_options.get("service_tier"), max_len=32)
  1620. if service_tier:
  1621. runtime_options["service_tier"] = service_tier
  1622. elif _coerce_request_bool(model_options.get("fast"), default=False):
  1623. runtime_options["service_tier"] = "priority"
  1624. return runtime_options
  1625. def _session_runtime_request_from_body(self, body: dict[str, Any]) -> dict[str, Any]:
  1626. raw_model = self._clean_runtime_id(body.get("model") or body.get("model_id"))
  1627. raw_provider = self._clean_runtime_id(body.get("provider") or body.get("provider_id"), max_len=80)
  1628. prefixed_provider, split_model = self._split_provider_prefixed_model(raw_model)
  1629. provider = raw_provider or prefixed_provider
  1630. model = split_model or raw_model
  1631. alias_route = self._resolve_route(raw_model) or self._resolve_route(model)
  1632. route = dict(alias_route) if isinstance(alias_route, dict) else None
  1633. # The virtual alias is not a provider model id: null it upstream of route-building and
  1634. # every "requested" dict so it is never persisted or misread as a raw override.
  1635. if model == self._model_name:
  1636. model = None
  1637. route_source = "model_routes" if route else "global"
  1638. if not route and model:
  1639. route = {"model": model}
  1640. if provider:
  1641. route["provider"] = provider
  1642. route_source = "raw_request"
  1643. return {
  1644. "requested": {"provider": provider, "model": model, "raw_model": raw_model},
  1645. "route": route, "route_source": route_source,
  1646. "runtime_options": self._runtime_options_from_model_options(body.get("model_options")),
  1647. "require_model_lock": _coerce_request_bool(body.get("require_model_lock"), default=False),
  1648. "model_options": (
  1649. body.get("model_options") if isinstance(body.get("model_options"), dict) else {})}
  1650. @classmethod
  1651. def _requested_ids(cls, requested: Any) -> tuple[str, str]:
  1652. """``(model, provider)`` cleaned from a ``requested``/lock mapping."""
  1653. requested = requested or {}
  1654. return (cls._clean_runtime_id(requested.get("model")),
  1655. cls._clean_runtime_id(requested.get("provider"), max_len=80))
  1656. def _runtime_lock_error(self, runtime_request: dict[str, Any]) -> Optional[web.Response]:
  1657. if not runtime_request.get("require_model_lock"):
  1658. return None
  1659. model, provider = self._requested_ids(runtime_request.get("requested"))
  1660. route = runtime_request.get("route")
  1661. if not model and not provider:
  1662. return _error_response(
  1663. "require_model_lock was set but no model/provider was provided", 400, code="missing_model")
  1664. if not route or runtime_request.get("route_source") == "global":
  1665. return _error_response(
  1666. "Requested Browser model lock cannot be routed; refusing silent global fallback",
  1667. 409, code="model_lock_unavailable")
  1668. return None
  1669. def _persist_session_runtime_lock(self, session_id: str, runtime_request: dict[str, Any]) -> bool:
  1670. # Persist only a newly confirmed lock: a reused stored lock must not be rewritten each
  1671. # turn, and a one-off request override must not erase a confirmed lock.
  1672. if runtime_request.get("persisted_lock") or not runtime_request.get("require_model_lock"):
  1673. return True
  1674. model, provider = self._requested_ids(runtime_request.get("requested"))
  1675. if not model and not provider:
  1676. return False
  1677. db = self._ensure_session_db()
  1678. if db is None:
  1679. return False
  1680. try:
  1681. db.update_session_runtime_lock(
  1682. session_id, model=model or None, provider=provider or None,
  1683. model_options=runtime_request.get("model_options") or {},
  1684. route_source=runtime_request.get("route_source") or "",
  1685. confirmed=bool(runtime_request.get("require_model_lock")))
  1686. return True
  1687. except Exception:
  1688. logger.warning("[%s] failed to persist session runtime lock for %s", self.name, session_id, exc_info=True)
  1689. return False
  1690. @staticmethod
  1691. def _parse_session_model_config(raw: Any) -> dict[str, Any]:
  1692. if isinstance(raw, dict):
  1693. return dict(raw)
  1694. if isinstance(raw, str) and raw.strip():
  1695. with suppress(Exception):
  1696. parsed = json.loads(raw)
  1697. return parsed if isinstance(parsed, dict) else {}
  1698. return {}
  1699. def _runtime_request_from_persisted_session_lock(
  1700. self, session: Optional[dict[str, Any]], body: dict[str, Any]) -> Optional[dict[str, Any]]:
  1701. if not isinstance(session, dict):
  1702. return None
  1703. model_config = self._parse_session_model_config(session.get("model_config"))
  1704. lock = model_config.get("browser_model_lock")
  1705. if not isinstance(lock, dict) or not _coerce_request_bool(lock.get("confirmed"), default=False):
  1706. return None
  1707. model, provider = self._requested_ids(lock)
  1708. if not model and not provider:
  1709. return None
  1710. if self._clean_runtime_id(lock.get("route_source"), max_len=64).lower() == "model_routes":
  1711. route = self._resolve_route(model) if model else None
  1712. else:
  1713. route = {"model": model} if model else {}
  1714. if provider:
  1715. route["provider"] = provider
  1716. model_options = body.get("model_options")
  1717. if not isinstance(model_options, dict):
  1718. model_options = lock.get("model_options")
  1719. return {
  1720. "requested": {"provider": provider, "model": model, "raw_model": model},
  1721. "route": route or None, "route_source": "session_model_lock",
  1722. "runtime_options": self._runtime_options_from_model_options(model_options),
  1723. "require_model_lock": True,
  1724. "model_options": model_options if isinstance(model_options, dict) else {},
  1725. "persisted_lock": True}
  1726. def _effective_session_runtime_request(
  1727. self, *, session: Optional[dict[str, Any]], body: dict[str, Any]) -> dict[str, Any]:
  1728. runtime_request = self._session_runtime_request_from_body(body)
  1729. requested = runtime_request.get("requested") or {}
  1730. if requested.get("model") or requested.get("provider"):
  1731. return runtime_request
  1732. return self._runtime_request_from_persisted_session_lock(session, body) or runtime_request
  1733. @classmethod
  1734. def _sanitize_runtime_metadata(
  1735. cls, *, runtime: Optional[dict[str, Any]] = None, requested_runtime: Optional[dict[str, Any]] = None,
  1736. route_source: str = "global", model_lock: str = "") -> dict[str, Any]:
  1737. payload = dict(runtime or {})
  1738. provider = cls._clean_runtime_id(
  1739. payload.get("provider") or payload.get("provider_id") or payload.get("effective_provider"),
  1740. max_len=80)
  1741. model = cls._clean_runtime_id(payload.get("model") or payload.get("model_id") or payload.get("effective_model"))
  1742. source = cls._clean_runtime_id(payload.get("route_source") or route_source, max_len=64)
  1743. result: dict[str, Any] = {
  1744. "provider": provider, "model": model, "route_source": source or "global"}
  1745. if requested_runtime or payload.get("requested"):
  1746. model, provider = cls._requested_ids(requested_runtime or payload.get("requested"))
  1747. result["requested"] = {"provider": provider, "model": model}
  1748. if model_lock or payload.get("model_lock"):
  1749. result["model_lock"] = cls._clean_runtime_id(model_lock or payload.get("model_lock"), max_len=32)
  1750. return result
  1751. @staticmethod
  1752. def _normalize_session_source(value: Any) -> str:
  1753. text = str(value or "").strip().lower()
  1754. allowed = {"api_server", "hermes_browser", "browser", "cli", "telegram", "discord", "slack", "desktop", "dashboard"}
  1755. if text not in allowed:
  1756. return "api_server"
  1757. return "hermes_browser" if text == "browser" else text
  1758. def _session_model_override_for(self, session_key: Optional[str]) -> Optional[dict[str, Any]]:
  1759. """The gateway's per-session ``/model`` override for *session_key*, if any — a
  1760. user-issued ``/model`` always wins over static route config."""
  1761. if not session_key:
  1762. return None
  1763. try:
  1764. from gateway.run import _gateway_runner_ref
  1765. runner = _gateway_runner_ref()
  1766. if runner is None:
  1767. return None
  1768. try:
  1769. rehydrate = getattr(runner, "_rehydrate_session_model_override", None)
  1770. if callable(rehydrate):
  1771. rehydrate(session_key)
  1772. except Exception:
  1773. logger.debug(
  1774. "api_server failed to rehydrate session /model override for %s", session_key, exc_info=True)
  1775. override = runner._session_model_overrides.get(session_key)
  1776. return dict(override) if isinstance(override, dict) else None
  1777. except Exception:
  1778. return None
  1779. def _request_route_conflict_error(
  1780. self, *, session_id: Optional[str], gateway_session_key: Optional[str], requested_model: Optional[str],
  1781. requested_provider: Optional[str], route: Optional[dict[str, Any]]) -> Optional[str]:
  1782. """Return a 400-worthy conflict string for ambiguous route/provider mixes."""
  1783. request_provider = _clean_request_string(requested_provider)
  1784. if not request_provider or not isinstance(route, dict):
  1785. return None
  1786. if self._session_model_override_for(gateway_session_key or session_id):
  1787. return None # session /model wins over both, so nothing is ambiguous
  1788. route_provider = _clean_request_string(route.get("provider"))
  1789. route_api_key = _clean_request_string(route.get("api_key"))
  1790. route_base_url = _clean_request_string(route.get("base_url"))
  1791. route_alias = _clean_request_string(requested_model) or "requested model"
  1792. if route_provider and request_provider != route_provider:
  1793. return (
  1794. f"Model route '{route_alias}' is pinned to provider '{route_provider}'. "
  1795. f"Remove 'provider' or use '{route_provider}'.")
  1796. if not route_provider and (route_api_key or route_base_url):
  1797. return (
  1798. f"Model route '{route_alias}' pins route credentials/base_url. "
  1799. "Do not combine it with an explicit 'provider'.")
  1800. return None
  1801. @staticmethod
  1802. def _resolve_provider_runtime(
  1803. provider: Optional[str], *, target_model: Optional[str], required: bool,
  1804. ) -> Optional[dict[str, Any]]:
  1805. """Runtime kwargs for ``provider``, falling back to the gateway's resolver; ``required``
  1806. raises ``_ProviderAuthResolutionError`` (controlled response, not a raw 500), not None."""
  1807. provider_name = _clean_request_string(provider)
  1808. if not provider_name:
  1809. return None
  1810. try:
  1811. return _resolve_request_runtime_agent_kwargs(provider_name, target_model=target_model or None)
  1812. except Exception as exc:
  1813. with suppress(Exception):
  1814. from gateway.run import _resolve_runtime_agent_kwargs_for_provider
  1815. return _resolve_runtime_agent_kwargs_for_provider(provider_name, target_model=target_model or None)
  1816. if required:
  1817. raise _ProviderAuthResolutionError(str(exc)) from exc
  1818. logger.debug(
  1819. "api_server provider-runtime refresh failed for provider=%s model=%s",
  1820. provider_name, target_model or "", exc_info=True)
  1821. return None
  1822. def _apply_provider_runtime(
  1823. self, runtime_kwargs: dict[str, Any], provider: Optional[str], *,
  1824. target_model: Optional[str], required: bool = False) -> bool:
  1825. """Resolve ``provider``'s runtime and merge it into ``runtime_kwargs``; True if applied."""
  1826. provider_runtime = self._resolve_provider_runtime(
  1827. provider, target_model=target_model, required=required)
  1828. if provider_runtime:
  1829. _apply_runtime_agent_overrides(runtime_kwargs, provider_runtime)
  1830. return bool(provider_runtime)
  1831. def _recover_or_record_model(self, model: str, runtime_kwargs: dict[str, Any], gateway_session_key) -> str:
  1832. """Fill an empty resolved model: provider's default catalog model, then the last-known-good
  1833. model for this key / process-wide. Non-empty non-virtual models are recorded instead."""
  1834. # No model.default but a provider resolved (e.g. `hermes auth add` without `hermes model`).
  1835. if not model and runtime_kwargs.get("provider"):
  1836. with suppress(Exception):
  1837. from hermes_cli.models import get_default_model_for_provider
  1838. model = get_default_model_for_provider(runtime_kwargs["provider"])
  1839. if model:
  1840. logger.info(
  1841. "No model configured — defaulting to %s for provider %s",
  1842. model, runtime_kwargs["provider"])
  1843. # Keyed by gateway_session_key only (session_id is per-request -> unbounded growth).
  1844. _resolved_key = gateway_session_key or ""
  1845. if not model:
  1846. _recovered = (self._last_resolved_model.get(_resolved_key)
  1847. or self._last_resolved_model.get("*"))
  1848. if _recovered and _recovered != self._model_name:
  1849. logger.warning(
  1850. "Empty model resolved for session=%s — recovering "
  1851. "last-known-good model %s (config read likely returned "
  1852. "empty; see #35314)",
  1853. _resolved_key, _recovered)
  1854. model = _recovered
  1855. elif model != self._model_name:
  1856. if _resolved_key:
  1857. self._last_resolved_model[_resolved_key] = model
  1858. self._last_resolved_model["*"] = model
  1859. return model
  1860. def _select_agent_runtime(
  1861. self, runtime_kwargs: dict[str, Any], model: str, *, requested_model: Optional[str],
  1862. requested_provider: Optional[str], route: Optional[dict[str, Any]], session_model: Optional[str],
  1863. confirmed_runtime_lock: bool, gateway_session_key: Optional[str], session_id: Optional[str]) -> tuple:
  1864. """Apply the model/provider precedence chain for one agent (mutates ``runtime_kwargs``):
  1865. confirmed Browser lock > session ``/model`` override > session-persisted model >
  1866. model_routes alias > per-request provider/model > global defaults. A confirmed lock
  1867. bypasses the override and fails closed if its provider cannot be resolved.
  1868. Returns ``(model, session_override, request_model, request_provider)``."""
  1869. request_model = _clean_request_string(requested_model)
  1870. request_provider = _clean_request_string(requested_provider)
  1871. route_cfg = route if isinstance(route, dict) else {}
  1872. route_model = _clean_request_string(route_cfg.get("model"))
  1873. route_provider = _clean_request_string(route_cfg.get("provider"))
  1874. session_key = gateway_session_key or session_id
  1875. session_row_model = _clean_request_string(session_model)
  1876. current_provider = _clean_request_string(runtime_kwargs.get("provider"))
  1877. session_override = None if confirmed_runtime_lock else self._session_model_override_for(session_key)
  1878. # Model-string precedence (override > session-persisted > global) is owned by
  1879. # hermes_cli.model_switch.resolve_effective_model.
  1880. from hermes_cli.model_switch import resolve_effective_model
  1881. if session_override:
  1882. model = resolve_effective_model(session_override, None, model)
  1883. self._apply_provider_runtime(
  1884. runtime_kwargs,
  1885. _clean_request_string(session_override.get("provider")) or current_provider,
  1886. target_model=model)
  1887. _apply_runtime_agent_overrides(runtime_kwargs, session_override)
  1888. if route or request_model or request_provider:
  1889. logger.debug(
  1890. "api_server request selection skipped: session /model override wins for %s",
  1891. session_key or "")
  1892. elif session_row_model and not confirmed_runtime_lock:
  1893. # A session-persisted raw model (no route alias) is a standing selection that pins
  1894. # this session's turns ahead of per-request body values.
  1895. self._apply_provider_runtime(
  1896. runtime_kwargs, current_provider, target_model=session_row_model)
  1897. model = resolve_effective_model(None, session_row_model, model)
  1898. if request_model or request_provider:
  1899. logger.debug(
  1900. "api_server request selection skipped: session-persisted model wins for %s",
  1901. session_key or "")
  1902. else:
  1903. # The request's ``model`` selected the route, so its value is the ALIAS — never a
  1904. # model name; a route with no ``model`` key keeps the global default.
  1905. effective_model = (route_model or model) if route is not None else (request_model or model)
  1906. effective_provider = request_provider or route_provider or current_provider
  1907. applied = False
  1908. if effective_provider and (bool(request_provider or route_provider) or effective_model != model):
  1909. # A confirmed Browser lock fails closed: never fall through to the previous
  1910. # global provider's credentials.
  1911. applied = self._apply_provider_runtime(
  1912. runtime_kwargs, effective_provider, target_model=effective_model,
  1913. required=bool(request_provider) or confirmed_runtime_lock)
  1914. if not applied and effective_provider and effective_provider != current_provider:
  1915. runtime_kwargs["provider"] = effective_provider
  1916. model = effective_model
  1917. # Per-route explicit transport secrets/base URLs win after provider resolution.
  1918. for key in ("api_key", "base_url"):
  1919. value = _clean_request_string(route_cfg.get(key))
  1920. if value:
  1921. runtime_kwargs[key] = value
  1922. if route:
  1923. logger.debug(
  1924. "api_server request selection applied: model=%s provider=%s route_provider=%s request_provider=%s",
  1925. model, runtime_kwargs.get("provider"), route_provider or "", request_provider or "")
  1926. model = self._recover_or_record_model(model, runtime_kwargs, gateway_session_key)
  1927. return model, session_override, request_model, request_provider
  1928. def _create_agent(
  1929. self, ephemeral_system_prompt: Optional[str] = None, session_id: Optional[str] = None,
  1930. stream_delta_callback=None, tool_progress_callback=None, tool_start_callback=None,
  1931. tool_complete_callback=None, interim_assistant_callback=None, reasoning_callback=None,
  1932. status_callback=None, gateway_session_key: Optional[str] = None,
  1933. requested_model: Optional[str] = None, requested_provider: Optional[str] = None,
  1934. model_options: Optional[dict[str, Any]] = None, route: Optional[dict[str, Any]] = None,
  1935. session_model: Optional[str] = None, confirmed_runtime_lock: bool = False,
  1936. room_dispatch: Optional[dict[str, Any]] = None,
  1937. room_execution_policy: Optional[dict[str, Any]] = None) -> Any:
  1938. """Create an AIAgent from the gateway runtime config + platform toolsets.
  1939. ``gateway_session_key`` persists across transcripts (memory scope), unlike ``session_id``;
  1940. ``route`` / ``session_model`` are mutually exclusive; ``confirmed_runtime_lock`` beats the
  1941. session ``/model`` override, disables the fallback chain and fails closed."""
  1942. from run_agent import AIAgent
  1943. from gateway.run import (
  1944. _checkpoint_agent_kwargs, _current_max_iterations, _resolve_runtime_agent_kwargs,
  1945. _resolve_gateway_model, _load_gateway_config, GatewayRunner)
  1946. from hermes_cli.tools_config import _get_platform_tools
  1947. # RuntimeError is caught ONLY here (sole provider-auth raiser); the typed subclass keeps
  1948. # run_conversation() errors distinct.
  1949. try:
  1950. runtime_kwargs = _resolve_runtime_agent_kwargs()
  1951. except RuntimeError as exc:
  1952. raise _ProviderAuthResolutionError(str(exc)) from exc
  1953. # A fallback-provider runtime carries its own ``model``: pop it (overrides config, and
  1954. # must not collide with the ``**runtime_kwargs`` spread).
  1955. model = runtime_kwargs.pop("model", None) or _resolve_gateway_model()
  1956. runtime_kwargs.pop("_fallback_notice", None) # raw API surface: the switch is already logged
  1957. request_reasoning_config = _request_reasoning_config(model_options)
  1958. request_service_tier = _request_service_tier(model_options)
  1959. model, session_override, request_model, request_provider = self._select_agent_runtime(
  1960. runtime_kwargs, model,
  1961. requested_model=requested_model, requested_provider=requested_provider, route=route,
  1962. session_model=session_model, confirmed_runtime_lock=confirmed_runtime_lock,
  1963. gateway_session_key=gateway_session_key, session_id=session_id)
  1964. user_config = _load_gateway_config()
  1965. enabled_toolsets = sorted(_get_platform_tools(user_config, "api_server"))
  1966. # Same gate the messaging gateway and TUI apply: ``display.interim_assistant_messages``
  1967. # off means no callback is installed, so mid-turn commentary never leaves the agent.
  1968. if not resolve_display_setting(user_config, "api_server", "interim_assistant_messages", True):
  1969. interim_assistant_callback = None
  1970. max_iterations = _current_max_iterations()
  1971. if room_dispatch is not None:
  1972. from gateway.hosted_room_execution_policy import RoomExecutionPolicy
  1973. policy = RoomExecutionPolicy.from_mapping(room_execution_policy or {})
  1974. enabled_toolsets = list(policy.enabled_toolsets)
  1975. max_iterations = policy.max_iterations
  1976. # Reasoning resolves against the model that actually runs (per-model overrides), so only
  1977. # after the precedence chain settles; an explicit request wins.
  1978. if request_reasoning_config is None:
  1979. request_reasoning_config = GatewayRunner._load_reasoning_config(model)
  1980. agent_kwargs = {
  1981. "model": model, **runtime_kwargs, **_checkpoint_agent_kwargs(user_config),
  1982. "max_iterations": max_iterations, "quiet_mode": True, "verbose_logging": False,
  1983. "ephemeral_system_prompt": ephemeral_system_prompt or None,
  1984. "enabled_toolsets": enabled_toolsets, "session_id": session_id,
  1985. "platform": "api_server",
  1986. "stream_delta_callback": stream_delta_callback,
  1987. "tool_progress_callback": tool_progress_callback,
  1988. "tool_start_callback": tool_start_callback,
  1989. "tool_complete_callback": tool_complete_callback,
  1990. "interim_assistant_callback": interim_assistant_callback,
  1991. "reasoning_callback": reasoning_callback,
  1992. "status_callback": status_callback,
  1993. "session_db": self._ensure_session_db(),
  1994. # Same fallback provider chain as Telegram/Discord/Slack.
  1995. "fallback_model": None if confirmed_runtime_lock else GatewayRunner._load_fallback_model(),
  1996. "reasoning_config": request_reasoning_config,
  1997. "gateway_session_key": gateway_session_key,
  1998. # The session's provider from the previous request, so its queued recall reaches this turn
  1999. # (#120116); checked back in by the turn's finally.
  2000. "memory_manager": self._memory_sessions.checkout(session_id)}
  2001. if request_service_tier is not _REQUEST_OPTION_MISSING:
  2002. agent_kwargs["service_tier"] = request_service_tier
  2003. agent = AIAgent(**agent_kwargs)
  2004. route_source = (
  2005. "session_model_lock" if confirmed_runtime_lock
  2006. else "session_model_override" if session_override
  2007. else "raw_request" if route or request_model or request_provider else "global")
  2008. agent._hermes_api_runtime = {
  2009. "provider": runtime_kwargs.get("provider") or getattr(agent, "provider", "") or "",
  2010. "model": getattr(agent, "model", None) or model,
  2011. "route_source": route_source}
  2012. return agent
  2013. # -- HTTP handlers ----------------------------------------------------------------
  2014. async def _handle_health(self, request: web.Request) -> web.Response:
  2015. """GET /health — simple health check."""
  2016. return web.json_response({"status": "ok", "platform": "hermes-agent", "version": _hermes_version()})
  2017. @_require_auth
  2018. async def _handle_health_detailed(self, request: web.Request) -> web.Response:
  2019. """GET /health/detailed — gateway state, platforms, PID for dashboard probing (Bearer auth)."""
  2020. from gateway.status import (
  2021. derive_gateway_busy, derive_gateway_drainable, normalize_updated_at, parse_active_agents,
  2022. read_runtime_status)
  2023. runtime = read_runtime_status() or {}
  2024. gw_state = runtime.get("gateway_state")
  2025. gw_active = parse_active_agents(runtime.get("active_agents", 0))
  2026. # Serve the live adapter's own metrics alongside the persisted platform map: the
  2027. # heartbeat loop keeps the file fresh, but a just-booted or wedged writer would
  2028. # otherwise show boot-time values here too (#52323).
  2029. platforms = runtime.get("platforms", {})
  2030. if not isinstance(platforms, dict):
  2031. platforms = {}
  2032. platforms = dict(platforms)
  2033. api_status = self._api_server_status_payload(heartbeat_at=time.time())
  2034. api_platform = dict(platforms.get("api_server", {}))
  2035. api_platform.setdefault("state", "connected" if self.is_connected else "disconnected")
  2036. api_platform["metrics"] = api_status
  2037. platforms["api_server"] = api_platform
  2038. # Served BY the gateway process, so gateway_running is True by definition; busy/
  2039. # drainable use the same shared contract as /api/status so the two never disagree.
  2040. active_api_runs, process_depth, active_delegations = self._readiness_work_counts()
  2041. from gateway.run import _resolve_gateway_model
  2042. readiness = collect_runtime_readiness(
  2043. configured_model=_resolve_gateway_model(), runtime_status=runtime,
  2044. active_api_runs=active_api_runs, process_completion_queue_depth=process_depth,
  2045. active_delegations=active_delegations)
  2046. return web.json_response({
  2047. "status": readiness["status"], "readiness": readiness, "platform": "hermes-agent",
  2048. "version": _hermes_version(), "gateway_state": gw_state,
  2049. "platforms": platforms,
  2050. "api_server": api_status,
  2051. "metrics_today": api_status["metrics_today"],
  2052. "last_heartbeat": api_status["last_heartbeat"],
  2053. "active_agents": gw_active,
  2054. "gateway_busy": derive_gateway_busy(
  2055. gateway_running=True, gateway_state=gw_state, active_agents=gw_active),
  2056. "gateway_drainable": derive_gateway_drainable(
  2057. gateway_running=True, gateway_state=gw_state),
  2058. "exit_reason": runtime.get("exit_reason"),
  2059. # Contract: RFC3339 string | null, never a number (legacy epoch floats exist).
  2060. "updated_at": normalize_updated_at(runtime.get("updated_at")), "pid": os.getpid()})
  2061. @_require_auth
  2062. async def _handle_models(self, request: web.Request) -> web.Response:
  2063. """GET /v1/models — hermes-agent plus configured model_routes aliases (alias + resolved
  2064. model only, never credentials). Under /p/<profile>/ the primary id follows that profile."""
  2065. now = int(time.time())
  2066. # The middleware already entered the profile scope, so get_active_profile_name() resolves.
  2067. model_name = self._resolve_model_name("") if _api_request_profile.get() else self._model_name
  2068. def _model(mid: str, root: str, parent) -> dict[str, Any]:
  2069. return {"id": mid, "object": "model", "created": now, "owned_by": "hermes", "permission": [],
  2070. "root": root, "parent": parent}
  2071. models = [_model(model_name, model_name, None)]
  2072. models.extend(
  2073. _model(alias, route_cfg.get("model", alias), model_name)
  2074. for alias, route_cfg in self._model_routes.items() if alias != model_name)
  2075. return web.json_response({"object": "list", "data": models})
  2076. @_require_auth
  2077. async def _handle_model_options(self, request: web.Request) -> web.Response:
  2078. """GET /api/model/options — the dashboard/TUI model-picker inventory, so external clients
  2079. can sync to the configured provider catalog instead of scraping /v1/models."""
  2080. refresh = _coerce_request_bool(request.query.get("refresh"), default=False)
  2081. include_unconfigured = _coerce_request_bool(
  2082. request.query.get("include_unconfigured"), default=True)
  2083. try:
  2084. from hermes_cli.inventory import build_model_options_payload, load_picker_context
  2085. def _build_payload() -> dict[str, Any]:
  2086. return build_model_options_payload(
  2087. load_picker_context(), include_unconfigured=include_unconfigured, refresh=refresh)
  2088. # Enrichment can fetch pricing/provider catalogs: keep it off the event loop.
  2089. payload = await asyncio.to_thread(_build_payload)
  2090. return web.json_response(payload)
  2091. except Exception:
  2092. logger.exception("[%s] GET /api/model/options failed", self.name)
  2093. return _error_response("Failed to list model options.", 500, code="model_options_failed")
  2094. @_require_auth
  2095. async def _handle_capabilities(self, request: web.Request) -> web.Response:
  2096. """GET /v1/capabilities — the stable, machine-readable API surface for external UIs."""
  2097. runner = getattr(self, "gateway_runner", None)
  2098. features = {
  2099. "chat_completions": True, "chat_completions_streaming": True,
  2100. "responses_api": True, "responses_streaming": True, "run_submission": True,
  2101. "runs_idempotency": _api_runs._idempotency_capabilities(self, store_type=RunIdempotencyStore),
  2102. **_STATIC_FEATURE_FLAGS,
  2103. "run_unknown_resolution": getattr(runner, "session_authority", None) is not None,
  2104. "cors": bool(self._cors_origins)}
  2105. return web.json_response({
  2106. "object": "hermes.api_server.capabilities", "platform": "hermes-agent",
  2107. "model": self._model_name,
  2108. "auth": {"type": "bearer", "required": bool(self._api_key)},
  2109. "runtime": {
  2110. "mode": "server_agent", "tool_execution": "server", "split_runtime": False,
  2111. "description": (
  2112. "The API server creates a server-side Hermes AIAgent; "
  2113. "tools execute on the API-server host unless a future "
  2114. "explicit split-runtime mode is enabled.")},
  2115. "features": features,
  2116. "endpoints": {
  2117. name: {"method": entry[0], "path": entry[1]}
  2118. for name, entry in _CAPABILITY_ENDPOINTS
  2119. if len(entry) < 3 or features[entry[2]]},
  2120. })
  2121. @_require_auth
  2122. async def _handle_skills(self, request: web.Request) -> web.Response:
  2123. """GET /v1/skills — deterministic JSON listing of installed skills (name, description,
  2124. category), the same set ``/skills list`` shows."""
  2125. try:
  2126. from tools.skills_tool import find_all_skills, sort_skills
  2127. skills = sort_skills(
  2128. find_all_skills(
  2129. skip_disabled=False, include_editorial=True
  2130. )
  2131. )
  2132. except Exception:
  2133. logger.exception("GET /v1/skills failed")
  2134. return _error_response("Failed to enumerate skills", 500, err_type="server_error")
  2135. return web.json_response({"object": "list", "data": skills})
  2136. @_require_auth
  2137. async def _handle_toolsets(self, request: web.Request) -> web.Response:
  2138. """GET /v1/toolsets — each toolset the api_server agent exposes: enabled/configured state
  2139. plus the concrete tool names it expands to."""
  2140. try:
  2141. from hermes_cli.config import load_config
  2142. from hermes_cli.tools_config import (
  2143. _get_effective_configurable_toolsets, _get_platform_tools, _toolset_has_keys,
  2144. get_nous_subscription_features)
  2145. from toolsets import resolve_toolset
  2146. config = load_config()
  2147. enabled_toolsets = _get_platform_tools(config, "api_server", include_default_mcp_servers=False)
  2148. features = get_nous_subscription_features(config)
  2149. data: list[dict[str, Any]] = []
  2150. for name, label, desc in _get_effective_configurable_toolsets():
  2151. try:
  2152. tools = sorted(set(resolve_toolset(name)))
  2153. except Exception:
  2154. tools = []
  2155. data.append({
  2156. "name": name, "label": label, "description": desc,
  2157. "enabled": name in enabled_toolsets,
  2158. "configured": _toolset_has_keys(name, config, features=features),
  2159. "tools": tools})
  2160. except Exception:
  2161. logger.exception("GET /v1/toolsets failed")
  2162. return _error_response("Failed to enumerate toolsets", 500, err_type="server_error")
  2163. return web.json_response({"object": "list", "platform": "api_server", "data": data})
  2164. # -- /api/sessions: thin client/session resource API -------------------------------
  2165. @staticmethod
  2166. def _parse_nonnegative_int(value: Any, default: int, maximum: int) -> int:
  2167. try:
  2168. parsed = int(value)
  2169. except (TypeError, ValueError):
  2170. return default
  2171. return default if parsed < 0 else min(parsed, maximum)
  2172. @staticmethod
  2173. def _session_db_unavailable() -> web.Response:
  2174. return _error_response("Session database unavailable", 503, code="session_db_unavailable")
  2175. @staticmethod
  2176. def _session_response(session: dict[str, Any]) -> dict[str, Any]:
  2177. """Return a stable, client-safe session representation."""
  2178. safe_keys = (
  2179. "id", "source", "user_id", "model", "title", "started_at", "ended_at", "end_reason",
  2180. "message_count", "tool_call_count", "input_tokens", "output_tokens",
  2181. "cache_read_tokens", "cache_write_tokens", "reasoning_tokens", "estimated_cost_usd",
  2182. "actual_cost_usd", "api_call_count", "parent_session_id", "last_active", "preview",
  2183. "_lineage_root_id", "pinned", "archived", "hidden")
  2184. payload = {key: session.get(key) for key in safe_keys if key in session}
  2185. # SQLite stores the flags as 0/1.
  2186. payload.update(
  2187. {f: bool(payload[f]) for f in ("pinned", "archived", "hidden") if f in payload})
  2188. # Full system prompts / model_config never cross the client API; only their presence.
  2189. payload["has_system_prompt"] = bool(session.get("system_prompt"))
  2190. payload["has_model_config"] = bool(session.get("model_config"))
  2191. raw_model_config = session.get("model_config")
  2192. try:
  2193. model_config = (
  2194. json.loads(raw_model_config)
  2195. if isinstance(raw_model_config, str)
  2196. else raw_model_config
  2197. )
  2198. except (TypeError, json.JSONDecodeError):
  2199. model_config = None
  2200. # Exact-id consumers may inspect/resume delegate children even though
  2201. # list endpoints intentionally omit them. Project only the provenance
  2202. # bit the client needs so it cannot accidentally promote such a row
  2203. # into an ordinary session list; never expose the model snapshot.
  2204. payload["is_internal_child"] = bool(
  2205. isinstance(model_config, dict)
  2206. and model_config.get("_delegate_from") is not None
  2207. )
  2208. return payload
  2209. @staticmethod
  2210. def _message_response(message: dict[str, Any]) -> dict[str, Any]:
  2211. message = _project_client_message(message)
  2212. safe_keys = (
  2213. "id", "session_id", "role", "content", "tool_call_id", "tool_calls", "tool_name",
  2214. "timestamp", "token_count", "finish_reason", "reasoning", "reasoning_content",
  2215. "display_kind")
  2216. return {key: message.get(key) for key in safe_keys if key in message}
  2217. async def _read_json_body(self, request: web.Request) -> tuple[dict[str, Any], Optional[web.Response]]:
  2218. try:
  2219. body = await request.json()
  2220. except Exception:
  2221. return {}, _error_response("Invalid JSON in request body", 400)
  2222. if not isinstance(body, dict):
  2223. return {}, _error_response("Request body must be a JSON object", 400)
  2224. return body, None
  2225. async def _get_existing_session_or_404(self, session_id: str) -> tuple[Optional[dict[str, Any]], Optional[web.Response]]:
  2226. db = await self._ensure_session_db_async()
  2227. if db is None:
  2228. return None, self._session_db_unavailable()
  2229. session = await asyncio.to_thread(db.get_session, session_id)
  2230. if not session:
  2231. return None, _error_response(f"Session not found: {session_id}", 404, code="session_not_found")
  2232. return session, None
  2233. async def _conversation_history_for_session(self, session_id: str) -> list[dict[str, Any]]:
  2234. db = await self._ensure_session_db_async()
  2235. if db is None:
  2236. return []
  2237. try:
  2238. return await asyncio.to_thread(db.get_messages_as_conversation, session_id)
  2239. except Exception as exc:
  2240. logger.warning("Failed to load session history for %s: %s", session_id, exc)
  2241. return []
  2242. async def run_internal_session_turn(self, *, session_id: str, text: str, profile: str,
  2243. notification_category: str = "result") -> None:
  2244. """Run one background wake turn against a raw session id IN-PROCESS (no HTTP, no API key);
  2245. see ``api_server_runs.run_internal_session_turn``."""
  2246. await _api_runs.run_internal_session_turn(
  2247. self, session_id=session_id, text=text, profile=profile,
  2248. notification_category=notification_category, _api_server=sys.modules[__name__])
  2249. @_require_auth
  2250. async def _handle_list_sessions(self, request: web.Request) -> web.Response:
  2251. """GET /api/sessions — list persisted Hermes sessions."""
  2252. db = await self._ensure_session_db_async()
  2253. if db is None:
  2254. return self._session_db_unavailable()
  2255. limit = self._parse_nonnegative_int(request.query.get("limit"), default=50, maximum=200)
  2256. offset = self._parse_nonnegative_int(request.query.get("offset"), default=0, maximum=1_000_000)
  2257. source = request.query.get("source") or None
  2258. include_children = _coerce_request_bool(request.query.get("include_children"), default=False)
  2259. # Exact-title lookup (`hermes peer dm` -> canonical "Bot Chat"). include_hidden is honored
  2260. # ONLY with a title filter: a blanket hidden listing stays off this client surface.
  2261. title_filter = (request.query.get("title") or "").strip() or None
  2262. include_hidden = bool(title_filter) and _coerce_request_bool(
  2263. request.query.get("include_hidden"), default=False)
  2264. async def _list() -> list:
  2265. # include_pinned back-fills pins past the recency window; search_query pushes the
  2266. # title needle into SQL (substring) so a hidden/old row is found, exact match below.
  2267. rows = await asyncio.to_thread(
  2268. db.list_sessions_rich, source=source, limit=limit, offset=offset,
  2269. include_children=include_children, order_by_last_active=True, include_pinned=True,
  2270. search_query=title_filter, include_hidden=include_hidden)
  2271. if title_filter:
  2272. rows = [s for s in rows if (s.get("title") or "").strip() == title_filter]
  2273. return rows
  2274. sessions = await _list() or (await reset_local_title_owner(db, title_filter, include_hidden, source))
  2275. if title_filter and not sessions:
  2276. # A canonical Bot Chat auto-archived by the orphan reaper would make `hermes peer dm`
  2277. # mint transient sessions: resurrect and re-list; deliberate archives stay put.
  2278. try:
  2279. # Recoverable-archive resurrection (#92687): a canonical Bot Chat archived by the ws-orphan
  2280. # reaper / older agent cleanup is invisible to list_sessions_rich (include_archived=False),
  2281. # which would fail `hermes peer dm` resolution and mint transient sessions — same accident
  2282. # the tui_gateway lookups heal.
  2283. from tools.bot_mode_probe import BOT_CHAT_TITLE
  2284. def _resurrect() -> bool:
  2285. # Lookup + unarchive (a WRITE with the full write patience) as one worker-thread
  2286. # hop: a contended lock parks this thread, never the event loop (#113772).
  2287. stale = db.get_session_by_title(title_filter)
  2288. return bool(stale and stale.get("archived") and db.unarchive_recoverable_session(stale["id"]))
  2289. if title_filter == BOT_CHAT_TITLE and await asyncio.to_thread(_resurrect):
  2290. sessions = await _list()
  2291. except Exception:
  2292. pass # resolution degrades to today's no-row behavior
  2293. # Back-filled pins arrive PAST the limit: counting them would report a page that doesn't exist.
  2294. windowed = sum(1 for s in sessions if not s.get("pinned"))
  2295. return web.json_response({
  2296. "object": "list", "data": [self._session_response(s) for s in sessions],
  2297. "limit": limit, "offset": offset, "has_more": windowed >= limit})
  2298. @_require_auth
  2299. async def _handle_create_session(self, request: web.Request) -> web.Response:
  2300. """POST /api/sessions -- create an empty Hermes session row. Existence check, insert and
  2301. title handling run as ONE off-loop write so concurrent same-id creates can't both 201."""
  2302. body, err = await self._read_json_body(request)
  2303. if err:
  2304. return err
  2305. from gateway.platforms.api_server_bot_chat import create_peer_bot_chat
  2306. if (bot_chat := await create_peer_bot_chat(self, body)) is not None:
  2307. return bot_chat # the owner minted the canonical Bot Chat (#139370)
  2308. db = await self._ensure_session_db_async()
  2309. if db is None:
  2310. return self._session_db_unavailable()
  2311. raw_id = body.get("id") or body.get("session_id")
  2312. session_id = str(raw_id).strip() if raw_id else f"api_{int(time.time())}_{uuid.uuid4().hex[:8]}"
  2313. from gateway.session import _is_path_unsafe
  2314. if not session_id or re.search(r'[\r\n\x00]', session_id) or _is_path_unsafe(session_id):
  2315. return _error_response("Invalid session ID", 400, code="invalid_session_id")
  2316. if len(session_id) > self._MAX_SESSION_HEADER_LEN:
  2317. return _error_response("Session ID too long", 400, code="invalid_session_id")
  2318. system_prompt = body.get("system_prompt")
  2319. if system_prompt is not None and not isinstance(system_prompt, str):
  2320. return _error_response("system_prompt must be a string", 400, code="invalid_system_prompt")
  2321. source = self._normalize_session_source(body.get("source") or "api_server")
  2322. runtime_request = self._session_runtime_request_from_body(body)
  2323. lock_error = self._runtime_lock_error(runtime_request)
  2324. if lock_error is not None:
  2325. return lock_error
  2326. requested = runtime_request.get("requested") or {}
  2327. # The normalized requested["model"] (prefix split, virtual alias nulled) — the raw body
  2328. # would persist "hermes-agent" and later send it to the provider literally.
  2329. model_name = self._clean_runtime_id(requested.get("model")) or None
  2330. model_config = None
  2331. if requested.get("model") or requested.get("provider"):
  2332. model_config = {"browser_model_lock": {
  2333. "provider": requested.get("provider") or "", "model": requested.get("model") or "",
  2334. "model_options": runtime_request.get("model_options") or {},
  2335. "route_source": runtime_request.get("route_source") or "",
  2336. "confirmed": bool(runtime_request.get("require_model_lock")),
  2337. "updated_at": time.time()}}
  2338. title = body.get("title")
  2339. def _atomic(conn):
  2340. from hermes_state_mutation_retirement import create_conflict
  2341. if conflict := create_conflict(conn, session_id): # one BEGIN IMMEDIATE write: a racing create sees the row
  2342. return None, conflict
  2343. conn.execute(
  2344. """INSERT INTO sessions (
  2345. id, source, model, model_config, system_prompt, started_at
  2346. ) VALUES (?, ?, ?, ?, ?, ?)""",
  2347. (session_id, source, model_name, json.dumps(model_config) if model_config else None,
  2348. system_prompt, time.time()))
  2349. if title is not None:
  2350. clean_title = db.sanitize_title(str(title))
  2351. if clean_title:
  2352. try:
  2353. db._resolve_title_conflict(conn, session_id, clean_title)
  2354. except ValueError as exc: # the DB's uniqueness rule; undo the INSERT
  2355. conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
  2356. return None, f"title:{exc}"
  2357. conn.execute("UPDATE sessions SET title = ? WHERE id = ?", (clean_title, session_id))
  2358. session_row = conn.execute("SELECT * FROM sessions WHERE id = ?", (session_id,)).fetchone()
  2359. return (dict(session_row) if session_row else {
  2360. "id": session_id, "source": source, "model": model_name, "title": title}), None
  2361. session, err = await asyncio.to_thread(db._execute_write, _atomic)
  2362. if isinstance(err, tuple): # a live row, or a deleted id's fence: refused now, not on every turn
  2363. return _error_response(f"{err[1]}: {session_id}", 409, code=err[0])
  2364. if err and err.startswith("title:"):
  2365. return _error_response(err[len("title:"):], 400, code="invalid_title")
  2366. return web.json_response({"object": "hermes.session", "session": self._session_response(session)}, status=201)
  2367. @_require_auth
  2368. async def _handle_get_session(self, request: web.Request) -> web.Response:
  2369. """GET /api/sessions/{session_id}."""
  2370. session, err = await self._get_existing_session_or_404(request.match_info["session_id"])
  2371. if err:
  2372. return err
  2373. return web.json_response({"object": "hermes.session", "session": self._session_response(session)})
  2374. @_require_auth
  2375. async def _handle_patch_session(self, request: web.Request) -> web.Response:
  2376. """PATCH /api/sessions/{session_id} — update client-safe session metadata."""
  2377. session_id = request.match_info["session_id"]
  2378. session, err = await self._get_existing_session_or_404(session_id)
  2379. if err:
  2380. return err
  2381. body, err = await self._read_json_body(request)
  2382. if err:
  2383. return err
  2384. # pinned/archived/unread are durable desktop-sidebar flags.
  2385. unknown = sorted(set(body) - {"title", "end_reason", "pinned", "archived", "hidden", "unread"})
  2386. if unknown:
  2387. return _error_response(
  2388. f"Unsupported session fields: {', '.join(unknown)}", 400, code="unsupported_session_field")
  2389. for flag in ("pinned", "archived", "hidden", "unread"):
  2390. if flag in body and not isinstance(body[flag], bool):
  2391. return _error_response(f"'{flag}' must be a boolean", 400, code="invalid_session_field")
  2392. db = await self._ensure_session_db_async()
  2393. if db is None:
  2394. return self._session_db_unavailable()
  2395. if "title" in body:
  2396. try:
  2397. await asyncio.to_thread(
  2398. db.set_session_title, session_id, "" if body["title"] is None else str(body["title"]))
  2399. except ValueError as exc:
  2400. return _error_response(str(exc), 400, code="invalid_title")
  2401. # Pinned last: set_session_pinned clears hidden, so a pin in the same request
  2402. # wins over an explicit hidden (same order as the dashboard's _RENAME_FLAG_SETTERS).
  2403. for flag, setter in (("archived", db.set_session_archived), ("hidden", db.set_session_hidden),
  2404. ("pinned", db.set_session_pinned)):
  2405. if flag in body:
  2406. await asyncio.to_thread(setter, session_id, body[flag])
  2407. if "unread" in body:
  2408. await asyncio.to_thread(db.set_session_read, session_id, read=not body["unread"])
  2409. if body.get("end_reason"):
  2410. await asyncio.to_thread(db.end_session, session_id, str(body["end_reason"]))
  2411. session = await asyncio.to_thread(db.get_session, session_id) or session
  2412. return web.json_response({"object": "hermes.session", "session": self._session_response(session)})
  2413. @_require_auth
  2414. async def _handle_delete_session(self, request: web.Request) -> web.Response:
  2415. """DELETE /api/sessions/{session_id}."""
  2416. session_id = request.match_info["session_id"]
  2417. _session, err = await self._get_existing_session_or_404(session_id)
  2418. if err:
  2419. return err
  2420. db = await self._ensure_session_db_async()
  2421. if db is None:
  2422. return self._session_db_unavailable()
  2423. # Same profile home the DB was resolved from (the profile middleware scopes
  2424. # get_hermes_home() for this request) — without it the transcript/dump scrub is skipped.
  2425. sessions_dir = None
  2426. try:
  2427. from hermes_constants import get_hermes_home
  2428. sessions_dir = Path(get_hermes_home()) / "sessions"
  2429. except Exception:
  2430. logger.debug("sessions dir unavailable for delete of %s", session_id, exc_info=True)
  2431. try:
  2432. deleted = await asyncio.to_thread(
  2433. db.delete_session, session_id, sessions_dir=sessions_dir, exclude_active_write_guards=True)
  2434. except SessionActiveWriteGuardError as exc:
  2435. return _error_response(str(exc), 409, code="session_active_turn")
  2436. if deleted:
  2437. # A hard delete must also drop the gateway's durable channel→session routing entries
  2438. # for the id, or the next inbound message resolves the SAME id and run_agent's
  2439. # INSERT OR IGNORE resurrects the deleted row (#42422).
  2440. runner = self.gateway_runner or request.app.get("gateway_runner")
  2441. store = getattr(runner, "session_store", None)
  2442. if store is not None:
  2443. await asyncio.to_thread(store.remove_by_session_id, session_id)
  2444. # Retirement erased the chat's image references; bytes nothing else holds go too. Off the
  2445. # loop like every other media release: its holder check and unlink are one write txn.
  2446. from gateway.session_ingress_media import collect_unheld_api_images
  2447. await asyncio.to_thread(collect_unheld_api_images, db)
  2448. return web.json_response({"object": "hermes.session.deleted", "id": session_id, "deleted": bool(deleted)})
  2449. @_require_auth
  2450. async def _handle_session_messages(self, request: web.Request) -> web.Response:
  2451. """GET /api/sessions/{session_id}/messages."""
  2452. session_id = request.match_info["session_id"]
  2453. _, err = await self._get_existing_session_or_404(session_id)
  2454. if err:
  2455. return err
  2456. db = await self._ensure_session_db_async()
  2457. resolved_id = await asyncio.to_thread(db.resolve_resume_session_id, session_id)
  2458. raw_limit, raw_offset = request.query.get("limit"), request.query.get("offset", "0")
  2459. order = request.query.get("order")
  2460. if order not in (None, "oldest", "latest"):
  2461. return _error_response("order must be one of: oldest, latest", 400, code="invalid_pagination")
  2462. try:
  2463. offset = int(raw_offset)
  2464. requested_limit = None if raw_limit is None else int(raw_limit)
  2465. except (TypeError, ValueError):
  2466. offset = requested_limit = -1
  2467. if offset < 0 or (requested_limit is not None and requested_limit < 0):
  2468. return _error_response("limit and offset must be non-negative integers", 400, code="invalid_pagination")
  2469. default_page = requested_limit is None
  2470. latest_page = order == "latest" or (order is None and default_page)
  2471. limit = 500 if default_page else min(requested_limit, 500)
  2472. include_compacted = _coerce_request_bool(request.query.get("include_compacted"), default=False)
  2473. # Compression lineage: return root→tip messages, matching the REST router (#51058).
  2474. messages = await asyncio.to_thread(
  2475. db.get_messages, resolved_id, limit=limit, offset=offset, latest=latest_page,
  2476. include_compacted=include_compacted, include_ancestors=True)
  2477. return web.json_response({
  2478. "object": "list", "session_id": resolved_id,
  2479. "data": [self._message_response(m) for m in messages],
  2480. "pagination": {
  2481. "limit": limit, "offset": offset,
  2482. "order": order or ("latest" if default_page else "oldest"),
  2483. "returned": len(messages)}})
  2484. @_require_auth
  2485. async def _handle_fork_session(self, request: web.Request) -> web.Response:
  2486. """POST /api/sessions/{session_id}/fork — branch via current SessionDB primitives."""
  2487. source_id = request.match_info["session_id"]
  2488. source, err = await self._get_existing_session_or_404(source_id)
  2489. if err:
  2490. return err
  2491. body, err = await self._read_json_body(request)
  2492. if err:
  2493. return err
  2494. db = await self._ensure_session_db_async()
  2495. fork_id = str(body.get("id") or body.get("session_id") or f"api_{int(time.time())}_{uuid.uuid4().hex[:8]}").strip()
  2496. if not fork_id or re.search(r'[\r\n\x00]', fork_id):
  2497. return _error_response("Invalid session ID", 400, code="invalid_session_id")
  2498. if await asyncio.to_thread(db.get_session, fork_id):
  2499. return _error_response(f"Session already exists: {fork_id}", 409, code="session_exists")
  2500. # CLI /branch semantics: create the child, then end the original as branched (child first, so
  2501. # a failed create never leaves the source ended with no fork, #11030).
  2502. # ``_branched_from`` is the durable branch marker (same as CLI /branch): with the child created
  2503. # first, the timestamp fallback in _BRANCH_CHILD_SQL (child.started_at >= parent.ended_at) no
  2504. # longer holds, and an unmarked child would vanish from default session listings.
  2505. await asyncio.to_thread(
  2506. db.create_session, fork_id, "api_server", model=source.get("model"),
  2507. system_prompt=source.get("system_prompt"), parent_session_id=source_id,
  2508. model_config={"_branched_from": source_id})
  2509. await asyncio.to_thread(db.end_session, source_id, "branched")
  2510. messages = await asyncio.to_thread(db.get_messages, source_id)
  2511. await asyncio.to_thread(db.replace_messages, fork_id, messages)
  2512. title = body.get("title")
  2513. if title is None:
  2514. base = source.get("title") or "fork"
  2515. title = f"{base} fork"
  2516. with suppress(Exception):
  2517. title = await asyncio.to_thread(db.get_next_title_in_lineage, base)
  2518. try:
  2519. await asyncio.to_thread(db.set_session_title, fork_id, str(title))
  2520. except ValueError as exc:
  2521. return _error_response(str(exc), 400, code="invalid_title")
  2522. fork = await asyncio.to_thread(db.get_session, fork_id) or {"id": fork_id, "parent_session_id": source_id}
  2523. return web.json_response({"object": "hermes.session", "session": self._session_response(fork)}, status=201)
  2524. async def _prepare_session_chat(self, request: web.Request) -> tuple:
  2525. """Shared prelude for /api/sessions/{id}/chat[/stream]: header/body validation, then
  2526. runtime selection — a Browser model lock (body ``require_model_lock`` or a confirmed
  2527. persisted lock) wins; else the session-persisted model routes via model_routes when an
  2528. alias or threads through as ``session_model`` when raw, then body values.
  2529. Returns ``(ctx, None)`` or ``(None, error)``; ``ctx["run_kwargs"]`` feeds ``_run_agent``."""
  2530. gateway_session_key, key_err = self._parse_session_key_header(request)
  2531. if key_err is not None:
  2532. return None, key_err
  2533. session_id = request.match_info["session_id"]
  2534. session, err = await self._get_existing_session_or_404(session_id)
  2535. if err:
  2536. return None, err
  2537. body, err = await self._read_json_body(request)
  2538. if err:
  2539. return None, err
  2540. user_message, err = _session_chat_user_message(body)
  2541. if err is not None:
  2542. return None, err
  2543. try:
  2544. turn_author = _request_turn_author(body)
  2545. except ValueError as exc:
  2546. return None, _error_response(str(exc), 400, code="invalid_author")
  2547. system_prompt = body.get("system_message") or body.get("instructions")
  2548. if system_prompt is not None and not isinstance(system_prompt, str):
  2549. return None, _error_response("system_message must be a string", 400, code="invalid_system_message")
  2550. runtime_request = self._effective_session_runtime_request(session=session, body=body)
  2551. lock_error = self._runtime_lock_error(runtime_request)
  2552. if lock_error is not None:
  2553. return None, lock_error
  2554. if not await asyncio.to_thread(self._persist_session_runtime_lock, session_id, runtime_request):
  2555. return None, _error_response(
  2556. "Could not persist the requested session model lock", 500, code="model_lock_persistence_failed")
  2557. lock_active = bool(runtime_request.get("require_model_lock"))
  2558. if lock_active:
  2559. route = runtime_request.get("route")
  2560. session_model = None
  2561. requested = runtime_request.get("requested") or {}
  2562. agent_overrides: dict[str, Any] = {}
  2563. for src_key, dst_key in (("model", "requested_model"), ("provider", "requested_provider")):
  2564. if requested.get(src_key):
  2565. agent_overrides[dst_key] = requested[src_key]
  2566. if runtime_request.get("model_options"):
  2567. agent_overrides["model_options"] = runtime_request["model_options"]
  2568. else:
  2569. stored_model = self._stored_session_model(session)
  2570. stored_route = self._resolve_route(stored_model)
  2571. route = stored_route or self._resolve_route(body.get("model"))
  2572. session_model = stored_model if (stored_model and stored_route is None) else None
  2573. agent_overrides = _request_agent_overrides(body, virtual_model=self._model_name)
  2574. selection_error = self._request_route_conflict_error(
  2575. session_id=session_id, gateway_session_key=gateway_session_key,
  2576. requested_model=agent_overrides.get("requested_model"),
  2577. requested_provider=agent_overrides.get("requested_provider"), route=route)
  2578. if selection_error:
  2579. return None, _error_response(selection_error, 400)
  2580. run_kwargs = dict(
  2581. user_message=user_message, ephemeral_system_prompt=system_prompt, session_id=session_id,
  2582. gateway_session_key=gateway_session_key, route=route, session_model=session_model,
  2583. requested_runtime=runtime_request.get("requested") or {},
  2584. route_source=runtime_request.get("route_source") or "global",
  2585. confirmed_runtime_lock=lock_active, turn_author=turn_author,
  2586. # #98619: the client addresses this session by construction — the id is in the
  2587. # request path (/api/sessions/{session_id}/chat) — so a wake self-post lands where
  2588. # the client will read it. The audited native-session opt-in.
  2589. session_history_delivery="1", **agent_overrides)
  2590. return {
  2591. "gateway_session_key": gateway_session_key, "session_id": session_id, "body": body,
  2592. "user_message": user_message, "runtime_request": runtime_request,
  2593. "lock_active": lock_active, "run_kwargs": run_kwargs}, None
  2594. @staticmethod
  2595. def _session_headers(session_id: str, gateway_session_key: Optional[str]) -> dict[str, str]:
  2596. """``X-Hermes-Session-Id`` (+ ``X-Hermes-Session-Key`` when declared) response headers."""
  2597. headers = {"X-Hermes-Session-Id": session_id}
  2598. if gateway_session_key:
  2599. headers["X-Hermes-Session-Key"] = gateway_session_key
  2600. return headers
  2601. def _effective_turn_runtime(self, runtime_request: dict[str, Any], result: Any, usage: Any) -> dict[str, Any]:
  2602. """Sanitized runtime metadata for a finished session-chat turn."""
  2603. runtime = self._result_runtime(result, usage)
  2604. return self._sanitize_runtime_metadata(
  2605. # Same shared ladder /api/status uses. Before this was unified, the two endpoints disagreed on
  2606. # the same page load — the sidebar strip read "running" (it probed GATEWAY_HEALTH_URL and scoped
  2607. # to the requested profile) while the Channels page rendered "The gateway is not running" (it
  2608. # did neither). Cross-container, profile-scoped, and launch-service-managed deployments each hit
  2609. # that split. profile_home is passed when the request was scoped to a named profile:
  2610. # gateway/status readers resolve process-level paths and do NOT follow the HERMES_HOME
  2611. # contextvar override (#56986 / #69143), so the profile's directory has to be handed over
  2612. # explicitly or messaging silently reports another profile's gateway (#71211).
  2613. runtime=runtime,
  2614. requested_runtime=runtime_request.get("requested"),
  2615. route_source=runtime_request.get("route_source") or "global",
  2616. model_lock=self._model_lock_state(runtime_request, runtime))
  2617. @staticmethod
  2618. def _result_runtime(result: Any, usage: Any) -> dict[str, Any]:
  2619. """Runtime metadata from the result dict, falling back to the usage dict."""
  2620. runtime = (result.get("runtime") or {}) if isinstance(result, dict) else {}
  2621. return runtime or ((usage.get("runtime") or {}) if isinstance(usage, dict) else {})
  2622. @staticmethod
  2623. def _model_lock_state(runtime_request: dict[str, Any], runtime: Any) -> str:
  2624. """``confirmed`` once a runtime was observed under a lock, ``accepted`` before, else ``""``."""
  2625. if not runtime_request.get("require_model_lock"):
  2626. return ""
  2627. return "confirmed" if runtime else "accepted"
  2628. async def _admit_to_live_bot_chat(
  2629. self, session_id: str, message: Any, author: Optional[dict[str, Any]],
  2630. ) -> Optional[tuple[Path, dict[str, Any]]]:
  2631. """Admit a turn aimed at the canonical Bot Chat to the Desktop session that holds it live.
  2632. ``(profile home, mailbox record)`` when a live owner took it; None when this process should
  2633. run the turn itself — the session is not the canonical Bot Chat's own lineage, or nobody
  2634. holds that chat. Both peer transports (``/api/sessions/{id}/chat`` for ``peer dm``,
  2635. ``/v1/runs`` for ``peer run``) go through here, so the two lanes cannot drift.
  2636. """
  2637. if not isinstance(message, str):
  2638. return None
  2639. # Under session authority the Bot Chat is a LOCAL session whose only writer is the
  2640. # authority FIFO (a Desktop showing it is a viewer, not a lease holder): the turn enters
  2641. # through the same door as ``bot_relay.deliver`` and the receipt is its admission's.
  2642. if getattr(self.gateway_runner, "session_authority", None) is not None:
  2643. from gateway.platforms.api_server_bot_chat import admit_peer_turn
  2644. return await admit_peer_turn(self.gateway_runner, session_id, message, author)
  2645. db = await self._ensure_session_db_async()
  2646. if db is None:
  2647. return None
  2648. home = Path(db.db_path).parent
  2649. from tools.bot_live_delivery import deliver_to_live_owner, find_canonical_live_owner
  2650. def _admit() -> Optional[dict[str, Any]]:
  2651. try:
  2652. owner = find_canonical_live_owner(home)
  2653. except ValueError:
  2654. # No reachable profile authority to hand the chat to: this process runs the turn.
  2655. return None
  2656. # Only the canonical Bot Chat's own lineage: a peer turn into any other session runs here.
  2657. if owner is None or db.get_compression_tip(session_id) != owner["session_id"]:
  2658. return None
  2659. return deliver_to_live_owner(home, owner, message, author=author)
  2660. record = await asyncio.to_thread(_admit)
  2661. return None if record is None else (home, record)
  2662. async def _answer_through_live_bot_chat(self, ctx: dict[str, Any]) -> Optional[web.Response]:
  2663. """Hand a turn aimed at a canonical Bot Chat that a Desktop holds live to that owner.
  2664. This is the ``hermes peer dm`` transport. Running the turn here would make this process a
  2665. second writer beside the lease holder: the open chat never shows the message or the reply,
  2666. its live context never learns of them, and the two transcripts interleave in state.db.
  2667. Local and relayed DMs already hand such a message to the owner's mailbox
  2668. (``tools/bot_mode_dm.py``, ``tui_gateway/methods_bot_relay.py``). This waits for the owner's
  2669. receipt on the same budget as the local path, so the peer still gets the reply on this call.
  2670. """
  2671. admitted = await self._admit_to_live_bot_chat(ctx["session_id"], ctx["user_message"], ctx["run_kwargs"].get("turn_author"))
  2672. if admitted is None:
  2673. return None
  2674. session_id = admitted[1].get("session_id") or ctx["session_id"] # a moved-aside API row: the local chat (MSG-21)
  2675. record = await self._await_live_bot_chat_receipt(*admitted)
  2676. delivery_id = record["delivery_id"]
  2677. headers = self._session_headers(session_id, ctx["gateway_session_key"])
  2678. if record["status"] == "settled":
  2679. return web.json_response(
  2680. {"object": "hermes.session.chat.completion", "session_id": session_id,
  2681. "message": {"role": "assistant", "content": record.get("reply") or ""},
  2682. "usage": {}, "runtime": {}, "delivery_id": delivery_id}, headers=headers)
  2683. if record["status"] in ("queued", "claimed"):
  2684. return web.json_response(
  2685. {"object": "hermes.session.chat.queued", "session_id": session_id,
  2686. "status": record["status"], "delivery_id": delivery_id}, status=202, headers=headers)
  2687. return _error_response(record.get("error") or f"Bot Chat delivery {record['status']}", 502,
  2688. code=record.get("reason") or record["status"], headers=headers)
  2689. async def _await_live_bot_chat_receipt(self, home: Path, record: dict[str, Any], *, keepalive=None) -> dict[str, Any]:
  2690. """Wait on the live Bot Chat's receipt (the authority admission's waiter, or the legacy owner
  2691. mailbox through ``await_delivery_async``) until it settles or the local DM budget runs out;
  2692. ``keepalive`` (async) is called every SSE keepalive interval so a streaming caller's proxy
  2693. keeps the socket."""
  2694. from gateway.platforms.api_server_bot_chat import await_live_delivery
  2695. from tools.bot_mode_dm import _LIVE_WAIT_SECONDS
  2696. deadline = time.monotonic() + _LIVE_WAIT_SECONDS
  2697. while record["status"] in ("queued", "claimed"):
  2698. remaining = deadline - time.monotonic()
  2699. if remaining <= 0:
  2700. break
  2701. budget = remaining if keepalive is None else min(remaining, CHAT_COMPLETIONS_SSE_KEEPALIVE_SECONDS)
  2702. record = await await_live_delivery(self, home, record, budget)
  2703. if keepalive is not None and record["status"] in ("queued", "claimed"):
  2704. await keepalive()
  2705. return record
  2706. async def _stream_through_live_bot_chat(self, request: web.Request, ctx: dict[str, Any]) -> Optional[web.StreamResponse]:
  2707. """``_answer_through_live_bot_chat`` for the SSE sibling route: the owner's settled receipt is
  2708. the run's single ``assistant.completed`` event; a receipt still open at the budget is a
  2709. ``run.queued`` event (the 202 shape), a failed one an ``error`` event carrying the reason."""
  2710. admitted = await self._admit_to_live_bot_chat(ctx["session_id"], ctx["user_message"], ctx["run_kwargs"].get("turn_author"))
  2711. if admitted is None:
  2712. return None
  2713. session_id = admitted[1].get("session_id") or ctx["session_id"] # a moved-aside API row: the local chat (MSG-21)
  2714. events = _SessionEventQueue(session_id, f"run_{uuid.uuid4().hex}")
  2715. response = await self._prepare_sse_response(request, session_id, ctx["gateway_session_key"])
  2716. async def _write(name: str, payload: dict[str, Any]) -> None:
  2717. name, payload = events.payload(name, payload)
  2718. await response.write(_sse_frame(payload, event=name, ensure_ascii=False))
  2719. async def _keepalive() -> None:
  2720. await response.write(b": keepalive\n\n")
  2721. try:
  2722. await _write("run.started", {"user_message": {"role": "user", "content": ctx["user_message"]}, "runtime": {}})
  2723. record = await self._await_live_bot_chat_receipt(*admitted, keepalive=_keepalive)
  2724. delivery_id = record["delivery_id"]
  2725. if record["status"] == "settled":
  2726. message_id = f"msg_{uuid.uuid4().hex}"
  2727. await _write("message.started", {"message": {"id": message_id, "role": "assistant"}})
  2728. await _write("assistant.completed", {
  2729. "message_id": message_id, "content": record.get("reply") or "", "delivery_id": delivery_id, "runtime": {}})
  2730. await _write("run.completed", {"message_id": message_id, "delivery_id": delivery_id, "usage": {}, "runtime": {}})
  2731. elif record["status"] in ("queued", "claimed"):
  2732. await _write("run.queued", {"status": record["status"], "delivery_id": delivery_id})
  2733. else:
  2734. await _write("error", {"message": record.get("error") or f"Bot Chat delivery {record['status']}",
  2735. "code": record.get("reason") or record["status"], "delivery_id": delivery_id})
  2736. await _write("done", {})
  2737. except (ConnectionResetError, ConnectionAbortedError, BrokenPipeError, OSError):
  2738. logger.info("Session SSE client disconnected while a live Bot Chat held the turn")
  2739. return response
  2740. @_admit_api_agent_request
  2741. async def _handle_session_chat(self, request: web.Request) -> web.Response:
  2742. """POST /api/sessions/{session_id}/chat — one synchronous agent turn (plus the delivery lanes'
  2743. one bounded re-run of a transient failure; ``hermes peer dm`` is the client)."""
  2744. from tools.bot_failure_reasons import RETRY_NONE, result_retry_action
  2745. # This turn runs through _run_agent, so it already COUNTS toward the cap (#7483).
  2746. # Spending the budget without checking it refused every other caller while never
  2747. # refusing this route — and a fleet's cross-machine DMs all arrive here.
  2748. limited = self._concurrency_limited_response()
  2749. if limited is not None:
  2750. return limited
  2751. ctx, err = await self._prepare_session_chat(request)
  2752. if err is not None:
  2753. return err
  2754. from gateway.platforms.api_server_openai_routes import _response_status
  2755. handed_off = await self._answer_through_live_bot_chat(ctx)
  2756. if handed_off is not None:
  2757. return handed_off
  2758. gateway_session_key = ctx["gateway_session_key"]
  2759. session_id = ctx["session_id"]
  2760. history = await self._conversation_history_for_session(session_id)
  2761. result, usage = await self._run_agent(conversation_history=history, **ctx["run_kwargs"])
  2762. # One policy-gated re-run of a transiently failed turn — the peer-DM transport's half of the
  2763. # retry the local (``tools.bot_mode_dm``) and relayed (``tui_gateway.methods_bot_relay``)
  2764. # delivery lanes already apply (#93091 item 5, #115325). Same policy, same gate: transient
  2765. # classes (429 / 5xx) re-run the SAME session once, a context overflow lets the re-run's
  2766. # pre-API compaction shrink the transcript first, and auth/quota/config/model never re-run. The
  2767. # store is read again first: the failed attempt's turn-start persist left the DM as the
  2768. # transcript's unanswered tail row, and the re-run resumes that row instead of appending a
  2769. # second copy of it. A turn that fails again reaches the peer client exactly as before.
  2770. if result_retry_action(result) != RETRY_NONE:
  2771. history = await self._conversation_history_for_session(session_id)
  2772. result, usage = await self._run_agent(
  2773. conversation_history=history, resume_unanswered_turn=True, **ctx["run_kwargs"])
  2774. is_dict = isinstance(result, dict)
  2775. effective_session_id = result.get("session_id") if is_dict else session_id
  2776. final_response = _resolve_media_to_data_urls(
  2777. result.get("final_response", "") if is_dict else "")
  2778. headers = self._session_headers(effective_session_id or session_id, gateway_session_key)
  2779. return web.json_response(
  2780. {"object": "hermes.session.chat.completion", "status": _response_status(result),
  2781. "session_id": effective_session_id or session_id,
  2782. "message": {"role": "assistant", "content": final_response}, "usage": usage,
  2783. "runtime": self._effective_turn_runtime(ctx["runtime_request"], result, usage)},
  2784. headers=headers)
  2785. @_admit_api_agent_request
  2786. async def _handle_session_chat_stream(self, request: web.Request) -> web.StreamResponse:
  2787. """POST /api/sessions/{session_id}/chat/stream — SSE wrapper over _run_agent."""
  2788. limited = self._concurrency_limited_response()
  2789. if limited is not None:
  2790. return limited
  2791. ctx, err = await self._prepare_session_chat(request)
  2792. if err is not None:
  2793. return err
  2794. handed_off = await self._stream_through_live_bot_chat(request, ctx)
  2795. if handed_off is not None:
  2796. return handed_off
  2797. gateway_session_key, session_id = ctx["gateway_session_key"], ctx["session_id"]
  2798. user_message, runtime_request = ctx["user_message"], ctx["runtime_request"]
  2799. runtime_meta = self._sanitize_runtime_metadata(
  2800. requested_runtime=runtime_request.get("requested"),
  2801. route_source=runtime_request.get("route_source") or "global",
  2802. model_lock=("accepted" if ctx["lock_active"] else ""))
  2803. message_id = f"msg_{uuid.uuid4().hex}"
  2804. run_id = f"run_{uuid.uuid4().hex}"
  2805. events = _SessionEventQueue(session_id, run_id)
  2806. queue, _event_payload = events.queue, events.payload
  2807. # Claim ownership inside the request's profile scope before any run-keyed state
  2808. # exists, so /v1/runs/{id}* control is confined to the starting profile.
  2809. # See #93689.
  2810. self._run_owners[run_id] = self._run_idempotency_scope(request)
  2811. self._set_run_status(
  2812. run_id, "queued", session_id=session_id, model=ctx["body"].get("model", self._model_name))
  2813. def _delta(delta: str) -> None:
  2814. if delta:
  2815. events.enqueue("assistant.delta", {"message_id": message_id, "delta": delta})
  2816. def _tool_progress(event_type: str, tool_name: str | None = None, preview: str | None = None, args=None, **kwargs) -> None:
  2817. if event_type == "reasoning.available":
  2818. events.enqueue("tool.progress", {"message_id": message_id, "tool_name": tool_name or "_thinking", "delta": preview or ""})
  2819. elif event_type in {"tool.started", "tool.completed", "tool.failed"}:
  2820. event_name = (
  2821. "tool.failed"
  2822. if event_type == "tool.completed" and kwargs.get("is_error")
  2823. else event_type
  2824. )
  2825. events.enqueue(event_name, {"message_id": message_id, "tool_name": tool_name, "preview": preview, "args": args})
  2826. def _commentary(text: str, *, already_streamed: bool = False) -> None:
  2827. # Mid-turn assistant commentary (Codex ``phase="commentary"``, text beside tool calls)
  2828. # as its own typed event — never folded into ``assistant.completed`` (#67580).
  2829. if isinstance(text, str) and text.strip():
  2830. events.enqueue("assistant.commentary", {
  2831. "message_id": message_id, "text": text, "already_streamed": bool(already_streamed)})
  2832. approval_notify = self._register_session_stream_approval(run_id, events, message_id)
  2833. async def _run_and_signal() -> None:
  2834. try:
  2835. await queue.put(_event_payload("run.started", {
  2836. "user_message": {"role": "user", "content": user_message},
  2837. "runtime": runtime_meta}))
  2838. self._set_run_status(run_id, "running", last_event="run.started")
  2839. await queue.put(_event_payload("message.started", {"message": {"id": message_id, "role": "assistant"}}))
  2840. history = await self._conversation_history_for_session(session_id)
  2841. result, usage = await self._run_agent(
  2842. conversation_history=history, stream_delta_callback=_delta,
  2843. tool_progress_callback=_tool_progress, interim_assistant_callback=_commentary,
  2844. active_run_id=run_id, approval_notify_callback=approval_notify,
  2845. approval_session_key=run_id, **ctx["run_kwargs"])
  2846. await events.flush()
  2847. is_dict = isinstance(result, dict)
  2848. final_response = _resolve_media_to_data_urls(result.get("final_response", "") if is_dict else "")
  2849. effective_session_id = result.get("session_id", session_id) if is_dict else session_id
  2850. turn_messages = self._turn_transcript_messages(history, user_message, result) if is_dict else []
  2851. effective_runtime = self._effective_turn_runtime(runtime_request, result, usage)
  2852. # Terminal status and flags come from the result (interrupted -> cancelled,
  2853. # unfinished -> failed); a late steer rides along as ``pending_steer`` for replay.
  2854. status, fields = _api_runs.terminal_run_status(result if is_dict else {})
  2855. await queue.put(_event_payload("assistant.completed", {
  2856. "session_id": effective_session_id, "message_id": message_id,
  2857. "content": final_response, **fields, "runtime": effective_runtime}))
  2858. await queue.put(_event_payload(f"run.{status}", {
  2859. "session_id": effective_session_id, "message_id": message_id, **fields,
  2860. "messages": turn_messages, "usage": usage, "runtime": effective_runtime}))
  2861. self._set_run_status(
  2862. run_id, status, session_id=effective_session_id,
  2863. # The reply text, so a caller whose stream died can still read it from
  2864. # GET /v1/runs/{run_id}; POST /v1/runs already records output in `_finish`.
  2865. output=final_response, usage=usage,
  2866. last_event=f"run.{status}", **fields)
  2867. except asyncio.CancelledError:
  2868. self._set_run_status(run_id, "cancelled", last_event="run.cancelled")
  2869. raise
  2870. except Exception as exc:
  2871. logger.exception("[api_server] session chat stream failed")
  2872. self._set_run_status(
  2873. run_id, "failed", error=_redact_api_error_text(exc), last_event="run.failed")
  2874. await queue.put(_event_payload("error", {"message": _redact_api_error_text(exc)}))
  2875. finally:
  2876. self._active_run_agents.pop(run_id, None)
  2877. self._run_approval_sessions.pop(run_id, None)
  2878. self._release_run_owner_if_forgotten(run_id)
  2879. await events.flush()
  2880. await queue.put(_event_payload("done", {}))
  2881. await queue.put(None)
  2882. # NOT in _active_run_tasks: _run_agent already counts this turn for the shutdown drain.
  2883. task = asyncio.create_task(_run_and_signal())
  2884. self._track_background_task(task)
  2885. response = await self._prepare_sse_response(request, session_id, gateway_session_key)
  2886. try:
  2887. while True:
  2888. try:
  2889. item = await asyncio.wait_for(queue.get(), timeout=CHAT_COMPLETIONS_SSE_KEEPALIVE_SECONDS)
  2890. except TimeoutError:
  2891. await response.write(b": keepalive\n\n")
  2892. continue
  2893. if item is None:
  2894. break
  2895. name, payload = item
  2896. await response.write(_sse_frame(payload, event=name, ensure_ascii=False))
  2897. except (ConnectionResetError, ConnectionAbortedError, BrokenPipeError, OSError):
  2898. await self._drain_session_stream_task_on_disconnect(
  2899. run_id, task, interrupt_message="SSE client disconnected", shield_wait=False)
  2900. logger.info("Session SSE client disconnected; interrupted live run %s", run_id)
  2901. except asyncio.CancelledError:
  2902. await self._drain_session_stream_task_on_disconnect(
  2903. run_id, task, interrupt_message="SSE task cancelled", shield_wait=True)
  2904. logger.info("Session SSE task cancelled; drained live run %s", run_id)
  2905. raise
  2906. except Exception as exc:
  2907. logger.debug("[api_server] session SSE stream error: %s", exc)
  2908. return response
  2909. def _register_session_stream_approval(self, run_id: str, events: _SessionEventQueue, message_id: str):
  2910. """Route a session-stream turn's dangerous-command approvals to its SSE queue and to
  2911. ``POST /v1/runs/{run_id}/approval`` (#58856). Keyed by the run id (never the shared
  2912. session key) so concurrent turns on one session can't cross-resolve."""
  2913. self._run_approval_sessions[run_id] = run_id
  2914. def _approval_notify(approval_data: dict[str, Any]) -> None:
  2915. event = _approval_request_event(run_id, approval_data, message_id=message_id)
  2916. self._set_run_status(run_id, "waiting_for_approval", last_event="approval.request", approval=event)
  2917. events.enqueue("approval.request", event) # executor thread -> loop hop inside
  2918. return _approval_notify
  2919. async def _drain_session_stream_task_on_disconnect(
  2920. self, run_id: str, task: asyncio.Task, *, interrupt_message: str, shield_wait: bool
  2921. ) -> None:
  2922. """Preserve live run control refs until the executor-backed turn actually exits."""
  2923. agent = self._active_run_agents.get(run_id)
  2924. if agent is None:
  2925. if not task.done():
  2926. task.cancel()
  2927. with suppress(Exception):
  2928. await task
  2929. return
  2930. with suppress(Exception):
  2931. agent.interrupt(interrupt_message)
  2932. if not task.done():
  2933. with suppress(Exception):
  2934. await (asyncio.shield(task) if shield_wait else task)
  2935. @_require_auth
  2936. async def _handle_session_model_lock(self, request: web.Request) -> web.Response:
  2937. """POST /api/sessions/{session_id}/model — backend-ack a Browser model lock."""
  2938. session_id = request.match_info["session_id"]
  2939. _, err = await self._get_existing_session_or_404(session_id)
  2940. if err:
  2941. return err
  2942. body, err = await self._read_json_body(request)
  2943. if err:
  2944. return err
  2945. runtime_request = self._session_runtime_request_from_body(body)
  2946. runtime_request["require_model_lock"] = True
  2947. lock_error = self._runtime_lock_error(runtime_request)
  2948. if lock_error is not None:
  2949. return lock_error
  2950. if not await asyncio.to_thread(self._persist_session_runtime_lock, session_id, runtime_request):
  2951. return _error_response(
  2952. "Could not persist the requested session model lock", 500, code="model_lock_persistence_failed")
  2953. requested = runtime_request.get("requested") or {}
  2954. route = runtime_request.get("route") or {}
  2955. runtime = self._sanitize_runtime_metadata(
  2956. runtime={
  2957. "provider": route.get("provider") or requested.get("provider") or "",
  2958. "model": route.get("model") or requested.get("model") or "",
  2959. "route_source": runtime_request.get("route_source") or "raw_request"},
  2960. requested_runtime=requested,
  2961. route_source=runtime_request.get("route_source") or "raw_request",
  2962. model_lock="accepted")
  2963. return web.json_response(
  2964. {"object": "hermes.session.model_lock", "session_id": session_id, "runtime": runtime})
  2965. # -- Cron jobs API ----------------------------------------------------------------
  2966. _JOB_ID_RE = re.compile(r"[a-f0-9]{12}")
  2967. # Update whitelist — prevents clients injecting arbitrary keys.
  2968. _UPDATE_ALLOWED_FIELDS = {"name", "schedule", "prompt", "deliver", "skills", "skill", "repeat", "enabled"}
  2969. _MAX_NAME_LENGTH = 200
  2970. _MAX_PROMPT_LENGTH = 5000
  2971. def _cron_request_guard(
  2972. self, request: web.Request, *, need_job_id: bool = False, check_draining: bool = False,
  2973. ) -> tuple:
  2974. """Shared /api/jobs prelude: auth → (drain) → cron available → (job_id). Returns (job_id, err)."""
  2975. auth_err = self._check_auth(request)
  2976. if auth_err:
  2977. return None, auth_err
  2978. if check_draining:
  2979. draining = self._draining_response()
  2980. if draining is not None:
  2981. return None, draining
  2982. if not _CRON_AVAILABLE:
  2983. return None, web.json_response({"error": "Cron module not available"}, status=501)
  2984. if not need_job_id:
  2985. return None, None
  2986. job_id = request.match_info["job_id"]
  2987. if not self._JOB_ID_RE.fullmatch(job_id):
  2988. logger.warning(
  2989. "Cron jobs API rejected invalid job_id %r: %s", job_id, self._request_audit_log_suffix(request))
  2990. return job_id, web.json_response({"error": "Invalid job ID format"}, status=400)
  2991. return job_id, None
  2992. @staticmethod
  2993. def _cron_error_response(exc: BaseException) -> web.Response:
  2994. return web.json_response({"error": _redact_api_error_text(exc)}, status=500)
  2995. def _validate_cron_prompt(self, prompt: str) -> Optional[web.Response]:
  2996. """Length cap + injection scan shared by create/update/run."""
  2997. if len(prompt) > self._MAX_PROMPT_LENGTH:
  2998. return web.json_response({"error": f"Prompt must be ≤ {self._MAX_PROMPT_LENGTH} characters"}, status=400)
  2999. if prompt and _scan_cron_prompt is not None:
  3000. scan_error = _scan_cron_prompt(prompt)
  3001. if scan_error:
  3002. return web.json_response({"error": scan_error}, status=400)
  3003. return None
  3004. def _job_response(self, fn, job_id: str, *, notify: bool) -> web.Response:
  3005. """Run ``fn(job_id)``: 404 when falsy, else ``{"job": ...}``; exceptions -> 500."""
  3006. try:
  3007. job = fn(job_id)
  3008. if not job:
  3009. return web.json_response({"error": "Job not found"}, status=404)
  3010. if notify:
  3011. _notify_cron_provider_jobs_changed()
  3012. return web.json_response({"job": job})
  3013. except Exception as e:
  3014. return self._cron_error_response(e)
  3015. async def _job_lookup_or_mutate(self, request: web.Request, fn, *, notify: bool) -> web.Response:
  3016. job_id, err = self._cron_request_guard(request, need_job_id=True)
  3017. return err if err else self._job_response(fn, job_id, notify=notify)
  3018. async def _handle_list_jobs(self, request: web.Request) -> web.Response:
  3019. """GET /api/jobs — list all cron jobs."""
  3020. _, err = self._cron_request_guard(request)
  3021. if err:
  3022. return err
  3023. try:
  3024. include_disabled = request.query.get("include_disabled", "").lower() in {"true", "1"}
  3025. return web.json_response({"jobs": _cron_list(include_disabled=include_disabled)})
  3026. except Exception as e:
  3027. return self._cron_error_response(e)
  3028. async def _handle_create_job(self, request: web.Request) -> web.Response:
  3029. """POST /api/jobs — create a new cron job."""
  3030. _, err = self._cron_request_guard(request)
  3031. if err:
  3032. return err
  3033. try:
  3034. body = await request.json()
  3035. name = (body.get("name") or "").strip()
  3036. schedule = (body.get("schedule") or "").strip()
  3037. prompt = body.get("prompt", "")
  3038. skills = body.get("skills")
  3039. repeat = body.get("repeat")
  3040. if not name:
  3041. return web.json_response({"error": "Name is required"}, status=400)
  3042. if len(name) > self._MAX_NAME_LENGTH:
  3043. return web.json_response({"error": f"Name must be ≤ {self._MAX_NAME_LENGTH} characters"}, status=400)
  3044. if not schedule:
  3045. return web.json_response({"error": "Schedule is required"}, status=400)
  3046. prompt_err = self._validate_cron_prompt(prompt)
  3047. if prompt_err:
  3048. return prompt_err
  3049. if repeat is not None and (not isinstance(repeat, int) or repeat < 1):
  3050. return web.json_response({"error": "Repeat must be a positive integer"}, status=400)
  3051. kwargs = {
  3052. "prompt": prompt, "schedule": schedule, "name": name,
  3053. "deliver": body.get("deliver", "local"),
  3054. "origin": self._cron_origin_from_request(request)}
  3055. for key in ("paused", "paused_reason"):
  3056. if key in body:
  3057. kwargs[key] = body[key]
  3058. if skills:
  3059. kwargs["skills"] = skills
  3060. if repeat is not None:
  3061. kwargs["repeat"] = repeat
  3062. return web.json_response({"job": _cron_create(**kwargs)})
  3063. except _CronSchedulerRegistrationError as e:
  3064. return web.json_response(e.to_dict(), status=424)
  3065. except ValueError as e:
  3066. return web.json_response({"error": str(e)}, status=400)
  3067. except Exception as e:
  3068. return self._cron_error_response(e)
  3069. async def _handle_get_job(self, request: web.Request) -> web.Response:
  3070. """GET /api/jobs/{job_id} — get a single cron job."""
  3071. return await self._job_lookup_or_mutate(request, _cron_get, notify=False)
  3072. async def _handle_update_job(self, request: web.Request) -> web.Response:
  3073. """PATCH /api/jobs/{job_id} — update a cron job."""
  3074. job_id, err = self._cron_request_guard(request, need_job_id=True)
  3075. if err:
  3076. return err
  3077. try:
  3078. body = await request.json()
  3079. # Whitelist allowed fields to prevent arbitrary key injection
  3080. sanitized = {k: v for k, v in body.items() if k in self._UPDATE_ALLOWED_FIELDS}
  3081. if not sanitized:
  3082. return web.json_response({"error": "No valid fields to update"}, status=400)
  3083. if "name" in sanitized and len(sanitized["name"]) > self._MAX_NAME_LENGTH:
  3084. return web.json_response({"error": f"Name must be ≤ {self._MAX_NAME_LENGTH} characters"}, status=400)
  3085. if "prompt" in sanitized:
  3086. prompt_err = self._validate_cron_prompt(sanitized["prompt"])
  3087. if prompt_err:
  3088. return prompt_err
  3089. except Exception as e:
  3090. return self._cron_error_response(e)
  3091. return self._job_response(lambda jid: _cron_update(jid, sanitized), job_id, notify=True)
  3092. async def _handle_delete_job(self, request: web.Request) -> web.Response:
  3093. """DELETE /api/jobs/{job_id} — delete a cron job."""
  3094. job_id, err = self._cron_request_guard(request, need_job_id=True)
  3095. if err:
  3096. return err
  3097. try:
  3098. if not _cron_remove(job_id):
  3099. return web.json_response({"error": "Job not found"}, status=404)
  3100. _notify_cron_provider_jobs_changed()
  3101. return web.json_response({"ok": True})
  3102. except Exception as e:
  3103. return self._cron_error_response(e)
  3104. async def _handle_pause_job(self, request: web.Request) -> web.Response:
  3105. """POST /api/jobs/{job_id}/pause — pause a cron job."""
  3106. return await self._job_lookup_or_mutate(request, _cron_pause, notify=True)
  3107. async def _handle_resume_job(self, request: web.Request) -> web.Response:
  3108. """POST /api/jobs/{job_id}/resume — resume a paused cron job."""
  3109. return await self._job_lookup_or_mutate(request, _cron_resume, notify=True)
  3110. async def _handle_run_job(self, request: web.Request) -> web.Response:
  3111. """POST /api/jobs/{job_id}/run — trigger immediate execution."""
  3112. job_id, err = self._cron_request_guard(request, need_job_id=True, check_draining=True)
  3113. if err:
  3114. return err
  3115. # Optional transient per-run context (standalone `hermes cron run` /
  3116. # cronjob(action='run', prompt=...)) — same cap + scan as a stored prompt.
  3117. extra_prompt = body = None
  3118. with suppress(Exception):
  3119. body = await request.json()
  3120. if isinstance(body, dict):
  3121. raw_prompt = body.get("prompt")
  3122. if raw_prompt is not None:
  3123. extra_prompt = str(raw_prompt)
  3124. prompt_err = self._validate_cron_prompt(extra_prompt)
  3125. if prompt_err:
  3126. return prompt_err
  3127. extra_prompt = extra_prompt or None
  3128. return self._job_response(
  3129. lambda jid: _cron_trigger(jid, extra_prompt=extra_prompt), job_id, notify=False)
  3130. async def _handle_cron_fire(self, request: web.Request) -> web.Response:
  3131. """POST /api/cron/fire — Chronos fire webhook (NAS -> agent), authenticated by a
  3132. NAS-minted JWT via the pluggable verifier, NOT API_SERVER_KEY. 202 + background run so
  3133. a long turn never trips NAS's timeout; the store CAS claim guards double-fire on retry."""
  3134. # Startup-wait budget starts here so a slow JWKS fetch cannot outlast the forwarder timeout.
  3135. received_at = asyncio.get_running_loop().time()
  3136. from hermes_cli.config import cfg_get, load_config
  3137. from plugins.cron_providers.chronos.verify import get_fire_verifier
  3138. auth = request.headers.get("Authorization", "")
  3139. token = auth[7:].strip() if auth.startswith("Bearer ") else ""
  3140. cfg = load_config()
  3141. verifier = get_fire_verifier()
  3142. verify_kwargs = dict(
  3143. token=token,
  3144. expected_audience=cfg_get(cfg, "cron", "chronos", "expected_audience", default=""),
  3145. jwks_or_key=cfg_get(cfg, "cron", "chronos", "nas_jwks_url", default="") or None,
  3146. issuer=cfg_get(cfg, "cron", "chronos", "portal_url", default="") or None)
  3147. try:
  3148. claims = await _call_verifier(verifier, **verify_kwargs)
  3149. except Exception:
  3150. # Fail closed: a crashing verifier must never admit a fire.
  3151. logger.exception("cron fire: verifier crashed; rejecting token")
  3152. claims = None
  3153. if claims is None:
  3154. logger.warning("cron fire: rejected invalid token: %s", self._request_audit_log_suffix(request))
  3155. return web.json_response({"error": "invalid fire token"}, status=401)
  3156. draining = self._draining_response()
  3157. if draining is not None:
  3158. return draining
  3159. with _reserve_pending_api_work(self) as reservation:
  3160. body = {}
  3161. with suppress(Exception):
  3162. body = await request.json()
  3163. job_id = (body or {}).get("job_id")
  3164. if not job_id:
  3165. return web.json_response({"error": "missing job_id"}, status=400)
  3166. # `hermes pause` ESTOP: refuse the fire and ask NAS to retry later.
  3167. # Placed after JWT verify (don't leak pause state to unauth callers)
  3168. # and after the drain check (drain is transient shutdown, ESTOP is
  3169. # operator override). 503 + Retry-After reschedules the job via NAS
  3170. # retry or the misfire backstop rather than silently dropping it —
  3171. # matches _CRON_FIRE_RETRY_AFTER_SECONDS in web_routers/cron.py.
  3172. with suppress(ImportError):
  3173. from agent.estop import check_paused as _estop_check_paused
  3174. if _estop_check_paused("cron-webhook", logger):
  3175. return web.json_response(
  3176. {"error": "hermes is paused (ESTOP)", "job_id": job_id},
  3177. status=503,
  3178. headers={"Retry-After": str(60)},
  3179. )
  3180. from cron.scheduler_provider import provider_supports_split_fire, resolve_cron_scheduler
  3181. provider = resolve_cron_scheduler()
  3182. loop = asyncio.get_running_loop()
  3183. from gateway.platforms.api_server_fire_startup import live_adapters_once_started
  3184. refusal, adapters = await live_adapters_once_started(self, request, job_id, received_at=received_at)
  3185. if refusal is not None:
  3186. return refusal
  3187. def _detach_fire(fire_fn, *fire_args) -> web.Response:
  3188. # The done callback owns the reservation once the task is detached.
  3189. task = asyncio.create_task(_api_runs.on_turn_executor(fire_fn, *fire_args, adapters=adapters, loop=loop))
  3190. reservation["detached"] = True
  3191. task.add_done_callback(lambda _task: _release_pending_api_work(self, reservation))
  3192. self._track_background_task(task, tolerate_missing=True)
  3193. return web.json_response({"status": "accepted", "job_id": job_id}, status=202)
  3194. if not provider_supports_split_fire(provider):
  3195. # A legacy single-phase provider overrides ``fire_due`` but inherits the base
  3196. # ``claim_fire``; the split path would silently bypass that override.
  3197. return _detach_fire(provider.fire_due, job_id)
  3198. # Persist the attempt + exact store owner before acknowledging NAS; a failure here
  3199. # is retryable and the reservation remains attached.
  3200. try:
  3201. claimed_job = await asyncio.to_thread(provider.claim_fire, job_id)
  3202. except Exception as exc:
  3203. logger.error("cron fire admission failed for %s: %s", job_id, exc)
  3204. return web.json_response({"error": "cron fire admission failed", "job_id": job_id}, status=503)
  3205. if claimed_job is None:
  3206. return web.json_response({"status": "duplicate", "job_id": job_id}, status=200)
  3207. return _detach_fire(provider.fire_claimed, claimed_job)
  3208. # -- Agent execution --------------------------------------------------------------
  3209. def _track_background_task(self, task, *, tolerate_missing: bool = False) -> None:
  3210. """Register a task in ``_background_tasks`` (tolerates test doubles) with auto-discard.
  3211. ``tolerate_missing`` (cron fire paths) also swallows AttributeError from the whole
  3212. registration; the run/sweep paths only tolerate an unhashable task."""
  3213. if tolerate_missing:
  3214. with suppress(TypeError, AttributeError):
  3215. self._background_tasks.add(task)
  3216. task.add_done_callback(self._background_tasks.discard)
  3217. return
  3218. with suppress(TypeError):
  3219. self._background_tasks.add(task)
  3220. if hasattr(task, "add_done_callback"):
  3221. task.add_done_callback(self._background_tasks.discard)
  3222. def _concurrency_limited_response(self) -> Optional[web.Response]:
  3223. """429 when the concurrent-run cap is reached (0 disables), else None. Uses the same
  3224. adapter-owned work count as shutdown draining (admitted requests included)."""
  3225. limit = self._max_concurrent_runs
  3226. if limit <= 0:
  3227. return None
  3228. inflight = self.active_agent_work_count()
  3229. # The current request's own reservation must not consume its last available slot.
  3230. reservation = _api_agent_request_reservation.get()
  3231. if reservation and reservation["active"]:
  3232. inflight -= 1
  3233. if inflight >= limit:
  3234. return _error_response(
  3235. f"Too many concurrent runs (max {limit})", 429, err_type="rate_limit_error",
  3236. code="rate_limit_exceeded", headers={"Retry-After": "1"})
  3237. return None
  3238. @staticmethod
  3239. def _bind_api_server_session(
  3240. *, chat_id: str = "", session_key: str = "", session_id: str = "", profile: str = "",
  3241. session_history_delivery: str = "") -> list:
  3242. """Bind an API turn with push disabled and history delivery default-denied.
  3243. Only routes whose continuation reads SessionDB may pass "1". An omitted
  3244. declaration or fingerprint-derived identity keeps delegation synchronous.
  3245. ``profile`` is the ``/p/<profile>/`` prefix serving the request (``""`` = default). It must
  3246. reach ``HERMES_SESSION_PROFILE``: the persistent-Docker container key is derived from it, so an
  3247. unbound profile collapses every profile's turns onto the default sandbox (#96370)."""
  3248. from gateway.session_context import set_session_vars
  3249. return set_session_vars(
  3250. platform="api_server", chat_id=chat_id, session_key=session_key, session_id=session_id,
  3251. profile=profile, async_delivery=False, cron_session="", session_history_delivery=session_history_delivery)
  3252. def _turn_runtime_metadata(
  3253. self, agent: Any, *, route: Optional[dict[str, Any]], requested_runtime: Optional[dict[str, Any]],
  3254. route_source: str, confirmed_runtime_lock: bool) -> dict[str, Any]:
  3255. """Sanitized actual-vs-requested runtime for a finished turn; raises RuntimeError when a
  3256. confirmed model lock's provider/model differs from what the agent actually ran with."""
  3257. runtime = dict(getattr(agent, "_hermes_api_runtime", {}) or {})
  3258. raw_provider = getattr(agent, "provider", "")
  3259. raw_model = getattr(agent, "model", "")
  3260. actual_provider = self._clean_runtime_id(raw_provider, max_len=80) if isinstance(raw_provider, str) else ""
  3261. actual_model = self._clean_runtime_id(raw_model) if isinstance(raw_model, str) else ""
  3262. resolved_provider = self._clean_runtime_id(runtime.get("provider"), max_len=80)
  3263. for key, actual in (("provider", actual_provider), ("model", actual_model)):
  3264. if actual:
  3265. runtime[key] = actual
  3266. else:
  3267. runtime.setdefault(key, "")
  3268. route = route or {}
  3269. requested_runtime = requested_runtime or {}
  3270. if confirmed_runtime_lock:
  3271. requested_provider = self._clean_runtime_id(
  3272. route.get("provider") or requested_runtime.get("provider"), max_len=80)
  3273. # _create_agent records the provider after resolving the request through the
  3274. # provider catalog. Compare that identity with the agent's actual runtime so
  3275. # aliases and named custom providers do not fail a literal-string check.
  3276. expected_provider = self._clean_runtime_id(
  3277. resolved_provider or requested_provider, max_len=80)
  3278. expected_model = self._clean_runtime_id(route.get("model") or requested_runtime.get("model"))
  3279. if (expected_provider and actual_provider != expected_provider) or (
  3280. expected_model and actual_model != expected_model):
  3281. raise RuntimeError(
  3282. "confirmed model lock runtime mismatch: "
  3283. f"expected provider={requested_provider or expected_provider or '<unspecified>'} "
  3284. f"model={expected_model or '<unspecified>'}; "
  3285. f"actual provider={actual_provider or '<unknown>'} "
  3286. f"model={actual_model or '<unknown>'}")
  3287. if requested_runtime:
  3288. model, provider = self._requested_ids(requested_runtime)
  3289. runtime["requested"] = {"provider": provider, "model": model}
  3290. runtime["route_source"] = route_source or runtime.get("route_source") or "global"
  3291. return self._sanitize_runtime_metadata(
  3292. runtime=runtime, requested_runtime=requested_runtime or None, route_source=route_source or "global",
  3293. model_lock=("confirmed" if confirmed_runtime_lock else ""))
  3294. def _finish_turn_result(
  3295. self, agent: Any, result: Any, session_id: Optional[str], *, route, requested_runtime, route_source,
  3296. confirmed_runtime_lock: bool) -> tuple:
  3297. """Attach usage, effective session id, ``_compressed`` and runtime metadata to a finished turn."""
  3298. usage = {"input_tokens": getattr(agent, "session_prompt_tokens", 0) or 0,
  3299. "output_tokens": getattr(agent, "session_completion_tokens", 0) or 0,
  3300. "total_tokens": getattr(agent, "session_total_tokens", 0) or 0}
  3301. # Effective session id lets callers track compression-triggered rotations.
  3302. # (#16938)
  3303. _eff_sid = getattr(agent, "session_id", session_id)
  3304. if isinstance(_eff_sid, str) and _eff_sid:
  3305. result["session_id"] = _eff_sid
  3306. # _compressed tells _build_response_conversation_history to store the compacted
  3307. # transcript as-is (rotation changes session_id; in-place compaction sets a flag).
  3308. _session_rotated = isinstance(_eff_sid, str) and isinstance(session_id, str) and _eff_sid != session_id
  3309. if getattr(agent, "_last_compaction_in_place", False) or _session_rotated:
  3310. result["_compressed"] = True
  3311. if requested_runtime or route or confirmed_runtime_lock or (route_source and route_source != "global"):
  3312. runtime = self._turn_runtime_metadata(
  3313. agent, route=route, requested_runtime=requested_runtime,
  3314. route_source=route_source, confirmed_runtime_lock=confirmed_runtime_lock)
  3315. if isinstance(result, dict):
  3316. result["runtime"] = runtime
  3317. usage["runtime"] = runtime
  3318. return result, usage
  3319. async def _run_agent(
  3320. self, user_message: str, conversation_history: list[dict[str, str]],
  3321. ephemeral_system_prompt: Optional[str] = None, session_id: Optional[str] = None,
  3322. stream_delta_callback=None, tool_progress_callback=None, tool_start_callback=None,
  3323. tool_complete_callback=None, interim_assistant_callback=None, reasoning_callback=None,
  3324. status_callback=None, agent_ref: Optional[list] = None, active_run_id: Optional[str] = None,
  3325. gateway_session_key: Optional[str] = None, requested_model: Optional[str] = None,
  3326. requested_provider: Optional[str] = None, model_options: Optional[dict[str, Any]] = None,
  3327. route: Optional[dict[str, Any]] = None, session_model: Optional[str] = None,
  3328. requested_runtime: Optional[dict[str, Any]] = None, route_source: str = "global",
  3329. confirmed_runtime_lock: bool = False, bind_declared_conversation: bool = False,
  3330. request_id: Optional[str] = None, history_from_session: bool = False, run_owner_scope=None,
  3331. session_history_delivery: str = "", turn_author: Optional[dict[str, Any]] = None,
  3332. relay_metadata: Optional[dict[str, Any]] = None, notification_category: str = "result",
  3333. resume_unanswered_turn: bool = False, approval_notify_callback=None,
  3334. approval_session_key: Optional[str] = None, walked_from: Optional[str] = None) -> tuple:
  3335. """Create an agent and run one turn in a thread executor -> ``(result, usage)``.
  3336. ``approval_notify_callback`` (with ``approval_session_key``) routes dangerous-command
  3337. approval requests to the caller's stream, keyed like ``/v1/runs`` approvals (#51871).
  3338. ``agent_ref[0]`` receives the agent so SSE writers can interrupt it; ``active_run_id``
  3339. registers it in ``_active_run_agents``. Under a confirmed model lock the actual
  3340. provider/model must match or the turn fails; ``runtime`` metadata is attached.
  3341. ``session_history_delivery`` declares #98619 session-id provenance and default-denies: only audited
  3342. producers whose client can address the id again pass "1" (see
  3343. ``_bind_api_server_session``).
  3344. ``turn_author`` only labels the turn for memory attribution. It grants nothing.
  3345. ``resume_unanswered_turn`` marks a policy-gated re-run of a turn whose user row the failed attempt
  3346. already persisted: the transcript's unanswered tail row is adopted from ``conversation_history``
  3347. as THIS turn's user message instead of being appended a second time
  3348. (``agent.session_persistence.adopt_unanswered_turn``; #115325)."""
  3349. if getattr(self.gateway_runner, "session_authority", None) is not None:
  3350. from gateway.session_api_turn import run_api_turn
  3351. return await run_api_turn(self, user_message=user_message, conversation_history=conversation_history,
  3352. ephemeral_system_prompt=ephemeral_system_prompt, session_id=session_id,
  3353. stream_delta_callback=stream_delta_callback, tool_progress_callback=tool_progress_callback,
  3354. tool_start_callback=tool_start_callback, tool_complete_callback=tool_complete_callback,
  3355. interim_assistant_callback=interim_assistant_callback, reasoning_callback=reasoning_callback,
  3356. status_callback=status_callback, walked_from=walked_from,
  3357. agent_ref=agent_ref, active_run_id=active_run_id, gateway_session_key=gateway_session_key,
  3358. requested_model=requested_model, requested_provider=requested_provider, model_options=model_options,
  3359. route=route, session_model=session_model, requested_runtime=requested_runtime,
  3360. route_source=route_source, confirmed_runtime_lock=confirmed_runtime_lock,
  3361. bind_declared_conversation=bind_declared_conversation, request_id=request_id, run_owner_scope=run_owner_scope,
  3362. history_from_session=history_from_session, session_history_delivery=session_history_delivery,
  3363. turn_author=turn_author, resume_unanswered_turn=resume_unanswered_turn, relay_metadata=relay_metadata,
  3364. approval_notify_callback=approval_notify_callback, approval_session_key=approval_session_key)
  3365. loop = asyncio.get_running_loop()
  3366. # ContextVars do not follow run_in_executor threads: capture here, re-enter in _run().
  3367. request_profile = _api_request_profile.get()
  3368. def _run():
  3369. from gateway.session_context import clear_session_vars
  3370. with self._profile_scope(request_profile):
  3371. tokens = self._bind_api_server_session(
  3372. chat_id=session_id or "", session_key=gateway_session_key or session_id or "",
  3373. session_id=session_id or "", profile=request_profile or "",
  3374. session_history_delivery=session_history_delivery)
  3375. agent = None
  3376. from agent.notification_presentation import notification_turn
  3377. from gateway.warning_notifications import diagnostic_turn_muted
  3378. muted = diagnostic_turn_muted({"notification_category": notification_category}, "api_server")
  3379. try:
  3380. agent = self._create_agent(
  3381. ephemeral_system_prompt=ephemeral_system_prompt, session_id=session_id,
  3382. stream_delta_callback=stream_delta_callback, tool_progress_callback=tool_progress_callback,
  3383. tool_start_callback=tool_start_callback, tool_complete_callback=tool_complete_callback,
  3384. interim_assistant_callback=interim_assistant_callback,
  3385. reasoning_callback=reasoning_callback, status_callback=status_callback,
  3386. gateway_session_key=gateway_session_key, requested_model=requested_model,
  3387. requested_provider=requested_provider, model_options=model_options, route=route,
  3388. session_model=session_model, confirmed_runtime_lock=confirmed_runtime_lock)
  3389. if agent_ref is not None:
  3390. agent_ref[0] = agent
  3391. if resume_unanswered_turn:
  3392. # A dispatcher's re-run of a failed delivery turn: the DM's own row is already
  3393. # in the store (the failed attempt persisted it at turn start), so continue THAT
  3394. # row instead of appending a second copy of the same text (#115325).
  3395. from agent.session_persistence import adopt_unanswered_turn
  3396. adopt_unanswered_turn(conversation_history, user_message, agent)
  3397. if active_run_id:
  3398. self._active_run_agents[active_run_id] = agent
  3399. effective_task_id = session_id or str(uuid.uuid4())
  3400. # Process baseline for disconnect reaping (this surface bypasses TurnRunner)
  3401. # + shutdown-interrupt registration, once for every caller.
  3402. # Baseline for selective background-process reaping on SSE client disconnect — mirrors
  3403. # gateway/run.py's gateway-turn cleanup (#76115); this API-server surface runs its own
  3404. # agent lifecycle and doesn't go through TurnRunner, so it needs its own baseline.
  3405. # /v1/runs runs its own agent lifecycle (no TurnRunner, no _run_agent) — record turn
  3406. # process ownership so stop/cancel can reap only the background processes this run
  3407. # created (#76115).
  3408. _publish_turn_process_ownership(agent, effective_task_id)
  3409. # Registering here, once, covers every _run_agent() caller — the same reason the
  3410. # _ProviderAuthResolutionError handler below lives here rather than in each route. Only
  3411. # two callers pass ``agent_ref``, and only /v1/runs has a run_id, so neither is a usable
  3412. # hook for the rest. See #63529.
  3413. self._shutdown_interruptible_agents[id(agent)] = agent
  3414. # Passed only when set: a human turn keeps today's call shape.
  3415. author_kwargs = {"turn_author": turn_author} if turn_author is not None else {}
  3416. conversation_kwargs = dict(
  3417. user_message=user_message,
  3418. conversation_history=conversation_history,
  3419. task_id=effective_task_id,
  3420. **author_kwargs,
  3421. )
  3422. if relay_metadata:
  3423. conversation_kwargs["relay_metadata"] = relay_metadata
  3424. approval_token = None
  3425. if approval_notify_callback is not None and approval_session_key:
  3426. # Same machinery as /v1/runs (_run_agent_sync): the contextvar scopes
  3427. # this turn's approvals to the key the resolve endpoint looks up.
  3428. from tools.approval import register_gateway_notify
  3429. from tools.approval_context import set_current_session_key
  3430. approval_token = set_current_session_key(approval_session_key)
  3431. register_gateway_notify(approval_session_key, approval_notify_callback)
  3432. try:
  3433. with notification_turn(agent, muted=muted, session_id=session_id or ""):
  3434. result = agent.run_conversation(**conversation_kwargs)
  3435. finally:
  3436. if approval_token is not None:
  3437. from tools.approval_context import reset_current_session_key
  3438. _api_runs._unregister_approval_notify(approval_session_key)
  3439. with suppress(Exception):
  3440. reset_current_session_key(approval_token)
  3441. result, usage = self._finish_turn_result(
  3442. agent, result, session_id, route=route, requested_runtime=requested_runtime,
  3443. route_source=route_source, confirmed_runtime_lock=confirmed_runtime_lock)
  3444. if muted and isinstance(result, dict):
  3445. # Project presentation only after finishing the source outcome. Keep
  3446. # the agent's result, transcript, failure flags and usage intact.
  3447. result = {**result, "_notification_presentation_suppressed": True}
  3448. return result, usage
  3449. except _ProviderAuthResolutionError as exc:
  3450. # Typed provider-auth failure only, handled once for every caller in
  3451. # run.py's response shape (text, no HTTP error).
  3452. logger.warning("Provider resolution failed for session=%s: %s",
  3453. session_id or "", exc)
  3454. return (
  3455. {"final_response": exc.user_text(), "messages": [],
  3456. "api_calls": 0, "tools": [],
  3457. **({"_notification_presentation_suppressed": True} if muted else {})},
  3458. {"input_tokens": 0, "output_tokens": 0, "total_tokens": 0})
  3459. except Exception as exc:
  3460. if muted:
  3461. # Keep the original exception/traceback for logs and failure
  3462. # handling; the HTTP/SSE boundary suppresses its presentation.
  3463. exc._notification_presentation_suppressed = True
  3464. raise
  3465. finally:
  3466. # Turn over (any outcome): clear ownership so a late disconnect can't reap
  3467. # background work this turn deliberately left running.
  3468. if active_run_id:
  3469. self._active_run_agents.pop(active_run_id, None)
  3470. if agent is not None:
  3471. _clear_turn_process_ownership(agent)
  3472. self._shutdown_interruptible_agents.pop(id(agent), None)
  3473. self._memory_sessions.checkin(agent)
  3474. # Bind the declared key to the row the turn actually ended on
  3475. # (agent.session_id carries a mid-turn rotation). Opt-in per route.
  3476. # Record the declared conversation on the row the turn actually ended on —
  3477. # ``agent.session_id`` already carries a mid-turn compression rotation (#16938), so
  3478. # the next reply resolves the live transcript rather than its retired parent.
  3479. # Opt-in: only the routes that resolve their session id from the declared key
  3480. # (/v1/responses, /v1/runs) record one, so no other caller's rows change shape.
  3481. if bind_declared_conversation:
  3482. self._bind_declared_conversation(
  3483. getattr(agent, "session_id", None) or session_id, gateway_session_key)
  3484. clear_session_vars(tokens)
  3485. self._activate_admitted_request()
  3486. self._inflight_agent_runs += 1
  3487. started_at = time.perf_counter()
  3488. usage: Optional[dict[str, Any]] = None
  3489. try:
  3490. # Worker-scoped count rides along so the shutdown close gate still sees the thread
  3491. # after this handler task is cancelled (#116535); released in the worker's finally.
  3492. result, usage = await _api_runs._submit_api_worker(loop, _run)
  3493. return result, usage
  3494. finally:
  3495. self._inflight_agent_runs -= 1
  3496. if usage is not None:
  3497. self._record_api_metrics(usage, time.perf_counter() - started_at)
  3498. # -- /v1/runs, room grants, room dispatch: thin delegators (real methods: tests assert
  3499. # __dict__ membership and patch the module-level implementations) ---------------------
  3500. _RUN_STREAM_TTL = 300 # seconds before orphaned runs are swept
  3501. _RUN_STATUS_TTL = 3600 # seconds to retain terminal run status for polling
  3502. def _set_run_status(self, run_id: str, status: str, **fields: Any) -> dict[str, Any]:
  3503. return _api_runs._set_run_status(self, run_id, status, **fields)
  3504. def _make_run_event_callback(self, run_id: str, loop: asyncio.AbstractEventLoop):
  3505. return _api_runs._make_run_event_callback(self, run_id, loop, _api_server=sys.modules[__name__])
  3506. def _run_idempotency_scope(self, request: web.Request) -> str:
  3507. return _api_runs._run_idempotency_scope(self, request, _api_server=sys.modules[__name__])
  3508. @staticmethod
  3509. def _room_grant_token(request: web.Request) -> str:
  3510. return _room_grants._room_grant_token(request)
  3511. def _room_grant_secret(self) -> bytes:
  3512. return _room_grants._room_grant_secret(self)
  3513. def _room_grant_claims(self, request: web.Request, *, permission: str) -> dict[str, Any]:
  3514. return _room_grants._room_grant_claims(self, request, permission=permission)
  3515. def _check_run_auth(self, request: web.Request, *, permission: str) -> web.Response | None:
  3516. return _api_runs._check_run_auth(self, request, permission=permission, _api_server=sys.modules[__name__])
  3517. async def _ensure_hosted_member_session(self, dispatch: Any) -> str:
  3518. return await _room_dispatch._ensure_hosted_member_session(self, dispatch)
  3519. async def _normalize_room_dispatch(self, request: web.Request, body: Any) -> tuple[Any, web.Response | None]:
  3520. return await _room_dispatch._normalize_room_dispatch(self, request, body, _api_server=sys.modules[__name__])
  3521. _handle_room_member_invitation = _room_grant_delegate("_handle_room_member_invitation")
  3522. _handle_room_member_capabilities = _room_grant_delegate("_handle_room_member_capabilities")
  3523. _handle_room_member_grant_refresh = _room_grant_delegate("_handle_room_member_grant_refresh")
  3524. _handle_room_member_grant_revoke = _room_grant_delegate("_handle_room_member_grant_revoke")
  3525. def _durable_run_status(self, request: web.Request, run_id: str) -> dict[str, Any] | None:
  3526. return _api_runs._durable_run_status(self, request, run_id)
  3527. @_admit_api_agent_request
  3528. async def _handle_runs(self, request: web.Request) -> web.Response:
  3529. return await _api_runs._handle_runs(self, request, _api_server=sys.modules[__name__])
  3530. def _request_owns_run(self, request: web.Request, run_id: str) -> bool:
  3531. return _api_runs._request_owns_run(self, request, run_id)
  3532. def _release_run_owner_if_forgotten(self, run_id: str) -> None:
  3533. _api_runs._release_run_owner_if_forgotten(self, run_id)
  3534. _handle_get_run = _run_route_delegate("_handle_get_run")
  3535. _handle_run_events = _run_route_delegate("_handle_run_events")
  3536. _handle_run_approval = _run_route_delegate("_handle_run_approval")
  3537. _handle_run_clarify = _run_route_delegate("_handle_run_clarify")
  3538. _handle_steer_run = _run_route_delegate("_handle_steer_run")
  3539. _handle_resolve_unknown_run = _run_route_delegate("_handle_resolve_unknown_run")
  3540. _handle_stop_run = _run_route_delegate("_handle_stop_run")
  3541. async def _sweep_orphaned_runs(self) -> None:
  3542. return await _api_runs._sweep_orphaned_runs(self)
  3543. def _sweep_orphaned_runs_once(self, now: Optional[float] = None) -> None:
  3544. return _api_runs._sweep_orphaned_runs_once(self, now)
  3545. # -- BasePlatformAdapter interface ------------------------------------------------
  3546. def _api_key_passes_startup_guard(self) -> bool:
  3547. """Return True when API_SERVER_KEY is present and strong enough to start."""
  3548. if not self._api_key:
  3549. logger.error(
  3550. "[%s] Refusing to start: API_SERVER_KEY is required for the API server, "
  3551. "including loopback-only binds on %s.",
  3552. self.name, self._host)
  3553. return False
  3554. try:
  3555. from hermes_cli.auth import has_usable_secret
  3556. except Exception as exc:
  3557. # Fail CLOSED: "could not check" must not mean "start" on a terminal-capable endpoint.
  3558. logger.error(
  3559. "[%s] Refusing to start: API_SERVER_KEY strength could not be "
  3560. "verified (%s: %s), and this endpoint dispatches "
  3561. "terminal-capable agent work. Repair the installation before "
  3562. "starting the API server on %s.",
  3563. self.name, type(exc).__name__, exc, self._host)
  3564. return False
  3565. if not has_usable_secret(self._api_key, min_length=16):
  3566. logger.error(
  3567. "[%s] Refusing to start: API_SERVER_KEY is a "
  3568. "placeholder or too short (<16 chars). This endpoint "
  3569. "dispatches terminal-capable agent work — a guessable "
  3570. "key is remote code execution. Generate a strong secret "
  3571. "(e.g. `openssl rand -hex 32`) and set API_SERVER_KEY "
  3572. "before starting the API server on %s.",
  3573. self.name, self._host)
  3574. return False
  3575. return True
  3576. async def connect(self, *, is_reconnect: bool = False) -> bool:
  3577. """Start the aiohttp web server."""
  3578. if not AIOHTTP_AVAILABLE:
  3579. logger.warning("[%s] aiohttp not installed", self.name)
  3580. return False
  3581. with self._session_db_cache_lock:
  3582. self._session_db_cache_closed = False
  3583. if not self._api_key_passes_startup_guard():
  3584. # Config error, not transient: a bare ``return False`` would make the reconnect watcher
  3585. # re-instantiate the adapter (+ sqlite connection) until EMFILE.
  3586. self._set_fatal_error(
  3587. # A rejected API_SERVER_KEY is a configuration error, not a transient blip — the key will
  3588. # not become valid on its own. A bare ``return False`` makes the reconnect watcher in
  3589. # gateway.run treat it as retryable and loop forever at the backoff cap, re-instantiating
  3590. # the adapter (and its ResponseStore sqlite connection) every retry (#38803: ~501 leaked
  3591. # connections / 1002 fds over 2.5 days until EMFILE took the whole gateway down).
  3592. # Non-retryable drops it from the reconnect queue — same treatment as the port-conflict
  3593. # guard (api_server_port_in_use). The guard already logged the specific rejection reason
  3594. # just above.
  3595. "api_server_key_invalid",
  3596. "API_SERVER_KEY was rejected by the startup guard (missing, "
  3597. "placeholder/too short, or strength unverifiable — see the "
  3598. "error logged above). Generate a strong secret (e.g. "
  3599. "`openssl rand -hex 32`), set API_SERVER_KEY, then "
  3600. "`/platform resume api_server`.",
  3601. retryable=False)
  3602. return False
  3603. try:
  3604. from gateway.platforms.api_server_config_guard import config_unavailable_middleware
  3605. mws = [mw for mw in ( # the config guard outermost: entering a profile scope reads config
  3606. config_unavailable_middleware, self._make_profile_prefix_middleware(), cors_middleware,
  3607. body_limit_middleware, security_headers_middleware) if mw is not None]
  3608. self._app = web.Application(middlewares=mws, client_max_size=MAX_REQUEST_BYTES)
  3609. assert self._app is not None
  3610. # Native routes + multiplex /p/<profile>/ mirrors (the prefix middleware validates and
  3611. # scopes config/credentials when multiplexing is on).
  3612. for method, path, handler in self._http_route_table():
  3613. self._app.router.add_route(method, path, handler)
  3614. self._app.router.add_route(method, f"/p/{{profile}}{path}", handler)
  3615. # Registered LAST so every native mirror above wins: anything else under /p/<profile>/ is a
  3616. # secondary profile's inbound-port platform (Twilio, LINE, Teams, ...) served on this listener.
  3617. self._app.router.add_route("*", "/p/{profile}/{tail:.*}", self._handle_profile_ingress)
  3618. # After native routes: Relay bootstrap shims feature-detect on this key and must
  3619. # no-op rather than shadow the native session-control handlers.
  3620. self._app["api_server_adapter"] = self
  3621. if self.gateway_runner is not None:
  3622. self._app["gateway_runner"] = self.gateway_runner
  3623. self._track_background_task(asyncio.create_task(self._sweep_orphaned_runs()))
  3624. # Network-accessible + unsandboxed local terminal backend = host-user RCE surface;
  3625. # warn, don't refuse (the operator may have a firewall / strong key).
  3626. if is_network_accessible(self._host):
  3627. _backend = "local"
  3628. with suppress(Exception):
  3629. from hermes_cli.config import load_config as _load_cfg
  3630. _backend = ((_load_cfg() or {}).get("terminal") or {}).get("backend", "local")
  3631. if str(_backend).lower() == "local":
  3632. logger.warning(
  3633. "[%s] API server is network-accessible (%s) AND the "
  3634. "terminal backend is 'local' (unsandboxed). Agent work "
  3635. "dispatched through this endpoint runs as the host user "
  3636. "with full terminal/file access. Strongly consider a "
  3637. "sandboxed backend (terminal.backend: docker) and "
  3638. "firewalling this port to trusted networks only.",
  3639. self.name, self._host)
  3640. # Plugin-registered native handlers, wired before AppRunner.setup() freezes the router.
  3641. self._wire_plugin_handlers(self._app)
  3642. self._runner = web.AppRunner(self._app)
  3643. await self._runner.setup()
  3644. # Bind directly instead of probing 127.0.0.1 first — the old single-family pre-probe raced the
  3645. # real bind and reported a TIME_WAIT socket as "in use" (#10297), failing gateway restarts for
  3646. # up to ~60s. Platform-dependent SO_REUSEADDR and the macOS TIME_WAIT rebind live in
  3647. # start_tcp_site; the loop below covers a predecessor still holding the port for a moment.
  3648. try:
  3649. # aiohttp registers a site with its runner before binding, so a failed start leaves the
  3650. # site registered: rebuild the runner per attempt rather than reach into its internals.
  3651. for attempt in range(_BIND_ATTEMPTS):
  3652. try:
  3653. self._site = await start_tcp_site(self._runner, self._host, self._port, log_tag=self.name)
  3654. break
  3655. except OSError as exc:
  3656. if exc.errno != errno.EADDRINUSE or attempt == _BIND_ATTEMPTS - 1:
  3657. raise
  3658. await self._runner.cleanup()
  3659. self._runner = web.AppRunner(self._app)
  3660. await self._runner.setup()
  3661. await asyncio.sleep(0.2 * (attempt + 1))
  3662. except OSError as exc:
  3663. await self._runner.cleanup()
  3664. self._runner = None
  3665. self._site = None
  3666. if getattr(exc, "errno", None) == errno.EADDRINUSE:
  3667. # Config error: non-retryable, or the reconnect watcher leaks fds forever.
  3668. self._set_fatal_error(
  3669. # A port conflict is a configuration error, not a transient blip — another process
  3670. # holds the port for its lifetime. A bare ``return False`` makes the reconnect
  3671. # watcher in gateway.run treat it as retryable and loop forever at the backoff cap
  3672. # (observed: 1568+ retries over 5 days across multi-profile setups all defaulting
  3673. # to the same port, #52132), filling errors.log and leaking the adapter's ResponseStore
  3674. # fds each retry. Non-retryable drops it from the reconnect queue; the operator
  3675. # recovers with ``/platform resume api_server`` after changing the port.
  3676. "api_server_port_in_use",
  3677. f"Port {self._port} already in use. Set "
  3678. f"platforms.api_server.port in config.yaml to a "
  3679. f"different value, then `/platform resume api_server`.",
  3680. retryable=False)
  3681. logger.error(
  3682. "[%s] Could not bind %s:%d: %s. Set a different port in "
  3683. "config.yaml: platforms.api_server.port",
  3684. self.name, self._host, self._port, exc)
  3685. return False
  3686. from gateway.platforms.shared_ingress import listener_base_url
  3687. self._mark_connected(listener_base=listener_base_url(self._host, self._port))
  3688. # Publish a metrics-bearing snapshot at bind and keep it fresh: the
  3689. # heartbeat loop updates last_heartbeat/metrics_today (#52323).
  3690. self._publish_runtime_status()
  3691. self._track_background_task(asyncio.create_task(self._heartbeat_loop()))
  3692. logger.info(
  3693. "[%s] API server listening on http://%s:%d (model: %s)",
  3694. self.name, self._host, self._port, self._model_name)
  3695. return True
  3696. except Exception as e:
  3697. logger.error("[%s] Failed to start API server: %s", self.name, e)
  3698. return False
  3699. async def disconnect(self) -> None:
  3700. """Stop the aiohttp server and release every owned resource, including the ResponseStore
  3701. connection (the reconnect loop builds a fresh adapter per retry; leaked fds hit EMFILE).
  3702. Without this, every adapter instance leaks 2 file descriptors (the database file and its WAL
  3703. sidecar) — the reconnect loop in ``gateway.run`` constructs a fresh adapter on every retry, so 2
  3704. fds/retry × 300s backoff cap ≈ 12 fds/hour, which exhausts the default 2560 fd limit after ~12h of
  3705. failed reconnects and turns the whole gateway into a zombie (OSError: [Errno 24] Too many open
  3706. files, #37011).
  3707. """
  3708. self._mark_disconnected()
  3709. # getattr: disconnect() tolerates bare __new__ fixtures (pinned in test_api_server_run_idempotency).
  3710. routed = getattr(self, "_response_stores", {})
  3711. stores = [s for s in (getattr(self, "_response_store", None), *list(routed.values())) if s is not None]
  3712. routed.clear()
  3713. for store in stores:
  3714. try:
  3715. await asyncio.to_thread(store.close) # a persistence worker may hold its lock
  3716. except Exception:
  3717. logger.debug("Failed to close response store for %s", self.name, exc_info=True)
  3718. with suppress(Exception):
  3719. await asyncio.to_thread(self._memory_sessions.close_all)
  3720. try:
  3721. if self._site:
  3722. await self._site.stop()
  3723. self._site = None
  3724. if self._runner:
  3725. await self._runner.cleanup()
  3726. self._runner = None
  3727. finally:
  3728. _api_runs._close_run_state(self) # after site.stop(): no late request re-mints the executor
  3729. self._close_cached_session_dbs()
  3730. self._app = None
  3731. logger.info("[%s] API server stopped", self.name)
  3732. async def send(
  3733. self, chat_id: str, content: str, reply_to: Optional[str] = None,
  3734. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  3735. """Not used — the HTTP request/response cycle handles delivery directly."""
  3736. return SendResult(success=False, error="API server uses HTTP request/response, not send()")
  3737. async def send_clarify(self, chat_id: str, question: str, choices: Optional[list],
  3738. clarify_id: str, session_key: str,
  3739. metadata: Optional[dict[str, Any]] = None) -> SendResult:
  3740. from gateway.platforms.api_server_authority_runs import send_clarify
  3741. return await send_clarify(self, chat_id=chat_id, clarify_id=clarify_id)
  3742. async def get_chat_info(self, chat_id: str) -> dict[str, Any]:
  3743. """Return basic info about the API server."""
  3744. return {"name": "API Server", "type": "api", "host": self._host, "port": self._port}