
    Jj                    N   U d Z ddlZddlZddlZddlZddlZddlZddlZddl	Z	ddl
Z
ddlZddlZddlmZ ddlmZmZmZmZ ddlmZ  ej        e          ZddlmZmZ ddlmZ ddlmZm Z m!Z!m"Z"m#Z# d	e$d
ede$fdZ% e%dde&d          Z' e%dde(d          Z)d Z*i Z+e,e$e$f         e-d<    e	j.                    Z/ e	j0                    Z1d Z2d Z3d Z4d Z5de$fdZ6de$fdZ7de$ddfdZ8ddZ9ddl:m;Z< d e$de=fd!Z>d"ee$ef         de=fd#Z?	 dd%e$d&e$d'e=de,fd(Z@ ejA        d)          ZBd*e$de$dz  fd+ZCd,e$d&e$de$fd-ZDd.ZEd,e$de=fd/ZFd%e$dz  d,e$de=fd0ZGdd2e&de$fd3ZHdd%ed5e&de$fd6ZId7e$de=fd8ZJd%e$d9e&deKe$e&f         fd:ZLd%e$deKe$e&f         fd;ZMd%e$de&fd<ZNde=fd=ZOd%e$de$fd>ZPd%e$dz  deKe$dz  e$dz  f         fd?ZQdd@lRmSZT ddAlmUZV ddBlWmXZY ddClZm[Z\ ddDl]m^Z_ ddEl`maZb ddFlcmdZd ddleZedGZfi Zgee$ef         e-dH<   i Zhee$e(f         e-dI<    e	j.                    Zii Zjee$e	j.        f         e-dJ<    e	j.                    Zkdald$amd$an e	j.                    ZodKee$ef         ddfdLZpi Zqee$ee$ef         f         e-dM<   dNe$dOee$ef         fdPZrdNe$fdQZsdNee$         de$fdRZtdNee$         dee$ef         fdSZue&dfd	e$d
e$dTede$fdUZvde$fdVZwdWZx eyh dX          ZzdYe$dZe$de=fd[Z{dZe$de=fd\Z|dee$ef         fd]Z}d^e~dz  dee$ef         fd_Z	 	 	 	 dd&e$d`e$dZe$dae&dbe,dKe,dce,dNe$dde$fdeZddge&fdhZdi Zdj Zdk ZdNe$fdlZdNe$de=fdmZdn Zd$dodNe$dpe=fdqZdr Z e
j        e           d%e$dse&de$dz  fdtZd%e$de=fduZ ejA        dvej        ej        z            Z ejA        dw          Z ejA        dx          Zd%e$de$fdyZ ejA        dzej                   ejA        d{ej                   ejA        d|ej                   ejA        d}ej                   ejA        d~ej                   ejA        dej                   ejA        dej                   ejA        dej                  fZd%e$de=fdZd%e$de$dz  fdZde=de=deKfdZd*ee$         dede$de$fdZ	 	 	 	 	 	 	 	 	 dd%e$de=daee&         dNee$         dee$         de=d*ee$         de=de=deee$                  de$fdZde=fdZedk    r\ ed            ed            e}            Z ed            eded&                      eded                      eded                      ededZ                      ededa          d            ededg          d            e            s ed            eej        d            ed            ed            ed            ed            ed            ed            ed            ed            ed            ed           dZ ed ej        dd           d            ed ej        de                       ed ej        dde                        ed ej        de                       ed ej        de                       ed ej        d ew                                  ddlmZ  ed ej        d e             d                       ed ej        dd                       ed ej        dd¦                      ddlmZ defddddȜddd$d˜dde' de' dΝddϜdddȜddd$d˜ddd$d˜dddidd֜dלd%gd؜dٜZdڄ Z ej        ddeeeddܬݦ           dS )a7  
Terminal Tool Module

A terminal tool that executes commands in local, Docker, Modal, SSH,
Singularity, and Daytona environments. Supports local execution,
containerized backends, and cloud sandboxes, including managed Modal mode.

Supported environments:
- "local": Execute directly on the host machine (default, fastest)
- "docker": Execute in Docker containers (isolated, requires Docker)
- "modal": Execute in Modal cloud sandboxes (direct Modal or managed gateway)

Features:
- Multiple execution backends (local, docker, modal)
- Background task support
- VM/container lifecycle management
- Automatic cleanup after inactivity

Cloud sandbox note:
- Persistent filesystems preserve working state across sandbox recreation
- Persistent filesystems do NOT guarantee the same live sandbox or long-running processes survive cleanup, idle reaping, or Hermes exit

Usage:
    from terminal_tool import terminal_tool

    # Execute a simple command
    result = terminal_tool("ls -la")

    # Execute in background
    result = terminal_tool("python server.py", background=True)
    N)Path)OptionalDictAnyList)env_var_enabled)is_interrupted_interrupt_event)_get_scratch_dir)coerce_modal_modehas_direct_modal_credentialsmanaged_nous_tools_enabled%nous_tool_gateway_unavailable_messageresolve_modal_backend_statenamedefault
type_labelc                     t          j        |           }||dk    r|S 	  ||          S # t          t          f$ r# t                              d| |||           |cY S w xY w)zParse module-level numeric env vars without breaking import.

    Terminal tool is imported by CLI, ACP, tests, and tool discovery. A single
    malformed env var must not make the whole module unloadable at import time.
    N z;Invalid value for %s: %r (expected %s). Falling back to %r.)osgetenv	TypeError
ValueErrorloggerwarningr   r   	converterr   raws        9/home/rurouni/.hermes/hermes-agent/tools/terminal_tool.py_safe_parse_import_envr    O   s     )D//C
{cRii
y~~z"   I	
 	
 	
 s   
+ 1AATERMINAL_MAX_FOREGROUND_TIMEOUTiX  integerTERMINAL_DISK_WARNING_GBg     @@numberc                  d   	 t                      } d}ddl}|                    t          | dz                      D ]}t          |                              d          D ]g}|                                rQ	 ||                                j        z  }4# t          $ r&}t          
                    d||           Y d}~_d}~ww xY wh|dz  }|t          k    r#t                              d|t                     dS d	S # t          $ r(}t          
                    d
|d           Y d}~d	S d}~ww xY w)z4Check if total disk usage exceeds warning threshold.r   Nhermes-**zCould not stat file %s: %si   @z\Disk usage (%.1fGB) exceeds threshold (%.0fGB). Consider running cleanup_all_environments().TFz#Disk usage warning check failed: %sexc_info)r   globstrr   rglobis_filestatst_sizeOSErrorr   debugDISK_USAGE_WARNING_THRESHOLD_GBr   	Exception)scratch_dirtotal_bytesr*   pathfetotal_gbs          r   _check_disk_usage_warningr:   {   s}   &(( IIc+
":;;<< 	I 	ID$ZZ%%c** I I99;; II#qvvxx'77" I I I%A1aHHHHHHHHIII ),555NNy#%DF F F4u   :AMMMuuuuusB   A3C= 6BC= 
CB>9C= >C6C= =
D/D**D/_sudo_password_cachec                  .    t          t          dd           S )Nsudo_passwordgetattr_callback_tls     r   _get_sudo_password_callbackrC      s    =/4888rB   c                  .    t          t          dd           S )Napprovalr>   rA   rB   r   _get_approval_callbackrF      s    =*d333rB   c                     | t           _        dS )u   Register a callback for sudo password prompts (used by CLI).

    Per-thread scope — ACP sessions that run concurrently in a
    ThreadPoolExecutor each have their own callback slot.
    N)r@   r=   cbs    r   set_sudo_password_callbackrJ      s     #%MrB   c                     | t           _        dS )u   Register a callback for dangerous command approval prompts.

    Per-thread scope — ACP sessions that run concurrently in a
    ThreadPoolExecutor each have their own callback slot. See
    GHSA-qg5c-hvr5-hjgr.
    N)r@   rE   rH   s    r   set_approval_callbackrL      s      MrB   returnc                     	 ddl m}   | dd          }n%# t          $ r t          j        dd          }Y nw xY w|rd| S t                      }|Zt          |dd          }t          |dd          }|$|"d	t          |           d
t          |           S dt          |           S dt          j	                     S )z6Return the cache scope for interactive sudo passwords.r   )get_session_envHERMES_SESSION_KEYr   zsession:N__self____func__zcallback-owner::z	callback:zthread:)
gateway.session_contextrO   r3   r   r   rC   r?   id	threading	get_ident)rO   session_keycallbackownerfuncs        r   _get_sudo_password_cache_scoper\      s    :;;;;;;%o&:B?? : : :i 4b99: ('+'''*,,H*d33xT22!1;RYY;;D;;;)2h<<))),Y(**,,,s    77c                      t                      } t          5  t                              | d          cddd           S # 1 swxY w Y   dS )z6Return the cached sudo password for the current scope.r   N)r\   _sudo_password_cache_lockr;   get)scopes    r   _get_cached_sudo_passwordra      s    *,,E	" 3 3#''r223 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3s   >AApasswordc                     t                      }t          5  | r| t          |<   nt                              |d           ddd           dS # 1 swxY w Y   dS )z.Persist a sudo password for the current scope.N)r\   r^   r;   pop)rb   r`   s     r   _set_cached_sudo_passwordre      s    *,,E	" 2 2 	2*2 '' $$UD111	2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2s   )AAAc                  x    t           5  t                                           ddd           dS # 1 swxY w Y   dS )z`Clear all cached sudo passwords.

    Internal helper for tests and process teardown paths.
    N)r^   r;   clearrA   rB   r   _reset_cached_sudo_passwordsrh      s    
 
# % %""$$$% % % % % % % % % % % % % % % % % %s   /33)check_all_command_guardsvolume_specc                     t          | t                    sdS |                                 }t          |          o=|                    d          p(t          |          dk    o|d         dk    o	|d         dv S )z>Return True when a docker volume spec bind-mounts a host path.F)/~z./z../      rS      )rl   \)
isinstancer+   stripbool
startswithlen)rj   vols     r   _docker_volume_uses_host_pathrx     s{    k3'' u




C99 .// 	D	SQ	B3q6S=	BSV{-BrB   configc                     |                      d          dk    rdS |                      d          r|                      d          rdS t          d |                      dg           D                       S )	zIReturn True when a Docker sandbox exposes host paths through bind mounts.env_typedockerFhost_cwddocker_mount_cwd_to_workspaceTc              3   4   K   | ]}t          |          V  d S N)rx   ).0rw   s     r   	<genexpr>z*_docker_has_host_access.<locals>.<genexpr>  s+      ^^c,S11^^^^^^rB   docker_volumes)r_   any)ry   s    r   _docker_has_host_accessr     sx    zz*))uzz* &**-L"M"M t^^VZZHXZ\=]=]^^^^^^rB   Fcommandr{   has_host_accessc                 @    t          | |t                      |          S )zJDelegate to consolidated guard (tirith + dangerous cmd) with CLI callback.)approval_callbackr   )_check_all_guards_implrF   )r   r{   r   s      r   _check_all_guardsr     s/     "'84J4L4L2AC C C CrB   z^[A-Za-z0-9/\\:_\-.~ +@=,]+$workdirc                     | sdS t                               |           s6| D ]1}t                               |          sdt          |           dc S 2dS dS )zReject workdir values that don't look like a filesystem path.

    Uses an allowlist of safe characters rather than a deny-list, so novel
    shell metacharacters can't slip through.

    Returns None if safe, or an error message string if dangerous.
    Nz/Blocked: workdir contains disallowed character z<. Use a simple filesystem path without shell metacharacters.z0Blocked: workdir contains disallowed characters.)_WORKDIR_SAFE_REmatchrepr)r   chs     r   _validate_workdirr   (  s      t!!'** B 	 	B#))"-- Qd2hh Q Q Q  
 BA4rB   outputc                 x    t          d          }|s| S g d}|D ]}|| v rddlm} | d |             dz   c S  | S )z
    Check for sudo failure and add helpful message for messaging contexts.
    
    Returns enhanced output if sudo failed in messaging context, else original.
    HERMES_GATEWAY_SESSION)zsudo: a password is requiredzsudo: no tty presentzsudo: a terminal is requiredr   display_hermes_homeu@   

💡 Tip: To enable sudo over messaging, add SUDO_PASSWORD to z/.env on the agent machine.)r   hermes_constantsr   )r   r{   
is_gatewaysudo_failuresfailure_dhhs         r   _handle_sudo_failurer   >  s     !!9::J   M ! E EfDDDDDD  Eaeaeagag  E  E  E  E  E  E  E  MrB   )zsudo: authentication failedz sudo: incorrect password attemptz1sudo: maximum 3 incorrect authentication attemptsz#sudo: 3 incorrect password attemptsc                 t    | sdS |                                  t          fdt          D                       S )z0Return True when sudo rejected a piped password.Fc              3       K   | ]}|v V  	d S r   rA   )r   markerlowereds     r   r   z/_sudo_wrong_password_failure.<locals>.<genexpr>f  s(      LLVv LLLLLLrB   )lowerr   _SUDO_WRONG_PASSWORD_MARKERS)r   r   s    @r   _sudo_wrong_password_failurer   a  sA     ullnnGLLLL/KLLLLLLrB   c                     dt           j        v rdS t          |          sdS t          | pd          dk    rdS t	                      sdS t          d           dS )u   Drop a session-cached sudo password after sudo rejects it.

    Env-configured ``SUDO_PASSWORD`` is left alone — that is an explicit
    operator choice, not an interactive cache entry.
    SUDO_PASSWORDFr   r   T)r   environr   _count_real_sudo_invocationsra   re   )r   r   s     r   '_invalidate_cached_sudo_on_auth_failurer   i  sm     "*$$u'// u#GMr22a77u$&& ub!!!4rB   -   timeout_secondsc                 F   ddl }t                      }|	  |            pdS # t          $ r Y dS w xY wdddfd}	 dt          j        d<   t          j        d	           t                       t          d
           t          d           t          d           t          d           t          d           t          d|  ddz   dz              t          d           t                       t          ddd           t          j	        |d          }|
                                 |                    |            d         r~d         pd}t                       |rt          d           nt          d           t                       |j                                         |dt          j        v rt          j        d= S S t          d           t          d           t                       |j                                         	 dt          j        v rt          j        d= dS dS # t          t          f$ re t                       t          d           t                       |j                                         Y dt          j        v rt          j        d= dS dS t          $ rT}t          d | d!           |j                                         Y d}~dt          j        v rt          j        d= dS dS d}~ww xY w# dt          j        v rt          j        d= w xY w)"a  
    Prompt user for sudo password with timeout.
    
    Returns the password if entered, or empty string if:
    - User presses Enter without input (skip)
    - Timeout expires (45s default)
    - Any error occurs
    
    Only works in interactive mode (HERMES_INTERACTIVE=1).
    If a _sudo_password_callback is registered (by the CLI), delegates to it
    so the prompt integrates with prompt_toolkit's UI.  Otherwise reads
    directly from /dev/tty with echo disabled.
    r   Nr   F)rb   donec                     d} d}	 t          j                    dk    r\ddl}g }	 |                                }|dv rn#|dk    rt          |                    |           <d                    |          
d<   nddl}t          j	        d	t          j
                  } |                    |           }|                    |           }|d
         |j         z  |d
<   |                    | |j        |           g }	 t          j        | d          }|r|dv rn|                    |           2d                    |                              dd          
d<   n2# t"          t          t$          f$ r d
d<   Y nt&          $ r d
d<   Y nw xY w| V|T	 ddl}|                    | |j        |           n2# t&          $ r%}	t(                              d|	           Y d}	~	nd}	~	ww xY w| H	 t          j        |            n2# t&          $ r%}	t(                              d|	           Y d}	~	nd}	~	ww xY wd
d<   dS # | V|T	 ddl}|                    | |j        |           n2# t&          $ r%}	t(                              d|	           Y d}	~	nd}	~	ww xY w| H	 t          j        |            n2# t&          $ r%}	t(                              d|	           Y d}	~	nd}	~	ww xY wd
d<   w xY w)zKRead password with echo disabled. Uses msvcrt on Windows, /dev/tty on Unix.NWindowsr   T>   
r   rb   z/dev/ttyrn   ro   >      
   rB   zutf-8replace)errorsz)Failed to restore terminal attributes: %szFailed to close tty fd: %sr   )platformsystemmsvcrtgetwchKeyboardInterruptappendjointermiosr   openO_RDONLY	tcgetattrECHO	tcsetattr	TCSAFLUSHreaddecodeEOFErrorr0   r3   r   r1   close)tty_fd	old_attrsr   charscr   	new_attrsb_termiosr8   results             r   read_password_threadz7_prompt_for_sudo_password.<locals>.read_password_thread  s   	*	"  I--$AL((F{{//LLOOO$ &(WWU^^z""R[99#--f55	#--f55	(|w|m;	!!!&'*;YGGG$**A ^ 3 3LLOOO	$
 &)XXe__%;%;GI%;%V%Vz"+W5 	$ 	$ 	$!#F: 	$ 	$ 	$!#F:	$ !i&;Q....&&vx/A9MMMM  Q Q QLL!LaPPPPPPPPQ!BHV$$$$  B B BLL!=qAAAAAAAAB!F6NNN !i&;Q....&&vx/A9MMMM  Q Q QLL!LaPPPPPPPPQ!BHV$$$$  B B BLL!=qAAAAAAAAB!F6N!!!!s   EE H5 F	6H5 8F	H5 F		H5  F2 2
G!<GG!'G< <
H+H&&H+5K; IK
J&JKJKJ&%K&
K0KKK	K1HERMES_SPINNER_PAUSEg?u   ┌──────────────────────────────────────────────────────────┐uA   │  🔐 SUDO PASSWORD REQUIRED                              │u   ├──────────────────────────────────────────────────────────┤u?   │  Enter password below (input is hidden), or:            │uA   │    • Press Enter to skip (command fails gracefully)     │u   │    • Wait zs to auto-skipz                           u   │u   └──────────────────────────────────────────────────────────┘z  Password (hidden): T)endflushtargetdaemontimeoutr   rb   u1     ✓ Password received (cached for this session)u'     ⏭ Skipped - continuing without sudou(   
  ⏱ Timeout - continuing without sudoz    (Press Enter to dismiss)u)     ⏭ Cancelled - continuing without sudoz
  [sudo prompt error: z] - continuing without sudo
)sysrC   r3   r   r   timesleepprintrV   Threadstartr   stdoutr   r   r   )r   r   _sudo_cbr   password_threadrb   r8   r   s          @r   _prompt_for_sudo_passwordr   }  s    JJJ +,,H	8::## 	 	 	22	 ..F." ." ." ." ."`03-0
)*
3()))CDDD()))OPPPQRRR@@@@8KeSTTT()))%2T::::#*2FtTTT_555&> 	j)/RHGGG AIJJJJ?@@@GGGJ& "RZ//
122 0# =>>>0111GGGJ "RZ//
1222 0/ '(   9:::
 "RZ//
1222 0/    IIIIJJJ
rrr!RZ//
1222 0/
 "RZ//
122222sJ   # 
11E-H. 	AH. .AL L #	L ,,K;L ;L  L L    limitc                     | dS t          | t                    r
| d|         S 	 t          |           d|         S # t          $ r dt	          |           j         dcY S w xY w)z>Return a log-safe preview for possibly-invalid command values.Nz<None><>)rr   r+   r   r3   type__name__)r   r   s     r   _safe_command_previewr     s    x'3 vv-G}}VeV$$ - - -,4==),,,,,,-s   < "A! A!tokenc                     d| vs|                      d          rdS |                     dd          \  }}t          t          j        d|                    S )zCReturn True when *token* is a leading shell environment assignment.=Fro   z^[A-Za-z_][A-Za-z0-9_]*$)ru   splitrt   rer   )r   r   _values      r   _looks_like_env_assignmentr     sW    
%5++C00u;;sA&&LD&4d;;<<<rB   r   c                    |}t          |           }||k     r| |         }|                                s|dv rn|dk    r:|dz  }||k     r#| |         dk    r|dz  }||k     r| |         dk    ||k     r|dz  }g|dk    r@|dz  }||k     r4| |         }|dk    r|dz   |k     r|dz  }#|dk    r|dz  }n|dz  }||k     4|dk    r|dz   |k     r|dz  }|dz  }||k     | ||         |fS )zERead one shell token, preserving quotes/escapes, starting at *start*.z;|&()'ro   "rq   rp   )rv   isspace)r   r   inr   inners         r   _read_shell_tokenr     s]   AGA
a%%QZ::<< 	2==99FAa%%GAJ#--Q a%%GAJ#--1uuQ99FAa%%
D==QUQYYFAC<<FAQ a%% ::!a%!))FA	Q5 a%%8 57QrB   c                    g }d}t          |           }d}d}||k     r| |         }|                                r#|                    |           |dk    rd}|dz  }F|dk    r]|r[|                     d|          }|dk    r|                    | |d                    n;|                    | ||                    |}|                     d|          s,|                     d	|          s|                     d
|          r)|                    | ||dz                       |dz  }d}|dv r|                    |           |dz  }d}6|dk    r|                    |           |dz  }d}Zt          | |          \  }}	|r!|dk    r|                    d           |dz  }n|                    |           |rt          |          rd}nd}|	}||k     d                    |          |fS )zRewrite only real unquoted sudo command words, not plain text mentions.

    Returns the rewritten command and the number of sudo invocations rewritten.
    r   Tr   ro   #N&&||;;rp   ;|&()Fsudozsudo -S -p ''r   )rv   r   r   findru   r   r   r   )
r   outr   r   command_start
sudo_countr   comment_endr   next_is
             r   _rewrite_real_sudo_invocationsr  0  sB   
 C	AGAMJ
a%%QZ::<< 	JJrNNNTzz $FA999!,,tQ//Kb  

7122;'''JJwq}-...AdA&& 	'*<*<T1*E*E 	I[I[\`bcIdId 	JJwqQw'(((FA M<<JJrNNNFA M99JJrNNNFA!M)'155v 	Uf__JJ'''!OJJJJu 	"7>> 	" MM!Ma a%%d 773<<##rB   c                 $   d}d}t          |           }d}||k     r| |         }|                                r|dk    rd}|dz  }0|dk    r"|r |                     d|          }|dk    rn|}X|                     d|          s,|                     d|          s|                     d	|          r|d
z  }d}|dv r|dz  }d}|dk    r|dz  }d}t	          | |          \  }}|r|dk    r|dz  }|rt          |          rd}nd}|}||k     |S )zReturn how many real sudo command words appear in *command*.

    Lightweight scan that reuses the same tokeniser as
    ``_rewrite_real_sudo_invocations`` but skips the string-building, so it
    is cheap to call from the result-processing path.
    r   Tr   ro   r   r   r   r   r  rp   r  r  Fr  )rv   r   r  ru   r   r   )	r   countr   r   r  r   r	  r   r
  s	            r   r   r   p  s    E	AGAM
a%%QZ::<< 	Tzz $FA999!,,tQ//Kb  AdA&& 	'*<*<T1*E*E 	I[I[\`bcIdId 	FA M<<FA M99FA!M)'155v 	Uf__QJE 	"7>> 	" MM!MO a%%R LrB   c                  6   t          j        dd                                                                          pd} | dk    rdS 	 t	          j        g dt          j        t          j        t          j        dd          }|j        dk    S # t          $ r Y dS w xY w)aN  Return True when local sudo currently works without prompting.

    Only probes for the `local` terminal backend; Docker/SSH/Modal/etc. must
    not inherit the host's sudo state. Re-probes every call (no process-level
    cache) so an expired sudo timestamp cannot make a later command silently
    block waiting for a password.
    TERMINAL_ENVlocalF)r  z-ntruern   )stdinr   stderrr   checkr   )	r   r   rs   r   
subprocessrunDEVNULL
returncoder3   )terminal_envprobes     r   _sudo_nopasswd_worksr    s     9^W55;;==CCEEPLwu"""$%%
 
 
 1$$   uus   AB
 

BBc                 T   t          |           }d}d}d}d}g }||k     rv| |         }|dk    r|dk    r|dk    rd}|dz  })|                                r|dz  }C|dk    r!|                     d|          }|dk    rn|}j|dk    r|dz   |k     r|dz  }|dv r't          | |          \  }	}
t	          |
|dz             }|d	k    r|dz  }|dz  }|d
k    rt	          d|dz
            }|dz  }|dk    rA|dz   |k     r8| |dz                                            s| |dz            dk    r|dz  }|dz  }!|dk    r|dk    r|dz  }d}|dz  };|dk    s|dk    r|dz  }N|                     d|          s|                     d|          r|dz   }|dz  }|dk    r	d}|dz  }|dk    r	d}|dz  }|dk    r|dz   |k     r| |dz            dk    r|dz  }|dz
  }|dk    r?| |                                         r%|dz  }|dk    r| |                                         %|dk    r| |         dv r|dz  }*|dk    r|                    ||f           d}|dz  }Pt          | |          \  }	}
t	          |
|dz             }||k     v|s| S | }t          |          D ]{\  }}|}||k     r?||                                         r%|dz  }||k     r||                                         %|d|         }|||         }||dz   d         }|dz   |z   dz   |z   }||S )u  Wrap `A && B &` (or `A || B &`) to `A && { B & }` at depth 0.

    Bash parses ``A && B &`` with `&&` tighter than `&`, so it forks a
    subshell for the whole `A && B` compound and backgrounds it. Inside
    the subshell, `B` runs foreground, so the subshell waits for `B` to
    finish. When `B` is a long-running process (`python3 -m http.server`,
    `yes > /dev/null`, anything that doesn't naturally exit), the subshell
    never exits. It leaks as a process stuck in ``wait4`` forever — and
    on the way, its open stdout pipe can prevent the terminal tool from
    returning promptly.

    Rewriting the tail to `A && { B & }` preserves `&&`'s error semantics
    (skip B if A fails) while replacing the subshell with a brace group.
    The brace group runs in the current shell (no fork), backgrounds B as
    a simple command (bash doesn't wait for it in non-interactive mode),
    and exits immediately. B runs as a normal backgrounded child, orphaned
    when the parent shell exits.

    Handles redirects (``&>``, ``2>&1``) and skips content inside quoted
    strings and parenthesised subshells. Leaves simple ``cmd &`` alone —
    that construct doesn't have the subshell-wait bug.
    r   r   r   ro   r   rq   rp   >   r   r   (r  {}r   r   ;|&r   z<>Nz{ z& })rv   r   r  r   maxru   r   reversed)r   r   r   paren_depthbrace_depthlast_chain_op_endrewritesr   nl_r
  jr   	chain_endamp_pos
insert_posprefixmiddlesuffixs                      r   _rewrite_compound_backgroundr2    sg   . 	GA	AKK &(H
a%%QZ ::+**{a/?/? "FA::<< 	FA
 99dA&&BRxxA::!a%!))FA )'155IAvFAE""A991KFA99aq11KFA 99QA(>(>(@(@GAPQENVZDZDZ1KFA99q1K "FA
 ??kAooFA dA&& 	'*<*<T1*E*E 	 !AFA 99 "FA 99 "FA 991uqyyWQU^s22QAAq&&WQZ//11&Q q&&WQZ//11&Avv'!*,,Q A%%!2A 6777 "FA &gq11	6A] a%%`   F&x00 9 9	7 
7""vj'9'A'A'C'C"!OJ 7""vj'9'A'A'C'C"$
7*+!& $'%/&8MrB   c                    | dS t          |           \  }}|dk    r| dfS dt          j        v }|r t          j                            dd          nt	                      }|s|st                      r| dfS t                      du}t          d          p|}|s%|s#|r!t          d          }|rt          |           |s|r|d	z   }|||z  fS | dfS )
a  
    Transform sudo commands to use -S flag if SUDO_PASSWORD is available.

    This is a shared helper used by all execution environments to provide
    consistent sudo handling across local, SSH, and container environments.

    Returns:
        (transformed_command, sudo_stdin) where:
        - transformed_command has every bare ``sudo`` replaced with
          ``sudo -S -p ''`` so sudo reads its password from stdin.
        - sudo_stdin is the password string with a trailing newline that the
          caller must prepend to the process's stdin stream.  sudo -S reads
          exactly one line (the password) and passes the rest of stdin to the
          child command, so prepending is safe even when the caller also has
          its own stdin_data to pipe.
        - If no password is available, sudo_stdin is None and the command is
          returned unchanged so it fails gracefully with
          "sudo: a password is required".

    Callers that drive a subprocess directly (local, ssh, docker, singularity)
    should prepend sudo_stdin to their stdin_data and pass the merged bytes to
    Popen's stdin pipe.

    Callers that cannot pipe subprocess stdin (modal, daytona) must embed
    the password in the command string themselves; see their execute()
    methods for how they handle the non-None sudo_stdin case.

    If SUDO_PASSWORD is not set and an interactive UI is available
    (HERMES_INTERACTIVE=1 or a registered sudo password callback):
      Prompts user for password with 45s timeout, caches for session.

    If SUDO_PASSWORD is not set and NOT interactive:
      Command runs as-is (fails gracefully with "sudo: a password is required").
    N)NNr   r   r   HERMES_INTERACTIVEr   )r   r   )
r  r   r   r_   ra   r  rC   r   r   re   )r   transformedr  has_configured_passwordr=   has_sudo_prompt_callbackshould_prompt_for_sudopassword_lines           r   _transform_sudo_commandr:  g  s3   F z<WEEKQ}-; #	)
+++&((  # = =Q=S=S }:<<DH,--I1I  # 5= 5=S 51"EEE 	5%m444 7- 7 &,MJ666D=rB   )LocalEnvironment)SingularityEnvironment)SSHEnvironment)DockerEnvironment)ModalEnvironment)ManagedModalEnvironment)is_managed_tool_gateway_readyu(	  Execute shell commands on a Linux environment. Filesystem, current working directory, and exported environment variables persist between calls.

Do NOT use cat/head/tail to read files — use read_file instead.
Do NOT use grep/rg/find to search — use search_files instead.
Do NOT use ls to list directories — use search_files(target='files') instead.
Do NOT use sed/awk to edit files — use patch instead.
Do NOT use echo/cat heredoc to create files — use write_file instead.
Reserve terminal for: builds, installs, git, processes, scripts, network, package managers, and anything that needs a shell.
Because exported environment state persists, activate a virtualenv or export setup variables once per session; do not re-source the same environment before every command unless a command proves the shell state was reset.

Foreground (default): Commands return INSTANTLY when done, even if the timeout is high. Set timeout=300 for long builds/scripts — you'll still get the result in seconds if it's fast. Prefer foreground for short commands.
Background: Set background=true to get a session_id. Almost always pair with notify_on_complete=true — bg without notify runs SILENTLY and you have no way to learn it finished short of calling process(action='poll') yourself. Two legitimate uses:
  (1) Long-lived processes that never exit (servers, watchers, daemons) — silent is correct, there's no exit to notify on.
  (2) Long-running bounded tasks (tests, builds, deploys, CI pollers, batch jobs) — MUST set notify_on_complete=true. Without it you'll either forget to poll or sit blocked waiting for the user to surface the result.
For servers/watchers, do NOT use shell-level background wrappers (nohup/disown/setsid/trailing '&') in foreground mode. Use background=true so Hermes can track lifecycle and output.
After starting a server, verify readiness with a health check or log signal, then run tests in a separate terminal() call. Avoid blind sleep loops.
Use process(action="poll") for progress checks, process(action="wait") to block until done.
Working directory: Use 'workdir' for per-command cwd.
PTY mode: Set pty=true for interactive CLI tools (Codex, Claude Code, Python REPL).

Do NOT use vim/nano/interactive tools without pty=true — they hang without a pseudo-terminal. Pipe git output to cat if it might page.
_active_environments_last_activity_creation_lockscontainer_configc                 d   |                      dd          sdS t          rdS t          5  t          r	 ddd           dS daddd           n# 1 swxY w Y   	 t          t	          j        dd                    }n# t          t          f$ r d}Y nw xY wt          d|          }|dz  }	 d	d
l	m
}m} n# t          $ r Y dS w xY w	  |            } |||          }|rt                              d||           dS dS # t          $ r&}t                              d|           Y d}~dS d}~ww xY w)uo  Run the docker orphan reaper once per process, if enabled.

    Sweeps long-Exited containers labeled ``hermes-agent=1`` for the current
    profile that match the issue #20561 leak class — containers left behind
    by Hermes processes that exited without firing ``atexit`` (SIGKILL,
    OOM, terminal-window-close). The reaper is conservative by default:
    only Exited containers older than ``2 × lifetime_seconds`` and scoped to
    the current profile.

    Gates:

    * ``terminal.docker_orphan_reaper: false`` disables it entirely (the
      operator opted out — usually because they're running multiple
      Hermes processes in the same profile and don't trust the
      conservative defaults).
    * ``_docker_orphan_reaper_ran`` flag — sweep runs once per Python
      interpreter, not on every subagent / RL-rollout / parallel
      ``terminal()`` call.
    docker_orphan_reaperTNTERMINAL_LIFETIME_SECONDS300,  <   rp   r   )reap_orphan_containers_get_active_profile_name)max_age_secondsprofile_filterzADocker orphan reaper removed %d stale container(s) for profile %szDocker orphan reaper raised: %s)r_   _docker_orphan_reaper_ran_docker_orphan_reaper_lockintr   r   r   r   r#  tools.environments.dockerrL  rM  ImportErrorr   infor3   r1   )rE  lifetimemax_agerL  rM  profileremovedr8   s           r   _maybe_reap_docker_orphansrZ    s2   *  6==  ! 	# ) )$ 	) ) ) ) ) ) ) ) %)!) ) ) ) ) ) ) ) ) ) ) ) ) ) )ry!<eDDEEz"   2x  HlG	
 	
 	
 	
 	
 	
 	
 	
 	
    ;**,,((#G
 
 
  	KKS    	 	
  ; ; ;6:::::::::;sR   	AAAA"A< <BB+B4 4
CC5C? ?
D/	D**D/_task_env_overridestask_id	overridesc                    |t           | <   |                    d          }t          |t                    r|                                rt          |           }t          5  t                              |           pt                              |          }ddd           n# 1 swxY w Y   |t          |dd          ||_	        dS dS dS dS dS )a#  
    Register environment overrides for a specific task/rollout.

    Called by Atropos environments before the agent loop to configure
    per-task sandbox settings (e.g., a custom Dockerfile for the Modal image).

    Supported override keys:
        - modal_image: str -- Path to Dockerfile or Docker Hub image name
        - docker_image: str -- Docker image name
        - cwd: str -- Working directory inside the sandbox

    Args:
        task_id: The rollout's unique task identifier
        overrides: Dict of config keys to override
    cwdN)
r[  r_   rr   r+   rs   _resolve_container_task_id	_env_lockrB  r?   r_  )r\  r]  new_cwdcontainer_idenvs        r   register_task_env_overridesre  1  s(     $-  mmE""G'3 
GMMOO 
 2':: 	^ 	^&**733]7K7O7OP\7]7]C	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^ 	^?wsE488DCGGG
 
 
 
 ?DDs   5B  B$'B$c                 <    t                               | d           dS )z
    Clear environment overrides for a task after rollout completes.

    Called during cleanup to avoid stale entries accumulating.
    N)r[  rd   )r\  s    r   clear_task_env_overridesrg  Z  s      GT*****rB   c                     t          h d          }| r<| t          v r3t          |          }t          |                                          |z  r| S dS )u  
    Map a tool-call ``task_id`` to the container/sandbox key used by
    ``_active_environments``.

    The top-level agent passes ``task_id=None`` and lands on ``"default"``.
    ``delegate_task`` children pass their own subagent ID so that
    file-state tracking, the active-subagents registry, and TUI events stay
    distinct per child -- but we deliberately collapse that ID back to
    ``"default"`` here so subagents share the parent's long-lived container
    (one bash, one /workspace, one set of installed packages).

    Exception: RL / benchmark environments (TerminalBench2, HermesSweEnv, ...)
    call ``register_task_env_overrides(task_id, {...})`` to request a
    per-task Docker/Modal image. When an override is registered for a
    task_id, we honour it by returning the task_id unchanged -- those
    rollouts need their own isolated sandbox, which is the whole point of
    the override.

    CWD-only overrides (registered by the ACP adapter for workspace
    tracking) are *not* isolation signals — they should not cause each
    session to spin up its own container.  Only overrides containing
    backend-specific image keys or ``env_type`` trigger isolation.
    >   r{   modal_imagedocker_imagedaytona_imagesingularity_imager   )	frozensetr[  setkeys)r\  _ISOLATION_KEYSr]  s      r   r`  r`  c  sj    0   ! ! !  O  7111'0	y~~  ?2 	N9rB   c                     | pd}t                               |          p(t                               t          |                    pi S )a  Return the env overrides for *task_id*, raw key first then collapsed.

    ``register_task_env_overrides`` writes under the *raw* task/session id, but
    a CWD-only override collapses (:func:`_resolve_container_task_id`) to the
    shared ``"default"`` container so per-session surfaces (ACP/gateway/
    dashboard) don't each spin up their own sandbox. Callers that need the
    override (terminal command setup, file-tool cwd resolution) must therefore
    read the raw id FIRST and only fall back to the collapsed container id, or
    the originating session's override is silently dropped. This is the single
    source of that lookup so the terminal and file layers can't drift apart.
    r   )r[  r_   r`  )r\  r   s     r   resolve_task_overridesrr    sK     
YC$$ 	""#=c#B#BCC	rB   r   c           
          t          j        | |          }	  ||          S # t          t          j        f$ r t          d|  d|d| d          w xY w)zParse an environment variable with *converter*, raising a clear error on bad values.

    Without this wrapper, a single malformed env var (e.g. TERMINAL_TIMEOUT=5m)
    causes an unhandled ValueError that kills every terminal command.
    zInvalid value for : z (expected z1). Check ~/.hermes/.env or environment variables.)r   r   r   jsonJSONDecodeErrorr   s        r   _parse_env_varrw    s     )D'
"
"C
y~~,- 
 
 
> > > > >: > > >
 
 	

s	   
" 0Ac                      	 t          j                    S # t          $ r6 t          j        d          pt           j                            d          cY S w xY w)am  Return the current working directory, tolerating a deleted CWD.

    ``os.getcwd()`` raises FileNotFoundError when the process's working
    directory has been removed out from under it (e.g. a scratch workspace
    that was cleaned up mid-session). Fall back to TERMINAL_CWD, then the
    user's home directory, so terminal setup never crashes on a stale CWD.
    TERMINAL_CWDrm   )r   getcwdFileNotFoundErrorr   r6   
expanduserrA   rB   r   _safe_getcwdr}    s^    Dy{{ D D Dy((CBG,>,>s,C,CCCCDs    =AA)z/Users/z/home/zC:\zC:/>   modalr|   daytonasingularitybackendr_  c                     | pd                                                                 dk    rdS |dk    p|                    d          S )aI  Return True when *cwd* is a tilde path that the remote SSH shell must
    expand itself, so the Hermes host/container must NOT ``expanduser`` it.

    SSH ``cwd`` is interpreted by the *remote* shell (``cd ~`` / ``cd ~/x``
    over ``ssh ... bash -c``). Expanding ``~`` locally would rewrite it to the
    Hermes host HOME (often ``/opt/data`` under Docker) and inject a
    nonexistent path into the remote session. Only ``~`` / ``~/...`` on the
    ``ssh`` backend qualify; absolute remote paths still pass through
    unchanged, and every other backend keeps expanding locally.
    r   sshFrm   z~/)rs   r   ru   )r  r_  s     r   _is_ssh_remote_tilde_cwdr    sK     	2$$&&%//u#:----rB   c                       sdS t           fdt          D                       rdS t          j                                       sdS dS )a  Return True if *cwd* is a host/relative path that won't work as the
    working directory inside a container sandbox.

    A container's cwd must be an absolute path that exists *inside* the
    sandbox (e.g. ``/workspace`` or ``/root``). A host path (``/home/user``,
    ``C:\Users\me``) or a relative path (``.``, ``src/``) is meaningless to
    ``docker run -w`` and makes the container fail to start (exit 125).
    Fc              3   B   K   | ]}                     |          V  d S r   ru   )r   pr_  s     r   r   z-_is_unusable_container_cwd.<locals>.<genexpr>  s/      
9
93>>!
9
9
9
9
9
9rB   T)r   _HOST_CWD_PREFIXESr   r6   isabs)r_  s   `r   _is_unusable_container_cwdr    s_      u

9
9
9
9&8
9
9
999 t 7== t5rB   c                  	   d} t          j        dd          }t          j        dd                                          dv }|dv }|dk    }|r8t          d	d
t          d          }t          dd          }t          dd          }nd}d}d}|rqt          ddt
          j        d          }t          ddt
          j        d          }	t          ddt
          j        d          }
t          ddt
          j        d          }ng }g }	i }
g }|dk    rt                      }n|dk    rd}nd}t          j        d|          }|r/t          ||          st           j	        
                    |          }d}|dk    r|rt          j        d          pt                      }t           j	                            t           j	        
                    |                    t          fdt          D                       sSt           j	                                      r8t           j	                                      r                    d           s}d!}n?|t"          v r6|r4t%          |          r%||k    rt&                              d"|||           |}i d#|d$t+          t          j        d%d&                    d't          j        d(|           d)|d*t          j        d+d,|            d-t          j        d.|           d/t          j        d0|           d1|d2|d3|d4t          d5d6          d7t          d8d9          d:t          j        d;d<          d=t          j        d>d<          d?t          d@dA          dBt          j        dCd<          dDt          j        dEt          j        dFdG                                                    dv t          j        dHd                                          dv |||t          j        dIdG                                          dv |	|
t          j        dJd                                          dv t          j        dKdG                                          dv |t          j        dLdG                                          dv t          j        dMdG                                          dv dNS )OzBGet terminal environment configuration from environment variables.*nikolaik/python-nodejs:python3.11-nodejs20r  r  &TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACEfalse>   r   yesr  >   r~  r|   r  r  r|   TERMINAL_CONTAINER_CPUr   r$   TERMINAL_CONTAINER_MEMORY5120TERMINAL_CONTAINER_DISK51200g      ?      TERMINAL_DOCKER_FORWARD_ENVz[]z
valid JSONTERMINAL_DOCKER_VOLUMESTERMINAL_DOCKER_ENVz{}TERMINAL_DOCKER_EXTRA_ARGSr  rm   /rootry  Nc              3   B   K   | ]}                     |          V  d S r   r  )r   r  	candidates     r   r   z"_get_env_config.<locals>.<genexpr>   s1      DDA	$$Q''DDDDDDrB   )
/workspacer  r  zeIgnoring TERMINAL_CWD=%r for %s backend (host/relative path won't work in sandbox). Using %r instead.r{   
modal_modeTERMINAL_MODAL_MODEautorj  TERMINAL_DOCKER_IMAGEdocker_forward_envrl  TERMINAL_SINGULARITY_IMAGE	docker://ri  TERMINAL_MODAL_IMAGErk  TERMINAL_DAYTONA_IMAGEr_  r}   r~   r   TERMINAL_TIMEOUT180lifetime_secondsrH  rI  ssh_hostTERMINAL_SSH_HOSTr   ssh_userTERMINAL_SSH_USERssh_portTERMINAL_SSH_PORT22ssh_keyTERMINAL_SSH_KEYssh_persistentTERMINAL_SSH_PERSISTENTTERMINAL_PERSISTENT_SHELLr  TERMINAL_LOCAL_PERSISTENTTERMINAL_CONTAINER_PERSISTENT TERMINAL_DOCKER_RUN_AS_HOST_USERTERMINAL_DOCKER_NETWORK(TERMINAL_DOCKER_PERSIST_ACROSS_PROCESSESTERMINAL_DOCKER_ORPHAN_REAPER)local_persistentcontainer_cpucontainer_memorycontainer_diskcontainer_persistentr   
docker_envdocker_run_as_host_userdocker_networkdocker_extra_argsdocker_persist_across_processesrG  )r   r   r   rw  floatru  loadsr}  r  r6   r|  abspathr   r  r  isdirru   _CONTAINER_BACKENDSr  r   rU  r   )default_imager{   mount_docker_cwdcontainer_backenddocker_backendr  r  r  r  r   r  r  default_cwdr_  r}   docker_cwd_sourcer  s                   @r   _get_env_configr    sV    AMy11Hy!I7SSYY[[_ss $QQ)N  &'?eXVV)*EvNN'(A7KK 	+,I4QUQ[]ijj'(A4Uabb#$94\ZZ
*+Gtz[ghh

 7"nn	U		 )NK
0
0C
 &+Hc:: &g  %%H8 0In55GGOOBG$6$67H$I$IJJ	DDDD1CDDDDD	i((	-/W]]9-E-E	NWNbNbczN{N{	 !HC	(	(	(S	(%c** 	sk/A/AKK XX{4 4 4 C5H5'	2G(P(PQQ5 		"9=II5 	0	5
 	RY'CE`Q^E`E`aa5 	ry!7GG5 	#;]KK5 	s5 	H5 	()95 	>"4e<<5 	N+FNN5 	BI12665 	BI12665  	N#6==!5" 	29/44#5* 	")%I16::
 
 %'')*+52 I&A7KKQQSSWkk ',( "	*I6 R R X X Z Z^r r( #%9-OQX#Y#Y#_#_#a#aey#y)$=vFFLLNNRff. ,.96,
 ,

%''),* !#	+V!
 !

%'')!*e5 5 5 5rB   r  c                 X    t          | t                      t          d                    S )z2Resolve direct vs managed Modal backend selection.r~  )
has_directmanaged_ready)r   r   rA  )r  s    r   _get_modal_backend_stater  e  s0    &/113G<<   rB   imager   
ssh_configlocal_configr}   c	           
      j   |pi }	|	                     dd          }
|	                     dd          }|	                     dd          }|	                     dd          }|	                     d	g           }|	                     d
g           }|	                     di           }|	                     dg           }|	                     dd          }| dk    rt          ||          S | dk    rt          |	           t          dGi d|d|d|d|
d|d|d|d|d|d|d|	                     dd          d|d|d |	                     d!d          d"|d#|d$|	                     d%d          S | d&k    rt	          ||||
||||'          S | d(k    rXi }|
d)k    r|
|d<   |d)k    r||d<   |d)k    rE	 d)d*l}d)d*l}d+|                    |j        j	                  j
        v r||d+<   n# t          $ r Y nw xY wt          |	                     d,                    }|d-         d.k    rt          ||||||/          S |d-         d0k    r|d1         r"t          d2t          d3          z   d4z             |d5         d.k    rt          d6t          d3          z             |d5         d0k    rt          d7          d8}t!                      rd9}t          |          t#          ||||||/          S | d:k    r&d)d;lm}  ||||t)          |
          ||||'          S | d<k    r|r*|                     d=          r|                     d>          st          d?          t+          |d=         |d>         |                     d@dA          |                     dBdC          ||D          S t          dE|  dF          )Ha  
    Create an execution environment for sandboxed command execution.
    
    Args:
        env_type: One of "local", "docker", "singularity", "modal",
            "daytona", "ssh"
        image: Docker/Singularity/Modal image name (ignored for local/ssh)
        cwd: Working directory
        timeout: Default command timeout
        ssh_config: SSH connection config (for env_type="ssh")
        container_config: Resource config for container backends (cpu, memory, disk, persistent)
        task_id: Task identifier for environment reuse and snapshot keying
        host_cwd: Optional host working directory to bind into Docker when explicitly enabled
        
    Returns:
        Environment instance with execute() method
    r  ro   r  r  r  r  r  Tr   r  r  r  r  r  )r_  r   r|   r  r_  r   cpumemorydiskpersistent_filesystemr\  volumesr}   auto_mount_cwdr~   Fforward_envrd  run_as_host_userr  network
extra_argspersist_across_processesr  r  )r  r_  r   r  r  r  r  r\  r~  r   Nephemeral_diskr  selected_backendmanaged)r  r_  r   modal_sandbox_kwargsr  r\  directmanaged_mode_blockedzModal backend is configured for managed mode, but Nous Tool Gateway access is not currently available and no direct Modal credentials/config were found. managed Modal executionzH Choose TERMINAL_MODAL_MODE=direct/auto to use direct Modal credentials.modez[Modal backend is configured for managed mode, but the managed tool gateway is unavailable. z_Modal backend is configured for direct mode, but no direct Modal credentials/config were found.zHModal backend selected but no direct Modal credentials/config was found.z`Modal backend selected but no direct Modal credentials/config or managed tool gateway was found.r  )DaytonaEnvironmentr  hostuserz?SSH environment requires ssh_host and ssh_user to be configuredport   keyr   )r  r  r  key_pathr_  r   zUnknown environment type: zD. Use 'local', 'docker', 'singularity', 'modal', 'daytona', or 'ssh'rA   )r_   _LocalEnvironmentrZ  _DockerEnvironment_SingularityEnvironmentinspectr~  	signatureSandboxcreate
parametersr3   r  _ManagedModalEnvironmentr   r   r   _ModalEnvironmenttools.environments.daytonar  rR  _SSHEnvironment)r{   r  r_  r   r  rE  r  r\  r}   ccr  r  r  
persistentr  r  r  r  r  sandbox_kwargsr  r~  modal_statemessage_DaytonaEnvironments                            r   _create_environmentr  n  sb   , 
	RB
&&!
$
$CVV&--F66"E**D.55Jff%r**G 4b99b))J2B77VV,d33N7 S'::::	X		 	#2&&&! 
 
 
%
 S
*1'

"F
)-
 #-*
 7>g
 G	

 X
 66"A5III
 +*
 

  VV$=uEEE
 #N
 )(
 &(VV,Mt%T%T%T
 	
 
]	"	"&S'F",g
 
 
 	
 
W		77$'N5!A::'-N8$!88%%%%%%%%#w'8'89M'N'N'YYY7;N#34    /rvvl/C/CDD)*i77+g%3&0'    )*h6612 	 < <1  aa   6"i// q;1    6"h.. u   aG)++ v  W%%% S'!/",g
 
 
 	
 
Y		XXXXXX""S'Cd",g
 
 
 	
 
U		 	`!7!7 	`z~~f?U?U 	`^___F#F#++^^E2..
 
 
 	
 ; ; ; ;
 
 	
s   33G' '
G43G4rJ  r  c                    t          j                     }	 ddlm} t          t                                                    D ]!}|                    |          r
|t          |<   "n# t          $ r Y nw xY wg }t          5  t          t          	                                          D ]]\  }}||z
  | k    rOt                              |d          }t                              |d           ||                    ||f           ^t          5  |D ] \  }}t                              |d           !	 ddd           n# 1 swxY w Y   ddd           n# 1 swxY w Y   |D ]+\  }}	 ddlm}  ||           n# t          $ r Y nw xY w	 t#          |d          r|                                 nIt#          |d          r|                                 n$t#          |d          r|                                 t*                              d|           # t.          $ rl}	t1          |	          }
d	|
v sd
|
                                v rt*                              d|           nt*                              d||	           Y d}	~	%d}	~	ww xY wdS )zOClean up environments that have been inactive for longer than lifetime_seconds.r   process_registryNclear_file_ops_cachecleanupstop	terminatez,Cleaned up inactive environment for task: %s404	not found*Environment for task %s already cleaned up-Error cleaning up environment for task %s: %s)r   tools.process_registryr  listrC  ro  has_active_processesrT  ra  itemsrB  rd   r   _creation_locks_lockrD  tools.file_toolsr  hasattrr  r  r  r   rU  r3   r+   r   r   )r  current_timer  r\  envs_to_stop	last_timerd  r*  r  r8   	error_strs              r   _cleanup_inactive_envsr     sq   9;;L;;;;;;N//1122 	7 	7G44W== 7*6w'	7     L	 3 3"&~';';'='=">"> 	8 	8GYi'*:::*..w==""7D111? ''#777 " 	3 	3* 3 3
##GT22223	3 	3 	3 	3 	3 	3 	3 	3 	3 	3 	3 	3 	3 	3 	33 3 3 3 3 3 3 3 3 3 3 3 3 3 3 % \ \	======  )))) 	 	 	D		\sI&&  f%%  



k**  KKFPPPP 	\ 	\ 	\AI	!![IOO4E4E%E%EH'RRRRNPWYZ[[[	\'\ \su   AA$ $
A10A1=BE	$D:.E:D>	>ED>	EEE%E77
FFB	H
JA!JJc                  6   t           r	 t                      } t          | d                    n4# t          $ r'}t                              d|d           Y d}~nd}~ww xY wt          d          D ]}t           s nt          j        d            t           dS dS )zKBackground thread worker that periodically cleans up inactive environments.r  zError in cleanup thread: %sTr(   NrK  ro   )	_cleanup_runningr  r   r3   r   r   ranger   r   )ry   r8   r*  s      r   _cleanup_thread_workerr$  D  s    
 
	L$&&F"6*<#=>>>> 	L 	L 	LNN8!dNKKKKKKKK	L r 	 	A# JqMMMM  
 
 
 
 
s   #- 
AAAc                      t           5  t          t                                          s6dat	          j        t          d          at                                           ddd           dS # 1 swxY w Y   dS )z;Start the background cleanup thread if not already running.NTr   )ra  _cleanup_threadis_aliver"  rV   r   r$  r   rA   rB   r   _start_cleanup_threadr(  S  s     
 $ $"/*B*B*D*D"#'.6LUYZZZO!!###	$ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $ $s   AA,,A03A0c                      da t          6	 t                              d           dS # t          t          f$ r Y dS w xY wdS )z#Stop the background cleanup thread.FN   r   )r"  r&  r   
SystemExitr   rA   rB   r   _stop_cleanup_threadr,  ^  sb     "	   +++++-. 	 	 	DD	 #"s   ( ==c                     t          |           }t          5  t                              |          pt                              |           cddd           S # 1 swxY w Y   dS )z9Return the active BaseEnvironment for *task_id*, or None.N)r`  ra  rB  r_   )r\  lookups     r   get_active_envr/  i  s    '00F	 U U#''//T3G3K3KG3T3TU U U U U U U U U U U U U U U U U Us   4AAAc                 d    t          |           }|dS t          t          |dd                    S )a  Return True if the active environment for task_id is configured for
    cross-turn persistence (``persistent_filesystem=True``).

    Used by the agent loop to skip per-turn teardown for backends whose whole
    point is to survive between turns (docker with ``container_persistent``,
    daytona, modal, etc.). Non-persistent backends (e.g. Morph) still get torn
    down at end-of-turn to prevent leakage. The idle reaper
    (``_cleanup_inactive_envs``) handles persistent envs once they exceed
    ``terminal.lifetime_seconds``.
    NF_persistent)r/  rt   r?   )r\  rd  s     r   is_persistent_envr2  p  s5     
!
!C
{u]E22333rB   c                  t   t          t                                                    } d}| D ]L}	 t          |           |dz  }# t          $ r(}t
                              d||d           Y d}~Ed}~ww xY wt                      }ddl}|                    t          |dz                      D ]g}	 t          j        |d           t
                              d	|           5# t          $ r&}t
                              d
||           Y d}~`d}~ww xY w|dk    rt
                              d|           |S )z3Clean up ALL active environments. Use with caution.r   ro   zError cleaning %s: %sTr(   Nr&   )ignore_errorszRemoved orphaned: %sz%Failed to remove orphaned path %s: %szCleaned %d environments)r  rB  ro  
cleanup_vmr3   r   errorr   r*   r+   shutilrmtreerU  r0   r1   )task_idscleanedr\  r8   r4   r*   r6   s          r   cleanup_all_environmentsr;    s   (--//00HG M M	MwqLGG 	M 	M 	MLL0'1tLLLLLLLLL	M #$$KKKK		#kJ67788 K K	KM$d3333KK.5555 	K 	K 	KLL@$JJJJJJJJ	K {{-w777Ns/   A
A5A00A521C$$
D.DDforce_remover=  c                   d}t           5  t                              | d          }t                              | d           ddd           n# 1 swxY w Y   t          5  t
                              | d           ddd           n# 1 swxY w Y   	 ddlm}  ||            n# t          $ r Y nw xY w|dS 	 t          |d          rSddl
}|                    |j                  }d|j        v r|                    |           n^|                                 nIt          |d          r|                                 n$t          |d          r|                                 t                               d	|            dS # t$          $ rr}t'          |          }d
|v sd|                                v rt                               d|            n"t                               d| |           Y d}~dS Y d}~dS d}~ww xY w)u$  Manually clean up a specific environment by task_id.

    *force_remove* (default False) is forwarded to backends that accept it
    — currently only ``DockerEnvironment``. The default of False matches
    session-lifecycle semantics: this function is called from
    ``AIAgent.close()`` (TUI session close, gateway session teardown) and the
    per-turn cleanup branch for non-persistent envs, both of which should
    honor the user's persist-mode preference. Stopping the container here
    would defeat the "ONE long-lived container shared across sessions"
    contract — exactly the bug Ben reported when the container was killed
    on every TUI session close.

    Pass ``force_remove=True`` for actual user-initiated teardown
    (e.g. ``/reset``-style flows that haven't been wired yet, or future
    "destroy my sandbox" commands).

    The idle reaper passes the env through ``env.cleanup()`` directly (not
    via this function), so persist-mode idle envs are similarly no-op'd —
    only the orphan reaper at next startup reclaims them.
    Nr   r  r  r=  r<  r  r  z,Manually cleaned up environment for task: %sr  r  r  r  )ra  rB  rd   rC  r  rD  r  r  rT  r  r  r  r  r  r  r  r   rU  r3   r+   r   r   )r\  r=  rd  r  r  sigr8   r  s           r   r5  r5    s   0 C	 * *"&&w557D)))* * * * * * * * * * * * * * *
 
 + +GT***+ + + + + + + + + + + + + + +999999W%%%%    {X3	"" 	 NNN##CK00C//6666S&!! 	HHJJJJS+&& 	MMOOOBGLLLLL X X XFF	I	0A0A!A!AKKDgNNNNNNJGUVWWWWWWWWW ONNNNNXsO   7AAABBBB% %
B21B2:CF 
G?A!G::G?c                     t                       t          rt          t                    } t                              d|            t          t                                                    }t                       |D ]W}t          |dd          }|	  |d           $# t          $ r%}t          
                    d|           Y d}~Nd}~ww xY wdS dS )zBStop cleanup thread and shut down all remaining sandboxes on exit.z)Shutting down %d remaining sandbox(es)...wait_for_cleanupNg      .@r   z#wait_for_cleanup raised on exit: %s)r,  rB  rv   r   rU  r  valuesr;  r?   r3   r1   )r  envs_to_waitrd  wait_fnr8   s        r   _atexit_cleanuprE    s
    G())?GGG 07799:: """
   	G 	GCc#5t<<GG%%%%% G G GBAFFFFFFFFG%G G	G 	Gs   B
C)C		C	exit_codec                    |dk    rdS t          j        d|           }|r|d         n|                                 }|                                }d}|D ]7}d|v r|                    d          s|                    d          d         } |sdS d	d
id	d
id	d
id	d
id	d
id	d
id	did	did	did	did	didddddd	did}|                    |          }|r||v r||         S dS )a
  Return a human-readable note when a non-zero exit code is non-erroneous.

    Returns None when the exit code is 0 or genuinely signals an error.
    The note is appended to the tool result so the model doesn't waste
    turns investigating expected exit codes.
    r   Nz\s*(?:\|\||&&|[|;])\s*r   r   r   -rl   ro   zNo matches found (not an error)z%Files differ (expected, not an error)zGSome directories were inaccessible (partial results may still be valid)z5Condition evaluated to false (expected, not an error)zCould not resolve hostzFailed to connect to hostz2HTTP response code indicated error (e.g. 404, 500)zOperation timed out)      r     uL   Non-zero exit (often normal — e.g. 'git diff' returns 1 when files differ))grepegrepfgreprgagackdiff	colordiffr  test[curlgit)r   r   rs   ru   r_   )	r   rF  segmentslast_segmentwordsbase_cmdw	semanticscmd_semanticss	            r   _interpret_exit_coder_    st    A~~t
 x17;;H$,9HRLL'@@BBL   EH  !88ALL--8773<<# t
 676767676767<=@A^_LMLM (*D%	
 
 cd1, ,I6 MM(++M (m33Y''4rB   c                     d                     |                                                                           }|                    d          od|v S )au  Return True when PTY mode would break stdin-driven commands.

    Some CLIs change behavior when stdin is a TTY. In particular,
    `gh auth login --with-token` expects the token to arrive via piped stdin and
    waits for EOF; when we launch it under a PTY, `process.submit()` only sends a
    newline, so the command appears to hang forever with no visible progress.
     zgh auth loginz--with-token)r   r   r   ru   r   
normalizeds     r   _command_requires_pipe_stdinrd  E  sL     '--////1122Jo.. 	)j(rB   z=(?:^|[;&|]\s*|&&\s*|\|\|\s*|\$\(\s*)(?:nohup|disown|setsid)\bz\s&\sz\s&\s*(?:#.*)?$c                     t          j        dd|           }t          j        dd|          }t          j        dd|          }|S )a:  Remove single- and double-quoted content so regex checks don't match inside strings.

    This prevents false positives when keywords like 'nohup' or 'setsid' appear
    in commit messages, Python -c code, echo arguments, or PR body text.
    Also strips backtick-quoted content and heredoc-style inline text.
    z'[^']*'z''z"(?:[^"\\]|\\.)*"z""z`[^`]*`z``)r   sub)r   r   s     r   _strip_quotesrg  [  sC     VJg..FV($77FVJf--FMrB   z@\b(?:npm|pnpm|yarn|bun)\s+(?:run\s+)?(?:dev|start|serve|watch)\bz\bdocker\s+compose\s+up\bz\bnext\s+dev\bz\bvite(?:\s|$)z\bnodemon\bz\buvicorn\bz\bgunicorn\bz$\bpython(?:3)?\s+-m\s+http\.server\bc                     d                     |                                                                           }d|v p-|                    d          pd|v p|                    d          S )zGReturn True for informational invocations that should never be blocked.ra  z --helpz -hz
 --versionz -v)r   r   r   endswithrb  s     r   #_looks_like_help_or_version_commandrj  w  so    '--////1122JZ 	&u%%	&:%	& u%%	rB   c                 4   t          |           rdS t          |           }t                              |          r	 dS t                              |          st
                              |          r	 dS t          D ]}|                    |          r	  dS dS )zSuggest background mode when a foreground command looks long-lived.

    Prevents workflows that start a server/watch process and then stall before
    follow-up checks or test commands run.
    NzForeground command uses shell-level background wrappers (nohup/disown/setsid). Use terminal(background=true) so Hermes can track the process, then run readiness checks and tests in separate commands.zForeground command uses '&' backgrounding. Use terminal(background=true) for long-lived processes, then run health checks and tests in follow-up terminal calls.zThis foreground command appears to start a long-lived server/watch process. Run it with background=true, verify readiness (health endpoint/log signal), then execute tests in a separate command.)rj  rg  _SHELL_LEVEL_BACKGROUND_REsearch_INLINE_BACKGROUND_AMP_RE_TRAILING_BACKGROUND_AMP_RE_LONG_LIVED_FOREGROUND_PATTERNS)r   unquotedpatterns      r   _foreground_background_guidancers    s     +733 t W%%H!((22 
?	
 	
 !''11 
5P5W5WX`5a5a 
W	
 	

 3  >>(## 	<  	 4rB   notify_on_complete
backgroundc                 "    |r
| r|rd}d|fS |dfS )uK  Decide what to do when both notify_on_complete and watch_patterns are set.

    These flags produce duplicate, delayed notifications when combined — one
    notification per watch-pattern match AND one on process exit, with async
    delivery that can spam the user long after the process ends. When both are
    set, we drop watch_patterns in favor of notify_on_complete (the more useful
    "let me know when it's done" signal) and return a human-readable note.

    Returns:
        (watch_patterns_to_use, conflict_note). conflict_note is "" when there
        is no conflict.
    zuwatch_patterns ignored because notify_on_complete=True; these two flags produce duplicate notifications when combinedNr   rA   )rt  watch_patternsru  notes       r   #_resolve_notification_flag_conflictry    s=    $  ( ^ L 	 Tz2rB   rd  r  c                     | r| S t          |dd          }t          |t                    r|                                r|S |S )a  Return the cwd for a command, preferring the live session cwd.

    ``terminal_tool`` historically re-sent the init-time/config cwd on every
    call. That broke session-local ``cd`` state: the environment tracked the
    new directory in ``env.cwd``, but foreground/background calls kept forcing
    the old cwd back through ``env.execute(..., cwd=...)``. Explicit
    ``workdir=`` must still override everything.
    r_  N)r?   rr   r+   rs   )r   rd  r  live_cwds       r   _resolve_command_cwdr|    sP      sE4((H(C   X^^%5%5 rB   
session_idforceptyrw  c
                 \   	 t          | t                    s]t                              dt	          |           j                   t          j        dddt	          |           j         ddd          S t                      }
|
d	         }t          |          }t          |          }|d
k    r|                    d          p|
d         }nn|dk    r|                    d          p|
d         }nJ|dk    r|                    d          p|
d         }n&|dk    r|                    d          p|
d         }nd}|                    d          p|
d         }|t          v rFt          |          r7||
d         k    r#t                              d|||
d                    |
d         }|
d         }|p|}|s1|r/|t          k    r$t          j        dd| dt           did          S |s,t!          |           }|rt          j        dd|ddd          S t#                       t$          5  |t&          v r|n|r|t&          v r|nd}|+t)          j                    t*          |<   t&          |         }d}nd}ddd           n# 1 swxY w Y   |rt,          5  |t.          vrt1          j                    t.          |<   t.          |         }ddd           n# 1 swxY w Y   |5  t$          5  |t&          v r|n|r|t&          v r|nd}|*t)          j                    t*          |<   t&          |         }d}ddd           n# 1 swxY w Y   |r|dk    rt5                       t                              d||dd                    	 d}|dk    rl|
                    dd          |
                    dd          |
                    dd           |
                    d!d          |
                    d"d          d#}d}|d$v r)|
                    d%d&          |
                    d'd(          |
                    d)d*          |
                    d+d          |
                    d,d-          |
                    d.g           |
                    d/d          |
                    d0g           |
                    d1i           |
                    d2d          |
                    d3g           |
                    d4d          |
                    d5d          |
                    d6d          d7}d}|d8k    rd9|
                    d:d          i}t7          |||||||||
                    d;          <	  	        }nB# t8          $ r5}t          j        ddd=| d>d?dd          cY d}~cddd           S d}~ww xY wt$          5  |t&          |<   t)          j                    t*          |<   |}ddd           n# 1 swxY w Y   t                              d@||dd                    ddd           n# 1 swxY w Y   t:          j                            dA          dBk    r,dCdDlm }  ||           rt          j        dd&dEddd          S d}|sItC          | |tE          |
          F          }|dG         s|                    dH          dIk    r[t          j        ddddId|                    dJ|           |                    dKdL          |                    dMd          dNd          S |                    dKdL          }dO| dP} t          j        dd|                    dQ|           dRdd          S |                    dS          r|                    dKdT          }dU| dV}n1|                    dW          r|                    dKdT          }dX| dY}|r]tG          |          }!|!rLt                              dZ|dd[         tI          |                      t          j        dd|!dRdd          S d}"|}#|rtK          |           rd}#d\}"dCd]l&m'}$  |$d^          p|pd}%	 |%|_(        n# tR          $ r Y nw xY w|rdCd_l*m+}& tY          |||`          }'	 |d8k    r3|&-                    | |'||%t]          |da          r|j/        nd|#b          }(n|&0                    || |'||%c          }(dd|(j1        |(j2        dCdde})|r||)df<   |"r|"|)dg<   |r	|s|	sdh|)di<   |rG| rEdj| v pdk| v }*dl| v pdm| v pdn| v }+do| v p|*o|+},|,r'|)                    did          }-dp}.|-r|-dqz   |.z   n|.|)di<   |r|s|	rdCdrl3m4}/m5}0  |/            s/d}d}	d|)ds<   dt|)du<   t                              dv|(j1                   nt |0dwd          }1|1rf |0dxd          }2 |0dyd          }3 |0dzd          }4 |0d{d          }5 |0d|d          }6|1|(_6        |2|(_7        |4|(_8        |5|(_9        |3|(_:        |6|(_;        ty          t{          |          |	t{          |          }          \  }	}7|7r&t                              d~|(j1        |7           |7|)d<   |rd|rbd|(_>        d|)ds<   |(j6        rOd|(_?        |&j@        A                    |(j1        d|%|(j6        |(j7        |(j8        |(j9        |(j:        |(j;        dd
           |	r |rt          |	          |(_C        |(jC        |)d<   t          j        |)d          S # tR          $ r4}t          j        dddt          |           dd          cY d}~S d}~ww xY wd}8dC}9d}:d};|9|8k    rq	 tY          |||`          };||;d}< |jD        | fi |<}:nH# tR          $ r:}t          |          E                                }=d|=v r#t          j        ddd| ddd          cY d}~S |9|8k     rd|9d&z  }9d|9z  }>t                              d|>|9|8tI          |           t	          |          j        |||	  	         t)          jF        |>           Y d}~t          G                    d|8tI          |           t	          |          j        |||           t          j        dddt	          |          j         dt          |           dd          cY d}~S d}~ww xY w	 |:                    dd          }?|:                    ddC          }@t          |?|          }?t          |?          }At          | |?          }B|Br&t                      du}C|Cst          d          r|?dz  }?	 dCdlMmN}D  |Dd| |?|@|pd|          }E|ED ]}Ft          |Ft                    r|F}? nn# tR          $ r Y nw xY wdCdlOmP}G  |G            }Ht          |?          |Hk    r[t          |Hdz            }I|H|Iz
  }Jt          |?          |Iz
  |Jz
  }Kd|K dt          |?           d}L|?d|I         |Lz   |?|J d         z   }?dCdlSmT}M  |M|?          }?dCdlUmV}N |?r |N|?W                                |           nd}?t          | |@          }O|?|@dd}P	 dCdlYmZ}Q  |Q| |;|p|p|pd|@|?          }R|RrV|R                    dH          |R                    d          |R                    d          |R                    d          d|Pd<   n,# tR          $ r t          [                    dd           Y nw xY w|r||Pdf<   |Or|O|Pd<   |Ard|Pd<   |Brd|Pd<   t          j        |Pd          S # tR          $ ri}dCdl\}S|S]                                }Tt          G                    d|T           t          j        dddt          |           |Tddd          cY d}~S d}~ww xY w)u|  
    Execute a command in the configured terminal environment.

    Args:
        command: The command to execute
        background: Whether to run in background (default: False)
        timeout: Command timeout in seconds (default: from config)
        task_id: Unique identifier for environment isolation (optional)
        session_id: Conversation/session identifier for durable observability
        force: If True, skip dangerous command check (use after user confirms)
        workdir: Working directory for this command (optional, uses session cwd if not set)
        pty: If True, use pseudo-terminal for interactive CLI tools (local backend only)
        notify_on_complete: If True and background=True, you'll be notified exactly once when the process exits. The right choice for almost every long task. MUTUALLY EXCLUSIVE with watch_patterns.
        watch_patterns: List of strings to watch for in background output. HARD rate limit: 1 notification per 15s per process. After 3 strike windows in a row, watch_patterns is disabled and the session is auto-promoted to notify_on_complete. Use ONLY for rare, one-shot mid-process signals on long-lived processes (server readiness, migration-done markers). NEVER use in loops/batch jobs — error patterns there will hit the strike limit and get disabled. MUTUALLY EXCLUSIVE with notify_on_complete — set one, not both.

    Returns:
        str: JSON string with output, exit_code, and error fields

    Examples:
        # Execute a simple command
        >>> result = terminal_tool(command="ls -la /tmp")

        # Run a background task
        >>> result = terminal_tool(command="python server.py", background=True)

        # With custom timeout
        >>> result = terminal_tool(command="long_task.sh", timeout=300)
        
        # Force run after user confirmation
        # Note: force parameter is internal only, not exposed to model API
    z+Rejected invalid terminal command value: %sr   r   z&Invalid command: expected string, got r6  )r   rF  r6  statusF)ensure_asciir{   r|   rj  r  rl  r~  ri  r  rk  r_  zaIgnoring host/relative cwd override %r for %s backend (won't exist in sandbox). Using %r instead.r   zForeground timeout zs exceeds the maximum of zNs. Use background=true with notify_on_complete=true for long-running commands.NTz*Creating new %s environment for task %s...   r  r  r  r  r  r  r  )r  r  r  r  r  >   r~  r|   r  r  r  ro   r  r  r  r  r  r  r  r   r~   r  r  r  r  r  r  rG  )r  r  r  r  r  r   r~   r  r  r  r  r  r  rG  r  r  r  r}   )	r{   r  r_  r   r  rE  r  r\  r}   z5Terminal tool disabled: environment creation failed (r  disabledz %s environment ready for task %s_HERMES_GATEWAYr   r   )#_contains_gateway_lifecycle_commanda  Blocked: cannot restart or stop the gateway from inside the gateway process. The gateway would kill this command before it could complete (SIGTERM propagates to child processes). Run `hermes gateway restart` from a separate shell outside the running gateway.)r   approvedr  pending_approvalr   descriptionzcommand flaggedpattern_key)r   rF  r6  r  approval_pendingr   r  r  zCommand denied: z?. Use the approval prompt to allow it, or rephrase the command.r  blockeduser_approvedzflagged as dangerouszCommand required approval (z) and was approved by the user.smart_approvedzCommand was flagged (z&) and auto-approved by smart approval.z+Blocked dangerous workdir: %s (command: %s)r   zPTY disabled for this command because it expects piped stdin/EOF (for example gh auth login --with-token). For local background processes, call process(action='close') after writing so it receives EOF.)get_current_session_key)r   r
  )r   rd  r  rd  )r   r_  r\  rX   env_varsuse_pty)rd  r   r_  r\  rX   zBackground process started)r   r}  pidrF  r6  rE   pty_noteu  background=true without notify_on_complete=true means this process runs SILENTLY — you will not be told when it exits. If this is a bounded task (test suite, build, CI poller, deploy, anything with a defined end), you almost certainly wanted notify_on_complete=true so the system pings you on exit. Re-launch with notify_on_complete=true, or call process(action='poll') / process(action='wait') yourself to learn the outcome. Only ignore this hint for genuine long-lived processes that never exit (servers, watchers, daemons).hintz
gh pr viewzgh pr checksz jq z| jqz$(jqstatusCheckRollupuR  This looks like a homebrewed CI poller built from `gh pr view --json statusCheckRollup` and/or `gh pr checks | jq`. That shape has burned us repeatedly in hermes-agent dev work (PRs #31329, #31448, #31695, #31709, #31745, #32264, #33131) — stdout buffering kills output capture, jq null-key edge cases silently exit the loop, conclusion-vs-status field confusion exits early with bogus all-green verdicts, TTY-only summary banners never appear when piped. Use the canonical snippets in the green-ci-policy skill instead: the exit-code-driven `gh pr checks $PR >/dev/null` (rc 0 = green, 8 = pending, else fail) for exit-on-first-fail behavior, or the column-2 awk-on-tabs poller (`awk -F"\t" "$2==\"pending\""`) for sharded matrices. Load skill_view(name='github/hermes-agent-dev', file_path='references/green-ci-policy.md') for the verbatim snippets. If you must roll a custom loop with rich structured output, write each tick to a known file (`tee -a /tmp/ci.log`) and rely on `process(action='log')` to read THAT file — do not rely on background-process stdout capture for line-buffered shell loops.z

)async_delivery_supportedrO   rt  u  notify_on_complete / watch_patterns are not available on this endpoint (stateless HTTP API — no channel to deliver an async completion after the turn ends). The process is running in the background; retrieve its result with process(action='poll') or process(action='wait').notify_unsupportedzjbackground proc %s: async delivery unsupported on this session; notify_on_complete/watch_patterns disabledHERMES_SESSION_PLATFORMHERMES_SESSION_CHAT_IDHERMES_SESSION_THREAD_IDHERMES_SESSION_USER_IDHERMES_SESSION_USER_NAMEHERMES_SESSION_MESSAGE_ID)rt  rw  ru  zbackground proc %s: %swatch_patterns_ignoredr*  )
r}  check_intervalrX   r   chat_iduser_id	user_name	thread_id
message_idrt  rw  z$Failed to start background process: )r   rF  r6  rn   )r   r_  |   zCommand timed out after z secondsrp   zfExecution error, retrying in %ds (attempt %d/%d) - Command: %s - Error: %s: %s - Task: %s, Backend: %szWExecution failed after %d retries - Command: %s - Error: %s: %s - Task: %s, Backend: %szCommand execution failed: rt  r   r  r4  uu   

⚠️ Sudo authentication failed — cached password cleared. You will be prompted again on the next sudo command.)invoke_hooktransform_terminal_output)r   r   r  r\  r{   )get_max_bytesg?z

... [OUTPUT TRUNCATED - z chars omitted out of z total] ...

)
strip_ansi)redact_terminal_output)record_terminal_resultr   )r   r_  r}  rF  r   kindr`   canonical_command)r  r  r`   r  verification_evidencez&verification evidence recording failedr(   exit_code_meaningsudo_auth_failedsudo_cache_clearedzterminal_tool exception:
%szFailed to execute command: )r   rF  r6  	tracebackr  )^rr   r+   r   r   r   r   ru  dumpsr  r`  rr  r_   r  r  rU  FOREGROUND_MAX_TIMEOUTrs  r(  ra  rB  r   rC  r  rD  rV   Lockr:   r  rT  r   r   hermes_cli.cronr  r   r   r   r   rd  tools.approvalr  	cwd_ownerr3   r  r  r|  spawn_localr  rd  spawn_via_envrU   r  rT   r  rO   watcher_platformwatcher_chat_idwatcher_user_idwatcher_user_namewatcher_thread_idwatcher_message_idry  rt   rt  watcher_intervalpending_watchersr   r  rw  executer   r   r6  r   r   r   rC   r   hermes_cli.pluginsr  tools.tool_output_limitsr  rv   rR  tools.ansi_stripr  agent.redactr  rs   r_  agent.verification_evidencer  r1   r  
format_exc)Ur   ru  r   r\  r}  r~  r   r  rt  rw  ry   r{   effective_task_idr]  r  r_  default_timeouteffective_timeoutguidance_existing_keyrd  needs_creation	task_lockr  rE  r  new_envr8   r  approval_noterE   descfallback_msgworkdir_errorpty_disabled_reasoneffective_ptyr  rX   r  effective_cwdproc_sessionresult_data_gh_has_jq
_bad_shapeexistingcanonical_hint	_async_ok_gse_gw_platform_gw_chat_id_gw_thread_id_gw_user_id_gw_user_name_gw_message_idconflict_notemax_retriesretry_countr   command_cwdexecute_kwargsr  	wait_timer   r  r  r  r7  r  hook_resultshook_resultr  MAX_OUTPUT_CHARS
head_chars
tail_charsomittedtruncated_noticer  r  	exit_noteresult_dictr  evidencer  tb_strsU                                                                                        r   terminal_toolr    s   VI'3'' 
	#NN=W&   :Z$w--BXZZ!	 
 "# # # # !""*% 7w?? +733	 xMM.11KVN5KEE&&MM"566U&AT:UEE  MM-00IF=4IEE""MM/22Mf_6MEEEmmE""3fUm ***/I#/N/N*fUm##B6%=  
 -C +#6  	#g 	#'4J*J*J:J' J J-J J J "# # # #  	'6w??H 'z !#%%	# #
 !&' ' ' ' 	  	& 	& &7:N%N%N!!!(VW8L-L-LggRV  (04	}-*=9!&!%	& 	& 	& 	& 	& 	& 	& 	& 	& 	& 	& 	& 	& 	& 	&"  R	e% ? ?$O;;9B9I9IO$56+,=>	? ? ? ? ? ? ? ? ? ? ? ? ? ? ?
  Ke Ke / /->BV-V-V)))0^W@T5T5TggZ^ " %08<	}52=A)./ / / / / / / / / / / / / / / " ?e=001333KK LhXijlkljlXmnnn5/%)
#u,,(.

:r(B(B(.

:r(B(B(.

:r(B(B'-zz)R'@'@.4jj9I5.Q.Q* *J ,0(#'TTT17OQ1O1O4:JJ?QSW4X4X28**=Mu2U2U8>

CY[_8`8`.4jjv.N.N28**=Mr2R2RAGLkmrAsAs6<jjAUWY6Z6Z.4jjr.J.J;A::F_af;g;g5;ZZ@SUW5X5X28**=Mt2T2TCI::NoquCvCv8>

CY[_8`8`0 0," (,#w.. ,fjj9KU.S.S,L #6%-"' #$5'1-=)5$5%+ZZ
%;%;
# 
# 
# ' / / /#z&()+%a]^%a%a%a&0	+ +
 ). /  /  / / / / / /AKe Ke Ke Ke Ke Ke Ke Ke~/ # & &BI,->?<@IKK'89%& & & & & & & & & & & & & & & KK BHN_`bab`bNcdddWKe Ke Ke Ke Ke Ke Ke Ke Ke Ke Ke Ke Ke Ke Keh :>>+,,33KKKKKK227;; 'z !"/ &# # !&' ' ' '  $	e( 7 ? ?  H J' '<<))-???:"$%'!#"4,0#+<<	7#C#C'/||MCT'U'U'/||M2'F'F	' 	' %*	+ 	+ 	+ 	+  ||M3DEETt T T T  z !#%\\)\BB'	# #
 !&' ' ' ' ||O,, e||M3IJJ cd c c c.// e||M3IJJ d d d d  
	'-g66M 'L&tt}.CG.L.LN N Nz !#*'	# #
 !&' ' ' ' # 	/88 	!M   	;:::::--b999Lgm	'CMM 	 	 	D	  P	? @?????0  M
h'w&&#3#?#? ') 1$/,3C,?,?!IT - $@ $ $LL $4#A#A ') 1$/ $B $ $L ;"./'+!"!  ! <.;K
+& B.AK
+  &8  	H  'T  0' 0'72On6OC')SVw->S&GBS  ,w6 -
  OG  "  #.??62#>#>= '8 CK 0Hv->>!/ $F+  )M#5 )M )M        %9;; M-2*)-<A$89P $$89 R(O    (,t,Er'J'J' M*.$/G*L*LK,0D1KR,P,PM*.$/G*L*LK,0D1KR,P,PM-1T2Mr-R-RN<HL9;FL8;FL8=JL:=JL:>LL; 1T'+,>'?'?#1#J//1 1 1-
 ! JNN#;\_m\\\<IK 89 & * 6:L38<K 45
 $4 895(9@@*6/./+6(4(E'3'C'3'C)5)G)5)G*6*I26B B    " Pj P26~2F2FL/4@4OK 01z+EBBBB ' ' 'z !#LCFFLL# # !&	' ' ' ' ' ' ' ' '' KKFK,,#+"6 '$'# # #K $5*& &N )S[CCNCCFF  + + + #AI I--#z&(),%[@Q%[%[%[+ + ).	 /  /  / / / / / / / #[00#q($%$4	  (P'0+{LabiLjLjlpqrlslsl|~  BS  U]^ ^ ^
9--- LL!z!,.CG.L.LdSTggN^`actv~@ @ @:"$%'!Zd1gg>N!Z!ZRUVWRXRX!Z!Z' ' %*	+ + + + + + + + +)+6  ZZ"--FL!44J *&(;;F;FCC!H" " " +F+H+HPT+T(+ ?S/T/T #F::::::*{/#!)-3%      $0  K!+s33 !,     ?>>>>>,}6{{--- !1C!788
-
:
f++
2Z?;7 ; ;!&kk; ; ; !  ,/??&*BVV 433333Z''F <;;;;;HNV++FLLNNGDDDTVF -WjAAI !' K
VNNNNNN11##)VWV8IVY(!    "*,,x"8"8 (V 4 4!)g!6!6-5\\:M-N-N	< <K 78  V V VEPTUUUUUV 8*7J' =3</0 726./! 94801:k>>>> 
 
 
%%''3V<<<z;3q66;;
 
    	 	 	 	 	 		
s&  A1|8 4E0|8 %-|8 |8 (A
I>2|8 >J|8 J|8 2K|8 K|8 K|8 X(&AL9-X(9L=	=X( L=	>X( G/U0/X(0
V/:V*V/X(|8 *V//
X(9(W-!X(-W1	1X(4W1	5'X(|8 (X,,|8 /X,0A|8 B|8 "A
|8 -C|8 //|8 a' &|8 '
a41|8 3a44|8 I6l
 

m)m=m>|8 m|8 %n  |8 sAss|8 A%s:|8 ?A=s<s=|8 sB|8 7v |8 
v|8 vC|8 %A4{ |8 &| |8 |4|8 8
~+A~& ~+&~+c                  H   	 t                      } | d         }|dk    rdS |dk    r]ddlm}  |            }|st                              d           dS t          j        |d	gdd
t
          j                  }|j        dk    S |dk    r[t          j
        d          pt          j
        d          }|r/t          j        |dgdd
t
          j                  }|j        dk    S dS |dk    rH|                     d          r|                     d          st                              d           dS dS |dk    rwt          |                     d                    }|d         dk    rdS |d         dk    r|d         r*t                              dt          d                     dS |d         dk    r*t                              dt          d                     dS |d         dk    rEt                      rt                              d           nt                              d           dS t                      rt                              d           nt                              d            dS t          j                            d          t                              d"           dS dS |d#k    rdd$lm} t)          j        d%          d!uS t                              d&|           dS # t,          $ r(}t                              d'|d(           Y d!}~dS d!}~ww xY w))z8Check if all requirements for the terminal tool are met.r{   r  Tr|   r   )find_dockerz?Docker executable not found in PATH or common install locationsFversionr*  )capture_outputr   r  r  	apptainerz	--versionr  r  r  zSSH backend selected but TERMINAL_SSH_HOST and TERMINAL_SSH_USER are not both set. Configure both or switch TERMINAL_ENV to 'local'.r~  r  r  r  r  r  zModal backend selected with TERMINAL_MODAL_MODE=managed, but Nous Tool Gateway access is not currently available and no direct Modal credentials/config were found. %s Choose TERMINAL_MODAL_MODE=direct/auto to use direct Modal credentials.r  r  zhModal backend selected with TERMINAL_MODAL_MODE=managed, but the managed tool gateway is unavailable. %szModal backend selected with TERMINAL_MODAL_MODE=direct, but no direct Modal credentials/config were found. Configure Modal or choose TERMINAL_MODAL_MODE=managed/auto.zModal backend selected with TERMINAL_MODAL_MODE=direct, but no direct Modal credentials/config were found. Configure Modal or choose TERMINAL_MODAL_MODE=auto.zModal backend selected but no direct Modal credentials/config or managed tool gateway was found. Configure Modal, set up the managed gateway, or choose a different TERMINAL_ENV.z|Modal backend selected but no direct Modal credentials/config was found. Configure Modal or choose a different TERMINAL_ENV.NzFmodal is required for direct modal terminal backend: pip install modalr  )DaytonaDAYTONA_API_KEYzWUnknown TERMINAL_ENV '%s'. Use one of: local, docker, singularity, modal, daytona, ssh.z&Terminal requirements check failed: %sr(   )r  rS  r  r   r6  r  r  r  r  r7  whichr_   r  r   r   	importlibutil	find_specr  r  r   r   r3   )	ry   r{   r  r|   r   
executabler  r  r8   s	            r   check_terminal_requirementsr  
  s   i ""*%w4!!====== []]F ^___u^VY$7VW_i_qrrrF$))&&k22Qfl=6Q6QJ .#[(ARV`aisi{|||(A--5::j)) J1G1G Z   u4  26::l3K3KLLK-.);;t-.(::56 
!LL[ >5    !5v&)33LL:=5    !5 (H44133 @    8  
 !5133 
B    R   !5~''008efffu4""''''''9.//t;; LL'  
 5   =q4PPPuuuuusb   K/ 2K/ .K/ AK/ $A
K/ 25K/ )<K/ '4K/ AK/ .AK/ 39K/ 0!K/ K/ /
L!9LL!__main__zTerminal Tool Modulez2==================================================z
Current Configuration:z  Environment type: z  Docker image: rj  z  Modal image: ri  z  Working directory: z  Default timeout: sz  Lifetime: u;   
❌ Requirements not met. Please check the messages above.ro   u   
✅ All requirements met!z
Available Tool:z=  - terminal_tool: Execute commands in sandboxed environmentsz
Usage Examples:z  # Execute a commandz*  result = terminal_tool(command='ls -la')z  z  # Run a background taskzE  result = terminal_tool(command='python server.py', background=True)z
Environment Variables:r  z  TERMINAL_ENV: r  r  z- (local/docker/singularity/modal/daytona/ssh)z  TERMINAL_DOCKER_IMAGE: r  z  TERMINAL_SINGULARITY_IMAGE: r  r  z  TERMINAL_MODAL_IMAGE: r  z  TERMINAL_DAYTONA_IMAGE: r  z  TERMINAL_CWD: ry  r   z  TERMINAL_SANDBOX_DIR: TERMINAL_SANDBOX_DIRz
/sandboxesz  TERMINAL_TIMEOUT: r  60z  TERMINAL_LIFETIME_SECONDS: rH  rI  )registryterminalobjectstringz The command to execute on the VM)r   r  booleanus  Run the command in the background. Almost always pair with notify_on_complete=true — without it, the process runs silently and you'll have no way to learn it finished short of calling process(action='poll') yourself (easy to forget, leading to silent blindness on long jobs). Two legitimate patterns: (1) Long-lived processes that never exit (servers, watchers, daemons) — these stay silent because there's no exit to notify on. (2) Long-running bounded tasks (tests, builds, deploys, CI pollers, batch jobs) — these MUST set notify_on_complete=true. For short commands, prefer foreground with a generous timeout instead.)r   r  r   z3Max seconds to wait (default: 180, foreground max: u   ). Returns INSTANTLY when command finishes — set high for long tasks, you won't wait unnecessarily. Foreground timeout above z7s is rejected; use background=true for longer commands.)r   r  minimumz^Working directory for this command (absolute path). Defaults to the session working directory.zRun in pseudo-terminal (PTY) mode for interactive CLI tools like Codex, Claude Code, or Python REPL. Only works with local and SSH backends. Default: false.u  When true (and background=true), you'll be automatically notified exactly once when the process finishes. **This is the right choice for almost every long-running task** — tests, builds, deployments, multi-item batch jobs, anything that takes over a minute and has a defined end. Use this and keep working on other things; the system notifies you on exit. MUTUALLY EXCLUSIVE with watch_patterns — when both are set, watch_patterns is dropped.arrayr   u
  Strings to watch for in background process output. HARD RATE LIMIT: at most 1 notification per 15 seconds per process — matches arriving inside the cooldown are dropped. After 3 consecutive 15-second windows with dropped matches, watch_patterns is automatically disabled for that process and promoted to notify_on_complete behavior (one notification on exit, no more mid-process spam). USE ONLY for truly rare, one-shot mid-process signals on LONG-LIVED processes that will never exit on their own — e.g. ['Application startup complete'] on a server so you know when to hit its endpoint, or ['migration done'] on a daemon. DO NOT use for: (1) end-of-run markers like 'DONE'/'PASS' — use notify_on_complete instead; (2) error patterns like 'ERROR'/'Traceback' in loops or multi-item batch jobs — they fire on every iteration and you'll hit the strike limit fast; (3) anything you'd ever combine with notify_on_complete. When in doubt, choose notify_on_complete. MUTUALLY EXCLUSIVE with notify_on_complete — set one, not both.)r   r  r  )r   ru  r   r   r  rt  rw  )r   
propertiesrequired)r   r  r  c                    t          |                     d          |                     dd          |                     d          |                    d          |                    d          |                     d          |                     dd          |                     d	d          |                     d
          	  	        S )Nr   ru  Fr   r\  r}  r   r  rt  rw  )	r   ru  r   r\  r}  r   r  rt  rw  )r  r_   )argskws     r   _handle_terminalr    s    ##88L%00##y!!66,''##HHUE""88$8%@@xx 011
 
 
 
rB   u   💻i )r   toolsetschemahandlercheck_fnemojimax_result_size_chars)rM   N)F)r   )r   )NNNr   N)rJ  )	FNNNFNFFN)__doc__importlib.utilr  ru  loggingr   r   r   r   rV   atexitr7  r  pathlibr   typingr   r   r   r   utilsr   	getLoggerr   r   tools.interruptr	   r
   tools.environments.singularityr   tools.tool_backend_helpersr   r   r   r   r   r+   r    rR  r  r  r2   r:   r;   dict__annotations__r  r^   r  r@   rC   rF   rJ   rL   r\   ra   re   rh   r  ri   r   rt   rx   r   r   compiler   r   r   r   r   r   r   r   r   tupler   r  r   r  r2  r:  tools.environments.localr;  r  r<  r  tools.environments.sshr=  r  rS  r>  r  tools.environments.modalr?  r   tools.environments.managed_modalr@  r  tools.managed_tool_gatewayrA  r   TERMINAL_TOOL_DESCRIPTIONrB  rC  ra  rD  r  r&  r"  rP  rQ  rZ  r[  re  rg  r`  rr  rw  r}  r  rm  r  r  r  r  r  r  r  r   r$  r(  r,  r/  r2  r;  r5  rE  registerr_  rd  
IGNORECASE	MULTILINErl  rn  ro  rg  rp  rj  rs  ry  r|  r  r  r   ry   exitdefault_imgr   r   r   r   tools.registryr  TERMINAL_SCHEMAr  rA   rB   r   <module>r:     s^    @       				  				                  , , , , , , , , , , , , ! ! ! ! ! !		8	$	$ = < < < < < < < < ; ; ; ; ;             
 	   8 0/%	   #9"8			# #   F (* d38n ) ) )*IN,,   	!!9 9 94 4 4% % %     - - - - -,33 3 3 3 32 2 2 2 2 2% % % %     
	s 	t 	 	 	 	_DcN _t _ _ _ _ /4C Cs Cc C'+C8<C C C C 2:=>> s sTz    ,      6  M M M M M M4Z!$	   (z3 z3s z3C z3 z3 z3 z3x	- 	-3 	-s 	-S 	- 	- 	- 	-=c =d = = = =!s !3 !5c? ! ! ! !H=$C =$E#s(O =$ =$ =$ =$@5# 5# 5 5 5 5pd    4b# b# b b b bJHS4Z HE#*cDj:P4Q H H H HX K J J J J J \ \ \ \ \ \ D D D D D D M M M M M M J J J J J J ` ` ` ` ` ` D D D D D D 



 0 (* d38n ) ) )#%S%Z  % % %IN	-/c9>)* / / /%y~''  
 " +Y^-- >;c3h >;D >; >; >; >;R 24 T#tCH~-. 3 3 3& &c3h & & & &R+c + + + +   #        FHSM d38n    , >AT] 
 
 
s 
s 
c 
 
 
 
 Dc D D D D$ : i M M MNN .c . . . . . . C D    *zc3h z z z zz$ 4S>     KO-1'0(,	U
 U
# U
c U
 U
c U
$(U
CGU
&*U
 "%U
 #&	U
 U
 U
 U
p;\ ;\S ;\ ;\ ;\ ;\|  $ $ $  UC U U U U4s 4t 4 4 4 4&  6 6; AX AX AX AXd AX AX AX AXHG G G0       =# =# =#* = = = =@# $     (RZDbmVXVbFb   'BJx00 (bj);<< 3 3    " BJRTVTabbBJ+R];;BJ "-00BJ "-00BJ~r}--BJ~r}--BJ..BJ6FF	#      "S "S4Z " " " "J 	
    6c] 
 	
 	   4 !! $!$*.t ttt c]t c]	t
 t t c]t 
t t T#Y't 	t t t tnkT k k k k\ z	E
 !!!	E(OOO_F	E
$%%%	E
5
!3
5
5666	E
5VN3
5
5666	E
3F=1
3
3444	E
1&-
1
1222	E
4y 1
4
4
4555	E
6 23
6
6
6777&&(( LMMM	E
'(((	E
	E
IJJJ	E
	E
!"""	E
6777	E$KKK	E
%&&&	E
QRRR	E
$%%%>K	E	729^W--	7 	7 	7  
 
E
Wibi0G&U&U
W
WXXX	E
o9295QSl_jSlSl+m+m
o
oppp	E
UYRY/E{%S%S
U
UVVV	E
Yyry1I;'W'W
Y
YZZZ	E
HYRY~||~~FF
H
HIII<<<<<<	E
_YRY/E$$&&G\G\G\%]%]
_
_```	E
F+=t!D!D
F
FGGG	E
Y)")4OQV*W*W
Y
YZZZ $ # # # # # , !A 
 "  U
   "  |Uk   |   |  mC   |   |   |  ! 
 "  ~   "  ` # #   (+  l ;"
 "
F KK& &* *Z    	(
!     rB   