pi-multimodal-proxy 1.11.0 → 1.12.1

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.12.1] - 2026-08-07
+
+### Fixed
+
+- **Downloaded videos now save to the real Downloads folder.** The post-analysis "Save downloaded video?" prompt hardcoded `join(os.homedir(), "Downloads")` and wrapped `copyFile` in a silent `catch {}`. On machines where the Windows Downloads folder is relocated (e.g. `D:\Downloads`) or OneDrive-redirected, the default path doesn't exist, so `copyFile` threw `ENOENT`, the error was swallowed, and the user saw no file and no message after clicking **Yes**. `vision-proxy.ts` now resolves the real Downloads folder via the Windows Shell known-folder API (`FOLDERID_Downloads` / `shell:Downloads`, which respects relocation and OneDrive redirection), creates it on demand (`mkdir -p`), and surfaces any save failure with the target path. The success notification now includes the full saved path. New helpers: `resolveDownloadsDir`, `pathExists`.
+
+### Added
+
+- **yt-dlp auth knobs to defeat YouTube 403s.** YouTube increasingly returns `HTTP Error 403: Forbidden` on the media fetch even with the latest `yt-dlp`; the proxy previously passed no credentials. Two opt-in, persisted settings now forward to yt-dlp: `ytdlpCookiesFromBrowser` (`/multimodal-proxy ytdlp cookies <browser|off>`, validated against `chrome|firefox|edge|brave|opera|safari|vivaldi|chromium|whale`) reuses a logged-in browser session, and `ytdlpExtractorArgs` (`/multimodal-proxy ytdlp extractor-args "<text>|off>`) forwards arbitrary `--extractor-args` (e.g. `youtube:player_client=web_safari,web`). A 403 download failure now appends a hint pointing at the cookies knob. Env overrides: `PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER`, `PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS`. New sanitizers + tests: `sanitizeYtdlpCookiesFromBrowser`, `sanitizeYtdlpExtractorArgs`, `YTDLP_COOKIES_BROWSERS`.
+
 ## [1.11.0] - 2026-07-29
 
 ### Added

package/README.md

@@ -6,6 +6,18 @@ When images are sent, this extension routes them to a **vision-capable model**,
 
 When **video or audio files** are detected, they are routed to a **multimodal model** (default: Grok 4.3) that natively understands video content — transcribing speech with speaker diarization, describing visual scenes, reading on-screen text, and reasoning about the content — all in a single call.
 
+**YouTube links** are detected too: paste a URL (`youtube.com/watch?v=…`, `youtu.be/…`, `/shorts/…`, etc.) and the video is downloaded with [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) and analyzed exactly like a local file.
+
+## What's new in 1.12.1
+
+- **Fix: downloaded videos now save to your real Downloads folder.** The "Save downloaded video?" prompt hardcoded `~/Downloads` and wrapped the copy in a silent `catch`. If you relocated Downloads (e.g. to `D:\Downloads`) or use OneDrive redirection, that path doesn't exist — so clicking **Yes** silently failed with no file and no error. The proxy now resolves the real Downloads folder via the Windows Shell known-folder API (`FOLDERID_Downloads`, respects relocation + OneDrive), creates it if missing, and surfaces any save error with the target path. The success toast now shows the full saved path.
+- **Configurable yt-dlp auth (defeats YouTube 403s).** YouTube increasingly rejects unauthenticated media fetches with `HTTP 403`, even on the latest `yt-dlp`. Two opt-in knobs satisfy the check: `/multimodal-proxy ytdlp cookies <browser>` reuses a logged-in browser session (`chrome`, `firefox`, `edge`, `brave`, …), and `/multimodal-proxy ytdlp extractor-args "<args>"` forwards arbitrary `--extractor-args` (e.g. `youtube:player_client=web_safari,web`). A 403 failure now also hints at the cookies knob. Env overrides: `PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER`, `PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS`.
+
+## What's new in 1.12.0
+
+- **YouTube video download** — paste a YouTube URL in your prompt and the extension downloads it via `yt-dlp` and analyzes it like any local video file. Gated by path detection (on by default); requires `yt-dlp` on your PATH. See [YouTube videos](#youtube-videos). After successful analysis you are prompted to optionally keep the downloaded file in your Downloads folder.
+- **Save downloaded videos** — after analysis completes, the extension asks whether to save a copy to `~/Downloads` (sanitised filename, opt-in per file).
+
 ## What's new in 1.11.0
 
 - **Global consent wildcard** — `/multimodal-proxy allowed-providers add *` (or `all`) grants consent for **all providers** globally, so you can consent once and never be prompted again. The wildcard (`*`) appears in the pre-consented list as "* (all providers)" and can be removed with `/multimodal-proxy allowed-providers remove *`. An explicit in-session `consent no` still beats the wildcard.
@@ -56,6 +68,29 @@ pi install npm:pi-multimodal-proxy
 
 > **Upgrading from pi-vision-proxy?** Just install the new package. Your existing config is automatically migrated from `~/.pi/agent/vision-proxy.json`. The `/vision-proxy` command still works.
 
+### YouTube videos
+
+Pasting a YouTube URL downloads the video with [`yt-dlp`](https://github.com/yt-dlp/yt-dlp) and analyzes it through the normal video pipeline. Install yt-dlp once:
+
+```bash
+winget install yt-dlp.yt-dlp        # Windows
+# or:  choco install yt-dlp
+# or:  brew install yt-dlp           # macOS
+# or:  pipx install yt-dlp           # any OS with Python
+```
+
+`ffmpeg` is also used (for duration probing and stream merging) — it usually ships alongside yt-dlp. Downloads are capped to ≤720p and rejected past the configured size limit (`PI_VISION_PROXY_MAX_VIDEO_BYTES`, default 200 MB). To disable URL auto-download, turn off path detection: `/multimodal-proxy path-detection off`.
+
+#### 403 Forbidden / download failures
+
+YouTube periodically rejects unauthenticated media fetches with `HTTP Error 403: Forbidden`, even on the latest `yt-dlp`. The proxy can't fix YouTube's backend, but you can satisfy the auth check:
+
+- **Reuse a logged-in browser session** — `/multimodal-proxy ytdlp cookies chrome` (also `firefox`, `edge`, `brave`, `opera`, `safari`, `vivaldi`, `chromium`, `whale`). yt-dlp reads that browser's YouTube cookies. This fixes most 403s.
+- **Try alternate player clients** — `/multimodal-proxy ytdlp extractor-args "youtube:player_client=web_safari,web"`.
+- Show current settings with `/multimodal-proxy ytdlp`; turn either off with `... off`.
+
+Both are persisted in `~/.pi/agent/multimodal-proxy.json` and can be set via env (`PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER`, `PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS`), which override and lock the command.
+
 ## Modes
 
 | Mode | Behavior |

package/extensions/__tests__/internal.test.ts

@@ -35,6 +35,9 @@ import {
 	extractCandidateImagePaths,
 	extractCandidateVideoPaths,
 	extractCandidateAudioPaths,
+	extractCandidateMediaUrls,
+	canonicalYouTubeUrl,
+	youTubeVideoId,
 	extractDimensions,
 	fenceUntrusted,
 	findDescriptions,
@@ -48,6 +51,9 @@ import {
 	isValidNamedRegion,
 	expandLeadingTilde,
 	sanitizeAllowedFolders,
+	sanitizeYtdlpCookiesFromBrowser,
+	sanitizeYtdlpExtractorArgs,
+	YTDLP_COOKIES_BROWSERS,
 	pathAccessFromConfig,
 	MAX_ALLOWED_FOLDERS,
 	LRUCache,
@@ -262,18 +268,18 @@ describe("readEnvOverrides", () => {
 
 describe("envFlags", () => {
 	it("reports presence per variable", () => {
-		assert.deepEqual(envFlags({}), { mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false });
+		assert.deepEqual(envFlags({}), { mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false });
 		assert.deepEqual(
 			envFlags({
 				PI_VISION_PROXY_MODE: "x",
 				PI_VISION_PROXY_MODEL: "y",
 				PI_VISION_PROXY_INCLUDE_CONTEXT: "",
 			}),
-			{ mode: true, model: true, context: true, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false },
+			{ mode: true, model: true, context: true, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: false, allowedFolders: false, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false },
 		);
 		assert.deepEqual(
 			envFlags({ PI_VISION_PROXY_ALLOW_HOME: "1", PI_VISION_PROXY_ALLOWED_FOLDERS: "/a" }),
-			{ mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: true, allowedFolders: true, statusLine: false, pathDetection: false },
+			{ mode: false, model: false, context: false, tool: false, maxImagesPerCall: false, maxBatch: false, cacheSize: false, videoModel: false, allowedProviders: false, allowHome: true, allowedFolders: true, statusLine: false, pathDetection: false, ytdlpCookies: false, ytdlpExtractorArgs: false },
 		);
 		assert.equal(envFlags({ PI_VISION_PROXY_ALLOWED_PROVIDERS: "" }).allowedProviders, true);
 		// An unrecognized ALLOW_HOME value is not an override and must not lock the command
@@ -284,6 +290,32 @@ describe("envFlags", () => {
 		// An invalid value is not applied by readEnvOverrides, so it must not
 		// report (and thereby lock) the setting as env-overridden either.
 		assert.equal(envFlags({ PI_VISION_PROXY_STATUS_LINE: "bogus" }).statusLine, false);
+		assert.equal(envFlags({ PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER: "chrome" }).ytdlpCookies, true);
+		assert.equal(envFlags({ PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS: "youtube:player_client=web" }).ytdlpExtractorArgs, true);
+	});
+});
+
+describe("yt-dlp config sanitizers", () => {
+	it("accepts known browsers case-insensitively, rejects others", () => {
+		assert.equal(sanitizeYtdlpCookiesFromBrowser("Chrome"), "chrome");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser("FIREFOX"), "firefox");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser("edge"), "edge");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser("internet explorer"), "");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser(""), "");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser(undefined), "");
+		assert.equal(sanitizeYtdlpCookiesFromBrowser(123 as any), "");
+	});
+	it("exposes the supported browser set", () => {
+		assert.ok(YTDLP_COOKIES_BROWSERS.has("chrome"));
+		assert.ok(YTDLP_COOKIES_BROWSERS.has("brave"));
+	});
+	it("strips control chars and caps extractor-args length", () => {
+		assert.equal(sanitizeYtdlpExtractorArgs("youtube:player_client=web"), "youtube:player_client=web");
+		assert.equal(sanitizeYtdlpExtractorArgs("  trim me  "), "trim me");
+		assert.equal(sanitizeYtdlpExtractorArgs("a\x00b\x07c"), "abc");
+		assert.equal(sanitizeYtdlpExtractorArgs(""), "");
+		const long = "x".repeat(600);
+		assert.equal(sanitizeYtdlpExtractorArgs(long).length, 500);
 	});
 });
 
@@ -964,6 +996,80 @@ describe("extractCandidateMediaPaths", () => {
 	});
 });
 
+describe("extractCandidateMediaUrls (YouTube)", () => {
+	it("extracts the video id from common URL forms", () => {
+		assert.equal(youTubeVideoId("https://www.youtube.com/watch?v=dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://youtu.be/dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://www.youtube.com/shorts/dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://www.youtube.com/embed/dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://www.youtube.com/live/dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://m.youtube.com/watch?v=dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("https://music.youtube.com/watch?v=dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+	});
+
+	it("accepts scheme-less / bare URLs", () => {
+		assert.equal(youTubeVideoId("youtu.be/dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+		assert.equal(youTubeVideoId("www.youtube.com/watch?v=dQw4w9WgXcQ"), "dQw4w9WgXcQ");
+	});
+
+	it("handles leading query params before v=", () => {
+		assert.equal(
+			youTubeVideoId("https://www.youtube.com/watch?app=desktop&v=dQw4w9WgXcQ&list=xyz"),
+			"dQw4w9WgXcQ",
+		);
+	});
+
+	it("returns null for non-YouTube URLs", () => {
+		assert.equal(youTubeVideoId("https://vimeo.com/123456"), null);
+		assert.equal(youTubeVideoId("https://example.com/watch?v=abc"), null);
+		assert.equal(youTubeVideoId("not a url at all"), null);
+	});
+
+	it("builds a canonical watch URL", () => {
+		assert.equal(
+			canonicalYouTubeUrl("https://youtu.be/dQw4w9WgXcQ?t=42"),
+			"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+		);
+		assert.equal(canonicalYouTubeUrl("https://vimeo.com/123"), null);
+	});
+
+	it("detects YouTube URLs embedded in prompt text", () => {
+		assert.deepEqual(
+			extractCandidateMediaUrls("check this out https://www.youtube.com/watch?v=dQw4w9WgXcQ thanks"),
+			["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
+		);
+		assert.deepEqual(
+			extractCandidateMediaUrls("see youtu.be/abcdefghij and a shorts https://youtube.com/shorts/123456789ab"),
+			["youtu.be/abcdefghij", "https://youtube.com/shorts/123456789ab"],
+		);
+	});
+
+	it("captures trailing query/fragment so the whole URL can be stripped", () => {
+		assert.deepEqual(
+			extractCandidateMediaUrls("https://youtu.be/dQw4w9WgXcQ?t=42&feature=shared"),
+			["https://youtu.be/dQw4w9WgXcQ?t=42&feature=shared"],
+		);
+	});
+
+	it("does not swallow a trailing markdown link closer", () => {
+		assert.deepEqual(
+			extractCandidateMediaUrls("[video](https://www.youtube.com/watch?v=dQw4w9WgXcQ)"),
+			["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
+		);
+	});
+
+	it("deduplicates by video id across URL forms", () => {
+		const out = extractCandidateMediaUrls(
+			"https://youtu.be/dQw4w9WgXcQ and https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+		);
+		assert.deepEqual(out, ["https://youtu.be/dQw4w9WgXcQ"]);
+	});
+
+	it("ignores non-YouTube URLs", () => {
+		assert.deepEqual(extractCandidateMediaUrls("see https://vimeo.com/123456 and https://example.com"), []);
+	});
+});
+
 describe("stripMediaPaths", () => {
 	it("replaces media paths with placeholder", () => {
 		const mediaPath = "D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4";

package/extensions/internal.ts

@@ -79,6 +79,12 @@ export interface VisionConfig {
 	// (event.images) are always processed; only the convenience path-scan is
 	// gated. Explicit references via /multimodal-proxy describe still work.
 	pathDetection: ToolSetting;
+	// 1.12.1 — yt-dlp tuning to defeat YouTube 403s on the media fetch. Both
+	// empty by default. cookiesFromBrowser reuses a logged-in browser session
+	// (e.g. "chrome"); extractorArgs forwards arbitrary --extractor-args (e.g.
+	// "youtube:player_client=web_safari,web").
+	ytdlpCookiesFromBrowser: string;
+	ytdlpExtractorArgs: string;
 }
 
 export interface ImageMeta {
@@ -704,6 +710,8 @@ export const DEFAULT_CONFIG: VisionConfig = {
 		"google/gemini-2.5-pro": { format: "gemini_normalized_1000" },
 		"google/gemini-3-pro": { format: "gemini_normalized_1000" },
 	},
+	ytdlpCookiesFromBrowser: "",
+	ytdlpExtractorArgs: "",
 };
 
 // ── Persistent file storage ────────────────────────────────────────────────
@@ -729,6 +737,8 @@ const PERSISTED_CONFIG_KEYS = new Set([
 	"allowedFolders", "allowHome",
 	"statusLine",
 	"pathDetection",
+	"ytdlpCookiesFromBrowser",
+	"ytdlpExtractorArgs",
 ]);
 
 /** Read config from the persistent file. Returns empty object on any failure. */
@@ -868,10 +878,15 @@ export function readEnvOverrides(env: NodeJS.ProcessEnv = process.env): Partial<
 	if (foldersEnv !== undefined) {
 		overrides.allowedFolders = sanitizeAllowedFolders(foldersEnv.split(delimiter));
 	}
+	// 1.12.1 yt-dlp env overrides
+	const cookiesEnv = env.PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER;
+	if (cookiesEnv !== undefined) overrides.ytdlpCookiesFromBrowser = sanitizeYtdlpCookiesFromBrowser(cookiesEnv);
+	const extractorArgsEnv = env.PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS;
+	if (extractorArgsEnv !== undefined) overrides.ytdlpExtractorArgs = sanitizeYtdlpExtractorArgs(extractorArgsEnv);
 	return overrides;
 }
 
-export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean; model: boolean; context: boolean; tool: boolean; maxImagesPerCall: boolean; maxBatch: boolean; cacheSize: boolean; videoModel: boolean; allowedProviders: boolean; allowHome: boolean; allowedFolders: boolean; statusLine: boolean; pathDetection: boolean } {
+export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean; model: boolean; context: boolean; tool: boolean; maxImagesPerCall: boolean; maxBatch: boolean; cacheSize: boolean; videoModel: boolean; allowedProviders: boolean; allowHome: boolean; allowedFolders: boolean; statusLine: boolean; pathDetection: boolean; ytdlpCookies: boolean; ytdlpExtractorArgs: boolean } {
 	return {
 		mode: Boolean(env.PI_VISION_PROXY_MODE),
 		model: Boolean(env.PI_VISION_PROXY_MODEL),
@@ -891,6 +906,8 @@ export function envFlags(env: NodeJS.ProcessEnv = process.env): { mode: boolean;
 		statusLine: env.PI_VISION_PROXY_STATUS_LINE === "on" || env.PI_VISION_PROXY_STATUS_LINE === "off",
 		// Same rule: only a recognized value overrides path detection.
 		pathDetection: env.PI_VISION_PROXY_PATH_DETECTION === "on" || env.PI_VISION_PROXY_PATH_DETECTION === "off",
+		ytdlpCookies: env.PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER !== undefined,
+		ytdlpExtractorArgs: env.PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS !== undefined,
 	};
 }
 
@@ -984,6 +1001,33 @@ export function sanitizeAllowedFolders(value: unknown): string[] {
 	return out;
 }
 
+/** Browsers accepted by yt-dlp's --cookies-from-browser (1.12.1). */
+export const YTDLP_COOKIES_BROWSERS = new Set([
+	"chrome", "firefox", "edge", "brave", "opera", "safari", "vivaldi", "chromium", "whale",
+]);
+
+/** Max length of the freeform --extractor-args value (1.12.1). */
+export const YTDLP_EXTRACTOR_ARGS_MAX = 500;
+
+/**
+ * Validate a yt-dlp --cookies-from-browser value (1.12.1). Lowercases and
+ * accepts only known browser names; anything else collapses to "" (off).
+ */
+export function sanitizeYtdlpCookiesFromBrowser(value: unknown): string {
+	if (typeof value !== "string") return "";
+	const v = value.trim().toLowerCase();
+	return YTDLP_COOKIES_BROWSERS.has(v) ? v : "";
+}
+
+/**
+ * Validate a yt-dlp --extractor-args value (1.12.1). Strips control/null bytes
+ * and caps length; returned verbatim (yt-dlp parses the single arg value).
+ */
+export function sanitizeYtdlpExtractorArgs(value: unknown): string {
+	if (typeof value !== "string") return "";
+	return value.replace(/[\x00-\x1f\x7f]/g, "").trim().slice(0, YTDLP_EXTRACTOR_ARGS_MAX);
+}
+
 export function sanitize(config: VisionConfig): VisionConfig {
 	const safe: VisionConfig = { ...config };
 	if (typeof safe.provider === "string") safe.provider = canonicalProvider(safe.provider);
@@ -1052,6 +1096,9 @@ export function sanitize(config: VisionConfig): VisionConfig {
 	if (safe.statusLine !== "on" && safe.statusLine !== "off") safe.statusLine = DEFAULT_CONFIG.statusLine;
 	// 1.11.0 path-detection field
 	if (safe.pathDetection !== "on" && safe.pathDetection !== "off") safe.pathDetection = DEFAULT_CONFIG.pathDetection;
+	// 1.12.1 yt-dlp tuning fields
+	safe.ytdlpCookiesFromBrowser = sanitizeYtdlpCookiesFromBrowser(safe.ytdlpCookiesFromBrowser);
+	safe.ytdlpExtractorArgs = sanitizeYtdlpExtractorArgs(safe.ytdlpExtractorArgs);
 	return safe;
 }
 
@@ -1382,6 +1429,64 @@ export function extractCandidateAudioPaths(text: string): string[] {
 	return extractCandidateMediaPaths(text, AUDIO_EXT_ALT);
 }
 
+// ── Media URL detection (YouTube) ──────────────────────────────────────────
+
+/**
+ * Match a YouTube video URL and capture its video id (group 1).
+ *
+ * Supports youtu.be/<id>, youtube.com/watch?v=<id> (with optional leading
+ * query params such as `app=desktop`), and the /shorts/, /embed/, /live/,
+ * and /v/ path forms, on www., m., and music. subdomains. The scheme is
+ * optional (a bare `youtu.be/<id>` is accepted). An optional trailing
+ * query/fragment is consumed so the full matched text can be stripped from
+ * the prompt. Build a `gi` instance from `.source` when scanning text.
+ */
+const YOUTUBE_URL_RE =
+	/(?:https?:\/\/)?(?:www\.|m\.|music\.)?(?:youtu\.be\/|youtube\.com\/(?:watch\?(?:.*?&)?v=|shorts\/|embed\/|live\/|v\/))([A-Za-z0-9_-]{6,})(?:[?&][^\s"'<>()\[\]]*)?/i;
+
+/**
+ * Extract the YouTube video id from a string. Returns null when the string
+ * does not contain a YouTube video URL.
+ */
+export function youTubeVideoId(s: string): string | null {
+	const m = s.match(YOUTUBE_URL_RE);
+	return m?.[1] ?? null;
+}
+
+/**
+ * Return the canonical `https://www.youtube.com/watch?v=<id>` form for a
+ * YouTube URL. Returns null when the input is not a YouTube video URL.
+ * yt-dlp only needs the canonical watch URL — timestamp/playlist params are
+ * not required to fetch the video.
+ */
+export function canonicalYouTubeUrl(s: string): string | null {
+	const id = youTubeVideoId(s);
+	return id ? `https://www.youtube.com/watch?v=${id}` : null;
+}
+
+/**
+ * Extract candidate YouTube video URLs from prompt text.
+ *
+ * Returns the matched substrings exactly as they appear so they can be
+ * stripped from the prompt, de-duplicated by video id. Pass each result to
+ * `canonicalYouTubeUrl()` to obtain the yt-dlp input. Non-YouTube URLs are
+ * ignored (other providers can be added later by extending the regex).
+ */
+export function extractCandidateMediaUrls(text: string): string[] {
+	const out: string[] = [];
+	const seen = new Set<string>();
+	const re = new RegExp(YOUTUBE_URL_RE.source, "gi");
+	let m: RegExpExecArray | null;
+	while ((m = re.exec(text)) !== null) {
+		const id = m[1];
+		if (id && !seen.has(id)) {
+			seen.add(id);
+			out.push(m[0]);
+		}
+	}
+	return out;
+}
+
 /**
  * Extract candidate image file paths from prompt text.
  * Matches `pi-clipboard-*` temp files and general paths ending with image extensions.

package/extensions/vision-proxy.ts

@@ -37,13 +37,15 @@
  *     PI_VISION_PROXY_MAX_VIDEO_BYTES  - positive integer
  *     PI_VISION_PROXY_ALLOWED_PROVIDERS - comma-separated pre-consented providers
  *     PI_VISION_PROXY_STATUS_LINE      - "on" | "off"
+ *     PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER - chrome|firefox|edge|brave|opera|safari|vivaldi|chromium|whale (defeats YouTube 403s)
+ *     PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS - e.g. "youtube:player_client=web_safari,web"
  *
  * Install:
  *   pi install ./packages/pi-multimodal-proxy
  */
 
 import { execFile } from "node:child_process";
-import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { access, copyFile, mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
 import os from "node:os";
 import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
@@ -96,6 +98,9 @@ import {
 	extractCandidateImagePaths,
 	extractCandidateVideoPaths,
 	extractCandidateAudioPaths,
+	extractCandidateMediaUrls,
+	canonicalYouTubeUrl,
+	youTubeVideoId,
 	applyDefaultModelFallback,
 	applyRecallCompletion,
 	buildRecallItems,
@@ -125,6 +130,8 @@ import {
 	expandLeadingTilde,
 	isUncPath,
 	MAX_ALLOWED_FOLDERS,
+	sanitizeYtdlpExtractorArgs,
+	YTDLP_COOKIES_BROWSERS,
 
 	readMediaFileWithReason,
 	type ReadMediaReason,
@@ -929,6 +936,181 @@ async function extractAudioChunkToMp3(inputPath: string, outputPath: string, sta
 	], { windowsHide: true, timeout: 120_000 });
 }
 
+// ── yt-dlp: download media URLs (YouTube) ───────────────────────────────────
+
+/**
+ * Cache yt-dlp availability so a missing binary is reported once per session
+ * rather than every turn.
+ */
+let ytDlpAvailable: boolean | null = null;
+
+async function checkYtDlp(): Promise<boolean> {
+	if (ytDlpAvailable !== null) return ytDlpAvailable;
+	try {
+		await execFileAsync("yt-dlp", ["--version"], { windowsHide: true, timeout: 15_000 });
+		ytDlpAvailable = true;
+	} catch {
+		ytDlpAvailable = false;
+	}
+	return ytDlpAvailable;
+}
+
+interface DownloadedMedia {
+	/** Final on-disk path of the downloaded file. */
+	path: string;
+	/** Temp dir holding the file; the caller must remove it. */
+	tempDir: string;
+	/** Human-readable label (video title) for notifications / fences. */
+	title: string;
+}
+
+/**
+ * Download a media URL via yt-dlp into a fresh temp dir.
+ *
+ * Prefers an already-muxed mp4 at <=720p to keep the payload small for the
+ * video model; falls back to the best available stream merged to mp4. The
+ * post-read size guard (maxVideoFileBytes) still applies, so oversized
+ * downloads are rejected downstream with a clear "too-large" reason.
+ *
+ * Returns null (with a user-facing notification) when yt-dlp is missing or
+ * the download fails. The caller owns tempDir cleanup.
+ */
+async function downloadMediaUrl(
+	url: string,
+	signal: AbortSignal | undefined,
+	ctx: ExtensionContext,
+	ytdlp?: { cookiesFromBrowser?: string; extractorArgs?: string },
+): Promise<DownloadedMedia | null> {
+	if (!(await checkYtDlp())) {
+		ctx.ui.notify(
+			"[multimodal-proxy] YouTube download skipped — yt-dlp not found. Install it (e.g. `winget install yt-dlp.yt-dlp` or `choco install yt-dlp`) and retry.",
+			"warning",
+		);
+		return null;
+	}
+
+	const tempDir = await mkdtemp(join(os.tmpdir(), "multimodal-proxy-ytdl-"));
+	try {
+		// NOTE on `--print after_move:filepath`: when every --print field is a
+		// pre-download metadata field (e.g. only "%(title)s"), yt-dlp skips the
+		// actual download — it can satisfy the print from metadata alone. Adding
+		// an after_move field forces the download (it is only known once the file
+		// is in its final location) and also hands us the exact output path.
+		const args = [
+			"--no-playlist",
+			"--no-warnings",
+			"--no-progress",
+			"-f", "best[ext=mp4][height<=720]/best[height<=720]/best",
+			"--merge-output-format", "mp4",
+			"-o", join(tempDir, "%(id)s.%(ext)s"),
+		];
+		// Optional auth / player-client knobs (1.12.1) — defeat YouTube 403s on
+		// the media fetch by reusing a logged-in browser session and/or alternate
+		// player clients. Both opt-in; absent by default.
+		if (ytdlp?.cookiesFromBrowser) {
+			args.push("--cookies-from-browser", ytdlp.cookiesFromBrowser);
+		}
+		if (ytdlp?.extractorArgs) {
+			args.push("--extractor-args", ytdlp.extractorArgs);
+		}
+		args.push("--print", "%(title)s", "--print", "after_move:filepath", url);
+		const { stdout } = await execFileAsync(
+			"yt-dlp",
+			args,
+			{ windowsHide: true, timeout: 240_000, maxBuffer: 4 * 1024 * 1024, signal },
+		);
+
+		const lines = stdout.split(/\r?\n/).map((l) => l.trim()).filter((l) => l.length > 0);
+		// The filepath line is the one that looks like an absolute path.
+		const pathLine = lines.find((l) => /^([a-zA-Z]:[\\/]|[\\/])/.test(l));
+		const title = (lines.find((l) => l !== pathLine) ?? "").trim() || url;
+
+		// Prefer the path yt-dlp reported; fall back to scanning the temp dir.
+		let path = pathLine ?? "";
+		if (!path) {
+			const entries = await readdir(tempDir);
+			const file = entries.find((f) => !f.endsWith(".part") && !f.endsWith(".ytdl"));
+			path = file ? join(tempDir, file) : "";
+		}
+		if (!path) {
+			ctx.ui.notify(`[multimodal-proxy] YouTube download produced no file for ${url}`, "warning");
+			return null;
+		}
+		return { path, tempDir, title };
+	} catch (err) {
+		if (signal?.aborted) return null;
+		const msg = err instanceof Error ? err.message : String(err);
+		// A 403 on the media fetch usually means YouTube wants a logged-in
+		// session; point the user at the cookies knob if it isn't already set.
+		const hint = /403|forbidden/i.test(msg) && !ytdlp?.cookiesFromBrowser
+			? " (a 403 often means YouTube wants a logged-in session — try /multimodal-proxy ytdlp cookies <browser>)"
+			: "";
+		ctx.ui.notify(`[multimodal-proxy] YouTube download failed for ${url}: ${msg}${hint}`, "warning");
+		return null;
+	}
+}
+
+// ── Downloads folder resolution ─────────────────────────────────────────────
+//
+// The Windows default `C:\Users\<user>\Downloads` is frequently NOT the folder
+// File Explorer shows: OneDrive redirection or a custom relocation (e.g.
+// `D:\Downloads`) moves it elsewhere. Hardcoding the default then makes
+// `copyFile` throw ENOENT — and pre-fix that error was swallowed silently, so
+// the user clicked "Save", nothing appeared, and no error was surfaced.
+//
+// We resolve the real folder via the Shell known-folder (FOLDERID_Downloads)
+// on Windows, cache the result, and fall back to `~/Downloads` elsewhere.
+
+let downloadsDirCache: string | null = null;
+
+async function pathExists(p: string): Promise<boolean> {
+	try {
+		await access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Resolve the user's real Downloads folder, respecting Windows relocation /
+ * OneDrive redirection. Falls back to the default `~/Downloads` (which the
+ * caller creates on demand). Result is cached for the process lifetime.
+ */
+async function resolveDownloadsDir(): Promise<string> {
+	if (downloadsDirCache) return downloadsDirCache;
+	const defaultDir = join(os.homedir(), "Downloads");
+	if (await pathExists(defaultDir)) {
+		downloadsDirCache = defaultDir;
+		return defaultDir;
+	}
+	// Default is missing (relocated / OneDrive-redirected). On Windows, ask the
+	// Shell for the real Downloads known-folder path; this respects redirection.
+	if (process.platform === "win32") {
+		try {
+			const { stdout } = await execFileAsync(
+				"powershell.exe",
+				[
+					"-NoProfile",
+					"-NonInteractive",
+					"-Command",
+					"(New-Object -ComObject Shell.Application).NameSpace('shell:Downloads').Self.Path",
+				],
+				{ windowsHide: true, timeout: 10_000 },
+			);
+			const resolved = stdout.split(/\r?\n/).map((l) => l.trim()).find((l) => l.length > 0) ?? "";
+			if (resolved && (await pathExists(resolved))) {
+				downloadsDirCache = resolved;
+				return resolved;
+			}
+		} catch {
+			// PowerShell unavailable or failed — fall back to default (created below).
+		}
+	}
+	downloadsDirCache = defaultDir;
+	return defaultDir;
+}
+
 async function analyzeVideoViaXaiStt(
 	mediaFile: { type: "image"; data: string; mimeType: string },
 	filename: string,
@@ -1566,6 +1748,55 @@ export default function (pi: ExtensionAPI) {
 				event.prompt = stripMediaPaths(event.prompt, acceptedMediaPaths);
 			}
 
+			// ── Detect & download media URLs (YouTube, etc.) ─────────────────
+			// Reuses the local-file pipeline: download to a temp dir, then read it
+			// like any other media file. Gated by path detection (on by default) —
+			// no separate switch. Requires yt-dlp on PATH (ffmpeg is already used
+			// elsewhere by this extension).
+			const downloadedTempDirs: string[] = [];
+			const downloadedFiles = new Map<string, { title: string; tempDir: string; filename: string; size: number }>();
+			const cleanupDownloads = async () => {
+				for (const d of downloadedTempDirs) {
+					try { await rm(d, { recursive: true, force: true }); } catch { /* ignore */ }
+				}
+				downloadedTempDirs.length = 0;
+			};
+			if (pathDetectionOn) {
+				const mediaUrls = extractCandidateMediaUrls(event.prompt);
+				const acceptedMediaUrls: string[] = [];
+				for (const url of mediaUrls) {
+					const watch = canonicalYouTubeUrl(url);
+					if (!watch) continue;
+					const id = youTubeVideoId(url) ?? "";
+					const dl = await withProgress(
+						ctx,
+						() => `Downloading YouTube ${id}…`,
+						`Downloading YouTube ${id}…`,
+						() => downloadMediaUrl(watch, ctx.signal, ctx, {
+							cookiesFromBrowser: config.ytdlpCookiesFromBrowser,
+							extractorArgs: config.ytdlpExtractorArgs,
+						}),
+					);
+					if (!dl) continue;
+					downloadedTempDirs.push(dl.tempDir);
+					const r = await readMediaFileWithReason(dl.path, pathAccess);
+					if (r.media) {
+						const fname = r.filename ?? dl.title;
+						downloadedFiles.set(dl.path, { title: dl.title, tempDir: dl.tempDir, filename: fname, size: r.bytes ?? 0 });
+						mediaFiles.push({ file: r.media, filename: fname, path: dl.path });
+						acceptedMediaUrls.push(url);
+					} else if (r.reason && r.reason !== "not-a-media") {
+						ctx.ui.notify(
+							`[multimodal-proxy] Skipped YouTube ${id}: ${describeReadMediaReason(r.reason, r.bytes)}`,
+							"warning",
+						);
+					}
+				}
+				if (acceptedMediaUrls.length > 0) {
+					event.prompt = stripMediaPaths(event.prompt, acceptedMediaUrls);
+				}
+			}
+
 			// Inject loaded file-path images into the event so they reach the model
 			// regardless of whether vision-proxy stripping runs. Strip paths from the
 			// prompt text to avoid duplicate references.
@@ -1582,10 +1813,12 @@ export default function (pi: ExtensionAPI) {
 
 			// ── Handle video/audio files ─────────────────────────────────────
 			let videoDescriptionFence = "";
+			const videoResults: VideoAnalysisResult[] = [];
 			if (mediaFiles.length > 0 && config.mode !== "off") {
 				// Check consent for video provider
 				if (!(await ensureConsent({ ...config, provider: config.videoProvider }, ctx, entries, pi))) {
 					ctx.ui.notify("[multimodal-proxy] Video analysis skipped - no consent.", "warning");
+					await cleanupDownloads();
 					// Inject actionable message so the agent tells the user what to do
 					return {
 						systemPrompt:
@@ -1597,8 +1830,7 @@ export default function (pi: ExtensionAPI) {
 							")",
 					};
 				} else {
-					const videoResults: VideoAnalysisResult[] = [];
-					for (const [mi, mf] of mediaFiles.entries()) {
+				for (const [mi, mf] of mediaFiles.entries()) {
 						const label = () =>
 							mediaFiles.length > 1
 								? `Analyzing ${mf.filename} (${mi + 1}/${mediaFiles.length})…`
@@ -1653,6 +1885,36 @@ export default function (pi: ExtensionAPI) {
 					}
 				}
 			}
+			// Offer to save successfully analyzed downloaded videos
+			for (const [path, info] of downloadedFiles) {
+				const result = videoResults.find(r => r.filename === info.filename && r.description);
+				if (!result) continue;
+				const sizeMB = (info.size / (1024 * 1024)).toFixed(1);
+				try {
+					const save = await ctx.ui.confirm(
+						"Save downloaded video?",
+						`"${info.title}"\n\n${sizeMB} MB — save to your Downloads folder?`,
+					);
+					if (!save) continue;
+					const safeTitle = info.title.replace(/[<>:"\/\\|?*]/g, "_").replace(/\s+/g, " ").trim().slice(0, 200);
+					const destDir = await resolveDownloadsDir();
+					const dest = join(destDir, `${safeTitle}.mp4`);
+					try {
+						await mkdir(destDir, { recursive: true });
+						await copyFile(path, dest);
+						ctx.ui.notify(`[multimodal-proxy] ✓ Saved "${safeTitle}.mp4" to ${dest}`, "info");
+					} catch (saveErr) {
+						// Surface save failures (missing dir, permissions, disk) — the
+					// previous silent catch hid them and the video just vanished.
+						const reason = saveErr instanceof Error ? saveErr.message : String(saveErr);
+						ctx.ui.notify(`[multimodal-proxy] ✗ Could not save video to ${dest}: ${reason}`, "warning");
+					}
+				} catch {
+					// confirm() dialog itself failed — don't block the agent. Temp
+					// files are cleaned below regardless.
+				}
+			}
+			await cleanupDownloads();
 
 			// ── Handle images (existing flow) ──────────────────────────────────
 			if (images.length === 0) {
@@ -2350,6 +2612,73 @@ Use "*" or "all" to grant consent for all providers globally.`,
 				return;
 			}
 
+			// ── yt-dlp cookies / extractor-args (defeat YouTube 403s) ───────
+			if (sub === "ytdlp") {
+				const { sub: ySub, value: yValue } = splitSubcommand(value);
+
+				if (ySub === "cookies") {
+					if (env.ytdlpCookies) {
+						ctx.ui.notify(
+							"[multimodal-proxy] PI_VISION_PROXY_YTDLP_COOKIES_FROM_BROWSER is set - env overrides commands. Unset to change.",
+							"warning",
+						);
+						return;
+					}
+					const trimmed = yValue.trim().toLowerCase();
+					if (!trimmed || trimmed === "off") {
+						writePersisted({ ...persisted, ytdlpCookiesFromBrowser: "" });
+						ctx.ui.notify("[multimodal-proxy] yt-dlp cookies-from-browser: off", "info");
+						return;
+					}
+					if (!YTDLP_COOKIES_BROWSERS.has(trimmed)) {
+						ctx.ui.notify(
+							`[multimodal-proxy] Unknown browser "${trimmed}". Supported: ${[...YTDLP_COOKIES_BROWSERS].join(", ")}`,
+							"warning",
+						);
+						return;
+					}
+					writePersisted({ ...persisted, ytdlpCookiesFromBrowser: trimmed });
+					ctx.ui.notify(
+						`[multimodal-proxy] yt-dlp cookies-from-browser: ${trimmed} (applied on next YouTube download)`,
+						"info",
+					);
+					return;
+				}
+
+				if (ySub === "extractor-args") {
+					if (env.ytdlpExtractorArgs) {
+						ctx.ui.notify(
+							"[multimodal-proxy] PI_VISION_PROXY_YTDLP_EXTRACTOR_ARGS is set - env overrides commands. Unset to change.",
+							"warning",
+						);
+						return;
+					}
+					const trimmed = yValue.trim();
+					if (!trimmed || trimmed.toLowerCase() === "off") {
+						writePersisted({ ...persisted, ytdlpExtractorArgs: "" });
+						ctx.ui.notify("[multimodal-proxy] yt-dlp extractor-args: off", "info");
+						return;
+					}
+					const cleaned = sanitizeYtdlpExtractorArgs(trimmed);
+					writePersisted({ ...persisted, ytdlpExtractorArgs: cleaned });
+					ctx.ui.notify(`[multimodal-proxy] yt-dlp extractor-args: ${cleaned}`, "info");
+					return;
+				}
+
+				ctx.ui.notify(
+					"[multimodal-proxy] yt-dlp options:\n" +
+						`  cookies-from-browser: ${effective.ytdlpCookiesFromBrowser || "(off)"}\n` +
+						`  extractor-args: ${effective.ytdlpExtractorArgs || "(off)"}\n` +
+						(env.ytdlpCookies || env.ytdlpExtractorArgs ? "  (env override active)\n" : "") +
+						"Usage:\n" +
+						"  /multimodal-proxy ytdlp cookies <browser|off>      reuse a logged-in YouTube session (fixes most 403s)\n" +
+						'  /multimodal-proxy ytdlp extractor-args <text|off>  e.g. youtube:player_client=web_safari,web\n' +
+						`Browsers: ${[...YTDLP_COOKIES_BROWSERS].join(", ")}`,
+					"info",
+				);
+				return;
+			}
+
 			// ── max-images-per-call ────────────────────────────
 			if (sub === "max-images-per-call") {
 				if (env.maxImagesPerCall) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multimodal-proxy",
-  "version": "1.11.0",
+  "version": "1.12.1",
   "description": "Automatic image, video and audio description for any model in Pi. Routes media to a multimodal model and injects descriptions into context.",
   "keywords": [
     "pi-package"