xjRldZddlmZddlZddlZddlZddlmZddlm Z ddl m Z m Z m Z mZddlmZdZd Zhd Zhd Zhd Zhd ZejdZejdZejdZejdZGddeZedGddZedGddZedGddZ dJd!Z!dKd%Z"dLd'Z#dMd,Z$dNd0Z%dOd4Z&dd5dPd7Z'dQd:Z(dRd<Z)dSd?Z*dTd@Z+ddAdUdDZ,dVdEZ-dWdGZ.dXdIZ/dS)Ya>Compatibility helpers for Agent Plugins v1 portable directory packages. This module validates the versioned portable format locally and translates its supported components into records consumed by Hermes' existing skill and MCP runtimes. It deliberately performs no schema fetching and imports no plugin Python code. ) annotationsN) dataclass)Path)AnyDictMappingTuple) yaml_loadz:https://agent-plugins.org/schemas/1.0.0/plugin.schema.jsonz7https://agent-plugins.org/schemas/1.0.0/mcp.schema.json> nameauthorlicenseversionhomepagekeywords extensions repository description$schema>urlr email>cwdenvargstypecommand>rrheadersz3^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$z"^(?!.*--)[a-z0-9]+(?:-[a-z0-9]+)*$z\$\{(PLUGIN_ROOT|PLUGIN_DATA)\}z^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$ceZdZdZdS)AgentPluginErrorz+Fatal portable manifest validation failure.N)__name__ __module__ __qualname____doc__>7>;;<< \4#7 8VVV%KKcKKLLRUUV eT " "F%DDDEEE Ls(+A!AA!(tuple[dict, list[AgentPluginDiagnostic]]c|dz }t||r|stdt|d}g}t t |t z D]=}|tdd|| |>| dtkrtd| d}t|tr7d t|cxkrd krnnt|td d D]4}||vr.t||tstd |d5d|vrE|d}t|t"rt%d|Drtdd|vr|d}t|t&stdt |t(z }|s+t%d|Drtdd|vr|d} t| t&s9|tdd| dn:t%d| Drtd||fS)Nz plugin.jsonz9plugin.json must be a regular file within the plugin rootrGr7z!ignored unknown top-level field: rzCplugin.json declares an unsupported or missing Agent Plugins schemar @z0plugin.json name does not satisfy v1 constraints)rrrrr z plugin.json z must be a stringrc3BK|]}t|t VdSNrRr).0rSs r% z%_validate_manifest..s@1 1 +0 5#&& &1 1 1 1 1 1 r$z0plugin.json keywords must be an array of stringsr z$plugin.json author must be an objectc3BK|]}t|t VdSr\r]r^s r%r`z%_validate_manifest..s/RRj444RRRRRRr$zFplugin.json author may contain only string name, email, and url fieldsrz#ignored non-object extensions fieldc3BK|]}t|t VdSr\)rRrHr^s r%r`z%_validate_manifest..s/NNZt,,,NNNNNNr$z6plugin.json extension namespace values must be objects)rFis_filerrUsortedset_PLUGIN_FIELDSappendr(popgetPLUGIN_SCHEMA_V1rRr)len_PLUGIN_NAME_RE fullmatchlistanyrH_AUTHOR_FIELDSvalues) r0 manifest_pathr7r:fieldr rr unknownrs r%_validate_manifestruasL=(M =$ ' '\}/D/D/F/F\Z[[[ mDDDH/1KH 677 !*.YRW.Y.Y Z Z     U||I"222 Q    <<  D tS ! !SCII#########  $ $T * * 2QRRRPLL H  Z%E%E "#J%#J#J#JKK KXJ'(D)) WS1 1 4<1 1 1 . .  W##UVV V8(#&$'' K"#IJJ Jf++.  cRR&--//RRRRR "X xl+ *d++ ]   % E    LL & & & & NN*:K:K:M:MNNN N N ]"#[\\ \ [  r$r3r2directory_name str | Nonec|d}t|tr=||ks7dt|cxkrdkrnnt|dS|d}t|trdt|cxkrdksndSd|vrt|dtsd Sd |vr;|d }t|trdt|cxkrd ksnd Sd |vrJ|d }t|t r+td|DrdSd|vrt|dtsdSdS)Nr rYrZzBname must match the directory and satisfy Agent Skills constraintsrizAdescription must be a non-empty string of at most 1024 charactersr zlicense must be a string compatibilityiz5compatibility must be a string of 1 to 500 charactersmetadatac3tK|]3\}}t|t pt|t V4dSr\r]r_keyrSs r%r`z+_valid_skill_frontmatter..sY1 1 U3$$ $ BJuc,B,B(B1 1 1 1 1 1 r$z.metadata must map string keys to string valuesz allowed-toolszallowed-tools must be a string) rirRr)rk_SKILL_NAME_RErmrHroitems)r3rvr rryrzs r%_valid_skill_frontmatterrs ??6 " "D tS ! !T > ! !CII#########  # #D ) ) 1SS//-00K k3 ' 'SqC 4D4D/L/L/L/L/L/L/L/LRRK ;y3I3(O(O))+%%#O4 --- KQ#m:L:L5S5S5S5SPS5S5S5S5SJJ[  z*(D)) DS1 1 &nn..1 1 1 . .  DDC+%%jO$c//%0/ 4r$r:list[AgentPluginDiagnostic]tuple[AgentPluginSkill, ...]c |dz }|s|sdSt||r|s%|t dddSg} t |d}n>#t$r1}|t dd|Yd}~dSd}~wwxYw|D]i}|dz }|r|s1d|j }t||r| s$|t |d  | d } | d } | d stdtjd| dd} | td t#| d| dz} n%#t&$r}td||d}~wwxYwt)| t*std| } nK#tt,tf$r1}|t |d|Yd}~d}~wwxYwt/| |j } | r%|t || |t1|j | d|d|dt+| kt5|S)Nr8r#z#skills must be an in-root directoryc|jSr\)r )r;s r%z"_discover_skills..s$)r$)r}zcannot list skills: zSKILL.mdzskill:z'SKILL.md must be a regular in-root filerJrKuz---zmissing YAML frontmatterz \n---\s*\nzunterminated YAML frontmatterzinvalid YAML frontmatter: z"YAML frontmatter must be an objectzinvalid SKILL.md: rTr?)r rr0r1r3)exists is_symlinkrFis_dirrgr(rditerdirrCr rcrOlstrip startswithrEresearchr start ExceptionrRrHrPrr/rAtuple)r0r: skills_rootr8childrenrTchildr1r*content end_matchparsedr3errors r%_discover_skillsrs/K      (>(>(@(@r ; % %[-?-?-A-A !(,Q R R   r%'F+--//5K5KLLL 0;WRU;W;WXXYYYrrrrr( ( :%||~~ X__%6%6  %%%x&& h.>.>.@.@    %e-VWW     (('(::GnnX..G%%e,, = !;<<< -==I  !@AAA N"71y/@/@1/D+D#EFF N N N !Cc!C!CDD#M Nfd++ G !EFFF KKz2      4U.s\%++a..-Ir$)r)_PLACEHOLDER_REsub)rSrr6rs @r%_expandrsE;''9~~L   IIII5 Q QQr$expand_placeholdersrc,|rt|||n|}|dr|}||ddz }ni|dks|dr|}t|}n<|dks|dr|}t|}ntd|d } ||d n/#t ttf$r}td |d}~wwxYw|S) N./z${PLUGIN_ROOT}z${PLUGIN_ROOT}/z${PLUGIN_DATA}z${PLUGIN_DATA}/z:path must start with ./, ${PLUGIN_ROOT}, or ${PLUGIN_DATA}Fr?zpath escapes its resolved root)rrrrErArBrCrD) rSrr6rexpandedbase candidateresolvedrTs r%_resolve_scoped_pathrsE:MWwuk9555RWH  W8ABB<' " " "e&6&67H&I&I "NN " " "e&6&67H&I&I "NN UVVV   ..HDT\\\778888 \: .DDD9::CD Os;)C%%D<D  Drobjectc|dSt|tsdSt}|D]\}}t|trMt |3t|trd|vsd|vs||vrdS||dS)NTF  ) rRrHrerr)_HEADER_NAME_RErmloweradd)rseenr rSs r%_validate_headersr"st gt $ $uUUD}}   e4%% ((..6eS))7u}}u}}zz||t##55  4r$rcXddlm}t|tr|st d ||}n%#t$r}t d||d}~wwxYw|j}|dvrt d|j|jt d|j rt d |j }|st d |d krNd }|d krd}n2ddl } | |j }n#t$rd }YnwxYw|st d|S)upValidate a portable remote MCP URL per the v1 spec and return it. Rules (Agent Plugins v1 §7.2.1): absolute http(s) URL, no user information, no fragment; non-loopback endpoints must use HTTPS. HTTP is allowed only when the host is exactly ``localhost`` or an IP literal in a loopback range. No placeholder or environment expansion is performed. r)urlsplitzurl must be a non-empty stringzurl is not parseable: N>httphttpsz url scheme must be http or httpsz%url must not contain user informationzurl must not contain a fragmentzurl must have a hostrF localhostTznon-loopback url must use https) urllib.parserrRr)rEschemerusernamepasswordfragmenthostname ipaddress ip_address is_loopback)rrrrTrhostloopbackrs r%_validate_remote_urlr6s&%%%%% c3  ;s;9:::B# BBB7#7788cAB ] " "F &&&;<<< "fo&A@AAA <:;;; ?D 1/000  ;  HH     !$//55A ! ! !  ! @>?? ? Js' : AAA,D DDconfigDict[str, Any]cTt|tz rtdt|d}t |dstd|dd}|d}|rt ||d<|S)aTranslate a portable ``streamable-http`` entry into native MCP config. The returned record targets Hermes' existing URL-based MCP runtime. ``strict_redirect_headers`` instructs the runtime to drop the configured headers on any cross-origin redirect, which the v1 spec requires for portable packages (configured headers must not be forwarded to a different origin without explicit user authorization). zunknown remote fieldrrzinvalid headersT)rstrict_redirect_headers)re_REMOTE_FIELDSrErrirrH)rr translatedrs r%_translate_remoteras 6{{^#1/000 vzz%00 1 1C VZZ 22 3 3,*+++#'""Jjj##G. $W 9 r$ct|tz rtd|d}t |t r|rd|vrtd|dr!t t|d}nEtd|Drtd d |vsd |vs|d vrtd |}|dg}t |trtd|Drtd|di}t |tr+td| Drtdd|D}d|vsd|vrtd|d}|} n5t |t stdt|} fd| D} t | d<t | d<|fd|D| t | dS)Nzunknown stdio fieldrz,command must be a non-empty executable tokenrFrc3>K|]}|VdSr\)isspace)r_ characters r%r`z#_translate_stdio..s. : :YY   : : : : : :r$z)command must contain one executable token/\>...z2command must be a bare executable or begin with ./rc3BK|]}t|t VdSr\r]r^s r%r`z#_translate_stdio..s/(V(VZs-C-C)C(V(V(V(V(V(Vr$z args must be an array of stringsrc3tK|]3\}}t|t pt|t V4dSr\r]r|s r%r`z#_translate_stdio..sY(( C sC  > 5#(>(>$>((((((r$z)env must map string keys to string valuescZh|](}tjdkr|n|)S)nt)osr upper)r_r}s r% z#_translate_stdio..s.GGGCrw$ CGGGr$rrz(PLUGIN_ROOT and PLUGIN_DATA are reservedrzcwd must be a stringc:i|]\}}|t|Sr#r)r_r}rSr6rs r% z$_translate_stdio..s88BUWUK 3 3r$c2g|]}t|Sr#r)r_rSr6rs r% z$_translate_stdio..s%JJJE Y77JJJr$)rrrr) re _STDIO_FIELDSrErirRr)rrrornrHr) rrr6r command_valuerrenv_keysr cwd_valuetranslated_envs `` r%_translate_stdiorzs 6{{]"0.///jj##G gs # #I7If6G6GGHHH$  $)       : :' : : : : : DEEE 47??g.D.DMNNN ::fb ! !D dD ! !=S(V(VQU(V(V(V%V%V=;<<< **UB  C c4 FC(())++(((%%FDEEEGG3GGGH  MX$=$=CDDD **U  C { S ! !F/000(k9EE FIiikkN%( $4$4N=!$' NNN=! JJJJJTJJJ9~~   r$) create_datarDict[str, Dict[str, Any]]c |dz }|s|siSt||r|s%|t ddiS t |d}nI#t$r<}|t dt|icYd}~Sd}~wwxYwt|ddhkr%|t ddiS| dtkr%|t ddiS| d}t|ts%|t dd iSi}|D]\} } d | } t| tr| rt| ts$|t | d [| d } | d kr t| ||} |rj|ddt#| d} |||ddn#t&$rYnwxYw| || <#t(t&f$r;}|t | t|Yd}~Ad}~wwxYw| dkr] t+| || <d#t&$r;}|t | t|Yd}~d}~wwxYw| dkrt| t,z s_t| dtr7| dr"t/| ds%|t | dM|t | d| dv|t | d|S)Nzmcp.jsonmcpz'mcp.json must be a regular in-root filerXr mcpServersz'mcp.json has an invalid top-level shapez'mcp.json declares an unsupported schemazmcpServers must be an objectzmcp:zinvalid server entryrstdioT)parentsexist_okrzstreamable-httpsserrzinvalid remote entryz portable z transport is not supportedzunknown MCP server type)rrrFrcrgr(rUrr)reri MCP_SCHEMA_V1rRrHrrmkdirrrBrErCrrr)r0r6r:rmcp_pathrrTserversrr serverr* server_typetranslated_servercwd_paths r% _discover_mcprsj H ??  X%8%8%:%: 8T " "(*:*:*<*< !%)R S S    "8:>>> 0CAABBB  6{{y,/// !%)R S S     zz) -- !%)R S S    jj&&G gt $ $ !%)G H H    ,.J .X.X ft $$$ D  648P8P    4U)>??  ""#8@V#W#WXXXX"")LKLLL   4Urs|#""""" !!!!!!,,,,,,,,,,,,''''''PI    *))999 +++"*:ABB"*?@@"*>??66666z666 $  $######## $ 3 3 3 3 3 3 3 3:!:!:!:!zD<<<<~RRRR!% 6(((((V27777~ UUUUUUp6((((      r$