@nomix-ai/nomix-harness 0.2.4 → 0.2.6

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

@@ -10,13 +10,21 @@
  * in place when it changes.
  * @module @nomix-ai/nomix-llm-deepseek
  */
-import type { Context } from '@nomix-ai/cordis';
-import z from '@nomix-ai/schemastery';
+import type { Context } from '../../../cordis/lib/index.js';
+import z from '../../../schemastery/lib/index.mjs';
 import type { RetryPolicyConfig } from '../../../llm/lib/index.js';
 import { type LaunchEnvironmentSnapshot } from '../../../launch-environment/lib/index.js';
 import type { DeepSeekCatalogModel, DeepSeekConnectionOptions } from './adapter.ts';
-export { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from './adapter.ts';
+export { DEFAULT_CONTEXT_WINDOW, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_FILES_API_TIMEOUT_MS, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from './adapter.ts';
 export type { DeepSeekAdapterOptions, DeepSeekCatalogModel, DeepSeekConnectionOptions } from './adapter.ts';
+export { DeepSeekFileStore, MAX_CHAT_IMAGE_BYTES } from './file-store.ts';
+export type { DeepSeekFileConnection, DeepSeekFilePolicy, DeepSeekFileReference } from './file-store.ts';
+export { DeepSeekFilesClient, MAX_FILE_EXPIRY_SECONDS, MAX_FILE_UPLOAD_BYTES, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT, MIN_FILE_EXPIRY_SECONDS } from './files-api.ts';
+export type { DeepSeekFileObject, DeepSeekFilePage } from './files-api.ts';
+export { DeepSeekFileId } from './file-id.ts';
+export type { DeepSeekFileId as DeepSeekFileIdType } from './file-id.ts';
+export { DeepSeekUploadIndex, deepSeekFileScope } from './upload-index.ts';
+export type { DeepSeekUploadRecord } from './upload-index.ts';
 export type { RequestDefaults } from './serialize.ts';
 export type * from './types.ts';
 export declare const name = "llm-deepseek";
@@ -42,11 +50,31 @@ export interface Config {
     maxTokens?: number;
     /** Positive context capacity used when the selected model has no exact value (default 1,000,000). */
     defaultContextWindow?: number;
-    /** Advisory models shown by discovery consumers; defaults to V4 Flash and V4 Pro. */
+    /** Advisory models shown by discovery consumers; defaults to V4 Flash, V4 Pro, and V4 Flash Vision Exp. */
     models?: DeepSeekCatalogModel[];
     /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
     streamIdleTimeoutMs?: number;
-    /** Provider-owned model-request retry policy; omission uses normal defaults. */
+    /** Maximum accumulated file-referenced image bytes per chat request (default 128 MiB). */
+    maxRequestFilesBytes?: number;
+    /** Maximum accumulated base64 image payload after Files API fallback (default 20 MiB). */
+    maxInlineRequestImageBytes?: number;
+    /** Maximum number of represented images per chat request (default 600). */
+    maxImagesPerRequest?: number;
+    /** Raw-byte removal step after the request exceeds its file bound (default 64 MiB). */
+    imageOffloadByteQuantum?: number;
+    /** Base64-byte removal step after inline fallback exceeds its bound (default 10 MiB). */
+    inlineImageOffloadByteQuantum?: number;
+    /** Image-count removal step after the request exceeds its count bound (default 20). */
+    imageOffloadCountQuantum?: number;
+    /** Maximum duration of one request-image Files API resolution (default one minute). */
+    filesApiTimeoutMs?: number;
+    /** Explicit lifetime assigned to each uploaded image (default seven days). */
+    fileExpiresAfterSeconds?: number;
+    /** Remaining lifetime below which an indexed file is replaced (default one hour). */
+    fileRefreshMarginSeconds?: number;
+    /** Oldest harness-owned files deleted before one quota-recovery upload retry (default 100). */
+    fileQuotaCleanupBatch?: number;
+    /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
     retryPolicy?: RetryPolicyConfig;
 }
 export declare const Config: z<Config>;

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

@@ -10,15 +10,19 @@
  * in place when it changes.
  * @module @nomix-ai/nomix-llm-deepseek
  */
-import z from '@nomix-ai/schemastery';
+import z from '../../../schemastery/lib/index.mjs';
 import { assertUsableApiKey, LlmError, resolveRetryPolicy, RetryPolicySchema } 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 } from '../../../timeout/lib/index.js';
 import { getOrCreateAnonymousUserId } from '../../../anonymous-user-id/lib/index.js';
-import { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from "./adapter.js";
-export { DEFAULT_CONTEXT_WINDOW, DEFAULT_MAX_TOKENS, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from "./adapter.js";
+import { DEFAULT_CONTEXT_WINDOW, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_FILES_API_TIMEOUT_MS, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from "./adapter.js";
+export { DEFAULT_CONTEXT_WINDOW, DEFAULT_FILE_EXPIRY_SECONDS, DEFAULT_FILE_QUOTA_CLEANUP_BATCH, DEFAULT_FILE_REFRESH_MARGIN_SECONDS, DEFAULT_FILES_API_TIMEOUT_MS, DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM, DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM, DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET, DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES, DEFAULT_MAX_IMAGES_PER_REQUEST, DEFAULT_MAX_REQUEST_FILES_BYTES, DEFAULT_MAX_TOKENS, DEFAULT_REQUEST_IMAGE_MAX_BYTES, DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET, DEFAULT_STREAM_IDLE_TIMEOUT_MS, DeepSeekAdapter, } from "./adapter.js";
+export { DeepSeekFileStore, MAX_CHAT_IMAGE_BYTES } from "./file-store.js";
+export { DeepSeekFilesClient, MAX_FILE_EXPIRY_SECONDS, MAX_FILE_UPLOAD_BYTES, MAX_STORED_FILE_BYTES, MAX_STORED_FILE_COUNT, MIN_FILE_EXPIRY_SECONDS } from "./files-api.js";
+export { DeepSeekFileId } from "./file-id.js";
+export { DeepSeekUploadIndex, deepSeekFileScope } from "./upload-index.js";
 export const name = 'llm-deepseek';
 export const inject = ['llm'];
 const NS = settingsNamespace('llm-deepseek');
@@ -28,13 +32,26 @@ 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 },
+    {
+        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),
+    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']),
 });
 export const Config = z.object({
     apiKeyEnv: z.string().role('credential-ref').default(DEFAULT_API_KEY_ENV),
@@ -45,6 +62,16 @@ export 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(DEFAULT_MAX_IMAGES_PER_REQUEST),
+    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(DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM),
+    filesApiTimeoutMs: z.number().min(Number.MIN_VALUE).max(MAX_TIMER_DELAY_MS).default(DEFAULT_FILES_API_TIMEOUT_MS),
+    fileExpiresAfterSeconds: z.number().step(1).min(3_600).max(2_592_000).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(1_000).default(DEFAULT_FILE_QUOTA_CLEANUP_BATCH),
     retryPolicy: RetryPolicySchema,
 });
 /** Public API default; the internal endpoint comes from $DEEPSEEK_BASE_URL. */
@@ -68,6 +95,29 @@ function resolveModels(models) {
             && (!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 !== undefined
+            || model.imageMaxBytes !== undefined || model.imageDetail !== undefined)) {
+            throw new Error(`llm-deepseek: text-only catalog model "${model.id}" cannot declare image request limits`);
+        }
+        if (model.imagePixelBudget !== undefined
+            && (!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 !== undefined
+            && (!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);
@@ -77,6 +127,17 @@ function resolveModels(models) {
             ...model.description === undefined ? {} : { description: model.description },
             ...model.contextWindow === undefined ? {} : { contextWindow: model.contextWindow },
             ...model.maxTokens === undefined ? {} : { maxTokens: model.maxTokens },
+            inputModalities: [...inputModalities],
+            ...hasImage
+                ? {
+                    imagePixelBudget: model.imagePixelBudget
+                        ?? (model.imageDetail === 'low'
+                            ? DEFAULT_LOW_DETAIL_IMAGE_PIXEL_BUDGET
+                            : DEFAULT_REQUEST_IMAGE_PIXEL_BUDGET),
+                    imageMaxBytes: model.imageMaxBytes ?? DEFAULT_REQUEST_IMAGE_MAX_BYTES,
+                    ...model.imageDetail === undefined ? {} : { imageDetail: model.imageDetail },
+                }
+                : {},
         };
     });
 }
@@ -112,6 +173,64 @@ export function resolveAdapterOptions(config, environment) {
         || 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 ?? DEFAULT_MAX_REQUEST_FILES_BYTES;
+    if (!Number.isSafeInteger(maxRequestFilesBytes) || maxRequestFilesBytes <= 0) {
+        throw new Error('llm-deepseek: maxRequestFilesBytes must be a positive safe integer');
+    }
+    const maxInlineRequestImageBytes = config.maxInlineRequestImageBytes ?? DEFAULT_MAX_INLINE_REQUEST_IMAGE_BYTES;
+    if (!Number.isSafeInteger(maxInlineRequestImageBytes) || maxInlineRequestImageBytes <= 0) {
+        throw new Error('llm-deepseek: maxInlineRequestImageBytes must be a positive safe integer');
+    }
+    const maxImagesPerRequest = config.maxImagesPerRequest ?? DEFAULT_MAX_IMAGES_PER_REQUEST;
+    if (!Number.isSafeInteger(maxImagesPerRequest) || maxImagesPerRequest <= 0) {
+        throw new Error('llm-deepseek: maxImagesPerRequest must be a positive safe integer');
+    }
+    const imageOffloadByteQuantum = config.imageOffloadByteQuantum ?? DEFAULT_IMAGE_OFFLOAD_BYTE_QUANTUM;
+    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
+        ?? DEFAULT_INLINE_IMAGE_OFFLOAD_BYTE_QUANTUM;
+    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 ?? DEFAULT_IMAGE_OFFLOAD_COUNT_QUANTUM;
+    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 ?? DEFAULT_FILES_API_TIMEOUT_MS;
+    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 ?? DEFAULT_FILE_EXPIRY_SECONDS;
+    if (!Number.isSafeInteger(fileExpiresAfterSeconds)
+        || fileExpiresAfterSeconds < 3_600
+        || fileExpiresAfterSeconds > 2_592_000) {
+        throw new Error('llm-deepseek: fileExpiresAfterSeconds must be an integer from 3600 through 2592000');
+    }
+    const fileRefreshMarginSeconds = config.fileRefreshMarginSeconds ?? DEFAULT_FILE_REFRESH_MARGIN_SECONDS;
+    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 ?? DEFAULT_FILE_QUOTA_CLEANUP_BATCH;
+    if (!Number.isSafeInteger(fileQuotaCleanupBatch)
+        || fileQuotaCleanupBatch < 1
+        || fileQuotaCleanupBatch > 1_000) {
+        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
@@ -125,6 +244,18 @@ export function resolveAdapterOptions(config, environment) {
         defaultContextWindow: config.defaultContextWindow ?? DEFAULT_CONTEXT_WINDOW,
         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'),
     };
 }
@@ -178,7 +309,12 @@ export function apply(ctx, config) {
     };
     let userId;
     const resolveUserId = () => userId ??= getOrCreateAnonymousUserId();
-    const adapter = new DeepSeekAdapter({ options, resolveApiKey, resolveUserId });
+    const adapter = new DeepSeekAdapter({
+        options,
+        resolveApiKey,
+        resolveUserId,
+        resolveAttachments: () => ctx.get('attachments'),
+    });
     ctx.llm.registerConfigurableProviders([
         { provider: PROVIDER, displayName: 'DeepSeek', settingsNs: NS, settingsPath: [] },
     ]);

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

@@ -2,7 +2,7 @@
  * Package-owned invariant companion for `@nomix-ai/nomix-llm-deepseek`.
  * @module @nomix-ai/nomix-llm-deepseek/invariant
  */
-import type { Context } from '@nomix-ai/cordis';
+import type { Context } from '../../../cordis/lib/index.js';
 /** Cordis companion plugin name. */
 export declare const name = "llm-deepseek-invariant";
 /** Service required before the companion can reserve package ownership. */

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

@@ -1,18 +1,48 @@
 /**
- * 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
  */
-import type { GenerateOptions, Message } from '../../../llm/lib/index.js';
+import type { ContentBlock, GenerateOptions, Message } from '../../../llm/lib/index.js';
+import type { ImageAttachmentRef, RequestImageAttachment } from '../../../attachment/lib/index.js';
 import type { WireMessage, WireRequest } from './types.ts';
 /** Adapter-level request defaults (from plugin config). */
 export interface RequestDefaults {
     thinking?: 'enabled' | 'disabled' | undefined;
     reasoningEffort?: 'off' | 'low' | 'high' | 'max' | undefined;
 }
+/** Provider representation for every retained image in one request. */
+export type ImageRequestRepresentation = {
+    kind: 'file';
+    /** Resolve a retained request version to a reusable DeepSeek file id. */
+    resolveFileId: (version: RequestImageAttachment, block: Extract<ContentBlock, {
+        type: 'image';
+    }>, location: ImageWireLocation) => Promise<string>;
+} | {
+    kind: 'base64';
+};
+/** Dependencies required only when the request contains image input. */
+export interface ImageSerializationOptions {
+    /** One representation used for every retained image in this request. */
+    representation: ImageRequestRepresentation;
+    /** Request versions prepared for the conservatively retained normalized attachments, keyed by attachment id. */
+    requestImages: ReadonlyMap<ImageAttachmentRef['attachmentId'], RequestImageAttachment>;
+    /** Positive bound on accumulated represented image bytes. */
+    maxRequestImageBytes: number;
+    /** Maximum represented images in one request. */
+    maxImagesPerRequest?: number;
+    /** Represented-byte removal step applied after the request exceeds its byte bound. */
+    byteQuantum?: number;
+    /** Image-count removal step applied after the request exceeds its count bound. */
+    countQuantum?: number;
+}
+/** Durable message and image ordinal used in provider diagnostics. */
+export interface ImageWireLocation {
+    message: number;
+    image: number;
+}
 /**
  * Serialize the conversation. `tool-result` blocks become standalone
  * `{role: 'tool'}` messages; the harness puts each tool result in its own
@@ -22,6 +52,15 @@ export interface RequestDefaults {
  * @returns the wire messages; order preserved, each tool result expanded into its own entry.
  */
 export declare function serializeMessages(messages: Message[]): WireMessage[];
+/**
+ * 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.
+ */
+export declare function serializeMessagesWithImages(messages: readonly Message[], images: ImageSerializationOptions): Promise<WireMessage[]>;
 /**
  * Build the full wire request. Always streaming (`stream: true`, usage
  * reporting on); optional fields are omitted rather than sent as null, so
@@ -31,4 +70,14 @@ export declare function serializeMessages(messages: Message[]): WireMessage[];
  * @returns the chat-completions request body.
  */
 export declare function serializeRequest(options: GenerateOptions, defaults?: RequestDefaults): WireRequest;
+/**
+ * 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.
+ */
+export declare function serializeRequestWithImages(options: GenerateOptions, images: ImageSerializationOptions, defaults?: RequestDefaults): Promise<WireRequest>;
 //# sourceMappingURL=serialize.d.ts.map

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

@@ -1,12 +1,12 @@
 /**
- * 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
  */
-import { contentHasImage, LlmError } from '../../../llm/lib/index.js';
+import { contentHasImage, LlmError, offloadRequestImagesWithPolicy, requestImageHandleText } from '../../../llm/lib/index.js';
+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') {
@@ -44,6 +44,68 @@ function assertTextOnly(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 === undefined) {
+        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:
+                // Other merge-extensible blocks are not DeepSeek user-input vocabulary.
+                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);
@@ -69,10 +131,12 @@ function serializeAssistant(message) {
         // the message sits durably in the session log, a null here bricks every
         // later turn of that session.
         content: text,
-        // Official passback rule (guides/thinking_mode.mdx): reasoning_content
-        // must return on tool-call turns; it is ignored on plain turns, so we
-        // drop it there to save tokens.
-        ...toolCalls.length > 0 && reasoning.length > 0 ? { reasoning_content: reasoning } : {},
+        // CoT passback on every reasoning-carrying turn. The official rule
+        // (guides/thinking_mode.mdx) requires it on tool-call turns and ignores it
+        // elsewhere; a gateway re-encoding the conversation for another vendor
+        // recovers that turn's upstream thinking signature by hashing this exact
+        // text, which a tool-call-free turn carries nowhere else.
+        ...reasoning.length > 0 ? { reasoning_content: reasoning } : {},
         ...toolCalls.length > 0 ? { tool_calls: toolCalls } : {},
     };
 }
@@ -115,19 +179,65 @@ export 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.
  */
-export function serializeRequest(options, defaults = {}) {
-    const messages = [];
-    if (options.system !== undefined) {
-        messages.push({ role: 'system', content: options.system });
+export 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);
+        }
     }
-    messages.push(...serializeMessages(options.messages));
+    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: {
@@ -136,8 +246,6 @@ export function serializeRequest(options, defaults = {}) {
             parameters: tool.parameters,
         },
     }));
-    // A short title budget must produce visible text; conversation and
-    // compaction calls continue to inherit the adapter's thinking defaults.
     const resolvedThinking = resolveThinking(options, defaults);
     return {
         model: options.model,
@@ -154,4 +262,52 @@ export function serializeRequest(options, defaults = {}) {
         ...options.stop !== undefined ? { stop: options.stop } : {},
     };
 }
+/**
+ * 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.
+ */
+export function serializeRequest(options, defaults = {}) {
+    const messages = [];
+    if (options.system !== undefined) {
+        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.
+ */
+export 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 === undefined) {
+                throw new LlmError(`DeepSeek request image ${ref.attachmentId} was not prepared.`, 'INVALID_REQUEST');
+            }
+            return version.bytes;
+        },
+        maxBytes: images.maxRequestImageBytes,
+        ...images.maxImagesPerRequest === undefined ? {} : { maxImages: images.maxImagesPerRequest },
+        ...images.byteQuantum === undefined ? {} : { byteQuantum: images.byteQuantum },
+        ...images.countQuantum === undefined ? {} : { countQuantum: images.countQuantum },
+    });
+    const messages = [];
+    if (options.system !== undefined) {
+        messages.push({ role: 'system', content: options.system });
+    }
+    messages.push(...await serializeMessagesWithImages(requestMessages, images));
+    return requestWithMessages(options, messages, defaults);
+}
 //# sourceMappingURL=serialize.js.map