@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/llm-deepseek/lib/types/adapter.d.ts

@@ -8,10 +8,13 @@
  * @module nomix-llm-deepseek/adapter
  */
 import { LlmAdapter } from '../../../llm/lib/index.js';
-import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, ResolvedRetryPolicy, StreamChunk } from '../../../llm/lib/index.js';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, PreparedAdapterCall, LlmResolvedModelInfo, ModelModality, ResolvedRetryPolicy, StreamChunk } from '../../../llm/lib/index.js';
+import type { AttachmentStore, ImageRequestPolicy } from '../../../attachment/lib/index.js';
 import type { CredentialRef } from '../../../credentials/lib/index.js';
 import type { AnonymousUserId } from '../../../anonymous-user-id/lib/index.js';
 import type { RequestDefaults } from './serialize.ts';
+import { DeepSeekFileStore } from './file-store.ts';
+import type { DeepSeekFilePolicy } from './file-store.ts';
 import type { WireError } from './types.ts';
 /** One optional model entry advertised by the direct-fetch adapter. */
 export interface DeepSeekCatalogModel {
@@ -25,6 +28,14 @@ export interface DeepSeekCatalogModel {
     contextWindow?: number;
     /** Per-request output cap for this model; omission falls back to the profile's {@link DeepSeekConnectionOptions.maxTokens}. */
     maxTokens?: number;
+    /** Accepted request modalities; omission is text-only. */
+    inputModalities?: ModelModality[];
+    /** Total-pixel budget for one deterministic request preview. */
+    imagePixelBudget?: number;
+    /** Encoded-byte cap for one deterministic request preview. */
+    imageMaxBytes?: number;
+    /** Provider detail tier; `low` uses the 512-by-512 total-pixel default. */
+    imageDetail?: 'auto' | 'low';
 }
 /**
  * Validated connection facts for one operation. The plugin's
@@ -52,6 +63,22 @@ export interface DeepSeekConnectionOptions {
     models: readonly DeepSeekCatalogModel[];
     /** Maximum provider idle time while one stream read is outstanding. */
     streamIdleTimeoutMs: number;
+    /** Maximum accumulated file-referenced image bytes in one request. */
+    maxRequestFilesBytes: number;
+    /** Maximum accumulated base64 image payload after Files API fallback. */
+    maxInlineRequestImageBytes: number;
+    /** Maximum number of represented images in one request. */
+    maxImagesPerRequest: number;
+    /** Raw-byte removal step after the file-reference bound is exceeded. */
+    imageOffloadByteQuantum: number;
+    /** Base64-byte removal step after the inline fallback bound is exceeded. */
+    inlineImageOffloadByteQuantum: number;
+    /** Image-count removal step after the count bound is exceeded. */
+    imageOffloadCountQuantum: number;
+    /** Maximum duration of one request-image Files API resolution. */
+    filesApiTimeoutMs: number;
+    /** Upload expiry, refresh, and quota-recovery policy. */
+    filePolicy: DeepSeekFilePolicy;
     /** Provider-owned model-request retry policy, already resolved. */
     retryPolicy: ResolvedRetryPolicy;
 }
@@ -68,6 +95,10 @@ export interface DeepSeekAdapterOptions {
     resolveApiKey: (connection: DeepSeekConnectionOptions) => Promise<string>;
     /** Resolve the harness-home anonymous id shared with telemetry and feedback. */
     resolveUserId: () => AnonymousUserId;
+    /** Resolve the current durable attachment service; absence rejects image input. */
+    resolveAttachments?: () => AttachmentStore | undefined;
+    /** Resolve the process-wide upload reuse store. */
+    resolveFiles?: () => DeepSeekFileStore;
 }
 /** Default maximum idle interval while an adapter stream read is outstanding. */
 export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
@@ -75,6 +106,39 @@ export declare const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300000;
 export declare const DEFAULT_CONTEXT_WINDOW = 1000000;
 /** Default per-request output-token cap. */
 export declare const DEFAULT_MAX_TOKENS = 256000;
+/** Default bound on accumulated file-referenced image bytes per request. */
+export declare const DEFAULT_MAX_REQUEST_FILES_BYTES: number;
+/** Default bound on accumulated base64 image payload after Files API fallback. */
+export declare const DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES: number;
+/** Provider request image-count limit. */
+export declare const DEFAULT_MAX_IMAGES_PER_REQUEST = 600;
+/** Total-pixel budget matching DeepSeek's normal vision projection. */
+export declare const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 640000;
+/** Total-pixel budget matching provider low-detail image input. */
+export declare const DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET: number;
+/** Encoded-byte cap for one deterministic model-request image. */
+export declare const DEFAULT_REQUEST_IMAGE_MAX_BYTES: number;
+/** Deterministic raw-byte removal step. */
+export declare const DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM: number;
+/** Deterministic base64-byte removal step after Files API fallback. */
+export declare const DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM: number;
+/** Deterministic image-count removal step. */
+export declare const DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM = 20;
+/** Default explicit lifetime for uploaded images. */
+export declare const DEFAULT_FILE_EXPIRY_SECONDS: number;
+/** Default proactive refresh window for indexed file ids. */
+export declare const DEFAULT_FILE_REFRESH_MARGIN_SECONDS: number;
+/** Default number of oldest harness-owned files removed on quota recovery. */
+export declare const DEFAULT_FILE_QUOTA_CLEANUP_BATCH = 100;
+/** Default deadline for resolving one request image through the Files API. */
+export declare const DEFAULT_FILES_API_TIMEOUT_MS = 60000;
+/**
+ * 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
+ */
+export declare function resolveRequestImagePolicy(model: DeepSeekCatalogModel): ImageRequestPolicy;
 /**
  * Map an HTTP status to a stable LlmError code.
  * @param status - status of a non-2xx provider response.
@@ -91,12 +155,16 @@ export declare function httpErrorCode(status: number, error?: WireError['error']
  */
 export declare class DeepSeekAdapter extends LlmAdapter {
     private readonly config;
+    private readonly files;
     constructor(config: DeepSeekAdapterOptions);
     providerInfo(provider: string): LlmProviderInfo;
     providerRetryPolicy(_provider: string): ResolvedRetryPolicy;
     listModels(provider: string): Promise<readonly LlmModelInfo[]>;
     resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    private modelInfoFor;
+    prepareCall(provider: string, model: string, _signal?: AbortSignal): Promise<PreparedAdapterCall>;
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    private streamWithConnection;
     private request;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/dist/kernel/llm-deepseek/lib/types/adapter.js

@@ -59,9 +59,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     var e = new Error(message);
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
-import { attributionHeaders, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId } from '../../../llm/lib/index.js';
-import { idleWatchdog, timeoutOf } from '../../../timeout/lib/index.js';
-import { serializeRequest } from "./serialize.js";
+import { attributionHeaders, contentHasImage, CONTEXT_WINDOW_EXCEEDED_CODE, isContextWindowExceededError, isQuotaExceededError, LlmAdapter, LlmError, offloadRequestImagesWithPolicy, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId } from '../../../llm/lib/index.js';
+import { deadline, idleWatchdog, timeoutOf } from '../../../timeout/lib/index.js';
+import { serializeRequest, serializeRequestWithImages } from "./serialize.js";
+import { DeepSeekFileStore } from "./file-store.js";
 import { parseSse } from "./sse.js";
 import { translate } from "./translate.js";
 /** Default maximum idle interval while an adapter stream read is outstanding. */
@@ -70,7 +71,34 @@ export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000;
 export const DEFAULT_CONTEXT_WINDOW = 1_000_000;
 /** Default per-request output-token cap. */
 export const DEFAULT_MAX_TOKENS = 256_000;
+/** Default bound on accumulated file-referenced image bytes per request. */
+export const DEFAULT_MAX_REQUEST_FILES_BYTES = 128 * 1024 * 1024;
+/** Default bound on accumulated base64 image payload after Files API fallback. */
+export const DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES = 20 * 1024 * 1024;
+/** Provider request image-count limit. */
+export const DEFAULT_MAX_IMAGES_PER_REQUEST = 600;
+/** Total-pixel budget matching DeepSeek's normal vision projection. */
+export const DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET = 640_000;
+/** Total-pixel budget matching provider low-detail image input. */
+export const DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET = 512 * 512;
+/** Encoded-byte cap for one deterministic model-request image. */
+export const DEFAULT_REQUEST_IMAGE_MAX_BYTES = 1024 * 1024;
+/** Deterministic raw-byte removal step. */
+export const DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM = 64 * 1024 * 1024;
+/** Deterministic base64-byte removal step after Files API fallback. */
+export const DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM = 10 * 1024 * 1024;
+/** Deterministic image-count removal step. */
+export const DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM = 20;
+/** Default explicit lifetime for uploaded images. */
+export const DEFAULT_FILE_EXPIRY_SECONDS = 7 * 24 * 60 * 60;
+/** Default proactive refresh window for indexed file ids. */
+export const DEFAULT_FILE_REFRESH_MARGIN_SECONDS = 60 * 60;
+/** Default number of oldest harness-owned files removed on quota recovery. */
+export const DEFAULT_FILE_QUOTA_CLEANUP_BATCH = 100;
+/** Default deadline for resolving one request image through the Files API. */
+export const DEFAULT_FILES_API_TIMEOUT_MS = 60_000;
 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');
@@ -84,13 +112,108 @@ const REASONING_EFFORTS = [
 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. */
+class FileResolutionFailure 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
+ */
+export function resolveRequestImagePolicy(model) {
+    let maxPixels;
+    if (model.imagePixelBudget !== undefined)
+        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 === undefined
+            ? DEFAULT_REQUEST_IMAGE_MAX_BYTES
+            : model.imageMaxBytes,
+    };
+}
+async function prepareRequestImages(options, attachments, model, signal) {
+    const refs = 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) {
+    const reasonBeforeImage = /(?:unsupported|invalid|cannot read|failed to (?:decode|process)).{0,40}image/iu;
+    const imageBeforeReason = /image.{0,40}(?:unsupported|invalid|cannot be decoded)/iu;
+    return reasonBeforeImage.test(detail) || imageBeforeReason.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 === undefined || !/[\p{L}\p{N}_-]/u.test(before))
+            && (after === undefined || !/[\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 exact = files.find(file => detailNamesFileId(providerDetail, file.fileId));
+    const target = exact ?? (files.length === 1 ? files[0] : undefined);
+    if (target !== undefined) {
+        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.';
+    }
+    const candidates = [...new Map(files.map(file => [
+            `${file.version.variantId}\0${file.location.message}\0${file.location.image}`,
+            file,
+        ])).values()];
+    return `DeepSeek rejected a normalized request image: ${providerMessage}. Candidate images: `
+        + `${candidates.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 === undefined ? {} : { description: model.description },
-        inputModalities: ['text'],
+        inputModalities: model.inputModalities ?? ['text'],
     };
 }
 function providerRetryAfterMs(value) {
@@ -116,6 +239,8 @@ function requestId(headers) {
 export function httpErrorCode(status, error) {
     if (status === 401 || status === 403)
         return 'AUTH';
+    if (status === 413)
+        return 'INVALID_REQUEST';
     const detail = [error?.code, error?.type, error?.message].filter(Boolean).join(' ');
     if (isQuotaExceededError(detail))
         return QUOTA_EXCEEDED_CODE;
@@ -139,9 +264,11 @@ export function httpErrorCode(status, error) {
  */
 export class DeepSeekAdapter extends LlmAdapter {
     config;
+    files;
     constructor(config) {
         super();
         this.config = config;
+        this.files = config.resolveFiles?.() ?? new DeepSeekFileStore();
     }
     providerInfo(provider) {
         return { id: provider, name: 'DeepSeek' };
@@ -153,15 +280,16 @@ export class DeepSeekAdapter 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({
-            // The chat-completions wire route is text-only regardless of catalog
-            // membership, so the uncatalogued fallback declares the same negative
-            // capability — "unknown" here would let the host accept and persist
-            // images the serializer must then reject.
+        return {
+            // An uncatalogued endpoint is safely treated as text-only. Declaring an
+            // unverified image capability would let the host persist input that the
+            // endpoint may reject on every later turn.
             ...configured === undefined
                 ? { provider, id: model, name: model, inputModalities: ['text'] }
                 : modelInfo(provider, configured),
@@ -186,9 +314,19 @@ export class DeepSeekAdapter extends LlmAdapter {
                                     : 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 {
             // One resolution per stream call: connection facts and the credential
@@ -196,7 +334,18 @@ export class DeepSeekAdapter extends LlmAdapter {
             // never observes a configuration change and the next call re-resolves.
             // The key resolves *from this snapshot*, so an endpoint and the secret
             // sent to it can never come from different configuration generations.
-            const connection = this.config.options();
+            const hasImages = options.messages.some(message => contentHasImage(message.content));
+            let attachments;
+            if (hasImages) {
+                const model = connection.models.find(entry => entry.id === options.model);
+                if (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 === undefined) {
+                    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();
@@ -204,7 +353,7 @@ export class DeepSeekAdapter extends LlmAdapter {
                 ? consumer.signal
                 : AbortSignal.any([options.signal, consumer.signal]);
             const watchdog = __addDisposableResource(env_1, idleWatchdog(upstream, connection.streamIdleTimeoutMs, STREAM_IDLE_TIMEOUT_CODE), false);
-            const iterator = this.request(options, watchdog.signal, connection, apiKey, userId, () => { watchdog.pulse(); })[Symbol.asyncIterator]();
+            const iterator = this.request(options, watchdog.signal, connection, apiKey, userId, attachments, () => { watchdog.pulse(); })[Symbol.asyncIterator]();
             let exhausted = false;
             try {
                 while (true) {
@@ -247,11 +396,7 @@ export class DeepSeekAdapter extends LlmAdapter {
             __disposeResources(env_1);
         }
     }
-    async *request(options, signal, connection, apiKey, userId, onComment) {
-        const body = serializeRequest(options, connection.defaults);
-        // Prepared outside the try so the TRANSPORT label below covers exactly the
-        // transport boundary, never a serialization failure.
-        const payload = JSON.stringify(body);
+    async *request(options, signal, connection, apiKey, userId, attachments, onActivity) {
         const headers = {
             'authorization': `Bearer ${apiKey}`,
             'content-type': 'application/json',
@@ -265,52 +410,143 @@ export class DeepSeekAdapter extends LlmAdapter {
                 ? { 'x-nomix-harness-compact': '1' }
                 : {},
         };
-        // TODO(http): adopt the Cordis HTTP service when shared transport configuration
-        // outweighs its additional runtime dependencies.
-        let response;
-        try {
-            response = await fetch(`${connection.baseURL}/chat/completions`, {
-                method: 'POST',
-                headers,
-                body: payload,
-                signal,
-            });
-        }
-        catch (error) {
-            // The outer stream distinguishes caller cancellation and watchdog expiry.
-            if (signal.aborted)
-                throw error;
-            // fetch wraps every transport failure (DNS, refused connection, TLS,
-            // proxy) in a bare `TypeError: fetch failed` whose actionable detail
-            // lives on `cause`. Wrapping with the endpoint and chaining the cause
-            // lets `errorChain` render the full diagnosis at every reporting boundary.
-            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 === undefined ? undefined : resolveRequestImagePolicy(model);
+        const requestMessages = policy === undefined ? 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 === undefined || model === undefined
+            ? new Map()
+            : await prepareRequestImages(requestOptions, attachments, model, signal);
+        let representation = 'file';
+        let fileAttempt = 0;
+        while (true) {
+            const usedFiles = [];
+            let body;
+            if (attachments === undefined) {
+                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);
+            // TODO(http): adopt the Cordis HTTP service when shared transport configuration
+            // outweighs its additional runtime dependencies.
+            let response;
             try {
-                const parsed = await response.json();
-                providerError = parsed.error;
-                if (providerError?.message)
-                    message = providerError.message;
+                response = await fetch(`${connection.baseURL}/chat/completions`, {
+                    method: 'POST',
+                    headers,
+                    body: payload,
+                    signal,
+                });
             }
-            catch {
-                // Only swallow error-body parsing: the HTTP status still identifies the
-                // failure, so malformed gateway JSON must not mask it.
+            catch (error) {
+                if (signal.aborted)
+                    throw error;
+                throw new LlmError(`DeepSeek API request to ${connection.baseURL} failed`, 'TRANSPORT', { cause: error });
             }
-            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 === undefined ? {} : { providerRetryAfterMs: delay },
-                ...id === undefined ? {} : { requestId: id },
-            });
-        }
-        if (!response.body) {
-            throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE');
+            if (!response.ok) {
+                let message = `DeepSeek API error (HTTP ${response.status})`;
+                let providerError;
+                const rawResponse = await response.text();
+                try {
+                    const parsed = JSON.parse(rawResponse);
+                    providerError = parsed.error;
+                    if (providerError?.message)
+                        message = providerError.message;
+                }
+                catch {
+                    // The HTTP status remains authoritative when a gateway returns malformed JSON.
+                }
+                const detail = [providerError?.code, providerError?.type, providerError?.message]
+                    .filter((field) => typeof field === 'string')
+                    .join(' ');
+                const staleFile = usedFiles.length > 0 && providerRejectedFileId(detail);
+                if (staleFile) {
+                    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 === undefined ? {} : { providerRetryAfterMs: delay },
+                    ...id === undefined ? {} : { requestId: id },
+                });
+            }
+            if (!response.body) {
+                throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE');
+            }
+            yield* translate(parseSse(response.body, onActivity));
+            return;
         }
-        yield* translate(parseSse(response.body, onComment));
     }
 }
 //# sourceMappingURL=adapter.js.map

package/dist/kernel/llm-deepseek/lib/types/file-id.d.ts

@@ -0,0 +1,19 @@
+/** DeepSeek Files API identifiers. @module nomix-llm-deepseek/file-id */
+import type { Branded } from '../../../brand/lib/index.js';
+/** Opaque identifier returned by the DeepSeek Files API. */
+export type DeepSeekFileId = Branded<'DeepSeekFileId'>;
+/**
+ * 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.
+ */
+export declare function DeepSeekFileId(id: string): DeepSeekFileId;
+/** Non-secret digest identifying one endpoint and API-key file namespace. */
+export type DeepSeekFileScope = Branded<'DeepSeekFileScope'>;
+/**
+ * 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.
+ */
+export declare function DeepSeekFileScope(scope: string): DeepSeekFileScope;
+//# sourceMappingURL=file-id.d.ts.map

package/dist/kernel/llm-deepseek/lib/types/file-id.js

@@ -0,0 +1,18 @@
+/** 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.
+ */
+export 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.
+ */
+export function DeepSeekFileScope(scope) {
+    return scope;
+}
+//# sourceMappingURL=file-id.js.map