yjPdZddlmZddlZddlZddlZddlZddlmZddl m Z ddl m Z dZ Gdd eZGd d eZGd d eZGddeZGddeZGddeZeGddZeGddZejdZddd=d!Zd>d$Zd?d'Zd@d)ZdAd+ZdBd-ZdCd1ZdDd3Z dEd5Z! dFdGd6Z" dFdHd:Z#dId;Z$dddJd<Z%dS)KuSingle resolver for every media source -> bytes + mime. All source handling (data:/http(s)/file/local/container) funnels through :func:`resolve_image_source` so size and magic-byte checks are enforced exactly once. Returns raw bytes (not a path): the downstream step is base64 -> data URL (RFC 2397) and provider base64 content blocks. Images are the default and the historical purpose. Callers whose argument takes video opt in via ``permitted=("video",)`` — the same confinement and credential-guard pipeline applies, and only the type check at the end differs (extension-table typing plus an mp4 magic sniff, rather than image magic bytes). Every existing call site keeps the image-only default unchanged. Security (terminal-backend confinement, GHSA-gpxw-6wxv-w3qq): under a non-local terminal backend the file tools are confined to the sandbox (SECURITY.md 2.2), but vision read images host-side. This resolver enforces the same boundary: * local backend -> read any host path (chosen posture, unchanged) * non-local backend: path in a media cache -> host-read (the gateway/download caches live on the host and are bind-mounted into the sandbox) path anywhere else -> read the bytes *inside the sandbox* via exec-read (the agent can already ``cat`` any container file; this stays within the sandbox boundary and never reaches the host's ``/etc/passwd`` / ``~/.ssh``). So a prompt-injected ``vision_analyze('/etc/passwd')`` under Docker reads the *container's* file (what every other tool sees), not the host's — no escape — while container-only images (tmpfs ``/workspace``, root-owned) are still deliverable. This is the unified delivery + confinement model: the same mechanism that fixes "vision can't see container files" also closes the escape. ) annotationsN) dataclass)Path)Optionali c(eZdZddddfdZxZS) ImageResolutionErrorsrcoriginmessagestrr r cht|||c|_|_dSN)super__init__r r )selfr r r __class__s 8/home/ragecks/.hermes/hermes-agent/tools/image_source.pyrzImageResolutionError.__init__5s/ !!! #V$+++)r rr rr r)__name__ __module__ __qualname__r __classcell__)rs@rrr4sL35R,,,,,,,,,,,,rrceZdZdS)UnsupportedSchemeNrrrrrrr:DrrceZdZdS) SourceUnsafeNrrrrr!r!>rrr!ceZdZdS)SourceTooLargeNrrrrr#r#Brrr#ceZdZdS)SourceNotFoundNrrrrr%r%Frrr%ceZdZdS) NotAnImageNrrrrr'r'Jrrr'ceZdZUdZded<dS)ResolveContextN Optional[str]task_id)rrrr+__annotations__rrrr)r)Ns#!G!!!!!!rr)c.eZdZUded<ded<ded<dS) ResolvedImagebytesdatarmimer N)rrrr,rrrr.r.Ss+KKK IIIKKKKKrr.z^[A-Za-z][A-Za-z0-9+.\-]*://image permittedr rctxr5tuplereturnc\Kt|tr|stdt||}|dr%t |\}}t ||d||S|drHt|}|rt||t t|d{Vdd||St |r8| dstd || dr|tddn|}tt j|}t'||} | | r d d lm} n#t.$rd} YnwxYw| K | t| n1#t0$r$} tt| |d d} ~ wwxYwt3j| jd{V}t |dd ||St9rtd|d|d t;||||d{VS)Nzimage_url is requiredr data:r0)http://https://r httpzfile://zgUnrecognized image source scheme. Use an http(s) URL, a local file path, a file:// URI, or a data: URL.r)raise_if_read_blockedfiler zmedia file not found: '') isinstancerstripr% startswith_resolve_data_url _finalize_http_block_reasonr!_download_to_bytes _SCHEME_REmatchlowerrlenrospath expanduser_permitted_host_read_targetis_fileagent.file_safetyr? Exception ValueErrorasyncio to_thread read_bytes_is_local_terminal_backend_resolve_container_fallback) r r6r5sr0r1reason candidatep host_targetr?excs rresolve_image_sourcer`_s c3  Dsyy{{D4#c((CCCC A||G;&q)) dtVQ :::||+,,P#A&&  .v1--- -1!44444444b&!YOOO 17799#7#7 #B#B  8    '(ggii&:&:9&E&EL#i..//""1I RW   * *++A .a55K;#6#6#8#8 ) ? ? ? ? ? ? ? ) ) )$( ! ! ! ) , C%%c+&6&67777 C C C"3s886BBBB C&{'=>>>>>>>>r61i888!##S;q;;;6RRRR-QQ BB B B B B B BBs*G!! G0/G06H H=H88H=rZtuple[bytes, str]c|d\}}}d|vrtd|dd|tddddd pd }t|d zd zt krt d |dd tj|d}n.#t$r!}td||ddd}~wwxYw||fS)N,z;base64z data: URL must be base64-encoded@r:r;;rapplication/octet-streamzdata: URL exceeds size limitTvalidatezinvalid base64 in data: URL: ) partitionr'rLsplitrC_MAX_INGEST_BYTESr#base64 b64decoderS)rZheader_payloaddeclaredr0r_s rrErEs"S))FAw;3B3HHHHc'llmm$**32215;;==[A[H G qQ!222;3B3HHHHL$777 LLL>>>AcrcFKKKKL >s4C C6C11C6urlr*cddlm}ddlm}||sdS||}|r|dpdSdS)u Return a human-readable block reason, or None when the URL is allowed. Pre-flight short-circuit: policy-blocked URLs are refused BEFORE any network I/O. ``_download_image`` re-checks policy internally (per attempt and against the final redirect target) — that second evaluation is intentional, not redundant: this one guarantees no bytes move for a blocked URL; the inner one covers redirects and non-resolver callers. Preserves the specific website-policy message so the agent sees *why*. r) is_safe_url)check_website_accesszblocked: unsafe or private URLr zblocked by website policyN)tools.url_safetyrwtools.website_policyrxget)rurwrxblockeds rrGrGsv-,,,,,999999 ;s  0//""3''GE{{9%%D)DD 4rr/cKddl}ddlm}|dd5}t |j}dddn #1swxYwY |||d{Vt j|jd{V | dS#t$r$}tt||d d}~wwxYw#| dwxYw) Nr)_download_imagez.imgF)suffixdeleteT) missing_okr>r ) tempfiletools.vision_toolsr~NamedTemporaryFilernamerUrVrWunlinkPermissionErrorr!r)rurr~tftmpr_s rrHrHsYOOO222222  $ $F5 $ A AR27mm$oc3'''''''''&s~666666666 d #### ===3s88V<<<<= d ####s5AA  A 0B C#CCC C"boolcxtjdddvS)zTrue when the terminal backend runs directly on the host. Mirrors ``tools.browser_tool._is_local_backend`` and terminal_tool's own dispatch, which key off ``TERMINAL_ENV``. TERMINAL_ENVlocal)rr )rMgetenvrCrKrrrrXrXs3 9^W - - 3 3 5 5 ; ; = = NNrlistc^ddlm}|}|dz |dz |dz |dz |dz |dz |d z gS) a-Agent-managed media cache directories under HERMES_HOME (host side). The only host paths vision may read under a non-local backend: gateway- downloaded inbound media and the tools' own URL-download temp dirs. Covers the consolidated ``cache/`` layout and the legacy flat directories. r)get_hermes_homecacheimages image_cache audio_cache video_cachetemp_vision_imagestemp_video_files)hermes_constantsr)rhomes r_media_cache_rootsrse100000 ?  D w x } } } ## !! rr]rOptional[Path]ctr' |S#t$r|cYSwxYwddlm}t |t |} |}n#t$rYdSwxYwtD]=} |||cS#t$rY:wxYwdS)aReturn the host path to read, or ``None`` if a host read is not permitted. - Local backend: any path is permitted (chosen posture). Returns ``p``. - Non-local backend: permitted only if the path resolves inside a media cache root. A container-visible cache path (e.g. ``/root/.hermes/cache/ images/x.png``) is first translated back to its host mount; anything that is not under a cache returns ``None`` so the caller routes it to the in-sandbox exec-read instead of reading the host filesystem. r)from_agent_visible_cache_pathN) rXresolverStools.credential_filesrrrr relative_torT)r]r6rhost_candidaterealroots rrPrPs"## 99;;    HHH EDDDDD77A??@@N%%'' tt"$$    T\\^^ , , ,KKK    H  4s0$ 33"A77 BB(C CCr+cP|sdS ddlm}||S#t$rYdSwxYw)Nr)get_active_env)tools.terminal_toolrrS)r+rs r_get_active_envrsX t666666~g&&& tts  %%NonecT|sdS ddlm}||dS#t$rYdSwxYw)uLazily bring up the sandbox (SSH/Docker/…) before an in-sandbox read. Unlike the terminal tool, vision never triggered environment creation, so a session whose first action is ``vision_analyze`` on a container-only path under a non-local backend found no active env and failed — until a terminal command happened to create one (issue #62825). Best-effort: any failure just leaves the env absent and the caller hits the existing fail-closed error. Nr)ensure_task_env)rrrS)r+rs r_ensure_container_envrs`  777777          s  ''c(Kddl}ddl}t|jt |j}|t d|d|d|t|}dtdzd |d }dd d } td D]V} |j |j |d{V} | dddkrn| dkr|j dd{VW| dddkr| dpd } t!d| Dd } | rd| dddnd } t d|d| |d t#j| dd d}n)#t&$r}t)d|d||d}~wwxYwt+|tkrt-d|dt/|d d||S)a"Read the image bytes inside the sandbox (fail-closed when none exists). Reached when a host read is not permitted or the host file is absent. The agent can already ``cat`` any container file (file_operations.py reads root-owned mode-600 files this way), so this stays within the same sandbox boundary and never touches the host filesystem. ``--`` stops a leading-dash path from being parsed as a ``base64`` option; ``base64 -w0`` is GNU-only, so pipe through ``tr -d`` for BusyBox. Fail-closed: if there is no active sandbox env we refuse rather than falling back to a host read, so a non-cache host path under a sandbox never leaks. Cold-start retry: under Docker the very first exec against a freshly started container can fail (empty pipe / partial setup) while an identical second call succeeds. We retry once with a short delay before giving up, so callers don't see "could not read inside the sandbox" on a file that is verifiably readable on the immediate retry. See #76566. Diagnostic: when every attempt fails, the container's own output (stderr + stdout) is folded into the raised error so the user can distinguish "no such file" from "permission denied" from "container never came up" instead of staring at one opaque message. rNrAz[' is not reachable inside the sandbox and no active sandbox session is available to read it containerr zhead -c rfz < z | base64 | tr -d '\n'r ) returncodeoutputrg333333?rc3fK|],}||V-dSr)rC).0lns r z._resolve_container_fallback..rs7>>R288::>bhhjj>>>>>>rz ()zcould not read 'z' inside the sandboxTrjz%sandbox returned non-image data for 'z': r:media exceeds size limit)rUshlexrr+rr%quoterrnrangerVexecuter{sleeprC splitlinesnextrorprSr'rLr#rF)r]r6r r5rUrenvqpcmdlast_resattemptdiagfirstrr0r_s rrYrY0s4NNNLLL #+&&& #+ & &C { / / / /K))) ) SVV  B J&* J Jr J J JC$%44H88&&**3;<<<<<<<< << a ( (A - - E a<< '-%% % % % % % % %||L!$$)) X&&,"3355@@BB>>4>>>CC(-5$eDSDk$$$$2 >q > >f > >K))) )W Xr : :TJJJ WWWLLLsLLRUVVVVW 4yy$$$7SUUUU T2{C ; ;;s*F.. G8GGr0 declared_mimer cddlm}t|tkrt d||||}|(d|vrt d||t |||Sd|vr0d |dd vrt |d |Sd |vr6t||}|t |||St d ||t d||)uIntrinsic-correctness chokepoint: ingest byte cap + type check. The cap here is the generous 50MB *ingest* budget, not the 20MB provider payload cap — a 20-50MB image must survive this step so the call site can resize it under the payload cap. See ``_MAX_INGEST_BYTES``. Images are typed by magic bytes. Video (opt-in via ``permitted``) is typed by the extension table plus an mp4 container sniff: extension typing is sufficient because every downstream consumer re-validates — the upload gateway signs the content type into its presigned URL and the vendor rejects undecodable input — so a wrong guess is a clean rejection there rather than a hole here. r)"_detect_image_mime_type_from_bytesrr Nr3z3source is an image, but this argument takes a video)r0r1r s+> > >$_VLLLL)'c22  ! dFKKK KJPS\bcccc 7S P P PPrcddlm}ddlm}t|r||jn|}|t|}||St|dkr|dddkrd SdS) zVideo MIME from the extension table, else the mp4/mov container magic. The magic fallback covers extensionless sources (data: URLs, URLs with query strings): ISO base-media files carry ``ftyp`` at offset 4. r)urlsplit)_detect_video_mime_typeN risftypz video/mp4) urllib.parserrrrIrJrNrrL)r0r rr path_part by_extensions rrrs &%%%%%::::::&0&6&6s&;&;D ""I**4 ??;;L 4yy2~~$qs)w..{ 4rcNK|pd}|r'|dr|St|t ||d{V}t j|jd}|j pd}d|d |S) ueConvert a path-like media source into a ``data:`` URL via the resolver. Generation tools (image_generate / video_generate) forward model-supplied source images to provider plugins, which historically read local paths off the HOST filesystem regardless of terminal backend. Under a non-local backend that is both broken (the file usually lives in the sandbox, so the host read misses) and inconsistent with the confinement model vision/video analysis enforce (GHSA-gpxw-6wxv-w3qq): the sandbox boundary should govern every model-supplied path. This helper is the dispatch-layer chokepoint: URL-shaped sources (http/https/data) pass through untouched; anything path-like resolves through :func:`resolve_image_source` — media-cache host reads, bounded in-sandbox exec-read, lazy env bring-up, credential guard, ingest cap — and comes back as a ``data:`` URL every provider already accepts. Callers apply this only under a non-local terminal backend: on the local backend providers keep their existing host-side reads (chosen posture, zero behavior change). r )r<r=r;)r+r4Nasciirgr;z;base64,) rCrKrDr`r)ro b64encoder0decoder1)r r+r5rZresolvedencodedr1s r resolve_local_source_to_data_urlrs. A  $$%EFF ) >' * * *iHx}--44W==G = 66D *4 * * * **r)r rr6r)r5r7r8r.)rZrr8ra)rurr8r*)rurr8r/)r8r)r8r)r]rr6r)r8r)r+r*)r+r*r8r)r2) r]rr6r)r rr5r7r8r.) r0r/rrr rr rr5r7r8r.)r0r/r rr8r*)r rr+r*r5r7r8r)&__doc__ __future__rrUrorMre dataclassesrpathlibrtypingrrnrSrrr!r#r%r'r)r.compilerIr`rErGrHrXrrPrrrYrFrrrrrrs`@#""""" !!!!!!%,,,,,9,,,      ,        '        )        )        %    """"""" "  RZ7 8 8 " =C=C=C=C=C=C@    *$$$$"OOOO*@    (@JM<M<M<M<M