@gajae-code/coding-agent 0.18.11 → 0.19.0

package/src/sdk/host/control/dispatch.ts

@@ -256,7 +256,19 @@ function invoke(
 ): Promise<ControlValue> | ControlValue {
 	switch (operation) {
 		case "turn.prompt":
-			return surface.prompt(text(input), input.images, input.clientRef as string | undefined);
+			return surface.prompt(text(input), input.images, input.clientRef as string | undefined, input.stagedImages);
+		case "turn.image.begin":
+			if (!surface.imageBegin) invalidInput("Image uploads are not installed for this session.");
+			return surface.imageBegin(input);
+		case "turn.image.append":
+			if (!surface.imageAppend) invalidInput("Image uploads are not installed for this session.");
+			return surface.imageAppend(input);
+		case "turn.image.finish":
+			if (!surface.imageFinish) invalidInput("Image uploads are not installed for this session.");
+			return surface.imageFinish(input);
+		case "turn.image.discard":
+			if (!surface.imageDiscard) invalidInput("Image uploads are not installed for this session.");
+			return surface.imageDiscard(input);
 		case "turn.steer":
 			return surface.steer(
 				text(input),

package/src/sdk/host/control/operations.ts

@@ -21,7 +21,16 @@ export type ControlInput = Record<string, unknown>;
  * AgentSession and its controllers without exposing those concrete types here.
  */
 export interface ControlSurface {
-	prompt(text: string, images?: ControlValue, clientRef?: string): Promise<ControlValue> | ControlValue;
+	prompt(
+		text: string,
+		images?: ControlValue,
+		clientRef?: string,
+		stagedImages?: ControlValue,
+	): Promise<ControlValue> | ControlValue;
+	imageBegin?(input: ControlValue): Promise<ControlValue> | ControlValue;
+	imageAppend?(input: ControlValue): Promise<ControlValue> | ControlValue;
+	imageFinish?(input: ControlValue): Promise<ControlValue> | ControlValue;
+	imageDiscard?(input: ControlValue): Promise<ControlValue> | ControlValue;
 	steer(text: string, clientRef?: string, expectedSdkRunToken?: string): Promise<ControlValue> | ControlValue;
 	followUp(text: string): Promise<ControlValue> | ControlValue;
 	abort(): Promise<ControlValue> | ControlValue;

package/src/sdk/host/events.ts

@@ -26,10 +26,37 @@ export interface EventReplay {
 	gap?: EventReplayGap;
 }
 
+/** Kinds emit sites suppress once notification redaction is on. */
+const REDACTED_REPLAY_KINDS: ReadonlySet<string> = new Set([
+	"turn_stream",
+	"context_update",
+	"image_attachment",
+	"file_attachment",
+	"reasoning_summary",
+	"tool_activity",
+]);
+
+const outboundRedactBySession = new Map<string, boolean>();
+
+/** Notification policy refresh records the live redaction bit for one session ring. */
+export function setSessionOutboundRedact(sessionId: string, enabled: boolean): void {
+	outboundRedactBySession.set(sessionId, enabled);
+}
+
+function frameSessionId(frame: SdkFrame): string | undefined {
+	if (typeof frame.sessionId === "string") return frame.sessionId;
+	const payload = frame.payload;
+	if (!payload || typeof payload !== "object") return undefined;
+	const sessionId = (payload as { sessionId?: unknown }).sessionId;
+	return typeof sessionId === "string" ? sessionId : undefined;
+}
+
 export class SessionEventStream {
 	#generation = 0;
 	#seq = 0;
 	#frames: EventFrame[] = [];
+	#outboundRedact = false;
+	#sessionId: string | undefined;
 	readonly #ringSize: number;
 	readonly #resyncQueries: string[];
 	readonly #revisionProvider: (() => number | undefined) | undefined;
@@ -55,6 +82,12 @@ export class SessionEventStream {
 		return this.#seq;
 	}
 
+	/** Follow the session redaction bit. Replay then drops kinds emit sites already suppress. */
+	setOutboundRedact(enabled: boolean): void {
+		this.#outboundRedact = enabled;
+		if (this.#sessionId !== undefined) outboundRedactBySession.set(this.#sessionId, enabled);
+	}
+
 	restart(): number {
 		this.#generation += 1;
 		this.#seq = 0;
@@ -63,6 +96,8 @@ export class SessionEventStream {
 	}
 
 	emit(frame: SdkFrame): EventFrame {
+		this.#noteSession(frame);
+		this.#noteConfigRedact(frame);
 		const suppliedRevision = frame.revision;
 		const providedRevision = this.#revisionProvider?.();
 		const revision =
@@ -85,10 +120,9 @@ export class SessionEventStream {
 
 	/** Replays retained current-generation events and reports any required resynchronization. */
 	replay(lastSeq: number, generation = this.#generation): EventReplay {
-		const events = this.#frames.filter(frame => frame.seq > lastSeq);
 		if (generation !== this.#generation) {
 			return {
-				events: [...this.#frames],
+				events: this.#visible(this.#frames),
 				gap: {
 					kind: "generation_reset",
 					fromGeneration: generation,
@@ -101,7 +135,7 @@ export class SessionEventStream {
 		const replayFrom = lastSeq + 1;
 		if (replayFrom < oldest) {
 			return {
-				events: this.#frames.filter(frame => frame.seq >= oldest),
+				events: this.#visible(this.#frames.filter(frame => frame.seq >= oldest)),
 				gap: {
 					kind: "sequence_gap",
 					fromSeq: replayFrom,
@@ -110,6 +144,35 @@ export class SessionEventStream {
 				},
 			};
 		}
-		return { events };
+		return { events: this.#visible(this.#frames.filter(frame => frame.seq > lastSeq)) };
+	}
+
+	#noteSession(frame: SdkFrame): void {
+		if (this.#sessionId !== undefined) return;
+		this.#sessionId = frameSessionId(frame);
+	}
+
+	#noteConfigRedact(frame: SdkFrame): void {
+		if (frame.kind !== "config_update") return;
+		const payload = frame.payload;
+		if (!payload || typeof payload !== "object") return;
+		const redact = (payload as { redact?: unknown }).redact;
+		if (typeof redact !== "boolean") return;
+		this.setOutboundRedact(redact);
+	}
+
+	#replayRedact(): boolean {
+		if (this.#sessionId !== undefined) {
+			const noted = outboundRedactBySession.get(this.#sessionId);
+			if (noted !== undefined) return noted;
+		}
+		return this.#outboundRedact;
+	}
+
+	#visible(frames: readonly EventFrame[]): EventFrame[] {
+		const retained = this.#replayRedact()
+			? frames.filter(frame => !REDACTED_REPLAY_KINDS.has(String(frame.kind)))
+			: frames;
+		return [...retained];
 	}
 }

package/src/sdk/host/host.ts

@@ -103,6 +103,7 @@ export interface SessionSdkHostOptions extends HostEndpointAdapters {
  *  must see the same capability-gated event kinds on both legs, or live and
  *  replay delivery diverge for the same subscriber. */
 export const TOOL_ACTIVITY_CAPABILITY = "tool_activity_v2";
+export const AWAITING_INPUT_CAPABILITY = "awaiting_input_v1";
 /** Capability for non-replayable streamed turn content. */
 export const TURN_STREAM_CAPABILITY = "turn_stream";
 /** Capability used by notification adapters that observe a host without owning its work. */
@@ -113,12 +114,17 @@ export const SESSION_HOST_OBSERVER_CAPABILITY = "session_host_observer_v1";
  * of every frame its positioned envelope already reached.
  */
 export const POSITIONED_NOTIFICATION_EFFECTS_CAPABILITY = "positioned_notification_effects_v1";
-export const CAP_GATED_FRAME_KINDS: ReadonlySet<string> = new Set(["tool_activity", "reasoning_summary"]);
+export const CAP_GATED_FRAME_KINDS: ReadonlyMap<string, string> = new Map([
+	["tool_activity", TOOL_ACTIVITY_CAPABILITY],
+	["reasoning_summary", TOOL_ACTIVITY_CAPABILITY],
+	["awaiting_input", AWAITING_INPUT_CAPABILITY],
+]);
 const EMPTY_CAPABILITIES: ReadonlySet<string> = new Set();
 
 /** Keep live delivery and replay on one capability gate. */
 export function canDeliverSdkEvent(kind: string, capabilities: ReadonlySet<string> | undefined): boolean {
-	return !CAP_GATED_FRAME_KINDS.has(kind) || capabilities?.has(TOOL_ACTIVITY_CAPABILITY) === true;
+	const requiredCapability = CAP_GATED_FRAME_KINDS.get(kind);
+	return requiredCapability === undefined || capabilities?.has(requiredCapability) === true;
 }
 
 /** Safe, identifier-free explanations for every refused activation status. */

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();