Skip to main content

tea_coding_tools/web_fetch/
mod.rs

1use std::fmt;
2use std::future::Future;
3use std::pin::Pin;
4use std::str::FromStr;
5use std::sync::Arc;
6
7use futures_util::stream;
8use serde::{Deserialize, Serialize};
9use serde_json::{Value, json};
10use tea_control::CancellationScope;
11use tea_protocol::{
12    ContentBlock, ProtocolMetadata, ToolIdempotency, ToolPresentation, WebFetchPresentation,
13    WebFetchRedirect, WebFetchTruncation,
14};
15use tea_tools::{
16    BoxToolExecutionStream, ToolConcurrency, ToolEffect, ToolExecutionEvent, ToolExecutionFailure,
17    ToolExecutionSemantics, ToolExecutor, ToolName, ToolResult, ToolRetrySafety, ToolSpec,
18    ToolSpecError, ToolTimeout, ToolVersion, ValidatedToolInvocation,
19};
20use thiserror::Error;
21
22mod address_policy;
23mod body;
24mod cache;
25mod http;
26mod provider;
27mod url_policy;
28
29pub use address_policy::{FetchAddressPolicy, FetchAddressPolicyError, ValidatedFetchAddresses};
30pub use body::{
31    DEFAULT_FETCH_DECODED_BYTES, DEFAULT_FETCH_HTML_BYTES, DEFAULT_FETCH_HTML_ELEMENTS,
32    DecodedFetchBody, FetchBodyDecoder, FetchBodyLimits, FetchContentKind, MAX_FETCH_DECODED_BYTES,
33};
34pub use cache::{
35    DEFAULT_FETCH_CACHE_ENTRIES, DEFAULT_FETCH_CACHE_ENTRY_BYTES, DEFAULT_FETCH_CACHE_TOTAL_BYTES,
36    DEFAULT_FETCH_CACHE_TTL, FetchCacheConfig, FetchCacheScope, FetchCacheStats, FetchResultCache,
37    MAX_FETCH_CACHE_ENTRIES, MAX_FETCH_CACHE_ENTRY_BYTES, MAX_FETCH_CACHE_TOTAL_BYTES,
38    MAX_FETCH_CACHE_TTL,
39};
40pub use http::{
41    DEFAULT_FETCH_RESPONSE_BYTES, FetchDnsResolver, FetchHttpConfig, FetchHttpHeaders,
42    FetchHttpLimits, FetchHttpResponse, FetchHttpTimeouts, FetchHttpTransport, FetchResolveFuture,
43    MAX_FETCH_RESPONSE_BYTES, SystemFetchDnsResolver,
44};
45pub use provider::{FETCH_SECURITY_POLICY_VERSION, HttpFetchProvider};
46pub use url_policy::{FetchUrlPolicy, FetchUrlPolicyError, FetchUrlScheme, ValidatedFetchUrl};
47
48/// Maximum UTF-8 bytes accepted in a fetch URL.
49pub const MAX_FETCH_URL_BYTES: usize = 2 * 1024;
50/// Default number of body characters returned by the fetch tool.
51pub const DEFAULT_FETCH_MAX_CHARS: usize = 20_000;
52/// Maximum body characters retained by one fetch result.
53pub const MAX_FETCH_MAX_CHARS: usize = 100_000;
54/// Maximum title bytes retained by one fetch result.
55pub const MAX_FETCH_TITLE_BYTES: usize = 4 * 1024;
56/// Maximum MIME type bytes retained by one fetch result.
57pub const MAX_FETCH_MIME_BYTES: usize = 128;
58/// Maximum redirect records retained by one fetch result.
59pub const MAX_FETCH_REDIRECTS: usize = 10;
60
61/// Invalid provider-neutral fetch request.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
63pub enum FetchRequestError {
64    /// URL is empty, oversized, malformed, or outside the initial scheme contract.
65    #[error("web fetch URL is invalid")]
66    InvalidUrl,
67    /// Requested body character limit is outside the bounded contract.
68    #[error("web fetch character limit is invalid")]
69    InvalidMaxChars,
70    /// The request contains an unsupported field or shape.
71    #[error("web fetch request shape is invalid")]
72    InvalidShape,
73}
74
75/// Bounded provider-neutral request passed to a client fetch backend.
76#[derive(Clone, PartialEq, Eq)]
77pub struct FetchRequest {
78    url: String,
79    max_chars: usize,
80}
81
82impl FetchRequest {
83    /// Creates and validates a fetch request.
84    ///
85    /// DNS, IP-range checks, and per-hop connection authorization still belong
86    /// to the HTTP transport. This constructor freezes the production URL
87    /// syntax and scheme contract before the request reaches a provider.
88    ///
89    /// # Errors
90    ///
91    /// Rejects non-HTTPS URLs, credentials, unsafe ports, controls, and character
92    /// limits outside `1..=100_000`. Fragments are removed from the canonical URL.
93    pub fn new(url: impl Into<String>, max_chars: usize) -> Result<Self, FetchRequestError> {
94        Self::new_with_policy(url, max_chars, &FetchUrlPolicy::production())
95    }
96
97    /// Creates a request under an explicit URL policy.
98    ///
99    /// This supports transport conformance tests that use loopback fixture
100    /// servers. Product tool invocations use [`Self::new`].
101    ///
102    /// # Errors
103    ///
104    /// Returns the same bounded errors as [`Self::new`].
105    pub fn new_with_policy(
106        url: impl Into<String>,
107        max_chars: usize,
108        policy: &FetchUrlPolicy,
109    ) -> Result<Self, FetchRequestError> {
110        let raw_url = url.into();
111        let url = policy
112            .validate(&raw_url)
113            .map_err(|_| FetchRequestError::InvalidUrl)?
114            .as_str()
115            .to_owned();
116        if !(1..=MAX_FETCH_MAX_CHARS).contains(&max_chars) {
117            return Err(FetchRequestError::InvalidMaxChars);
118        }
119        Ok(Self { url, max_chars })
120    }
121
122    /// Returns the normalized requested URL.
123    #[must_use]
124    pub fn url(&self) -> &str {
125        &self.url
126    }
127
128    /// Returns the requested body character limit.
129    #[must_use]
130    pub const fn max_chars(&self) -> usize {
131        self.max_chars
132    }
133}
134
135impl fmt::Debug for FetchRequest {
136    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
137        let validated = FetchUrlPolicy::production().validate(&self.url).ok();
138        formatter
139            .debug_struct("FetchRequest")
140            .field("host", &validated.as_ref().map(ValidatedFetchUrl::host))
141            .field("url_bytes", &self.url.len())
142            .field("max_chars", &self.max_chars)
143            .finish()
144    }
145}
146
147/// Stable failure categories returned by client fetch backends.
148#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
149#[serde(rename_all = "snake_case")]
150pub enum FetchProviderErrorCode {
151    /// Backend or credential configuration is invalid.
152    InvalidConfiguration,
153    /// The normalized request is invalid.
154    InvalidRequest,
155    /// The destination is forbidden by URL or address policy.
156    ForbiddenDestination,
157    /// DNS resolution failed or returned an unsafe answer.
158    DnsResolution,
159    /// A redirect was invalid, unsafe, cyclic, or exceeded bounds.
160    RedirectRejected,
161    /// The response exceeded a compressed or decoded byte limit.
162    ResponseTooLarge,
163    /// The response MIME type or content shape is unsupported.
164    UnsupportedMime,
165    /// The backend timed out.
166    Timeout,
167    /// The backend could not be reached or the peer was not the pinned address.
168    Transport,
169    /// The response was malformed or failed bounded extraction.
170    MalformedResponse,
171    /// Cooperative cancellation was requested.
172    Cancelled,
173}
174
175/// Whether an upper layer may explicitly retry a failed fetch operation.
176#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
177#[serde(rename_all = "snake_case")]
178pub enum FetchRetryDisposition {
179    /// Retrying could repeat an unsafe or deterministic failure.
180    Never,
181    /// A caller may explicitly retry after a pre-response transport failure.
182    Explicit,
183}
184
185/// Secret-independent client fetch failure.
186#[derive(Clone, Copy, PartialEq, Eq)]
187pub struct FetchProviderError {
188    code: FetchProviderErrorCode,
189    message: &'static str,
190    retry: FetchRetryDisposition,
191}
192
193impl FetchProviderError {
194    /// Creates a failure with a stable, non-sensitive message.
195    #[must_use]
196    pub const fn new(code: FetchProviderErrorCode) -> Self {
197        Self {
198            code,
199            message: fetch_error_message(code),
200            retry: FetchRetryDisposition::Never,
201        }
202    }
203
204    pub(crate) const fn explicit_retry(code: FetchProviderErrorCode) -> Self {
205        Self {
206            code,
207            message: fetch_error_message(code),
208            retry: FetchRetryDisposition::Explicit,
209        }
210    }
211
212    /// Creates a cooperative cancellation failure.
213    #[must_use]
214    pub const fn cancelled() -> Self {
215        Self::new(FetchProviderErrorCode::Cancelled)
216    }
217
218    /// Returns the stable category.
219    #[must_use]
220    pub const fn code(&self) -> FetchProviderErrorCode {
221        self.code
222    }
223
224    /// Returns a bounded secret-independent technical message.
225    #[must_use]
226    pub const fn message(&self) -> &'static str {
227        self.message
228    }
229
230    /// Returns the conservative retry classification.
231    #[must_use]
232    pub const fn retry_disposition(&self) -> FetchRetryDisposition {
233        self.retry
234    }
235}
236
237impl fmt::Debug for FetchProviderError {
238    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
239        formatter
240            .debug_struct("FetchProviderError")
241            .field("code", &self.code)
242            .field("message", &self.message)
243            .field("retry", &self.retry)
244            .finish()
245    }
246}
247
248impl fmt::Display for FetchProviderError {
249    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
250        formatter.write_str(self.message)
251    }
252}
253
254impl std::error::Error for FetchProviderError {}
255
256const fn fetch_error_message(code: FetchProviderErrorCode) -> &'static str {
257    match code {
258        FetchProviderErrorCode::InvalidConfiguration => {
259            "web fetch backend configuration is invalid"
260        }
261        FetchProviderErrorCode::InvalidRequest => "web fetch request is invalid",
262        FetchProviderErrorCode::ForbiddenDestination => "web fetch destination is forbidden",
263        FetchProviderErrorCode::DnsResolution => {
264            "web fetch destination could not be resolved safely"
265        }
266        FetchProviderErrorCode::RedirectRejected => "web fetch redirect was rejected",
267        FetchProviderErrorCode::ResponseTooLarge => "web fetch response exceeded its bounds",
268        FetchProviderErrorCode::UnsupportedMime => "web fetch response MIME type is unsupported",
269        FetchProviderErrorCode::Timeout => "web fetch backend timed out",
270        FetchProviderErrorCode::Transport => "web fetch backend transport failed",
271        FetchProviderErrorCode::MalformedResponse => "web fetch response is malformed",
272        FetchProviderErrorCode::Cancelled => "web fetch was cancelled",
273    }
274}
275
276/// Why a fetch body was truncated.
277#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
278#[serde(rename_all = "snake_case")]
279pub enum FetchTruncationReason {
280    /// Compressed bytes exceeded the transport bound.
281    CompressedBytes,
282    /// Decoded bytes exceeded the transport bound.
283    DecodedBytes,
284    /// Extracted body characters reached the request limit.
285    BodyCharacters,
286    /// The content parser reached its complexity or structure bound.
287    ParserComplexity,
288}
289
290/// One bounded redirect record.
291#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
292pub struct FetchRedirect {
293    from: String,
294    to: String,
295    status: u16,
296}
297
298impl FetchRedirect {
299    /// Creates a redirect record.
300    ///
301    /// # Errors
302    ///
303    /// Rejects malformed URLs, non-redirect status codes, and oversized values.
304    pub fn new(
305        from: impl Into<String>,
306        to: impl Into<String>,
307        status: u16,
308    ) -> Result<Self, FetchProviderError> {
309        Self::new_with_policy(from, to, status, &FetchUrlPolicy::production())
310    }
311
312    /// Creates a redirect record under an explicit URL policy.
313    ///
314    /// # Errors
315    ///
316    /// Returns the same bounded errors as [`Self::new`].
317    pub fn new_with_policy(
318        from: impl Into<String>,
319        to: impl Into<String>,
320        status: u16,
321        policy: &FetchUrlPolicy,
322    ) -> Result<Self, FetchProviderError> {
323        if !(300..=399).contains(&status) {
324            return Err(FetchProviderError::new(
325                FetchProviderErrorCode::MalformedResponse,
326            ));
327        }
328        let raw_from = from.into();
329        let raw_to = to.into();
330        let from = normalize_result_url(&raw_from, *policy)?;
331        let to = normalize_result_url(&raw_to, *policy)?;
332        Ok(Self { from, to, status })
333    }
334
335    /// Returns the source URL.
336    #[must_use]
337    pub fn from(&self) -> &str {
338        &self.from
339    }
340
341    /// Returns the redirect target URL.
342    #[must_use]
343    pub fn to(&self) -> &str {
344        &self.to
345    }
346
347    /// Returns the HTTP redirect status.
348    #[must_use]
349    pub const fn status(&self) -> u16 {
350        self.status
351    }
352}
353
354impl fmt::Debug for FetchRedirect {
355    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
356        formatter
357            .debug_struct("FetchRedirect")
358            .field("status", &self.status)
359            .field("from_bytes", &self.from.len())
360            .field("to_bytes", &self.to.len())
361            .finish()
362    }
363}
364
365/// Bounded normalized result returned by a client fetch backend.
366#[derive(Clone, PartialEq, Eq, Serialize, Deserialize)]
367pub struct FetchResult {
368    requested_url: String,
369    final_url: String,
370    title: Option<String>,
371    mime_type: String,
372    body: String,
373    truncated: Option<FetchTruncationReason>,
374    redirects: Vec<FetchRedirect>,
375}
376
377impl FetchResult {
378    /// Creates a result with bounded URLs, MIME, and body content.
379    ///
380    /// # Errors
381    ///
382    /// Rejects malformed URLs, unsupported MIME syntax, oversized body/title
383    /// values, and more than ten redirect records.
384    pub fn new(
385        requested_url: impl Into<String>,
386        final_url: impl Into<String>,
387        mime_type: impl Into<String>,
388        body: impl Into<String>,
389    ) -> Result<Self, FetchProviderError> {
390        Self::new_with_policy(
391            requested_url,
392            final_url,
393            mime_type,
394            body,
395            &FetchUrlPolicy::production(),
396        )
397    }
398
399    /// Creates a result under an explicit URL policy.
400    ///
401    /// This supports deterministic loopback transport tests without weakening
402    /// the production constructor.
403    ///
404    /// # Errors
405    ///
406    /// Returns the same bounded errors as [`Self::new`].
407    pub fn new_with_policy(
408        requested_url: impl Into<String>,
409        final_url: impl Into<String>,
410        mime_type: impl Into<String>,
411        body: impl Into<String>,
412        policy: &FetchUrlPolicy,
413    ) -> Result<Self, FetchProviderError> {
414        let raw_requested_url = requested_url.into();
415        let raw_final_url = final_url.into();
416        let requested_url = normalize_result_url(&raw_requested_url, *policy)?;
417        let final_url = normalize_result_url(&raw_final_url, *policy)?;
418        let raw_mime_type = mime_type.into();
419        let mime_type = validate_mime_type(&raw_mime_type)?;
420        let body = body.into();
421        if body.chars().count() > MAX_FETCH_MAX_CHARS || body.contains('\0') {
422            return Err(FetchProviderError::new(
423                FetchProviderErrorCode::ResponseTooLarge,
424            ));
425        }
426        Ok(Self {
427            requested_url,
428            final_url,
429            title: None,
430            mime_type,
431            body,
432            truncated: None,
433            redirects: Vec::new(),
434        })
435    }
436
437    /// Adds an optional bounded document title.
438    ///
439    /// # Errors
440    ///
441    /// Rejects control characters or titles over 4 KiB.
442    pub fn with_title(mut self, title: impl Into<String>) -> Result<Self, FetchProviderError> {
443        let title = title.into();
444        if title.is_empty()
445            || title.len() > MAX_FETCH_TITLE_BYTES
446            || title.chars().any(char::is_control)
447        {
448            return Err(FetchProviderError::new(
449                FetchProviderErrorCode::MalformedResponse,
450            ));
451        }
452        self.title = Some(title);
453        Ok(self)
454    }
455
456    /// Marks the result as truncated for a bounded reason.
457    #[must_use]
458    pub const fn with_truncation(mut self, reason: FetchTruncationReason) -> Self {
459        self.truncated = Some(reason);
460        self
461    }
462
463    /// Adds bounded redirect metadata.
464    ///
465    /// # Errors
466    ///
467    /// Rejects more than ten records.
468    pub fn with_redirects(
469        mut self,
470        redirects: Vec<FetchRedirect>,
471    ) -> Result<Self, FetchProviderError> {
472        if redirects.len() > MAX_FETCH_REDIRECTS {
473            return Err(FetchProviderError::new(
474                FetchProviderErrorCode::MalformedResponse,
475            ));
476        }
477        self.redirects = redirects;
478        Ok(self)
479    }
480
481    /// Returns the originally requested URL.
482    #[must_use]
483    pub fn requested_url(&self) -> &str {
484        &self.requested_url
485    }
486
487    /// Returns the final URL after bounded redirects.
488    #[must_use]
489    pub fn final_url(&self) -> &str {
490        &self.final_url
491    }
492
493    /// Returns the optional extracted document title.
494    #[must_use]
495    pub fn title(&self) -> Option<&str> {
496        self.title.as_deref()
497    }
498
499    /// Returns the normalized MIME type.
500    #[must_use]
501    pub fn mime_type(&self) -> &str {
502        &self.mime_type
503    }
504
505    /// Returns the bounded extracted body.
506    #[must_use]
507    pub fn body(&self) -> &str {
508        &self.body
509    }
510
511    /// Returns the truncation reason, if the body was bounded.
512    #[must_use]
513    pub const fn truncation(&self) -> Option<FetchTruncationReason> {
514        self.truncated
515    }
516
517    /// Returns normalized redirect records.
518    #[must_use]
519    pub fn redirects(&self) -> &[FetchRedirect] {
520        &self.redirects
521    }
522}
523
524impl fmt::Debug for FetchResult {
525    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
526        formatter
527            .debug_struct("FetchResult")
528            .field("mime_type", &self.mime_type)
529            .field("body_chars", &self.body.chars().count())
530            .field("has_title", &self.title.is_some())
531            .field("truncated", &self.truncated)
532            .field("redirect_count", &self.redirects.len())
533            .finish_non_exhaustive()
534    }
535}
536
537fn normalize_result_url(value: &str, policy: FetchUrlPolicy) -> Result<String, FetchProviderError> {
538    policy
539        .validate(value)
540        .map(|validated| validated.as_str().to_owned())
541        .map_err(|_| FetchProviderError::new(FetchProviderErrorCode::MalformedResponse))
542}
543
544fn validate_mime_type(value: &str) -> Result<String, FetchProviderError> {
545    let valid = !value.is_empty()
546        && value.len() <= MAX_FETCH_MIME_BYTES
547        && value.bytes().all(|byte| {
548            byte.is_ascii_alphanumeric()
549                || matches!(byte, b'/' | b'.' | b'+' | b'-' | b';' | b'=' | b' ')
550        });
551    if valid {
552        Ok(value.to_ascii_lowercase())
553    } else {
554        Err(FetchProviderError::new(
555            FetchProviderErrorCode::MalformedResponse,
556        ))
557    }
558}
559
560/// Object-safe future returned by [`FetchProvider`].
561pub type FetchFuture<'a> =
562    Pin<Box<dyn Future<Output = Result<FetchResult, FetchProviderError>> + Send + 'a>>;
563
564/// Object-safe client web-fetch backend port.
565pub trait FetchProvider: fmt::Debug + Send + Sync {
566    /// Executes one bounded request with cooperative cancellation.
567    fn fetch(&self, request: FetchRequest, cancellation: CancellationScope) -> FetchFuture<'_>;
568}
569
570/// Client executor for the stable `web_fetch` tool contract.
571#[derive(Debug, Clone)]
572pub struct WebFetchTool {
573    provider: Arc<dyn FetchProvider>,
574}
575
576impl WebFetchTool {
577    /// Creates a client fetch executor.
578    #[must_use]
579    pub fn new(provider: Arc<dyn FetchProvider>) -> Self {
580        Self { provider }
581    }
582
583    /// Builds the strict client fetch tool contract.
584    ///
585    /// # Errors
586    ///
587    /// Returns an error only if the static contract violates tool bounds.
588    pub fn spec() -> Result<ToolSpec, ToolSpecError> {
589        ToolSpec::new(
590            ToolName::from_str("web_fetch").map_err(|_| ToolSpecError::InvalidDescription)?,
591            ToolVersion::from_str("1.0.0").map_err(|_| ToolSpecError::InvalidDescription)?,
592            "Fetch bounded public web content from an explicitly provided HTTPS URL.",
593            json!({
594                "type":"object",
595                "properties":{
596                    "url":{"type":"string","minLength":1,"maxLength":MAX_FETCH_URL_BYTES},
597                    "max_chars":{"type":"integer","minimum":1,"maximum":MAX_FETCH_MAX_CHARS}
598                },
599                "required":["url"],
600                "additionalProperties":false
601            }),
602            json!({
603                "type":"object",
604                "properties":{
605                    "requested_url":{"type":"string"},
606                    "final_url":{"type":"string"},
607                    "title":{"type":["string","null"]},
608                    "mime_type":{"type":"string"},
609                    "body":{"type":"string"},
610                    "truncated":{"type":["string","null"]},
611                    "redirects":{"type":"array","maxItems":MAX_FETCH_REDIRECTS}
612                },
613                "required":["requested_url","final_url","title","mime_type","body","truncated","redirects"],
614                "additionalProperties":false
615            }),
616            [ToolEffect::NetworkRequest],
617            ToolExecutionSemantics::new(
618                ToolIdempotency::Idempotent,
619                ToolRetrySafety::ExplicitOnly,
620                ToolConcurrency::Parallel,
621                ToolTimeout::from_millis(60_000)?,
622            )?,
623        )?
624        .with_prompt_hint(
625            "Use web_fetch only for an explicitly requested public URL; it does not search the web.",
626        )
627    }
628
629    async fn run(
630        &self,
631        invocation: &ValidatedToolInvocation,
632        cancellation: CancellationScope,
633    ) -> ToolExecutionEvent {
634        if cancellation.is_cancelled() {
635            return ToolExecutionEvent::Failed(ToolExecutionFailure::cancelled());
636        }
637        let Ok(request) = request_from_invocation(invocation) else {
638            return provider_failure(FetchProviderError::new(
639                FetchProviderErrorCode::InvalidRequest,
640            ));
641        };
642        match self.provider.fetch(request, cancellation).await {
643            Ok(result) => fetch_success(&result),
644            Err(error) => provider_failure(error),
645        }
646    }
647}
648
649impl ToolExecutor for WebFetchTool {
650    fn execute(
651        &self,
652        invocation: ValidatedToolInvocation,
653        cancellation: CancellationScope,
654    ) -> BoxToolExecutionStream {
655        let executor = self.clone();
656        Box::pin(stream::once(async move {
657            executor.run(&invocation, cancellation).await
658        }))
659    }
660}
661
662fn request_from_invocation(
663    invocation: &ValidatedToolInvocation,
664) -> Result<FetchRequest, FetchRequestError> {
665    let url = invocation
666        .arguments()
667        .get("url")
668        .and_then(Value::as_str)
669        .ok_or(FetchRequestError::InvalidUrl)?;
670    let max_chars = invocation
671        .arguments()
672        .get("max_chars")
673        .and_then(Value::as_u64)
674        .map(usize::try_from)
675        .transpose()
676        .map_err(|_| FetchRequestError::InvalidMaxChars)?
677        .unwrap_or(DEFAULT_FETCH_MAX_CHARS);
678    FetchRequest::new(url, max_chars)
679}
680
681fn fetch_success(result: &FetchResult) -> ToolExecutionEvent {
682    let redirects = result
683        .redirects()
684        .iter()
685        .map(|redirect| {
686            json!({
687                "from": redirect.from(),
688                "to": redirect.to(),
689                "status": redirect.status(),
690            })
691        })
692        .collect::<Vec<_>>();
693    let Ok(presentation) = web_fetch_presentation(result) else {
694        return ToolExecutionEvent::Failed(ToolExecutionFailure::internal_contract());
695    };
696    let visible = web_fetch_visible_text(&presentation);
697    let output = json!({
698        "requested_url": result.requested_url(),
699        "final_url": result.final_url(),
700        "title": result.title(),
701        "mime_type": result.mime_type(),
702        "body": result.body(),
703        "truncated": result.truncation().map(truncation_code),
704        "redirects": redirects,
705    });
706    let Ok(content) = ContentBlock::text(visible) else {
707        return ToolExecutionEvent::Failed(ToolExecutionFailure::internal_contract());
708    };
709    let Ok(result) = ToolResult::new(vec![content], output) else {
710        return ToolExecutionEvent::Failed(ToolExecutionFailure::internal_contract());
711    };
712    ToolExecutionEvent::Finished(
713        result.with_presentation(ToolPresentation::WebFetch(Box::new(presentation))),
714    )
715}
716
717fn web_fetch_presentation(
718    result: &FetchResult,
719) -> Result<WebFetchPresentation, tea_protocol::ExternalContentError> {
720    let mut presentation = WebFetchPresentation::new(
721        result.requested_url(),
722        result.final_url(),
723        result.mime_type(),
724        result.body(),
725    )?;
726    if let Some(title) = result.title() {
727        presentation = presentation.with_title(title)?;
728    }
729    if let Some(truncation) = result.truncation() {
730        presentation = presentation.with_truncation(match truncation {
731            FetchTruncationReason::CompressedBytes => WebFetchTruncation::CompressedBytes,
732            FetchTruncationReason::DecodedBytes => WebFetchTruncation::DecodedBytes,
733            FetchTruncationReason::BodyCharacters => WebFetchTruncation::BodyCharacters,
734            FetchTruncationReason::ParserComplexity => WebFetchTruncation::ParserComplexity,
735        });
736    }
737    let redirects = result
738        .redirects()
739        .iter()
740        .map(|redirect| WebFetchRedirect::new(redirect.from(), redirect.to(), redirect.status()))
741        .collect::<Result<Vec<_>, _>>()?;
742    presentation.with_redirects(redirects)
743}
744
745fn web_fetch_visible_text(presentation: &WebFetchPresentation) -> String {
746    let mut visible = format!(
747        "Fetched URL: {}\nContent-Type: {}",
748        presentation.final_url(),
749        presentation.mime_type()
750    );
751    if presentation.requested_url() != presentation.final_url() {
752        visible.push_str("\nRequested URL: ");
753        visible.push_str(presentation.requested_url());
754    }
755    if let Some(title) = presentation.title() {
756        visible.push_str("\nTitle: ");
757        visible.push_str(title);
758    }
759    if let Some(truncation) = presentation.truncation() {
760        visible.push_str("\nTruncated: ");
761        visible.push_str(match truncation {
762            WebFetchTruncation::CompressedBytes => "compressed_bytes",
763            WebFetchTruncation::DecodedBytes => "decoded_bytes",
764            WebFetchTruncation::BodyCharacters => "body_characters",
765            WebFetchTruncation::ParserComplexity => "parser_complexity",
766        });
767    }
768    if !presentation.redirects().is_empty() {
769        visible.push_str("\nRedirects: ");
770        visible.push_str(&presentation.redirects().len().to_string());
771    }
772    visible.push_str("\n\n");
773    visible.push_str(presentation.body());
774    visible
775}
776
777fn provider_failure(error: FetchProviderError) -> ToolExecutionEvent {
778    if error.code() == FetchProviderErrorCode::Cancelled {
779        return ToolExecutionEvent::Failed(ToolExecutionFailure::cancelled());
780    }
781    let details = ProtocolMetadata::from_entries([(
782        "dev.tea-rs.web-fetch",
783        json!({
784            "code":fetch_error_code(error.code()),
785            "retry":fetch_retry_code(error.retry_disposition()),
786        }),
787    )])
788    .unwrap_or_default();
789    let failure = ToolExecutionFailure::execution(error.message())
790        .unwrap_or_else(|_| ToolExecutionFailure::internal_contract())
791        .with_details(details);
792    ToolExecutionEvent::Failed(failure)
793}
794
795const fn fetch_retry_code(disposition: FetchRetryDisposition) -> &'static str {
796    match disposition {
797        FetchRetryDisposition::Never => "never",
798        FetchRetryDisposition::Explicit => "explicit",
799    }
800}
801
802const fn fetch_error_code(code: FetchProviderErrorCode) -> &'static str {
803    match code {
804        FetchProviderErrorCode::InvalidConfiguration => "invalid_configuration",
805        FetchProviderErrorCode::InvalidRequest => "invalid_request",
806        FetchProviderErrorCode::ForbiddenDestination => "forbidden_destination",
807        FetchProviderErrorCode::DnsResolution => "dns_resolution",
808        FetchProviderErrorCode::RedirectRejected => "redirect_rejected",
809        FetchProviderErrorCode::ResponseTooLarge => "response_too_large",
810        FetchProviderErrorCode::UnsupportedMime => "unsupported_mime",
811        FetchProviderErrorCode::Timeout => "timeout",
812        FetchProviderErrorCode::Transport => "transport",
813        FetchProviderErrorCode::MalformedResponse => "malformed_response",
814        FetchProviderErrorCode::Cancelled => "cancelled",
815    }
816}
817
818const fn truncation_code(reason: FetchTruncationReason) -> &'static str {
819    match reason {
820        FetchTruncationReason::CompressedBytes => "compressed_bytes",
821        FetchTruncationReason::DecodedBytes => "decoded_bytes",
822        FetchTruncationReason::BodyCharacters => "body_characters",
823        FetchTruncationReason::ParserComplexity => "parser_complexity",
824    }
825}