@iowarp/clio-coder 0.3.0 → 0.3.1

package/src/tools/worker-evidence.ts

@@ -0,0 +1,215 @@
+import { mentionsWorkerToolCallCap } from "../core/guardrails.js";
+import type { ReceiptIntegrityResult } from "../domains/dispatch/receipt-integrity.js";
+import type { RunReceipt, RunReceiptVerification } from "../domains/dispatch/types.js";
+
+/** Matches a source citation the parent can independently spot-check. */
+const SOURCE_CITATION_PATTERN = /([\w./~-]+):(\d+)/g;
+
+export interface SourceCitation {
+	path: string;
+	line: number;
+}
+
+function sourceCitations(text: string): SourceCitation[] {
+	const citations: SourceCitation[] = [];
+	for (const match of text.matchAll(SOURCE_CITATION_PATTERN)) {
+		const path = match[1];
+		const line = Number(match[2]);
+		if (path && Number.isSafeInteger(line) && line > 0) citations.push({ path, line });
+	}
+	return citations;
+}
+
+function hasSourceCitation(text: string): boolean {
+	return sourceCitations(text).length > 0;
+}
+
+/**
+ * Canonical parent spot-check sentence. Dispatch renders it head-anchored;
+ * the operating contract, agent catalog, and docs align to it byte-exact so
+ * every surface teaches the same discipline.
+ */
+export const SPOT_CHECK_GUIDANCE =
+	'Spot-check delegated claims before repeating them: re-read any cited file:line location, and re-run or inspect the named validation before repeating a "tests pass" claim.';
+
+/**
+ * Whether this run was dispatched as work that has to change the tree. Read
+ * from sealed fields only: the execution role a mutation-capable recipe
+ * derives, or a mutation-shaped result contract. A verifier asked to edit
+ * keeps its own role, so this is deliberately narrow; the activity and
+ * first-pass labels below carry the honest signal for every other class.
+ */
+function isMutationClassRun(receipt: RunReceipt, verification: RunReceiptVerification): boolean {
+	// A read-only agent seals `not_applicable`; recon that changes nothing is
+	// the expected outcome there, not a missing effect.
+	if (verification.state === "not_applicable") return false;
+	if (receipt.executionRole === "builder" || receipt.executionRole === "recovery") return true;
+	return receipt.quality?.resultContract?.sourceId?.startsWith("agent-result-contract:mutation-report") === true;
+}
+
+/**
+ * Facts the harness knew before or independently of the worker's account of
+ * itself: the capability/task pairing it was admitted under, and how many of
+ * its passing validation claims correspond to a command it actually ran. Both
+ * exist because a live verifier run sealed `exit=0 ... failed=0` on a
+ * fabricated `npm run typecheck` for a script that does not exist, and neither
+ * honest signal reached the line the orchestrator reads.
+ */
+function receiptAdmissionLabels(receipt: RunReceipt): string[] {
+	const labels: string[] = [];
+	const mismatch = receipt.capabilityMismatch;
+	if (mismatch !== undefined) {
+		labels.push(
+			`capability_mismatch=${mismatch.capabilityClass}/${mismatch.taskType}${
+				mismatch.suggestedAgentId === null ? "" : ` suggested:${mismatch.suggestedAgentId}`
+			}`,
+		);
+	}
+	const grounding = receipt.validationGrounding;
+	if (grounding !== undefined) {
+		labels.push(
+			`validations=claimed:${grounding.claimed} grounded:${grounding.grounded}${
+				grounding.ungrounded.length > 0
+					? ` ${grounding.basis === "no-command-executed" ? "unverifiable" : "unmatched"}:${grounding.ungrounded
+							.map((name) => JSON.stringify(name))
+							.join(",")}`
+					: ""
+			}`,
+		);
+	}
+	return labels;
+}
+
+/**
+ * Sealed work facts for the run line. `exit=0` alone has proven to be a
+ * misleading headline: a worker that never executed a call, or whose every
+ * mutating call was blocked, still exits 0 and still claims in prose that it
+ * fixed the file. These labels are the receipt's own counters, so the parent
+ * sees the shape of the run before it reads the worker's account of it.
+ */
+function receiptActivityLabels(receipt: RunReceipt, verification: RunReceiptVerification): string[] {
+	const labels: string[] = [];
+	const activity = receipt.toolActivity;
+	if (activity !== undefined) {
+		labels.push(
+			`work=calls:${activity.calls} ok:${activity.succeeded} failed:${activity.failed} blocked:${activity.blocked} mutations:${
+				activity.mutatingSucceeded ? "yes" : "no"
+			}`,
+		);
+		// The case this whole label set exists for: the task was to change
+		// something and nothing changed, under an exit code that says success.
+		if (!activity.mutatingSucceeded && isMutationClassRun(receipt, verification)) labels.push("mutation_effect=none");
+	}
+	const findings = receipt.findingsSummary;
+	if (findings !== undefined) {
+		if (!findings.firstPassSuccess) labels.push("first_pass=false");
+		if (findings.tags.length > 0) labels.push(`findings=${[...findings.tags].sort().join(",")}`);
+	}
+	return labels;
+}
+
+/**
+ * Model-facing receipt facts. The positive integrity label is reachable only
+ * when the caller supplies the result of a successful integrity verification;
+ * an embedded digest by itself is never described as verified. Briefing and
+ * project context stay separate, and neither line includes prompt prose.
+ */
+export function receiptEvidenceLabels(
+	receipt: RunReceipt,
+	verification: RunReceiptVerification,
+	integrity: ReceiptIntegrityResult,
+): string[] {
+	if (!integrity.ok) return [`receipt_integrity=FAILED reason=${JSON.stringify(integrity.reason)}`];
+	const briefing =
+		receipt.briefing === undefined
+			? "briefing=none"
+			: `briefing=bytes:${receipt.briefing.bytes} sha256:${receipt.briefing.contentHash}`;
+	let projectContext = "project_context=absent";
+	if (receipt.projectContext !== undefined) {
+		const sections = receipt.projectContext.sections ?? [];
+		projectContext = `project_context=${receipt.projectContext.tier} chars:${receipt.projectContext.chars ?? 0}${
+			sections.length > 0 ? ` sections:${[...sections].sort().join(",")}` : ""
+		}${receipt.projectContext.contentHash !== undefined ? ` sha256:${receipt.projectContext.contentHash}` : ""}`;
+	}
+	return [
+		`receipt_integrity=verified/v${receipt.integrity.version}/${receipt.integrity.algorithm}`,
+		`evidence_verification=${verification.state}/${verification.basis}`,
+		...receiptAdmissionLabels(receipt),
+		...receiptActivityLabels(receipt, verification),
+		briefing,
+		projectContext,
+	];
+}
+
+/**
+ * Header for delegated worker text, keyed only on integrity-checked receipt
+ * verification. The string is shared by dispatch and monitor so detached
+ * collection cannot silently assign a different evidence meaning.
+ */
+export function workerTextLabel(verification: RunReceiptVerification): string {
+	switch (verification.state) {
+		case "verified":
+			return "worker output (tool-verified):";
+		case "not_applicable":
+			return "reconnaissance output (advisory leads, not validation evidence):";
+		case "unknown":
+			return "worker claims (validation not observable at this layer):";
+		default:
+			return "worker claims (unverified prose):";
+	}
+}
+
+/**
+ * Deterministic framing for text that must not be consumed as results. Every
+ * trigger reads sealed receipt fields or machine-written guard diagnostics,
+ * never the worker's claims.
+ */
+export function workerTextNonEvidenceNotices(
+	receipt: RunReceipt,
+	verification: RunReceiptVerification,
+	answerText: string,
+): string[] {
+	const notices: string[] = [];
+	const failedRun = receipt.exitCode !== 0 || (receipt.outcome !== undefined && receipt.outcome !== "succeeded");
+	if (mentionsWorkerToolCallCap(receipt.failureMessage) || mentionsWorkerToolCallCap(receipt.outcomeDetail)) {
+		notices.push(
+			answerText.length > 0
+				? "non-evidence: the worker exhausted its tool-call cap; the text above is a partial synthesis, not verified results."
+				: "non-evidence: the worker exhausted its tool-call cap before a final synthesis was captured.",
+		);
+	} else if (failedRun) {
+		notices.push(
+			"non-evidence: this run did not succeed; treat the text above as an unsubstantiated report, not results.",
+		);
+	}
+	if (receipt.toolActivity !== undefined && receipt.toolActivity.succeeded === 0) {
+		notices.push("non-evidence: no tool call succeeded in this run; the text above was written without observed work.");
+	} else if (receipt.toolActivity?.mutatingSucceeded === false && isMutationClassRun(receipt, verification)) {
+		// A live verifier run returned {"verdict":"pass"} for a check it never
+		// ran, on a script that does not exist, at exit 0. The parent recovered
+		// only because it independently diffed the tree; say so on the line.
+		notices.push(
+			"non-evidence: this run was dispatched as work that changes the tree, but no mutating tool call succeeded. Nothing was written. Confirm with a diff before repeating any claim that something was fixed.",
+		);
+	}
+	const grounding = receipt.validationGrounding;
+	if (grounding !== undefined && grounding.ungrounded.length > 0) {
+		const named = grounding.ungrounded.map((name) => JSON.stringify(name)).join(", ");
+		notices.push(
+			grounding.basis === "no-command-executed"
+				? `non-evidence: this run reported ${named} as passing and executed no command at all. Re-run the check yourself before repeating the claim.`
+				: `non-evidence: this run reported ${named} as passing through a command the harness cannot identify as that check. Re-run it before repeating the claim.`,
+		);
+	}
+	if (receipt.capabilityMismatch !== undefined) {
+		notices.push(
+			`non-evidence: '${receipt.capabilityMismatch.agentId}' is a ${receipt.capabilityMismatch.capabilityClass} recipe and cannot write to the workspace, but this task classified as ${receipt.capabilityMismatch.taskType}. Nothing it reports as changed can have been changed by it.`,
+		);
+	}
+	if (!failedRun && verification.state === "not_applicable" && answerText.length > 0 && !hasSourceCitation(answerText)) {
+		notices.push(
+			"non-evidence: this reconnaissance answer cites no file:line locations; treat its leads as unconfirmed.",
+		);
+	}
+	return notices;
+}

package/src/tools/write.ts

@@ -0,0 +1,52 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { resolveToCwd } from "./path-utils.js";
+import type { ToolResult, ToolSpec } from "./registry.js";
+
+export const writeTool: ToolSpec = {
+	name: ToolNames.Write,
+	description:
+		"Write a UTF-8 text file, creating parent directories and overwriting existing files. Use edit for surgical changes.",
+	parameters: Type.Object({
+		path: Type.String({ description: "File path (relative or absolute)." }),
+		content: Type.String({ description: "Full UTF-8 file contents." }),
+	}),
+	baseActionClass: "write",
+	executionMode: "sequential",
+	async run(args): Promise<ToolResult> {
+		const pathArg = typeof args.path === "string" ? args.path : null;
+		if (!pathArg) return { kind: "error", message: "write: missing path argument" };
+		const content =
+			typeof args.content === "string" ? args.content : args.content === undefined ? null : String(args.content);
+		if (content === null) return { kind: "error", message: "write: missing content argument" };
+		const filePath = resolveToCwd(pathArg);
+		try {
+			let previousEndedWithNewline = false;
+			await withFileMutationQueue(filePath, async () => {
+				try {
+					previousEndedWithNewline = readFileSync(filePath, "utf8").endsWith("\n");
+				} catch {
+					previousEndedWithNewline = false;
+				}
+				mkdirSync(dirname(filePath), { recursive: true });
+				writeFileSync(filePath, content, "utf8");
+			});
+			const bytes = Buffer.byteLength(content, "utf8");
+			let output = `wrote ${bytes}B to ${pathArg}`;
+			if (previousEndedWithNewline && !content.endsWith("\n")) {
+				output += `\nnote: ${pathArg} no longer ends with a newline; the previous content did`;
+			}
+			// The transcript ledger sizes a call from details.observation.shownBytes
+			// before it falls back to the length of the returned text. A write's
+			// text is a confirmation sentence, so without this the ledger printed
+			// the sentence's length as the file size.
+			return { kind: "ok", output, details: { paths: [filePath], observation: { shownBytes: bytes } } };
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			return { kind: "error", message: `write: ${msg}` };
+		}
+	},
+};

package/src/utils/exif-orientation.ts

@@ -0,0 +1,192 @@
+import type { PhotonImageType } from "./photon.js";
+
+type Photon = typeof import("@silvia-odwyer/photon-node");
+
+function byte(bytes: Uint8Array, offset: number): number {
+	return bytes[offset] ?? 0;
+}
+
+function readOrientationFromTiff(bytes: Uint8Array, tiffStart: number): number {
+	if (tiffStart + 8 > bytes.length) return 1;
+
+	const byteOrder = (byte(bytes, tiffStart) << 8) | byte(bytes, tiffStart + 1);
+	const le = byteOrder === 0x4949;
+
+	const read16 = (pos: number): number => {
+		if (le) return byte(bytes, pos) | (byte(bytes, pos + 1) << 8);
+		return (byte(bytes, pos) << 8) | byte(bytes, pos + 1);
+	};
+
+	const read32 = (pos: number): number => {
+		if (le) {
+			return byte(bytes, pos) | (byte(bytes, pos + 1) << 8) | (byte(bytes, pos + 2) << 16) | (byte(bytes, pos + 3) << 24);
+		}
+		return (
+			((byte(bytes, pos) << 24) | (byte(bytes, pos + 1) << 16) | (byte(bytes, pos + 2) << 8) | byte(bytes, pos + 3)) >>> 0
+		);
+	};
+
+	const ifdOffset = read32(tiffStart + 4);
+	const ifdStart = tiffStart + ifdOffset;
+	if (ifdStart + 2 > bytes.length) return 1;
+
+	const entryCount = read16(ifdStart);
+	for (let i = 0; i < entryCount; i++) {
+		const entryPos = ifdStart + 2 + i * 12;
+		if (entryPos + 12 > bytes.length) return 1;
+
+		if (read16(entryPos) === 0x0112) {
+			const value = read16(entryPos + 8);
+			return value >= 1 && value <= 8 ? value : 1;
+		}
+	}
+
+	return 1;
+}
+
+function hasExifHeader(bytes: Uint8Array, offset: number): boolean {
+	return (
+		byte(bytes, offset) === 0x45 &&
+		byte(bytes, offset + 1) === 0x78 &&
+		byte(bytes, offset + 2) === 0x69 &&
+		byte(bytes, offset + 3) === 0x66 &&
+		byte(bytes, offset + 4) === 0x00 &&
+		byte(bytes, offset + 5) === 0x00
+	);
+}
+
+function findJpegTiffOffset(bytes: Uint8Array): number {
+	let offset = 2;
+	while (offset < bytes.length - 1) {
+		if (byte(bytes, offset) !== 0xff) return -1;
+		const marker = byte(bytes, offset + 1);
+		if (marker === 0xff) {
+			offset++;
+			continue;
+		}
+
+		if (marker === 0xe1) {
+			if (offset + 4 >= bytes.length) return -1;
+			const segmentStart = offset + 4;
+			if (segmentStart + 6 > bytes.length) return -1;
+			if (!hasExifHeader(bytes, segmentStart)) return -1;
+			return segmentStart + 6;
+		}
+
+		if (offset + 4 > bytes.length) return -1;
+		const length = (byte(bytes, offset + 2) << 8) | byte(bytes, offset + 3);
+		offset += 2 + length;
+	}
+
+	return -1;
+}
+
+function findWebpTiffOffset(bytes: Uint8Array): number {
+	let offset = 12;
+	while (offset + 8 <= bytes.length) {
+		const chunkId = String.fromCharCode(
+			byte(bytes, offset),
+			byte(bytes, offset + 1),
+			byte(bytes, offset + 2),
+			byte(bytes, offset + 3),
+		);
+		const chunkSize =
+			byte(bytes, offset + 4) |
+			(byte(bytes, offset + 5) << 8) |
+			(byte(bytes, offset + 6) << 16) |
+			(byte(bytes, offset + 7) << 24);
+		const dataStart = offset + 8;
+
+		if (chunkId === "EXIF") {
+			if (dataStart + chunkSize > bytes.length) return -1;
+			return chunkSize >= 6 && hasExifHeader(bytes, dataStart) ? dataStart + 6 : dataStart;
+		}
+
+		offset = dataStart + chunkSize + (chunkSize % 2);
+	}
+
+	return -1;
+}
+
+function getExifOrientation(bytes: Uint8Array): number {
+	let tiffOffset = -1;
+
+	if (bytes.length >= 2 && byte(bytes, 0) === 0xff && byte(bytes, 1) === 0xd8) {
+		tiffOffset = findJpegTiffOffset(bytes);
+	} else if (
+		bytes.length >= 12 &&
+		byte(bytes, 0) === 0x52 &&
+		byte(bytes, 1) === 0x49 &&
+		byte(bytes, 2) === 0x46 &&
+		byte(bytes, 3) === 0x46 &&
+		byte(bytes, 8) === 0x57 &&
+		byte(bytes, 9) === 0x45 &&
+		byte(bytes, 10) === 0x42 &&
+		byte(bytes, 11) === 0x50
+	) {
+		tiffOffset = findWebpTiffOffset(bytes);
+	}
+
+	if (tiffOffset === -1) return 1;
+	return readOrientationFromTiff(bytes, tiffOffset);
+}
+
+type DstIndexFn = (x: number, y: number, w: number, h: number) => number;
+
+function rotate90(photon: Photon, image: PhotonImageType, dstIndex: DstIndexFn): PhotonImageType {
+	const w = image.get_width();
+	const h = image.get_height();
+	const src = image.get_raw_pixels();
+	const dst = new Uint8Array(src.length);
+
+	for (let y = 0; y < h; y++) {
+		for (let x = 0; x < w; x++) {
+			const srcIdx = (y * w + x) * 4;
+			const dstIdx = dstIndex(x, y, w, h) * 4;
+			dst[dstIdx] = src[srcIdx] ?? 0;
+			dst[dstIdx + 1] = src[srcIdx + 1] ?? 0;
+			dst[dstIdx + 2] = src[srcIdx + 2] ?? 0;
+			dst[dstIdx + 3] = src[srcIdx + 3] ?? 0;
+		}
+	}
+
+	return new photon.PhotonImage(dst, h, w);
+}
+
+export function applyExifOrientation(
+	photon: Photon,
+	image: PhotonImageType,
+	originalBytes: Uint8Array,
+): PhotonImageType {
+	const orientation = getExifOrientation(originalBytes);
+	if (orientation === 1) return image;
+
+	switch (orientation) {
+		case 2:
+			photon.fliph(image);
+			return image;
+		case 3:
+			photon.fliph(image);
+			photon.flipv(image);
+			return image;
+		case 4:
+			photon.flipv(image);
+			return image;
+		case 5: {
+			const rotated = rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));
+			photon.fliph(rotated);
+			return rotated;
+		}
+		case 6:
+			return rotate90(photon, image, (x, y, _w, h) => x * h + (h - 1 - y));
+		case 7: {
+			const rotated = rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);
+			photon.fliph(rotated);
+			return rotated;
+		}
+		case 8:
+			return rotate90(photon, image, (x, y, w, h) => (w - 1 - x) * h + y);
+		default:
+			return image;
+	}
+}

package/src/utils/git.ts

@@ -0,0 +1,24 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Resolve the current git branch name for `cwd` (default: process.cwd()).
+ * Wraps `git rev-parse --abbrev-ref HEAD` with a 1s timeout and a defensive
+ * null fallback for non-repos, missing git on PATH, missing paths, and
+ * timeouts. Returns the trimmed branch name on success, or null on any
+ * failure mode.
+ */
+export async function getCurrentBranch(cwd?: string): Promise<string | null> {
+	try {
+		const { stdout } = await execFileAsync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+			cwd,
+			timeout: 1000,
+		});
+		const branch = stdout.trim();
+		return branch.length > 0 ? branch : null;
+	} catch {
+		return null;
+	}
+}

package/src/utils/image-resize.ts

@@ -0,0 +1,148 @@
+import type { ImageContent } from "../engine/types.js";
+import { applyExifOrientation } from "./exif-orientation.js";
+import { loadPhoton } from "./photon.js";
+
+export interface ImageResizeOptions {
+	maxWidth?: number;
+	maxHeight?: number;
+	maxBytes?: number;
+	jpegQuality?: number;
+}
+
+export interface ResizedImage {
+	data: string;
+	mimeType: string;
+	originalWidth: number;
+	originalHeight: number;
+	width: number;
+	height: number;
+	wasResized: boolean;
+}
+
+const DEFAULT_MAX_BYTES = 4.5 * 1024 * 1024;
+
+const DEFAULT_OPTIONS: Required<ImageResizeOptions> = {
+	maxWidth: 2000,
+	maxHeight: 2000,
+	maxBytes: DEFAULT_MAX_BYTES,
+	jpegQuality: 80,
+};
+
+interface EncodedCandidate {
+	data: string;
+	encodedSize: number;
+	mimeType: string;
+}
+
+function encodeCandidate(buffer: Uint8Array, mimeType: string): EncodedCandidate {
+	const data = Buffer.from(buffer).toString("base64");
+	return {
+		data,
+		encodedSize: Buffer.byteLength(data, "utf-8"),
+		mimeType,
+	};
+}
+
+export async function resizeImage(img: ImageContent, options?: ImageResizeOptions): Promise<ResizedImage | null> {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const inputBuffer = Buffer.from(img.data, "base64");
+	const inputBase64Size = Buffer.byteLength(img.data, "utf-8");
+
+	const photon = await loadPhoton();
+	if (!photon) return null;
+	const loadedPhoton = photon;
+
+	let image: ReturnType<typeof photon.PhotonImage.new_from_byteslice> | undefined;
+	try {
+		const inputBytes = new Uint8Array(inputBuffer);
+		const rawImage = photon.PhotonImage.new_from_byteslice(inputBytes);
+		image = applyExifOrientation(photon, rawImage, inputBytes);
+		if (image !== rawImage) rawImage.free();
+
+		const originalWidth = image.get_width();
+		const originalHeight = image.get_height();
+		const format = img.mimeType?.split("/")[1] ?? "png";
+
+		if (originalWidth <= opts.maxWidth && originalHeight <= opts.maxHeight && inputBase64Size < opts.maxBytes) {
+			return {
+				data: img.data,
+				mimeType: img.mimeType ?? `image/${format}`,
+				originalWidth,
+				originalHeight,
+				width: originalWidth,
+				height: originalHeight,
+				wasResized: false,
+			};
+		}
+
+		let targetWidth = originalWidth;
+		let targetHeight = originalHeight;
+
+		if (targetWidth > opts.maxWidth) {
+			targetHeight = Math.round((targetHeight * opts.maxWidth) / targetWidth);
+			targetWidth = opts.maxWidth;
+		}
+		if (targetHeight > opts.maxHeight) {
+			targetWidth = Math.round((targetWidth * opts.maxHeight) / targetHeight);
+			targetHeight = opts.maxHeight;
+		}
+
+		const loadedImage = image;
+		function tryEncodings(width: number, height: number, jpegQualities: number[]): EncodedCandidate[] {
+			const resized = loadedPhoton.resize(loadedImage, width, height, loadedPhoton.SamplingFilter.Lanczos3);
+
+			try {
+				const candidates: EncodedCandidate[] = [encodeCandidate(resized.get_bytes(), "image/png")];
+				for (const quality of jpegQualities) {
+					candidates.push(encodeCandidate(resized.get_bytes_jpeg(quality), "image/jpeg"));
+				}
+				return candidates;
+			} finally {
+				resized.free();
+			}
+		}
+
+		const qualitySteps = Array.from(new Set([opts.jpegQuality, 85, 70, 55, 40]));
+		let currentWidth = targetWidth;
+		let currentHeight = targetHeight;
+
+		while (true) {
+			const candidates = tryEncodings(currentWidth, currentHeight, qualitySteps);
+			for (const candidate of candidates) {
+				if (candidate.encodedSize < opts.maxBytes) {
+					return {
+						data: candidate.data,
+						mimeType: candidate.mimeType,
+						originalWidth,
+						originalHeight,
+						width: currentWidth,
+						height: currentHeight,
+						wasResized: true,
+					};
+				}
+			}
+
+			if (currentWidth === 1 && currentHeight === 1) break;
+
+			const nextWidth = currentWidth === 1 ? 1 : Math.max(1, Math.floor(currentWidth * 0.75));
+			const nextHeight = currentHeight === 1 ? 1 : Math.max(1, Math.floor(currentHeight * 0.75));
+			if (nextWidth === currentWidth && nextHeight === currentHeight) break;
+
+			currentWidth = nextWidth;
+			currentHeight = nextHeight;
+		}
+
+		return null;
+	} catch {
+		return null;
+	} finally {
+		if (image) image.free();
+	}
+}
+
+export function formatDimensionNote(result: ResizedImage): string | undefined {
+	if (!result.wasResized) return undefined;
+
+	const scale = result.originalWidth / result.width;
+	return `[Image: original ${result.originalWidth}x${result.originalHeight}, displayed at ${result.width}x${result.height}. Multiply coordinates by ${scale.toFixed(2)} to map to original image.]`;
+}