Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript
14.8 KB
Raw Blame
import { randomBytes } from "node:crypto";
import {
	createWriteStream,
	existsSync,
	openSync,
	readFileSync,
	rmdirSync,
	rmSync,
	unlinkSync,
} from "node:fs";
import { extname, join } from "node:path";
import type { Readable } from "node:stream";
import {
	ATTACHMENT_LIMITS,
	type AttachmentInfo,
	type AttachmentLimits,
	type AttachmentRef,
	type UploadedFile,
} from "@gentle-dot/protocol";
import { directAccess, type EngineAccess } from "./engine-access.ts";
import { ensurePrivateDir } from "./isolation.ts";

/** A stored file, with its absolute path. */
export interface StoredFile extends AttachmentInfo {
	path: string;
}

export interface UploadRefusal {
	ok: false;
	/** The HTTP status for the refusal. */
	status: number;
	code: string;
	/** Plain words for the user. */
	message: string;
}

export type UploadOutcome = { ok: true; file: UploadedFile } | UploadRefusal;

export type ResolveOutcome = { ok: true; files: StoredFile[] } | { ok: false; code: string; message: string };

/** One message's folder: its stored files, and the bytes taken by them and by uploads still running. */
interface Batch {
	dir: string;
	files: Map<string, StoredFile>;
	writing: Set<string>;
	bytes: number;
	createdAt: number;
}

export interface UploadStoreOptions {
	/** The assistant's workspace; files go to `<workspace>/uploads/<uploadId>/<name>`. */
	workspace: string;
	limits?: AttachmentLimits;
	/** How long an upload that was never sent is kept. Default one hour. */
	ttlMs?: number;
	now?: () => number;
	/**
	 * How the store reaches the workspace; in server mode as the engine's user (S25.8, B1), so a
	 * link the engine planted there leads nowhere it could not write itself.
	 */
	access?: EngineAccess;
}

const UNSENT_TTL_MS = 60 * 60 * 1000;
/** The longest image passed to the model: about 5 MB once base64-encoded, the strictest provider limit. */
export const MAX_IMAGE_BYTES = 3_750_000;
const MAX_NAME_LENGTH = 120;
const MAX_EXTENSION = 16;
const SNIFF_BYTES = 16;
/** Control characters, invisible and direction-changing marks. */
// biome-ignore lint/suspicious/noControlCharactersInRegex: removing control characters is the point
const HIDDEN_CHARS = /[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u202a-\u202e\u2066-\u2069\ufeff]/g;
const RESERVED = /^(con|prn|aux|nul|com\d|lpt\d)$/i;
const IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);

const tooLarge = (limits: AttachmentLimits): UploadRefusal => ({
	ok: false,
	status: 413,
	code: "file_too_large",
	message: `This file is too large: up to ${megabytes(limits.fileBytes)} per file.`,
});
const messageTooLarge = (limits: AttachmentLimits): UploadRefusal => ({
	ok: false,
	status: 413,
	code: "message_too_large",
	message: `These files are too large together: up to ${megabytes(limits.messageBytes)} per message.`,
});
const NOT_FOUND = {
	code: "attachment_not_found",
	message: "A file you attached is no longer available. Attach it again.",
};

function megabytes(bytes: number): string {
	return bytes >= 1024 * 1024 ? `${Math.round(bytes / (1024 * 1024))} MB` : `${bytes} bytes`;
}

/**
 * A safe file name: the last path segment only, without control or invisible characters,
 * a leading dot (hidden files), or a reserved name; "file" when nothing is left.
 */
export function sanitizeName(raw: string): string {
	let name = (raw.split(/[\\/]/).pop() ?? "").normalize("NFC").replace(HIDDEN_CHARS, "");
	name = name
		.replace(/[<>:"|?*]/g, "_")
		.replace(/^[.\s]+/, "")
		.replace(/[.\s]+$/, "");
	let extension = extname(name);
	if (extension.length > MAX_EXTENSION) extension = "";
	let stem = name.slice(0, name.length - extension.length);
	if (stem === "" || RESERVED.test(stem)) stem = "file";
	return `${stem.slice(0, MAX_NAME_LENGTH - extension.length).trimEnd()}${extension}`;
}

/** The type of an image or PDF from its first bytes; anything else is `application/octet-stream`. */
export function sniffMime(head: Buffer): string {
	const starts = (bytes: number[] | string, at = 0) => {
		const expected = typeof bytes === "string" ? Buffer.from(bytes, "latin1") : Buffer.from(bytes);
		return head.length >= at + expected.length && head.subarray(at, at + expected.length).equals(expected);
	};
	if (starts([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a])) return "image/png";
	if (starts([0xff, 0xd8, 0xff])) return "image/jpeg";
	if (starts("GIF87a") || starts("GIF89a")) return "image/gif";
	if (starts("RIFF") && starts("WEBP", 8)) return "image/webp";
	if (starts("%PDF-")) return "application/pdf";
	return "application/octet-stream";
}

/**
 * Files the user uploads for a message (S31). Each message gets a private folder under
 * `<workspace>/uploads/`; nothing is opened or run. The limits are checked while the bytes
 * arrive, and a refused or broken upload leaves nothing behind. Uploads wait here until a
 * message sends them, once; one never sent is removed after an hour.
 */
export class UploadStore {
	private readonly root: string;
	private readonly limits: AttachmentLimits;
	private readonly ttlMs: number;
	private readonly now: () => number;
	private readonly access: EngineAccess;
	private readonly batches = new Map<string, Batch>();

	constructor(options: UploadStoreOptions) {
		this.root = join(options.workspace, "uploads");
		this.access = options.access ?? directAccess;
		this.limits = options.limits ?? ATTACHMENT_LIMITS;
		this.ttlMs = options.ttlMs ?? UNSENT_TTL_MS;
		this.now = options.now ?? Date.now;
	}

	/**
	 * Streams one file to disk. Without `uploadId` it starts a new message folder; with it, the
	 * file joins that folder. `length` is the size the client declared, refused early when too large.
	 */
	async receive(
		body: Readable,
		request: { name: string; uploadId?: string; length?: number },
	): Promise<UploadOutcome> {
		this.access(() => this.prune());
		const limits = this.limits;
		if (request.length !== undefined && request.length > limits.fileBytes) return tooLarge(limits);
		const uploadId = request.uploadId ?? `u_${randomBytes(16).toString("base64url")}`;
		const known = this.batches.get(uploadId);
		if (request.uploadId !== undefined && !known) {
			return {
				ok: false,
				status: 404,
				code: "upload_not_found",
				message: "That upload is no longer available. Attach the files again.",
			};
		}
		const batch: Batch = known ?? {
			dir: join(this.root, uploadId),
			files: new Map(),
			writing: new Set(),
			bytes: 0,
			createdAt: this.now(),
		};
		if (batch.files.size + batch.writing.size >= limits.files) {
			return {
				ok: false,
				status: 413,
				code: "too_many_files",
				message: `Too many files: up to ${limits.files} per message.`,
			};
		}
		if (request.length !== undefined && batch.bytes + request.length > limits.messageBytes) {
			return messageTooLarge(limits);
		}
		const name = this.access(() => this.freeName(batch, sanitizeName(request.name)));
		const path = join(batch.dir, name);
		// The folders and the file are made here, synchronously; the bytes then go to the open file.
		let fd: number;
		try {
			fd = this.access(() => {
				ensurePrivateDir(this.root);
				ensurePrivateDir(batch.dir);
				return openSync(path, "wx", 0o600);
			});
		} catch {
			if (!known) this.access(() => this.dropIfEmpty(uploadId, batch));
			return {
				ok: false,
				status: 500,
				code: "upload_failed",
				message: "The file could not be saved. Try again.",
			};
		}
		batch.writing.add(name);
		this.batches.set(uploadId, batch);
		const written = await this.write(body, fd, batch);
		batch.writing.delete(name);
		if (!written.ok) {
			batch.bytes -= written.size;
			this.access(() => {
				removeQuietly(path);
				this.dropIfEmpty(uploadId, batch);
			});
			return written.refusal;
		}
		const file: StoredFile = { name, size: written.size, mime: sniffMime(written.head), path };
		batch.files.set(name, file);
		return {
			ok: true,
			file: { uploadId, name, size: file.size, mime: file.mime, path: `uploads/${uploadId}/${name}` },
		};
	}

	/** The stored files a message refers to, checked against the per-message limits; nothing is used up. */
	resolve(refs: AttachmentRef[]): ResolveOutcome {
		const files: StoredFile[] = [];
		const seen = new Set<string>();
		for (const { uploadId, name } of refs) {
			const file = this.batches.get(uploadId)?.files.get(name);
			const key = `${uploadId}/${name}`;
			if (!file || seen.has(key)) return { ok: false, ...NOT_FOUND };
			seen.add(key);
			files.push(file);
		}
		const bytes = files.reduce((sum, file) => sum + file.size, 0);
		if (files.length > this.limits.files || bytes > this.limits.messageBytes) {
			const { code, message } = messageTooLarge(this.limits);
			return { ok: false, code, message };
		}
		return { ok: true, files };
	}

	/** The files were sent: they stay on disk for the assistant, but no other message can send them. */
	consume(refs: AttachmentRef[]): void {
		for (const { uploadId, name } of refs) {
			const batch = this.batches.get(uploadId);
			if (!batch) continue;
			batch.files.delete(name);
			if (batch.files.size === 0 && batch.writing.size === 0) this.batches.delete(uploadId);
		}
	}

	private write(
		body: Readable,
		fd: number,
		batch: Batch,
	): Promise<{ ok: true; size: number; head: Buffer } | { ok: false; size: number; refusal: UploadRefusal }> {
		const limits = this.limits;
		return new Promise((resolve) => {
			// An open file: nothing on the thread pool opens a path (see engine-access.ts).
			const out = createWriteStream("", { fd, autoClose: true });
			let size = 0;
			let head = Buffer.alloc(0);
			let ended = false;
			let settled = false;
			const detach = () => {
				body.off("data", onData);
				body.off("end", onEnd);
				body.off("error", onBroken);
				body.off("close", onClose);
			};
			const fail = (refusal: UploadRefusal) => {
				if (settled) return;
				settled = true;
				detach();
				body.pause();
				out.once("close", () => resolve({ ok: false, size, refusal }));
				out.destroy();
			};
			const onData = (data: Buffer | string) => {
				const chunk = typeof data === "string" ? Buffer.from(data) : data;
				size += chunk.length;
				batch.bytes += chunk.length;
				if (size > limits.fileBytes) return fail(tooLarge(limits));
				if (batch.bytes > limits.messageBytes) return fail(messageTooLarge(limits));
				if (head.length < SNIFF_BYTES) head = Buffer.concat([head, chunk.subarray(0, SNIFF_BYTES)]);
				if (!out.write(chunk)) {
					body.pause();
					out.once("drain", () => body.resume());
				}
			};
			const onEnd = () => {
				ended = true;
				detach();
				out.end();
			};
			const onBroken = () =>
				fail({
					ok: false,
					status: 400,
					code: "upload_failed",
					message: "The upload did not finish. Try again.",
				});
			const onClose = () => {
				if (!ended) onBroken();
			};
			out.on("error", onBroken);
			out.on("close", () => {
				if (settled) return;
				settled = true;
				resolve({ ok: true, size, head: head.subarray(0, SNIFF_BYTES) });
			});
			body.on("data", onData);
			body.on("end", onEnd);
			body.on("error", onBroken);
			body.on("close", onClose);
			body.resume();
		});
	}

	/** The name, or "name (2).ext", "name (3).ext"… when the folder already has it. */
	private freeName(batch: Batch, name: string): string {
		const taken = (candidate: string) =>
			batch.files.has(candidate) || batch.writing.has(candidate) || existsSync(join(batch.dir, candidate));
		if (!taken(name)) return name;
		const extension = extname(name);
		const stem = name.slice(0, name.length - extension.length);
		for (let n = 2; ; n++) {
			const candidate = `${stem} (${n})${extension}`;
			if (!taken(candidate)) return candidate;
		}
	}

	private dropIfEmpty(uploadId: string, batch: Batch): void {
		if (batch.files.size > 0 || batch.writing.size > 0) return;
		this.batches.delete(uploadId);
		try {
			rmdirSync(batch.dir);
		} catch {
			// Not empty or already gone.
		}
	}

	/** Removes expired unsent files, preserving sent files that share their folder. */
	private prune(): void {
		const cutoff = this.now() - this.ttlMs;
		for (const [uploadId, batch] of this.batches) {
			if (batch.createdAt > cutoff || batch.writing.size > 0) continue;
			for (const file of batch.files.values()) rmSync(file.path, { force: true });
			batch.files.clear();
			this.dropIfEmpty(uploadId, batch);
		}
	}
}

function removeQuietly(path: string): void {
	try {
		unlinkSync(path);
	} catch {
		// Never created, or already removed.
	}
}

const INTRO =
	"The user attached these files, saved in your workspace. Read them with your tools when needed.";
const BLOCK_START = "<attachments>";
const BLOCK_END = "</attachments>";

/**
 * The prompt for a message with files: the user's text, then a block with each file's name, size,
 * type, and absolute path. Images go to the model as images only when it accepts them.
 */
export function composePrompt(
	text: string,
	files: StoredFile[],
	options: { images: boolean | undefined; read?: (path: string) => Buffer },
): { message: string; images?: { type: "image"; mimeType: string; data: string }[] } {
	const read = options.read ?? ((path: string) => readFileSync(path));
	const images: { type: "image"; mimeType: string; data: string }[] = [];
	const lines = files.map((file) => {
		const entry: Record<string, unknown> = {
			name: file.name,
			size: file.size,
			type: file.mime,
			path: file.path,
		};
		if (IMAGE_TYPES.has(file.mime)) {
			if (file.size > MAX_IMAGE_BYTES) entry.image = "too large to show you; read it from the path if needed";
			else if (options.images === true) {
				images.push({ type: "image", mimeType: file.mime, data: read(file.path).toString("base64") });
				entry.image = "attached to this message";
			} else entry.image = "saved, but the current model cannot see images";
		}
		return JSON.stringify(entry);
	});
	const block = [BLOCK_START, INTRO, ...lines, BLOCK_END].join("\n");
	const message = text === "" ? block : `${text}\n\n${block}`;
	return images.length > 0 ? { message, images } : { message };
}

/** Splits a user message into the text the user typed and the chips of the files the daemon appended. */
export function splitAttachments(message: string): { text: string; attachments: AttachmentInfo[] } {
	const none = { text: message, attachments: [] };
	if (!message.endsWith(`\n${BLOCK_END}`)) return none;
	const start = message.lastIndexOf(`${BLOCK_START}\n${INTRO}\n`);
	if (start < 0 || (start > 0 && message.slice(start - 2, start) !== "\n\n")) return none;
	const lines = message
		.slice(start, -BLOCK_END.length - 1)
		.split("\n")
		.slice(2);
	const attachments: AttachmentInfo[] = [];
	for (const line of lines) {
		let entry: Record<string, unknown>;
		try {
			entry = JSON.parse(line) as Record<string, unknown>;
		} catch {
			return none;
		}
		const { name, size, type } = entry;
		if (typeof name !== "string" || typeof size !== "number" || typeof type !== "string") return none;
		attachments.push({ name, size, mime: type });
	}
	if (attachments.length === 0) return none;
	return { text: message.slice(0, Math.max(0, start - 2)), attachments };
}