pi-multimodal-proxy 1.6.0 → 1.7.1

package/extensions/internal.ts

@@ -4,7 +4,7 @@
  */
 
 import { createHash } from "node:crypto";
-import { mkdir, readFile, realpath, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, writeFile } from "node:fs/promises";
 import os from "node:os";
 import { basename, dirname, extname, join, parse, relative } from "node:path";
 import type { ImageContent as PiAiImage } from "@earendil-works/pi-ai";
@@ -55,22 +55,162 @@ export interface ImageMeta {
 	filename?: string; // basename only
 }
 
-/** In-memory map: image hash → dimensions + filename. Populated on first ingestion. */
-export const _imageMeta = new Map<string, ImageMeta>();
+/**
+ * In-memory map: image hash → dimensions + filename, populated on first
+ * ingestion. Held per session (see SessionState in vision-proxy) rather than as
+ * a process-global, so forked/resumed sessions never inherit stale metadata.
+ */
+export type ImageMetaStore = Map<string, ImageMeta>;
+
+/** Create an empty per-session image-metadata store. */
+export function createImageMetaStore(): ImageMetaStore {
+	return new Map<string, ImageMeta>();
+}
 
 /** Maximum pixel dimension for decoded images. Prevents decode bombs (e.g., 10 MB PNG → 500 MB bitmap). */
 const MAX_IMAGE_DIMENSION = 16384; // 16K × 16K ≈ 1 billion pixels max
 
-/** Maximum entries in _imageMeta to prevent unbounded memory growth. */
+/** Maximum entries per image-metadata store to prevent unbounded memory growth. */
 const IMAGE_META_MAX = 500;
 
-function evictImageMeta(): void {
-	while (_imageMeta.size > IMAGE_META_MAX) {
-		const first = _imageMeta.keys().next().value;
-		if (first !== undefined) _imageMeta.delete(first);
+function evictImageMeta(meta: ImageMetaStore): void {
+	while (meta.size > IMAGE_META_MAX) {
+		const first = meta.keys().next().value;
+		if (first !== undefined) meta.delete(first);
+	}
+}
+
+// ── Session image recall ────────────────────────────────────────────────────
+//
+// Retains the actual image bytes (base64) of images seen this session, keyed by
+// hash, so the agent can re-query a previously-seen image with analyze_image
+// even when it is no longer attached to the current turn (e.g. a screenshot the
+// user pasted several turns ago). Storage is in-memory only — image bytes are
+// never written to the session log or disk, keeping the existing data-egress
+// posture intact. Insertion order is used for LRU eviction once the byte budget
+// is exceeded.
+
+/**
+ * Per-session retained-bytes store for image recall: hash → base64 bytes + mime
+ * type, plus a running total of decoded bytes for budget enforcement. Held per
+ * session (see SessionState in vision-proxy) so retained image bytes never leak
+ * across sessions, mirroring the per-session image-metadata store.
+ */
+export interface ImageDataStore {
+	map: Map<string, { data: string; mimeType: string }>;
+	totalBytes: number;
+}
+
+/** Create an empty per-session image-recall byte store. */
+export function createImageDataStore(): ImageDataStore {
+	return { map: new Map(), totalBytes: 0 };
+}
+
+/** Default byte budget for retained image data (decoded bytes, ≈64 MB). */
+const IMAGE_DATA_MAX_BYTES_DEFAULT = 64 * 1024 * 1024;
+
+/** Resolve the recall byte budget, allowing an env override. */
+function imageDataMaxBytes(): number {
+	const raw = process.env.PI_VISION_PROXY_IMAGE_RECALL_BYTES;
+	if (raw) {
+		const n = Number.parseInt(raw, 10);
+		if (Number.isFinite(n) && n >= 0) return n;
+	}
+	return IMAGE_DATA_MAX_BYTES_DEFAULT;
+}
+
+function evictImageData(store: ImageDataStore): void {
+	const budget = imageDataMaxBytes();
+	// When budget is 0, allow full eviction (recall disabled).
+	// Otherwise keep at least one entry so an oversized image is still recallable.
+	const minRetained = budget === 0 ? 0 : 1;
+	while (store.totalBytes > budget && store.map.size > minRetained) {
+		const first = store.map.keys().next().value;
+		if (first === undefined) break;
+		const v = store.map.get(first);
+		store.map.delete(first);
+		if (v) store.totalBytes -= Buffer.byteLength(v.data, "base64");
+	}
+}
+
+/** Retain an image's bytes for later recall. No-op if already retained (LRU bumped). */
+export function storeImageData(store: ImageDataStore, hash: string, data: string, mimeType: string): void {
+	if (!hash || !data) return;
+	const existing = store.map.get(hash);
+	if (existing) {
+		// Bump recency: re-insert at the end of the iteration order.
+		store.map.delete(hash);
+		store.map.set(hash, existing);
+		return;
+	}
+	store.map.set(hash, { data, mimeType });
+	store.totalBytes += Buffer.byteLength(data, "base64");
+	evictImageData(store);
+}
+
+/** Fetch retained image bytes by hash, bumping recency. Undefined if not retained. */
+export function getImageData(store: ImageDataStore, hash: string): { data: string; mimeType: string } | undefined {
+	const v = store.map.get(hash);
+	if (v) {
+		store.map.delete(hash);
+		store.map.set(hash, v);
 	}
+	return v;
+}
+
+/** Test/maintenance helper: drop all retained image bytes. */
+export function clearImageData(store: ImageDataStore): void {
+	store.map.clear();
+	store.totalBytes = 0;
+}
+
+/**
+ * Parse an analyze_image reference as a session-recall handle.
+ *
+ * Accepts the `image="..."` value carried by <vision_proxy_description> and
+ * related fences — either a bare hash, a `sha256:`-prefixed hash, or a hash with
+ * a `#crop:...` suffix (the crop suffix is ignored; recall returns the full
+ * image and any crop is re-applied via the tool's crop argument). Returns the
+ * normalized lowercase hash, or null if the reference is not a recall handle
+ * (in which case it should be treated as a file path).
+ */
+export function parseRecallRef(ref: string): string | null {
+	let s = ref.trim();
+	if (s.startsWith("sha256:")) s = s.slice("sha256:".length);
+	const hashPart = s.split("#")[0];
+	const re = new RegExp(`^[a-f0-9]{${HASH_HEX_LEN}}$`, "i");
+	return re.test(hashPart) ? hashPart.toLowerCase() : null;
+}
+
+// ── Live progress indicator ─────────────────────────────────────────────────
+
+/** Braille spinner frames used by the live status indicator during slow calls. */
+export const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+/** Pick a spinner frame for a given tick (wraps around). */
+export function spinnerFrame(tick: number): string {
+	const n = SPINNER_FRAMES.length;
+	const i = ((Math.trunc(tick) % n) + n) % n;
+	return SPINNER_FRAMES[i];
+}
+
+/** Format the status-line text shown while a vision/video call is in flight. */
+export function formatProgressStatus(label: string, frame: string, elapsedSec: number): string {
+	const secs = Math.max(0, Math.trunc(elapsedSec));
+	return `multimodal-proxy ${frame} ${label} (${secs}s)`;
 }
 
+// ── Recall affordance ───────────────────────────────────────────────────────
+
+/**
+ * Persistent reminder injected once per turn alongside recalled image
+ * descriptions, restating that earlier images can be re-queried by id. This is
+ * trusted extension text (not image-derived), so it is placed outside the
+ * untrusted description fence.
+ */
+export const RECALL_HINT =
+	'You can re-examine or crop this or any earlier image at any time by calling analyze_image with its image id (the image="…" value above) — no re-attachment or file path needed.';
+
 // ── Crop types ────────────────────────────────────────────────────────────
 
 export type NamedRegion =
@@ -919,16 +1059,33 @@ function driveAccessDisabled(): boolean {
 
 /**
  * Check that a resolved file path is within a safe directory.
- * By default allows tmpdir, cwd, and local Windows drive paths; opt into homedir
- * on non-drive platforms via PI_VISION_PROXY_ALLOW_HOME=1.
+ * By default allows tmpdir, /tmp (system-wide Unix temp), cwd, and local Windows drive paths;
+ * opt into homedir on non-drive platforms via PI_VISION_PROXY_ALLOW_HOME=1.
  * Both sides are canonicalized via realpath to handle symlinks and Windows 8.3 short names.
+ * If the target file does not exist, the parent directory is resolved so callers can
+ * distinguish "allowed dir but missing file" (→ "unreadable") from a genuinely denied path.
  */
 export async function isPathAllowed(filePath: string): Promise<boolean> {
 	let resolved: string;
 	try {
 		resolved = (await realpath(filePath)).toLowerCase();
 	} catch {
-		return false;
+		// realpath failed. Determine whether the path itself exists (e.g. broken symlink)
+		// or is simply absent. For broken symlinks the target is outside our control, so
+		// deny. For absent paths, fall back to the parent directory so that
+		// readImageFileWithReason can return "unreadable" rather than the misleading "denied".
+		try {
+			await lstat(filePath); // succeeds for broken symlinks; throws for absent paths
+			return false; // path exists (broken symlink or inaccessible) — deny
+		} catch {
+			// Path is absent — resolve via parent to check if it would be in an allowed dir.
+		}
+		const parent = dirname(filePath);
+		try {
+			resolved = join((await realpath(parent)).toLowerCase(), basename(filePath).toLowerCase());
+		} catch {
+			return false;
+		}
 	}
 
 	const tmp = await canonical(os.tmpdir?.() ?? "/tmp");
@@ -937,6 +1094,14 @@ export async function isPathAllowed(filePath: string): Promise<boolean> {
 	if (tmp && isInsideOrSame(resolved, tmp)) return true;
 	if (cwd && isInsideOrSame(resolved, cwd)) return true;
 
+	// On Unix, /tmp (the POSIX system-wide temp dir) may differ from os.tmpdir()
+	// (e.g. on macOS where os.tmpdir() returns a per-user dir like /var/folders/…/T).
+	// Allow it explicitly so files written to /tmp are always accessible.
+	if (os.platform() !== "win32") {
+		const unixTmp = await canonical("/tmp");
+		if (unixTmp && unixTmp !== tmp && isInsideOrSame(resolved, unixTmp)) return true;
+	}
+
 	if (process.env.PI_VISION_PROXY_ALLOW_HOME === "1") {
 		const home = await canonical(os.homedir?.());
 		if (home && isInsideOrSame(resolved, home)) return true;
@@ -960,6 +1125,11 @@ export async function readImageFileWithReason(filePath: string): Promise<ReadIma
 	} catch {
 		return { image: null, reason: "unreadable" };
 	}
+	// Post-read re-verification: the initial isPathAllowed() may have passed via the
+	// parent-dir fallback when the file did not yet exist. A symlink could have been
+	// swapped in during that window. Now that the file exists, realpath() resolves it
+	// fully — catching any symlink pointing outside the allow-list (TOCTOU mitigation).
+	if (!(await isPathAllowed(filePath))) return { image: null, reason: "denied" };
 	if (content.length === 0) return { image: null, reason: "empty", bytes: 0 };
 	const limit = maxImageFileBytes();
 	if (content.length > limit) return { image: null, reason: "too-large", bytes: content.length };
@@ -1194,8 +1364,8 @@ function safeDimensions(data: Buffer): { width: number; height: number } | undef
 	return dims;
 }
 
-export function storeImageMeta(hash: string, imageBufferOrData: Buffer | string, filename?: string): void {
-	const existing = _imageMeta.get(hash);
+export function storeImageMeta(meta: ImageMetaStore, hash: string, imageBufferOrData: Buffer | string, filename?: string): void {
+	const existing = meta.get(hash);
 	if (existing) {
 		// Backfill filename if previously stored without one
 		if (filename && !existing.filename) {
@@ -1217,8 +1387,8 @@ export function storeImageMeta(hash: string, imageBufferOrData: Buffer | string,
 	}
 	const dims = safeDimensions(buf);
 	if (dims) {
-		_imageMeta.set(hash, { width: dims.width, height: dims.height, filename });
-		evictImageMeta();
+		meta.set(hash, { width: dims.width, height: dims.height, filename });
+		evictImageMeta(meta);
 	}
 }
 
@@ -1342,10 +1512,285 @@ export function cropSignature(crop: ResolvedCrop): string {
 /** Whether ImageScript is available for cropping. */
 export const hasCropper = true;
 
+/**
+ * Wall-clock limit for a single image decode, in milliseconds. Override via env
+ * for slow hosts or very large legitimate images.
+ */
+function decodeTimeoutMs(): number {
+	const raw = process.env.PI_VISION_PROXY_DECODE_TIMEOUT_MS;
+	if (raw) {
+		const n = Number.parseInt(raw, 10);
+		if (Number.isFinite(n) && n > 0) return n;
+	}
+	return 5000;
+}
+
+/**
+ * Decode image bytes, rejecting if the decoder does not settle within the
+ * timeout.
+ *
+ * SCOPE / LIMITATION: ImageScript's codecs are synchronous WASM. Once the WASM
+ * `decode()` call starts it blocks the single Node thread until it returns, so
+ * this timer cannot pre-empt a decode that is genuinely spinning on a crafted
+ * body — the timeout callback can't run while the event loop is blocked. What
+ * this wrapper *does* bound is the portions that yield (first-call WASM
+ * instantiation and any async codec paths) and it stops a late-resolving decode
+ * from leaving the caller hanging forever. The primary defence against
+ * pathological inputs remains the dimension pre-check in cropImage(); full CPU
+ * isolation would require running the decode in a terminable worker thread.
+ */
+async function decodeWithTimeout(imageBytes: Buffer): Promise<Image> {
+	const timeoutMs = decodeTimeoutMs();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timeout = new Promise<never>((_resolve, reject) => {
+		timer = setTimeout(() => reject(new Error(`Image.decode exceeded ${timeoutMs}ms timeout`)), timeoutMs);
+	});
+	try {
+		return await Promise.race([Image.decode(new Uint8Array(imageBytes)), timeout]);
+	} finally {
+		if (timer) clearTimeout(timer);
+	}
+}
+
+/**
+ * In-thread decode → crop → encode. Bounded only by decodeWithTimeout, which
+ * cannot pre-empt a synchronous WASM hang (see its doc). Used as a fallback when
+ * the worker path is unavailable or disabled.
+ */
+async function cropInThread(
+	imageBytes: Buffer,
+	crop: ResolvedCrop,
+	mimeType?: string,
+): Promise<Buffer | null> {
+	const img = await decodeWithTimeout(imageBytes);
+	// Double-check decoded dimensions (image-size is header-only, actual may differ)
+	if (img.width > MAX_IMAGE_DIMENSION || img.height > MAX_IMAGE_DIMENSION) {
+		return null;
+	}
+	const cropped = img.crop(crop.x, crop.y, crop.width, crop.height);
+	let encoded: Uint8Array;
+	if (mimeType === "image/png") {
+		encoded = await cropped.encode(1); // PNG with compression level 1 (fast)
+	} else {
+		encoded = await cropped.encodeJPEG(90); // JPEG quality 90
+	}
+	return Buffer.from(encoded);
+}
+
+/** Sentinel: the worker path could not run (worker_threads unavailable / disabled). */
+const WORKER_UNAVAILABLE = Symbol("worker-unavailable");
+
+/** Whether to offload decode/crop/encode to a terminable worker thread. Default on. */
+function decodeWorkerEnabled(): boolean {
+	const raw = process.env.PI_VISION_PROXY_DECODE_WORKER?.toLowerCase();
+	return raw !== "0" && raw !== "false" && raw !== "no" && raw !== "off";
+}
+
+// Persistent CommonJS worker body (run via `{ eval: true }`). ImageScript is
+// loaded once from the path supplied in workerData, then the worker serves crop
+// tasks in a message loop so a pooled worker can be reused across calls without
+// paying decode-library init each time. Running in a worker is what makes the
+// timeout a *hard* limit: the main thread stays responsive and can terminate()
+// this thread mid-decode, which a same-thread Promise.race cannot do against
+// synchronous WASM.
+const CROP_WORKER_SRC = `
+const { parentPort, workerData } = require("worker_threads");
+const { Image } = require(workerData.imagescriptPath);
+parentPort.on("message", async (task) => {
+	const { bytes, crop, mimeType, maxDim } = task;
+	try {
+		const img = await Image.decode(new Uint8Array(bytes));
+		if (img.width > maxDim || img.height > maxDim) { parentPort.postMessage({ ok: false }); return; }
+		const cropped = img.crop(crop.x, crop.y, crop.width, crop.height);
+		const encoded = mimeType === "image/png" ? await cropped.encode(1) : await cropped.encodeJPEG(90);
+		const u8 = encoded instanceof Uint8Array ? encoded : new Uint8Array(encoded);
+		const out = u8.buffer.slice(u8.byteOffset, u8.byteOffset + u8.byteLength);
+		parentPort.postMessage({ ok: true, data: out }, [out]);
+	} catch (e) {
+		parentPort.postMessage({ ok: false, error: String((e && e.message) || e) });
+	}
+});
+`;
+
+type NodeWorker = import("node:worker_threads").Worker;
+
+/** An idle pooled worker plus the cleanup that detaches its idle-health listeners. */
+interface PooledWorker {
+	worker: NodeWorker;
+	detach: () => void;
+}
+
+/** Idle, reusable workers. Bounded by maxIdleWorkers(); unref'd so they never block process exit. */
+const _idleWorkers: PooledWorker[] = [];
+
+/** Maximum idle workers retained between calls. 0 disables pooling (spawn-per-call). */
+function maxIdleWorkers(): number {
+	const raw = process.env.PI_VISION_PROXY_DECODE_WORKER_POOL;
+	if (raw) {
+		const n = Number.parseInt(raw, 10);
+		if (Number.isFinite(n) && n >= 0) return n;
+	}
+	return 2;
+}
+
+let _workerCtor: typeof import("node:worker_threads").Worker | null = null;
+let _imagescriptPath: string | null = null;
+let _workerInfraResolved = false;
+
+/** Resolve the Worker constructor and ImageScript path once. Returns false if unavailable. */
+async function ensureWorkerInfra(): Promise<boolean> {
+	if (_workerInfraResolved) return _workerCtor !== null && _imagescriptPath !== null;
+	_workerInfraResolved = true;
+	try {
+		_workerCtor = (await import("node:worker_threads")).Worker;
+		const { createRequire } = await import("node:module");
+		_imagescriptPath = createRequire(import.meta.url).resolve("imagescript");
+		return true;
+	} catch {
+		_workerCtor = null;
+		_imagescriptPath = null;
+		return false;
+	}
+}
+
+/** Take an idle worker (detaching its health listeners) or spawn a fresh one. */
+function acquireWorker(): NodeWorker {
+	const budget = maxIdleWorkers();
+	// Honor the *current* budget before reusing anything: terminate idle workers
+	// beyond it so a lowered PI_VISION_PROXY_DECODE_WORKER_POOL takes effect
+	// immediately rather than waiting for the pool to drain naturally. With
+	// budget 0 this empties the pool, making spawn-per-call truly spawn-per-call.
+	while (_idleWorkers.length > budget) {
+		const extra = _idleWorkers.pop()!;
+		extra.detach();
+		void extra.worker.terminate();
+	}
+	// Only reuse a pooled worker when pooling is enabled.
+	if (budget > 0) {
+		const pooled = _idleWorkers.pop();
+		if (pooled) {
+			pooled.detach();
+			pooled.worker.ref();
+			return pooled.worker;
+		}
+	}
+	// _workerCtor / _imagescriptPath are non-null here (ensureWorkerInfra succeeded).
+	return new _workerCtor!(CROP_WORKER_SRC, {
+		eval: true,
+		workerData: { imagescriptPath: _imagescriptPath },
+	});
+}
+
+/** Return a healthy worker to the idle pool (unref'd), or terminate it if the pool is full. */
+function releaseWorker(worker: NodeWorker): void {
+	if (_idleWorkers.length >= maxIdleWorkers()) {
+		void worker.terminate();
+		return;
+	}
+	// If the worker dies while idle, drop it from the pool so it is never reused.
+	const onDeath = () => {
+		const i = _idleWorkers.findIndex((p) => p.worker === worker);
+		if (i >= 0) _idleWorkers.splice(i, 1);
+	};
+	worker.once("exit", onDeath);
+	worker.once("error", onDeath);
+	worker.unref();
+	_idleWorkers.push({
+		worker,
+		detach: () => {
+			worker.off("exit", onDeath);
+			worker.off("error", onDeath);
+		},
+	});
+}
+
+/** Run one crop task on a worker with a hard timeout. `reusable` is false on timeout/error. */
+function runCropTask(
+	worker: NodeWorker,
+	task: { bytes: ArrayBuffer; crop: ResolvedCrop; mimeType?: string; maxDim: number },
+	timeoutMs: number,
+): Promise<{ result: Buffer | null; reusable: boolean }> {
+	return new Promise((resolve) => {
+		let settled = false;
+		const settle = (result: Buffer | null, reusable: boolean) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			worker.off("message", onMessage);
+			worker.off("error", onError);
+			worker.off("exit", onExit);
+			resolve({ result, reusable });
+		};
+		const onMessage = (msg: { ok?: boolean; data?: ArrayBuffer }) =>
+			settle(msg && msg.ok && msg.data ? Buffer.from(msg.data) : null, true);
+		const onError = () => settle(null, false);
+		const onExit = () => settle(null, false);
+		// Timeout → not reusable: the worker may be wedged in a synchronous decode.
+		const timer = setTimeout(() => settle(null, false), timeoutMs);
+		worker.on("message", onMessage);
+		worker.on("error", onError);
+		worker.on("exit", onExit);
+		worker.postMessage(task, [task.bytes]);
+	});
+}
+
+/**
+ * Decode → crop → encode on a pooled, terminable worker thread with a hard
+ * timeout. Returns the cropped bytes, null on decode/crop failure (including a
+ * terminated timeout), or WORKER_UNAVAILABLE if worker infra is unavailable
+ * (caller should fall back to the in-thread path).
+ */
+async function cropInWorker(
+	imageBytes: Buffer,
+	crop: ResolvedCrop,
+	mimeType: string | undefined,
+	timeoutMs: number,
+): Promise<Buffer | null | typeof WORKER_UNAVAILABLE> {
+	if (!(await ensureWorkerInfra())) return WORKER_UNAVAILABLE;
+
+	let worker: NodeWorker;
+	try {
+		worker = acquireWorker();
+	} catch {
+		return WORKER_UNAVAILABLE;
+	}
+
+	// Detach a standalone, transferable copy of the bytes (Buffer pooling means
+	// imageBytes.buffer may be shared and unsafe to transfer directly).
+	const ab = imageBytes.buffer.slice(imageBytes.byteOffset, imageBytes.byteOffset + imageBytes.byteLength);
+
+	const { result, reusable } = await runCropTask(
+		worker,
+		{ bytes: ab, crop, mimeType, maxDim: MAX_IMAGE_DIMENSION },
+		timeoutMs,
+	);
+	if (reusable) releaseWorker(worker);
+	else void worker.terminate();
+	return result;
+}
+
+/**
+ * Terminate all idle pooled workers. Exposed for test teardown; safe to call
+ * anytime (a fresh worker is spawned on the next crop).
+ */
+export async function shutdownCropWorkers(): Promise<void> {
+	const pending = _idleWorkers.splice(0, _idleWorkers.length);
+	await Promise.all(pending.map((p) => {
+		p.detach();
+		return p.worker.terminate();
+	}));
+}
+
 /**
  * Crop an image buffer to the given pixel rectangle using ImageScript.
  * Accepts raw image bytes (JPEG/PNG) and returns cropped bytes in the same format.
  * Returns null if cropping fails.
+ *
+ * The decode/crop/encode runs in a terminable worker thread so a maliciously
+ * crafted image that makes the synchronous WASM decoder spin can be killed at the
+ * timeout instead of freezing the session. If worker_threads is unavailable (or
+ * disabled via PI_VISION_PROXY_DECODE_WORKER=0) it falls back to the in-thread
+ * path, which is still guarded by the dimension pre-check and decode timeout.
  */
 export async function cropImage(
 	imageBytes: Buffer,
@@ -1358,20 +1803,12 @@ export async function cropImage(
 		if (dims && (dims.width > MAX_IMAGE_DIMENSION || dims.height > MAX_IMAGE_DIMENSION)) {
 			return null;
 		}
-		const img = await Image.decode(new Uint8Array(imageBytes));
-		// Double-check decoded dimensions (image-size is header-only, actual may differ)
-		if (img.width > MAX_IMAGE_DIMENSION || img.height > MAX_IMAGE_DIMENSION) {
-			return null;
-		}
-		const cropped = img.crop(crop.x, crop.y, crop.width, crop.height);
-		// Encode back to the same format
-		let encoded: Uint8Array;
-		if (mimeType === "image/png") {
-			encoded = await cropped.encode(1); // PNG with compression level 1 (fast)
-		} else {
-			encoded = await cropped.encodeJPEG(90); // JPEG quality 90
+		if (decodeWorkerEnabled()) {
+			const viaWorker = await cropInWorker(imageBytes, crop, mimeType, decodeTimeoutMs());
+			if (viaWorker !== WORKER_UNAVAILABLE) return viaWorker;
+			// else: worker infra unavailable — fall through to in-thread crop
 		}
-		return Buffer.from(encoded);
+		return await cropInThread(imageBytes, crop, mimeType);
 	} catch {
 		return null;
 	}