@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/llm-deepseek/lib/index.js

@@ -1,20 +1,26 @@
 import z from "../../schemastery/lib/index.mjs";
-import { CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertUsableApiKey, attributionHeaders, contentHasImage, isContextWindowExceededError, isQuotaExceededError, resolveRetryPolicy } from "../../llm/lib/index.js";
+import { CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertUsableApiKey, attributionHeaders, contentHasImage, isContextWindowExceededError, isQuotaExceededError, offloadRequestImagesWithPolicy, requestImageHandleText, resolveRetryPolicy } from "../../llm/lib/index.js";
 import { credentialRef } from "../../credentials/lib/index.js";
 import { launchEnvironmentOf } from "../../launch-environment/lib/index.js";
 import { deepEqualJson, installSettingsSection, settingsNamespace } from "../../settings/lib/index.js";
-import { MAX_TIMER_DELAY_MS, idleWatchdog, timeoutOf } from "../../timeout/lib/index.js";
+import { MAX_TIMER_DELAY_MS, deadline, idleWatchdog, timeoutOf } from "../../timeout/lib/index.js";
 import { getOrCreateAnonymousUserId } from "../../anonymous-user-id/lib/index.js";
+import { createHash } from "node:crypto";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { withFileLock, writeFileAtomic } from "../../atomic-write/lib/index.js";
+import { resolveNomixHome } from "../../home-paths/lib/index.js";
+import { ImageVariantId } from "../../attachment/lib/index.js";
 import { EventSourceParserStream } from "eventsource-parser/stream";
 //#region lib/types/serialize.js
 /**
-* Serialize harness messages into DeepSeek chat completions. User text is joined; assistant text
-* becomes `content`, tool calls become `tool_calls`, and tool results become separate tool messages.
-* Assistant reasoning is replayed as `reasoning_content` only on tool-call turns, as required by
-* thinking-mode passback. Core image blocks are rejected explicitly because this wire route is text-only;
-* unknown declaration-merged block types retain the adapter's documented extension fallback.
+* Serialize harness messages into DeepSeek chat completions. Text-only
+* requests retain string user content; the image path resolves durable
+* attachments into ordered file-id or inline parts. Tool-result images follow their
+* string-only tool messages in a separate user message.
 * @module nomix-llm-deepseek/serialize
 */
+const TOOL_RESULT_IMAGE_TEXT = "Attached image(s) from tool result:";
 /** Validate the adapter-owned effort before resolving its DeepSeek wire fields. */
 function reasoningEffort(effort) {
 	if (effort === "off" || effort === "low" || effort === "high" || effort === "max") return effort;
@@ -40,6 +46,63 @@ function flattenText(blocks) {
 function assertTextOnly(blocks) {
 	if (contentHasImage(blocks)) throw new LlmError("The DeepSeek chat-completions adapter does not support image content.", "UNSUPPORTED_CONTENT");
 }
+/** Reject roles whose DeepSeek history format cannot carry image input. */
+function assertSupportedImageRoles(messages) {
+	for (const message of messages) if (message.role !== "user" && contentHasImage(message.content)) throw new LlmError(`The DeepSeek chat-completions adapter cannot represent image content in a ${message.role} message.`, "UNSUPPORTED_CONTENT");
+}
+/** Describe the exact request preview and its model-callable coordinate system. */
+function imageHandle(version, precededByContent) {
+	return {
+		type: "text",
+		text: `${precededByContent ? "\n" : ""}${requestImageHandleText(version)}`
+	};
+}
+/** Resolve one durable image into its descriptor and transient DeepSeek image part. */
+async function imageParts(block, images, location, precededByContent) {
+	const version = images.requestImages.get(block.attachment.attachmentId);
+	if (version === void 0) throw new LlmError(`DeepSeek request image ${block.attachment.attachmentId} was not prepared.`, "INVALID_REQUEST");
+	const image = images.representation.kind === "file" ? {
+		type: "file",
+		file_id: await images.representation.resolveFileId(version, block, location)
+	} : {
+		type: "image_url",
+		image_url: { url: `data:${version.mediaType};base64,${Buffer.from(version.data).toString("base64")}` }
+	};
+	return [imageHandle(version, precededByContent), image];
+}
+/** Convert user or nested tool-result blocks into ordered wire parts. */
+async function contentParts(blocks, images, message, nextImage) {
+	const parts = [];
+	for (const block of blocks) switch (block.type) {
+		case "text":
+			if (block.text.length > 0) parts.push({
+				type: "text",
+				text: block.text
+			});
+			break;
+		case "image":
+			nextImage.value += 1;
+			parts.push(...await imageParts(block, images, {
+				message,
+				image: nextImage.value
+			}, parts.length > 0));
+			break;
+		case "tool-result":
+			parts.push(...await contentParts(block.content, images, message, nextImage));
+			break;
+		default: break;
+	}
+	return parts;
+}
+/** Keep text-only user messages on the compact string wire form. */
+function userContent(parts) {
+	const text = [];
+	for (const part of parts) {
+		if (part.type !== "text") return [...parts];
+		text.push(part.text);
+	}
+	return text.join("");
+}
 /** Serialize one assistant message (text + reasoning + tool calls). */
 function serializeAssistant(message) {
 	const text = flattenText(message.content);
@@ -55,7 +118,7 @@ function serializeAssistant(message) {
 	return {
 		role: "assistant",
 		content: text,
-		...toolCalls.length > 0 && reasoning.length > 0 ? { reasoning_content: reasoning } : {},
+		...reasoning.length > 0 ? { reasoning_content: reasoning } : {},
 		...toolCalls.length > 0 ? { tool_calls: toolCalls } : {}
 	};
 }
@@ -97,20 +160,70 @@ function serializeMessages(messages) {
 	return wire;
 }
 /**
-* Build the full wire request. Always streaming (`stream: true`, usage
-* reporting on); optional fields are omitted rather than sent as null, so
-* provider defaults apply.
-* @param options - the harness request (model, history, system, tools, sampling).
-* @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
-* @returns the chat-completions request body.
+* Serialize image-capable history after resolving durable attachments.
+* Consecutive tool results keep string `tool` messages and share one following
+* user message containing their images.
+* @param messages - transient request history after request-size offloading.
+* @param images - prepared request versions, one provider representation, and its budget.
+* @returns ordered DeepSeek wire messages.
 */
-function serializeRequest(options, defaults = {}) {
-	const messages = [];
-	if (options.system !== void 0) messages.push({
-		role: "system",
-		content: options.system
-	});
-	messages.push(...serializeMessages(options.messages));
+async function serializeMessagesWithImages(messages, images) {
+	assertSupportedImageRoles(messages);
+	const wire = [];
+	let pendingToolImages = [];
+	const flushToolImages = () => {
+		if (pendingToolImages.length === 0) return;
+		wire.push({
+			role: "user",
+			content: [{
+				type: "text",
+				text: TOOL_RESULT_IMAGE_TEXT
+			}, ...pendingToolImages]
+		});
+		pendingToolImages = [];
+	};
+	for (const [messageIndex, message] of messages.entries()) {
+		const nextImage = { value: 0 };
+		if (message.role === "system") {
+			flushToolImages();
+			wire.push({
+				role: "system",
+				content: flattenText(message.content)
+			});
+			continue;
+		}
+		if (message.role === "assistant") {
+			flushToolImages();
+			wire.push(serializeAssistant(message));
+			continue;
+		}
+		const regular = message.content.filter((block) => block.type !== "tool-result");
+		const toolResults = message.content.filter((block) => block.type === "tool-result");
+		const content = userContent(await contentParts(regular, images, messageIndex + 1, nextImage));
+		if (content.length > 0 || toolResults.length === 0) {
+			flushToolImages();
+			wire.push({
+				role: "user",
+				content
+			});
+		}
+		for (const result of toolResults) {
+			const parts = await contentParts(result.content, images, messageIndex + 1, nextImage);
+			const imageParts = parts.filter((part) => part.type !== "text");
+			const text = parts.filter((part) => part.type === "text").map((part) => part.text).join("");
+			wire.push({
+				role: "tool",
+				tool_call_id: result.toolCallId,
+				content: text || "(no output)"
+			});
+			pendingToolImages.push(...imageParts);
+		}
+	}
+	flushToolImages();
+	return wire;
+}
+/** Assemble request fields shared by text-only and image-capable conversion. */
+function requestWithMessages(options, messages, defaults) {
 	const tools = options.tools?.map((tool) => ({
 		type: "function",
 		function: {
@@ -134,6 +247,635 @@ function serializeRequest(options, defaults = {}) {
 	};
 }
 /**
+* Build the full wire request. Always streaming (`stream: true`, usage
+* reporting on); optional fields are omitted rather than sent as null, so
+* provider defaults apply.
+* @param options - the harness request (model, history, system, tools, sampling).
+* @param defaults - adapter-level thinking defaults; undefined fields put nothing on the wire.
+* @returns the chat-completions request body.
+*/
+function serializeRequest(options, defaults = {}) {
+	const messages = [];
+	if (options.system !== void 0) messages.push({
+		role: "system",
+		content: options.system
+	});
+	messages.push(...serializeMessages(options.messages));
+	return requestWithMessages(options, messages, defaults);
+}
+/**
+* Build one image-capable request while keeping durable bytes out of session
+* messages. Oversized oldest images become deterministic text after their
+* exact request-version byte lengths are known and before provider serialization.
+* @param options - harness request containing image-capable user content.
+* @param images - attachment resolver, request bound, and cancellation.
+* @param defaults - adapter-level thinking defaults.
+* @returns the fully materialized DeepSeek request body.
+*/
+async function serializeRequestWithImages(options, images, defaults = {}) {
+	assertSupportedImageRoles(options.messages);
+	const requestMessages = offloadRequestImagesWithPolicy(options.messages, {
+		representation: images.representation.kind === "file" ? "raw" : "base64",
+		byteLength: (ref) => {
+			const version = images.requestImages.get(ref.attachmentId);
+			if (version === void 0) throw new LlmError(`DeepSeek request image ${ref.attachmentId} was not prepared.`, "INVALID_REQUEST");
+			return version.bytes;
+		},
+		maxBytes: images.maxRequestImageBytes,
+		...images.maxImagesPerRequest === void 0 ? {} : { maxImages: images.maxImagesPerRequest },
+		...images.byteQuantum === void 0 ? {} : { byteQuantum: images.byteQuantum },
+		...images.countQuantum === void 0 ? {} : { countQuantum: images.countQuantum }
+	});
+	const messages = [];
+	if (options.system !== void 0) messages.push({
+		role: "system",
+		content: options.system
+	});
+	messages.push(...await serializeMessagesWithImages(requestMessages, images));
+	return requestWithMessages(options, messages, defaults);
+}
+//#endregion
+//#region lib/types/file-id.js
+/** DeepSeek Files API identifiers. @module nomix-llm-deepseek/file-id */
+/**
+* Brand a provider-returned file identifier after wire validation.
+* @param id - non-empty Files API identifier.
+* @returns the same string with its provider identity attached at type level.
+*/
+function DeepSeekFileId(id) {
+	return id;
+}
+/**
+* Brand a locally derived namespace digest.
+* @param scope - SHA-256 digest of endpoint and API key.
+* @returns the same string with namespace identity attached at type level.
+*/
+function DeepSeekFileScope(scope) {
+	return scope;
+}
+//#endregion
+//#region lib/types/files-api.js
+/** OpenAI-compatible DeepSeek Files API transport. @module nomix-llm-deepseek/files-api */
+/** Minimum provider-supported file lifetime. */
+const MIN_FILE_EXPIRY_SECONDS = 3600;
+/** Maximum provider-supported file lifetime. */
+const MAX_FILE_EXPIRY_SECONDS = 2592e3;
+/** Maximum Files API upload size. */
+const MAX_FILE_UPLOAD_BYTES = 128 * 1024 * 1024;
+/** Current per-key file-count quota. */
+const MAX_STORED_FILE_COUNT = 1e4;
+/** Current per-key storage quota. */
+const MAX_STORED_FILE_BYTES = 25 * 1024 * 1024 * 1024;
+/** Files API operation failure with its HTTP status retained for recovery policy. */
+var DeepSeekFilesError = class extends LlmError {
+	/** Parsed provider detail used only for error classification. */
+	detail;
+	/**
+	* @param message - user-readable provider failure.
+	* @param status - HTTP status returned by the Files API.
+	* @param detail - provider error fields joined for classification.
+	*/
+	constructor(message, status, detail) {
+		super(message, status === 401 || status === 403 ? "AUTH" : status === 429 ? "RATE_LIMIT" : status >= 500 ? "SERVER" : "FILES_API", { status });
+		this.name = "DeepSeekFilesError";
+		this.detail = detail;
+	}
+};
+/**
+* Whether an upload failure reports a provider storage or file-count quota.
+* @param error - Files API operation failure.
+* @returns whether one bounded remote cleanup and upload retry may recover.
+*/
+function isFilesQuotaError(error) {
+	return error instanceof DeepSeekFilesError && /(?:quota|storage|stored files|file count|too many files)/iu.test(error.detail);
+}
+function invalidResponse(operation) {
+	return new LlmError(`DeepSeek Files API returned an invalid ${operation} response.`, "INVALID_RESPONSE");
+}
+function parseFileObject(value, operation) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalidResponse(operation);
+	const wire = value;
+	if (typeof wire.id !== "string" || wire.id.length === 0 || wire.object !== "file" || !Number.isSafeInteger(wire.bytes) || wire.bytes < 0 || !Number.isSafeInteger(wire.created_at) || wire.created_at < 0 || typeof wire.filename !== "string" || wire.filename.length === 0 || wire.purpose !== "user_data" || wire.expires_at !== void 0 && (!Number.isSafeInteger(wire.expires_at) || wire.expires_at < 0)) throw invalidResponse(operation);
+	return {
+		id: DeepSeekFileId(wire.id),
+		bytes: wire.bytes,
+		createdAt: wire.created_at,
+		filename: wire.filename,
+		purpose: "user_data",
+		...wire.expires_at === void 0 ? {} : { expiresAt: wire.expires_at }
+	};
+}
+function providerErrorDetail(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return { detail: "" };
+	const error = value.error;
+	if (error === null || typeof error !== "object" || Array.isArray(error)) return { detail: "" };
+	const fields = error;
+	const message = typeof fields.message === "string" ? fields.message : void 0;
+	return {
+		...message === void 0 ? {} : { message },
+		detail: [
+			fields.code,
+			fields.type,
+			fields.message
+		].filter((field) => typeof field === "string").join(" ")
+	};
+}
+/** Direct client for the OpenAI-compatible `/files` endpoints. */
+var DeepSeekFilesClient = class {
+	baseURL;
+	apiKey;
+	fetchImpl;
+	/**
+	* @param options - endpoint, API-key snapshot, and optional test transport.
+	*/
+	constructor(options) {
+		this.baseURL = options.baseURL.replace(/\/+$/u, "");
+		this.apiKey = options.apiKey;
+		this.fetchImpl = options.fetch ?? globalThis.fetch;
+	}
+	async request(path, init, signal) {
+		let response;
+		try {
+			const headers = new Headers(attributionHeaders());
+			headers.set("authorization", `Bearer ${this.apiKey}`);
+			response = await this.fetchImpl(`${this.baseURL}${path}`, {
+				...init,
+				headers,
+				...signal === void 0 ? {} : { signal }
+			});
+		} catch (error) {
+			if (signal?.aborted) throw error;
+			throw new LlmError(`DeepSeek Files API request to ${this.baseURL} failed`, "TRANSPORT", { cause: error });
+		}
+		if (response.ok) return response;
+		let parsed;
+		try {
+			parsed = await response.json();
+		} catch {}
+		const { message, detail } = providerErrorDetail(parsed);
+		throw new DeepSeekFilesError(message ?? `DeepSeek Files API error (HTTP ${response.status})`, response.status, detail);
+	}
+	/**
+	* Upload one image with an explicit expiry.
+	* @param input - deterministic request-version bytes, media type, filename, lifetime, and cancellation.
+	* @returns the validated provider file object, including `expires_at`.
+	*/
+	async upload(input) {
+		if (input.data.byteLength > 134217728) throw new LlmError("DeepSeek Files API upload exceeds 128 MiB.", "INVALID_REQUEST");
+		if (!Number.isSafeInteger(input.expiresAfterSeconds) || input.expiresAfterSeconds < 3600 || input.expiresAfterSeconds > 2592e3) throw new LlmError("DeepSeek file expiry must be between 3600 and 2592000 seconds.", "INVALID_REQUEST");
+		const form = new FormData();
+		form.set("purpose", "user_data");
+		form.set("expires_after[anchor]", "created_at");
+		form.set("expires_after[seconds]", String(input.expiresAfterSeconds));
+		form.set("file", new Blob([Uint8Array.from(input.data).buffer], { type: input.mediaType }), input.filename);
+		const file = parseFileObject(await (await this.request("/files", {
+			method: "POST",
+			body: form
+		}, input.signal)).json(), "upload");
+		if (file.expiresAt === void 0) throw invalidResponse("upload");
+		return {
+			...file,
+			expiresAt: file.expiresAt
+		};
+	}
+	/**
+	* List one ascending or descending page of user-data files.
+	* @param options - pagination, ordering, and cancellation.
+	* @returns the validated page.
+	*/
+	async list(options = {}) {
+		const query = new URLSearchParams({ purpose: "user_data" });
+		if (options.after !== void 0) query.set("after", options.after);
+		if (options.limit !== void 0) query.set("limit", String(options.limit));
+		if (options.order !== void 0) query.set("order", options.order);
+		const value = await (await this.request(`/files?${query.toString()}`, { method: "GET" }, options.signal)).json();
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalidResponse("list");
+		const wire = value;
+		if (wire.object !== "list" || !Array.isArray(wire.data) || typeof wire.has_more !== "boolean" || wire.first_id !== void 0 && typeof wire.first_id !== "string" || wire.last_id !== void 0 && typeof wire.last_id !== "string") throw invalidResponse("list");
+		return {
+			data: wire.data.map((item) => parseFileObject(item, "list")),
+			...typeof wire.first_id === "string" ? { firstId: DeepSeekFileId(wire.first_id) } : {},
+			...typeof wire.last_id === "string" ? { lastId: DeepSeekFileId(wire.last_id) } : {},
+			hasMore: wire.has_more
+		};
+	}
+	/**
+	* Retrieve one file object.
+	* @param fileId - provider file identifier.
+	* @param signal - request cancellation.
+	* @returns the validated file object.
+	*/
+	async retrieve(fileId, signal) {
+		return parseFileObject(await (await this.request(`/files/${encodeURIComponent(fileId)}`, { method: "GET" }, signal)).json(), "retrieve");
+	}
+	/**
+	* Delete one provider file.
+	* @param fileId - provider file identifier.
+	* @param signal - request cancellation.
+	*/
+	async delete(fileId, signal) {
+		const value = await (await this.request(`/files/${encodeURIComponent(fileId)}`, { method: "DELETE" }, signal)).json();
+		if (value === null || typeof value !== "object" || Array.isArray(value)) throw invalidResponse("delete");
+		const wire = value;
+		if (wire.id !== fileId || wire.object !== "file" || wire.deleted !== true) throw invalidResponse("delete");
+	}
+};
+//#endregion
+//#region lib/types/upload-index.js
+/** Durable DeepSeek attachment-to-file-id index. @module nomix-llm-deepseek/upload-index */
+var InvalidUploadIndexError = class extends Error {};
+/**
+* Derive a non-secret stable index namespace without persisting or logging the API key.
+* @param baseURL - normalized provider endpoint namespace.
+* @param apiKey - resolved credential used only as hash input.
+* @returns branded SHA-256 namespace digest.
+*/
+function deepSeekFileScope(baseURL, apiKey) {
+	return DeepSeekFileScope(createHash("sha256").update(baseURL.replace(/\/+$/u, "")).update("\0").update(apiKey).digest("hex"));
+}
+function absent(error) {
+	return error?.code === "ENOENT";
+}
+function parseRecord(value) {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new InvalidUploadIndexError("llm-deepseek: upload index contains a non-object record");
+	const record = value;
+	if (typeof record.scope !== "string" || !/^[0-9a-f]{64}$/u.test(record.scope) || typeof record.attachmentId !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(record.attachmentId) || typeof record.variantId !== "string" || !/^sha256:[0-9a-f]{64}$/u.test(record.variantId) || typeof record.fileId !== "string" || record.fileId.length === 0 || !Number.isSafeInteger(record.bytes) || record.bytes < 0 || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0 || !Number.isSafeInteger(record.expiresAt) || record.expiresAt < 0) throw new InvalidUploadIndexError("llm-deepseek: upload index contains an invalid record");
+	return {
+		scope: DeepSeekFileScope(record.scope),
+		attachmentId: record.attachmentId,
+		variantId: ImageVariantId(record.variantId),
+		fileId: DeepSeekFileId(record.fileId),
+		bytes: record.bytes,
+		createdAt: record.createdAt,
+		expiresAt: record.expiresAt
+	};
+}
+function parseIndex(text) {
+	let value;
+	try {
+		value = JSON.parse(text);
+	} catch (error) {
+		throw new InvalidUploadIndexError("llm-deepseek: upload index is not valid JSON", { cause: error });
+	}
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new InvalidUploadIndexError("llm-deepseek: upload index is not an object");
+	const index = value;
+	if (index.formatVersion !== 3 || !Array.isArray(index.records)) throw new InvalidUploadIndexError("llm-deepseek: unsupported upload index format");
+	const records = index.records.map(parseRecord);
+	const keys = /* @__PURE__ */ new Set();
+	for (const record of records) {
+		const key = `${record.scope}\0${record.variantId}`;
+		if (keys.has(key)) throw new InvalidUploadIndexError("llm-deepseek: upload index contains duplicate mappings");
+		keys.add(key);
+	}
+	return {
+		formatVersion: 3,
+		records
+	};
+}
+function reusable(record, now, refreshMarginMs) {
+	return record.expiresAt - now > refreshMarginMs;
+}
+/** Atomic local index shared by every DeepSeek session in this NOMIX home. */
+var DeepSeekUploadIndex = class {
+	/** Absolute owner-private JSON index path. */
+	path;
+	/**
+	* @param path - explicit test path; omission uses `NOMIX_HOME/llm-deepseek/files-v3.json`.
+	*/
+	constructor(path = join(resolveNomixHome(), "llm-deepseek", "files-v3.json")) {
+		this.path = path;
+	}
+	async load() {
+		try {
+			return parseIndex(await readFile(this.path, "utf8"));
+		} catch (error) {
+			if (absent(error) || error instanceof InvalidUploadIndexError) return {
+				formatVersion: 3,
+				records: []
+			};
+			throw error;
+		}
+	}
+	async save(index) {
+		await writeFileAtomic(this.path, `${JSON.stringify(index, void 0, 2)}\n`, {
+			mode: 384,
+			dirMode: 448
+		});
+	}
+	/**
+	* Read one reusable mapping.
+	* @param scope - endpoint/API-key namespace.
+	* @param variantId - complete request-image transformation identity.
+	* @param now - current Unix time in milliseconds.
+	* @param refreshMarginMs - remaining lifetime below which a mapping is not reused.
+	* @returns the mapping when it has enough lifetime remaining.
+	*/
+	async get(scope, variantId, now, refreshMarginMs) {
+		const record = (await this.load()).records.find((candidate) => candidate.scope === scope && candidate.variantId === variantId);
+		return record !== void 0 && reusable(record, now, refreshMarginMs) ? record : void 0;
+	}
+	/**
+	* Publish a completed upload unless another process already published a reusable mapping.
+	* @param candidate - completed remote upload.
+	* @param now - current Unix time in milliseconds.
+	* @param refreshMarginMs - minimum reusable remaining lifetime.
+	* @returns the winning record and whether the candidate entered the index.
+	*/
+	async commit(candidate, now, refreshMarginMs) {
+		await mkdir(dirname(this.path), {
+			recursive: true,
+			mode: 448
+		});
+		return withFileLock(this.path, async () => {
+			const index = await this.load();
+			const existing = index.records.find((record) => record.scope === candidate.scope && record.variantId === candidate.variantId && reusable(record, now, refreshMarginMs));
+			if (existing !== void 0) return {
+				record: existing,
+				accepted: false
+			};
+			const records = index.records.filter((record) => reusable(record, now, refreshMarginMs) && !(record.scope === candidate.scope && record.variantId === candidate.variantId));
+			records.push(candidate);
+			await this.save({
+				formatVersion: 3,
+				records
+			});
+			return {
+				record: candidate,
+				accepted: true
+			};
+		});
+	}
+	/**
+	* Remove one exact mapping without deleting a concurrently installed successor.
+	* @param scope - endpoint/API-key namespace.
+	* @param variantId - complete request-image transformation identity.
+	* @param fileId - exact remote generation being invalidated.
+	*/
+	async remove(scope, variantId, fileId) {
+		await mkdir(dirname(this.path), {
+			recursive: true,
+			mode: 448
+		});
+		await withFileLock(this.path, async () => {
+			const index = await this.load();
+			const records = index.records.filter((record) => !(record.scope === scope && record.variantId === variantId && record.fileId === fileId));
+			if (records.length !== index.records.length) await this.save({
+				formatVersion: 3,
+				records
+			});
+		});
+	}
+	/**
+	* Remove every local mapping for one remote namespace.
+	* @param scope - endpoint/API-key namespace.
+	*/
+	async clear(scope) {
+		await mkdir(dirname(this.path), {
+			recursive: true,
+			mode: 448
+		});
+		await withFileLock(this.path, async () => {
+			const index = await this.load();
+			const records = index.records.filter((record) => record.scope !== scope);
+			if (records.length !== index.records.length) await this.save({
+				formatVersion: 3,
+				records
+			});
+		});
+	}
+};
+//#endregion
+//#region lib/types/file-store.js
+/** DeepSeek Files API upload reuse, invalidation, and quota recovery. @module nomix-llm-deepseek/file-store */
+/** DeepSeek chat accepts at most 32 MiB per image even when it is referenced by file id. */
+const MAX_CHAT_IMAGE_BYTES = 32 * 1024 * 1024;
+const OWNED_FILE_PREFIX = "nomix-";
+function abortReason(signal) {
+	const reason = signal.reason;
+	return reason instanceof Error ? reason : new Error("DeepSeek file upload cancelled with a non-Error reason.", { cause: reason });
+}
+function uploadFailure(error) {
+	return error instanceof Error ? error : new Error("DeepSeek file upload failed with a non-Error reason.", { cause: error });
+}
+function waitForUpload(operation, signal) {
+	signal?.throwIfAborted();
+	operation.waiters += 1;
+	let released = false;
+	const release = (cancelledReason) => {
+		if (released) return;
+		released = true;
+		operation.waiters -= 1;
+		if (cancelledReason !== void 0 && operation.waiters === 0 && !operation.settled) operation.controller.abort(cancelledReason);
+	};
+	if (signal === void 0) return operation.promise.finally(() => {
+		release();
+	});
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			const reason = abortReason(signal);
+			release(reason);
+			reject(reason);
+		};
+		signal.addEventListener("abort", abort, { once: true });
+		operation.promise.then((value) => {
+			signal.removeEventListener("abort", abort);
+			release();
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", abort);
+			release();
+			reject(uploadFailure(error));
+		});
+	});
+}
+function extension(mediaType) {
+	switch (mediaType) {
+		case "image/png": return "png";
+		case "image/jpeg": return "jpeg";
+		case "image/webp": return "webp";
+		case "image/gif": return "gif";
+	}
+}
+function filename(version) {
+	return `${OWNED_FILE_PREFIX}${String(version.attachment.attachmentId).slice(7, 23)}-${String(version.variantId).slice(7, 15)}.${extension(version.mediaType)}`;
+}
+/** User-scoped durable file-id reuse for the DeepSeek route. */
+var DeepSeekFileStore = class {
+	index;
+	now;
+	fetchImpl;
+	inflight = /* @__PURE__ */ new Map();
+	/**
+	* @param options - testable index, clock, and transport boundaries.
+	*/
+	constructor(options = {}) {
+		this.index = options.index ?? new DeepSeekUploadIndex();
+		this.now = options.now ?? Date.now;
+		this.fetchImpl = options.fetch;
+	}
+	client(connection) {
+		return new DeepSeekFilesClient({
+			baseURL: connection.baseURL,
+			apiKey: connection.apiKey,
+			...this.fetchImpl === void 0 ? {} : { fetch: this.fetchImpl }
+		});
+	}
+	/**
+	* Resolve or upload one deterministic request image. Concurrent calls share one upload while retaining independent waits.
+	* @param version - deterministic model-request bytes and complete transformation identity.
+	* @param connection - endpoint and API-key snapshot.
+	* @param policy - expiry and quota-recovery policy.
+	* @param signal - cancellation of this wait; shared transport stops when no waiter remains.
+	* @returns a reusable file id and whether this call published a new upload.
+	*/
+	ensureUploaded(version, connection, policy, signal) {
+		signal?.throwIfAborted();
+		const key = `${deepSeekFileScope(connection.baseURL, connection.apiKey)}\0${version.variantId}`;
+		let active = this.inflight.get(key);
+		if (active?.controller.signal.aborted) {
+			this.inflight.delete(key);
+			active = void 0;
+		}
+		if (active !== void 0) return waitForUpload(active, signal);
+		const controller = new AbortController();
+		const shared = {
+			controller,
+			settled: false,
+			waiters: 0,
+			promise: void 0
+		};
+		shared.promise = this.ensureUploadedOnce(version, connection, policy, controller.signal).then((value) => {
+			shared.settled = true;
+			return value;
+		}, (error) => {
+			shared.settled = true;
+			throw uploadFailure(error);
+		});
+		this.inflight.set(key, shared);
+		shared.promise.finally(() => {
+			if (this.inflight.get(key) === shared) this.inflight.delete(key);
+		}).catch(() => {});
+		return waitForUpload(shared, signal);
+	}
+	async ensureUploadedOnce(version, connection, policy, signal) {
+		if (version.bytes > 33554432) throw new LlmError("DeepSeek chat image exceeds the 32 MiB per-image limit.", "INVALID_REQUEST");
+		const scope = deepSeekFileScope(connection.baseURL, connection.apiKey);
+		const now = this.now();
+		const marginMs = policy.refreshMarginSeconds * 1e3;
+		const cached = await this.index.get(scope, version.variantId, now, marginMs);
+		if (cached !== void 0) return {
+			record: cached,
+			uploaded: false
+		};
+		const client = this.client(connection);
+		const upload = async () => {
+			const remote = await client.upload({
+				data: version.data,
+				mediaType: version.mediaType,
+				filename: filename(version),
+				expiresAfterSeconds: policy.expiresAfterSeconds,
+				signal
+			});
+			if (remote.bytes !== version.data.byteLength) throw new LlmError("DeepSeek Files API upload response does not match the submitted image.", "INVALID_RESPONSE");
+			return {
+				scope,
+				attachmentId: version.attachment.attachmentId,
+				variantId: version.variantId,
+				fileId: remote.id,
+				bytes: remote.bytes,
+				createdAt: remote.createdAt * 1e3,
+				expiresAt: remote.expiresAt * 1e3
+			};
+		};
+		let candidate;
+		try {
+			candidate = await upload();
+		} catch (error) {
+			if (!isFilesQuotaError(error)) throw error;
+			if (await this.reclaimOldestOwned(connection, policy.quotaCleanupBatch, signal) === 0) throw error;
+			candidate = await upload();
+		}
+		const committed = await this.index.commit(candidate, this.now(), marginMs);
+		if (!committed.accepted) try {
+			await client.delete(candidate.fileId, signal);
+		} catch {}
+		return {
+			record: committed.record,
+			uploaded: committed.accepted
+		};
+	}
+	/**
+	* Invalidate one exact local mapping after the chat endpoint rejects its remote id.
+	* @param version - request-image version whose remote generation failed.
+	* @param fileId - exact rejected file id.
+	* @param connection - endpoint and API-key snapshot.
+	*/
+	async invalidate(version, fileId, connection) {
+		await this.index.remove(deepSeekFileScope(connection.baseURL, connection.apiKey), version.variantId, fileId);
+	}
+	/**
+	* Delete the indexed remote file for one attachment and remove its local mapping.
+	* @param version - exact request-image version to release.
+	* @param connection - endpoint and API-key snapshot.
+	* @param policy - expiry policy used to locate a reusable mapping.
+	* @param signal - request cancellation.
+	* @returns whether an indexed file existed and was deleted.
+	*/
+	async release(version, connection, policy, signal) {
+		const scope = deepSeekFileScope(connection.baseURL, connection.apiKey);
+		const record = await this.index.get(scope, version.variantId, this.now(), policy.refreshMarginSeconds * 1e3);
+		if (record === void 0) return false;
+		await this.client(connection).delete(record.fileId, signal);
+		await this.index.remove(scope, version.variantId, record.fileId);
+		return true;
+	}
+	/**
+	* Delete the oldest provider files whose names identify harness ownership.
+	* @param connection - endpoint and API-key snapshot.
+	* @param count - positive maximum number of files to delete.
+	* @param signal - request cancellation.
+	* @returns number of successfully deleted files.
+	*/
+	async reclaimOldestOwned(connection, count, signal) {
+		const client = this.client(connection);
+		let after;
+		const owned = [];
+		while (owned.length < count) {
+			const page = await client.list({
+				...after === void 0 ? {} : { after },
+				limit: 1e3,
+				order: "asc",
+				...signal === void 0 ? {} : { signal }
+			});
+			for (const file of page.data) {
+				if (!file.filename.startsWith(OWNED_FILE_PREFIX)) continue;
+				owned.push(file.id);
+				if (owned.length === count) break;
+			}
+			if (!page.hasMore || page.lastId === void 0 || page.lastId === after) break;
+			after = page.lastId;
+		}
+		for (const fileId of owned) await client.delete(fileId, signal);
+		return owned.length;
+	}
+	/**
+	* Delete every remote harness-owned file in the active API-key namespace and clear its index.
+	* @param connection - endpoint and API-key snapshot.
+	* @param signal - request cancellation.
+	* @returns number of deleted files.
+	*/
+	async releaseAll(connection, signal) {
+		let total = 0;
+		for (;;) {
+			const deleted = await this.reclaimOldestOwned(connection, 1e3, signal);
+			total += deleted;
+			if (deleted < 1e3) break;
+		}
+		await this.index.clear(deepSeekFileScope(connection.baseURL, connection.apiKey));
+		return total;
+	}
+};
+/**
 * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
 * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
 * without it (truncated response — the model call cannot be trusted).
@@ -411,7 +1153,34 @@ const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 3e5;
 const DEFAULT_CONTEXT_WINDOW = 1e6;
 /** Default per-request output-token cap. */
 const DEFAULT_MAX_TOKENS = 256e3;
+/** Default bound on accumulated file-referenced image bytes per request. */
+const DEFAULT_MAX_REQUEST_FILES_BYTES = 128 * 1024 * 1024;
+/** Default bound on accumulated base64 image payload after Files API fallback. */
+const DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Provider request image-count limit. */
+const DEFAULT_MAX_IMAGES_PER_REQUEST = 600;
+/** Total-pixel budget matching DeepSeek's normal vision projection. */
+const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 64e4;
+/** Total-pixel budget matching provider low-detail image input. */
+const DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET = 512 * 512;
+/** Encoded-byte cap for one deterministic model-request image. */
+const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
+/** Deterministic raw-byte removal step. */
+const DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM = 64 * 1024 * 1024;
+/** Deterministic base64-byte removal step after Files API fallback. */
+const DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM = 10 * 1024 * 1024;
+/** Deterministic image-count removal step. */
+const DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM = 20;
+/** Default explicit lifetime for uploaded images. */
+const DEFAULT_FILE_EXPIRY_SECONDS = 10080 * 60;
+/** Default proactive refresh window for indexed file ids. */
+const DEFAULT_FILE_REFRESH_MARGIN_SECONDS = 3600;
+/** Default number of oldest harness-owned files removed on quota recovery. */
+const DEFAULT_FILE_QUOTA_CLEANUP_BATCH = 100;
+/** Default deadline for resolving one request image through the Files API. */
+const DEFAULT_FILES_API_TIMEOUT_MS = 6e4;
 const STREAM_IDLE_TIMEOUT_CODE = "LLM_STREAM_IDLE_TIMEOUT";
+const FILES_API_TIMEOUT_CODE = "DEEPSEEK_FILES_API_TIMEOUT";
 const OFF_REASONING_EFFORT = ReasoningEffortId("off");
 const LOW_REASONING_EFFORT = ReasoningEffortId("low");
 const HIGH_REASONING_EFFORT = ReasoningEffortId("high");
@@ -438,13 +1207,83 @@ const OFF_ONLY_REASONING_EFFORTS = [{
 	id: OFF_REASONING_EFFORT,
 	name: "Off"
 }];
+/** Marks a failed file-id resolution that may be retried as an inline request. */
+var FileResolutionFailure = class extends Error {
+	constructor(cause) {
+		super("DeepSeek Files API could not resolve a request image.", { cause });
+		this.name = "FileResolutionFailure";
+	}
+};
+function collectImageRefs(content, refs) {
+	for (const block of content) if (block.type === "image") refs.set(block.attachment.attachmentId, block.attachment);
+	else if (block.type === "tool-result") collectImageRefs(block.content, refs);
+}
+/**
+* Resolve the request-image budgets owned by one DeepSeek model route.
+* @param model - Advertised model route and its optional image overrides.
+* @returns Complete pixel and encoded-byte budgets.
+* @internal
+*/
+function resolveRequestImagePolicy(model) {
+	let maxPixels;
+	if (model.imagePixelBudget !== void 0) maxPixels = model.imagePixelBudget;
+	else if (model.imageDetail === "low") maxPixels = DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET;
+	else maxPixels = DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET;
+	return {
+		maxPixels,
+		maxBytes: model.imageMaxBytes === void 0 ? DEFAULT_REQUEST_IMAGE_MAX_BYTES : model.imageMaxBytes
+	};
+}
+async function prepareRequestImages(options, attachments, model, signal) {
+	const refs = /* @__PURE__ */ new Map();
+	for (const message of options.messages) collectImageRefs(message.content, refs);
+	const policy = resolveRequestImagePolicy(model);
+	const orderedRefs = [...refs.values()];
+	const projected = await Promise.all(orderedRefs.map((ref) => attachments.readImageRequest(ref, policy, signal)));
+	return new Map(orderedRefs.map((ref, index) => [ref.attachmentId, projected[index]]));
+}
+function providerRejectedNormalizedImage(detail) {
+	return /(?:unsupported|invalid|cannot read|failed to (?:decode|process)).{0,40}image/iu.test(detail) || /image.{0,40}(?:unsupported|invalid|cannot be decoded)/iu.test(detail);
+}
+function providerRejectedFileId(detail) {
+	const file = /\bfile(?:[_ -]?(?:id|api|not[_ -]?found|deleted|expired))?/iu.test(detail);
+	const missing = /(?:expired|not[_ -]?found|deleted|do(?:es)? not exist|not created under (?:this|your) account)/iu.test(detail);
+	const invalidId = /(?:invalid.{0,20}file[_ -]?(?:id|api)|file[_ -]?(?:id|api).{0,20}invalid)/iu.test(detail);
+	return file && (missing || invalidId);
+}
+function detailNamesFileId(detail, fileId) {
+	let index = detail.indexOf(fileId);
+	while (index >= 0) {
+		const before = detail[index - 1];
+		const after = detail[index + fileId.length];
+		if ((before === void 0 || !/[\p{L}\p{N}_-]/u.test(before)) && (after === void 0 || !/[\p{L}\p{N}_-]/u.test(after))) return true;
+		index = detail.indexOf(fileId, index + 1);
+	}
+	return false;
+}
+function staleMappings(files, detail) {
+	const unique = [...new Map(files.map((file) => [`${file.version.variantId}\0${file.fileId}`, file])).values()];
+	const exact = unique.filter((file) => detailNamesFileId(detail, file.fileId));
+	return exact.length > 0 ? exact : unique;
+}
+function normalizedImageFacts(file) {
+	const version = file.version;
+	const name = version.attachment.name ?? version.attachment.attachmentId;
+	const colour = version.hasAlpha ? "sRGBA" : "sRGB";
+	return `"${name}" at message ${file.location.message}, image ${file.location.image} (${version.mediaType}, 8-bit ${colour}, ${version.width}x${version.height})`;
+}
+function normalizedImageDiagnostic(files, providerMessage, providerDetail) {
+	const target = files.find((file) => detailNamesFileId(providerDetail, file.fileId)) ?? (files.length === 1 ? files[0] : void 0);
+	if (target !== void 0) return `DeepSeek rejected normalized image ${normalizedImageFacts(target)}: ${providerMessage}. The provider rejected bytes already normalized by the harness; PNG, JPEG, WebP, and GIF remain supported input formats.`;
+	return `DeepSeek rejected a normalized request image: ${providerMessage}. Candidate images: ${[...new Map(files.map((file) => [`${file.version.variantId}\0${file.location.message}\0${file.location.image}`, file])).values()].map(normalizedImageFacts).join("; ")}. The provider rejected bytes already normalized by the harness; PNG, JPEG, WebP, and GIF remain supported input formats.`;
+}
 function modelInfo(provider, model) {
 	return {
 		provider,
 		id: model.id,
 		name: model.name ?? model.id,
 		...model.description === void 0 ? {} : { description: model.description },
-		inputModalities: ["text"]
+		inputModalities: model.inputModalities ?? ["text"]
 	};
 }
 function providerRetryAfterMs(value) {
@@ -468,6 +1307,7 @@ function requestId(headers) {
 */
 function httpErrorCode(status, error) {
 	if (status === 401 || status === 403) return "AUTH";
+	if (status === 413) return "INVALID_REQUEST";
 	const detail = [
 		error?.code,
 		error?.type,
@@ -491,9 +1331,11 @@ function httpErrorCode(status, error) {
 */
 var DeepSeekAdapter = class extends LlmAdapter {
 	config;
+	files;
 	constructor(config) {
 		super();
 		this.config = config;
+		this.files = config.resolveFiles?.() ?? new DeepSeekFileStore();
 	}
 	providerInfo(provider) {
 		return {
@@ -508,10 +1350,12 @@ var DeepSeekAdapter = class extends LlmAdapter {
 		return Promise.resolve(this.config.options().models.map((model) => modelInfo(provider, model)));
 	}
 	resolveModel(provider, model, _signal) {
-		const connection = this.config.options();
+		return Promise.resolve(this.modelInfoFor(this.config.options(), provider, model));
+	}
+	modelInfoFor(connection, provider, model) {
 		const configured = connection.models.find((entry) => entry.id === model);
 		const contextWindow = configured?.contextWindow ?? connection.defaultContextWindow;
-		return Promise.resolve({
+		return {
 			...configured === void 0 ? {
 				provider,
 				id: model,
@@ -527,21 +1371,37 @@ var DeepSeekAdapter = class extends LlmAdapter {
 				efforts: REASONING_EFFORTS,
 				defaultEffort: connection.defaults.reasoningEffort === "off" ? OFF_REASONING_EFFORT : connection.defaults.reasoningEffort === "low" ? LOW_REASONING_EFFORT : connection.defaults.reasoningEffort === "max" ? MAX_REASONING_EFFORT : HIGH_REASONING_EFFORT
 			} }
+		};
+	}
+	prepareCall(provider, model, _signal) {
+		const connection = this.config.options();
+		return Promise.resolve({
+			model: this.modelInfoFor(connection, provider, model),
+			stream: (options) => this.streamWithConnection(options, connection)
 		});
 	}
-	async *stream(options) {
+	stream(options) {
+		return this.streamWithConnection(options, this.config.options());
+	}
+	async *streamWithConnection(options, connection) {
 		const env_1 = {
 			stack: [],
 			error: void 0,
 			hasError: false
 		};
 		try {
-			const connection = this.config.options();
+			const hasImages = options.messages.some((message) => contentHasImage(message.content));
+			let attachments;
+			if (hasImages) {
+				if (connection.models.find((entry) => entry.id === options.model)?.inputModalities?.includes("image") !== true) throw new LlmError(`DeepSeek model "${options.model}" does not accept image input.`, "UNSUPPORTED_CONTENT");
+				attachments = this.config.resolveAttachments?.();
+				if (attachments === void 0) throw new LlmError("DeepSeek image conversion requires the durable attachment service.", "UNSUPPORTED_CONTENT");
+			}
 			const apiKey = await this.config.resolveApiKey(connection);
 			const userId = this.config.resolveUserId();
 			const consumer = new AbortController();
 			const watchdog = __addDisposableResource(env_1, idleWatchdog(options.signal === void 0 ? consumer.signal : AbortSignal.any([options.signal, consumer.signal]), connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE), false);
-			const iterator = this.request(options, watchdog.signal, connection, apiKey, userId, () => {
+			const iterator = this.request(options, watchdog.signal, connection, apiKey, userId, attachments, () => {
 				watchdog.pulse();
 			})[Symbol.asyncIterator]();
 			let exhausted = false;
@@ -572,9 +1432,7 @@ var DeepSeekAdapter = class extends LlmAdapter {
 			__disposeResources(env_1);
 		}
 	}
-	async *request(options, signal, connection, apiKey, userId, onComment) {
-		const body = serializeRequest(options, connection.defaults);
-		const payload = JSON.stringify(body);
+	async *request(options, signal, connection, apiKey, userId, attachments, onActivity) {
 		const headers = {
 			"authorization": `Bearer ${apiKey}`,
 			"content-type": "application/json",
@@ -584,35 +1442,131 @@ var DeepSeekAdapter = class extends LlmAdapter {
 			...options.sessionId !== void 0 ? { "x-nomix-harness-session-id": String(options.sessionId) } : {},
 			...options.purpose === "compaction" ? { "x-nomix-harness-compact": "1" } : {}
 		};
-		let response;
-		try {
-			response = await fetch(`${connection.baseURL}/chat/completions`, {
-				method: "POST",
-				headers,
-				body: payload,
-				signal
-			});
-		} catch (error) {
-			if (signal.aborted) throw error;
-			throw new LlmError(`DeepSeek API request to ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
-		}
-		if (!response.ok) {
-			let message = `DeepSeek API error (HTTP ${response.status})`;
-			let providerError;
+		const fileConnection = {
+			baseURL: connection.baseURL,
+			apiKey
+		};
+		const model = connection.models.find((entry) => entry.id === options.model);
+		const policy = model === void 0 ? void 0 : resolveRequestImagePolicy(model);
+		const requestMessages = policy === void 0 ? options.messages : offloadRequestImagesWithPolicy(options.messages, {
+			representation: "raw",
+			maxBytes: connection.maxRequestFilesBytes,
+			maxImages: connection.maxImagesPerRequest,
+			byteQuantum: connection.imageOffloadByteQuantum,
+			countQuantum: connection.imageOffloadCountQuantum,
+			byteLength: (ref) => Math.min(ref.bytes, policy.maxBytes)
+		});
+		const requestOptions = requestMessages === options.messages ? options : {
+			...options,
+			messages: [...requestMessages]
+		};
+		const requestImages = attachments === void 0 || model === void 0 ? /* @__PURE__ */ new Map() : await prepareRequestImages(requestOptions, attachments, model, signal);
+		let representation = "file";
+		let fileAttempt = 0;
+		while (true) {
+			const usedFiles = [];
+			let body;
+			if (attachments === void 0) body = serializeRequest(requestOptions, connection.defaults);
+			else if (representation === "base64") body = await serializeRequestWithImages(requestOptions, {
+				representation: { kind: "base64" },
+				requestImages,
+				maxRequestImageBytes: connection.maxInlineRequestImageBytes,
+				maxImagesPerRequest: connection.maxImagesPerRequest,
+				byteQuantum: connection.inlineImageOffloadByteQuantum,
+				countQuantum: connection.imageOffloadCountQuantum
+			}, connection.defaults);
+			else try {
+				body = await serializeRequestWithImages(requestOptions, {
+					representation: {
+						kind: "file",
+						resolveFileId: async (version, _block, location) => {
+							const env_2 = {
+								stack: [],
+								error: void 0,
+								hasError: false
+							};
+							try {
+								const filesDeadline = __addDisposableResource(env_2, deadline(signal, connection.filesApiTimeoutMs, FILES_API_TIMEOUT_CODE), false);
+								let resolved;
+								try {
+									resolved = await this.files.ensureUploaded(version, fileConnection, connection.filePolicy, filesDeadline.signal);
+								} catch (error) {
+									if (signal.aborted) throw error;
+									throw new FileResolutionFailure(error);
+								}
+								onActivity();
+								usedFiles.push({
+									version,
+									fileId: resolved.record.fileId,
+									location
+								});
+								return resolved.record.fileId;
+							} catch (e_2) {
+								env_2.error = e_2;
+								env_2.hasError = true;
+							} finally {
+								__disposeResources(env_2);
+							}
+						}
+					},
+					requestImages,
+					maxRequestImageBytes: connection.maxRequestFilesBytes,
+					maxImagesPerRequest: connection.maxImagesPerRequest,
+					byteQuantum: connection.imageOffloadByteQuantum,
+					countQuantum: connection.imageOffloadCountQuantum
+				}, connection.defaults);
+			} catch (error) {
+				if (!(error instanceof FileResolutionFailure)) throw error;
+				representation = "base64";
+				continue;
+			}
+			const payload = JSON.stringify(body);
+			let response;
 			try {
-				providerError = (await response.json()).error;
-				if (providerError?.message) message = providerError.message;
-			} catch {}
-			const delay = providerRetryAfterMs(response.headers.get("retry-after"));
-			const id = requestId(response.headers);
-			throw new LlmError(message, httpErrorCode(response.status, providerError), {
-				status: response.status,
-				...delay === void 0 ? {} : { providerRetryAfterMs: delay },
-				...id === void 0 ? {} : { requestId: id }
-			});
+				response = await fetch(`${connection.baseURL}/chat/completions`, {
+					method: "POST",
+					headers,
+					body: payload,
+					signal
+				});
+			} catch (error) {
+				if (signal.aborted) throw error;
+				throw new LlmError(`DeepSeek API request to ${connection.baseURL} failed`, "TRANSPORT", { cause: error });
+			}
+			if (!response.ok) {
+				let message = `DeepSeek API error (HTTP ${response.status})`;
+				let providerError;
+				const rawResponse = await response.text();
+				try {
+					providerError = JSON.parse(rawResponse).error;
+					if (providerError?.message) message = providerError.message;
+				} catch {}
+				const detail = [
+					providerError?.code,
+					providerError?.type,
+					providerError?.message
+				].filter((field) => typeof field === "string").join(" ");
+				if (usedFiles.length > 0 && providerRejectedFileId(detail)) {
+					await Promise.all(staleMappings(usedFiles, detail).map((file) => this.files.invalidate(file.version, file.fileId, fileConnection)));
+					if (fileAttempt === 0) {
+						fileAttempt += 1;
+						continue;
+					}
+				}
+				if (response.status === 400 && usedFiles.length > 0 && providerRejectedNormalizedImage(detail)) message = normalizedImageDiagnostic(usedFiles, message, detail);
+				const delay = providerRetryAfterMs(response.headers.get("retry-after"));
+				const id = requestId(response.headers);
+				throw new LlmError(message, httpErrorCode(response.status, providerError), {
+					cause: new Error(rawResponse.length > 0 ? rawResponse : `DeepSeek HTTP ${response.status}`),
+					status: response.status,
+					...delay === void 0 ? {} : { providerRetryAfterMs: delay },
+					...id === void 0 ? {} : { requestId: id }
+				});
+			}
+			if (!response.body) throw new LlmError("DeepSeek API returned no response body", "EMPTY_RESPONSE");
+			yield* translate(parseSse(response.body, onActivity));
+			return;
 		}
-		if (!response.body) throw new LlmError("DeepSeek API returned no response body", "EMPTY_RESPONSE");
-		yield* translate(parseSse(response.body, onComment));
 	}
 };
 //#endregion
@@ -635,21 +1589,37 @@ const NS = settingsNamespace("llm-deepseek");
 const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
 /** The single provider route this plugin owns. */
 const PROVIDER = "deepseek-official";
-const DEFAULT_MODELS = [{
-	id: "deepseek-v4-flash",
-	name: "DeepSeek-V4-Flash",
-	contextWindow: DEFAULT_CONTEXT_WINDOW
-}, {
-	id: "deepseek-v4-pro",
-	name: "DeepSeek-V4-Pro",
-	contextWindow: DEFAULT_CONTEXT_WINDOW
-}];
+const DEFAULT_MODELS = [
+	{
+		id: "deepseek-v4-flash",
+		name: "DeepSeek-V4-Flash",
+		contextWindow: DEFAULT_CONTEXT_WINDOW
+	},
+	{
+		id: "deepseek-v4-pro",
+		name: "DeepSeek-V4-Pro",
+		contextWindow: DEFAULT_CONTEXT_WINDOW
+	},
+	{
+		id: "deepseek-v4-flash-vision-exp",
+		name: "DeepSeek-V4-Flash-Vision-Exp",
+		contextWindow: DEFAULT_CONTEXT_WINDOW,
+		inputModalities: ["text", "image"],
+		imagePixelBudget: DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET,
+		imageMaxBytes: DEFAULT_REQUEST_IMAGE_MAX_BYTES
+	}
+];
+const MODEL_MODALITIES = ["text", "image"];
 const catalogModel = z.object({
 	id: z.string().required(),
 	name: z.string(),
 	description: z.string(),
 	contextWindow: z.number().step(1).min(1),
-	maxTokens: z.number().step(1).min(1)
+	maxTokens: z.number().step(1).min(1),
+	inputModalities: z.array(z.union(MODEL_MODALITIES)).min(1).default(["text"]),
+	imagePixelBudget: z.number().step(1).min(1),
+	imageMaxBytes: z.number().step(1).min(1),
+	imageDetail: z.union(["auto", "low"])
 });
 const Config = z.object({
 	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
@@ -665,6 +1635,16 @@ const Config = z.object({
 	defaultContextWindow: z.number().step(1).min(1).default(DEFAULT_CONTEXT_WINDOW),
 	models: z.array(catalogModel).default(DEFAULT_MODELS),
 	streamIdleTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_STREAM_IDLE_TIMEOUT_MS),
+	maxRequestFilesBytes: z.number().step(1).min(1).default(DEFAULT_MAX_REQUEST_FILES_BYTES),
+	maxInlineRequestImageBytes: z.number().step(1).min(1).default(DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES),
+	maxImagesPerRequest: z.number().step(1).min(1).default(600),
+	imageOffloadByteQuantum: z.number().step(1).min(1).default(DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM),
+	inlineImageOffloadByteQuantum: z.number().step(1).min(1).default(DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM),
+	imageOffloadCountQuantum: z.number().step(1).min(1).default(20),
+	filesApiTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_FILES_API_TIMEOUT_MS),
+	fileExpiresAfterSeconds: z.number().step(1).min(3600).max(2592e3).default(DEFAULT_FILE_EXPIRY_SECONDS),
+	fileRefreshMarginSeconds: z.number().step(1).min(0).default(DEFAULT_FILE_REFRESH_MARGIN_SECONDS),
+	fileQuotaCleanupBatch: z.number().step(1).min(1).max(1e3).default(100),
 	retryPolicy: RetryPolicySchema
 });
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
@@ -679,6 +1659,14 @@ function resolveModels(models) {
 		if (model.name !== void 0 && model.name.length === 0) throw new Error(`llm-deepseek: catalog model "${model.id}" has an empty name`);
 		if (model.contextWindow !== void 0 && (!Number.isInteger(model.contextWindow) || model.contextWindow <= 0)) throw new Error(`llm-deepseek: catalog model "${model.id}" contextWindow must be a positive integer`);
 		if (model.maxTokens !== void 0 && (!Number.isInteger(model.maxTokens) || model.maxTokens <= 0)) throw new Error(`llm-deepseek: catalog model "${model.id}" maxTokens must be a positive integer`);
+		const inputModalities = model.inputModalities ?? ["text"];
+		if (inputModalities.length === 0) throw new Error(`llm-deepseek: catalog model "${model.id}" inputModalities must not be empty`);
+		if (inputModalities.some((modality) => !MODEL_MODALITIES.includes(modality))) throw new Error(`llm-deepseek: catalog model "${model.id}" inputModalities must contain only "text" and "image"`);
+		if (new Set(inputModalities).size !== inputModalities.length) throw new Error(`llm-deepseek: catalog model "${model.id}" inputModalities must not contain duplicates`);
+		const hasImage = inputModalities.includes("image");
+		if (!hasImage && (model.imagePixelBudget !== void 0 || model.imageMaxBytes !== void 0 || model.imageDetail !== void 0)) throw new Error(`llm-deepseek: text-only catalog model "${model.id}" cannot declare image request limits`);
+		if (model.imagePixelBudget !== void 0 && (!Number.isSafeInteger(model.imagePixelBudget) || model.imagePixelBudget <= 0)) throw new Error(`llm-deepseek: catalog model "${model.id}" imagePixelBudget must be a positive safe integer`);
+		if (model.imageMaxBytes !== void 0 && (!Number.isSafeInteger(model.imageMaxBytes) || model.imageMaxBytes <= 0)) throw new Error(`llm-deepseek: catalog model "${model.id}" imageMaxBytes must be a positive safe integer`);
 		if (seen.has(model.id)) throw new Error(`llm-deepseek: duplicate catalog model "${model.id}"`);
 		seen.add(model.id);
 		return {
@@ -686,7 +1674,13 @@ function resolveModels(models) {
 			...model.name === void 0 ? {} : { name: model.name },
 			...model.description === void 0 ? {} : { description: model.description },
 			...model.contextWindow === void 0 ? {} : { contextWindow: model.contextWindow },
-			...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens }
+			...model.maxTokens === void 0 ? {} : { maxTokens: model.maxTokens },
+			inputModalities: [...inputModalities],
+			...hasImage ? {
+				imagePixelBudget: model.imagePixelBudget ?? (model.imageDetail === "low" ? 262144 : 64e4),
+				imageMaxBytes: model.imageMaxBytes ?? 1048576,
+				...model.imageDetail === void 0 ? {} : { imageDetail: model.imageDetail }
+			} : {}
 		};
 	});
 }
@@ -708,6 +1702,29 @@ function resolveAdapterOptions(config, environment) {
 	if (config.maxTokens !== void 0 && (!Number.isSafeInteger(config.maxTokens) || config.maxTokens <= 0)) throw new Error("llm-deepseek: maxTokens must be a positive safe integer");
 	const streamIdleTimeoutMs = config.streamIdleTimeoutMs ?? 3e5;
 	if (!Number.isFinite(streamIdleTimeoutMs) || streamIdleTimeoutMs <= 0 || streamIdleTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`llm-deepseek: streamIdleTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	const maxRequestFilesBytes = config.maxRequestFilesBytes ?? 134217728;
+	if (!Number.isSafeInteger(maxRequestFilesBytes) || maxRequestFilesBytes <= 0) throw new Error("llm-deepseek: maxRequestFilesBytes must be a positive safe integer");
+	const maxInlineRequestImageBytes = config.maxInlineRequestImageBytes ?? 20971520;
+	if (!Number.isSafeInteger(maxInlineRequestImageBytes) || maxInlineRequestImageBytes <= 0) throw new Error("llm-deepseek: maxInlineRequestImageBytes must be a positive safe integer");
+	const maxImagesPerRequest = config.maxImagesPerRequest ?? 600;
+	if (!Number.isSafeInteger(maxImagesPerRequest) || maxImagesPerRequest <= 0) throw new Error("llm-deepseek: maxImagesPerRequest must be a positive safe integer");
+	const imageOffloadByteQuantum = config.imageOffloadByteQuantum ?? 67108864;
+	if (!Number.isSafeInteger(imageOffloadByteQuantum) || imageOffloadByteQuantum <= 0) throw new Error("llm-deepseek: imageOffloadByteQuantum must be a positive safe integer");
+	if (imageOffloadByteQuantum > maxRequestFilesBytes) throw new Error("llm-deepseek: imageOffloadByteQuantum must not exceed maxRequestFilesBytes");
+	const inlineImageOffloadByteQuantum = config.inlineImageOffloadByteQuantum ?? 10485760;
+	if (!Number.isSafeInteger(inlineImageOffloadByteQuantum) || inlineImageOffloadByteQuantum <= 0) throw new Error("llm-deepseek: inlineImageOffloadByteQuantum must be a positive safe integer");
+	if (inlineImageOffloadByteQuantum > maxInlineRequestImageBytes) throw new Error("llm-deepseek: inlineImageOffloadByteQuantum must not exceed maxInlineRequestImageBytes");
+	const imageOffloadCountQuantum = config.imageOffloadCountQuantum ?? 20;
+	if (!Number.isSafeInteger(imageOffloadCountQuantum) || imageOffloadCountQuantum <= 0) throw new Error("llm-deepseek: imageOffloadCountQuantum must be a positive safe integer");
+	if (imageOffloadCountQuantum > maxImagesPerRequest) throw new Error("llm-deepseek: imageOffloadCountQuantum must not exceed maxImagesPerRequest");
+	const filesApiTimeoutMs = config.filesApiTimeoutMs ?? 6e4;
+	if (!Number.isFinite(filesApiTimeoutMs) || filesApiTimeoutMs <= 0 || filesApiTimeoutMs > MAX_TIMER_DELAY_MS) throw new Error(`llm-deepseek: filesApiTimeoutMs must be a positive finite number no greater than ${MAX_TIMER_DELAY_MS}`);
+	const fileExpiresAfterSeconds = config.fileExpiresAfterSeconds ?? 604800;
+	if (!Number.isSafeInteger(fileExpiresAfterSeconds) || fileExpiresAfterSeconds < 3600 || fileExpiresAfterSeconds > 2592e3) throw new Error("llm-deepseek: fileExpiresAfterSeconds must be an integer from 3600 through 2592000");
+	const fileRefreshMarginSeconds = config.fileRefreshMarginSeconds ?? 3600;
+	if (!Number.isSafeInteger(fileRefreshMarginSeconds) || fileRefreshMarginSeconds < 0 || fileRefreshMarginSeconds >= fileExpiresAfterSeconds) throw new Error("llm-deepseek: fileRefreshMarginSeconds must be a non-negative integer below fileExpiresAfterSeconds");
+	const fileQuotaCleanupBatch = config.fileQuotaCleanupBatch ?? 100;
+	if (!Number.isSafeInteger(fileQuotaCleanupBatch) || fileQuotaCleanupBatch < 1 || fileQuotaCleanupBatch > 1e3) throw new Error("llm-deepseek: fileQuotaCleanupBatch must be an integer from 1 through 1000");
 	return {
 		apiKeyEnv: credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV),
 		baseURL: config.baseURL ?? environment?.get(BASE_URL_ENV)?.value ?? "https://api.deepseek.com",
@@ -719,6 +1736,18 @@ function resolveAdapterOptions(config, environment) {
 		defaultContextWindow: config.defaultContextWindow ?? 1e6,
 		models: resolveModels(config.models),
 		streamIdleTimeoutMs,
+		maxRequestFilesBytes,
+		maxInlineRequestImageBytes,
+		maxImagesPerRequest,
+		imageOffloadByteQuantum,
+		inlineImageOffloadByteQuantum,
+		imageOffloadCountQuantum,
+		filesApiTimeoutMs,
+		filePolicy: {
+			expiresAfterSeconds: fileExpiresAfterSeconds,
+			refreshMarginSeconds: fileRefreshMarginSeconds,
+			quotaCleanupBatch: fileQuotaCleanupBatch
+		},
 		retryPolicy: resolveRetryPolicy(config.retryPolicy, "llm-deepseek: retryPolicy")
 	};
 }
@@ -760,7 +1789,8 @@ function apply(ctx, config) {
 	const adapter = new DeepSeekAdapter({
 		options,
 		resolveApiKey,
-		resolveUserId
+		resolveUserId,
+		resolveAttachments: () => ctx.get("attachments")
 	});
 	ctx.llm.registerConfigurableProviders([{
 		provider: PROVIDER,
@@ -784,4 +1814,4 @@ function apply(ctx, config) {
 	});
 }
 //#endregion
-export { Config, DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, PUBLIC_BASE_URL, apply, inject, name, resolveAdapterOptions };
+export { Config, DEFAULT_CONTEXT_WINDOW, DEFAULT_FILES_API_TIMEOUT_MS, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET, DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, DeepSeekFileId, DeepSeekFileStore, DeepSeekFilesClient, DeepSeekUploadIndex, MAX_CHAT_IMAGE_BYTES, MAX_FILE_EXPIRY_SECONDS, MAX_FILE_UPLOAD_BYTES, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT, MIN_FILE_EXPIRY_SECONDS, PUBLIC_BASE_URL, apply, deepSeekFileScope, inject, name, resolveAdapterOptions };