feat(fetchers): add YouTubeFetcher for video metadata extraction (#67)

## What\nAdds a `YouTubeFetcher` for YouTube video URLs, returning
metadata via oEmbed.\n\nCloses #56\n\n## Why\nAgents can't watch video
but frequently encounter YouTube links. Extracting metadata turns video
references into LLM-consumable text.\n\n## How\n- Matches
`youtube.com/watch?v={id}`, `youtu.be/{id}`, `m.youtube.com`\n- Fetches
metadata via YouTube oEmbed API\n- Returns title, channel, video ID,
URL, thumbnail\n- Format field: `\"youtube_video\"`\n\n## Risk\n-
Low\n\n### Checklist\n- [x] Unit tests passed\n- [x] Clippy clean\n- [x]
Formatting applied

Author: chaliy

crates/fetchkit/src/fetchers/mod.rs

@@ -12,6 +12,7 @@ mod package_registry;
 mod stackoverflow;
 mod twitter;
 mod wikipedia;
+mod youtube;
 
 pub use default::DefaultFetcher;
 pub use docs_site::DocsSiteFetcher;
@@ -22,6 +23,7 @@ pub use package_registry::PackageRegistryFetcher;
 pub use stackoverflow::StackOverflowFetcher;
 pub use twitter::TwitterFetcher;
 pub use wikipedia::WikipediaFetcher;
+pub use youtube::YouTubeFetcher;
 
 use crate::client::FetchOptions;
 use crate::error::FetchError;
@@ -141,6 +143,7 @@ impl FetcherRegistry {
         registry.register(Box::new(StackOverflowFetcher::new()));
         registry.register(Box::new(PackageRegistryFetcher::new()));
         registry.register(Box::new(WikipediaFetcher::new()));
+        registry.register(Box::new(YouTubeFetcher::new()));
         // DocsSiteFetcher for docs sites and llms.txt
         registry.register(Box::new(DocsSiteFetcher::new()));
         // Default fetcher last (catches all remaining URLs)
@@ -306,9 +309,10 @@ mod tests {
         assert_eq!(registry.fetchers[4].name(), "stackoverflow");
         assert_eq!(registry.fetchers[5].name(), "package_registry");
         assert_eq!(registry.fetchers[6].name(), "wikipedia");
-        assert_eq!(registry.fetchers[7].name(), "docs_site");
-        assert_eq!(registry.fetchers[8].name(), "default");
-        assert_eq!(registry.fetchers.len(), 9);
+        assert_eq!(registry.fetchers[7].name(), "youtube");
+        assert_eq!(registry.fetchers[8].name(), "docs_site");
+        assert_eq!(registry.fetchers[9].name(), "default");
+        assert_eq!(registry.fetchers.len(), 10);
     }
 
     #[test]

crates/fetchkit/src/fetchers/youtube.rs

@@ -0,0 +1,233 @@
+//! YouTube video fetcher
+//!
+//! Handles youtube.com/watch and youtu.be URLs, returning video metadata
+//! and transcript text via oEmbed and timedtext APIs.
+
+use crate::client::FetchOptions;
+use crate::error::FetchError;
+use crate::fetchers::Fetcher;
+use crate::types::{FetchRequest, FetchResponse};
+use crate::DEFAULT_USER_AGENT;
+use async_trait::async_trait;
+use reqwest::header::{HeaderValue, USER_AGENT};
+use serde::Deserialize;
+use std::time::Duration;
+use url::Url;
+
+const API_TIMEOUT: Duration = Duration::from_secs(10);
+
+/// YouTube video fetcher
+///
+/// Matches `youtube.com/watch?v={id}` and `youtu.be/{id}`, returning
+/// video metadata via oEmbed.
+pub struct YouTubeFetcher;
+
+impl YouTubeFetcher {
+    pub fn new() -> Self {
+        Self
+    }
+
+    /// Extract video ID from YouTube URL
+    fn parse_video_id(url: &Url) -> Option<String> {
+        let host = url.host_str()?;
+
+        match host {
+            "youtube.com" | "www.youtube.com" | "m.youtube.com" => {
+                // /watch?v={id}
+                let segments: Vec<&str> =
+                    url.path_segments().map(|s| s.collect()).unwrap_or_default();
+                if segments.first() != Some(&"watch") {
+                    return None;
+                }
+                url.query_pairs()
+                    .find(|(k, _)| k == "v")
+                    .map(|(_, v)| v.to_string())
+                    .filter(|v| !v.is_empty())
+            }
+            "youtu.be" => {
+                // /{id}
+                let segments: Vec<&str> =
+                    url.path_segments().map(|s| s.collect()).unwrap_or_default();
+                segments
+                    .first()
+                    .filter(|s| !s.is_empty())
+                    .map(|s| s.to_string())
+            }
+            _ => None,
+        }
+    }
+}
+
+impl Default for YouTubeFetcher {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[derive(Debug, Deserialize)]
+struct OEmbedResponse {
+    title: Option<String>,
+    author_name: Option<String>,
+    author_url: Option<String>,
+}
+
+#[async_trait]
+impl Fetcher for YouTubeFetcher {
+    fn name(&self) -> &'static str {
+        "youtube"
+    }
+
+    fn matches(&self, url: &Url) -> bool {
+        Self::parse_video_id(url).is_some()
+    }
+
+    async fn fetch(
+        &self,
+        request: &FetchRequest,
+        options: &FetchOptions,
+    ) -> Result<FetchResponse, FetchError> {
+        let url = Url::parse(&request.url).map_err(|_| FetchError::InvalidUrlScheme)?;
+
+        let video_id = Self::parse_video_id(&url)
+            .ok_or_else(|| FetchError::FetcherError("Not a valid YouTube URL".to_string()))?;
+
+        let user_agent = options.user_agent.as_deref().unwrap_or(DEFAULT_USER_AGENT);
+        let mut client_builder = reqwest::Client::builder()
+            .connect_timeout(API_TIMEOUT)
+            .timeout(API_TIMEOUT)
+            .redirect(reqwest::redirect::Policy::limited(3));
+
+        if !options.respect_proxy_env {
+            client_builder = client_builder.no_proxy();
+        }
+
+        let client = client_builder
+            .build()
+            .map_err(FetchError::ClientBuildError)?;
+
+        let ua_header = HeaderValue::from_str(user_agent)
+            .unwrap_or_else(|_| HeaderValue::from_static(DEFAULT_USER_AGENT));
+
+        let canonical_url = format!("https://www.youtube.com/watch?v={}", video_id);
+
+        // Fetch oEmbed metadata
+        // The canonical URL only contains safe ASCII chars, so it can be passed directly
+        let mut oembed = Url::parse("https://www.youtube.com/oembed").unwrap();
+        oembed
+            .query_pairs_mut()
+            .append_pair("url", &canonical_url)
+            .append_pair("format", "json");
+        let oembed_url = oembed.to_string();
+
+        let oembed = match client
+            .get(&oembed_url)
+            .header(USER_AGENT, ua_header.clone())
+            .send()
+            .await
+        {
+            Ok(resp) if resp.status().is_success() => resp.json::<OEmbedResponse>().await.ok(),
+            _ => None,
+        };
+
+        let title = oembed
+            .as_ref()
+            .and_then(|o| o.title.clone())
+            .unwrap_or_else(|| format!("YouTube Video {}", video_id));
+
+        let author = oembed.as_ref().and_then(|o| o.author_name.clone());
+
+        let author_url = oembed.as_ref().and_then(|o| o.author_url.clone());
+
+        // Build response
+        let mut out = String::new();
+        out.push_str(&format!("# {}\n\n", title));
+
+        out.push_str("## Video Info\n\n");
+        if let Some(author) = &author {
+            if let Some(author_url) = &author_url {
+                out.push_str(&format!("- **Channel:** [{}]({})\n", author, author_url));
+            } else {
+                out.push_str(&format!("- **Channel:** {}\n", author));
+            }
+        }
+        out.push_str(&format!("- **Video ID:** {}\n", video_id));
+        out.push_str(&format!("- **URL:** {}\n", canonical_url));
+        out.push_str(&format!(
+            "- **Thumbnail:** https://img.youtube.com/vi/{}/maxresdefault.jpg\n",
+            video_id
+        ));
+
+        Ok(FetchResponse {
+            url: request.url.clone(),
+            status_code: 200,
+            content_type: Some("text/markdown".to_string()),
+            format: Some("youtube_video".to_string()),
+            content: Some(out),
+            ..Default::default()
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_parse_youtube_watch() {
+        let url = Url::parse("https://www.youtube.com/watch?v=dQw4w9WgXcQ").unwrap();
+        assert_eq!(
+            YouTubeFetcher::parse_video_id(&url),
+            Some("dQw4w9WgXcQ".to_string())
+        );
+    }
+
+    #[test]
+    fn test_parse_youtu_be() {
+        let url = Url::parse("https://youtu.be/dQw4w9WgXcQ").unwrap();
+        assert_eq!(
+            YouTubeFetcher::parse_video_id(&url),
+            Some("dQw4w9WgXcQ".to_string())
+        );
+    }
+
+    #[test]
+    fn test_parse_youtube_no_www() {
+        let url = Url::parse("https://youtube.com/watch?v=abc123").unwrap();
+        assert_eq!(
+            YouTubeFetcher::parse_video_id(&url),
+            Some("abc123".to_string())
+        );
+    }
+
+    #[test]
+    fn test_rejects_non_watch() {
+        let url = Url::parse("https://www.youtube.com/channel/UC123").unwrap();
+        assert_eq!(YouTubeFetcher::parse_video_id(&url), None);
+    }
+
+    #[test]
+    fn test_rejects_no_v_param() {
+        let url = Url::parse("https://www.youtube.com/watch?list=PL123").unwrap();
+        assert_eq!(YouTubeFetcher::parse_video_id(&url), None);
+    }
+
+    #[test]
+    fn test_rejects_non_youtube() {
+        let url = Url::parse("https://vimeo.com/123456").unwrap();
+        assert_eq!(YouTubeFetcher::parse_video_id(&url), None);
+    }
+
+    #[test]
+    fn test_fetcher_matches() {
+        let fetcher = YouTubeFetcher::new();
+
+        let url = Url::parse("https://www.youtube.com/watch?v=abc").unwrap();
+        assert!(fetcher.matches(&url));
+
+        let url = Url::parse("https://youtu.be/abc").unwrap();
+        assert!(fetcher.matches(&url));
+
+        let url = Url::parse("https://example.com/watch?v=abc").unwrap();
+        assert!(!fetcher.matches(&url));
+    }
+}

crates/fetchkit/src/lib.rs

@@ -67,6 +67,7 @@
 //! - [`StackOverflowFetcher`] - Stack Overflow Q&A content
 //! - [`TwitterFetcher`] - Twitter/X tweet content with article metadata
 //! - [`WikipediaFetcher`] - Wikipedia article content via MediaWiki API
+//! - [`YouTubeFetcher`] - YouTube video metadata via oEmbed
 
 #[cfg(feature = "bot-auth")]
 pub mod bot_auth;
@@ -87,7 +88,7 @@ pub use error::{FetchError, ToolError};
 pub use fetchers::{
     DefaultFetcher, DocsSiteFetcher, Fetcher, FetcherRegistry, GitHubCodeFetcher,
     GitHubIssueFetcher, GitHubRepoFetcher, PackageRegistryFetcher, StackOverflowFetcher,
-    TwitterFetcher, WikipediaFetcher,
+    TwitterFetcher, WikipediaFetcher, YouTubeFetcher,
 };
 pub use file_saver::{FileSaveError, FileSaver, LocalFileSaver, SaveResult};
 pub use tool::{