pi-multimodal-proxy 1.6.0-beta.0 → 1.7.1

package/extensions/__tests__/internal.test.ts

@@ -8,15 +8,22 @@
  */
 
 import { strict as assert } from "node:assert";
-import { describe, it } from "node:test";
-import { mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { after, describe, it } from "node:test";
+import { lstat, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
 import os from "node:os";
-import { join } from "node:path";
+import { join, parse } from "node:path";
 import {
 	buildConversationContext,
 	buildDescriptionFence,
 	buildAnalysisFence,
+	buildVideoDescriptionFence,
+	buildVideoEmptyResponseError,
+	buildVideoProxySection,
 	clampPixels,
+	extractXaiResponsesText,
+	formatXaiSttTranscript,
+	isTranscriptionRequest,
+	isXaiProvider,
 	CUSTOM_TYPE_CONFIG,
 	CUSTOM_TYPE_CONSENT,
 	CUSTOM_TYPE_DESCRIPTION,
@@ -25,6 +32,8 @@ import {
 	envFlags,
 	escapeAttr,
 	extractCandidateImagePaths,
+	extractCandidateVideoPaths,
+	extractCandidateAudioPaths,
 	extractDimensions,
 	fenceUntrusted,
 	findDescriptions,
@@ -33,6 +42,7 @@ import {
 	hasConsent,
 	hashImageData,
 	IMAGE_PATH_PLACEHOLDER,
+	VIDEO_PATH_PLACEHOLDER,
 	isPathAllowed,
 	isValidNamedRegion,
 	LRUCache,
@@ -49,17 +59,27 @@ import {
 	hammingDistance,
 	computePHash,
 	cropImage,
+	shutdownCropWorkers,
 	piAiImageToBuffer,
 	bufferToPiAiImage,
 	shouldStripImages,
 	splitSubcommand,
 	stripImagePaths,
+	stripMediaPaths,
 	toPiAiImage,
 	type VisionConfig,
 	writePersistentFile,
 	sanitizeForLog,
 	storeImageMeta,
-	_imageMeta,
+	createImageMetaStore,
+	storeImageData,
+	getImageData,
+	createImageDataStore,
+	parseRecallRef,
+	spinnerFrame,
+	formatProgressStatus,
+	SPINNER_FRAMES,
+	RECALL_HINT,
 } from "../internal.ts";
 
 // SessionEntry minimal shape — typed loose because peer dep types are not loaded in test
@@ -89,6 +109,17 @@ describe("parseModelString", () => {
 		});
 	});
 
+	it("normalizes legacy x-ai provider id to Pi's xai provider", () => {
+		assert.deepEqual(parseModelString("x-ai/grok-4.3"), {
+			provider: "xai",
+			modelId: "grok-4.3",
+		});
+		assert.deepEqual(parseModelString("xai/grok-4.3"), {
+			provider: "xai",
+			modelId: "grok-4.3",
+		});
+	});
+
 	it("rejects malformed strings", () => {
 		assert.equal(parseModelString(""), null);
 		assert.equal(parseModelString("/foo"), null);
@@ -115,6 +146,12 @@ describe("sanitize", () => {
 		assert.equal(out.includeContext, DEFAULT_CONFIG.includeContext);
 	});
 
+	it("normalizes legacy x-ai provider id in config", () => {
+		const result = sanitize({ ...DEFAULT_CONFIG, provider: "x-ai", videoProvider: "x-ai" });
+		assert.equal(result.provider, "xai");
+		assert.equal(result.videoProvider, "xai");
+	});
+
 	it("preserves valid values", () => {
 		const cfg: VisionConfig = {
 			mode: "always",
@@ -163,6 +200,12 @@ describe("readEnvOverrides", () => {
 		assert.equal(out.modelId, "gpt-4o");
 	});
 
+	it("normalizes legacy x-ai video model env override", () => {
+		const out = readEnvOverrides({ PI_VISION_PROXY_VIDEO_MODEL: "x-ai/grok-4.3" });
+		assert.equal(out.videoProvider, "xai");
+		assert.equal(out.videoModelId, "grok-4.3");
+	});
+
 	it("ignores malformed model string", () => {
 		assert.deepEqual(readEnvOverrides({ PI_VISION_PROXY_MODEL: "noslash" }), {});
 	});
@@ -251,6 +294,152 @@ describe("pluralImages", () => {
 	});
 });
 
+describe("parseRecallRef", () => {
+	const hash = "a".repeat(32);
+
+	it("accepts a bare 32-hex hash", () => {
+		assert.equal(parseRecallRef(hash), hash);
+	});
+
+	it("accepts a sha256:-prefixed hash", () => {
+		assert.equal(parseRecallRef(`sha256:${hash}`), hash);
+	});
+
+	it("strips a #crop suffix and recalls the base image", () => {
+		assert.equal(parseRecallRef(`${hash}#crop:1840,120,840,360`), hash);
+	});
+
+	it("normalizes uppercase to lowercase", () => {
+		assert.equal(parseRecallRef("A".repeat(32)), hash);
+	});
+
+	it("rejects file paths and non-hash refs", () => {
+		assert.equal(parseRecallRef("/tmp/shot.png"), null);
+		assert.equal(parseRecallRef("./a.png"), null);
+		assert.equal(parseRecallRef("screenshot.png"), null);
+		// Wrong length / non-hex
+		assert.equal(parseRecallRef("a".repeat(31)), null);
+		assert.equal(parseRecallRef("a".repeat(33)), null);
+		assert.equal(parseRecallRef("z".repeat(32)), null);
+	});
+});
+
+describe("session image recall store", () => {
+	it("round-trips retained image bytes by hash", () => {
+		const store = createImageDataStore();
+		storeImageData(store, "hash1", "AAAA", "image/png");
+		const got = getImageData(store, "hash1");
+		assert.deepEqual(got, { data: "AAAA", mimeType: "image/png" });
+		assert.equal(getImageData(store, "missing"), undefined);
+	});
+
+	it("ignores empty hash or data", () => {
+		const store = createImageDataStore();
+		storeImageData(store, "", "AAAA", "image/png");
+		storeImageData(store, "hash", "", "image/png");
+		assert.equal(store.map.size, 0);
+	});
+
+	it("does not duplicate on re-store of the same hash", () => {
+		const store = createImageDataStore();
+		storeImageData(store, "hash1", "AAAA", "image/png");
+		storeImageData(store, "hash1", "AAAA", "image/png");
+		assert.equal(store.map.size, 1);
+	});
+
+	it("keeps stores isolated — one session's bytes do not leak into another (issue #12)", () => {
+		const sessionA = createImageDataStore();
+		const sessionB = createImageDataStore();
+		storeImageData(sessionA, "hash1", "AAAA", "image/png");
+		assert.deepEqual(getImageData(sessionA, "hash1"), { data: "AAAA", mimeType: "image/png" });
+		assert.equal(getImageData(sessionB, "hash1"), undefined);
+	});
+
+	it("evicts least-recently-used entries past the byte budget", () => {
+		const store = createImageDataStore();
+		const prev = process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+		// Budget of 10 decoded bytes; each 8-char base64 entry decodes to 6 bytes.
+		process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = "10";
+		try {
+			storeImageData(store, "h1", "AAAAAAAA", "image/png"); // 6 decoded bytes, total 6
+			storeImageData(store, "h2", "BBBBBBBB", "image/png"); // 6 decoded bytes, total 12 > 10 → evict h1
+			assert.equal(getImageData(store, "h1"), undefined);
+			assert.deepEqual(getImageData(store, "h2"), { data: "BBBBBBBB", mimeType: "image/png" });
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+			else process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = prev;
+		}
+	});
+
+	it("keeps a single oversized image rather than evicting everything", () => {
+		const store = createImageDataStore();
+		const prev = process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+		process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = "4";
+		try {
+			storeImageData(store, "big", "AAAAAAAAAAAA", "image/png"); // 9 decoded bytes > 4 budget
+			assert.deepEqual(getImageData(store, "big"), { data: "AAAAAAAAAAAA", mimeType: "image/png" });
+			assert.equal(store.map.size, 1);
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+			else process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = prev;
+		}
+	});
+
+	it("bumps recency on access so the touched entry survives eviction", () => {
+		const store = createImageDataStore();
+		const prev = process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+		// Budget of 14 decoded bytes; each 8-char base64 entry decodes to 6 bytes.
+		process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = "14";
+		try {
+			storeImageData(store, "h1", "AAAAAAAA", "image/png"); // 6 decoded bytes, total 6
+			storeImageData(store, "h2", "BBBBBBBB", "image/png"); // 6 decoded bytes, total 12
+			getImageData(store, "h1"); // bump h1 to most-recent
+			storeImageData(store, "h3", "CCCCCCCC", "image/png"); // 6 decoded bytes, total 18 > 14 → evict LRU (h2)
+			assert.deepEqual(getImageData(store, "h1"), { data: "AAAAAAAA", mimeType: "image/png" });
+			assert.equal(getImageData(store, "h2"), undefined);
+			assert.deepEqual(getImageData(store, "h3"), { data: "CCCCCCCC", mimeType: "image/png" });
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+			else process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES = prev;
+		}
+	});
+});
+
+describe("spinnerFrame", () => {
+	it("returns a frame from the set and wraps around", () => {
+		assert.equal(spinnerFrame(0), SPINNER_FRAMES[0]);
+		assert.equal(spinnerFrame(SPINNER_FRAMES.length), SPINNER_FRAMES[0]);
+		assert.equal(spinnerFrame(SPINNER_FRAMES.length + 1), SPINNER_FRAMES[1]);
+		assert.ok(SPINNER_FRAMES.includes(spinnerFrame(7)));
+	});
+
+	it("handles negative ticks without throwing", () => {
+		assert.ok(SPINNER_FRAMES.includes(spinnerFrame(-1)));
+		assert.ok(SPINNER_FRAMES.includes(spinnerFrame(-13)));
+	});
+});
+
+describe("formatProgressStatus", () => {
+	it("includes frame, label, and elapsed seconds", () => {
+		assert.equal(
+			formatProgressStatus("Analyzing image 2/4…", "⠙", 3),
+			"multimodal-proxy ⠙ Analyzing image 2/4… (3s)",
+		);
+	});
+
+	it("floors and clamps elapsed seconds", () => {
+		assert.match(formatProgressStatus("x", "⠋", 4.9), /\(4s\)$/);
+		assert.match(formatProgressStatus("x", "⠋", -2), /\(0s\)$/);
+	});
+});
+
+describe("RECALL_HINT", () => {
+	it("mentions analyze_image and the image id", () => {
+		assert.match(RECALL_HINT, /analyze_image/);
+		assert.match(RECALL_HINT, /image id/i);
+	});
+});
+
 describe("splitSubcommand", () => {
 	it("splits sub and value with arbitrary whitespace", () => {
 		assert.deepEqual(splitSubcommand("model anthropic/claude"), { sub: "model", value: "anthropic/claude" });
@@ -469,6 +658,46 @@ describe("extractCandidateImagePaths", () => {
 	});
 });
 
+describe("extractCandidateMediaPaths", () => {
+	it("detects quoted Windows video paths with spaces", () => {
+		const input = `video is not working: "D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4" transcribe this`;
+		assert.deepEqual(extractCandidateVideoPaths(input), [
+			"D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4",
+		]);
+	});
+
+	it("detects unquoted video paths without spaces", () => {
+		assert.deepEqual(extractCandidateVideoPaths("see D:\\Downloads\\clip.mp4 now"), ["D:\\Downloads\\clip.mp4"]);
+		assert.deepEqual(extractCandidateVideoPaths("see ./clip.mkv now"), ["./clip.mkv"]);
+	});
+
+	it("detects unquoted Windows video paths with spaces", () => {
+		const input = "Transcribe this video with timestamps D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4";
+		assert.deepEqual(extractCandidateVideoPaths(input), [
+			"D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4",
+		]);
+	});
+
+	it("detects quoted relative paths and audio paths with spaces", () => {
+		assert.deepEqual(extractCandidateVideoPaths(`see "./my video.mp4" now`), ["./my video.mp4"]);
+		assert.deepEqual(extractCandidateAudioPaths(`listen "C:\\Users\\Me\\Audio File.m4a" please`), [
+			"C:\\Users\\Me\\Audio File.m4a",
+		]);
+	});
+
+	it("does not treat unquoted paths with spaces as a single path", () => {
+		assert.deepEqual(extractCandidateVideoPaths("see ./my video.mp4 now"), []);
+	});
+});
+
+describe("stripMediaPaths", () => {
+	it("replaces media paths with placeholder", () => {
+		const mediaPath = "D:\\Downloads\\Rethinking Agents - Harness is All you Need_.mp4";
+		const result = stripMediaPaths(`transcribe "${mediaPath}" please`, [mediaPath]);
+		assert.equal(result, `transcribe "${VIDEO_PATH_PLACEHOLDER}" please`);
+	});
+});
+
 describe("stripImagePaths", () => {
 	it("replaces a single path with placeholder", () => {
 		const result = stripImagePaths("see /tmp/pi-clipboard-abc.png here", ["/tmp/pi-clipboard-abc.png"]);
@@ -517,29 +746,79 @@ describe("isPathAllowed", () => {
 		}
 	});
 
-	it("denies non-existent files", async () => {
-		assert.equal(await isPathAllowed(join(os.tmpdir(), "does-not-exist-xyz.png")), false);
+	it("allows non-existent files whose parent directory is in the allow-list", async () => {
+		// Non-existent files in tmpdir pass the check so callers can return "unreadable"
+		// instead of the misleading "denied" / "path outside allowed directories" message.
+		assert.equal(await isPathAllowed(join(os.tmpdir(), "does-not-exist-xyz.png")), true);
+	});
+
+	it("denies non-existent files outside the allow-list", async () => {
+		assert.equal(await isPathAllowed("/etc/does-not-exist-vp-xyz.png"), false);
+	});
+
+	it("allows files inside /tmp (system-wide Unix temp dir)", async () => {
+		if (os.platform() === "win32") return;
+		const file = join("/tmp", `vp-test-direct-${Date.now()}.png`);
+		await writeFile(file, TINY_PNG);
+		try {
+			assert.equal(await isPathAllowed(file), true);
+		} finally {
+			try { await rm(file); } catch { /* ignore */ }
+		}
+	});
+
+	it("allows non-existent files inside /tmp", async () => {
+		if (os.platform() === "win32") return;
+		assert.equal(await isPathAllowed("/tmp/does-not-exist-vp-xyz.png"), true);
+	});
+
+	it("allows local Windows drive paths by default", async () => {
+		const root = parse(process.cwd()).root;
+		if (!/^[a-z]:[\\/]/i.test(root)) return;
+		const prevDrives = process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+		try {
+			delete process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+			assert.equal(await isPathAllowed(process.cwd()), true);
+		} finally {
+			if (prevDrives === undefined) delete process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+			else process.env.PI_VISION_PROXY_ALLOW_DRIVES = prevDrives;
+		}
+	});
+
+	it("can disable local Windows drive path access with PI_VISION_PROXY_ALLOW_DRIVES=0", async () => {
+		const root = parse(process.cwd()).root;
+		if (!/^[a-z]:[\\/]/i.test(root)) return;
+		const prevDrives = process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+		try {
+			process.env.PI_VISION_PROXY_ALLOW_DRIVES = "0";
+			// cwd is still allowed by the cwd rule, so assert using the user home when it is outside cwd.
+			const home = os.homedir();
+			if (!home.toLowerCase().startsWith(process.cwd().toLowerCase())) {
+				assert.equal(await isPathAllowed(home), false);
+			}
+		} finally {
+			if (prevDrives === undefined) delete process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+			else process.env.PI_VISION_PROXY_ALLOW_DRIVES = prevDrives;
+		}
 	});
 
-	it("denies homedir files unless PI_VISION_PROXY_ALLOW_HOME=1", async () => {
-		// Use tmpdir as a stand-in we can write to; flip env to simulate the gate.
-		// We resolve a path that is neither under cwd nor tmp by asserting the env behaviour
-		// indirectly: with the flag set, an existing tmp file is still allowed (tmp wins);
-		// without it, that's also true. So we test the env path explicitly with realpath of
-		// homedir itself, which is a real, resolvable directory outside tmp/cwd.
+	it("allows homedir files when PI_VISION_PROXY_ALLOW_HOME=1", async () => {
 		const home = os.homedir();
-		const prev = process.env.PI_VISION_PROXY_ALLOW_HOME;
+		const prevHome = process.env.PI_VISION_PROXY_ALLOW_HOME;
+		const prevDrives = process.env.PI_VISION_PROXY_ALLOW_DRIVES;
 		try {
+			process.env.PI_VISION_PROXY_ALLOW_DRIVES = "0";
 			delete process.env.PI_VISION_PROXY_ALLOW_HOME;
-			// homedir() may equal cwd in odd setups; skip the assertion in that case.
 			if (!home.toLowerCase().startsWith(process.cwd().toLowerCase())) {
 				assert.equal(await isPathAllowed(home), false);
 			}
 			process.env.PI_VISION_PROXY_ALLOW_HOME = "1";
 			assert.equal(await isPathAllowed(home), true);
 		} finally {
-			if (prev === undefined) delete process.env.PI_VISION_PROXY_ALLOW_HOME;
-			else process.env.PI_VISION_PROXY_ALLOW_HOME = prev;
+			if (prevHome === undefined) delete process.env.PI_VISION_PROXY_ALLOW_HOME;
+			else process.env.PI_VISION_PROXY_ALLOW_HOME = prevHome;
+			if (prevDrives === undefined) delete process.env.PI_VISION_PROXY_ALLOW_DRIVES;
+			else process.env.PI_VISION_PROXY_ALLOW_DRIVES = prevDrives;
 		}
 	});
 });
@@ -567,13 +846,20 @@ describe("readImageFileWithReason", () => {
 	});
 
 	it("returns reason=denied for path outside allow-list", async () => {
-		// /etc/passwd.png does not exist but extension is image-like.
-		// realpath fails → denied. Either reason is acceptable in that order; assert non-null reason.
 		const r = await readImageFileWithReason("/etc/never-exists-vp.png");
 		assert.equal(r.image, null);
 		assert.equal(r.reason, "denied");
 	});
 
+	it("returns reason=unreadable for non-existent file inside /tmp", async () => {
+		if (os.platform() === "win32") return;
+		// Previously returned "denied" (misleading); now returns "unreadable" so the user
+		// knows the file is simply missing, not that /tmp itself is forbidden.
+		const r = await readImageFileWithReason("/tmp/does-not-exist-vp-xyz.png");
+		assert.equal(r.image, null);
+		assert.equal(r.reason, "unreadable");
+	});
+
 	it("returns reason=empty for zero-byte image", async () => {
 		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
 		const file = join(dir, "empty.png");
@@ -622,6 +908,34 @@ describe("readImageFileWithReason", () => {
 			await rm(dir, { recursive: true, force: true });
 		}
 	});
+
+	it("denies symlink to existing file outside allow-list (TOCTOU post-read check)", async () => {
+		// Simulate the TOCTOU race: the symlink target exists and is readable, so
+		// readFile() succeeds, but the post-read realpath re-verification must catch that
+		// the resolved path is outside the allow-list and return "denied".
+		if (os.platform() === "win32") return;
+		// Find a readable file outside the allow-list to use as a target.
+		// /etc/hostname is present on most Unix systems; use it if it exists.
+		const target = "/etc/hostname";
+		let targetExists = false;
+		try { await lstat(target); targetExists = true; } catch { /* skip if absent */ }
+		if (!targetExists) return;
+
+		const dir = await mkdtemp(join(os.tmpdir(), "vp-test-"));
+		const link = join(dir, "link.png");
+		try {
+			try {
+				await symlink(target, link);
+			} catch {
+				return; // no symlink support → skip
+			}
+			const r = await readImageFileWithReason(link);
+			assert.equal(r.image, null);
+			assert.equal(r.reason, "denied");
+		} finally {
+			await rm(dir, { recursive: true, force: true });
+		}
+	});
 });
 
 describe("readPersistentFile / writePersistentFile", () => {
@@ -954,6 +1268,82 @@ describe("extractDimensions", () => {
 	});
 });
 
+describe("buildVideoDescriptionFence", () => {
+	it("builds video fence with file, hash, and mime attributes", () => {
+		const fence = buildVideoDescriptionFence("abc123", "clip.mp4", "video/mp4", "Hello world");
+		assert.ok(fence.includes('file="clip.mp4"'));
+		assert.ok(fence.includes('hash="abc123"'));
+		assert.ok(fence.includes('mime="video/mp4"'));
+		assert.ok(fence.includes("Hello world"));
+	});
+});
+
+describe("buildVideoEmptyResponseError", () => {
+	it("returns actionable guidance for providers that accept video but return no text", () => {
+		const message = buildVideoEmptyResponseError("xai", "grok-4.3");
+		assert.ok(message.includes("empty response from xai/grok-4.3"));
+		assert.ok(message.includes("provider accepted the request but returned no text"));
+		assert.ok(message.includes("native xAI STT or Files/Responses path"));
+		assert.ok(message.includes("shorter clip"));
+		assert.ok(message.includes("smaller/transcoded video"));
+		assert.ok(message.includes("Gemini"));
+	});
+});
+
+describe("xAI native media helpers", () => {
+	it("detects transcription requests", () => {
+		assert.equal(isTranscriptionRequest("Transcribe this video with timestamps"), true);
+		assert.equal(isTranscriptionRequest("make SRT captions"), true);
+		assert.equal(isTranscriptionRequest("summarize visual scenes"), false);
+	});
+
+	it("detects xAI provider aliases", () => {
+		assert.equal(isXaiProvider("xai"), true);
+		assert.equal(isXaiProvider("x-ai"), true);
+		assert.equal(isXaiProvider("google"), false);
+	});
+
+	it("formats xAI STT words into timestamped transcript", () => {
+		const formatted = formatXaiSttTranscript({
+			text: "Hello world.",
+			language: "English",
+			duration: 1.5,
+			words: [
+				{ text: "Hello", start: 0.1, end: 0.5 },
+				{ text: "world.", start: 0.6, end: 1.2 },
+			],
+		}, "clip.mp4");
+		assert.ok(formatted.includes("xAI Speech-to-Text transcription for clip.mp4"));
+		assert.ok(formatted.includes("Detected language: English"));
+		assert.ok(formatted.includes("[00:00"));
+		assert.ok(formatted.includes("Hello world."));
+	});
+
+	it("extracts output text from xAI Responses objects", () => {
+		assert.equal(extractXaiResponsesText({ output_text: "direct" }), "direct");
+		assert.equal(extractXaiResponsesText({ output: [{ type: "message", content: [{ type: "output_text", text: "nested" }] }] }), "nested");
+	});
+});
+
+describe("buildVideoProxySection", () => {
+	it("instructs downstream agents to use injected video analysis instead of local transcription tools", () => {
+		const section = buildVideoProxySection(
+			1,
+			"x-ai",
+			"grok-4.3",
+			buildVideoDescriptionFence("abc123", "clip.mp4", "video/mp4", "[00:00] hello"),
+		);
+		assert.ok(section.includes("already analyzed the media"));
+		assert.ok(section.includes("answer from this injected context"));
+		assert.ok(section.includes("Do not run local media-processing or transcription tools"));
+		assert.ok(section.includes("ffmpeg"));
+		assert.ok(section.includes("Whisper"));
+		assert.ok(section.includes("Python"));
+		assert.ok(section.includes("Only use external/local tools"));
+		assert.ok(section.includes("<vision_proxy_video_description"));
+	});
+});
+
 describe("buildDescriptionFence", () => {
 	it("builds fence with metadata attributes", () => {
 		const fence = buildDescriptionFence("abc123", "A screenshot", { width: 1920, height: 1080, filename: "screen.png" });
@@ -1143,6 +1533,10 @@ async function create10x10Png(): Promise<Buffer> {
 }
 
 describe("cropImage (ImageScript)", () => {
+	after(async () => {
+		await shutdownCropWorkers();
+	});
+
 	it("crops a 10×10 PNG to a 5×5 region", async () => {
 		const png = await create10x10Png();
 		const crop = { x: 2, y: 3, width: 5, height: 5 };
@@ -1177,6 +1571,92 @@ describe("cropImage (ImageScript)", () => {
 		assert.equal(result[0], 0xff);
 		assert.equal(result[1], 0xd8);
 	});
+
+	it("succeeds within a generous decode timeout (env override is honoured)", async () => {
+		const prev = process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS;
+		process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS = "10000";
+		try {
+			const png = await create10x10Png();
+			const result = await cropImage(png, { x: 0, y: 0, width: 10, height: 10 }, "image/png");
+			assert.ok(result, "crop should succeed with a generous timeout");
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS;
+			else process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS = prev;
+		}
+	});
+
+	it("returns null (no throw) for undecodable garbage bytes", async () => {
+		const garbage = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0x01, 0x02, 0x03, 0x04, 0x05]);
+		const result = await cropImage(garbage, { x: 0, y: 0, width: 5, height: 5 }, "image/png");
+		assert.equal(result, null);
+	});
+
+	it("falls back to the in-thread path when the worker is disabled", async () => {
+		const prev = process.env.PI_VISION_PROXY_DECODE_WORKER;
+		process.env.PI_VISION_PROXY_DECODE_WORKER = "0";
+		try {
+			const png = await create10x10Png();
+			const result = await cropImage(png, { x: 2, y: 3, width: 5, height: 5 }, "image/png");
+			assert.ok(result, "in-thread fallback should still crop");
+			const dims = extractDimensions(result);
+			assert.ok(dims && dims.width === 5 && dims.height === 5, "fallback crop should have correct dims");
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_DECODE_WORKER;
+			else process.env.PI_VISION_PROXY_DECODE_WORKER = prev;
+		}
+	});
+
+	it("handles several sequential crops (worker pool reuse)", async () => {
+		const png = await create10x10Png();
+		for (let i = 0; i < 5; i++) {
+			const result = await cropImage(png, { x: 0, y: 0, width: 5, height: 5 }, "image/png");
+			assert.ok(result, `crop ${i} should succeed`);
+			const dims = extractDimensions(result);
+			assert.ok(dims && dims.width === 5 && dims.height === 5, `crop ${i} dims`);
+		}
+	});
+
+	it("works with pooling disabled (spawn-per-call)", async () => {
+		const prev = process.env.PI_VISION_PROXY_DECODE_WORKER_POOL;
+		process.env.PI_VISION_PROXY_DECODE_WORKER_POOL = "0";
+		try {
+			const png = await create10x10Png();
+			const a = await cropImage(png, { x: 0, y: 0, width: 5, height: 5 }, "image/png");
+			const b = await cropImage(png, { x: 1, y: 1, width: 4, height: 4 }, "image/png");
+			assert.ok(a && b, "both crops should succeed without pooling");
+		} finally {
+			if (prev === undefined) delete process.env.PI_VISION_PROXY_DECODE_WORKER_POOL;
+			else process.env.PI_VISION_PROXY_DECODE_WORKER_POOL = prev;
+		}
+	});
+
+	it("hard-terminates the worker on timeout (returns null, does not hang)", async () => {
+		// Force pool=0 so a *fresh* worker is spawned (never a warmed pooled one).
+		// Spinning up a thread + loading ImageScript + instantiating the WASM codec
+		// is reliably far slower than the 1ms timeout regardless of machine speed,
+		// so the main-thread timer fires and terminate()s the worker — proving the
+		// timeout is a hard limit, without depending on wall-clock scheduling luck.
+		const prevWorker = process.env.PI_VISION_PROXY_DECODE_WORKER;
+		const prevPool = process.env.PI_VISION_PROXY_DECODE_WORKER_POOL;
+		const prevTimeout = process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS;
+		process.env.PI_VISION_PROXY_DECODE_WORKER = "1";
+		process.env.PI_VISION_PROXY_DECODE_WORKER_POOL = "0";
+		process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS = "1";
+		try {
+			const png = await create10x10Png();
+			const started = Date.now();
+			const result = await cropImage(png, { x: 0, y: 0, width: 10, height: 10 }, "image/png");
+			assert.equal(result, null, "timed-out crop should return null");
+			assert.ok(Date.now() - started < 5000, "should return promptly, not hang");
+		} finally {
+			if (prevWorker === undefined) delete process.env.PI_VISION_PROXY_DECODE_WORKER;
+			else process.env.PI_VISION_PROXY_DECODE_WORKER = prevWorker;
+			if (prevPool === undefined) delete process.env.PI_VISION_PROXY_DECODE_WORKER_POOL;
+			else process.env.PI_VISION_PROXY_DECODE_WORKER_POOL = prevPool;
+			if (prevTimeout === undefined) delete process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS;
+			else process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS = prevTimeout;
+		}
+	});
 });
 
 describe("piAiImageToBuffer / bufferToPiAiImage", () => {
@@ -1780,8 +2260,9 @@ describe("Security: image decode bomb protection", () => {
 		const img = new Image(100, 100);
 		const encoded = Buffer.from(await img.encode(1));
 		const hash = "test-decode-bomb-normal";
-		storeImageMeta(hash, encoded);
-		const meta = _imageMeta.get(hash);
+		const store = createImageMetaStore();
+		storeImageMeta(store, hash, encoded);
+		const meta = store.get(hash);
 		// Normal image should be accepted
 		assert.ok(meta, "normal image should be stored");
 	});
@@ -1872,10 +2353,21 @@ describe("Review fixes: storeImageMeta filename backfill", () => {
 		const img = new Image(50, 60);
 		const encoded = Buffer.from(await img.encode(1));
 		const hash = "test-backfill-filename";
-		storeImageMeta(hash, encoded); // first call, no filename
-		storeImageMeta(hash, encoded, "photo.png"); // second call, with filename
-		const meta = _imageMeta.get(hash);
+		const store = createImageMetaStore();
+		storeImageMeta(store, hash, encoded); // first call, no filename
+		storeImageMeta(store, hash, encoded, "photo.png"); // second call, with filename
+		const meta = store.get(hash);
 		assert.ok(meta, "meta should exist");
 		assert.equal(meta!.filename, "photo.png", "filename should be backfilled");
 	});
+
+	it("keeps stores isolated — one session's metadata does not leak into another (issue #12)", async () => {
+		const { Image } = await import("imagescript");
+		const encoded = Buffer.from(await new Image(40, 30).encode(1));
+		const sessionA = createImageMetaStore();
+		const sessionB = createImageMetaStore();
+		storeImageMeta(sessionA, "shared-hash", encoded, "a.png");
+		assert.ok(sessionA.get("shared-hash"), "session A should have the metadata");
+		assert.equal(sessionB.get("shared-hash"), undefined, "session B must not inherit it");
+	});
 });