
    epjN                       U d Z ddlm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 ddlmZmZmZmZ ddlmZ dZd	Zd
ZdZd
ZdZ G d de          Z  G d de!ej"                  Z# ej$        d           G d d                      Z% ej$        d           G d d                      Z& ej$        d           G d d                      Z' ej$        d           G d d                      Z( ej$        d           G d d                      Z) ej$        d           G d d                      Z* ej$        d           G d d                       Z+ej$         G d! d"                      Z, G d# d$          Z- e-            Z.dd%l/m0Z1  e1d&d'(          Z2 e
j3        d)          Z4 ej5        d*d+          Z6d,e7d-<   ed5d0            Z8d6d2Z9 G d3 d4          Z:dS )7a*  Public, plugin-safe lifecycle API for delegated Hermes subagents.

This module deliberately exposes immutable contracts, not ``AIAgent`` objects.
It is the supported boundary for plugins that need to supervise fresh child
sessions; plugins must obtain it from ``PluginContext.subagent_lifecycle``.
    )annotationsN)contextmanager)FutureTimeoutError)AnyCallableMappingOptional)request_hard_interrupt   i>  i }  i    i  c                      e Zd ZdZdS )SubagentLifecycleErrorz@A request cannot be safely accepted by the public lifecycle API.N)__name__
__module____qualname____doc__     >/home/thesage/.hermes/hermes-agent/agent/subagent_lifecycle.pyr   r   "   s        JJJJr   r   c                  2    e Zd ZdZdZdZdZdZdZdZ	dZ
d	Zd
S )SubagentStatePENDINGSTARTINGRUNNING	SUCCEEDEDFAILEDINTERRUPTEDCANCEL_REQUESTED	CANCELLEDUNKNOWNN)r   r   r   r   r   r   r   r   r   r   r   r    r   r   r   r   r   &   s<        GHGIFK)IGGGr   r   T)frozenc                      e Zd ZU ded<   dZded<   dZded<   dZded<   dZd	ed
<   dZded<   dZ	ded<   dZ
ded<   dZded<    ej        e          Zded<   dZded<   dS )SubagentLaunchRequeststrgoalNOptional[str]contextleafrolemodelzOptional[tuple[str, ...]]allowed_toolsetsr   ztuple[str, ...]blocked_toolsworking_directoryparent_session_idcorrelation_iddefault_factoryMapping[str, Any]metadataOptional[float]timeout_seconds)r   r   r   __annotations__r'   r)   r*   r+   r,   r-   r.   r/   dataclassesfielddictr3   r5   r   r   r   r#   r#   2   s         III!G!!!!DE266666%'M'''''+++++'+++++$(N(((("3+"3D"I"I"IHIIII'+O++++++r   r#   c                      e Zd ZU ded<   ded<   ded<   ded<   ded	<   ded
<   ded<   ded<   ded<   ded<   ddZedd            ZdS )SubagentHandleintcontract_versionr$   subagent_idr&   r.   r/   float
created_atproviderr*   r)   depth
capabilityreturndict[str, Any]c                *    t          j        |           S N)r7   asdictselfs    r   to_dictzSubagentHandle.to_dictN   s    !$'''r   valuer2   'SubagentHandle'c                    	  | di t          |          S # t          t          f$ r}t          d          |d }~ww xY w)NzMalformed subagent handle.r   )r9   	TypeError
ValueErrorr   )clsrL   excs      r   	from_dictzSubagentHandle.from_dictQ   s]    	P3%%e%%%:& 	P 	P 	P()EFFCO	Ps    =8=N)rD   rE   )rL   r2   rD   rM   )r   r   r   r6   rK   classmethodrS   r   r   r   r;   r;   A   s         $$$$!!!!IIIJJJOOO( ( ( ( P P P [P P Pr   r;   c                  <    e Zd ZU ded<   ded<   ded<   dZded	<   dS )
SubagentStatusr;   handler   stater?   
updated_atNr&   
diagnosticr   r   r   r6   rZ   r   r   r   rV   rV   Y   sG          $J$$$$$$r   rV   c                  J    e Zd ZU ded<   ded<   ded<   dZded<   d	Zd
ed<   d	S )SubagentTerminalStater;   rW   r   rX   bool	completedF	timed_outNr&   rZ   )r   r   r   r6   r`   rZ   r   r   r   r]   r]   a   sU         OOOI $J$$$$$$r   r]   c                  \    e Zd ZU ded<   dZded<   dZded<   dZded<   ej        Z	ded<   d	S )
SubagentCancelResultr^   acceptedFalready_terminalunknown_handleunsupportedr   rX   N)
r   r   r   r6   rd   re   rf   r   r    rX   r   r   r   rb   rb   j   sc         NNN""""" N    K(0E000000r   rb   c                      e Zd ZU ded<   ded<   ded<   dZded	<   dZd
ed<   dZded<   dZded<   dZded<   dZ	ded<    e
j        e          Zded<    e
j        e          Zded<   dZded<   dS )SubagentResultr;   rW   r   terminal_stater^   readyNr&   summaryzOptional[Mapping[str, Any]]structured_payloadr4   
started_atcompleted_aterror_classificationerror_messager0   r2   usage_metadatatool_execution_summaryresult_hash)r   r   r   r6   rk   rl   rm   rn   ro   rp   r7   r8   r9   rq   rr   rs   r   r   r   rh   rh   s   s         !!!!KKK!G!!!!6:::::"&J&&&&$(L((((*.....#'M''''(9(9$(O(O(ONOOOO0A0ARV0W0W0WWWWW!%K%%%%%%r   rh   c                  2    e Zd ZU ded<   ded<   dZded<   dS )SubagentReconnectResultr^   	connectedr   rX   Nr&   rZ   r[   r   r   r   ru   ru      s8         OOO $J$$$$$$r   ru   c                  t    e Zd ZU ded<   ded<   ded<   dZded	<   dZd
ed<   dZded<   dZded<   dZded<   dS )_Recordr;   rW   r   rX   r?   rY   Nr   agentzOptional[Future]futurer4   rm   rn   zOptional[SubagentResult]result)	r   r   r   r6   ry   rz   rm   rn   r{   r   r   r   rx   rx      s         E#F####"&J&&&&$(L(((('+F++++++r   rx   c                      e Zd ZdZddZdS )	_RegistryzDThread-safe terminal-retention registry; never returns live records.rD   Nonec                R    t          j                    | _        i | _        i | _        d S rG   )	threadingRLocklockrecordscorrelationsrI   s    r   __init__z_Registry.__init__   s&    O%%	+-BDr   NrD   r~   )r   r   r   r   r   r   r   r   r}   r}      s4        NNE E E E E Er   r}   )DaemonThreadPoolExecutor   zhermes-lifecycle)max_workersthread_name_prefix     hermes_subagent_lifecycle_parent)defaultzcontextvars.ContextVar[Any]_ACTIVE_PARENT_AGENTparent_agentr   c              #     K   t                               |           }	 dV  t                               |           dS # t                               |           w xY w)z6Bind the host-owned parent for the current agent turn.N)r   setreset)r   tokens     r   bind_subagent_parentr      s^       !$$\22E*""5)))))""5))))s	   > ArD   c                 4    t                                           S )z:Return the parent bound to this execution context, if any.)r   getr   r   r   get_active_subagent_parentr      s    ##%%%r   c                      e Zd ZdZd,dZd-d
Zd.dZddd/dZd0dZd1dZ	d2dZ
d3dZed4d            Zd5d$Zed6d*            Zed7d+            ZdS )8SubagentLifecycleServicea7  Stable public service returned by :attr:`PluginContext.subagent_lifecycle`.

    Running children are in-process only.  Completed results remain available
    until process exit; ``reconnect`` accurately reports that a serialized
    handle cannot reconnect after a restart instead of launching work again.
    parent_agent_resolverCallable[[], Any]rD   r~   c                    || _         d S rG   )_parent_agent_resolver)rJ   r   s     r   r   z!SubagentLifecycleService.__init__   s    &;###r   requestr#   r;   c                    |                                  }|t          d          |                     ||           t          t	          |dd          pd          pd }|j        r|j        |k    rt          d          ||j        pdf}t          j        5  | 	                                 |j        r|t          j
        v rt          d          d d d            n# 1 swxY w Y   ddlm}m}  |d|j        |j        |j        rt#          |j                  nd |j        |d||j        		  	        }t          t	          |d
d          pd          }|st          d          t)          j                    }	t+          t,          |||j        |	t	          |dd           t	          |dd           t	          |d|j                  t/          t	          |dd          pd          |                     |||	          
  
        }
t3          |
t4          j        |	|          }t          j        5  |t          j        |<   |j        r|t          j
        |<   d d d            n# 1 swxY w Y   t:                              | j        ||j        |          |_         |
S )Nz-No active Hermes parent session is available.
session_id z4parent_session_id does not match the active session.z1Duplicate correlation_id for this parent session.r   )$_build_child_preserving_parent_toolsDEFAULT_MAX_ITERATIONSr   )	
task_indexr%   r'   toolsetsr*   max_iterations
task_countr   r)   _subagent_idz)Hermes failed to assign a child identity.rA   r*   _delegate_role_delegate_depth)ry   )!r   r   _validate_requestr$   getattrr.   r/   	_REGISTRYr   _cleanup_lockedr   tools.delegate_toolr   r   r%   r'   r+   listr*   r)   timer;   PUBLIC_CONTRACT_VERSIONr<   _capabilityrx   r   r   r   	_EXECUTORsubmit_runrz   )rJ   r   parentr.   correlation_keyr   r   childr>   createdrW   records               r   launchzSubagentLifecycleService.launch   sb   ,,..>(?   	w///b A A GRHHPD$ 	)BFW)W)W(F   -g.D.JK^ 	 	  """% /Y=S*S*S,G  	 	 	 	 	 	 	 	 	 	 	 	 	 	 		
 	
 	
 	
 	
 	
 	
 	

 54O'T'2333-1
 
 
 '%<<BCC 	V()TUUU)++#"E:t,,E7D))E+W\::0!449::[*;WEE
 
 !6uMMM^ 	F 	F-3Ik*% F:E	&7	F 	F 	F 	F 	F 	F 	F 	F 	F 	F 	F 	F 	F 	F 	F "((FGL&QQs$   9CC"C%&IIIrW   rV   c                   |                      |          }|-t          |t          j        t	          j                    d          S t
          j        5  t          |j        |j        |j	                  cd d d            S # 1 swxY w Y   d S )NUNKNOWN_HANDLE)
_recordrV   r   r    r   r   r   rW   rX   rY   rJ   rW   r   s      r   statuszSubagentLifecycleService.status  s    f%%>!-ty{{<L   ^ 	R 	R!&-v?PQQ	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	R 	Rs    A>>BBN)r5   r5   r4   r]   c                  |                      |          }|t          |t          j        dd          S |j        }|O	 |                    |           n7# t          $ r t          |j        |j        dd          cY S t          $ r Y nw xY wt          j        5  t          |j        |j        |j        d u          cd d d            S # 1 swxY w Y   d S )NTr   )rZ   )timeoutF)r   r]   r   r    rz   r{   r   rW   rX   	Exceptionr   r   )rJ   rW   r5   r   rz   s        r   waitzSubagentLifecycleService.wait  sH    f%%>(-t@P    o6666 W W W,V]FL%QUVVVVV   ^ 	 	(v|V]$-F 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	s)   A &B
>	B
	B
"CCCreasonr$   rb   c                  |                      |          }|t          dd          S t          j        5  |j        #t          dd|j                  cd d d            S |j        }t          j        |_        t          j	                    |_
        d d d            n# 1 swxY w Y   |t          ddt          j                  S 	 t          |d|d d                    }n,# t          $ r t          ddt          j                  cY S w xY w|st          ddt          j                  S t          dt          j                  S )	NFT)re   )rd   rX   )rf   rX   z"Lifecycle cancellation requested: i  )rX   )r   rb   r   r   r{   rX   ry   r   r   r   rY   r   r   )rJ   rW   r   r   ry   rc   s         r   cancelzSubagentLifecycleService.cancel$  s   f%%>'dCCCC^ 	, 	,}(+D  	, 	, 	, 	, 	, 	, 	, 	,
 LE(9FL $	F	, 	, 	, 	, 	, 	, 	, 	, 	, 	, 	, 	, 	, 	, 	, ='4}/M   	-JF4C4LJJ HH  	 	 	'4}/M     	  	'4}/M    $D0NOOOOs)   B 0BB #B C" "&D
Drh   c                $   |                      |          }|t          |t          j        dd          S t          j        5  |j        |j        cd d d            S t          |j        |j        dd          cd d d            S # 1 swxY w Y   d S )NFr   )ro   	NOT_READY)	r   rh   r   r    r   r   r{   rW   rX   r   s      r   r{   zSubagentLifecycleService.resultB  s   f%%>!%%5	    ^ 	 	}(}	 	 	 	 	 	 	 	 "v|U  	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	s   BBB	B	ru   c                    |                      |          }|t          dt          j        d          S t          j        5  t          d|j                  cd d d            S # 1 swxY w Y   d S )NFRECONNECT_UNAVAILABLET)r   ru   r   r    r   r   rX   r   s      r   	reconnectz"SubagentLifecycleService.reconnectR  s    f%%>*},.E   ^ 	? 	?*4>>	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	? 	?s   A!!A%(A%Optional[_Record]c                   t          |t                    r+t          |j                  t          us|j        t
          k    rd S t          |j        t                    r0|j        r(|j        t          |j        t                    r|j	        t          |j	        t                    rt          |j
        t                    st          |j
        t          t          f          rt          j        |j
                  r|j        t          |j        t                    rp|j        t          |j        t                    rOt          |j        t                    r5t          |j                  t          ust          |j        t                    sd S t)          j        |j        |                     |j        |j        |j
                            sd S |                                 }t          t1          |dd          pd          pd }||j        k    rd S t2          j        5  t2          j                            |j                  cd d d            S # 1 swxY w Y   d S )Nr   r   )
isinstancer;   typer=   r<   r   r>   r$   r.   r/   r@   r^   r?   mathisfiniterA   r*   r)   rB   rC   hmaccompare_digestr   r   r   r   r   r   r   )rJ   rW   r   active_parent_ids       r   r   z SubagentLifecycleService._record[  sq   6>22	F+,,C77&*AAA46-s33	%	 (4"6#;SAA 5 %1"6#8#>> 2 &+T22 2 f/#u>>	 2
 =!233 2 +JvPS4T4T+(FL#1N1N(fk3// )FL!!,,f/55 - 4""F$<f>O 
 
 	 4,,..wv|R@@FBGGO4v7774^ 	= 	=$(();<<	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	= 	=s   $IIIc                 ^   t          j                     t          z
  fdt          j                                        D             } | D ]c}t          j                            |          }|j        j        r6t          j                            |j        j	        |j        j        fd           ddS )z@Retain terminal snapshots for a bounded period, never live work.c                L    g | ] \  }}|j         |j        |j        k     |!S rG   )r{   rn   ).0r>   r   cutoffs      r   
<listcomp>z<SubagentLifecycleService._cleanup_locked.<locals>.<listcomp>  sH     
 
 
#V}(#/#f,,	  -,,r   N)
r   _TERMINAL_RETENTION_SECONDSr   r   itemspoprW   r/   r   r.   )expiredr>   r   r   s      @r   r   z(SubagentLifecycleService._cleanup_locked  s     ::
 
 
 
'0'8'>'>'@'@
 
 
 # 	 	K&**;77F}+ &**]4fm6RS  	 	r   r   rx   r%   r   r   c                   t           j        5  |j        t          j        urt          j        |_        t          j                    |_        |j        |_        d d d            n# 1 swxY w Y   	 ddl	m
}  |d||j        |          }t          |t                    r#t          |                    dd                    nd}|dk    rt          j        }n@|dk    r.|j        t          j        k    rt          j        nt          j        }nt          j        }t          |t                    r|                    d          nd }|t          |          d t(                   nd }t          |t                    r|                    d          nd }	t+          |j        |d|t          j                    |j        |t          j        k    rd n|                                |	rt          |	          d t(                   nd t          |t                    rd	|                    d	d          ini t          |t                    rd
|                    d
d          ini 
  
        }
n~# t0          $ rq}t+          |j        t          j        d|j        t          j                    t3          |          j        t          |          d t(                             }
Y d }~nd }~ww xY wt7          j        |
          }|                    dd            t7          j        |
t?          j         tC          j"        |dt                    #                                          $                                          }
t           j        5  d |_        |
|_%        |
j&        |_        |
j'        |_'        |
j'        pt          j                    |_        d d d            d S # 1 swxY w Y   d S )Nr   )_run_child_lifecycler   errorr_   interruptedrk   T	api_callsduration_seconds)rk   rn   rm   ro   rp   rq   rr   )rm   rn   ro   rp   rs   )	sort_keysr   )rs   )(r   r   rX   r   r   r   r   rm   rY   r   r   ry   r   r9   r$   r   r   r   r   r   _MAX_RESULT_CHARSrh   rW   upperr   r   r   r7   rH   r   replacehashlibsha256jsondumpsencode	hexdigestr{   ri   rn   )rJ   r   r%   r   r   rawr   rX   rk   r   r{   rR   payloads                r   r   zSubagentLifecycleService._run  s;   ^ 	2 	2|=#AAA,4 $	F & 1F		2 	2 	2 	2 	2 	2 	2 	2 	2 	2 	2 	2 	2 	2 	2
1	@@@@@@&&q$fEEC3=c43H3HUCGGHg..///g  $$%/=(( |}'EEE "++&2  &,,6sD,A,AKcggi(((tG:A:Mc'll#5$5#566SWG(23(=(=GCGGG$$$4E#!Y[[!,M333 &*T\\^^@EOc%jj);*;);<<4c4(( SWW[!-D-DEE c4(((&0BA(F(F( ( %  FF(  		 		 		#$!,!Y[[%)#YY%7!#hh'9(9'9:  FFFFFF		 $V,,M4((($
7dC@@@GGII ikk	
 
 
 ^ 	C 	CFL"FM!0FL"("5F & 3 Bty{{F	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	C 	Cs?   A	A""A&)A&.G.I 
K'A'KK7AO

OOr>   r.   r&   r@   r?   c                    |  d|pd d|d                                 }t          j        t          |t          j                                                  S )N|r   z.6f)r   r   new_SECRETr   r   r   )r>   r.   r@   rL   s       r   r   z$SubagentLifecycleService._capability  sV     KK!2!8bKK:KKKRRTTx77AACCCr   c                   t          | t                    rPt          | j        t                    r6| j                                        rt          | j                  t          k    rt          d          | j        Ft          | j        t                    rt          | j                  t          k    rt          d          | j
        dvrt          d          | j        t          d          | j        t          d          | j        rt          d          	 t          t          j        t!          | j                  d	                                                    }n)# t&          t(          f$ r}t          d
          |d }~ww xY w|t*          k    rt          d          | j        rddlm} t3          | j                  t3          |          z
  }|r3t          dd                    t7          |                     d          t9          |dd           }|Et3          | j                                      t3          |                    st          d          d S d S d S )Nz<goal must be a non-empty string of at most 16000 characters.z5context must be a string of at most 32000 characters.>   r(   orchestratorz&role must be 'leaf' or 'orchestrator'.zMPer-launch timeout is not supported; configure delegation timeout explicitly.z[working_directory is not supported because Hermes delegates use isolated task environments.zbPer-tool blocking is not supported; use allowed_toolsets. Hermes always blocks unsafe child tools.T)r   z#metadata must be JSON-serializable.zmetadata exceeds 8192 bytes.r   )TOOLSETSzUnknown toolsets: z, .enabled_toolsetsz4Requested toolsets would broaden parent permissions.)r   r#   r%   r$   striplen_MAX_GOAL_CHARSr   r'   _MAX_CONTEXT_CHARSr)   r5   r-   r,   r   r   r9   r3   r   rO   rP   _MAX_METADATA_BYTESr+   r   r   r   joinsortedr   issubset)r   r   metadata_bytesrR   r   unknownenableds          r   r   z*SubagentLifecycleService._validate_request  s    7$9::	glC00	 <%%''	 7<  ?22(N   ?&7?C00 '7?##&888(G   <777()QRRR".(_   $0(m     	(t  	Y 
4 011TBBBIIKK NN :& 	Y 	Y 	Y()NOOUXX	Y///()GHHH# 	))))))'233c(mmCG ,F6'??)C)CFFF   f&8$??G"3w/G+H+H+Q+QG, ," -J  	 	 #"""s   AE% %F6FF)r   r   rD   r~   )r   r#   rD   r;   )rW   r;   rD   rV   )rW   r;   r5   r4   rD   r]   )rW   r;   r   r$   rD   rb   )rW   r;   rD   rh   )rW   r;   rD   ru   )rW   r;   rD   r   r   )r   rx   r%   r$   r   r   rD   r~   )r>   r$   r.   r&   r@   r?   rD   r$   )r   r#   r   r   rD   r~   )r   r   r   r   r   r   r   r   r   r{   r   r   staticmethodr   r   r   r   r   r   r   r   r      sZ        < < < <> > > >@R R R R MQ     *P P P P<    ? ? ? ?(= (= (= (=T    \$EC EC EC ECN D D D \D 5 5 5 \5 5 5r   r   )r   r   )rD   r   );r   
__future__r   contextvarsr7   enumr   r   r   r   secretsr   r   
contextlibr   concurrent.futuresr   r   typingr   r   r	   r
   agent.interrupt_compatr   r   r   r   r   r   r   rP   r   r$   Enumr   	dataclassr#   r;   rV   r]   rb   rh   ru   rx   r}   r   tools.daemon_poolr   _DaemonExecutorr   token_bytesr   
ContextVarr   r6   r   r   r   r   r   r   <module>r     s     # " " " " "                    % % % % % % 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 9 9 9 9 9 9    # K K K K KZ K K K	 	 	 	 	C 	 	 	 d###, , , , , , , $#, d###P P P P P P P $#P. d###% % % % % % % $#% d###% % % % % % % $#% d###1 1 1 1 1 1 1 $#1 d###& & & & & & & $#& d###% % % % % % % $#% , , , , , , , ,E E E E E E E E IKK	 J I I I I IO>PQQQ	
'
b
!
!4JK4J&5 5 5     
 * * * *& & & &
a a a a a a a a a ar   