pi-multimodal-proxy 1.12.0 → 1.13.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.13.0] - 2026-08-09
+
+### Fixed
+- Migrated to `ModelRegistry.complete`.
+
+## [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

@@ -8,6 +8,11 @@ When **video or audio files** are detected, they are routed to a **multimodal mo
 
 **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.
@@ -76,6 +81,16 @@ winget install yt-dlp.yt-dlp        # Windows
 
 `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 |
@@ -299,3 +314,4 @@ For the full security audit see [`SECURITY-REVIEW.md`](./SECURITY-REVIEW.md).
 ## License
 
 MIT
+

package/extensions/__tests__/internal.test.ts

@@ -51,6 +51,9 @@ import {
 	isValidNamedRegion,
 	expandLeadingTilde,
 	sanitizeAllowedFolders,
+	sanitizeYtdlpCookiesFromBrowser,
+	sanitizeYtdlpExtractorArgs,
+	YTDLP_COOKIES_BROWSERS,
 	pathAccessFromConfig,
 	MAX_ALLOWED_FOLDERS,
 	LRUCache,
@@ -265,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
@@ -287,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);
 	});
 });
 

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;
 }
 

package/extensions/vision-proxy.ts

@@ -37,23 +37,55 @@
  *     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 { copyFile, mkdtemp, readFile, readdir, 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";
-import { type ImageContent as PiAiImage, complete } from "@earendil-works/pi-ai";
+import { type ImageContent as PiAiImage, type Api, type Model, type Context, type ProviderStreamOptions, type AssistantMessage } from "@earendil-works/pi-ai";
+
+type LegacyComplete = <TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions) => Promise<AssistantMessage>;
+
+// move `complete` to @earendil-works/pi-ai/compat 
+let legacyCompletePromise: Promise<LegacyComplete> | undefined;
+function loadLegacyComplete(): Promise<LegacyComplete> {
+    if (!legacyCompletePromise) {
+        const compatSpecifier: string = "@earendil-works/pi-ai/compat";
+        legacyCompletePromise = import("@earendil-works/pi-ai").then((mod: any) =>
+            typeof mod.complete === "function"
+                ? mod.complete
+                : import(compatSpecifier).then((compat: any) => compat.complete),
+        );
+    }
+    return legacyCompletePromise;
+}
+
+/** Compatibility wrapper: uses new ModelRegistry.complete when available, otherwise falls back to legacyComplete. */
+function hasComplete(mr: ModelRegistry): mr is ModelRegistry & { complete: LegacyComplete } {
+    return typeof (mr as any).complete === "function";
+}
+
+async function completeCompat<TApi extends Api>(ctx: ExtensionContext, model: Model<TApi>, request: Context, options?: ProviderStreamOptions) {
+    if (hasComplete(ctx.modelRegistry)) {
+        return ctx.modelRegistry.complete(model, request, options);
+    }
+    const legacyComplete = await loadLegacyComplete();
+    return legacyComplete(model, request, options);
+}
+
 import type {
 	BeforeAgentStartEvent,
 	BeforeAgentStartEventResult,
 	ContextEvent,
 	ExtensionAPI,
-	ExtensionContext,
+	ExtensionContext, ModelRegistry,
 	SessionCompactEvent,
 	SessionEntry,
 	SessionStartEvent,
@@ -128,6 +160,8 @@ import {
 	expandLeadingTilde,
 	isUncPath,
 	MAX_ALLOWED_FOLDERS,
+	sanitizeYtdlpExtractorArgs,
+	YTDLP_COOKIES_BROWSERS,
 
 	readMediaFileWithReason,
 	type ReadMediaReason,
@@ -613,7 +647,9 @@ async function analyzeImages(
 	config: VisionConfig,
 	ctx: ExtensionContext,
 ): Promise<AnalysisResult[] | null> {
+
 	const visionModel = ctx.modelRegistry.find(config.provider, config.modelId);
+
 	if (!visionModel) {
 		ctx.ui.notify(
 			`[multimodal-proxy] Model "${modelLabel(config)}" not found. Use /multimodal-proxy pick to choose one.`,
@@ -663,7 +699,7 @@ async function analyzeImages(
 		storeImageData(imageData, hash, piAiImage.data, piAiImage.mimeType);
 
 		try {
-			const response = await complete(
+			const response = await completeCompat(ctx,
 				visionModel,
 				{
 					systemPrompt: config.systemPrompt,
@@ -786,7 +822,7 @@ async function analyzeVideo(
 		: "";
 
 	try {
-		const response = await complete(
+		const response = await completeCompat(ctx,
 			videoModel,
 			{
 				systemPrompt: config.videoSystemPrompt,
@@ -975,6 +1011,7 @@ async function downloadMediaUrl(
 	url: string,
 	signal: AbortSignal | undefined,
 	ctx: ExtensionContext,
+	ytdlp?: { cookiesFromBrowser?: string; extractorArgs?: string },
 ): Promise<DownloadedMedia | null> {
 	if (!(await checkYtDlp())) {
 		ctx.ui.notify(
@@ -991,19 +1028,27 @@ async function downloadMediaUrl(
 		// 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",
-			[
-				"--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"),
-				"--print", "%(title)s",
-				"--print", "after_move:filepath",
-				url,
-			],
+			args,
 			{ windowsHide: true, timeout: 240_000, maxBuffer: 4 * 1024 * 1024, signal },
 		);
 
@@ -1027,11 +1072,77 @@ async function downloadMediaUrl(
 	} catch (err) {
 		if (signal?.aborted) return null;
 		const msg = err instanceof Error ? err.message : String(err);
-		ctx.ui.notify(`[multimodal-proxy] YouTube download failed for ${url}: ${msg}`, "warning");
+		// 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,
@@ -1384,7 +1495,7 @@ async function handleAnalyzeImage(
 
 	try {
 		const startTime = Date.now();
-		const response = await complete(
+		const response = await completeCompat(ctx,
 			visionModel,
 			{
 				systemPrompt,
@@ -1693,7 +1804,10 @@ export default function (pi: ExtensionAPI) {
 						ctx,
 						() => `Downloading YouTube ${id}…`,
 						`Downloading YouTube ${id}…`,
-						() => downloadMediaUrl(watch, ctx.signal, ctx),
+						() => downloadMediaUrl(watch, ctx.signal, ctx, {
+							cookiesFromBrowser: config.ytdlpCookiesFromBrowser,
+							extractorArgs: config.ytdlpExtractorArgs,
+						}),
 					);
 					if (!dl) continue;
 					downloadedTempDirs.push(dl.tempDir);
@@ -1813,15 +1927,23 @@ export default function (pi: ExtensionAPI) {
 						"Save downloaded video?",
 						`"${info.title}"\n\n${sizeMB} MB — save to your Downloads folder?`,
 					);
-					if (save) {
-						const safeTitle = info.title.replace(/[<>:"\/\\|?*]/g, "_").replace(/\s+/g, " ").trim().slice(0, 200);
-						const dest = join(os.homedir(), "Downloads", `${safeTitle}.mp4`);
+					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 Downloads`, "info");
+						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 {
-					// Don't block the agent on save errors — temp files are
-					// cleaned below regardless.
+					// confirm() dialog itself failed — don't block the agent. Temp
+					// files are cleaned below regardless.
 				}
 			}
 			await cleanupDownloads();
@@ -1939,7 +2061,7 @@ export default function (pi: ExtensionAPI) {
 								...jointImages,
 							];
 
-							const jointResponse = await complete(
+							const jointResponse = await completeCompat(ctx,
 								jointVisionModel,
 								{
 									systemPrompt: jointSystemPrompt,
@@ -2522,6 +2644,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) {
@@ -2963,7 +3152,7 @@ Use "*" or "all" to grant consent for all providers globally.`,
 
 				try {
 					const startTime = Date.now();
-					const response = await complete(
+					const response = await completeCompat(ctx,
 						descVisionModel,
 						{
 							systemPrompt,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-multimodal-proxy",
-  "version": "1.12.0",
+  "version": "1.13.0",
   "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"