߲j|dZddlZddlZddlZddlZddlZddlZddlZddlm Z m Z ddl m Z ddl mZmZddlmZddlmZmZmZddlmZmZmZmZdd lmZmZmZmZm Z m!Z!dd l"m#Z#dd l$m%Z%ejLe'Z(e%d Z)d Z*e)re(jWejXejZZ.Gdde/Z0dZ1Gdde/Z2dee3gdfdzddfdZ4dee3gdfdzfdZ5de6de3ddfdZ7de fdZ8de de6fdZ9de de6ddfdZ:de3de;eGd!d"e Z?dd#l m@Z@dd$l mAZAddlBZBdd%lCmDZDddlEZEddlFZFddlGZGd&d'd(ZHd)ZIy)*aBase class for all Hermes execution environment backends. Unified spawn-per-call model: every command spawns a fresh ``bash -c`` process. A session snapshot (env vars, functions, aliases) is captured once at init and re-sourced before each command. CWD persists via in-band stdout markers (remote) or a temp file (local). Cohesive pieces live in sibling modules (``base_output``, ``base_session_env``, ``base_wait``, ``path_utils``). N)ABCabstractmethod)Path)CallableIterable)get_hermes_home) consume_yieldis_interruptedis_thread_interrupted) ProcessHandle_finalize_wait_result_new_output_collector_start_drain_thread)_SHELL_ENV_NAME_RE_SNAP_TMP_SUFFIX _cwd_marker_snapshot_bootstrap_script_split_cwd_marker_wrap_command_script) _WaitTrace)env_var_enabledHERMES_DEBUG_INTERRUPTg@ceZdZdZy)FileFetchErrorz:A file could not be extracted from the backend filesystem.N)__name__ __module__ __qualname____doc__Register a callback that _wait_for_process fires periodically.N)_activity_callback_localcallback)r.s r!set_activity_callbackr3Qs (*%r c$ttddS)umThread-local activity callback; capture it before handing work to another thread. Public accessor for callers outside this module that need to capture the calling thread's callback before handing work to another thread (the callback is thread-local, so a freshly spawned thread cannot read it back) — e.g. the manual cron-run heartbeat (#76502). r2N)getattrr1rr r!get_activity_callbackr6Vs +Z >>r statelabelc tj}||dz |jddkry||d< t}|r||dt ||dz dyy#t $rYywxYw)zFire the activity callback at most once every ``state['interval']`` (default 10 s). *state* holds ``last_touch``/``start`` monotonic timestamps. Swallows all exceptions. last_touchintervalg$@Nz (startz s elapsed))time monotonicgetr6int Exception)r7r8nowr.s r!touch_activity_if_duerC`s .. C U<  599Z#>>E, " $ %3sU7^345Z@ A     s)A"" A.-A.ctjd}|r t|n tdz }|j dd|S)zHost-side root for all sandbox storage (Docker workspaces, Singularity overlays/SIF cache). ``TERMINAL_SANDBOX_DIR`` overrides ``{HERMES_HOME}/sandboxes``.TERMINAL_SANDBOX_DIR sandboxesTparentsexist_ok)osgetenvrrmkdir)customps r!get_sandbox_dirrOos=YY- .FV O$5 $CAGGD4G( Hr pathcp tj|jdS#t$ricYSwxYw)z:Load a JSON file as a dict, returning ``{}`` on any error.utf-8encoding)jsonloads read_textrA)rPs r!_load_json_storerXxs5zz$..'.:;;  s $' 55datac|jjdd|jtj|ddy)z.Write *data* as pretty-printed JSON to *path*.TrG)indentrRrSN)parentrL write_textrUdumps)rPrYs r!_save_json_storer`s4KKdT2OODJJtA.OAr host_pathc t|j}|j|jfS#t$rYywxYw)zIReturn ``(mtime, size)`` for cache comparison, or ``None`` if unreadable.N)rstatst_mtimest_sizeOSError)rasts r!_file_mtime_keyrhs> )_ ! ! # RZZ(( s 03 ??ceZdZUdZdZeed<dZeed<dZ e ed<dZ eed<dZ eed <d efd Z d?d ede defdZddd ddedede ded zd ef dZedZdedede d d fdZded ed zfdZd eefdZd eedffdZd ed efd Zd!Zd"ed eeeffd#Zed ed efd$Zd%ed efd&Z d'ed ed efd(Z!ed'eded efd)Z" d@dd d d*d+ede d,ed-e d zd.e#eegefd zd ef d/Z$ee%Z%d+efd0Z&d1efd2Z'd1efd3Z(dAd4Z)dAd5Z* dBd d d6dd d7d'ed ede d zded zd8ed,ed.e#eegefd zd efd9Z+dAd:Z,d;Z-d'ed eeed zffd<Z.d=Z/d efd>Z0y )CBaseEnvironmentzCommon interface and unified execution flow for all Hermes backends. Subclasses implement ``_run_bash()`` and ``cleanup()``; the base provides ``execute()`` with snapshot sourcing, CWD tracking, interrupt handling and timeout enforcement.pipe _stdin_modeFis_local_snapshot_timeout_sudo_nopasswd_probe_supported_profile_scoped_passthroughr/cy)zBackend temp directory for session artifacts (``/tmp`` in sandboxes; LocalEnvironment overrides for Termux where only ``TMPDIR`` is writable).z/tmprr*s r! get_temp_dirzBaseEnvironment.get_temp_dirsr Ncwdtimeoutenvc||_||_|xsi|_tjj dd|_|jjdxsd}|d|j d|_ |d|j d|_ t|j |_ d|_ t|_d|_y)N /z /hermes-snap-z.shz /hermes-cwd-z.txtF)rurvrwuuiduuid4hex _session_idrtrstrip_snapshot_path _cwd_filer_snapshot_readyset_snapshot_passthrough_names_prefer_nonlogin)r*rurvrwtemp_dirs r!r)zBaseEnvironment.__init__s 9"::<++CR0$$&--c29c!) -8H8H7IM$:\$2B2B1C4H&t'7'78$58U(!&r xloginrv stdin_data cmd_stringrrcDtt|jd)zGSpawn a bash process to run *cmd_string*; every backend overrides this.z must implement _run_bash())NotImplementedErrortyper)r*rrrvrs r! _run_bashzBaseEnvironment._run_bashs""T$Z%8%8$99T"UVVr cy)zYZ]Y^!_`fi i js?EF0FFc|jdtj|dd}t|j dxsddk7ryt dt |j d xsd jDdS) zG``readlink -f`` inside the backend, or None when it cannot be resolved.z readlink -f z 2>/dev/nullF)rrrNc3|K|]4}|jjds#|j6yw)rzN)strip startswith).0lns r! z1BaseEnvironment.fetch_realpath..s.|Bacaiaiakavavwza{RXXZ|s$<<rr$)rrrr@r?nextreversed splitlines)r*rrs r!fetch_realpathzBaseEnvironment.fetch_realpaths U[[-E,FlSqvw vzz,',1 - 2|(FJJx4H4NB3Z3Z3\*]|CD Dr cy)zAReturn backend-specific names that must not persist in snapshots.rrrss r!,_additional_profile_scoped_passthrough_namesz.s/8l!js.CHZHdHdeiHjD8ls 555z4Could not refresh profile-scoped snapshot exclusionsTexc_info) rqagent.secret_scopertools.env_passthroughrrrupdaterAloggerdebugtuplesorted)r*rrnamess r!$_snapshot_excluded_passthrough_namesz4BaseEnvironment._snapshot_excluded_passthrough_namess// ` >"$Ef-/f$2c2c2ef00778l%*8llVD<<=>> ` LLOZ^L _ `sAA<< BBct|j||j|j|j|jtz|j S)aQuoting inputs shared by the bootstrap and per-command wrapper scripts. ``_quote_cwd_for_cd`` / ``_quote_shell_path`` (not bare shlex.quote) let the Windows subclass rewrite ``C:\...`` to ``/c/...`` so ``cd`` resolves and MSYS doesn't choke.) quoted_cwd quoted_snapsnap_tmp_template cwd_marker)dict_quote_cwd_for_cd_quote_shell_pathrrr)r*rus r!_snapshot_script_kwargsz'BaseEnvironment._snapshot_script_kwargssV--c2..t/B/BC"44T5H5HK[5[\'' ) )r c td d|ji|j|j} |j |d|j }|j ||j }t|jdxsddk7rtd|jdd|_ |j|tjd|j|jy #t$r}d |_ |j!t#|\|_}|j$r"tj'd |j|n&tj'd |j|Yd }~y Yd }~y d }~wwxYw)ukCapture the login shell environment into the snapshot file (once, after construction). On success ``_snapshot_ready`` is set so commands source the snapshot instead of running under ``bash -l``. On failure, fall back to ``bash -l`` per command — unless a non-login probe shows login bash itself is dead, in which case prefer ``bash -c``.excluded_namesTrrvrvrrz)snapshot bootstrap failed with exit code z-Session snapshot created (session=%s, cwd=%s)Fu_init_session failed (session=%s): %s — login bash unusable; falling back to non-login bash -cuLinit_session failed (session=%s): %s — falling back to bash -l per commandNr)rrrrurro_wait_for_processr@r? RuntimeErrorr _update_cwdrinfor~rA_probe_nonlogin_fallbackr,rwarning)r* bootstrapprocrrdetails r! init_sessionzBaseEnvironment.init_session sc /rDDFrJNJfJfgkgogoJpr  .>>)4AWAW>XD++D$:P:P+QF6::l+0q1Q6"%NvzzZfOgNh#ijj#'D   V $ KKGIYIY[_[c[c d .#(D ,0,I,I#c(,S )D !6$$M$$c+ b$$f.. + .sB>FrcXtd|j} |jdd|}|j||}t |j dxsddk(}|s'|j dxs|j xs|}||fS#t$r}d|d |fcYd }~Sd }~wwxYw) zHRun ``true`` under non-login bash; return ``(prefer_nonlogin, detail)``.trueFrrrrstdoutz; non-login probe: N)minrorrr@r?rrA)r*r probe_timeoutprobe probe_resultprefer_nonlogin probe_excs r!rz(BaseEnvironment._probe_nonlogin_fallback)sB 6 67  DNN6 NNE11%1OL!,"2"2<"@"EAF!KO"&**84>EEGQ6"F* * DVH$7 {CC C DsA4B B)B$B)$B)c|dk(r|S|dk(ry|jdrdtj|ddStj|S)zQuote a ``cd`` target while preserving ``~`` expansion (``~/...`` goes through ``$HOME`` so suffixes with spaces stay one word).~z~/z$HOMEz$HOME/r[N)rrr)rus r!rz!BaseEnvironment._quote_cwd_for_cd7sR #:J $; >>$ EKKAB012 2{{3r rPc,tj|S)zQuote *path* for a bash script. LocalEnvironment overrides this to rewrite native/mixed Windows paths to ``/c/...``; remote backends are POSIX.)rr)r*rPs r!rz!BaseEnvironment._quote_shell_pathCs{{4  r commandcnt|f|j|jd|j|S)zJFull bash script: source snapshot, cd, run, re-dump env, emit CWD markers.)passthrough_namessnapshot_ready)rrrr)r*rrus r! _wrap_commandzBaseEnvironment._wrap_commandHsA# 1"GGI//1**3/ 1 1r cddtjjdd}|d|d|d|S)zJAppend stdin_data as a shell heredoc to the command string (SDK backends). HERMES_STDIN_Nryz << 'z'  )r{r|r})rr delimiters r!_embed_stdin_heredocz$BaseEnvironment._embed_stdin_heredocPsA$DJJL$4$4Sb$9#:; % {#j\I;GGr )bounded_capturewatch_interrupt_tid yield_handlerrrrrct|}|tjnd}t||t j }||z} ||d} t |tt} | jfd} d} j| xjdz c_ ts t|r:| j| j||j!dd S|vt#|rk|j%j'd  ||j!}||j-|S|j/t||t j | kDr_| j1| |j!d|d}|j2dk(r|j5}j||dSt7| d| j9t j:| | dkrt=| dzd} jj'd  jDjG| jIjJtMdd}||j'd |j!}j||jJ}tMddx}rtO|dx|d<}|d|dz|d<|S#t($rtj+d d d}YwxYw#t>t@f$r)| jC | #t($rYwxYwwxYw#t($rY wxYw)uPoll-based wait with interrupt checking and stdout draining (shared, not overridden). ``yield_handler(proc, output_so_far)``: when the tool thread is asked to yield (``tools.interrupt.request_yield`` — a user message arrived mid-command), the drain thread is stopped, the still-running process is handed to the handler and its dict is returned as the result; the process is NOT killed. ``bounded_capture=True`` (foreground terminal-tool path only) retains at most ``tool_output.max_bytes`` in a head/tail window so a verbose subprocess cannot OOM the process; the default keeps full fidelity for internal consumers. Fires the activity callback every 10s so the gateway's inactivity timeout doesn't kill long commands. ``watch_interrupt_tid`` is the tool-worker thread that submitted this wait: ``execute()`` may move the wait onto a ``run_bounded_sync`` worker while ``/stop`` still interrupts the original tid, so both bits are honored. ``KeyboardInterrupt``/``SystemExit`` mid-poll kills the process first — the local backend spawns into its own process group, so an unkilled child would be orphaned. The default (False) preserves full-fidelity capture for internal consumers — file-operation ``cat`` reads feeding the patch engine, code-execution RPC reads, log reads — where truncation would corrupt data. See #64435. N)r:r<)enabledrcLjjdy)Nr[r) _kill_processr) drain_threadrr*sr!_kill_and_joinz9BaseEnvironment._wait_for_process.._kill_and_joinws"   t $   a  (r g{Gzt?rz [Command interrupted])suffixrz6yield-to-background handoff failed; continuing to waitTrz [Command timed out after s]r|zterminal command runningg?g?r[_hermes_stdin_thread_hermes_stdin_errors stdin_errorz [stdin write failed: ]r)(r threadingEventrr=r>r_DEBUG_INTERRUPTrenterpoll iterationsr r interruptedr renderr rrrAr close_spillclear timed_out total_charslstriprC heartbeatsleeprKeyboardInterrupt SystemExitexception_exitrclose natural_exitrr5r,)r*rrvrrrr drain_stop_nowdeadline_activity_statetracer  _poll_sleephandedrendered stdin_threadr stdin_errorserrr s`` @r!rz!BaseEnvironment._wait_for_processWsY.'t_=*7*CY__& *4D ~~'>)-=42B6R  ))  K))+%  A% !#'<=P'Q%%'"$55ffmmSlm>morss ,?R1SNN$ %%a%0&!.tV]]_!E)**,% $$tVZ#PL>>#h.OO%"$%}}6QRYQZZ\4]}^H))Q.#+??#455fhLL%o7QR! ;'$"%kC&7"=K=))+%R !$  KK    4??+ t%;TB  #   a  (==?++FHdooN"4)?F F< F*-l1o*> >F= !C',CC5*JJF8  a%&'_jno!%&(":.   "           s{A6L-9/L-)LL-BL-'AL-M("L*&L-)L**L--M% MM% M!M% M!!M%( M54M5cZ |jy#tttf$rYywxYw)zDTerminate a process. Subclasses may override for process-group kill.N)killProcessLookupErrorPermissionErrorrfr*rs r!rzBaseEnvironment._kill_processs)  IIK"OW=   s **rc&|j|y)zDExtract CWD from command output. Override for local file-based read.N)_extract_cwd_from_output)r*rs r!rzBaseEnvironment._update_cwds %%f-r ct|jdd|j}|y|\}}|r||_d|d<||d<||d<y)aParse the ``__HERMES_CWD_{session}__`` marker from ``result["output"]``, update ``self.cwd`` and strip the marker line. ``result["cwd_observed"]``/``["cwd"]`` are set only when THIS command emitted a marker: a killed/timed-out command emits none and ``self.cwd`` keeps the previous value. The environment is shared across sessions, so concurrent callers must read ``result["cwd"]`` rather than ``self.cwd``.rr$NT cwd_observedru)rr?rru)r*rrcwd_pathcleaneds r!r9z(BaseEnvironment._extract_cwd_from_outputsZ "&**Xr":D "$F5M"xr cy)zHook before each command. Remote backends (SSH, Modal, Daytona) trigger their FileSyncManager here; bind-mount backends and Local don't.Nrrss r!_before_executezBaseEnvironment._before_executes r cd|_y)uFlag that the live container/sandbox was replaced while serving the current command. ``execute`` folds the flag into the result as ``environment_recreated`` so the tool layer can warn the model that background processes died and non-persisted files may be gone — without this the recovery is silent and the model keeps assuming the old workspace state (lobehub/lobehub#19329 class).TN)_recreated_notice_pendingrss r!_mark_recreatedzBaseEnvironment._mark_recreateds *.&r T)rvrrrrrc jj|\}} |rddlm} | |}|xs j|xs j } | | |xsdzn|r#j dk(rj|}dj|| j xr j tjjtgdtff d } dfd } dd lm} t%}|t*z } || |d t-j.| }|j4r d dddn |j6}j9|t;ddr d_d|d<|S#t&t(f$rd }YwxYw#t0t2f$r | wxYw)u Execute a command, return {"output": str, "returncode": int}. ``bounded_capture=True`` caps retention at ``tool_output.max_bytes`` WHILE draining; only the foreground terminal tool may set it — internal full-fidelity consumers (file-op ``cat`` reads feeding the patch engine, RPC reads, log reads) MUST leave it False or data is corrupted. The wait is bounded by ``agent.deadline.run_bounded_sync`` so a wedged poll loop cannot hang past ``timeout`` and silently disable every asyncio timer in the process. ``bounded_capture=True`` caps stdout/stderr retention at ``tool_output.max_bytes`` WHILE the stream is drained (head/tail window) instead of holding the full output in memory (#64435). See #94285. r)_rewrite_compound_backgroundNr$heredocr/c  tj }j|j|fd d iSiS)Nr)rvrrr)r3rappendr) spawnedreffective_stdineffective_timeoutrparent_activity_cb parent_tid proc_holderr*wrappedrs r!_spawn_and_waitz0BaseEnvironment.execute.._spawn_and_waits!-%&89nnWECTapnqG   w ')4))[!2O$.[8E7PO]3[ [WY[ [r c4rjdyy)Nr)_kill_spawned_tree)rMr*sr! _on_timeoutz,BaseEnvironment.execute.._on_timeout&s'' A7r )run_bounded_syncg^@zterminal.wait:)r8 on_timeoutz[Command timed out after r r)rrrAFTenvironment_recreatedr/N)r?_prepare_commandtools.terminal_tool_sudorDrvrurlrrrrrcurrent_threadidentr6ragent.deadlinerSfloat TypeErrorr_EXECUTE_WAIT_BOUND_GRACE_Srrr#r$rvaluerr5rA)r*rrurvrrrr exec_command sudo_stdinrD effective_cwdrOrRrSbound_sboundedrrIrJrrKrLrMrNs` `` @@@@@@@r!rzBaseEnvironment.executes* #'#8#8#A j ' M7 EL#3t||txx >H=S* (8b9Yc t//9<44\?SL"O$$\=A(((F1F1F-F--/55 34  [ [ [ 8 4 -.G .. &.dATAT@U0VcnpG  33D2ERHX[ \&-mm   44e <-2D *.2F* + %:& G ":.  M  s F!"F'F$#F$'F?c |j|t |dd}|sy ddlm}|t|y#t$rtjddYKwxYw#t$rtjddYywxYw) zJBest-effort kill of a wedged spawned process and its tree (backstop path).z'terminal wait-bound kill_process failedTrpidNr)kill_process_treez,terminal wait-bound kill_process_tree failed)rrArrr5r[rgr@)r*rHrfrgs r!rQz"BaseEnvironment._kill_spawned_treeHs S   w 'gud+  X 8 c#h ' S LLBTL R S X LLGRVL W Xs <A" AA" BBcD |jy#t$rYywxYwr)rrArss r!__del__zBaseEnvironment.__del__Xs"  LLN   s  c6ddlm}|||jS)zTRewrite sudo for a piped password, or leave it alone when this backend has NOPASSWD.r)_transform_sudo_command)sudo_nopasswd_check)rXrk_sudo_nopasswd_works)r*rrks r!rWz BaseEnvironment._prepare_command^sD&wDD]D]^^r c|jsy |jd|j}|j||jj ddk(S#t $rYywxYw)z``sudo -n true`` inside THIS backend (host sudo state must not leak into a sandbox). Fails closed: any error or a timed-out probe means "assume a password is needed".Fz sudo -n truerrr)rpr_SUDO_PROBE_TIMEOUT_Srr?rAr7s r!rmz$BaseEnvironment._sudo_nopasswd_worksesm22 >>.$:T:T>UD))$8R8R)SWWXdeijj j  sA A A'&A'r)rrV)r$)1rrrrrlr,__annotations__rmboolror@rprqrtrr)r rrrrrrrrrrrrr staticmethodrrrrrrr rrr9r?rBrrQrirWrprmrr r!rjrjs[T KHd s,1"D0).-c &C&#&D&$16cdhWW)-W@CWWZ]aWaW W   +c+t+3+SW+<D#D#*Dhsm?eCHo?")3)4).8 Ds DuT3Y7G D  s  s    !c!c! 1S1s1s1HcHsHsHH36c %EIc!c,/cc?-.$.#t#" .\ #!%,0 %EI\\\ t \ $J \&*\\  4d :;dB\OS\| X  __c3:o0F_  d r rj)IO)Protocol)deque)ztools.environments.path_utilssanitize_task_id_for_path)zhermes_cli._subprocess_compatwindows_hide_flags)rwrxctj|}|tdtd|ddl}ddlm}|t|g|t|j|d|dS)Nzmodule z has no attribute r) warn_oncer) _PLUGIN_COMPAT_LAZYr?AttributeErrorr importlibhermes_cli.plugin_compatrzr5 import_module)rtargetr}rzs r! __getattr__rse $ $T *F ~wxl2DTHMNN2 h&v& 9**6!95vay AAr )JrrUloggingrJrrr=r{abcrrpathlibrtypingrrhermes_constantsrtools.interruptr r r tools.environments.base_outputr r rr#tools.environments.base_session_envrrrrrrtools.environments.base_waitrutilsr getLoggerrrrr^setLevelINFOlocalr1rrrr#r,r3r6rrCrOrXr`rr\r@rhrjrtrucodecs collectionsrvreselect subprocessr{rrr r!rs   #%,PP4!   8 $##;<" OOGLL!+9??,E\E 33"+hud{3d:+t+ ?xt 4t;?    c  d    4DB4BtBB suUCZ'84'?_c_L  "`Q Br