pi-multimodal-proxy 1.14.0 → 1.15.0

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.15.0] - 2026-08-11
+
+### Added
+
+- **Vision-model picker respects the session's model scope.** `/multimodal-proxy pick` now honors `ctx.scopedModels` (pi ≥ 0.83.0): when a scope is configured via `--models` or `enabledModels`, the picker lists only scoped vision-capable models, mirroring the built-in `/model` selector instead of enumerating the whole catalogue. Falls back to the full registry when no scope is set, and on runtimes that predate `scopedModels` (gracefully undefined). When the persisted provider is excluded by the configured scope, the picker opens on the first in-scope provider instead of an empty model list. New tested pure helper `selectVisionModels`.
+
+### Fixed
+
+- **Forward-compat with pi 0.84.0 `null` header-deletion markers.** Since pi 0.84.0, `ModelRegistry.getApiKeyAndHeaders()` returns `ProviderHeaders` (`Record<string, string | null>`) where `null` marks a header for deletion. The xAI native video path (STT / file-upload / `/v1/responses`) builds raw `fetch()` calls that cannot carry `null` — undici throws `TypeError` on a non-string header value, or sends a literal `"null"`. Those headers are now stripped at the call boundary (and at the `xaiHeaders` choke point as defense-in-depth). An explicit `Authorization: null` deletion marker is now honored — the header is suppressed rather than re-filled with the API key — so a credential deliberately suppressed by a provider/header hook is not forwarded. The pi-ai `complete()` paths continue to pass headers through unchanged, as required. New tested pure helper `sanitizeProviderHeaders`.
+
 ## [1.14.0] - 2026-08-09
 
 ### Added

package/extensions/__tests__/internal.test.ts

@@ -53,6 +53,7 @@ import {
 	sanitizeAllowedFolders,
 	sanitizeYtdlpCookiesFromBrowser,
 	sanitizeYtdlpExtractorArgs,
+	sanitizeProviderHeaders,
 	YTDLP_COOKIES_BROWSERS,
 	pathAccessFromConfig,
 	MAX_ALLOWED_FOLDERS,
@@ -77,6 +78,7 @@ import {
 	piAiImageToBuffer,
 	bufferToPiAiImage,
 	shouldStripImages,
+	selectVisionModels,
 	splitSubcommand,
 	stripImagePaths,
 	stripMediaPaths,
@@ -319,6 +321,58 @@ describe("yt-dlp config sanitizers", () => {
 	});
 });
 
+describe("selectVisionModels", () => {
+	const img = (id: string) => ({ id, input: ["text", "image"] as readonly string[] });
+	const txt = (id: string) => ({ id, input: ["text"] as readonly string[] });
+
+	it("returns all vision models when no scope is configured (undefined)", () => {
+		const all = [img("a"), txt("b"), img("c")];
+		assert.deepEqual(selectVisionModels(undefined, all).map((m) => m.id), ["a", "c"]);
+	});
+	it("returns all vision models when scope is empty (every model usable)", () => {
+		const all = [img("a"), txt("b")];
+		assert.deepEqual(selectVisionModels([], all).map((m) => m.id), ["a"]);
+	});
+	it("restricts to scoped vision models when a scope is configured", () => {
+		const all = [img("a"), img("b"), img("c")];
+		const scoped = [{ model: img("b") }, { model: txt("x") }];
+		assert.deepEqual(selectVisionModels(scoped, all).map((m) => m.id), ["b"]);
+	});
+	it("uses the scope verbatim and ignores the full catalogue", () => {
+		// `b` is not in `all`; the scope is the source of truth when configured
+		const all = [img("a"), img("c")];
+		const scoped = [{ model: img("b") }];
+		assert.deepEqual(selectVisionModels(scoped, all).map((m) => m.id), ["b"]);
+	});
+	it("drops non-image scoped models", () => {
+		const scoped = [{ model: txt("x") }, { model: txt("y") }];
+		assert.deepEqual(selectVisionModels(scoped, [img("a")]).map((m) => m.id), []);
+	});
+});
+
+describe("sanitizeProviderHeaders", () => {
+	it("drops null deletion markers", () => {
+		assert.deepEqual(
+			sanitizeProviderHeaders({ Authorization: "Bearer x", "X-Delete": null, Keep: "v" }),
+			{ Authorization: "Bearer x", Keep: "v" },
+		);
+	});
+	it("drops undefined values defensively", () => {
+		assert.deepEqual(
+			sanitizeProviderHeaders({ A: undefined as unknown as null, B: "b" }),
+			{ B: "b" },
+		);
+	});
+	it("returns an empty object for undefined / empty input", () => {
+		assert.deepEqual(sanitizeProviderHeaders(undefined), {});
+		assert.deepEqual(sanitizeProviderHeaders({}), {});
+	});
+	it("never lets a null survive into the output", () => {
+		const out = sanitizeProviderHeaders({ "X-N": null, "X-S": "s" });
+		for (const v of Object.values(out)) assert.equal(typeof v, "string");
+	});
+});
+
 describe("resolveConfig", () => {
 	it("returns defaults with no entries and empty env", () => {
 		const cfg = resolveConfig([], {});

package/extensions/internal.ts

@@ -1028,6 +1028,27 @@ export function sanitizeYtdlpExtractorArgs(value: unknown): string {
 	return value.replace(/[\x00-\x1f\x7f]/g, "").trim().slice(0, YTDLP_EXTRACTOR_ARGS_MAX);
 }
 
+/**
+ * Drop `null` header values from a `ProviderHeaders` map. Since pi 0.84.0,
+ * `ModelRegistry.getApiKeyAndHeaders()` returns `Record<string, string | null>`
+ * where `null` marks a header for deletion. Raw `fetch()` calls (the xAI STT /
+ * file-upload / responses endpoints) can't carry `null` — undici throws
+ * `TypeError` on a non-string header value, or sends a literal `"null"` — so
+ * strip them before building fetch headers. (`undefined` values are also
+ * dropped defensively.)
+ */
+export function sanitizeProviderHeaders(
+	headers: Record<string, string | null> | undefined,
+): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (headers) {
+		for (const [key, value] of Object.entries(headers)) {
+			if (value !== null && value !== undefined) out[key] = value;
+		}
+	}
+	return out;
+}
+
 export function sanitize(config: VisionConfig): VisionConfig {
 	const safe: VisionConfig = { ...config };
 	if (typeof safe.provider === "string") safe.provider = canonicalProvider(safe.provider);
@@ -1925,6 +1946,30 @@ export function fuzzyMatches(target: string, query: string): boolean {
 	return true;
 }
 
+/** Minimal model shape for vision selection (keeps this helper testable
+ *  without pulling in pi-ai's `Model`/`Api` types). */
+interface VisionModelLike {
+	input: readonly string[];
+}
+
+/**
+ * Vision-capable models for the picker. Honors the session's model scope
+ * (`ctx.scopedModels`, pi ≥ 0.83.0) when one is configured, so
+ * `/multimodal-proxy pick` mirrors the built-in `/model` selector instead of
+ * enumerating the whole catalogue. Falls back to the full list when no scope
+ * is set — an empty scope means every available model is usable — and on
+ * runtimes that predate `scopedModels`, where `scoped` is undefined.
+ */
+export function selectVisionModels<T extends VisionModelLike>(
+	scoped: readonly { model: T }[] | undefined,
+	all: readonly T[],
+): T[] {
+	if (scoped && scoped.length > 0) {
+		return scoped.map((s) => s.model).filter((m) => m.input.includes("image"));
+	}
+	return all.filter((m) => m.input.includes("image"));
+}
+
 export function shouldStripImages(config: VisionConfig, modelInput: readonly string[] | undefined): boolean {
 	if (config.mode === "off") return false;
 	if (config.mode === "always") return true;

package/extensions/vision-proxy.ts

@@ -49,7 +49,7 @@ import { access, copyFile, mkdir, mkdtemp, readFile, readdir, rm } from "node:fs
 import os from "node:os";
 import { isAbsolute, join } from "node:path";
 import { promisify } from "node:util";
-import { type ImageContent as PiAiImage, type Api, type Model, type Context, type ProviderStreamOptions, type AssistantMessage } from "@earendil-works/pi-ai";
+import { type ImageContent as PiAiImage, type Api, type Model, type Context, type ProviderHeaders, type ProviderStreamOptions, type AssistantMessage } from "@earendil-works/pi-ai";
 
 type LegacyComplete = <TApi extends Api>(model: Model<TApi>, context: Context, options?: ProviderStreamOptions) => Promise<AssistantMessage>;
 
@@ -185,7 +185,9 @@ import {
 	resolveCropEntry,
 	sanitize,
 	sanitizeForLog,
+	sanitizeProviderHeaders,
 	shouldStripImages as shouldStripImagesPure,
+	selectVisionModels,
 	splitSubcommand,
 	stripImagePaths,
 	stripMediaPaths,
@@ -348,7 +350,11 @@ async function pickVisionModel(
 		);
 		return;
 	}
-	const vision = ctx.modelRegistry.getAll().filter((m) => m.input.includes("image"));
+	// Honor the session's model scope (ctx.scopedModels, pi ≥ 0.83.0) when set,
+	// so the picker mirrors the built-in /model selector instead of listing the
+	// whole catalogue. Falls back to the full registry when no scope is set or
+	// on runtimes that predate scopedModels.
+	const vision = selectVisionModels(ctx.scopedModels, ctx.modelRegistry.getAll());
 	if (vision.length === 0) {
 		ctx.ui.notify("[multimodal-proxy] No vision-capable models in registry.", "error");
 		return;
@@ -376,9 +382,11 @@ async function pickVisionModel(
 	if (providerSet.length === 1) {
 		providerPicked = providerSet[0];
 	} else {
-		// Start directly at the model list for the current (★) provider
-		// User can navigate back to pick a different provider
-		providerPicked = currentProvider;
+		// Start at the current (★) provider's model list when it's still in the
+		// scoped set; otherwise fall back to the first available scoped provider
+		// so the picker never opens on a provider with zero models (e.g. when a
+		// model scope excludes the persisted provider).
+		providerPicked = providerSet.includes(currentProvider) ? currentProvider : providerSet[0];
 	}
 
 	// Provider selection loop - re-enters when user picks "← Change provider"
@@ -812,7 +820,9 @@ async function analyzeVideo(
 	);
 
 	if (isXaiProvider(config.videoProvider)) {
-		return analyzeVideoViaXaiNative(mediaFile, filename, prompt, conversationContext, config, auth.apiKey, auth.headers, ctx, hash, mediaPath);
+		// sanitizeProviderHeaders: auth.headers is ProviderHeaders (Record<string, string | null>,
+		// pi ≥ 0.84) where null = deletion marker; the xAI raw-fetch path needs clean strings.
+		return analyzeVideoViaXaiNative(mediaFile, filename, prompt, conversationContext, config, auth.apiKey, sanitizeProviderHeaders(auth.headers), ctx, hash, mediaPath);
 	}
 
 	const contextBlock = conversationContext
@@ -897,11 +907,18 @@ async function analyzeVideoViaXaiNative(
 
 // ── analyze_image tool handler ─────────────────────────────────────────────
 
-function xaiHeaders(apiKey: string, extra?: Record<string, string>, contentType?: string): Record<string, string> {
-	const headers: Record<string, string> = {
-		...(extra ?? {}),
-		Authorization: extra?.Authorization ?? `Bearer ${apiKey}`,
-	};
+function xaiHeaders(apiKey: string, extra?: Record<string, string | null>, contentType?: string): Record<string, string> {
+	// `extra` may carry `null` header-deletion markers from ProviderHeaders (pi ≥ 0.84).
+	// Strip them: undici rejects non-string header values (TypeError) or would send a
+	// literal "null". Defense-in-depth — the xAI path also sanitizes at its boundary.
+	const headers: Record<string, string> = sanitizeProviderHeaders(extra);
+	// Only inject the default Bearer when the caller didn't address Authorization
+	// at all. An explicit `Authorization: null` is a pi ≥ 0.84 deletion marker and
+	// must be honored (suppress the header) rather than re-adding the key and
+	// forwarding a credential that was deliberately suppressed.
+	if (!extra || !("Authorization" in extra)) {
+		headers.Authorization ??= `Bearer ${apiKey}`;
+	}
 	if (contentType) headers["Content-Type"] = contentType;
 	return headers;
 }

package/package.json

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