pyproject.toml 46 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835
  1. [project]
  2. name = "hermes-agent"
  3. version = "0.0.0"
  4. description = "The self-improving AI agent — creates skills from experience, improves them during use, and runs anywhere"
  5. readme = "README.md"
  6. # 3.14 is the newest python we know we have wheels for.
  7. # we *only* support 3.14, BUT we need to allow old hermes installs on <3.14
  8. # to get thru their update step on old python.
  9. # Shortly after they do, we update to our latest python.
  10. # See tests/compat/README.md for the updater contract this keeps.
  11. requires-python = ">=3.11,<3.15"
  12. authors = [{ name = "Nous Research" }]
  13. license = "MIT"
  14. license-files = ["LICENSE"]
  15. dependencies = [
  16. # Core — every direct dep is exact-pinned to ==X.Y.Z (no ranges).
  17. # Rationale: ranges allow PyPI to ship a fresh version of a transitive
  18. # at any time without a code review on our side. Exact pins mean the
  19. # only way a new package version reaches a user is via an intentional
  20. # update on our end (bump the pin in this file, regenerate uv.lock).
  21. # This was tightened on 2026-05-12 in response to the Mini Shai-Hulud
  22. # worm hitting mistralai 2.4.6 on PyPI; if that release had been
  23. # captured by `mistralai>=2.3.0,<3` rather than an exact pin, every
  24. # install in the hours before the quarantine would have pulled it.
  25. #
  26. # After a pin change, run `hermes pm lock` so the transitive resolution
  27. # stays consistent. Do not introduce ranges
  28. # without a written justification.
  29. #
  30. # Scope rule: only packages used by EVERY hermes session belong here.
  31. # Anything that's provider-specific (`anthropic`, `firecrawl-py`,
  32. # `exa-py`, `fal-client`, `edge-tts`, `parallel-web`) belongs in an
  33. # extra and gets prepared through PM when the
  34. # user picks that backend. Smaller `dependencies` = smaller blast
  35. # radius for the next supply-chain attack.
  36. "openai==2.54.0; python_version >= '3.14'",
  37. "certifi==2026.10.19; python_version >= '3.14'",
  38. # TLS trust comes from the OS certificate store (agent/ssl_verify.py), so
  39. # a corporate/internal root installed on the machine just works. certifi
  40. # above stays a direct pin because httpx/requests/openai each depend on
  41. # it regardless; it is no longer OUR trust source.
  42. # ssl_verify uses truststore's private original SSLContext for explicit CA overrides.
  43. # Keep this exact until that path has a public-API replacement.
  44. "truststore==0.10.5; python_version >= '3.14'",
  45. "python-dotenv==1.2.4; python_version >= '3.14'",
  46. "fire==0.7.1; python_version >= '3.14'",
  47. "httpx[socks]==0.28.1; python_version >= '3.14'",
  48. "rich==14.3.4; python_version >= '3.14'",
  49. "tenacity==9.2.1; python_version >= '3.14'",
  50. "tomli-w==1.2.0; python_version >= '3.14'", # Preserve relative dependency paths in staged plugin metadata.
  51. # 0.18.17 requires ruamel.yaml.clib on 3.14, which has no Windows ARM64 wheel.
  52. "ruamel.yaml==0.18.16; python_version >= '3.14'",
  53. # 0.18.16 only pulls in its C parser below 3.14, so every 3.14 install parsed YAML
  54. # (plugin manifests, config) in pure Python: ~5 s of gateway startup on 1 vCPU.
  55. # Declared where clib ships a cp314 wheel; elsewhere hermes_yaml falls back to pure.
  56. "ruamel.yaml.clib==0.2.15; python_version >= '3.14' and platform_python_implementation == 'CPython' and (sys_platform == 'darwin' or (sys_platform == 'linux' and platform_machine in 'x86_64 aarch64 i686') or (sys_platform == 'win32' and platform_machine in 'AMD64 x86'))",
  57. "requests==2.34.2; python_version >= '3.14'", # CVE-2026-25645
  58. "jinja2==3.1.6; python_version >= '3.14'",
  59. # Document-to-Markdown extraction for read_file (PDF, legacy Office,
  60. # OpenDocument, RTF, EPUB) + typed NeedsOcrError for scanned pages.
  61. # Bundled in core by maintainer decision (read_file is a core tool and
  62. # PDF reads are a common first-session action; the previous lazy-only
  63. # arrangement dated to the package's uv exclude-newer quarantine, which
  64. # has long expired). PM's doc-extract extra repairs lean/broken installs
  65. # from this same dependency declaration.
  66. "firecrawl-anydoc==0.2.4; python_version >= '3.14'",
  67. # Bumped from 2.12.5 to 2.13.4 to pull in pydantic-core 2.46.4.
  68. # pydantic-core 2.41.5 (pulled by 2.12.5) segfaults when the OpenAI SDK's
  69. # Responses API resource is exercised from a non-main thread, which is the
  70. # codex_responses dispatch in agent/chat_completion_helpers.py:_call.
  71. "pydantic==2.14.1; python_version >= '3.14'",
  72. # Interactive CLI (prompt_toolkit is used directly by cli.py)
  73. "prompt_toolkit==3.0.53; python_version >= '3.14'",
  74. # Cron scheduler (built-in feature — scheduled cron/interval jobs use croniter).
  75. "croniter==6.2.4; python_version >= '3.14'",
  76. # Snowball stemming for tool_search's BM25 (tools/tool_search.py) —
  77. # official Snowball project package, pure Python, zero transitive deps.
  78. # Applied at index AND query time so morphological variants match
  79. # ("issues" finds create_issue).
  80. "snowballstemmer==3.1.1; python_version >= '3.14'",
  81. # Requirement and version checks must work in lean installs without
  82. # relying on another package to bring packaging in transitively.
  83. "packaging==26.3; python_version >= '3.14'",
  84. # Markdown -> HTML conversion for rich message delivery (Matrix
  85. # `formatted_body`, and the `send_message` tool's HTML path). Now on the
  86. # DEFAULT delivery path, not matrix-specific: without it both
  87. # gateway/platforms/matrix.py and tools/send_message_tool.py silently fall
  88. # back to plain text, so cron/agent deliveries render raw `##`/`**`/tables
  89. # in clients like Element (see #32486). Pure-Python py3-none-any wheel
  90. # (~108KB, no compiled extensions, no platform constraints), so unlike the
  91. # matrix extra's `mautrix`/`python-olm` it's safe to ship everywhere — keeps
  92. # it out of the lazy-install path that exists only for the heavy matrix deps.
  93. "Markdown==3.11.2; python_version >= '3.14'",
  94. # Skills Hub (GitHub App JWT auth — optional, only needed for bot identity)
  95. "PyJWT[crypto]==2.15.1; python_version >= '3.14'", # PYSEC-2026-175/177/178/179 + GHSA-ffc3-869f-jxw9, GHSA-42vr-xj54-vc7v (fixed in 2.14.0/2.15.0)
  96. # urllib3 2.8.0 fixes GHSA-8988-9cw3-xx77 (proxy TLS config ignored),
  97. # GHSA-gh4c-6fx4-qh6g (chunked-deflate infinite loop) and
  98. # GHSA-vxq7-64xx-v4gw (unbounded chunk buffering). 2.8.0 is the latest
  99. # release older than 3 days and still supports Python >= 3.10
  100. # (3.11 bridge intact).
  101. "urllib3>=2.8.0,<3; python_version >= '3.14'",
  102. # PyJWT[crypto] pulls cryptography in transitively. Pin it here as well, so
  103. # that the WeCom and Weixin crypto paths cannot fall below the patched
  104. # version. 50.0.0 is the floor: it fixes CVE-2026-69247, a Bleichenbacher
  105. # oracle in PKCS#7 EnvelopedData, and 49.0.0 fixed GHSA-m2h6-j472-rp4c,
  106. # where a wildcard DNS name escapes permittedSubtrees, and
  107. # GHSA-jwv3-5hgf-82ww, exponential path-building on duplicate self-signed
  108. # intermediates.
  109. #
  110. # A pin here is not sufficient on its own. alibabacloud-tea-openapi caps
  111. # cryptography<49, so [tool.uv] also holds an override. Read that comment
  112. # before you move this version.
  113. "cryptography==50.0.2; python_version >= '3.14'", # CVE-2026-69247, GHSA-m2h6-j472-rp4c, GHSA-jwv3-5hgf-82ww, CVE-2026-39892, CVE-2026-34073, GHSA-537c-gmf6-5ccf
  114. # Windows has no IANA tzdata shipped with the OS, so Python's ``zoneinfo``
  115. # (PEP 615) raises ``ZoneInfoNotFoundError`` for every non-UTC timezone
  116. # out of the box. ``tzdata`` ships the Olson database as a data package
  117. # Python resolves automatically. No-op on Linux/macOS (which have
  118. # /usr/share/zoneinfo). Credits: PR #13182 (@sprmn24).
  119. "tzdata==2025.3; sys_platform == 'win32' and python_version >= '3.14'",
  120. # Cross-platform process / PID management. `psutil` is the canonical
  121. # answer for "is this PID alive" and process-tree walking across Linux,
  122. # macOS and Windows. It replaces POSIX-only idioms like `os.kill(pid, 0)`
  123. # (which is a silent killer on Windows — see CONTRIBUTING.md) and
  124. # `os.killpg` (which doesn't exist on Windows).
  125. "psutil==7.2.2; sys_platform != 'android' and python_version >= '3.14'",
  126. # Android Python 3.13+ needs upstream #2891 for platform recognition and
  127. # disk_partitions(). The fix is not in a published psutil release yet.
  128. # Keep this commit until a release includes it, then remove the source pin.
  129. "psutil @ git+https://github.com/giampaolo/psutil.git@380bd2b59c67b0e1b04bbf3a90b11744f4f96644 ; sys_platform == 'android' and python_version >= '3.14'",
  130. # Browser CDP supervisor + browser_dialog import this directly. Keep core
  131. # so browser tool discovery doesn't fail on lean installs.
  132. "websockets==15.0.1; python_version >= '3.14'",
  133. # Engine of the default browser_exec tool (the `browser-use` CLI is a thin
  134. # wrapper over it). Pure Python, and its pins match Pillow/websockets above,
  135. # so it rides in the main venv and every install, Desktop bundle included,
  136. # ships it without a separate tool environment.
  137. "browser-harness==0.1.13; python_version >= '3.14'",
  138. # .gitignore-aware file matching for desktop build stamp.
  139. "pathspec==1.1.1; python_version >= '3.14'",
  140. "fastapi>=0.104.0,<1; python_version >= '3.14'",
  141. # CIDR-aware forwarded_allow_ips requires uvicorn >=0.31.0.
  142. # uvicorn's [standard] extra bundles uvloop, httptools, and watchfiles.
  143. # uvloop cannot build on Android/Termux (libuv's ./configure fails), so
  144. # we declare the working components inline and gate uvloop behind the
  145. # [uvloop] optional extra — desktop/server profiles pull it via [all].
  146. "uvicorn>=0.31.0,<1; python_version >= '3.14'",
  147. "httptools>=0.6.3,<0.9; python_version >= '3.14'",
  148. "watchfiles>=0.20,<2; python_version >= '3.14'",
  149. # Streaming multipart uploads for the dashboard file manager (NS-501).
  150. # FastAPI's UploadFile/Form depend on python-multipart; it is NOT pulled in
  151. # by fastapi itself, so the dashboard's multipart upload endpoint would 500
  152. # without an explicit dependency here (and in the `web` extra below).
  153. "python-multipart>=0.0.9,<1; python_version >= '3.14'",
  154. "ptyprocess>=0.7.0,<1; sys_platform != 'win32' and python_version >= '3.14'",
  155. # Python 3.14 requires pywinpty 3.x. Version 3.0.5 includes the native
  156. # binaries missing from 3.0.4 wheels on both Windows architectures.
  157. "pywinpty>=3.0.5,<4; sys_platform == 'win32' and python_version >= '3.14'",
  158. # Desktop SSH's Windows remote runtime (hermes_cli/windows_ssh_runtime.py)
  159. # imports win32security/win32file/etc. directly — declare pywin32 rather than
  160. # relying on the concurrent-log-handler → portalocker transitive chain.
  161. "pywin32>=306,<312; sys_platform == 'win32' and python_version >= '3.14'",
  162. # App Installer checks use Package from ApplicationModel. Foundation
  163. # supplies the URI and async result types projected when the checker runs.
  164. "winrt-windows-applicationmodel>=3.2.1,<4; sys_platform == 'win32' and python_version >= '3.14'",
  165. "winrt-windows-foundation>=3.2.1,<4; sys_platform == 'win32' and python_version >= '3.14'",
  166. # Store update queries and request results project collection interfaces.
  167. "winrt-windows-foundation-collections>=3.2.1,<4; sys_platform == 'win32' and python_version >= '3.14'",
  168. "winrt-windows-services-store>=3.2.1,<4; sys_platform == 'win32' and python_version >= '3.14'",
  169. # Image resize recovery for the vision tools. Pillow shrinks oversized images
  170. # (>5 MB or >8000px) at embed time; without it the byte AND pixel-dimension
  171. # shrink paths no-op, so an oversized image bakes into immutable history and
  172. # bricks the session on Anthropic's non-retryable 400. Pure-wheel, no system
  173. # libs required for the codecs we use, so it's safe to ship in the base
  174. # install rather than gating it behind an extra + a mid-session lazy install
  175. # (which deadlocked the CLI under prompt_toolkit — see #40490).
  176. "Pillow==13.0.0; python_version >= '3.14'",
  177. # HEIF/HEIC/AVIF decode for the vision tools. iPhone photos and screenshots
  178. # are HEIC (frequently mislabeled .jpg by upload pipelines); Pillow has no
  179. # built-in HEIF codec, so without this the vision resolver rejects them as
  180. # "not a recognized image". pillow-heif registers a Pillow opener so
  181. # _normalize_to_supported_image can re-encode HEIF/AVIF to PNG before embed.
  182. # Ships prebuilt wheels bundling libheif for the common platforms (no system
  183. # libs needed), so it's safe in the base install alongside Pillow.
  184. "pillow-heif>=1.4.0,<2; python_version >= '3.14'",
  185. # SVG rendering for the icon generator (scripts/generate_icons.py). Source
  186. # builds render icons with the runtime interpreter (`hermes desktop`,
  187. # `hermes update`), so a source install carries its renderer instead of
  188. # preparing a separate environment at launch. abi3 wheels for every
  189. # shipped platform, including Windows ARM64 and Android.
  190. "resvg-py==0.5.0; python_version >= '3.14'",
  191. # Windows log rotation. Stdlib ``RotatingFileHandler.doRollover()`` uses
  192. # ``os.rename()`` which fails with ``PermissionError [WinError 32]`` on
  193. # Windows whenever any other process holds an append-mode handle on
  194. # ``agent.log`` (always the case in Hermes — TUI, gateway, ``hy_memory``
  195. # server, MCP servers, and on-demand CLI commands all log from separate
  196. # processes), pinning ``agent.log`` at the 5 MiB threshold and spamming
  197. # stderr on every emit (see #44873). ``concurrent-log-handler`` wraps the
  198. # rename in a cross-process file lock (via ``portalocker``: pywin32 on
  199. # Windows) so only one process rotates at a time. ``hermes_logging.py``
  200. # aliases it ONLY on Windows — POSIX renames an open file fine, so stdlib
  201. # already works there and managed-mode perms depend on its exact lifecycle.
  202. # Hence the ``sys_platform == 'win32'`` marker: the dep (and its portalocker
  203. # / pywin32 tree) ships only where it's actually used.
  204. "concurrent-log-handler==0.9.30; sys_platform == 'win32' and python_version >= '3.14'",
  205. # First-party lifecycle and shared-metrics runtime. Relay 0.11 is the supported
  206. # native runtime and provider-codec baseline. Managed calls pass request and
  207. # response data through this native module in-process; shared metrics installs
  208. # no network exporter and consumes only its bounded projection. This marker
  209. # must stay false anywhere no compatible native wheel tag can match; otherwise
  210. # installing Python dependencies fails instead of falling back to the no-op
  211. # Relay host (#76469, Termux).
  212. # Termux Python reports plain linux/aarch64 but runs on Bionic
  213. # libc, which satisfies neither manylinux nor musllinux, hence the
  214. # `'android' not in platform_release` guard on the linux arms: Android GKI
  215. # kernels embed "-androidNN-" in the kernel release string. (Official PEP
  216. # 738 CPython reports sys_platform == 'android' and never matched.) Pre-GKI
  217. # devices can still slip through; they get the same resolution failure as
  218. # before, worked around by installing with `--no-deps` or an older release.
  219. "nemo-relay>=0.11,<0.12; ((sys_platform == 'darwin' and platform_machine == 'arm64') or (sys_platform == 'linux' and platform_machine == 'x86_64' and 'android' not in platform_release) or (sys_platform == 'linux' and platform_machine == 'aarch64' and 'android' not in platform_release) or (sys_platform == 'win32' and platform_machine == 'AMD64') or (sys_platform == 'win32' and platform_machine == 'ARM64')) and python_version >= '3.14'",]
  220. [project.optional-dependencies]
  221. # High-performance event loop — uvloop replaces the stdlib asyncio loop with
  222. # a libuv-backed implementation for ~2-4x throughput on uvicorn. Gated as an
  223. # optional extra because libuv's ./configure does not run on Android/Termux
  224. # (bionic libc, non-FHS layout). Desktop and server installs pull this via
  225. # [all]; the [termux] / [termux-all] profiles intentionally omit it.
  226. uvloop = [
  227. "uvloop>=0.15.1,<0.24; sys_platform != 'win32' and sys_platform != 'cygwin' and sys_platform != 'android' and platform_python_implementation != 'PyPy'",
  228. ]
  229. # Native Anthropic provider — only needed when provider=anthropic (not via
  230. # OpenRouter or other aggregators).
  231. anthropic = ["anthropic==0.125.0"] # CVE-2026-34450, CVE-2026-34452
  232. # Web search backends — each only loaded when the user picks it as their
  233. # search provider (configured via `hermes tools` or config.yaml).
  234. exa = ["exa-py==2.26.0"]
  235. firecrawl = ["firecrawl-py==4.53.2"]
  236. parallel-web = ["parallel-web==0.6.0"]
  237. ddgs = ["ddgs==9.16.0"]
  238. # Image generation backends
  239. fal = ["fal-client==0.14.1"]
  240. # Edge TTS — default TTS provider but still optional (users can pick
  241. # ElevenLabs / OpenAI / MiniMax instead).
  242. edge-tts = ["edge-tts==7.3.1"]
  243. # NeuTTS's upstream Python ceiling excludes the managed interpreter.
  244. # Keep dependency markers and PM gates together: bundles omit them, explicit
  245. # setup requests report unavailable rather than succeeding with an empty set.
  246. neutts = ["neutts[all]==1.4.1; python_version < '3.14'"]
  247. kittentts = [
  248. "kittentts @ https://github.com/KittenML/KittenTTS/releases/download/0.8.1/kittentts-0.8.1-py3-none-any.whl ; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'",
  249. # KittenTTS requires misaki[en]>=0.9.4, and PyPI's misaki 0.9.4 caps Python
  250. # below 3.13. The NousResearch fork is the same 0.9.4 code with the cap
  251. # raised to <3.15. Declaring it here makes KittenTTS's transitive
  252. # requirement resolve to the fork. Drop this line when upstream misaki
  253. # publishes a release that allows 3.14.
  254. "misaki[en] @ git+https://github.com/NousResearch/misaki.git@f03fd2be7346952a83d3d4845c217fc7667f322d ; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'",
  255. "soundfile==0.14.0; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'",
  256. ]
  257. # onnxruntime has no Intel macOS or Android wheel. Piper has no Windows ARM64 wheel.
  258. piper = [
  259. "piper-tts==1.8.0; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'",
  260. ]
  261. modal = ["modal==1.6.2"]
  262. daytona = ["daytona==0.225.0"]
  263. vercel = ["vercel==0.12.0"]
  264. google-meet = ["playwright==1.64.0; sys_platform != 'android'", "websockets==15.0.1; sys_platform != 'android'"]
  265. messaging = [
  266. "python-telegram-bot[webhooks]==22.8",
  267. "discord.py[voice]==2.7.1",
  268. "aiohttp==3.14.5",
  269. "brotlicffi==1.2.1.0",
  270. "slack-bolt==1.30.0",
  271. "slack-sdk==3.45.0",
  272. "qrcode==7.4.2",
  273. ] # aiohttp 3.14.5: prior CVEs + GHSA-9xw5-w5jj-pvcg/GHSA-2g87-pp6c-29x5/GHSA-5wr8-gcqf-gqf3 family
  274. cron = [] # croniter is now a core dependency; this extra kept for back-compat
  275. slack = ["slack-bolt==1.30.0", "slack-sdk==3.45.0", "aiohttp==3.14.5"]
  276. # Matrix gateway deps. `mautrix[encryption]` pulls `python-olm`, whose
  277. # vendored libolm (archived 2023) cannot build on Windows or modern macOS:
  278. # no wheels for those targets AND the sdist fails to compile on current
  279. # clang/MSVC (olm/list.hh const-iterator error) and on CMake >= 4. It is
  280. # linux-only — gate the whole extra so `uv sync --all-extras` (the bundle
  281. # build) doesn't try to build python-olm on the win/darwin lanes. The
  282. # matrix adapter degrades gracefully without mautrix (import stubs).
  283. matrix = [
  284. "mautrix[encryption]==0.21.1; sys_platform == 'linux'",
  285. "aiosqlite==0.22.1; sys_platform == 'linux'",
  286. "asyncpg==0.32.0; sys_platform == 'linux'",
  287. "aiohttp-socks==0.12.0; sys_platform == 'linux'",
  288. "aiohttp==3.14.5; sys_platform == 'linux'",
  289. ] # aiohttp 3.14.5: prior CVEs + GHSA-9xw5-w5jj-pvcg/GHSA-2g87-pp6c-29x5/GHSA-5wr8-gcqf-gqf3 family (mautrix/aiohttp-socks only cap aiohttp<4 / >=3.10, so pin the patched floor directly)
  290. # WeCom callback-mode adapter — parses untrusted XML POST bodies from
  291. # WeCom-controlled callback endpoints, so we use defusedxml (drop-in
  292. # replacement for stdlib xml.etree.ElementTree) to block billion-laughs
  293. # and XXE. aiohttp/httpx are already in [messaging]; defusedxml lands
  294. # here to keep the dependency local to wecom_callback's threat model.
  295. wecom = ["defusedxml==0.7.1"]
  296. # Opt-in OS-keychain storage for the local credential vault key (vault.key_storage: keychain).
  297. # Lazy-installed by `hermes vault key migrate --to keychain`, so NOT in [all].
  298. keychain = ["keyring==25.7.0"]
  299. tts-premium = ["elevenlabs==1.59.0"]
  300. voice = [
  301. # Local STT pulls in wheel-only transitive deps (ctranslate2, onnxruntime).
  302. # faster-whisper's closure is prebuilt-only and missing pieces on two
  303. # targets: ctranslate2 has no win_arm64 wheel/sdist (win32-arm64), and
  304. # onnxruntime has no darwin-x64 wheel/sdist (darwin-x64). Gate the local
  305. # STT path off both; sounddevice/numpy still ship.
  306. "faster-whisper==1.2.1; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or platform_system != 'Darwin') and sys_platform != 'android'",
  307. "sounddevice==0.5.6",
  308. "numpy==2.5.4",
  309. ]
  310. # Wake engines are optional. Bundles include the engines supported by their
  311. # target. PM installs the selected engine on first use for source installs.
  312. wake = [
  313. # pyopen-wakeword includes the TFLite library and shared feature models.
  314. # Its universal2 wheel contains an ARM64-only library, so Intel Macs cannot
  315. # load it. There is no native Windows ARM64 wheel either.
  316. "pyopen-wakeword==1.1.0; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin')",
  317. "sherpa-onnx==1.13.8",
  318. # uv reads sherpa-onnx metadata from its cp311-linux_armv7l wheel, which
  319. # omits this pin. Every wheel the bundles install requires it. Without the
  320. # pin a frozen sync installs sherpa-onnx alone, and desktop dependency
  321. # preparation fails on `uv pip check`.
  322. "sherpa-onnx-core==1.13.8",
  323. # text2token imports both tokenizers even for English phrases.
  324. "sentencepiece==0.2.2",
  325. "pypinyin==0.55.0",
  326. "pvporcupine==4.0.3",
  327. "sounddevice==0.5.6",
  328. "numpy==2.5.4",
  329. ]
  330. # Platform sub-extras / alias extras — declared so pm.extras.ANCHORS names
  331. # only real extras (contract: tests/pm/test_extras.py). Each is
  332. # lazy-installed at first use via pm.ensure_import(name) and therefore
  333. # deliberately NOT in [all] (see tests/test_project_metadata.py's
  334. # lazy_covered_extras list — keep that list in sync when adding here).
  335. telegram = ["python-telegram-bot[webhooks]==22.8"]
  336. discord = ["discord.py[voice]==2.7.1"]
  337. # stt-whisper + audio-io compose [voice] (faster-whisper / sounddevice / numpy).
  338. stt-whisper = [
  339. "faster-whisper==1.2.1; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or platform_system != 'Darwin') and sys_platform != 'android'",
  340. ]
  341. audio-io = ["sounddevice==0.5.6", "numpy==2.5.4"]
  342. # WeChat voice decode (tools/transcription_tools.py self-heal path).
  343. silk = ["pilk==0.2.4"]
  344. # Wake-engine sub-extras — lazy per-engine installs so a user who only wants
  345. # sherpa-onnx doesn't pull the whole [wake] bundle. Pins match [wake].
  346. wake-openwakeword = [
  347. "pyopen-wakeword==1.1.0; (platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin')",
  348. ]
  349. wake-sherpa = [
  350. "sherpa-onnx==1.13.8",
  351. # Required by the sherpa-onnx wheel. See [wake] for why it is explicit.
  352. "sherpa-onnx-core==1.13.8",
  353. "sentencepiece==0.2.2",
  354. "pypinyin==0.55.0",
  355. ]
  356. wake-porcupine = ["pvporcupine==4.0.3"]
  357. # Google Chat service account push (gateway/platforms/google_chat) — pubsub
  358. # subscriber for the Chat API's Cloud Pub/Sub delivery.
  359. # grpcio (pubsub's native transitive) has no win_arm64 wheel, so win32-arm64
  360. # would build its sdist and fail — gate the whole extra off there like
  361. # faster-whisper. The adapter's pubsub import is lazy, so this just makes the
  362. # google-chat platform unavailable on win32-arm64.
  363. google-chat = [
  364. "google-cloud-pubsub==2.43.0; platform_machine != 'ARM64' or sys_platform != 'win32'",
  365. ]
  366. # Document extraction (read_file anydoc converter self-heal) — core already
  367. # bundles firecrawl-anydoc==0.2.4; the extra exists so a lean/broken install
  368. # can re-sync exactly the pin from core.
  369. doc-extract = ["firecrawl-anydoc==0.2.4"]
  370. # Office/PDF authoring libraries for skills/productivity/{docx,xlsx,powerpoint,pdf}.
  371. # Baked into the Docker image (Dockerfile `--extra documents`), whose sealed
  372. # venv has no pip and whose root fs resets on restart; ~25 MB there. Not in
  373. # [all]: plain installs keep the skills' persistent side environment instead.
  374. documents = [
  375. "python-docx==1.2.0",
  376. "openpyxl==3.1.5",
  377. "python-pptx==1.0.2",
  378. "reportlab==5.1.0",
  379. "pypdf==6.21.4",
  380. ]
  381. # PDF text extraction and rasterization for skills/productivity/pdf. Only in
  382. # the skills' side environment (`hermes pm environment documents --extra
  383. # documents --extra documents-pdf`), never baked: ~17 MB of pdfminer/pdfium.
  384. documents-pdf = [
  385. "pdfplumber==0.11.10",
  386. "pypdfium2==5.14.0",
  387. ]
  388. trace-upload = ["huggingface-hub==1.33.0"]
  389. # Cloud memory providers are opt-in PM extras. They stay outside [all]
  390. # so a quarantined release cannot break fresh installs.
  391. # Image resize recovery for the vision tools. Pillow is now a CORE dependency
  392. # (see the main `dependencies` list above) since the byte/pixel shrink paths are on
  393. # the default vision-embed path and the mid-session lazy install deadlocked the
  394. # CLI under prompt_toolkit (#40490). This extra is kept as a no-op back-compat
  395. # alias so existing requests for the `vision` extra resolve.
  396. vision = []
  397. # Kept as a no-op back-compat alias — `ptyprocess` and `pywinpty` are now
  398. # in the main `dependencies` list (with the same platform markers), so
  399. # any existing requests for the `pty` extra resolve cleanly
  400. # without pulling in extra packages.
  401. pty = []
  402. # CVE-2026-48710 (BadHost): Starlette is pulled transitively by mcp's
  403. # sse-starlette / HTTP-SSE stack (and by fastapi in the `web` extra). Before
  404. # 1.0.1, a malformed Host header makes `request.url.path` desync from the path
  405. # the ASGI router actually dispatched, so middleware/endpoints that gate on
  406. # `request.url` can be bypassed. We pin a patched Starlette directly in every
  407. # extra that exposes a Starlette-backed server surface so pip/uv can't resolve
  408. # a vulnerable pre-1.0.1 transitive. Bump in lockstep with uv.lock.
  409. #
  410. # mcp 2.x implements MCP revision 2026-07-28 and moved its own HTTP stack
  411. # from `httpx` to `httpx2`. httpx2 arrives transitively, but tools/mcp_tool.py
  412. # and tools/mcp_oauth_manager.py import it by name to build the client objects
  413. # they hand to the SDK, so it is pinned here explicitly rather than left to
  414. # resolution. Hermes' own `httpx[socks]==0.28.1` in [dependencies] is
  415. # unaffected — the two distributions install side by side under different
  416. # module names.
  417. mcp = [
  418. "mcp==2.3.0",
  419. "httpx2==2.15.1",
  420. "starlette==1.9.0",
  421. ] # starlette: CVE-2026-48710
  422. # Backwards-compatible no-op alias. Relay is a core dependency on supported
  423. # wheel targets and intentionally unavailable on other platforms.
  424. nemo-relay = []
  425. sms = ["aiohttp==3.14.5"]
  426. teams = [
  427. "microsoft-teams-apps==2.1.1",
  428. "aiohttp==3.14.5",
  429. ] # aiohttp 3.14.5: prior CVEs + GHSA-9xw5-w5jj-pvcg/GHSA-2g87-pp6c-29x5/GHSA-5wr8-gcqf-gqf3 family
  430. # Computer use talks to PM's pinned cua-driver over MCP stdio. This extra
  431. # provides the MCP client, independently of the native driver package.
  432. computer-use = [
  433. "mcp==2.3.0",
  434. "httpx2==2.15.1",
  435. "starlette==1.9.0",
  436. ] # starlette: CVE-2026-48710
  437. acp = ["agent-client-protocol==0.9.0"]
  438. # mistral: Voxtral STT + TTS. Pinned to an exact verified-clean version.
  439. # The `mistralai` PyPI project was quarantined 2026-05-12 after the malicious
  440. # 2.4.6 release (Mini Shai-Hulud worm); 2.4.6 was removed from PyPI and the
  441. # project is serving clean releases again (2.4.7 2026-05-25, 2.4.8 2026-05-28).
  442. # 2.9.2+ drops the opentelemetry-semantic-conventions<0.61 cap that blocked
  443. # the [otlp] OpenTelemetry 1.45.x bump.
  444. # Like other opt-in TTS/STT backends, this is lazy-installed via
  445. # pm (stt.mistral / tts.mistral) at first use — deliberately
  446. # NOT re-added to [all] so a future quarantined release can't break fresh
  447. # installs (see [all] policy comment below).
  448. mistral = ["mistralai==2.10.1"]
  449. # OTLP gateway monitoring export (optional). Provides the OpenTelemetry SDK +
  450. # OTLP/HTTP exporter for monitoring.gateway_health_export. Lazy-installed via
  451. # PM on first use; never a core dependency and deliberately
  452. # NOT in [all].
  453. otlp = [
  454. "opentelemetry-sdk==1.45.1",
  455. "opentelemetry-exporter-otlp-proto-http==1.45.1",
  456. ]
  457. bedrock = ["boto3==1.43.115"]
  458. vertex = ["google-auth==2.62.0"]
  459. azure-identity = ["azure-identity==1.26.0"]
  460. termux = [
  461. # Baseline Android / Termux path for reliable fresh installs.
  462. "python-telegram-bot[webhooks]==22.8",
  463. "hermes-agent[cron]",
  464. "hermes-agent[mcp]",
  465. "hermes-agent[acp]",
  466. ]
  467. termux-all = [
  468. # Best-effort "install all" profile for Termux. Same policy as [all]:
  469. # only includes extras that are not prepared on demand by PM.
  470. # Backends like telegram/slack/dingtalk/feishu lazy-install at
  471. # first use, so they're no longer eager-installed here.
  472. "hermes-agent[termux]",
  473. "hermes-agent[google]",
  474. "hermes-agent[sms]",
  475. "hermes-agent[web]",
  476. "hermes-agent[pty]",
  477. ]
  478. dingtalk = [
  479. "dingtalk-stream==0.24.3",
  480. "alibabacloud-dingtalk==2.2.65",
  481. "qrcode==7.4.2",
  482. ]
  483. feishu = ["lark-oapi==1.7.5", "qrcode==7.4.2"]
  484. google = [
  485. # Required by the google-workspace skill (Gmail, Calendar, Drive, Contacts,
  486. # Sheets, Docs). Declared here so PM environments and independent
  487. # packagers can include them without mutating an application's runtime.
  488. "google-api-python-client==2.201.0",
  489. "google-auth==2.62.0",
  490. "google-auth-oauthlib==1.5.0",
  491. "google-auth-httplib2==0.4.4",
  492. # The Google SDKs permit older vulnerable transitives, so unlocked installs
  493. # must carry the same fixed floors as uv.lock and the runtime installers:
  494. # httplib2 0.32.0 (GHSA-j5g9-f88f-gfj3 decompression bomb DoS),
  495. # pyasn1 0.6.5, google-auth 2.55.1.
  496. "httplib2==0.32.0",
  497. "pyasn1==0.6.5",
  498. ]
  499. youtube = [
  500. # Required by skills/media/youtube-content and
  501. # optional-skills/productivity/memento-flashcards (youtube_quiz.py).
  502. # Without this declaration dependency sync omits the package and both skills fail
  503. # at first invocation with ModuleNotFoundError (issue #22243).
  504. "youtube-transcript-api==1.2.4",
  505. ]
  506. # `hermes dashboard` (localhost SPA + API). Not in core to keep the default install lean.
  507. # starlette==1.3.1 pinned for CVE-2026-48710 (BadHost) — fastapi pulls Starlette
  508. # transitively and pre-1.0.1 is the vulnerable range. See the mcp extra above.
  509. # uvicorn pin without [standard] — httptools / watchfiles are now core deps,
  510. # and uvloop is gated behind the [uvloop] extra. This keeps [web] safe for
  511. # termux-all which includes it.
  512. web = [
  513. "fastapi==0.133.1",
  514. "uvicorn==0.54.0",
  515. "starlette==1.9.0",
  516. "python-multipart==0.0.32",
  517. ]
  518. all = [
  519. # Policy (2026-05-12): `[all]` includes only extras that genuinely
  520. # CAN'T be prepared on demand by PM — i.e. things every
  521. # session can use, things needed before the agent loop is alive
  522. # (terminal/CLI), and skill deps that dev environments need.
  523. # Anything an opt-in backend (provider, search, TTS, image, memory,
  524. # messaging platform, terminal sandbox) needs MUST live exclusively in
  525. # opt-in extras and resolve at first use — otherwise one quarantined PyPI
  526. # release breaks every fresh install.
  527. #
  528. # Removed from [all] on 2026-05-12 (covered by lazy-install):
  529. # anthropic, exa, firecrawl, parallel-web, fal, edge-tts,
  530. # modal, daytona, vercel, messaging (telegram/discord/slack),
  531. # matrix, slack, honcho, voice (faster-whisper),
  532. # dingtalk, feishu, bedrock, tts-premium (elevenlabs)
  533. #
  534. # Why: the matrix extra in particular pulls `mautrix[encryption]`
  535. # which depends on `python-olm`. python-olm has Linux-only wheels and
  536. # no native build path on Windows or modern macOS. With matrix in
  537. # [all], `uv sync --locked` on Windows tried to build it from sdist
  538. # and failed on `make`. Lazy-install routes that build to first use,
  539. # where the user is expected to have a toolchain available.
  540. "hermes-agent[cron]",
  541. "hermes-agent[pty]",
  542. "hermes-agent[mcp]",
  543. "hermes-agent[uvloop]",
  544. "hermes-agent[sms]",
  545. "hermes-agent[acp]",
  546. "hermes-agent[google]",
  547. "hermes-agent[web]",
  548. "hermes-agent[youtube]",
  549. ]
  550. [dependency-groups]
  551. # Build and test tooling never ships in runtime payloads.
  552. dev = [
  553. "debugpy==1.8.22",
  554. "pytest==9.1.1",
  555. "pytest-asyncio==1.4.0",
  556. "mcp==2.3.0",
  557. "httpx2==2.15.1",
  558. "starlette==1.9.0",
  559. "ty==0.0.89",
  560. "ruff==0.15.22",
  561. "setuptools==84.1.0",
  562. ] # starlette: CVE-2026-48710; setuptools: 84.1.0 (GHSA-xmj3-9gf7-h52w; torch >=2.13 requires setuptools 83+)
  563. # Native launcher and provider-catalog E2E dependencies belong in the test
  564. # environment, not the core runtime. Keep the Anthropic SDK at the same
  565. # reviewed version as the optional runtime extra above.
  566. test = [
  567. "distlib==0.4.4; sys_platform == 'win32'",
  568. "anthropic==0.125.0",
  569. ]
  570. [build-system]
  571. # setuptools.build_meta + our setup.py bdist_wheel guard import wheel during
  572. # PEP 517 isolated builds. Without wheel in
  573. # requires, the isolation sandbox only gets setuptools and the build
  574. # fails with ModuleNotFoundError: wheel.cli (#96488).
  575. requires = ["setuptools==84.1.0", "wheel"]
  576. build-backend = "setuptools.build_meta"
  577. [project.scripts]
  578. hermes = "hermes_cli.main:main"
  579. hermes-agent = "agent.legacy_cli:main"
  580. hermes-acp = "acp_adapter.entry:main"
  581. [tool.hermes]
  582. # Extras that only an explicit selection installs (setup, sync_venv). Bundles
  583. # build with --all-extras and pass --no-extra for each of these, so their
  584. # closures never ship. KittenTTS pulls torch, transformers and spaCy through
  585. # misaki[en]: installed when the user picks it, not preinstalled.
  586. opt-in-extras = ["kittentts"]
  587. # Per-extra platform gates (settled 2026-09-02): an extra listed here is
  588. # only installable on platforms matching the marker. pm consults this
  589. # table (pm.extras.extra_supported) — ensure_import/sync_venv refuse a
  590. # gated-off extra with a clear message instead of resolving it to an
  591. # empty set. The per-package markers inside the extra stay (uv's
  592. # resolver needs them for --all-extras); this table is the readable
  593. # single-authority for WHICH extra is supported WHERE.
  594. [tool.hermes.extras-platforms]
  595. # mautrix[encryption] → python-olm: linux-only wheels, no win/darwin build.
  596. matrix = "sys_platform == 'linux'"
  597. # grpcio (via google-cloud-pubsub) has no win_arm64 wheel.
  598. google-chat = "platform_machine != 'ARM64' or sys_platform != 'win32'"
  599. # Match the engine dependency markers so PM refuses an unsupported install.
  600. wake-openwakeword = "(platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin')"
  601. # faster-whisper's closure is prebuilt-only: ctranslate2 has no win_arm64 wheel and onnxruntime
  602. # none for darwin-x64. Its ANCHOR is faster_whisper, so an unsupported machine could install the
  603. # extra, rebuild the whole dependency environment and still fail the anchor on every retry.
  604. # Gate the extra that carries only faster-whisper; [voice] also has ungated deps (sounddevice,
  605. # numpy) and stays installable, see test_declared_extra_gates_match_dependency_selection.
  606. stt-whisper = "(platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or platform_system != 'Darwin') and sys_platform != 'android'"
  607. # NeuTTS excludes Python 3.14.
  608. neutts = "python_version < '3.14'"
  609. # KittenTTS: onnxruntime has no Intel macOS or Android wheel; misaki[en]'s torch has no
  610. # Windows ARM64 wheel.
  611. kittentts = "(platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'"
  612. piper = "(platform_machine != 'ARM64' or sys_platform != 'win32') and (platform_machine != 'x86_64' or sys_platform != 'darwin') and sys_platform != 'android'"
  613. # no playwright on android
  614. google-meet = "sys_platform != 'android'"
  615. [tool.uv]
  616. # uv otherwise enables the dev group by default, including in payload builds.
  617. default-groups = []
  618. # 3.11 is an install bridge for pre-PM updaters, never a runtime, so the lock
  619. # covers 3.14 only. Without this the lock must resolve every supported version,
  620. # where extras that only ever coexist on 3.14 (kittentts vs neutts) conflict.
  621. environments = ["python_version >= '3.14'"]
  622. override-dependencies = [
  623. # discord.py's latest published version, 2.7.1, pins pynacl at <1.6. however, pynacl 1.5.0 has known vulnerabilities.
  624. # discord.py has updated pynacl to 1.6 on `main`, but has not yet published a patch release.
  625. # so, we force-override this to pynacl 1.6. here.
  626. # remove this when we update discord.py
  627. "pynacl>=1.6,<1.7",
  628. # alibabacloud-tea-openapi caps cryptography<49, and its latest release
  629. # still does. Without this override, that cap holds cryptography at 48.0.1
  630. # and its three advisories (see the cryptography pin in
  631. # [project].dependencies). The package uses cryptography only to sign
  632. # requests with RSA and AES, and that API did not break in 49 or 50.
  633. # Keep this exact version equal to the direct dependency. uv overrides
  634. # replace that requirement too, not only the vendor's upper bound.
  635. # Remove this line when alibabacloud-tea-openapi lifts the cap.
  636. "cryptography==50.0.2",
  637. # browser-harness 0.1.13 (core dependency, latest release) pins
  638. # pillow==12.3.0 exactly, which holds Pillow below 13.0.0, the first
  639. # release fixing GHSA-8g5g-8vmr-9782, GHSA-w889-685w-c8fh and the rest of
  640. # the 13.0.0 advisory set. browser-harness only opens, converts, composes
  641. # and draws images (Image.open/new/convert, ImageDraw, ImageFont,
  642. # ImageOps.contain), none of which changed in 13. Keep this exact version
  643. # equal to the direct dependency (uv overrides replace that requirement
  644. # too). PM's install-time `uv pip check` accepts the resulting mismatch
  645. # because uv.lock records this override (pm/pip_check.py).
  646. # Remove this line when browser-harness allows Pillow 13. Plugin workspaces
  647. # inherit [tool.uv], so a plugin requiring pillow<13 also gets 13.0.0.
  648. "Pillow==13.0.0",
  649. # misaki[en] (pulled by [kittentts]) lists spacy-curated-transformers.
  650. # The newest release that fits spacy 3.8 (2.x needs thinc 9), 0.3.1, caps
  651. # Python below 3.14, so PM's `uv pip check` rejects the venv. Nothing
  652. # imports it: only transformer spaCy models (trf=True) do, and KittenTTS
  653. # never builds a misaki G2P. The never-true marker removes it from the lock.
  654. # Remove this line when misaki drops it or a 3.14-capable release fits.
  655. "spacy-curated-transformers; sys_platform == 'never'",
  656. ]
  657. # Release-age check: Hermes's dependencies must be at least 3 days old when Hermes
  658. # locks them. It runs where uv.lock is resolved (`hermes pm lock`, and CI's lock
  659. # check), never on users' machines: PM installs from this vetted lock and drops the
  660. # cutoff from what it generates (pm/workspace.py::_trust_core_lock), because many
  661. # package mirrors publish no upload times and uv rejects a file it cannot date
  662. # (#135589). Exact pins follow the same 3-day rule. The one exemption is CA
  663. # trust stores: a release that revokes or distrusts a compromised CA must reach
  664. # the lock the day it ships, because holding it back keeps the bad root trusted.
  665. # Only packages whose job is CA trust belong in exclude-newer-package.
  666. exclude-newer = "3 days"
  667. exclude-newer-package = { certifi = false }
  668. [tool.setuptools]
  669. # Root single-file modules are derived by setup.py at build time from the
  670. # source tree (see the ``_root_py_modules`` helper there). A static
  671. # ``py-modules`` list here drifted from the tree each time the layout changed,
  672. # and the drift broke installed wheels. Do not add the list back.
  673. [tool.setuptools.packages.find]
  674. include = [
  675. "agent",
  676. "agent.*",
  677. "tools",
  678. "tools.*",
  679. "hermes_cli",
  680. "hermes_cli.*",
  681. "gateway",
  682. "gateway.*",
  683. "tui_gateway",
  684. "tui_gateway.*",
  685. "cron",
  686. "cron.*",
  687. "acp_adapter",
  688. "plugins",
  689. "plugins.*",
  690. "providers",
  691. "providers.*",
  692. "hermes_platform",
  693. "hermes_platform.*",
  694. "pm",
  695. "pm.*",
  696. "tools",
  697. "tools.*",
  698. ]
  699. [tool.setuptools.package-data]
  700. hermes_cli = [
  701. "observability/schemas/*.json",
  702. "data/*.json",
  703. "local_runtime/*.json",
  704. "process_supervisor.sh",
  705. ]
  706. # gateway/assets/ ships status_phrases.yaml and the Telegram BotFather
  707. # screenshot. Without this, sealed venvs (uv2nix) silently lose both —
  708. # status phrases fall back to the tiny hardcoded set and the Telegram
  709. # topic-setup image disappears. Loaded via Path(__file__).parent / "assets"
  710. # in gateway/status_phrases.py and gateway/run.py.
  711. gateway = ["assets/**/*"]
  712. # Bundled plugin discovery reads these manifests at runtime. Keep them in
  713. # sealed wheels with the plugin Python modules; without this declaration the
  714. # wheel contains adapters but discovery finds zero bundled plugins.
  715. # The remote config backend checks its vendored config-plane conformance fixtures (secret-key
  716. # list) at runtime: plugins/config_backends/remote/values.py.
  717. plugins = ["**/plugin.yaml", "**/plugin.yml", "config_backends/remote/vendor/**/*"]
  718. # pm/lock.json is the runtime pin table (uv/python/tool versions + sha256s).
  719. # Without it a sealed wheel installs the pm package but has no pins to
  720. # realize — the pm store would be empty.
  721. pm = ["lock.json", "artifact-mirror.json", "pyproject.toml", "uv.lock"]
  722. # Bot Desktop starts Xvnc + Xfce through a shell launcher and seeds the wallpaper; both are read
  723. # via Path(__file__).parent in tools/bot_desktop/runtime.py and vanish from sealed wheels otherwise.
  724. tools = ["bot_desktop/launcher.sh", "bot_desktop/wallpaper.png"]
  725. [tool.pytest.ini_options]
  726. testpaths = ["tests"]
  727. markers = [
  728. "integration: marks tests requiring external services (API keys, Modal, etc.)",
  729. "live: secrets-gated canaries against REAL LLM provider APIs (spends money; select with -m live)",
  730. "real_concurrent_gate: opt out of the autouse stub that disables _detect_concurrent_hermes_instances",
  731. "real_agent_prewarm: opt out of the autouse stub that disables the tui_gateway deferred agent pre-warm timer",
  732. "real_retry_backoff: opt out of the tests/agent autouse stub that zeroes jittered_backoff",
  733. "requires_wal: needs the runtime to actually enable SQLite WAL mode (skipped where Hermes falls back to journal_mode=DELETE)",
  734. "no_isolate: opt out of per-file subprocess isolation (tests share mutable module-level state)",
  735. "ssh: marks tests requiring a reachable SSH server (skipped in normal CI)",
  736. "platforms(*specs, arch=None, arch_negate=False): run only on hosts matching at least one spec — linux/macos/windows/posix/any, 'not X' negation, optional arch filter",
  737. ]
  738. # integration tests take way too long to run in the normal CI environments
  739. addopts = "-m 'not integration and not live'"
  740. [tool.ty.environment]
  741. python-version = "3.13"
  742. [tool.ty.rules]
  743. unknown-argument = "warn"
  744. redundant-cast = "ignore"
  745. [tool.ruff]
  746. preview = true # required for PLW1514 (unspecified-encoding) — preview rule
  747. [tool.ruff.lint]
  748. # All other lints are intentionally disabled (see comment history on this
  749. # file) while we wrangle typechecks — but PLW1514 is too load-bearing to
  750. # keep off. Bare open()/read_text()/write_text() in text mode defaults to
  751. # the system locale encoding on Windows (cp1252 on US-locale installs),
  752. # which silently corrupts any non-ASCII file content. We had three
  753. # separate Windows sandbox regressions in one debug session before
  754. # adding the explicit encoding. This rule keeps new code honest.
  755. #
  756. # ASYNC210/220/221/251: blocking calls inside `async def` freeze the whole
  757. # gateway/uvicorn event loop — every adapter, timer, and health check stops
  758. # until the call returns. Real incidents: a 17-minute getaddrinfo hang took
  759. # the backend down (#91912); `time.sleep` in start_gateway froze restarts
  760. # for 10s (#36163). The fix pattern is `await asyncio.to_thread(...)` (or
  761. # `loop.run_in_executor`), `asyncio.create_subprocess_exec`, and
  762. # `await asyncio.sleep`. These four are the direct freeze vectors:
  763. # ASYNC210 — blocking HTTP call in async fn (urllib/requests/httpx-sync)
  764. # ASYNC220 — subprocess.Popen in async fn
  765. # ASYNC221 — subprocess.run / os.system in async fn
  766. # ASYNC251 — time.sleep in async fn
  767. # ASYNC230 (blocking open()) and ASYNC240 (blocking path methods) are real
  768. # but ~180 legacy sites deep; they graduate to this list once the backlog
  769. # is burned down (see per-file-ignores below for the frozen baseline).
  770. select = ["PLW1514", "ASYNC210", "ASYNC220", "ASYNC221", "ASYNC251", "TID251"]
  771. [tool.ruff.lint.flake8-tidy-imports.banned-api]
  772. "pm.uv".msg = "Use PM's semantic Python operations, not an installer executable."
  773. "pm.client.uv".msg = "Use PM's semantic Python operations."
  774. "pm.install.uv".msg = "The raw uv bridge was removed; use PM operations."
  775. "pm._uv".msg = "Tool acquisition is private to PM."
  776. "pm.environment".msg = "The environment engine is private; use PM operations."
  777. "pm.runtime_stage".msg = "PM stages its own worker runtime; consumers call pm operations."
  778. [tool.ruff.lint.per-file-ignores]
  779. "pm/**" = ["TID251"]
  780. # Desktop E2E fixtures stand in for PM's worker/runtime and reach into it like tests do.
  781. "apps/desktop/electron/fixtures/**" = ["TID251"]
  782. # Tests can intentionally exercise locale-encoding edge cases.
  783. "tests/**" = [
  784. "PLW1514",
  785. "ASYNC210",
  786. "ASYNC220",
  787. "ASYNC221",
  788. "ASYNC251",
  789. "TID251",
  790. ]
  791. # Skills and plugins are partially user-authored — their own conventions.
  792. "skills/**" = ["PLW1514"]
  793. "optional-skills/**" = ["PLW1514"]
  794. # Plugin platform adapters run ON the gateway event loop — the ASYNC gate
  795. # applies to them with full force; only PLW1514 stays relaxed.
  796. "plugins/**" = ["PLW1514"]
  797. # ---------------------------------------------------------------------------
  798. # ASYNC ratchet baseline — legacy blocking sites that predate the gate.
  799. # Each entry is an EXISTING violation being fixed in its own PR; do NOT add
  800. # new files here. Remove the entry when the file's sites are fixed.
  801. # ---------------------------------------------------------------------------
  802. # Detached restart watchers: Popen of a fully-detached, fire-and-forget
  803. # process (no wait), an accepted momentary spawn cost pending a dedicated
  804. # async-subprocess sweep.
  805. "gateway/run.py" = ["ASYNC220"]
  806. "gateway/run_shutdown.py" = ["ASYNC220"]
  807. "gateway/slash_commands.py" = ["ASYNC220"]
  808. # Off-loop sweep for these routers is in flight (PR #84376).
  809. "hermes_cli/web_routers/profiles.py" = ["ASYNC220", "ASYNC221"]
  810. # Legacy blocking spawn sites in platform adapters, pending their own fixes.
  811. "plugins/platforms/whatsapp/adapter.py" = ["ASYNC220", "ASYNC221"]
  812. "plugins/platforms/photon/adapter.py" = ["ASYNC220"]