+ Wj aRt^0tRt^RIt^RIt^RIt^RIt^RIt^RIt^RIt^RI t ^RI t ^RI t ^RI H t ^RIHt^RIHtHt^RIHt^RIt]P.!]4t]!0Rm4tRRRlltRR R lltR R ltRtRRlt RRlt!RRlt"RRlt#RRlt$RRlt%RRlt&]PNR8Ht(]!0Rm4t)^t*Rt+Rt,]PZ]P\3t/R R!lt0R"R#lt1R$R%lt2R&R'lt3R(R)lt4R*R+lt5R,R-lt6R.R/R/R0llt7R1R2R3RR4R5R6RR7R/R8R9llt8RR:R;llt9R1R2RRR?RR3RR7R/R@RAllt:RRLR RMR/RNROllt?RPRRQRRRRR?R/RSRTllt@RURVltARRR/RWRXlltBRYRZltC]!0Rm4tDR[R\ltER]R/R^R_lltFRR`RalltGRbRcltH/tI]^k] P!4tKRdReltLRfRgltMRRhRilltNRRjRklltORRlRmlltPRtQRtRRnRoltSRpRqltTRrRsltURtRultVRvRwltWRxRyltXRzR{ltYR|R}ltZR~Rlt[RRlt\RRlt]R#)z*Shared utility functions for hermes-agent.N)suppressPath)AnyUnion)urlparseFc<V^8dQhR\R\R\/#)valuedefaultreturnrbool)formats"9C:\Users\johnn\AppData\Local\hermes\hermes-agent\utils.py __annotate__rs!3$cVfV#\V\4'd&VP4P4\9#\ V4#)zDCoerce bool-ish values using the project's shared truthy string set.) isinstancestrstriplowerTRUTHY_STRINGSr)r r s&&ris_truthy_valuers= }%{{}""$66 ;rc<V^8dQhR\R\R\/#)r namer r rr)rs"rrr#s&DD#DDTDrcD\\P!W4RR7#)zBReturn True when an environment variable is set to a truthy value.Fr rosgetenv)rr s&&renv_var_enabledr##s 299T3U CCrczV^8dQhR\PR\\\\\3,/#)r str )r! stat_resulttupleint)rs"rrr(s0 C Cr~~ C%S#s0B*C Crc^VPVPVPVP3#)uChange-detection key for a stat result: ``(st_mtime_ns, st_size, st_ino, st_ctime_ns)``. mtime + size alone miss a replacement that preserves both (``cp -p``, ``rsync -t``, a tar restore, a script pinning the timestamp with ``os.utime``). The inode changes on an atomic replace and ctime cannot be backdated from user space, so the pair catches those writers. On Windows ``st_ino`` may be 0 and ``st_ctime_ns`` is the creation time — both stable across an in-place rewrite, so the key degrades to mtime + size there rather than misfiring. ) st_mtime_nsst_sizest_ino st_ctime_ns)r%s&rfile_signaturer.(s# NNBJJ 2>> BBri5wc0V^8dQhR\R\/#)r mtime_nsr )r(r)rs"rrr:s<H $'; ;;rc>V^8dQhR\R\R,/#r pathr Nrr()rs"rrr?sdsTzrcVP4'd/\P!VP4P4#R# \dR#i;i)z6Permission bits of *path* if it exists, else ``None``.N)existsstatS_IMODEst_modeOSError)r8s&r_preserve_file_moder@?sC48KKMMt||DIIK//0KtK sA-AA AAc`V^8dQhR\R\\\3,R,/#r7rr'r()rs"rrrGs'22t2c3h$(>2rc\PR8XdVP4MRpT'dTPTP 3#R# \dR#i;i)z8Owning ``(uid, gid)`` of *path* on POSIX, else ``None``.posixN)r!rr<r?st_uidst_gid)r8r%s& r_preserve_file_ownerrGGsOGGw.TYY[D&(BIIryy !1T1 s'A AAc~V^8dQhR\R\\\3,R,R\R,RR/#)r r8ownerNmoder rB)rs"rrrPs; ! ! !eCHo.D !CRVJ ![_ !rcVe\\\R4'dF\\4;_uu_4\P!W^,V^,4RRR4Ve9\\4;_uu_4\P !W4RRR4R#R# +'giLN;i +'giR#;i)aBest-effort re-apply of uid/gid and permission bits after an atomic replace. Docker/NAS installs often run some commands as root on a volume owned by the runtime user; ``os.replace`` swaps in the temp file's owner, so privileged callers chown it back. ``mkstemp`` creates 0o600 files; without re-applying *mode* the target would inherit that and break volume mounts relying on broader permissions. Nchown)hasattrr!rr?rLchmod)r8rIrJs&&&r_restore_file_metadatarOPs{ WR11 g   HHT8U1X .  g   HHT     s&B;B1 B. 1 C c2V^8dQhR\R,/#r r N)r()rs"rrr`ssTzrc\PR8wdR#\P!^?4p\P!V4RT(,# \dR#i;i)uThe mode ``open(path, "w")`` gives a file it has to create (``0o666 & ~umask``); ``None`` when the umask cannot be read or on non-POSIX hosts (Windows mode bits are synthesized). ``mkstemp`` always creates at 0600, so publishing a *new* non-secret file through a temp file would tighten it to owner-only — the Docker/NAS volume-mount hazard :func:`_restore_file_metadata` documents. The transient mask is 0o077: a thread that opens a file in the read window gets a tighter file, never a looser one. rDNi)r!rumaskr?)currents rdefault_new_file_moderU`sT ww'((5/  G8  s,A AAcdV^8dQhR\R\\\3,R,RR/#)r r8rINr rB)rs"rrrss...d.5c?T+A.d.rc\WR4R#NrO)r8rIs&&r_restore_file_ownerrZss 4-rcBV^8dQhR\R\R,RR/#)r r8rJNr r9)rs"rrrws%--T-t--rc \VRV4R#rXrY)r8rJs&&r_restore_file_moder]ws4t,rntg{Gz?g?c0V^8dQhR\R\/#)r excr )r?r)rs"rrrs__W__rcF\;'d\VRR4\9#)z %s failed with %s; falling back to %srbzin-place rewritecopy)r _publish_pathr!replacer?rferrno_CROSS_DEVICE_ERRNOSagent.retry_utilsrrange_REPLACE_RETRY_ATTEMPTSr2sleep_REPLACE_RETRY_BASE_DELAY_S_REPLACE_RETRY_MAX_DELAY_Sloggerdebugrd errorcodegetr|r) rr target_strrjrir` contendedrattempt retry_excs && ratomic_replacersjVJj)I(mGQ 7& Q7< 990 0   : $;a$?@ +G@[hBCD JJw2$$#C *>>$) >yIIJ  A  RT[S*d3eeu7J7J399>>XY[^[d[d7e+4'& B( ^ ;WPP 1Qsv; G'F>/F>8AF>CF>G D&*D!F> D!F>!D&&)F>,F>=F>F>&F>>Gc0V^8dQhR\R\/#)r rr rk)rs"rrrsVVcVcVrc\PPV4'd \PPV4#T#)z\The path :func:`atomic_replace` renames onto: a symlink's real file, else the target itself.)r!r8islinkrealpath)rs&rrrs.+-77>>*+E+E277  J 'U:UrctV^8dQhR\\,R\R\\\3,/#)r rkwr )rrrr'r()rs"rrrs-443:4S4U38_4rc J\V4p\\V4P4p\PP \ V44;'gTp\P!RRV/VB# \d#YC8Xdh\P!RRT/TBu#i;i)a``tempfile.mkstemp`` in the directory :func:`atomic_replace` will rename into. A temp staged next to a symlink whose target lives on another filesystem turns the publish rename into EXDEV, and atomic_replace's copy fallback then rewrites the file in place (torn on a crash). Staging beside the resolved target keeps the rename atomic. If that directory is not writable to us (the file itself may still be), stage beside the link instead: the save keeps working through the non-atomic copy fallback, exactly as before. dir) rrparentr!r8dirnamertempfilemkstempPermissionError)rrrlink_dir stage_dirs&, rmkstemp_besidersVJ4 #**+H j 9:FFhI44I444 4  3H3334sA55*B"!B"c>V^8dQhR\\,RR/#r7r)rs"rrrs#*rc \PR8XdR#\P!V\P\ \R^4,4p\ \ 4;_uu_4\P!T4RRR4\P!T4R# \ dR#i;i +'giL:;i \P!T4i;i)u5Best-effort fsync of a directory entry so a just-renamed file survives power loss. No-op on Windows (directories can't be opened with ``os.open``; the file fsync still applies) and on any OSError — durability of the directory entry is never worth failing a write that has already been replaced into place. r^N O_DIRECTORY) r!rroO_RDONLYrdr?rrurv)r8rzs& rfsync_directoryrs ww$ WWT2;;]A)FF G g   HHRL     s5;B#C,B5C# B21B25 C CC  ignore_errorscJV^8dQhR\\,R\RR/#)r r8rr N)rrr)rs"rrr s%  #*   rcRp\P!WR7R# \d\P!YR7R#i;i \dT'ghR#i;i)a,``shutil.rmtree`` that can also delete read-only trees. ``shutil.rmtree`` stops at the first entry it cannot unlink. Git marks loose object files read-only on Windows (``WinError 5``), and package installs (Nix store, deb/rpm) are copied ``r--r--r--`` into ``0555`` directories on POSIX, where unlinking needs a writable *parent*. Clear the write bit on the failing path and on its parent, then retry the exact operation that failed. Only ``PermissionError`` is retried: every other failure keeps ``shutil.rmtree``'s semantics (and ``ignore_errors``). c \V\4'd V^,MTp\V\4'gVh\PP V4V3FpV'gK \ \4;_uu_4\P!V\P!V4P\P,\P,4RRR4K V!V4R# +'giK;i)N) rr'rr!r8rrr?rNr<r>S_IWUSRS_IXUSR)funcfpathexc_infor` candidates&&& r _on_error"rmtree_readonly.._on_errors'%88hqkh#//I''//%0%8Iyg&&HHY (:(B(BT\\(QTXT`T`(`a'&9 U '&&s ?A C55 D )onexc)onerrorN)rrmtree TypeErrorr?)r8rrs&$ rrmtree_readonlyr sV   3 MM$ 0 3 MM$ 2 2 3  s-"AAAAA A A encodingutf-8rJpreserve_ownerTbinary fsync_dirc~V^8dQhR\R\R\R\R,R\R\R\R R/#) r r8prefixrrJNrrrr )rrr(r)rs"rrr-sO((((s(TWZ^T^("&(7;(PT(ae(rc^RIHpV!VP4Vf!VP4'g \ 4pV'd \ V4MRp \ WRR7wr\P!Y'dRMRV'dRMTR7;_uu_4p Ve<\\R4'd&\P!V P4V4V!V 4V P4\P!V P44RRR4\\W44p \!WV4V'd\#V P4R#R# +'giLQ;i \$dL\'\(4;_uu_4\P*!T 4RRR4h +'gih;ii;i) uTemp file + fsync + :func:`atomic_replace`, then re-apply owner/mode. *write(f)* emits the payload into the open handle (text, or bytes when *binary*). The temp file is created by ``mkstemp`` — ``O_CREAT|O_EXCL`` at 0600 regardless of umask — so a secret is never readable at process umask, not even between create and chmod. *mode* is fchmod'd onto the temp fd BEFORE the replace so the target never transits through mkstemp's 0600 (fchmod is Unix-only; the post-replace chmod is the sole path on Windows). With no *mode* a NEW target gets what ``open(path, "w")`` would have given it (process umask) — the callers this replaced wrote at umask, and silently tightening every fresh cache/state file to 0600 breaks shared volume mounts; an existing target with no *mode* keeps mkstemp's bits, as before. *fsync_dir* also fsyncs the resolved target's parent so the rename itself is durable. The temp file is removed on any failure — ``BaseException`` on purpose, so KeyboardInterrupt / SystemExit still clean up. mkdir_under_hermes_homeNz.tmp)rsuffixwbwrfchmod)hermes_constantsrrr;rUrGrr!fdopenrMrrflushrurrrOr BaseExceptionrr?rw)r8rsrrrJrrrroriginal_ownerrzrrreplaceds&&$$$$$$ r _atomic_writer-s-&9DKK( |DKKMM$&3A)$/tN!$fELB YYr64sVTQY Z Z^_GB$9$9 !((*d+ !H GGI HHQXXZ [ x67x>  HOO , [ Z  g   IIh    sD""E.E.A#atomic_write_text..i!'''"2rN)r)rrrJrr)rrr)r8rrrrrrJrs&f$$$$$$ratomic_write_textr^s3 :D$2:#/t_Tan5o!.Erc |V^8dQhR\\,R\R\R\R,R\RR/#)r r8rrrJNrr )rrbytesr(r)rs"rrrnsIeeS4Ze%ee 4Ze;?eLPerc ha\V4p\TV3RlTRRVeTM \V4VR7R#)zKBytes variant of :func:`atomic_write_text` (encrypted blobs, key material).c&<VPS4#rXrrs&rr$atomic_write_bytes..rrrTFN)rrrrJr)rrr@)r8rrrJrs&f$$$ratomic_write_bytesrns6 :D$2:dch#/t5H5NZcerc ZV^8dQhR\R\R,R\R\RR/#)r ryindentN ensure_ascii dump_kwargsr )rr(rdict)rs"rrrvs<SSSSd S$SUYS^bSrc \P!V3RVRV/VBpVPV4R# \d/TP\P!T3RTRR/TB4R#i;i)uV``json.dump`` that survives surrogate-escaped strings. ``os.fsdecode`` of a non-UTF-8 filename/argv yields lone surrogates (``'\udcff'``); a utf-8 text handle rejects them with ``UnicodeEncodeError`` — a ValueError, which callers guarding ``except OSError`` never see. ``ensure_ascii=True`` escapes them as ``\udcff`` and ``json.loads`` restores the identical str, so the retry round-trips; ``surrogateescape`` would emit a raw 0xFF byte that the reader's utf-8 decode rejects. Serializing to a str first keeps the failure before any byte reaches the file, so no partial payload is left behind. rrTN)jsondumpsrsUnicodeEncodeError)ryrrrrtexts&&$$$ r _dump_jsonrvsg ::d T6 T T TDS  S  4QQTQ[QRSs05A)(A)rrcV^8dQhR\\,R\R\R\R,R\R\R\R R/#) r r8ryrrJNrrrr )rrrr(r)rs"rrrsV'' *'',/';>:''+/'HK' 'rc aaaa\V4p\TVVVV3RlRVP R2VeTM \V4VR7R#)aWrite JSON to *path* atomically (temp file + fsync + replace). Surrogate-escaped strings (non-UTF-8 argv/paths) are always persisted: the write falls back to ``ensure_ascii=True`` escapes for that payload only, so normal content keeps its raw UTF-8 bytes. ``mode=0o600`` is the private-credential form: the temp file is 0600 from creation (mkstemp), so the payload is never umask-readable. c$<\SVSSSR7#))rrr)r)rryrrrs&rr#atomic_json_write..s*T1VR^lw"xr._N)rrJr)rrstemr@)r8ryrrJrrrs&fd$d$lratomic_json_writers> :D$xTYYKq)8HNabfNg%'rcFV^8dQhR\\,R\/#r r8r rrr)rs"rrrs 2 2S4Z 2D 2rc\P!\V4PRR74p\ T\4'dT#/# \\ 3d/u#i;i)u%The JSON object at *path*, or ``{}`` when the file is missing, unreadable, malformed or not an object. The read half of every ``read → merge → atomic_json_write`` config store (memory-provider ``save_config``), so a corrupt sidecar degrades to defaults instead of taking the provider down.z utf-8-sigr)rloadsr read_textr? ValueErrorrr)r8rys& rread_json_or_emptyrs[ zz$t*.. .DEdD))41r1 Z  s/A A! A!labellogcV^8dQhR\\,R\R\PR,R\/#)r r8rrNr )rrloggingLoggerr)rs"rrrs:3:X_XfXfimXmy}rc\V4pVP4Pp\P R8wg3T\P \P,,'gR#T;'g\PRT'dT R2MRTP \P!T4T4R# \dR#i;i)aWarn when a credential file is group/world-readable; True when a warning was emitted. Hand-made secret files (or ones older Hermes wrote without an explicit mode) commonly end up 0o644 under the default umask; call this before loading any token/credential file. No-op on non-POSIX (Windows ACLs don't map onto group/other bits; st_mode there is synthesized), when the file is missing, or when permissions are already tight. FrDzO%s%s is group/world-readable (mode 0%o) and contains secrets. Run: chmod 600 %s rT) rr<r>r?r!rS_IRGRPS_IROTHrwarningr=)r8rrp file_modes&$$ r(warn_if_credential_file_broadly_readablers T AFFH$$  ww')t||dll/J"K"K]]Fm+0ugQKb!&&$,,yBY[\^  sC CCdefault_flow_style sort_keys extra_contentcV^8dQhR\\,R\R\R\R\R,R\R,RR/#) r r8ryrrr Nrr )rrrrr()rs"rrrsV b bC$J bc b$ bcg b%(4Z bEH4Z b[_ brc aaaa\V4pRVVVV3Rllp\WRVP R2\W4R7R#)z>Write YAML to *path* atomically (temp file + fsync + replace).cV^8dQhRR/#rQr)rs"rr'atomic_yaml_write..__annotate__##T#rcr<\P!SVSSR7S'dVPS4R#R#))rrN)yaml safe_dumprs)rryrr rs&r_write!atomic_yaml_write.._writes+ tQ3EQZ[  GGM " rrrrrJN)rrrr)r8ryrrr rr)s&fddd$ ratomic_yaml_writer,s8 :D## $499+Q'7od>`arc$V^8dQhR\/#)r r8r)rs"rrrsYY$Yrc^RIHp\P!4pVP 4'd"VP VP RR74MRpT\W14'dV3#T!T;'g/43#)z``(yaml_rt, CommentedMap)``: a ruamel round-trip loader keeping quotes/Unicode with 2-space indents, plus *path* loaded through it (empty map when missing/blank). CommentedMaprrN)ruamel.yaml.commentsr0r'roundtrip_yamlr;loadrr)r8r0yaml_rtrys& r_roundtrip_loadr5sd2!!#G=A[[]]7<<8 9PTD Jt::D XX TZZUW@X XXrcBV^8dQhR\R\R,RR/#)r r8r Nr )rr)rs"rrrs+YY$Y3:YY]YrclaaaRVVV3Rllp\WRVP R2\V4R7R#)cV^8dQhRR/#rQr)rs"rr%_roundtrip_dump..__annotate__r%rcb<SPSV4S'dVPS4R#R#rX)dumprs)rconfigr r4s&rr)_roundtrip_dump.._writes% VQ  GGM " rrrr+N)rrr@)r8r4r<r r)s&ffd r_roundtrip_dumpr>s/## $499+Q'7>QRV>WXrcVV^8dQhR\\,R\R\RR/#)r r8key_pathr r Nrrr)rs"rrrs-(+(+sTz(+S(+(+QU(+rc^RIHp^RIHpHp\ V4p^RIHpV!VP4\V4wrxTp V!V4p ^p WRp V!\V 4V 4;'g V ^,^3wrW,\V 48XdVfV PV R4MW)V &M?V PV 4p\W4'gVfR#V!4pWV &Tp W, p K\WV4R#)aUpdate one dotted YAML key while preserving comments, ordering, quoting and Unicode. Narrower than :func:`atomic_yaml_write` on purpose: for user-edited config files where a single setting mutation must not disturb the rest. Still writes via temp file + atomic replace. ``value=None`` removes the key (a ``key: null`` leftover reads as absent everywhere but litters the file and diverges from whole-document writers that drop the key). r/)_greedy_literal_match_split_key_pathrN)r1r0hermes_cli.configrCrDrrrrr5rrrpoprrr>)r8r@r r0rCrDrr4r<rTkeysi remainingsegconsumed next_values&&& ratomic_roundtrip_yaml_updaterMs2 I :D8DKK(%d+OGG 8 $D A H -d7mYG\\IVWLZ[K\  <3t9 $} C&$ [[% *33}%J%CL D6*rc0V^8dQhR\R\/#)r r r r)rs"rrr sSSrcp^RIHpHp^RIHp\ V\ 4'd0V!4pVP4FwrV\V4WE&K V#\ V\\34'dV!RV44#\ V\4'd"VP4\9d V!V4#V#)uPlain Python value → ruamel node: YAML 1.1-ambiguous strings force-quoted at every depth (a bare ``off`` inside a list reads back as ``False`` just like one at the top level).r0 CommentedSeq)DoubleQuotedScalarStringc38"TFp\V4xK R#5irX) _rt_value).0vs& r _rt_value..s8%QIaLL%s)r1r0rRruamel.yaml.scalarstringrSrritemsrUlistr'rr_YAML11_AMBIGUOUS_WORDS)r r0rRrSnodekrWs& rrUrU s@A%~KKMDAlDG" %$''8%888%%++-3J"J'.. Lrextra_content_on_createcdV^8dQhR\\,R\R\R,RR/#)r r8 new_stater`Nr r )rs"rrrs8:j:jS4Z:jD:j8;d :jNR:jrcaa a a a a ^RIHoHo ^RIHp\ V4p^RIHpV!VP4V!V4VP4'*;'g&VPRR7P4'*p\V4wrgRRlo V 3RlV 3R llo R VV V V V 3R llo V3R lV 3R llo S !Wq4\YYu'dTMRR7R#)uAPersist a full config-state dict while preserving comments and ordering. THE on-disk primitive for ``config.yaml`` (production callers reach it through ``hermes_cli.config.atomic_config_write`` or ``atomic_config_replace``): the document is loaded through ruamel round-trip mode and *new_state* is merged onto it, so comments, key order, quotes, blank lines and readable Unicode survive. Only nodes whose value actually changed are reassigned; an untouched scalar or list keeps its inline comments and formatting. Keys absent from *new_state* are deleted ("explicit absence": ``cfg.pop(k)`` + save removes ``k`` from disk). ``extra_content_on_create`` (commented example blocks) is appended only when the file is being created — re-appending it on every rewrite is how the stock boilerplate replaced users' own comments (#92554). rQ)$require_readable_config_before_writerrrc<V^8dQhR\R\R\/#)r rTr r r )rs"rr0atomic_roundtrip_yaml_save..__annotate__5s&YYCYYYrcZW8H;'d!\V\4\V\4J#rX)rr)rTr s&&r _unchanged.atomic_roundtrip_yaml_save.._unchanged5s'XXJw$=ESWAX$XXrc.<V^8dQhRSR\RR/#r dstrxr N)r\)rrRs"rrrf9s" 4Drc<\V4F:wr#V\V48d S!WV4K VP\V44K< V\V4R1R#rX) enumeraterrappendrU)rlrxrHr _merge_items&& r _merge_seq.atomic_roundtrip_yaml_save.._merge_seq9sH!#HA3s8|CE* 9U+, ' C NrcV^8dQhRR/#rQr)rs"rrrfBs(((rc<W,p\V\4'd\VS4'd S!W24R#\V\4'd\VS4'd S!W24R#S!W24'g\V4W&R#R#rX)rrr\rU) rlkeyr rTr0rR_mergerqrhs &&& rrp/atomic_roundtrip_yaml_save.._merge_itemBsh( eT " "z'<'H'H 7 " t $ $G\)J)J w &G++ 'CH,rc.<V^8dQhRSR\RR/#rk)r)rr0s"rrrfLs"Ltrc<VP4F#wr#W 9d S!WV4K\V4W&K% VUu.uF qDV9gK VNK upFpWK R#uupirX)r[rU)rlrxrur r_rps&& rrv*atomic_roundtrip_yaml_save.._mergeLsY))+JCzCe,$U+ & #3s!slAAs3C43s A AN)r )r1r0rRrErdrrrrr;rrr5r>)r8rbr`rdrcreatingr4existingr0rRrvrprqrhs&&$ @@@@@@ratomic_roundtrip_yaml_saver}s@F :D8DKK((.;;= PP(H(N(N(P$PH'-GY(( 8D8V^;Rdhirc<V^8dQhR\R\R\/#)r rr r )rr)rs"rrrYs!#src\P!V4# \P\\3dTu#i;i)z3Parse JSON, returning *default* on any parse error.)rr JSONDecodeErrorrr)rr s&&rsafe_json_loadsrYs7zz$  )Z 8s "==c0V^8dQhR\R\/#)r streamr rO)rs"rrras""3"3"rc.\P!V4#)zLUse the shared safe reader (which selects ruamel's C parser when available).)r' safe_load)rs&rfast_safe_loadras >>& !!rcFV^8dQhR\\,R\/#r rA)rs"rrrjs#*rc\V4p\VP44p\V4p\;_uu_4\ P V4pVe"V^,V8XdV^,uuRRR4#RRR4\VRR7;_uu_4p\V4pRRR4\;_uu_4VX3\ V&RRR4V# +'giL];i +'giLG;i +'giX#;i)u``fast_safe_load`` of a file, re-parsed only when its :func:`file_signature` changes. Returns the cached object itself — callers must never mutate it. Parse errors propagate and are not cached; a missing file raises ``FileNotFoundError`` like ``open`` does.Nrr) rr.r<r_YAML_FILE_CACHE_LOCK_YAML_FILE_CACHError)r8sigrucachedrrys& rload_yaml_file_readonlyrjs :D  %C d)C  !%%c*  &)s"2!9    dW % %a  &  !$d   K   & %   Ks#0C C!8 C4 C ! C1 4 D c$V^8dQhR\/#)r rurk)rs"rrr}sSrc\P!VR4P4pV'd V!V4#T# \\3dTu#i;ir)r!r"rrr)rur castraws&&& r _env_numberr}sJ ))C  " " $CtCy,W,  "s999AAc<V^8dQhR\R\R\/#r rur r )rr()rs"rrrs!***s*3*rc"\W\4#)z:Read an environment variable as an integer, with fallback.)rr(rur s&&renv_intrs sS ))rc<V^8dQhR\R\R\/#r)rfloat)rs"rrrs!,,3,,,rc"\W\4#)z7Read an environment variable as a float, with fallback.)rrrs&&r env_floatrs sU ++rc<V^8dQhR\R\R\/#rr)rs"rrrs&@@#@@@rcF\\P!VR4VR7#)z*Read an environment variable as a boolean.rrr rs&&renv_boolrs 299S"-w ??rcLV^8dQhR\R,R\R,/#)r proxy_urlNr rk)rs"rrrs"3:#*rc\T;'gR4P4pVP4PR4'dRV\ R4R 2#T;'gR#)zaNormalize proxy URLs for httpx/aiohttp: WSL/Clash export ``socks://``, httpx needs ``socks5://``.rzsocks://z socks5://N)rrr startswithrr)rrs& rnormalize_proxy_urlrs[IOO$**,I##J//9S_%56788   rc>V^8dQhR\R\R,/#)r entryr Nrk)rs"rrrs33c3cDj3rc~^RIp\T;'gR4P4p\P!RV4;'g\P!RV4pV'gR#VP VP ^44pTP^8XdTP ^4#R# \dR#i;i)u$The bare IPv6 literal a NO_PROXY entry should become, or None when the entry is not an IPv6 form httpx cannot compile (``[::1]``, ``[::1]:8080``, ``[2001:db8::1]/64``, ``::1/128``). httpx 0.28.1's ``get_environment_proxies`` routes bracketed entries through its wildcard branch (``all://*[::1]`` → ``InvalidURL: Invalid port`` at ``Client.__init__``) and cannot compile IPv6 CIDR bypasses at all, so both degrade to the bare literal — which httpx compiles into a working ``all://[]`` bypass and urllib, requests and ``agent.proxy_bypass`` all understand. A ``[]:port`` entry loses its port: httpx has no port-scoped IPv6 bypass form, and the portless literal still bypasses every port (the operator's intent superset). Bracketed or CIDR IPv4 is left alone (httpx compiles those forms fine). Nrz\[([0-9A-Fa-f:.]+)\](?:[/:].*)?z([0-9A-Fa-f:.]+)/\d+) ipaddressrrre fullmatch ip_addressgrouprversion)rrrmips& r_bare_ipv6_literalrsEKKR &&(I 8) D = = LL0) <   ! !!''!* -q1771:2d2 s) B-- B<;B<c>V^8dQhR\R,R\/#)r no_proxy_valueNr rk)rs"rrrscDjSrc\T;'gR4p\P!RVP44Uu.uFq"'gK VNK ppV'dRV9dV#.pVF>p\ V4pVfVP V4K%Wd9gK-VP V4K@ WC8XdV#RP V4#uupi)aRewrite NO_PROXY entries httpx 0.28.1 cannot compile into the equivalent bare-IPv6 forms. Every other entry passes through verbatim, and the original string is returned byte-stable when nothing needed rewriting (an env without bracketed/CIDR IPv6 entries is untouched). rz[\s,]+*,)rrsplitrrrojoin)rrpartentries rewrittenrbares& rsanitize_no_proxy_entriesrs n"" #C "CIIK @I @Dtt @GI cWn I!%( <   U #  "   T "   88I Js C CcV^8dQhRR/#rQr)rs"rrrs , ,$ ,rcT\FJp\P!VR4p\V4pV'gK/W!8wgK7V\PV&KL \ FIp\P!V4pV'gK#\ V4pW18wgK6V\PV&KK R#)zARewrite supported proxy env vars to canonical URL forms in-place.rN)_PROXY_ENV_KEYSr!r"renviron_NO_PROXY_ENV_KEYSr)rur normalized sanitizeds rnormalize_proxy_env_varsrsx #r"(/ :*-(BJJsO  " # 51%8I!"+ 3 "rc$V^8dQhR\/#)r base_urlrk)rs"rrrsJJcJrcT;'gRP4pV'd\RV9dV4#RV 24#R#)zF``urlparse`` that tolerates a bare ``host[:port][/path]`` (no scheme).rz://z//N)rr)rrs& r_parse_base_urlrs< >>r "C>rc0V^8dQhR\R\/#)r modelr r)rs"rrrsJJcJdJrcT;'gRP4P4PR^4R,pVPR4#)zYTrue for OpenAI families that reject ``max_tokens`` (HTTP 400 ``unsupported_parameter``).rr)zgpt-4ozgpt-4.1zgpt-5o1o3o4)rrrsplitr)rrs& r"model_forces_max_completion_tokensrsA "##%,,S!4R8A <<H IIrc\V^8dQhR\R\\\\3,/#r)rr'r()rs"rrrs)cccceCcM&:crc\V4p\V4pV'gR#VP;'gRP4pVPpY2TfRRR^P/P T^43#T3# \ dRu#i;i)u``(scheme, hostname, effective_port)`` for a base URL; ``("", "", 0)`` on no host/bad port. Origin, not just host: ``https://h`` vs ``http://h`` and two ports on one host are different trust boundaries, so handing a bearer secret to a new URL must compare all three — hostname alone would authorise an HTTPS→HTTP downgrade. Port defaults to 443/80 so ``https://h`` equals ``https://h:443``. rhttpsihttp)rr)rrschemerportrr)rrrrrs& rbase_url_originrsX &FF#H mm!!r ( ( *F{{ 41onyestrue)Fr> !)T> ny~noroffrnullrfalserX)r)g) HTTPS_PROXY HTTP_PROXY ALL_PROXY https_proxy http_proxy all_proxy)NO_PROXYno_proxy)_r__doc__rrrr!rrr<r threadingr2 contextlibrpathlibrtypingrr urllib.parser hermes_yamlr' getLogger__name__r frozensetrrr#r.r4r5r@rGrOrUrZr]rrcrerrrEXDEVEBUSYrrfr|rrrrrrrrrrrrrrr,r5r>rMr]rUr}rrrLockrrrrrrrrrrrrrrrrrrrr)rs@rrs0   !   8 $56D C%< 2 ! &.-ggo %.k$:! "  U[[1_ ,'TV 4(( u F(W(ae()-(>C(W\(VF E Edk E,1 EMQ Efj E(- E ege*.eBGeS"'23'HL''27'" 2rpt( bQV bjo b26 bRV bYYPTY(+^$$fg$:jEI:jz" !(&* , @ g-34, ,J I3?J c(ar