@deepseek-ai/dsh-llm 0.1.1-rc.2 → 0.1.2-alpha.2

package/lib/typert.remote-client.js

@@ -0,0 +1,102 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+const _deepseek_ai_dsh_llm_llm_discoverModels_parameter_0$schema = z.string()
+const _deepseek_ai_dsh_llm_llm_discoverModels_parameter_1$schema = z.object({
+  'provider': z.string().optional(),
+  'baseURL': z.string().optional(),
+  'api': z.string().optional(),
+  'apiKey': z.string().optional(),
+})
+const _deepseek_ai_dsh_llm_llm_discoverModels_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string().optional(),
+  'contextWindow': z.number().optional(),
+  'maxTokens': z.number().optional(),
+}))
+const _deepseek_ai_dsh_llm_llm_listConfigurableProviders_result$schema = z.array(z.object({
+  'provider': z.string(),
+  'displayName': z.string(),
+  'settingsNs': z.string(),
+  'settingsPath': z.array(z.string()),
+  'declared': z.boolean().optional(),
+}))
+const _deepseek_ai_dsh_llm_llm_listProviders_result$schema = z.array(z.object({
+  'id': z.string(),
+  'name': z.string(),
+}))
+
+export const TYPERT_REMOTE = {
+  package: '@deepseek-ai/dsh-llm',
+  descriptors: [
+    {
+      id: '@deepseek-ai/dsh-llm#llm/discoverModels',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'discoverModels',
+      implementation: 'remoteDiscoverModels',
+      invocation: { kind: 'direct' },
+      parameters: [
+        {
+          name: 'settingsNs',
+          wire: 'settingsNs',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-llm#llm/discoverModels:settingsNs',
+            schema: _deepseek_ai_dsh_llm_llm_discoverModels_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@deepseek-ai/dsh-llm/types#LlmModelDiscoveryRequest',
+            schema: _deepseek_ai_dsh_llm_llm_discoverModels_parameter_1$schema,
+          },
+        },
+      ],
+      cancellation: { parameter: 'signal' },
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-llm#llm/discoverModels:result',
+        schema: _deepseek_ai_dsh_llm_llm_discoverModels_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":621,"column":9},
+    },
+    {
+      id: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listConfigurableProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders:result',
+        schema: _deepseek_ai_dsh_llm_llm_listConfigurableProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":534,"column":3},
+    },
+    {
+      id: '@deepseek-ai/dsh-llm#llm/listProviders',
+      service: 'llm',
+      namespace: 'llm',
+      method: 'listProviders',
+      invocation: { kind: 'direct' },
+      parameters: [
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@deepseek-ai/dsh-llm#llm/listProviders:result',
+        schema: _deepseek_ai_dsh_llm_llm_listProviders_result$schema,
+      },
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":462,"column":3},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/assembler.js

@@ -5,8 +5,8 @@
  *
  * @module @deepseek-ai/dsh-llm/assembler
  */
-import { CallId } from "./brand.js";
-import { assertNever } from "./never.js";
+import { brandString } from '@deepseek-ai/dsh-brand';
+import { assertNever } from '@deepseek-ai/dsh-util-values';
 import { createMessage } from "./message.js";
 /**
  * Incrementally assembles raw {@link StreamChunk}s into complete
@@ -99,7 +99,7 @@ export class BlockAssembler {
             case 'reasoning': return { type: 'reasoning', text: partial.text };
             case 'tool-call': return {
                 type: 'tool-call',
-                id: partial.toolCallId ?? CallId(`call-${index}`),
+                id: partial.toolCallId ?? brandString(`call-${index}`),
                 name: partial.toolCallName ?? '',
                 arguments: partial.toolCallArguments,
             };

package/lib/types/brand.d.ts

@@ -2,33 +2,33 @@
  * dsh-llm's owned branded ids: tool-call correlation and provider request
  * diagnostics.
  *
- * The `Branded<B>` primitive itself lives in `@deepseek-ai/dsh-brand` (a
- * zero-dependency type-only package) so every owner of a cross-boundary id can
- * brand it without depending on dsh-llm; see that package's README for the
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@deepseek-ai/dsh-brand` so every owner of a cross-boundary id can brand it
+ * without depending on dsh-llm; see that package's README for the
  * nominal-typing policy.
  *
  * @module @deepseek-ai/dsh-llm/brand
  */
-import type { Branded } from '@deepseek-ai/dsh-brand';
+import { type Branded } from '@deepseek-ai/dsh-brand';
 /** Stable identity carried by one message across inbox, log, and model-request boundaries. */
 export type MessageId = Branded<'MessageId'>;
 /**
  * Brand a message identifier.
  * @param id - the opaque message identifier.
- * @returns the same string, branded; no validation is performed.
+ * @returns the same string with the message-id brand.
  */
 export declare function MessageId(id: string): MessageId;
 /**
  * Correlates a model-issued tool call with its result. Provider-issued for
  * real adapters; synthesized by mocks/assembler fallbacks.
  */
-export type CallId = Branded<'CallId'>;
+export type ToolCallId = Branded<'ToolCallId'>;
 /**
- * Brand a string as a {@link CallId}.
- * @param id - the provider-issued (or synthesized) call id.
- * @returns the same string, branded; no validation is performed.
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
  */
-export declare function CallId(id: string): CallId;
+export declare function ToolCallId(id: string): ToolCallId;
 /** Provider-issued request identifier retained for diagnostics across package boundaries. */
 export type ProviderRequestId = Branded<'ProviderRequestId'>;
 /**

package/lib/types/brand.js

@@ -2,28 +2,29 @@
  * dsh-llm's owned branded ids: tool-call correlation and provider request
  * diagnostics.
  *
- * The `Branded<B>` primitive itself lives in `@deepseek-ai/dsh-brand` (a
- * zero-dependency type-only package) so every owner of a cross-boundary id can
- * brand it without depending on dsh-llm; see that package's README for the
+ * The `Branded<B>` primitive and stateless constructor live in
+ * `@deepseek-ai/dsh-brand` so every owner of a cross-boundary id can brand it
+ * without depending on dsh-llm; see that package's README for the
  * nominal-typing policy.
  *
  * @module @deepseek-ai/dsh-llm/brand
  */
+import { brandString } from '@deepseek-ai/dsh-brand';
 /**
  * Brand a message identifier.
  * @param id - the opaque message identifier.
- * @returns the same string, branded; no validation is performed.
+ * @returns the same string with the message-id brand.
  */
 export function MessageId(id) {
-    return id;
+    return brandString(id);
 }
 /**
- * Brand a string as a {@link CallId}.
- * @param id - the provider-issued (or synthesized) call id.
- * @returns the same string, branded; no validation is performed.
+ * Brand a string as a {@link ToolCallId}.
+ * @param id - the provider-issued or synthesized call id.
+ * @returns the same string with the tool-call-id brand.
  */
-export function CallId(id) {
-    return id;
+export function ToolCallId(id) {
+    return brandString(id);
 }
 /**
  * Brand a provider-issued request identifier.
@@ -31,7 +32,7 @@ export function CallId(id) {
  * @returns the same string, branded; no validation is performed.
  */
 export function ProviderRequestId(id) {
-    return id;
+    return brandString(id);
 }
 /**
  * Brand an adapter-owned reasoning-effort identifier.
@@ -39,6 +40,6 @@ export function ProviderRequestId(id) {
  * @returns the same string, branded; no validation is performed.
  */
 export function ReasoningEffortId(id) {
-    return id;
+    return brandString(id);
 }
 //# sourceMappingURL=brand.js.map

package/lib/types/call-config.d.ts

@@ -50,13 +50,4 @@ export declare function markAgentLoopRequest<T extends GenerateOptions>(request:
  * @returns whether {@link markAgentLoopRequest} recorded this object.
  */
 export declare function isAgentLoopRequest(request: GenerateOptions): boolean;
-/**
- * Deep-freeze a value in place with an iterative traversal, guarding cycles,
- * so later mutation throws without imposing a JavaScript call-stack depth cap.
- * {@link AbortSignal} objects are deliberately skipped because they are the
- * request's live cancellation channel and freezing them breaks abort.
- * @param value - the value to freeze in place.
- * @returns the same value, frozen.
- */
-export declare function deepFreeze<T>(value: T): T;
 //# sourceMappingURL=call-config.d.ts.map

package/lib/types/call-config.js

@@ -43,44 +43,4 @@ export function markAgentLoopRequest(request) {
 export function isAgentLoopRequest(request) {
     return AGENT_LOOP_REQUESTS.has(request);
 }
-/**
- * Deep-freeze a value in place with an iterative traversal, guarding cycles,
- * so later mutation throws without imposing a JavaScript call-stack depth cap.
- * {@link AbortSignal} objects are deliberately skipped because they are the
- * request's live cancellation channel and freezing them breaks abort.
- * @param value - the value to freeze in place.
- * @returns the same value, frozen.
- */
-export function deepFreeze(value) {
-    const seen = new WeakSet();
-    const pending = [{ kind: 'visit', node: value }];
-    while (pending.length > 0) {
-        const task = pending.pop();
-        /* v8 ignore next -- the loop condition guarantees one pending task. */
-        if (task === undefined)
-            continue;
-        if (task.kind === 'property') {
-            pending.push({ kind: 'visit', node: task.source[task.key] });
-            continue;
-        }
-        const node = task.node;
-        if (node === null || typeof node !== 'object')
-            continue;
-        if (node instanceof AbortSignal)
-            continue;
-        if (seen.has(node))
-            continue;
-        seen.add(node);
-        Object.freeze(node);
-        const keys = Object.keys(node);
-        for (let index = keys.length - 1; index >= 0; index--) {
-            const key = keys[index];
-            /* v8 ignore next -- the loop is bounded by the captured key count. */
-            if (key === undefined)
-                continue;
-            pending.push({ kind: 'property', source: node, key });
-        }
-    }
-    return value;
-}
 //# sourceMappingURL=call-config.js.map

package/lib/types/content.d.ts

@@ -1,21 +1,53 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-llm/content */
 import type { ContentBlock } from './types.ts';
 import type { Message } from './message.ts';
-import type { ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
-/** 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.]";
+import type { AttachmentStore, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
+/** Execution-world path that model tools can use to read one normalized attachment. */
+export interface ImageAttachmentAccess {
+    /** Absolute path to immutable normalized bytes; callers must treat it as read-only. */
+    readonlyPath: string;
+}
+/**
+ * Resolve current execution-world access for one durable image reference.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when unavailable.
+ */
+export type ImageAttachmentAccessResolver = (ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+/**
+ * Bridge one attachment provider's host object location into the mounted
+ * tool execution world. The consumer supplies the current filesystem
+ * provider's mapping without making attachment or LLM definitions depend on it.
+ * @param attachments - provider that owns the normalized attachment object.
+ * @param mapHostPath - map one absolute host path into the current tool execution world.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when either provider exposes no mapping.
+ * @throws an attachment error when the durable reference is invalid.
+ */
+export declare function resolveImageAttachmentAccess(attachments: AttachmentStore, mapHostPath: (hostPath: string) => string | undefined, ref: ImageAttachmentRef): ImageAttachmentAccess | undefined;
 /**
  * Stable text shown to a model that cannot accept one durable image reference.
- * @param ref - durable master reference omitted from the request.
+ * @param ref - durable normalized attachment 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.
+ * Stable model-facing handle for one exact request image. Identity comes from
+ * the occurrence's own durable reference: request versions are prepared per
+ * attachment id, so one shared version may serve occurrences whose display
+ * names differ.
+ * @param ref - the occurrence's durable normalized attachment.
+ * @param version - exact request-image dimensions shown beside the text.
+ * @param access - optional path resolved for the current tool execution world.
  * @returns attachment handle and request-image dimensions.
  */
-export declare function requestImageHandleText(version: RequestImageAttachment): string;
+export declare function requestImageHandleText(ref: ImageAttachmentRef, version: Pick<RequestImageAttachment, 'width' | 'height'>, access?: ImageAttachmentAccess): string;
+/**
+ * Stable per-image placeholder for a request-limit omission.
+ * @param ref - durable normalized attachment omitted from this request.
+ * @param access - optional provider-resolved path for model tools.
+ * @returns identity, normalized metadata, and the available recovery path.
+ */
+export declare function offloadedImageText(ref: ImageAttachmentRef, access?: ImageAttachmentAccess): 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
@@ -37,8 +69,10 @@ export interface RequestImageOffloadPolicy {
     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. */
+    /** Resolve the encoded request-version length; omission uses normalized attachment bytes. */
     byteLength?: (ref: ImageAttachmentRef) => number;
+    /** Build the model-visible replacement for each omitted attachment. */
+    placeholder: (ref: ImageAttachmentRef) => string;
 }
 /**
  * Project durable image history into deterministic text for an exact text-only model.
@@ -47,15 +81,15 @@ export interface RequestImageOffloadPolicy {
  */
 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.
+ * Number of oldest image occurrences one request projection removes, in whole
+ * count and byte quanta, once a route budget is exceeded. The result depends
+ * only on the represented lengths, so provider request pricing reproduces the
+ * exact serialization decision without building the projected messages.
+ * @param lengths - represented byte length of every occurrence, in request order.
+ * @param policy - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences the projection replaces with placeholders.
  */
-export declare function offloadRequestImages(messages: readonly Message[], maxRequestImageBytes: number | undefined): readonly Message[];
+export declare function offloadedImagePrefixCount(lengths: readonly number[], policy: Pick<RequestImageOffloadPolicy, 'maxImages' | 'maxBytes' | 'countQuantum' | 'byteQuantum'>): number;
 /**
  * Return a deterministic transient projection whose oldest images are replaced
  * in whole count and byte quanta after a route budget is exceeded. The target

package/lib/types/content.js

@@ -1,9 +1,47 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-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.]';
+import { assertNever } from '@deepseek-ai/dsh-util-values';
+/**
+ * Bridge one attachment provider's host object location into the mounted
+ * tool execution world. The consumer supplies the current filesystem
+ * provider's mapping without making attachment or LLM definitions depend on it.
+ * @param attachments - provider that owns the normalized attachment object.
+ * @param mapHostPath - map one absolute host path into the current tool execution world.
+ * @param ref - durable normalized attachment reference.
+ * @returns a read-only execution-world path, or undefined when either provider exposes no mapping.
+ * @throws an attachment error when the durable reference is invalid.
+ */
+export function resolveImageAttachmentAccess(attachments, mapHostPath, ref) {
+    const hostPath = attachments.imageHostPath(ref);
+    if (hostPath === undefined)
+        return undefined;
+    const readonlyPath = mapHostPath(hostPath);
+    return readonlyPath === undefined ? undefined : { readonlyPath };
+}
+function quoted(value) {
+    return JSON.stringify(value);
+}
+function imageIdentity(ref) {
+    return ref.name === undefined
+        ? String(ref.attachmentId)
+        : `${quoted(ref.name)} (${ref.attachmentId})`;
+}
+function extension(mediaType) {
+    switch (mediaType) {
+        case 'image/png': return '.png';
+        case 'image/jpeg': return '.jpg';
+        case 'image/webp': return '.webp';
+        case 'image/gif': return '.gif';
+        default: return assertNever(mediaType, 'image extension');
+    }
+}
+function normalizedAccessText(ref, access) {
+    return ` Normalized copy (read-only; may be resized or re-encoded): ${quoted(access.readonlyPath)} (${ref.width}x${ref.height}px, ${ref.mediaType}).`
+        + ' Source dimensions, format, and byte size may differ.'
+        + ` Copy to a writable path ending in ${extension(ref.mediaType)} before editing.`;
+}
 /**
  * Stable text shown to a model that cannot accept one durable image reference.
- * @param ref - durable master reference omitted from the request.
+ * @param ref - durable normalized attachment omitted from the request.
  * @returns deterministic text-only placeholder.
  */
 export function textOnlyImageText(ref) {
@@ -11,12 +49,33 @@ export function textOnlyImageText(ref) {
     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.
+ * Stable model-facing handle for one exact request image. Identity comes from
+ * the occurrence's own durable reference: request versions are prepared per
+ * attachment id, so one shared version may serve occurrences whose display
+ * names differ.
+ * @param ref - the occurrence's durable normalized attachment.
+ * @param version - exact request-image dimensions shown beside the text.
+ * @param access - optional path resolved for the current tool execution world.
  * @returns attachment handle and request-image dimensions.
  */
-export function requestImageHandleText(version) {
-    return `Image ${version.attachment.attachmentId}; request image ${version.width}x${version.height}px.`;
+export function requestImageHandleText(ref, version, access) {
+    const preview = `Image ${imageIdentity(ref)}; request preview ${version.width}x${version.height}px.`;
+    return access === undefined
+        ? `${preview} It may be resized or re-encoded; source dimensions, format, and byte size may differ.`
+        : preview + normalizedAccessText(ref, access);
+}
+/**
+ * Stable per-image placeholder for a request-limit omission.
+ * @param ref - durable normalized attachment omitted from this request.
+ * @param access - optional provider-resolved path for model tools.
+ * @returns identity, normalized metadata, and the available recovery path.
+ */
+export function offloadedImageText(ref, access) {
+    const identity = `image omitted to fit request image limits; ${imageIdentity(ref)}.`;
+    if (access === undefined) {
+        return `[${identity} No local normalized image path is available; ask the user to attach it again if needed.]`;
+    }
+    return `[${identity}${normalizedAccessText(ref, access)}]`;
 }
 /**
  * True when typed model content contains an image block, walking nested
@@ -49,17 +108,17 @@ function collectImageLengths(blocks, lengths, policy) {
     }
 }
 /** Replace the first `remaining.count` image occurrences without mutating durable messages. */
-function replaceOldestImages(blocks, remaining) {
+function replaceOldestImages(blocks, remaining, placeholder) {
     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 });
+            next.push({ type: 'text', text: placeholder(block.attachment) });
             continue;
         }
         if (block.type === 'tool-result') {
-            const content = replaceOldestImages(block.content, remaining);
+            const content = replaceOldestImages(block.content, remaining, placeholder);
             if (content !== block.content) {
                 next ??= blocks.slice(0, index);
                 next.push({ ...block, content });
@@ -105,41 +164,20 @@ export function projectImagesForTextModel(messages) {
     });
 }
 /**
- * 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.
+ * Number of oldest image occurrences one request projection removes, in whole
+ * count and byte quanta, once a route budget is exceeded. The result depends
+ * only on the represented lengths, so provider request pricing reproduces the
+ * exact serialization decision without building the projected messages.
+ * @param lengths - represented byte length of every occurrence, in request order.
+ * @param policy - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences the projection replaces with placeholders.
  */
-export function offloadRequestImagesWithPolicy(messages, policy) {
-    const lengths = [];
-    for (const message of messages)
-        collectImageLengths(message.content, lengths, policy);
+export function offloadedImagePrefixCount(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;
+        return 0;
     const countQuantum = policy.countQuantum ?? 1;
     const byteQuantum = policy.byteQuantum ?? 1;
     const removeCount = excessCount === 0 ? 0 : Math.ceil(excessCount / countQuantum) * countQuantum;
@@ -154,9 +192,29 @@ export function offloadRequestImagesWithPolicy(messages, policy) {
         removedBytes += imageBytes;
         count += 1;
     }
+    return count;
+}
+/**
+ * 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 count = offloadedImagePrefixCount(lengths, policy);
+    if (count === 0)
+        return messages;
     const remaining = { count };
     return messages.map((message) => {
-        const content = replaceOldestImages(message.content, remaining);
+        const content = replaceOldestImages(message.content, remaining, policy.placeholder);
         return content === message.content ? message : { ...message, content };
     });
 }