sjdZddlZddlZddlZddlZddlZddlZddlZddlZddl m Z ddl m Z m Z ddlmZddlZejeZehdZdXde d ed efd ZdYd ed ed efdZde d dfdZde d dfdZde ddd dfdZde ddd dfdZejdkZehdZ dZ!dZ"dZ#de$d efdZ%ded ed dfd!Z&ded ed dfd"Z'd#e ee fd$e ee fd efd%Z(d&d'ddd(de ee fd)ed*ed+ed,ed-dd dfd.Z)d/dd0de ee fd1e d2e*de*dzd3e d df d4Z+d dd5de ee fd6ed7ej,dzd efd8Z-Gd9d:ej.Z/ddddd;de ee fd1e dedzd-dd dfd?Z0de ee fd@ede d dfdAZ1de ee fdBe2d dfdCZ3dZdDed e d e fdEZ4da5dFZ6dGe d e fdHZ7d[dIed e*d e*fdJZ8d\dIed e9d e9fdLZ:dXdIed ed efdMZ;dNZdRed efdSZ?dTed efdUZ@dRedVed efdWZAdS)^z*Shared utility functions for hermes-agent.N)Path)AnyUnion)urlparse>1onyestrueFvaluedefaultreturnc||St|tr|St|tr-|t vSt|S)zDCoerce bool-ish values using the project's shared truthy string set.) isinstanceboolstrstriplowerTRUTHY_STRINGS)r r s )/home/agent/.hermes/hermes-agent/utils.pyis_truthy_valuers` }% %7{{}}""$$66 ;;namecJttj||dS)zBReturn True when an environment variable is set to a truthy value.Fr rosgetenv)rr s renv_var_enabledr"s! 29T733U C C CCrpathz int | Nonec |r+tj|jndS#t$rYdSwxYw)zBCapture the permission bits of *path* if it exists, else ``None``.N)existsstatS_IMODEst_modeOSError)r s r_preserve_file_moder''sV48KKMMKt|DIIKK/000tK ttsAA AAztuple[int, int] | NonectjdkrdS |}n#t$rYdSwxYw|j|jfS)zACapture the owning uid/gid of *path* if the platform supports it.posixN)rrr#r&st_uidst_gid)r sts r_preserve_file_ownerr-/sY w't YY[[ tt 9bi s ) 77ownerc|ttdsdS tj||d|ddS#t$rYdSwxYw)aRe-apply uid/gid after an atomic replace when permitted. Docker and NAS-backed installs often run some commands as root while the persistent volume is owned by the runtime user. ``os.replace`` swaps in the temp file's owner, so a root-run config write can leave ``config.yaml`` owned by root. Best-effort chown preserves the existing owner for privileged callers and is harmless for unprivileged callers that cannot chown. Nchownr)hasattrrr0r&)r r.s r_restore_file_ownerr3:se }GB00}  uQxq*****      s"? A  A modec\|dS tj||dS#t$rYdSwxYw)aRe-apply *mode* to *path* after an atomic replace. ``tempfile.mkstemp`` creates files with 0o600 (owner-only). After ``os.replace`` swaps the temp file into place the target inherits those restrictive permissions, breaking Docker / NAS volume mounts that rely on broader permissions set by the user. Calling this right after ``os.replace`` restores the original permissions. N)rchmodr&)r r4s r_restore_file_moder7KsM |  t      s  ++nt> !g{Gz?g?excc@tot|ddtvS)uHReturn True for Windows rename failures a retry might clear. Only a *candidate* classification: ``ERROR_ACCESS_DENIED`` covers both a concurrent handle and a real ACL denial, and the two are not reliably distinguishable up front. Probing the target with ``os.access`` does not work — ``os.replace`` needs delete-child rights on the *parent directory*, so a directory-level denial reports the target as writable. Instead of guessing, both cases enter the same bounded retry and a genuine denial falls through to the caller with its original error. winerrorN) _IS_WINDOWSgetattr!_WINDOWS_CONTENDED_REPLACE_ERRORS)r=s r#_is_contended_windows_replace_errorrCs'  73 D99)rtmp_str real_pathct|d5}|}dddn #1swxYwYtjt tddz}tj||} tj|dtjd}|t|kr3|tj|||dz }|t|k3tj |t| tj |n#t$rYnwxYwtj |n#tj |wxYwtj |dS)uOverwrite *real_path* with the contents of *tmp_str*, in place. Last-resort path for a target whose handle is still held after the retry budget: writing through the existing file works where renaming onto it does not. Unlike ``shutil.copyfile`` this never truncates the target to zero first — a concurrent reader would otherwise be able to observe an empty ``auth.json`` / ``gateway_state.json`` mid-write (measured: a 4-thread poller sees a 0-byte read during a plain copyfile). A single ``os.write`` of the full payload followed by ``ftruncate`` keeps the visible content going straight from old to new. This is still not atomic — it is a strictly smaller window than a copy, not the absence of one — so it runs only after the rename has genuinely failed. Writing through the target also preserves its ACL, which ``os.replace`` does not (the temp file's inherited ACL wins there). rbNO_BINARYr)openreadrO_WRONLYrAlseekSEEK_SETlenwrite ftruncatefsyncr&closeunlink)rDrEsrcdataflagsfdwrittens r_rewrite_in_placerYs" gt  xxzz K'"j!44 4E E " "B  Q $$$D !! rxDN33 3GD !! RT###  HRLLLL    D    Igs=2666B D;DD; D# D;"D##D;;Ecftj|| tj||n#t$rYnwxYw t |d5}t j|dddn #1swxYwYn#t$rYnwxYwt j|dS)zCCopy/fsync/unlink fallback for cross-device and bind-mount renames.rGN) shutilcopyfilecopystatr&rIrrQfilenorS)rDrEfs r_copy_fallbackr`s OGY''' ++++       )T " " !a HQXXZZ  ! ! ! ! ! ! ! ! ! ! ! ! ! ! !      IgsA- ::B 'B5 B BB B B BBtmp_pathtargetc t|}tj|rtj|n|}t|} tj|||S#t $rx}t|}|jtj tj fvr|s|rddl m }tdtdzD]}tj||t"t$ tj|||ccYd}~S#t $rE} | jtj tj fvr | }d}Yd} ~ nt| s| }Yd} ~ d} ~ wwxYwt&d||t+|ddp+tj|jpd|j|rd nd |rt1||nt3||Yd}~nd}~wwxYw|S) uAtomically move *tmp_path* onto *target*, preserving symlinks. ``os.replace(tmp, target)`` atomically swaps ``tmp`` into place at ``target``. When ``target`` is a symlink, the symlink itself is replaced with a regular file — silently detaching managed deployments that symlink ``config.yaml`` / ``SOUL.md`` / ``auth.json`` etc. from ``~/.hermes/`` to a git-tracked profile package or dotfiles repo (GitHub #16743). This helper resolves the symlink first so ``os.replace`` writes to the real file in-place while the symlink survives. For non-symlink and non-existent paths the behavior is identical to a plain ``os.replace`` call unless the rename fails with: * ``EXDEV`` / ``EBUSY`` (any platform) — cross-device, bind-mount, and busy-file deployments fall back to copy/fsync/unlink immediately. These never clear on retry. * A Windows rename contended by another open handle (winerror 5/32/33). CPython opens files without ``FILE_SHARE_DELETE``, so *any* concurrent reader of the target blocks the rename. The rename is retried with jittered backoff first — a retry that wins keeps the write atomic — and only a target whose handle outlives the budget is rewritten in place, so the update lands instead of being silently dropped. A genuine Windows permission failure produces the same winerror as a contended one, so it is not classified up front: it exhausts the retry budget, fails the in-place rewrite too, and is re-raised unchanged. Returns the resolved real path used for the replace, so callers that need to re-apply permissions can target it instead of the symlink. r)jittered_backoffr1) base_delay max_delayNFz;atomic_replace: %s -> %s failed with %s; falling back to %sr?zin-place rewritecopy)rrr islinkrealpathreplacer&rCerrnoEXDEVEBUSYagent.retry_utilsrdrange_REPLACE_RETRY_ATTEMPTStimesleep_REPLACE_RETRY_BASE_DELAY_S_REPLACE_RETRY_MAX_DELAY_SloggerdebugrA errorcodegetrYr`) rarb target_strrErDr= contendedrdattempt retry_excs ratomic_replacer}s[@VJ02z0J0JZ  ,,,PZI(mmG./ 7I&&& +/+/+/7<< 9U[%+6 6 6y 6   $ ; : : : : : $;a$?@@ $ $ $$#>"< $Jw 222$$$$$$$$$$$$ 5; *DDD'$) >yII#CCCCCC$  I   CT * * >""39>39=="+ 7        / gy 1 1 1 1 7I . . .W+/X sV A77 G:A=G5DG5G: E-(#E( G5E(#G5(E--BG55G:utf-8z.tmp_)encoding tmp_prefix preserve_mode create_modecontentrrrrct|}|jdd|rt|nd}|rt |nd}|}|||s|}t jt|j|d\} } tj | d|5} |H'---DM3@J)$///dN"N+"9$++--"9$#   ZLB Yr3 2 2 2 &f)gb(.C.C) &--//>::: LL ! ! ! LLNNN HV]]__ % % % & & & & & & & & & & & & & & &#8T22  A Y @ @ @  %gb(.C.C % tI ? ? ? ? ? & % % %   Ih        D  sVG2BE  G EGEA&G G2 G G2 G-*G2,G--G2)indentr4rUr dump_kwargsc t|}|jdd|dnt|}t |}t jt|jd|jdd\}} |*ttdrtj ||tj |d d 5} tj|| f|d d || tj| dddn #1swxYwYt%||} t| } t'| ||) tj| |dS#t*$rYdSwxYwt-| |dS#t.$r( tj|n#t*$rYnwxYwwxYw)aWrite JSON data to a file atomically. Uses temp file + fsync + os.replace to ensure the target file is never left in a partially-written state. If the process crashes mid-write, the previous version of the file remains intact. Args: path: Target file path (will be created or overwritten). data: JSON-serializable data to write. indent: JSON indentation (default 2). mode: Optional final permission mode. When set, the temp file is created and replaced with this mode, avoiding chmod-after-write TOCTOU exposure for secret-bearing files. **dump_kwargs: Additional keyword args forwarded to json.dump(), such as default=str for non-native types. TrN._rrrrr~rF)r ensure_ascii)rrrr'r-rrrstemr2rrrjsondumprrQr^r}r3r6r&r7rrS) r rUrr4rrrrWrar_rE real_path_objs ratomic_json_writerZs\0 ::DKdT222 ,DD2Ed2K2KM)$//N#   49LB "  H 5 5  Ib$    Yr3 1 1 1 !Q I "         GGIII HQXXZZ  ! ! ! ! ! ! ! ! ! ! ! ! ! ! !#8T22 Y M>:::   -----     }m < < < < <   Ih        D  stAFAD$ F$D((F+D(,4F!E88 FFFF G &F;:G ; GG GG )labellogrrc\t|}|pt} |j}n#t$rYdSwxYwt jdkrdS|tjtjzzsdS| d|r|dnd|jtj ||dS)ajWarn (once per call) when a credential file is group/world-readable. Secret-bearing files that users create by hand (or that older Hermes versions wrote without an explicit mode) commonly end up 0o644 under the default umask. This helper is the shared read-time check for that class: call it before loading any token/credential file so the owner gets a remediation hint in the logs. Returns True when a warning was emitted. No-ops (returns False) on platforms without POSIX permission bits semantics (best effort), when the file is missing, or when permissions are already tight. Fr)zO%s%s is group/world-readable (mode 0%o) and contains secrets. Run: chmod 600 %s rT) rrur#r%r&rrS_IRGRPS_IROTHwarningr$)r rrp_log file_modes r(warn_if_credential_file_broadly_readablers$ T A =&DFFHH$ uu w'u  4 5uLL $5 "  Y  4s4 AAc$eZdZdZdfd ZxZS) IndentDumperuDPyYAML dumper that indents list items under mapping keys (2-space). Default PyYAML emits "indentless" sequences — list items start at the same column as their parent mapping key. ``ruamel.yaml`` (used by :func:`atomic_roundtrip_yaml_update`) emits 2-space-indented sequences. Mixing both styles in the same ``config.yaml`` produces a file that stricter parsers like ``js-yaml`` reject with ``bad indentation of a mapping entry``. Forcing ``indentless=False`` aligns the two serializers so all write paths emit byte-identical layouts (#31999). FcHt|dS)NF)superincrease_indent)selfflow indentless __class__s rrzIndentDumper.increase_indentsww&&tU333r)FF)__name__ __module__ __qualname____doc__r __classcell__)rs@rrrsG  4444444444rr)default_flow_style sort_keys extra_contentrrrrc t|}|jddt|}t |}|||s|}t jt|jd|j dd\}} tj |dd 5} |:::=-88888   Ih        D  sVF81B/E, F8,E00F83E04AF88 G*GG* G%"G*$G%%G*key_pathcNddlm}ddlm}t |}|jdd|d}d|_d|_d|_ | d d d | rO| d d 5}| |p |}dddn #1swxYwYn |}t||s ||}|}|d} | ddD]8} || } t| |s|} | || <| }9||| d<t#|} t%|} t'jt+|jd|jdd\}} t/j|dd 5}||||t/j|dddn #1swxYwYt;||}t |}t=|| t?|| dS#t@$r( t/j!|n#tD$rYnwxYwwxYw)a_Update one dotted YAML key while preserving comments and readable text. This is intentionally narrower than :func:`atomic_yaml_write`: it is for user-edited config files where comments, ordering, quoting, and Unicode should survive a single setting mutation. Writes still use the same temp file + fsync + atomic replace pattern. rYAML CommentedMapTrrttypFrr<mappingsequenceoffsetrr~rNrrrrr)# ruamel.yamlrruamel.yaml.commentsrrrrpreserve_quotesrrrr"rIloadrsplitrxr'r-rrrrrrrrrQr^r}r3r7rrSr&)r rr rryaml_rtr_configcurrentkeyskey next_valuerrrWrarErs ratomic_roundtrip_yaml_updater,s[!     111111 ::DKdT222dtnnnG"G G!&G NN1qN333 {{}} YYsWY - - 7\\!__6 F 7 7 7 7 7 7 7 7 7 7 7 7 7 7 7 fl + +&f%%G >>#  DCRCy[[%% *l33 &%J%GCLGDH'--M)$//N#   49LB  Yr3 1 1 1 !Q LL # # # GGIII HQXXZZ  ! ! ! ! ! ! ! ! ! ! ! ! ! ! !#8T22 Y M>:::=-88888   Ih        D  sh CC C 2I2 AH& I2&H**I2-H*.AI22 J$=JJ$ JJ$JJ$ new_statec ddlm}ddlm ddlmddlm}t|}|j dd|||d }d|_ d|_ d |_ |d d d |rb|dd5}||}dddn #1swxYwYt%| s  |pi}n  }hdfdd dt&ddf fd ||t)|}t+|}t-jt1|j d|jdd\} } t5j| dd5}||||t5j|dddn #1swxYwYtA| |} t| } tC| |tE| |dS#tF$r( t5j$| n#tJ$rYnwxYwwxYw)uPersist a full config-state dict while preserving comments and ordering. Behaves like ``atomic_yaml_write`` (writes the whole file in one shot from ``new_state``), but routes through ruamel.yaml round-trip mode so existing comments, key order, quotes, and readable Unicode survive. Reconciliation rules against the on-disk YAML: * Keys present in both are updated in-place via assignment, which keeps ruamel's CommentedMap anchors (and their attached comments) attached to their original positions. * Keys missing from ``new_state`` are deleted. * Keys added in ``new_state`` are appended at the end of their parent map. * Nested ``dict`` values recurse with the same rules. * Non-dict values (lists, scalars) are overwritten wholesale — list element comments are not individually preserved, matching ruamel's semantics. This is the comment-safe replacement for ``yaml.safe_dump(cfg, f)`` in callers that mutate a deep-loaded config dict and want to persist the whole thing. Shares the fail-closed contract ``hermes_cli.config.atomic_config_write`` enforces for plain (non-comment-preserving) full-document writes: an existing-but-unreadable ``config.yaml`` (permission error, broken mount, transient I/O) raises rather than being silently replaced with only ``new_state``. Imported lazily to avoid a module-level circular import — ``hermes_cli.config`` itself imports from this module. rrr)DoubleQuotedScalarString)$require_readable_config_before_writeTrrrFrr<rrr~rN> ny~noroffr nullr falsectt|tr!|vr |S|SN)rrr)r r_YAML11_AMBIGUOUS_WORDSs r_quote_if_yaml11_ambiguousz>atomic_roundtrip_yaml_save.._quote_if_yaml11_ambiguouss> eS ! ! 3ekkmm7N&N&N++E22 2 rdstrTr cRD]i\}}t|trA||}t|s}|||<||[|||<jfd|DD]}||=dS)Ncg|]}|v| Sr).0krTs r z>atomic_roundtrip_yaml_save.._merge..s:::!Qc\\A\\\r)itemsrdictrxr)rrTrr rr_mergers ` rrz*atomic_roundtrip_yaml_save.._merges))++ = =JC%&& =''#,,!'<88'*lnnG&CHw&&&&55e<<C;:::sxxzz:::  CC  rrrrrr)&rrrrruamel.yaml.scalarstringrhermes_cli.configrrrrrrrrr"rIrrrr'r-rrrrrrrrrQr^r}r3r7rrSr&)r rrrrr_existingrrrWrarErrrrrrs @@@@@ratomic_roundtrip_yaml_saverosB!     111111AAAAAAFFFFFF ::DKdT222((...dtnnnG"G G!&G NN1qN333 {{}}" YYsWY - - '||AH ' ' ' ' ' ' ' ' ' ' ' ' ' ' '(L11 4#|HN33H<>> Lt" F8Y'--M)$//N#   49LB  Yr3 1 1 1 !Q LL1 % % % GGIII HQXXZZ  ! ! ! ! ! ! ! ! ! ! ! ! ! ! !#8T22 Y M>:::=-88888   Ih        D  sh8CC!C I !AG>2 I >HI HAI I<I*)I<* I74I<6I77I<textct tj|S#tjttf$r|cYSwxYw)zParse JSON, returning *default* on any parse error. Replaces the ``try: json.loads(x) except (JSONDecodeError, TypeError)`` pattern duplicated across display.py, anthropic_adapter.py, auxiliary_client.py, and others. )rloadsJSONDecodeError TypeError ValueError)rr s rsafe_json_loadsrsEz$  )Z 8s 77cbt"ttddp tjatS)N CSafeLoader)_fast_yaml_loaderrAr SafeLoaderrrr_get_fast_yaml_loaderr s' #D->>Q$/ rstreamcFtj|tS)uy``yaml.safe_load`` using the libyaml C loader when available. Accepts the same inputs as ``yaml.safe_load`` (a ``str``/``bytes`` document or a readable file object) and returns the same parsed structure. Falls back to PyYAML's pure-Python ``SafeLoader`` when ``CSafeLoader`` isn't available, so behavior is identical everywhere — only the speed differs. )Loader)rrr )r s rfast_safe_loadrs  9V$9$;$; < < <dS)zARewrite supported proxy env vars to canonical URL forms in-place.rN)_PROXY_ENV_KEYSrrr'environ)rr normalizeds rnormalize_proxy_env_varsr,GsW)) #r""(//  )*--(BJsO ))rbase_urlc|pd}|sdStd|vr|nd|}|jpddS)aReturn the lowercased hostname for a base URL, or ``""`` if absent. Use exact-hostname comparisons against known provider hosts (``api.openai.com``, ``api.x.ai``, ``api.anthropic.com``) instead of substring matches on the raw URL. Substring checks treat attacker- or proxy-controlled paths/hosts like ``https://api.openai.com.example/v1`` or ``https://proxy.test/api.openai.com/v1`` as native endpoints, which leads to wrong api_mode / auth routing. rz://z//r)rrhostnamerrstrip)r-rparseds rbase_url_hostnamer2Ssl >r " "C r Uc\\cczCzz : :F O !r ( ( * * 1 1# 6 66rmodelc|pd}|sdSd|vr|ddd}|dph|dpS|dp>|d p)|d p|d S) uAReturn True for model families that require ``max_completion_tokens``. OpenAI's newer families reject ``max_tokens`` on /v1/chat/completions with HTTP 400 ``unsupported_parameter`` — the caller must send ``max_completion_tokens`` instead. This covers: - ``gpt-4o`` / ``gpt-4o-mini`` / ``gpt-4o-*`` - ``gpt-4.1`` / ``gpt-4.1-*`` - ``gpt-5`` / ``gpt-5.x`` / ``gpt-5-*`` - ``o1`` / ``o1-*`` - ``o3`` / ``o3-*`` - ``o4`` / ``o4-*`` Handles vendor prefixes like ``openai/gpt-5.4`` by stripping to the tail. The URL-based check (``base_url_hostname == "api.openai.com"``) misses third-party OpenAI-compatible endpoints (custom OpenAI gateways, OpenRouter) that front these models and enforce the same parameter constraint, so name-based detection is required as a fallback. rF/r1rzgpt-4ozgpt-4.1zgpt-5o1o3o4)rrrsplitr%)r3ms r"model_forces_max_completion_tokensr;gs( "##%%A u axx HHS!  R  X  << " "  <<   <<    <<     <<   rdomainct|}|sdS|pdd}|sdS||kp|d|zS)acReturn True when the base URL's hostname is ``domain`` or a subdomain. Safer counterpart to ``domain in base_url``, which is the substring false-positive class documented on ``base_url_hostname``. Accepts bare hosts, full URLs, and URLs with paths. base_url_host_matches("https://api.moonshot.ai/v1", "moonshot.ai") == True base_url_host_matches("https://moonshot.ai", "moonshot.ai") == True base_url_host_matches("https://evil.com/moonshot.ai/v1", "moonshot.ai") == False base_url_host_matches("https://moonshot.ai.evil/v1", "moonshot.ai") == False Frr)r2rrr0endswith)r-r<r/s rbase_url_host_matchesr?s|!**H ul ! ! # # ) ) + + 2 23 7 7F u v  @!2!23rHs00   !!!!!!  8 $ $555663$DD#DDTDDDD d| t (@     d +C     " T  $    "go "%.Ikkk$:$:!"  W      !s!s!t!!!!H C C D    RU39-RuS$Y7GRCRRRRr $@@@ T @ @ @  @  @@ @@@@N EEE T E E  E * E  E EEEEV!% &&& T & & $  &  &&&&R 4 4 4 4 44? 4 4 4( % $ $NNN T N N N  N : NN NNNNb@ T @@ @ @@@@Fs T ss ssssr  #  s    (=3=3====s33@@#@@@@@@ 3: #*    ))))777777( c d    FACAAAAAAAAr