@narumitw/pi-webui 0.21.0 → 0.25.0

package/src/conversation.ts

@@ -12,7 +12,7 @@ export interface SessionDescriptor {
 export type PublicContent =
 	| { type: "text"; text: string }
 	| { type: "thinking"; text: string }
-	| { type: "image"; mimeType?: string }
+	| { type: "image"; mimeType?: string; retainedImageId?: string }
 	| { type: "toolCall"; id: string; name: string; arguments: unknown };
 
 export interface PublicMessage {
@@ -116,8 +116,13 @@ export class ConversationProjection {
 		this.publishSnapshot();
 	}
 
-	recordMessage(message: unknown, final = true, entryId?: string): void {
-		const projected = projectMessage(message, entryId, final);
+	recordMessage(
+		message: unknown,
+		final = true,
+		entryId?: string,
+		retainedImageIds: readonly string[] = [],
+	): void {
+		const projected = projectMessage(message, entryId, final, retainedImageIds);
 		const previous = this.messages.get(projected.id);
 		if (previous && JSON.stringify(previous) === JSON.stringify(projected)) return;
 		this.messages.set(projected.id, projected);
@@ -194,12 +199,17 @@ export function projectBranchMessages(branch: unknown): PublicMessage[] {
 	return messages;
 }
 
-export function projectMessage(message: unknown, entryId?: string, final = true): PublicMessage {
+export function projectMessage(
+	message: unknown,
+	entryId?: string,
+	final = true,
+	retainedImageIds: readonly string[] = [],
+): PublicMessage {
 	if (!isRecord(message) || typeof message.role !== "string") {
 		throw new Error("Invalid Pi message");
 	}
 	const timestamp = typeof message.timestamp === "number" ? message.timestamp : undefined;
-	const content = projectContent(message.content);
+	const content = projectContent(message.content, retainedImageIds);
 	const id = entryId ?? messageId(message, timestamp, content);
 	return {
 		id,
@@ -217,10 +227,14 @@ export function projectMessage(message: unknown, entryId?: string, final = true)
 	};
 }
 
-function projectContent(content: unknown): PublicContent[] {
+function projectContent(
+	content: unknown,
+	retainedImageIds: readonly string[] = [],
+): PublicContent[] {
 	if (typeof content === "string") return [{ type: "text", text: truncateText(content) }];
 	if (!Array.isArray(content)) return [];
 	const projected: PublicContent[] = [];
+	let imageIndex = 0;
 	for (const block of content) {
 		if (!isRecord(block) || typeof block.type !== "string") continue;
 		if (block.type === "text" && typeof block.text === "string") {
@@ -228,9 +242,12 @@ function projectContent(content: unknown): PublicContent[] {
 		} else if (block.type === "thinking" && typeof block.thinking === "string") {
 			projected.push({ type: "thinking", text: truncateText(block.thinking) });
 		} else if (block.type === "image") {
+			const retainedImageId = retainedImageIds[imageIndex];
+			imageIndex += 1;
 			projected.push({
 				type: "image",
 				...(typeof block.mimeType === "string" ? { mimeType: block.mimeType } : {}),
+				...(typeof retainedImageId === "string" ? { retainedImageId } : {}),
 			});
 		} else if (
 			block.type === "toolCall" &&

package/src/drafts.ts

@@ -0,0 +1,226 @@
+import { createHash, randomUUID } from "node:crypto";
+
+export interface DraftSettings {
+	maxTextBytes: number;
+	maxMutationRecords?: number;
+}
+
+export interface PublicDraftState {
+	revision: number;
+	text: string;
+	attachmentRevision: number;
+	attachmentIds: string[];
+}
+
+export interface DraftSendReservation {
+	token: string;
+	revision: number;
+	text: string;
+	attachmentRevision: number;
+	attachmentIds: string[];
+}
+
+interface MutationRecord {
+	digest: string;
+	result: PublicDraftState;
+}
+
+export class DraftError extends Error {
+	constructor(
+		message: string,
+		readonly status = 409,
+	) {
+		super(message);
+		this.name = "DraftError";
+	}
+}
+
+export class DraftStore {
+	private readonly mutations = new Map<string, MutationRecord>();
+	private readonly reservations = new Map<string, DraftSendReservation>();
+	private readonly maxMutationRecords: number;
+	private revision = 0;
+	private text = "";
+	private attachmentRevision = 0;
+	private attachmentIds: string[] = [];
+	private closed = false;
+
+	constructor(private readonly settings: DraftSettings) {
+		if (!Number.isSafeInteger(settings.maxTextBytes) || settings.maxTextBytes <= 0) {
+			throw new Error("Draft maxTextBytes must be a positive integer.");
+		}
+		this.maxMutationRecords = settings.maxMutationRecords ?? 128;
+		if (!Number.isSafeInteger(this.maxMutationRecords) || this.maxMutationRecords <= 0) {
+			throw new Error("Draft maxMutationRecords must be a positive integer.");
+		}
+	}
+
+	publicState(): PublicDraftState {
+		return {
+			revision: this.revision,
+			text: this.text,
+			attachmentRevision: this.attachmentRevision,
+			attachmentIds: [...this.attachmentIds],
+		};
+	}
+
+	residentBytes(): number {
+		return Buffer.byteLength(this.text);
+	}
+
+	setText(text: string, expectedRevision: number, mutationId: string): PublicDraftState {
+		this.assertOpen();
+		const normalized = normalizeText(text, this.settings.maxTextBytes);
+		const id = normalizeMutationId(mutationId);
+		const digest = mutationDigest(normalized);
+		const prior = this.mutations.get(id);
+		if (prior) {
+			if (prior.digest !== digest) throw new DraftError("Draft mutation id was reused.");
+			return cloneState(prior.result);
+		}
+		this.assertRevision(expectedRevision);
+		if (normalized !== this.text) {
+			this.text = normalized;
+			this.revision += 1;
+		}
+		const result = this.publicState();
+		this.mutations.set(id, { digest, result: cloneState(result) });
+		this.evictMutations();
+		return result;
+	}
+
+	syncAttachments(ids: readonly string[], attachmentRevision: number): PublicDraftState {
+		this.assertOpen();
+		const normalized = normalizeAttachmentIds(ids);
+		if (!Number.isSafeInteger(attachmentRevision) || attachmentRevision < 0) {
+			throw new DraftError("Attachment revision is invalid.", 400);
+		}
+		if (sameIds(normalized, this.attachmentIds)) return this.publicState();
+		this.attachmentIds = normalized;
+		this.attachmentRevision = attachmentRevision;
+		this.revision += 1;
+		return this.publicState();
+	}
+
+	beginSend(expectedRevision: number): DraftSendReservation {
+		this.assertOpen();
+		this.assertRevision(expectedRevision);
+		if (!this.text.trim() && this.attachmentIds.length === 0) {
+			throw new DraftError("Draft cannot be empty.", 400);
+		}
+		const reservation: DraftSendReservation = {
+			token: randomUUID(),
+			revision: this.revision,
+			text: this.text,
+			attachmentRevision: this.attachmentRevision,
+			attachmentIds: [...this.attachmentIds],
+		};
+		this.reservations.set(reservation.token, reservation);
+		return cloneReservation(reservation);
+	}
+
+	finishSend(
+		token: string,
+		committed: boolean,
+		attachments?: { revision: number; ids: readonly string[] },
+	): PublicDraftState {
+		this.assertOpen();
+		const reservation = this.reservations.get(token);
+		if (!reservation) throw new DraftError("Draft send reservation is stale.");
+		this.reservations.delete(token);
+		if (!committed) return this.publicState();
+		let changed = false;
+		if (this.text === reservation.text && this.text !== "") {
+			this.text = "";
+			changed = true;
+		}
+		if (attachments && sameIds(this.attachmentIds, reservation.attachmentIds)) {
+			const normalized = normalizeAttachmentIds(attachments.ids);
+			if (!Number.isSafeInteger(attachments.revision) || attachments.revision < 0) {
+				throw new DraftError("Attachment revision is invalid.", 400);
+			}
+			if (
+				!sameIds(this.attachmentIds, normalized) ||
+				this.attachmentRevision !== attachments.revision
+			) {
+				this.attachmentIds = normalized;
+				this.attachmentRevision = attachments.revision;
+				changed = true;
+			}
+		}
+		if (changed) this.revision += 1;
+		return this.publicState();
+	}
+
+	close(): void {
+		if (this.closed) return;
+		this.closed = true;
+		this.text = "";
+		this.attachmentIds = [];
+		this.attachmentRevision = 0;
+		this.mutations.clear();
+		this.reservations.clear();
+		this.revision += 1;
+	}
+
+	private assertRevision(expectedRevision: number): void {
+		if (!Number.isSafeInteger(expectedRevision) || expectedRevision !== this.revision) {
+			throw new DraftError(`Draft revision mismatch; current revision is ${this.revision}.`);
+		}
+	}
+
+	private assertOpen(): void {
+		if (this.closed) throw new DraftError("Draft store is closed.", 410);
+	}
+
+	private evictMutations(): void {
+		while (this.mutations.size > this.maxMutationRecords) {
+			const oldest = this.mutations.keys().next().value;
+			if (typeof oldest !== "string") return;
+			this.mutations.delete(oldest);
+		}
+	}
+}
+
+function normalizeText(value: string, maxBytes: number): string {
+	if (typeof value !== "string") throw new DraftError("Draft text is invalid.", 400);
+	if (Buffer.byteLength(value) > maxBytes) throw new DraftError("Draft text is too large.", 413);
+	return value;
+}
+
+function normalizeMutationId(value: string): string {
+	if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
+		throw new DraftError("Draft mutation id is invalid.", 400);
+	}
+	return value;
+}
+
+function normalizeAttachmentIds(values: readonly string[]): string[] {
+	if (!Array.isArray(values)) throw new DraftError("Attachment ids are invalid.", 400);
+	const result = values.map((value) => {
+		if (typeof value !== "string" || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) {
+			throw new DraftError("Attachment id is invalid.", 400);
+		}
+		return value;
+	});
+	if (new Set(result).size !== result.length) {
+		throw new DraftError("Attachment ids contain a duplicate.", 400);
+	}
+	return result;
+}
+
+function mutationDigest(text: string): string {
+	return createHash("sha256").update(text).digest("hex");
+}
+
+function sameIds(left: readonly string[], right: readonly string[]): boolean {
+	return left.length === right.length && left.every((id, index) => id === right[index]);
+}
+
+function cloneState(state: PublicDraftState): PublicDraftState {
+	return { ...state, attachmentIds: [...state.attachmentIds] };
+}
+
+function cloneReservation(reservation: DraftSendReservation): DraftSendReservation {
+	return { ...reservation, attachmentIds: [...reservation.attachmentIds] };
+}

package/src/image-limits.ts

@@ -0,0 +1,36 @@
+const MIB = 1024 * 1024;
+
+export interface ImageLimits {
+	maxImages: number;
+	maxImageBytes: number;
+	maxBatchBytes: number;
+	maxImagePixels: number;
+}
+
+export const DEFAULT_IMAGE_LIMITS: Readonly<ImageLimits> = Object.freeze({
+	maxImages: 8,
+	maxImageBytes: 10 * MIB,
+	maxBatchBytes: 40 * MIB,
+	maxImagePixels: 50_000_000,
+});
+
+export const IMAGE_HARD_LIMITS: Readonly<ImageLimits> = Object.freeze({
+	maxImages: 32,
+	maxImageBytes: 50 * MIB,
+	maxBatchBytes: 200 * MIB,
+	maxImagePixels: 100_000_000,
+});
+
+export const PROVIDER_IMAGE_LIMITS = Object.freeze({
+	maxDimension: 2_000,
+	maxBase64Bytes: 4_500_000,
+});
+
+export function imageLimits(value: Partial<ImageLimits> = {}): Readonly<ImageLimits> {
+	return Object.freeze({
+		maxImages: value.maxImages ?? DEFAULT_IMAGE_LIMITS.maxImages,
+		maxImageBytes: value.maxImageBytes ?? DEFAULT_IMAGE_LIMITS.maxImageBytes,
+		maxBatchBytes: value.maxBatchBytes ?? DEFAULT_IMAGE_LIMITS.maxBatchBytes,
+		maxImagePixels: value.maxImagePixels ?? DEFAULT_IMAGE_LIMITS.maxImagePixels,
+	});
+}

package/src/image-pipeline.ts

@@ -0,0 +1,325 @@
+import { decode as decodeBmp } from "bmp-js";
+import decodeHeic from "heic-decode";
+import sharp, { type OutputInfo, type Sharp, type SharpOptions } from "sharp";
+
+export type SupportedImageFormat =
+	| "png"
+	| "jpeg"
+	| "webp"
+	| "gif"
+	| "bmp"
+	| "tiff"
+	| "heic"
+	| "avif";
+
+export interface ProcessImageOptions {
+	autoResize: boolean;
+	maxPixels: number;
+	maxDimension: number;
+	maxBase64Bytes: number;
+	signal?: AbortSignal;
+}
+
+export interface ProcessedBrowserImage {
+	bytes: Buffer;
+	mimeType: string;
+	width: number;
+	height: number;
+	originalWidth: number;
+	originalHeight: number;
+	sourceFormat: SupportedImageFormat;
+	outputFormat: "png" | "jpeg" | "webp" | "gif";
+	resized: boolean;
+}
+
+export class UnsupportedImageError extends Error {}
+export class ImageLimitError extends Error {}
+
+interface InputDescriptor {
+	input: Buffer;
+	options: SharpOptions;
+	format: SupportedImageFormat;
+	animated: boolean;
+}
+
+interface Dimensions {
+	width: number;
+	height: number;
+	pages: number;
+}
+
+export function detectImageFormat(bytes: Uint8Array): SupportedImageFormat | null {
+	if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return "png";
+	if (startsWith(bytes, [0xff, 0xd8, 0xff])) return "jpeg";
+	if (ascii(bytes, 0, 6) === "GIF87a" || ascii(bytes, 0, 6) === "GIF89a") return "gif";
+	if (ascii(bytes, 0, 4) === "RIFF" && ascii(bytes, 8, 12) === "WEBP") return "webp";
+	if (ascii(bytes, 0, 2) === "BM") return "bmp";
+	if (startsWith(bytes, [0x49, 0x49, 0x2a, 0x00]) || startsWith(bytes, [0x4d, 0x4d, 0x00, 0x2a])) {
+		return "tiff";
+	}
+	if (ascii(bytes, 4, 8) === "ftyp") {
+		const brands = ascii(bytes, 8, Math.min(bytes.length, 64));
+		if (brands.includes("avif") || brands.includes("avis")) return "avif";
+		if (
+			brands.includes("heic") ||
+			brands.includes("heix") ||
+			brands.includes("hevc") ||
+			brands.includes("hevx") ||
+			brands.startsWith("mif1") ||
+			brands.startsWith("msf1")
+		) {
+			return "heic";
+		}
+	}
+	return null;
+}
+
+export async function processImage(
+	source: Uint8Array,
+	options: ProcessImageOptions,
+): Promise<ProcessedBrowserImage> {
+	throwIfAborted(options.signal);
+	const bytes = Buffer.from(source);
+	const format = detectImageFormat(bytes);
+	if (!format) throw new UnsupportedImageError("Unsupported image format");
+	const descriptor = await describeInput(bytes, format, options.maxPixels, options.signal);
+	const original = await dimensions(descriptor, options.maxPixels);
+	throwIfAborted(options.signal);
+
+	if (
+		!options.autoResize &&
+		(original.width > options.maxDimension || original.height > options.maxDimension)
+	) {
+		throw new ImageLimitError("Image dimensions exceed Pi's limit while auto-resize is disabled");
+	}
+
+	let target = options.autoResize ? fitWithin(original, options.maxDimension) : original;
+	let quality = 95;
+	while (true) {
+		throwIfAborted(options.signal);
+		const encoded = await encode(descriptor, target, quality);
+		throwIfAborted(options.signal);
+		const base64Bytes = Buffer.byteLength(encoded.data.toString("base64"));
+		if (base64Bytes <= options.maxBase64Bytes) {
+			const width = encoded.info.width;
+			const height = encoded.info.pageHeight ?? encoded.info.height;
+			const outputFormat = normalizeOutputFormat(encoded.info.format);
+			return {
+				bytes: encoded.data,
+				mimeType: mimeType(outputFormat),
+				width,
+				height,
+				originalWidth: original.width,
+				originalHeight: original.height,
+				sourceFormat: format,
+				outputFormat,
+				resized: width !== original.width || height !== original.height,
+			};
+		}
+		if (!options.autoResize) {
+			throw new ImageLimitError("Processed image exceeds Pi's inline limit");
+		}
+		if ((format === "jpeg" || format === "webp") && quality > 40) {
+			quality = nextQuality(quality);
+			continue;
+		}
+		quality = 95;
+		if (target.width === 1 && target.height === 1) {
+			throw new ImageLimitError("Image could not be reduced below Pi's inline limit");
+		}
+		target = {
+			...target,
+			width: target.width === 1 ? 1 : Math.max(1, Math.floor(target.width * 0.8)),
+			height: target.height === 1 ? 1 : Math.max(1, Math.floor(target.height * 0.8)),
+		};
+	}
+}
+
+async function describeInput(
+	bytes: Buffer,
+	format: SupportedImageFormat,
+	maxPixels: number,
+	signal?: AbortSignal,
+): Promise<InputDescriptor> {
+	if (format === "bmp") return describeBmp(bytes, maxPixels);
+	if (format !== "heic") {
+		return {
+			input: bytes,
+			options: {
+				animated: format === "gif",
+				failOn: "warning",
+				limitInputPixels: maxPixels,
+				sequentialRead: true,
+			},
+			format,
+			animated: format === "gif",
+		};
+	}
+
+	throwIfAborted(signal);
+	let deferred: Awaited<ReturnType<typeof decodeHeic.all>> | undefined;
+	try {
+		deferred = await decodeHeic.all({ buffer: bytes });
+		const first = deferred[0];
+		if (!first) throw new UnsupportedImageError("HEIC image has no frames");
+		assertPixelLimit(first.width, first.height, maxPixels);
+		const decoded = await first.decode();
+		throwIfAborted(signal);
+		return {
+			input: Buffer.from(decoded.data),
+			options: {
+				raw: { width: decoded.width, height: decoded.height, channels: 4 },
+				limitInputPixels: maxPixels,
+			},
+			format,
+			animated: false,
+		};
+	} catch (error) {
+		if (error instanceof ImageLimitError || isAbortError(error)) throw error;
+		throw new UnsupportedImageError(`HEIC decode failed: ${formatError(error)}`);
+	} finally {
+		deferred?.dispose();
+	}
+}
+
+function describeBmp(bytes: Buffer, maxPixels: number): InputDescriptor {
+	if (bytes.byteLength < 54 || bytes.readUInt32LE(14) < 40) {
+		throw new UnsupportedImageError("BMP header is unsupported");
+	}
+	const width = bytes.readInt32LE(18);
+	const height = Math.abs(bytes.readInt32LE(22));
+	assertPixelLimit(width, height, maxPixels);
+	let decoded: ReturnType<typeof decodeBmp>;
+	try {
+		decoded = decodeBmp(bytes, true);
+	} catch (error) {
+		throw new UnsupportedImageError(`BMP decode failed: ${formatError(error)}`);
+	}
+	const rgba = Buffer.allocUnsafe(decoded.width * decoded.height * 4);
+	const bitDepth = bytes.readUInt16LE(28);
+	for (let offset = 0; offset < rgba.length; offset += 4) {
+		rgba[offset] = decoded.data[offset + 3] ?? 0;
+		rgba[offset + 1] = decoded.data[offset + 2] ?? 0;
+		rgba[offset + 2] = decoded.data[offset + 1] ?? 0;
+		rgba[offset + 3] = bitDepth === 32 ? (decoded.data[offset] ?? 255) : 255;
+	}
+	return {
+		input: rgba,
+		options: {
+			raw: { width: decoded.width, height: decoded.height, channels: 4 },
+			limitInputPixels: maxPixels,
+		},
+		format: "bmp",
+		animated: false,
+	};
+}
+
+async function dimensions(descriptor: InputDescriptor, maxPixels: number): Promise<Dimensions> {
+	try {
+		const metadata = await sharp(descriptor.input, descriptor.options).metadata();
+		const width = metadata.autoOrient.width ?? metadata.width;
+		const totalHeight = metadata.autoOrient.height ?? metadata.height;
+		if (!width || !totalHeight) throw new Error("Image dimensions are missing");
+		const pages = metadata.pages ?? 1;
+		const height = metadata.pageHeight ?? Math.floor(totalHeight / pages);
+		assertPixelLimit(width, height * pages, maxPixels);
+		return { width, height, pages };
+	} catch (error) {
+		if (error instanceof ImageLimitError) throw error;
+		throw new Error(`Image decode failed: ${formatError(error)}`);
+	}
+}
+
+async function encode(
+	descriptor: InputDescriptor,
+	target: Dimensions,
+	quality: number,
+): Promise<{ data: Buffer; info: OutputInfo }> {
+	let pipeline: Sharp = sharp(descriptor.input, descriptor.options).autoOrient().keepIccProfile();
+	pipeline = pipeline.resize(target.width, target.height, {
+		fit: "inside",
+		withoutEnlargement: true,
+		kernel: sharp.kernel.lanczos3,
+	});
+	switch (descriptor.format) {
+		case "jpeg":
+			pipeline = pipeline.jpeg({ quality, chromaSubsampling: "4:4:4", mozjpeg: true });
+			break;
+		case "webp":
+			pipeline = pipeline.webp(
+				quality === 95 ? { lossless: true, effort: 5 } : { quality, alphaQuality: 100, effort: 5 },
+			);
+			break;
+		case "gif":
+			pipeline = pipeline.gif({ reuse: true, effort: 7 });
+			break;
+		case "png":
+			pipeline = pipeline.png({ compressionLevel: 9, adaptiveFiltering: true });
+			break;
+		default:
+			pipeline = pipeline.png({ compressionLevel: 9, adaptiveFiltering: true });
+	}
+	return pipeline.toBuffer({ resolveWithObject: true });
+}
+
+function fitWithin(dimensions: Dimensions, max: number): Dimensions {
+	const ratio = Math.min(1, max / dimensions.width, max / dimensions.height);
+	return {
+		...dimensions,
+		width: Math.max(1, Math.round(dimensions.width * ratio)),
+		height: Math.max(1, Math.round(dimensions.height * ratio)),
+	};
+}
+
+function nextQuality(quality: number): number {
+	if (quality > 85) return 85;
+	if (quality > 70) return 70;
+	if (quality > 55) return 55;
+	return 40;
+}
+
+function normalizeOutputFormat(format: string): "png" | "jpeg" | "webp" | "gif" {
+	if (format === "jpg") return "jpeg";
+	if (format === "png" || format === "jpeg" || format === "webp" || format === "gif") {
+		return format;
+	}
+	throw new UnsupportedImageError(`Unsupported output format: ${format}`);
+}
+
+function mimeType(format: "png" | "jpeg" | "webp" | "gif"): string {
+	return `image/${format}`;
+}
+
+function assertPixelLimit(width: number, height: number, max: number): void {
+	if (!Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width <= 0 || height <= 0) {
+		throw new ImageLimitError("Image dimensions are invalid");
+	}
+	if (width > Math.floor(max / height))
+		throw new ImageLimitError("Image pixel count exceeds the limit");
+}
+
+function throwIfAborted(signal?: AbortSignal): void {
+	if (signal?.aborted) throw abortError();
+}
+
+function abortError(): Error {
+	const error = new Error("Image processing aborted");
+	error.name = "AbortError";
+	return error;
+}
+
+function isAbortError(error: unknown): boolean {
+	return error instanceof Error && error.name === "AbortError";
+}
+
+function startsWith(bytes: Uint8Array, signature: readonly number[]): boolean {
+	return signature.every((byte, index) => bytes[index] === byte);
+}
+
+function ascii(bytes: Uint8Array, start: number, end: number): string {
+	return Buffer.from(bytes.subarray(start, end)).toString("latin1");
+}
+
+function formatError(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}