@nomix-ai/nomix-harness 0.2.5 → 0.2.6

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

@@ -353,7 +353,7 @@ function isHarnessError(value) {
 *
 * @module @nomix-ai/nomix-llm/retry-policy
 */
-const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRIES = 5;
 const DEFAULT_INITIAL_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 1e4;
 const DEFAULT_JITTER_RATIO = .1;
@@ -387,7 +387,12 @@ const NORMAL_POLICY_KEYS = new Set([
 	"retryableCodes",
 	"backoff"
 ]);
-const ALWAYS_POLICY_KEYS = new Set(["mode", "backoff"]);
+const ALWAYS_POLICY_KEYS = new Set([
+	"mode",
+	"maxRetries",
+	"retryableCodes",
+	"backoff"
+]);
 const BACKOFF_KEYS = new Set([
 	"initialDelayMs",
 	"maxDelayMs",
@@ -575,6 +580,173 @@ function normalizeApiKey(raw) {
 	};
 }
 //#endregion
+//#region lib/types/content.js
+/** Content-block structure helpers. @module @nomix-ai/nomix-llm/content */
+/** Model-facing stand-in for an image removed to fit a provider request bound. */
+const OFFLOADED_IMAGE_TEXT = "[image omitted to keep the request within its image limit; older images are omitted first. If this image is still needed, read its file again when a path is available; otherwise ask the user to attach it again.]";
+/**
+* Stable text shown to a model that cannot accept one durable image reference.
+* @param ref - durable master reference omitted from the request.
+* @returns deterministic text-only placeholder.
+*/
+function textOnlyImageText(ref) {
+	return `[image omitted because this model accepts text only; attachment sha256:${String(ref.attachmentId).slice(7, 15)}]`;
+}
+/**
+* Stable model-facing handle for one exact request image.
+* @param version - exact request image shown beside the text.
+* @returns attachment handle and request-image dimensions.
+*/
+function requestImageHandleText(version) {
+	return `Image ${version.attachment.attachmentId}; request image ${version.width}x${version.height}px.`;
+}
+/**
+* True when typed model content contains an image block, walking nested
+* tool-result content. This is the one recursive image walk shared by every
+* image policy (capability gating, text-only serialization, compaction
+* survey), so a consumer cannot silently diverge on nesting depth.
+* @param content - typed model content blocks.
+* @returns whether any nested block is an image.
+*/
+function contentHasImage(content) {
+	return content.some((block) => block.type === "image" || block.type === "tool-result" && contentHasImage(block.content));
+}
+/** Base64 length of raw image bytes, including padding. */
+function base64Length(bytes) {
+	return Math.ceil(bytes / 3) * 4;
+}
+/** Collect represented image lengths in request and nested-block order. */
+function collectImageLengths(blocks, lengths, policy) {
+	for (const block of blocks) if (block.type === "image") {
+		const bytes = policy.byteLength === void 0 ? block.attachment.bytes : policy.byteLength(block.attachment);
+		lengths.push(policy.representation === "base64" ? base64Length(bytes) : bytes);
+	} else if (block.type === "tool-result") collectImageLengths(block.content, lengths, policy);
+}
+/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
+function replaceOldestImages(blocks, remaining) {
+	let next;
+	for (const [index, block] of blocks.entries()) {
+		if (block.type === "image" && remaining.count > 0) {
+			remaining.count -= 1;
+			next ??= blocks.slice(0, index);
+			next.push({
+				type: "text",
+				text: OFFLOADED_IMAGE_TEXT
+			});
+			continue;
+		}
+		if (block.type === "tool-result") {
+			const content = replaceOldestImages(block.content, remaining);
+			if (content !== block.content) {
+				next ??= blocks.slice(0, index);
+				next.push({
+					...block,
+					content
+				});
+				continue;
+			}
+		}
+		next?.push(block);
+	}
+	return next ?? blocks;
+}
+/** Replace every image occurrence, including nested tool results, for a text-only model. */
+function replaceImagesForTextModel(blocks) {
+	let next;
+	for (const [index, block] of blocks.entries()) {
+		if (block.type === "image") {
+			next ??= blocks.slice(0, index);
+			next.push({
+				type: "text",
+				text: textOnlyImageText(block.attachment)
+			});
+			continue;
+		}
+		if (block.type === "tool-result") {
+			const content = replaceImagesForTextModel(block.content);
+			if (content !== block.content) {
+				next ??= blocks.slice(0, index);
+				next.push({
+					...block,
+					content
+				});
+				continue;
+			}
+		}
+		next?.push(block);
+	}
+	return next ?? blocks;
+}
+/**
+* Project durable image history into deterministic text for an exact text-only model.
+* @param messages - complete request history.
+* @returns the original list without images, otherwise shallow message copies with stable placeholders.
+*/
+function projectImagesForTextModel(messages) {
+	if (!messages.some((message) => contentHasImage(message.content))) return messages;
+	return messages.map((message) => {
+		const content = replaceImagesForTextModel(message.content);
+		return content === message.content ? message : {
+			...message,
+			content
+		};
+	});
+}
+/**
+* Return transient request messages whose oldest images are replaced until
+* their accumulated base64 payload fits the configured bound. The selection
+* is deterministic from durable message order and attachment metadata; a
+* provider can serialize the returned messages without reading omitted bytes.
+* @param messages - complete request history, oldest first.
+* @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+* @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+*/
+function offloadRequestImages(messages, maxRequestImageBytes) {
+	return offloadRequestImagesWithPolicy(messages, {
+		representation: "base64",
+		...maxRequestImageBytes === void 0 ? {} : { maxBytes: maxRequestImageBytes },
+		byteQuantum: 1
+	});
+}
+/**
+* Return a deterministic transient projection whose oldest images are replaced
+* in whole count and byte quanta after a route budget is exceeded. The target
+* depends only on complete durable history: at 129 one-megabyte images under
+* a 128 MiB bound with a 64 MiB quantum, the oldest 65 images are removed so
+* 64 MiB remain; that removed prefix stays fixed until total history exceeds
+* 192 MiB.
+* @param messages - complete request history, oldest first.
+* @param policy - route representation, budgets, and removal quanta.
+* @returns original messages below both bounds, otherwise shallow copies with deterministic placeholders.
+*/
+function offloadRequestImagesWithPolicy(messages, policy) {
+	const lengths = [];
+	for (const message of messages) collectImageLengths(message.content, lengths, policy);
+	const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+	const excessCount = policy.maxImages === void 0 ? 0 : Math.max(0, lengths.length - policy.maxImages);
+	const excessBytes = policy.maxBytes === void 0 ? 0 : Math.max(0, total - policy.maxBytes);
+	if (excessCount === 0 && excessBytes === 0) return messages;
+	const countQuantum = policy.countQuantum ?? 1;
+	const byteQuantum = policy.byteQuantum ?? 1;
+	const removeCount = excessCount === 0 ? 0 : Math.ceil(excessCount / countQuantum) * countQuantum;
+	const removeBytes = excessBytes === 0 ? 0 : Math.ceil(excessBytes / byteQuantum) * byteQuantum;
+	let count = 0;
+	let removedBytes = 0;
+	for (const imageBytes of lengths) {
+		if (count >= removeCount && (removeBytes === 0 || (byteQuantum === 1 ? removedBytes >= removeBytes : removedBytes > removeBytes))) break;
+		removedBytes += imageBytes;
+		count += 1;
+	}
+	const remaining = { count };
+	return messages.map((message) => {
+		const content = replaceOldestImages(message.content, remaining);
+		return content === message.content ? message : {
+			...message,
+			content
+		};
+	});
+}
+//#endregion
 //#region lib/types/attribution.js
 /**
 * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
@@ -637,20 +809,6 @@ function assertNever(value, context) {
 	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
 }
 //#endregion
-//#region lib/types/content.js
-/** Content-block structure helpers. @module @nomix-ai/nomix-llm/content */
-/**
-* True when typed model content contains an image block, walking nested
-* tool-result content. This is the one recursive image walk shared by every
-* image policy (capability gating, text-only serialization, compaction
-* survey), so a consumer cannot silently diverge on nesting depth.
-* @param content - typed model content blocks.
-* @returns whether any nested block is an image.
-*/
-function contentHasImage(content) {
-	return content.some((block) => block.type === "image" || block.type === "tool-result" && contentHasImage(block.content));
-}
-//#endregion
 //#region lib/types/assembler.js
 /**
 * Incremental chunk-to-message assembler. This is the single canonical assembly
@@ -664,7 +822,8 @@ function contentHasImage(content) {
 * {@link ContentBlock}s and a final assistant {@link Message}.
 *
 * The agent loop feeds it while logging raw chunks for replay fidelity, then
-* reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+* reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+* or `interruptedBlocks()` when cancellation cut the stream short.
 *
 * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
 * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -797,6 +956,21 @@ var BlockAssembler = class {
 	blocks() {
 		return this.assembled().blocks;
 	}
+	/**
+	* Assemble the prefix an interrupted stream can safely finalize: closed and
+	* open text/reasoning blocks with non-whitespace content, in stream order.
+	* Tool calls are omitted because interruption precedes dispatch; retaining
+	* one would require a fabricated result. Open unknown blocks are also omitted.
+	* @returns the kept blocks; empty when nothing streamed before the interruption.
+	*/
+	interruptedBlocks() {
+		return this.order.map((index) => {
+			const partial = this.mustGet(index);
+			const type = partial.block?.type ?? partial.blockType;
+			if (type !== "text" && type !== "reasoning") return void 0;
+			return this.assemble(partial, index);
+		}).filter((block) => (block?.type === "text" || block?.type === "reasoning") && block.text.trim() !== "");
+	}
 	/** Usage from the `usage` chunk; undefined until one arrives. */
 	get usage() {
 		return this._usage;
@@ -940,6 +1114,21 @@ var LlmAdapter = class {
 			name: model
 		});
 	}
+	/**
+	* Bind exact model metadata and the eventual request dispatch to one adapter generation.
+	* Dynamic adapters override this so settings changes between preparation and
+	* dispatch cannot combine one generation's capabilities with another's endpoint.
+	* @param provider - registered provider route.
+	* @param model - exact model id.
+	* @param signal - cancellation for model resolution.
+	* @returns model metadata and a one-generation stream entry point.
+	*/
+	async prepareCall(provider, model, signal) {
+		return {
+			model: await this.resolveModel(provider, model, signal),
+			stream: (options) => this.stream(options)
+		};
+	}
 };
 /**
 * The abstract `llm` service: an adapter registry plus a streaming model-call
@@ -1209,8 +1398,12 @@ var LlmRuntime = class extends Service {
 		return this.resolveModelInfoFor(this.registration(provider), model, signal);
 	}
 	async resolveModelInfoFor(registration, model, signal) {
+		const resolved = await registration.adapter.resolveModel(registration.provider.id, model, signal);
+		return this.normalizeModelInfo(registration, model, resolved);
+	}
+	/** Validate and detach one adapter-returned exact model result. */
+	normalizeModelInfo(registration, model, resolved) {
 		const provider = registration.provider.id;
-		const resolved = await registration.adapter.resolveModel(provider, model, signal);
 		if (typeof resolved.provider !== "string" || resolved.provider !== provider || typeof resolved.id !== "string" || resolved.id !== model || typeof resolved.name !== "string" || resolved.name.length === 0 || resolved.description !== void 0 && typeof resolved.description !== "string") throw new LlmError(`adapter returned invalid exact model metadata for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
 		const context = resolved.context;
 		if (context !== void 0 && (!Number.isInteger(context.contextWindow) || context.contextWindow <= 0)) throw new LlmError(`adapter returned invalid context metadata for provider "${provider}" model "${model}"`, "INVALID_MODEL_CONTEXT");
@@ -1263,6 +1456,10 @@ var LlmRuntime = class extends Service {
 	}
 	async resolveCallFor(registration, config, signal) {
 		const info = await this.resolveModelInfoFor(registration, config.model, signal);
+		return this.resolveCallWithInfo(config, info);
+	}
+	/** Validate request controls against one already-bound exact model result. */
+	resolveCallWithInfo(config, info) {
 		const defaulted = config.maxTokens === void 0 && info.defaultMaxTokens !== void 0 ? {
 			...config,
 			maxTokens: info.defaultMaxTokens
@@ -1284,7 +1481,8 @@ var LlmRuntime = class extends Service {
 		}
 		return {
 			config: resolvedConfig,
-			...info.context === void 0 ? {} : { context: info.context }
+			...info.context === void 0 ? {} : { context: info.context },
+			modelInfo: info
 		};
 	}
 	/**
@@ -1297,7 +1495,9 @@ var LlmRuntime = class extends Service {
 	*/
 	async prepareCall(config, signal) {
 		const registration = this.registration(config.provider);
-		const resolved = await this.resolveCallFor(registration, config, signal);
+		const adapterCall = await registration.adapter.prepareCall(config.provider, config.model, signal);
+		const modelInfo = this.normalizeModelInfo(registration, config.model, adapterCall.model);
+		const resolved = this.resolveCallWithInfo(config, modelInfo);
 		const resolvedConfig = deepFreeze(structuredClone(resolved.config));
 		const context = resolved.context === void 0 ? void 0 : deepFreeze(structuredClone(resolved.context));
 		const adapterDefaults = deepFreeze({
@@ -1310,13 +1510,16 @@ var LlmRuntime = class extends Service {
 			retryPolicy: registration.retryPolicy,
 			adapterDefaults,
 			...context === void 0 ? {} : { context },
+			...modelInfo.inputModalities === void 0 ? {} : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
 			stream: (options) => {
 				if (dispatched) throw new LlmError("a prepared LLM call can only be dispatched once", "INVALID_PREPARED_CALL");
 				if (!callConfigEquals(options, resolvedConfig)) throw new LlmError("prepared LLM call config changed before adapter dispatch", "INVALID_PREPARED_CALL");
 				dispatched = true;
 				return this.streamWithRegistration(options, {
 					registration,
-					config: resolvedConfig
+					config: resolvedConfig,
+					modelInfo,
+					dispatch: (options) => adapterCall.stream(options)
 				});
 			}
 		});
@@ -1357,7 +1560,20 @@ var LlmRuntime = class extends Service {
 		let iterator;
 		try {
 			const registration = prepared?.registration ?? this.registration(options.provider);
-			const resolvedConfig = prepared === void 0 ? (await this.resolveCallFor(registration, options, options.signal)).config : prepared.config;
+			const adapter = registration.adapter;
+			let modelInfo;
+			let resolvedConfig;
+			let dispatch;
+			if (prepared === void 0) {
+				const adapterCall = await adapter.prepareCall(options.provider, options.model, options.signal);
+				modelInfo = this.normalizeModelInfo(registration, options.model, adapterCall.model);
+				resolvedConfig = this.resolveCallWithInfo(options, modelInfo).config;
+				dispatch = (options) => adapterCall.stream(options);
+			} else {
+				modelInfo = prepared.modelInfo;
+				resolvedConfig = prepared.config;
+				dispatch = prepared.dispatch;
+			}
 			if (prepared !== void 0 && !callConfigEquals(options, resolvedConfig)) throw new LlmError("prepared LLM call config changed before adapter dispatch", "INVALID_PREPARED_CALL");
 			const resolvedOptions = callConfigEquals(options, resolvedConfig) ? options : Object.isFrozen(options) ? deepFreeze({
 				...options,
@@ -1366,8 +1582,14 @@ var LlmRuntime = class extends Service {
 				...options,
 				...resolvedConfig
 			};
-			const adapter = registration.adapter;
-			iterator = adapter.stream(this.forAdapter(resolvedOptions, adapter))[Symbol.asyncIterator]();
+			const projectedOptions = modelInfo.inputModalities !== void 0 && !modelInfo.inputModalities.includes("image") && resolvedOptions.messages.some((message) => contentHasImage(message.content)) ? Object.isFrozen(resolvedOptions) ? deepFreeze({
+				...resolvedOptions,
+				messages: projectImagesForTextModel(resolvedOptions.messages)
+			}) : {
+				...resolvedOptions,
+				messages: projectImagesForTextModel(resolvedOptions.messages)
+			} : resolvedOptions;
+			iterator = dispatch(this.forAdapter(projectedOptions, adapter))[Symbol.asyncIterator]();
 		} catch (error) {
 			yield adapterFailureChunk(error, options.signal);
 			return;
@@ -1433,4 +1655,4 @@ function adapterFailureChunk(error, signal) {
 	};
 }
 //#endregion
-export { APP_IDENTITY, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, HarnessError, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertNever, assertUsableApiKey, attributionHeaders, boundContextSummary, callConfigEquals, contentHasImage, createAssistantMessage, createMessage, createToolResultMessage, createUserMessage, deepFreeze, errorChain, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, markAgentLoopRequest, normalizeApiKey, resolveRetryPolicy, userAgent };
+export { APP_IDENTITY, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, HarnessError, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, LlmRuntime, LlmRuntime as default, MessageId, OFFLOADED_IMAGE_TEXT, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertNever, assertUsableApiKey, attributionHeaders, boundContextSummary, callConfigEquals, contentHasImage, createAssistantMessage, createMessage, createToolResultMessage, createUserMessage, deepFreeze, errorChain, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, markAgentLoopRequest, normalizeApiKey, offloadRequestImages, offloadRequestImagesWithPolicy, projectImagesForTextModel, requestImageHandleText, resolveRetryPolicy, textOnlyImageText, userAgent };

package/dist/kernel/llm/lib/types/assembler.d.ts

@@ -12,7 +12,8 @@ import type { ContentBlock, FinishReason, ReplayEnvelope, StreamChunk, TokenUsag
  * {@link ContentBlock}s and a final assistant {@link Message}.
  *
  * The agent loop feeds it while logging raw chunks for replay fidelity, then
- * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
  *
  * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
  * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -46,6 +47,14 @@ export declare class BlockAssembler {
      *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
      */
     blocks(): ContentBlock[];
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks(): ContentBlock[];
     /** Usage from the `usage` chunk; undefined until one arrives. */
     get usage(): TokenUsage | undefined;
     /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */

package/dist/kernel/llm/lib/types/assembler.js

@@ -13,7 +13,8 @@ import { createMessage } from "./message.js";
  * {@link ContentBlock}s and a final assistant {@link Message}.
  *
  * The agent loop feeds it while logging raw chunks for replay fidelity, then
- * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
  *
  * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
  * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -144,6 +145,24 @@ export class BlockAssembler {
     blocks() {
         return this.assembled().blocks;
     }
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks() {
+        return this.order
+            .map((index) => {
+            const partial = this.mustGet(index);
+            const type = partial.block?.type ?? partial.blockType;
+            if (type !== 'text' && type !== 'reasoning')
+                return undefined;
+            return this.assemble(partial, index);
+        })
+            .filter((block) => (block?.type === 'text' || block?.type === 'reasoning') && block.text.trim() !== '');
+    }
     /** Usage from the `usage` chunk; undefined until one arrives. */
     get usage() {
         return this._usage;

package/dist/kernel/llm/lib/types/content.d.ts

@@ -1,5 +1,21 @@
 /** Content-block structure helpers. @module @nomix-ai/nomix-llm/content */
 import type { ContentBlock } from './types.ts';
+import type { Message } from './message.ts';
+import type { ImageAttachmentRef, RequestImageAttachment } from '../../../attachment/lib/index.js';
+/** Model-facing stand-in for an image removed to fit a provider request bound. */
+export declare const OFFLOADED_IMAGE_TEXT = "[image omitted to keep the request within its image limit; older images are omitted first. If this image is still needed, read its file again when a path is available; otherwise ask the user to attach it again.]";
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable master reference omitted from the request.
+ * @returns deterministic text-only placeholder.
+ */
+export declare function textOnlyImageText(ref: ImageAttachmentRef): string;
+/**
+ * Stable model-facing handle for one exact request image.
+ * @param version - exact request image shown beside the text.
+ * @returns attachment handle and request-image dimensions.
+ */
+export declare function requestImageHandleText(version: RequestImageAttachment): string;
 /**
  * True when typed model content contains an image block, walking nested
  * tool-result content. This is the one recursive image walk shared by every
@@ -9,4 +25,47 @@ import type { ContentBlock } from './types.ts';
  * @returns whether any nested block is an image.
  */
 export declare function contentHasImage(content: readonly ContentBlock[]): boolean;
+/** Byte accounting and quantized removal policy for one request representation. */
+export interface RequestImageOffloadPolicy {
+    /** Image count accepted by the route; omission leaves count unbounded. */
+    maxImages?: number;
+    /** Accumulated image bytes accepted by the route; omission leaves bytes unbounded. */
+    maxBytes?: number;
+    /** Number of excess images removed as one deterministic step. */
+    countQuantum?: number;
+    /** Number of excess bytes removed as one deterministic step. */
+    byteQuantum?: number;
+    /** Whether byte accounting uses raw file bytes or inline base64 length. */
+    representation: 'raw' | 'base64';
+    /** Resolve the encoded request-version length; omission uses master attachment bytes. */
+    byteLength?: (ref: ImageAttachmentRef) => number;
+}
+/**
+ * Project durable image history into deterministic text for an exact text-only model.
+ * @param messages - complete request history.
+ * @returns the original list without images, otherwise shallow message copies with stable placeholders.
+ */
+export declare function projectImagesForTextModel(messages: readonly Message[]): readonly Message[];
+/**
+ * Return transient request messages whose oldest images are replaced until
+ * their accumulated base64 payload fits the configured bound. The selection
+ * is deterministic from durable message order and attachment metadata; a
+ * provider can serialize the returned messages without reading omitted bytes.
+ * @param messages - complete request history, oldest first.
+ * @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+ * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+ */
+export declare function offloadRequestImages(messages: readonly Message[], maxRequestImageBytes: number | undefined): readonly Message[];
+/**
+ * Return a deterministic transient projection whose oldest images are replaced
+ * in whole count and byte quanta after a route budget is exceeded. The target
+ * depends only on complete durable history: at 129 one-megabyte images under
+ * a 128 MiB bound with a 64 MiB quantum, the oldest 65 images are removed so
+ * 64 MiB remain; that removed prefix stays fixed until total history exceeds
+ * 192 MiB.
+ * @param messages - complete request history, oldest first.
+ * @param policy - route representation, budgets, and removal quanta.
+ * @returns original messages below both bounds, otherwise shallow copies with deterministic placeholders.
+ */
+export declare function offloadRequestImagesWithPolicy(messages: readonly Message[], policy: RequestImageOffloadPolicy): readonly Message[];
 //# sourceMappingURL=content.d.ts.map

package/dist/kernel/llm/lib/types/content.js

@@ -1,4 +1,23 @@
 /** Content-block structure helpers. @module @nomix-ai/nomix-llm/content */
+/** Model-facing stand-in for an image removed to fit a provider request bound. */
+export const OFFLOADED_IMAGE_TEXT = '[image omitted to keep the request within its image limit; older images are omitted first. If this image is still needed, read its file again when a path is available; otherwise ask the user to attach it again.]';
+/**
+ * Stable text shown to a model that cannot accept one durable image reference.
+ * @param ref - durable master reference omitted from the request.
+ * @returns deterministic text-only placeholder.
+ */
+export function textOnlyImageText(ref) {
+    const digest = String(ref.attachmentId).slice('sha256:'.length, 'sha256:'.length + 8);
+    return `[image omitted because this model accepts text only; attachment sha256:${digest}]`;
+}
+/**
+ * Stable model-facing handle for one exact request image.
+ * @param version - exact request image shown beside the text.
+ * @returns attachment handle and request-image dimensions.
+ */
+export function requestImageHandleText(version) {
+    return `Image ${version.attachment.attachmentId}; request image ${version.width}x${version.height}px.`;
+}
 /**
  * True when typed model content contains an image block, walking nested
  * tool-result content. This is the one recursive image walk shared by every
@@ -11,4 +30,134 @@ export function contentHasImage(content) {
     return content.some(block => block.type === 'image'
         || (block.type === 'tool-result' && contentHasImage(block.content)));
 }
+/** Base64 length of raw image bytes, including padding. */
+function base64Length(bytes) {
+    return Math.ceil(bytes / 3) * 4;
+}
+/** Collect represented image lengths in request and nested-block order. */
+function collectImageLengths(blocks, lengths, policy) {
+    for (const block of blocks) {
+        if (block.type === 'image') {
+            const bytes = policy.byteLength === undefined
+                ? block.attachment.bytes
+                : policy.byteLength(block.attachment);
+            lengths.push(policy.representation === 'base64' ? base64Length(bytes) : bytes);
+        }
+        else if (block.type === 'tool-result') {
+            collectImageLengths(block.content, lengths, policy);
+        }
+    }
+}
+/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
+function replaceOldestImages(blocks, remaining) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image' && remaining.count > 0) {
+            remaining.count -= 1;
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: OFFLOADED_IMAGE_TEXT });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceOldestImages(block.content, remaining);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/** Replace every image occurrence, including nested tool results, for a text-only model. */
+function replaceImagesForTextModel(blocks) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image') {
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: textOnlyImageText(block.attachment) });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceImagesForTextModel(block.content);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/**
+ * Project durable image history into deterministic text for an exact text-only model.
+ * @param messages - complete request history.
+ * @returns the original list without images, otherwise shallow message copies with stable placeholders.
+ */
+export function projectImagesForTextModel(messages) {
+    if (!messages.some(message => contentHasImage(message.content)))
+        return messages;
+    return messages.map((message) => {
+        const content = replaceImagesForTextModel(message.content);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+/**
+ * Return transient request messages whose oldest images are replaced until
+ * their accumulated base64 payload fits the configured bound. The selection
+ * is deterministic from durable message order and attachment metadata; a
+ * provider can serialize the returned messages without reading omitted bytes.
+ * @param messages - complete request history, oldest first.
+ * @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+ * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+ */
+export function offloadRequestImages(messages, maxRequestImageBytes) {
+    return offloadRequestImagesWithPolicy(messages, {
+        representation: 'base64',
+        ...maxRequestImageBytes === undefined ? {} : { maxBytes: maxRequestImageBytes },
+        byteQuantum: 1,
+    });
+}
+/**
+ * Return a deterministic transient projection whose oldest images are replaced
+ * in whole count and byte quanta after a route budget is exceeded. The target
+ * depends only on complete durable history: at 129 one-megabyte images under
+ * a 128 MiB bound with a 64 MiB quantum, the oldest 65 images are removed so
+ * 64 MiB remain; that removed prefix stays fixed until total history exceeds
+ * 192 MiB.
+ * @param messages - complete request history, oldest first.
+ * @param policy - route representation, budgets, and removal quanta.
+ * @returns original messages below both bounds, otherwise shallow copies with deterministic placeholders.
+ */
+export function offloadRequestImagesWithPolicy(messages, policy) {
+    const lengths = [];
+    for (const message of messages)
+        collectImageLengths(message.content, lengths, policy);
+    const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+    const excessCount = policy.maxImages === undefined ? 0 : Math.max(0, lengths.length - policy.maxImages);
+    const excessBytes = policy.maxBytes === undefined ? 0 : Math.max(0, total - policy.maxBytes);
+    if (excessCount === 0 && excessBytes === 0)
+        return messages;
+    const countQuantum = policy.countQuantum ?? 1;
+    const byteQuantum = policy.byteQuantum ?? 1;
+    const removeCount = excessCount === 0 ? 0 : Math.ceil(excessCount / countQuantum) * countQuantum;
+    const removeBytes = excessBytes === 0 ? 0 : Math.ceil(excessBytes / byteQuantum) * byteQuantum;
+    let count = 0;
+    let removedBytes = 0;
+    for (const imageBytes of lengths) {
+        const byteTargetMet = removeBytes === 0
+            || (byteQuantum === 1 ? removedBytes >= removeBytes : removedBytes > removeBytes);
+        if (count >= removeCount && byteTargetMet)
+            break;
+        removedBytes += imageBytes;
+        count += 1;
+    }
+    const remaining = { count };
+    return messages.map((message) => {
+        const content = replaceOldestImages(message.content, remaining);
+        return content === message.content ? message : { ...message, content };
+    });
+}
 //# sourceMappingURL=content.js.map