@gajae-code/coding-agent 0.18.12 → 0.19.0

package/src/sdk/host/prompt-image-upload.ts

@@ -0,0 +1,438 @@
+import * as crypto from "node:crypto";
+import type { RunSettlementProof } from "@gajae-code/agent-core";
+import type { ImageContent } from "@gajae-code/ai/core";
+import { logger, parseImageMetadata } from "@gajae-code/utils";
+import {
+	MAX_IMAGE_INPUT_BYTES,
+	MAX_PASTED_IMAGE_DIMENSION,
+	MAX_PASTED_IMAGE_PIXELS,
+	MAX_PASTED_IMAGE_SOURCE_BYTES,
+	MAX_STAGED_PROMPT_IMAGES,
+} from "../../utils/image-limits";
+import { isAnimatedImage } from "../../utils/pasted-image-loading";
+import { TypedControlError } from "./control/dispatch";
+
+const MAX_CHUNK_BYTES = 96 * 1024;
+const MIN_RETAINED_BUFFER_BYTES = 4 * 1024;
+const MAX_ACCEPTED_BYTES = 64 * 1024 * 1024;
+const MAX_PROCESS_BYTES = 256 * 1024 * 1024;
+// Each session gets one decoder slot; byte reservations remain process-wide.
+const MAX_CONCURRENT_FINISHES = 1;
+const LEASE_MS = 120_000;
+
+/** One definitive event-driven wait; teardown and elapsed time are not settlement proof. */
+export function retirePromptImageReservation(
+	handle: string,
+	waitForRunSettlement: (handle: string) => Promise<RunSettlementProof>,
+	isCurrent: () => boolean,
+	release: () => void,
+): void {
+	if (!isCurrent()) return;
+	void (async (): Promise<void> => {
+		try {
+			const proof = await waitForRunSettlement(handle);
+			if (!isCurrent()) return;
+			if (proof.status === "settled") {
+				release();
+				return;
+			}
+			logger.warn("SDK image settlement observer returned unfenced proof; capacity retained", {
+				handle,
+				reason: proof.reason,
+				contractViolation: proof.reason === "run_not_sealed" || proof.reason === "resources_pending",
+			});
+		} catch (error) {
+			if (isCurrent())
+				logger.warn("SDK image settlement observation failed; capacity retained without settlement proof", {
+					handle,
+					reason: "observation_failed",
+					error,
+				});
+		}
+	})();
+}
+const MAX_BATCH_ID_LENGTH = 128;
+const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+let processBytes = 0;
+let transientBytes = 0;
+let concurrentFinishes = 0;
+
+export interface PromptImageProcessBudgetSnapshot {
+	/** Retained upload and accepted source bytes, including accepted base64 copies. */
+	readonly sourceBytes: number;
+	readonly transientBytes: number;
+	readonly concurrentFinishes: number;
+}
+
+/** Internal process diagnostics only; not an SDK operation or a release capability. */
+export function getPromptImageProcessBudgetSnapshot(): PromptImageProcessBudgetSnapshot {
+	return Object.freeze({ sourceBytes: processBytes, transientBytes, concurrentFinishes });
+}
+
+type Upload = {
+	owner: string;
+	batchId?: string;
+	mimeType: string;
+	byteLength: number;
+	sha256: string;
+	chunks: Buffer[];
+	reservedBytes: number;
+	length: number;
+	sequence: number;
+	finishing: boolean;
+	finished: boolean;
+	expiresAt: number;
+	timer: NodeJS.Timeout;
+};
+
+function invalid(message: string): never {
+	throw new TypedControlError("invalid_input", message);
+}
+function busy(message: string): never {
+	throw new TypedControlError("busy", message);
+}
+function object(value: unknown, fields: readonly string[]): Record<string, unknown> {
+	if (!value || typeof value !== "object" || Array.isArray(value)) invalid("Image input must be an object.");
+	const input = value as Record<string, unknown>;
+	if (Object.keys(input).some(key => !fields.includes(key))) invalid("Unknown image input field.");
+	return input;
+}
+function ownerId(connectionId: string | undefined): string {
+	if (!connectionId)
+		throw new TypedControlError("operation_prohibited", "An authenticated SDK connection is required.");
+	return connectionId;
+}
+
+/** Session-scoped, connection-owned image leases; no client-supplied path or identity is trusted. */
+export class PromptImageUploadStore {
+	readonly #uploads = new Map<string, Upload>();
+	readonly #isConnectionOpen: (connectionId: string) => boolean;
+	#closed = false;
+	#uploadBytes = 0;
+	#acceptedBytes = 0;
+	#concurrentFinishes = 0;
+
+	/** The host supplies live socket membership; standalone callers must choose an explicit policy. */
+	constructor(isConnectionOpen: (connectionId: string) => boolean) {
+		this.#isConnectionOpen = isConnectionOpen;
+	}
+
+	begin(connectionId: string | undefined, value: unknown): { id: string; nextSequence: 0 } {
+		this.#assertOpen();
+		const owner = ownerId(connectionId);
+		this.#assertConnected(owner);
+		const input = object(value, ["mimeType", "byteLength", "sha256", "batchId"]);
+		if (
+			typeof input.mimeType !== "string" ||
+			!["image/png", "image/jpeg", "image/webp", "image/gif"].includes(input.mimeType)
+		)
+			invalid("Unsupported image MIME type.");
+		if (
+			!Number.isSafeInteger(input.byteLength) ||
+			(input.byteLength as number) <= 0 ||
+			(input.byteLength as number) > MAX_IMAGE_INPUT_BYTES
+		)
+			invalid("Image byteLength exceeds the 20 MiB limit.");
+		if (typeof input.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(input.sha256))
+			invalid("Invalid image SHA-256 digest.");
+		if (
+			Object.hasOwn(input, "batchId") &&
+			(typeof input.batchId !== "string" || input.batchId.length === 0 || input.batchId.length > MAX_BATCH_ID_LENGTH)
+		)
+			invalid("Image batchId must be a nonempty string of at most 128 characters.");
+		const now = Date.now();
+		for (const [uploadId, upload] of this.#uploads) this.#expire(uploadId, upload, now);
+		if (this.#uploads.size >= MAX_STAGED_PROMPT_IMAGES) busy("Too many concurrent image uploads.");
+		const id = crypto.randomUUID();
+		const timer = setTimeout(() => this.#remove(id), LEASE_MS);
+		timer.unref?.();
+		const upload: Upload = {
+			owner,
+			...(typeof input.batchId === "string" ? { batchId: input.batchId } : {}),
+			mimeType: input.mimeType,
+			byteLength: input.byteLength as number,
+			sha256: input.sha256,
+			chunks: [],
+			reservedBytes: 0,
+			length: 0,
+			sequence: 0,
+			finishing: false,
+			finished: false,
+			expiresAt: now + LEASE_MS,
+			timer,
+		};
+		this.#uploads.set(id, upload);
+		this.#renewBatch(owner, id, upload);
+		return { id, nextSequence: 0 };
+	}
+
+	append(
+		connectionId: string | undefined,
+		value: unknown,
+	): { id: string; nextSequence: number; receivedBytes: number } {
+		const input = object(value, ["id", "sequence", "data"]);
+		const upload = this.#owned(connectionId, input.id);
+		if (upload.finishing || upload.finished) invalid("Image upload is already finishing or finished.");
+		if (!Number.isSafeInteger(input.sequence) || input.sequence !== upload.sequence)
+			invalid("Image chunk sequence is out of order.");
+		if (
+			typeof input.data !== "string" ||
+			input.data.length === 0 ||
+			input.data.length > (MAX_CHUNK_BYTES * 4) / 3 ||
+			!CANONICAL_BASE64.test(input.data)
+		)
+			invalid("Image chunk must be canonical base64 within the frame limit.");
+		const bytes = Buffer.from(input.data, "base64");
+		if (bytes.length === 0 || bytes.length > MAX_CHUNK_BYTES || bytes.toString("base64") !== input.data)
+			invalid("Image chunk must be canonical base64 within the frame limit.");
+		if (upload.length + bytes.length > upload.byteLength) invalid("Image upload exceeds its declared size.");
+		const nextLength = upload.length + bytes.length;
+		const allocationLimit = Math.max(upload.byteLength, MIN_RETAINED_BUFFER_BYTES);
+		const requiredBytes = Math.min(Math.ceil(nextLength / MAX_CHUNK_BYTES) * MAX_CHUNK_BYTES, allocationLimit);
+		const addedBytes = requiredBytes - upload.reservedBytes;
+		if (
+			this.#uploadBytes + addedBytes > MAX_PASTED_IMAGE_SOURCE_BYTES ||
+			processBytes + transientBytes + addedBytes > MAX_PROCESS_BYTES
+		)
+			busy("Image staging capacity exceeded.");
+
+		// Reserve coalesced fixed-size slabs before allocating or retaining them. Tiny declared
+		// uploads reserve at least 4 KiB, avoiding one retained Buffer per admitted byte.
+		this.#uploadBytes += addedBytes;
+		processBytes += addedBytes;
+		const originalChunkCount = upload.chunks.length;
+		try {
+			const newChunks: Buffer[] = [];
+			for (let allocated = upload.reservedBytes; allocated < requiredBytes; ) {
+				const chunkBytes = Math.min(MAX_CHUNK_BYTES, requiredBytes - allocated);
+				newChunks.push(Buffer.allocUnsafeSlow(chunkBytes));
+				allocated += chunkBytes;
+			}
+
+			let sourceOffset = 0;
+			let targetOffset = upload.length;
+			while (sourceOffset < bytes.length) {
+				const chunkIndex = Math.floor(targetOffset / MAX_CHUNK_BYTES);
+				const chunk =
+					chunkIndex < upload.chunks.length
+						? upload.chunks[chunkIndex]!
+						: newChunks[chunkIndex - upload.chunks.length]!;
+				const chunkOffset = targetOffset % MAX_CHUNK_BYTES;
+				const copied = Math.min(bytes.length - sourceOffset, chunk.length - chunkOffset);
+				bytes.copy(chunk, chunkOffset, sourceOffset, sourceOffset + copied);
+				sourceOffset += copied;
+				targetOffset += copied;
+			}
+
+			if (newChunks.length > 0) upload.chunks.push(...newChunks);
+			upload.reservedBytes = requiredBytes;
+			upload.length = nextLength;
+			upload.sequence++;
+		} catch (error) {
+			upload.chunks.length = originalChunkCount;
+			this.#uploadBytes -= addedBytes;
+			processBytes -= addedBytes;
+			throw error;
+		}
+		this.#renewBatch(upload.owner, input.id as string, upload);
+		return { id: input.id as string, nextSequence: upload.sequence, receivedBytes: upload.length };
+	}
+
+	async finish(
+		connectionId: string | undefined,
+		value: unknown,
+	): Promise<{ id: string; byteLength: number; sha256: string; mimeType: string }> {
+		const input = object(value, ["id"]);
+		const upload = this.#owned(connectionId, input.id);
+		if (upload.finishing || upload.finished) invalid("Image upload is already finishing or finished.");
+		if (upload.length !== upload.byteLength) invalid("Image upload is incomplete.");
+		// Claim the lease, decoder slot and copy capacity before the first allocation or await.
+		if (
+			this.#concurrentFinishes >= MAX_CONCURRENT_FINISHES ||
+			processBytes + transientBytes + upload.length > MAX_PROCESS_BYTES
+		)
+			busy("Image finalization capacity exceeded.");
+		upload.finishing = true;
+		this.#concurrentFinishes++;
+		concurrentFinishes++;
+		transientBytes += upload.length;
+		let transientReservation = upload.length;
+		try {
+			const bytes = Buffer.concat(upload.chunks, upload.length);
+			if (crypto.createHash("sha256").update(bytes).digest("hex") !== upload.sha256)
+				invalid("Image SHA-256 digest mismatch.");
+			const metadata = parseImageMetadata(bytes);
+			if (
+				!metadata ||
+				metadata.mimeType !== upload.mimeType ||
+				!metadata.width ||
+				!metadata.height ||
+				metadata.width > MAX_PASTED_IMAGE_DIMENSION ||
+				metadata.height > MAX_PASTED_IMAGE_DIMENSION ||
+				metadata.width * metadata.height > MAX_PASTED_IMAGE_PIXELS
+			)
+				invalid("Image MIME type, structure or dimensions are invalid.");
+			if (isAnimatedImage(bytes, metadata.mimeType) !== false)
+				invalid("Animated or malformed images are not supported.");
+			const decodedBytes = metadata.width * metadata.height * 4;
+			if (processBytes + transientBytes + decodedBytes > MAX_PROCESS_BYTES)
+				busy("Image decoding capacity exceeded.");
+			transientBytes += decodedBytes;
+			transientReservation += decodedBytes;
+			try {
+				const decoded = await new Bun.Image(bytes).metadata();
+				if (decoded.width !== metadata.width || decoded.height !== metadata.height)
+					invalid("Image dimensions do not match decoded data.");
+				await new Bun.Image(bytes).resize(1, 1).png().bytes();
+			} catch (error) {
+				if (error instanceof TypedControlError) throw error;
+				invalid("Image cannot be decoded.");
+			}
+			// A custom transport may attest liveness without delivering a close
+			// callback. Decode completion must re-authorize, not renew a dead lease.
+			if (!this.#isConnectionOpen(upload.owner)) {
+				this.#remove(input.id as string);
+				throw new TypedControlError("resource_gone", "Image upload connection is closed.");
+			}
+			// The transport can disconnect while decoding. A removed lease cannot be resurrected.
+			if (this.#uploads.get(input.id as string) !== upload || this.#expire(input.id as string, upload))
+				throw new TypedControlError("resource_gone", "Image upload expired.");
+			const releasedBytes = upload.reservedBytes - upload.length;
+			this.#uploadBytes -= releasedBytes;
+			processBytes -= releasedBytes;
+			upload.chunks = [bytes];
+			upload.reservedBytes = upload.length;
+			upload.finished = true;
+			this.#renewBatch(upload.owner, input.id as string, upload);
+			return { id: input.id as string, byteLength: upload.length, sha256: upload.sha256, mimeType: upload.mimeType };
+		} finally {
+			// A discarded lease still owns its source chunks until this async decode settles.
+			if (this.#uploads.get(input.id as string) !== upload) {
+				this.#uploadBytes -= upload.reservedBytes;
+				processBytes -= upload.reservedBytes;
+			}
+			transientBytes -= transientReservation;
+			concurrentFinishes--;
+			this.#concurrentFinishes--;
+			upload.finishing = false;
+		}
+	}
+
+	discard(connectionId: string | undefined, value: unknown): { discarded: true } {
+		const input = object(value, ["id"]);
+		this.#owned(connectionId, input.id);
+		this.#remove(input.id as string);
+		return { discarded: true };
+	}
+
+	/** Synchronous reserve–validate–copy–consume transaction, called before prompt admission. */
+	redeem(connectionId: string | undefined, value: unknown): { images: ImageContent[]; release: () => void } {
+		this.#assertOpen();
+		const owner = ownerId(connectionId);
+		this.#assertConnected(owner);
+		if (!Array.isArray(value) || value.length === 0 || value.length > MAX_STAGED_PROMPT_IMAGES)
+			invalid(`stagedImages must contain 1–${MAX_STAGED_PROMPT_IMAGES} image IDs.`);
+		const seen = new Set<string>();
+		const entries: Array<[string, Upload]> = [];
+		let bytes = 0;
+		for (const descriptor of value) {
+			const input = object(descriptor, ["id"]);
+			const id = input.id;
+			if (typeof id !== "string" || !id || seen.has(id))
+				invalid("stagedImages contains an invalid or duplicate ID.");
+			seen.add(id);
+			const entry = this.#uploads.get(id);
+			if (!entry || entry.owner !== owner || this.#expire(id, entry))
+				throw new TypedControlError("image_upload_unavailable", "Image upload is unavailable or already consumed.");
+			if (!entry.finished) invalid("Image upload is not finished.");
+			bytes += entry.length;
+			entries.push([id, entry]);
+		}
+		const encodedBytes = entries.reduce((total, [, entry]) => total + Math.ceil(entry.length / 3) * 4, 0);
+		if (
+			bytes > MAX_PASTED_IMAGE_SOURCE_BYTES ||
+			this.#acceptedBytes + bytes > MAX_ACCEPTED_BYTES ||
+			processBytes + transientBytes + bytes + encodedBytes > MAX_PROCESS_BYTES
+		)
+			busy("Accepted image capacity exceeded.");
+		this.#acceptedBytes += bytes;
+		processBytes += bytes + encodedBytes;
+		let released = false;
+		const release = () => {
+			if (released) return;
+			released = true;
+			this.#acceptedBytes -= bytes;
+			processBytes -= bytes + encodedBytes;
+		};
+		try {
+			const images: ImageContent[] = entries.map(([, entry]) => ({
+				type: "image",
+				data: entry.chunks[0]!.toString("base64"),
+				mimeType: entry.mimeType,
+			}));
+			for (const [id] of entries) this.#remove(id);
+			return { images, release };
+		} catch (error) {
+			release();
+			throw error;
+		}
+	}
+
+	disconnect(connectionId: string): void {
+		for (const [id, upload] of this.#uploads) if (upload.owner === connectionId) this.#remove(id);
+	}
+	close(): void {
+		this.#closed = true;
+		for (const id of this.#uploads.keys()) this.#remove(id);
+	}
+	#owned(connectionId: string | undefined, value: unknown): Upload {
+		this.#assertOpen();
+		const owner = ownerId(connectionId);
+		this.#assertConnected(owner);
+		if (typeof value !== "string" || !value) invalid("Image upload ID is required.");
+		const upload = this.#uploads.get(value);
+		if (!upload || upload.owner !== owner || this.#expire(value, upload))
+			throw new TypedControlError("resource_gone", "Image upload is unavailable.");
+		return upload;
+	}
+	#assertOpen(): void {
+		if (this.#closed) throw new TypedControlError("resource_gone", "Image upload session is closed.");
+	}
+	#assertConnected(owner: string): void {
+		if (!this.#isConnectionOpen(owner))
+			throw new TypedControlError("resource_gone", "Image upload connection is closed.");
+	}
+	#expire(id: string, upload: Upload, now = Date.now()): boolean {
+		if (now < upload.expiresAt) return false;
+		this.#remove(id);
+		return true;
+	}
+	#renewBatch(owner: string, id: string, current: Upload): void {
+		const now = Date.now();
+		if (this.#uploads.get(id) !== current || this.#expire(id, current, now))
+			throw new TypedControlError("resource_gone", "Image upload expired.");
+		if (current.batchId === undefined) {
+			this.#resetLease(id, current, now);
+			return;
+		}
+		for (const [uploadId, upload] of this.#uploads)
+			if (upload.owner === owner && upload.batchId === current.batchId && !this.#expire(uploadId, upload, now))
+				this.#resetLease(uploadId, upload, now);
+	}
+	#resetLease(id: string, upload: Upload, now: number): void {
+		clearTimeout(upload.timer);
+		upload.expiresAt = now + LEASE_MS;
+		upload.timer = setTimeout(() => this.#remove(id), LEASE_MS);
+		upload.timer.unref?.();
+	}
+	#remove(id: string): void {
+		const upload = this.#uploads.get(id);
+		if (!upload) return;
+		this.#uploads.delete(id);
+		clearTimeout(upload.timer);
+		if (!upload.finishing) {
+			this.#uploadBytes -= upload.reservedBytes;
+			processBytes -= upload.reservedBytes;
+		}
+	}
+}

package/src/sdk/host/sdk-surface-parity.test.ts

@@ -133,6 +133,21 @@ describe("SDK surface parity", () => {
 		expect(policy.installedQueries.has("skill.list/state")).toBe(false);
 	});
 
+	test("private image operations are advertised only when the host installs staging", () => {
+		for (const available of [false, true]) {
+			const policy = createSdkSurfacePolicy({
+				bindings: [],
+				workflowGateAvailable: false,
+				imageUploadsAvailable: available,
+			});
+			const capabilities = createSdkCapabilities(policy);
+			expect(capabilities.operations.filter(operation => operation.startsWith("turn.image."))).toEqual(
+				available ? ["turn.image.begin", "turn.image.append", "turn.image.finish", "turn.image.discard"] : [],
+			);
+			expect(capabilities.operations).toContain("turn.prompt");
+		}
+	});
+
 	test("request results, replay order, and typed protocol errors match across transports", async () => {
 		const nativeTransport = memoryTransport();
 		const loopbackTransport = memoryTransport();