@deepseek-ai/dsh-llm 0.1.5-rc.1 → 0.1.6-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/llm/llm/README.md
-README.md: 75a5d3e1d51ada12338a41e54b42ad8d6d21c279
-README.zh.md: e10706108d86f337c333b1f80a15c731fd2a00cf
+README.md: 8e4e547190a039959f7db29898945f2ed68ff874
+README.zh.md: 9164f4a6e6107e439b732539cddeb14716bc3fdc

package/README.md

@@ -95,13 +95,13 @@ The service is built on one separation: **the logical contract is provider-neutr
 | [`src/call-config.ts`](src/call-config.ts) | Call-config validation, adapter-default materialization, and request freezing |
 | [`src/retry-policy.ts`](src/retry-policy.ts) | Provider-owned retry policy resolution (normal and always modes) |
 | [`src/error.ts`](src/error.ts) | `HarnessError`/`LlmError` taxonomy and provider-neutral failure codes |
-| [`src/content.ts`](src/content.ts) | Shared file and image projection helpers, including request-image offloading |
+| [`src/content.ts`](src/content.ts) | Shared file and image helpers: content walks, file projection, image offload accounting, and offloaded-image projection |
 | [`src/api-key.ts`](src/api-key.ts) | Credential format check shared by every adapter |
 | [`src/adapter-failure.ts`](src/adapter-failure.ts) | Failure normalization into terminal finish chunks |
 
 ### Main flow
 
-A request is validated against its exact model's capability — context window, output default, reasoning efforts, input modalities, and `systemPromptUpdate` mode — and any adapter-configured defaults are materialized, then the whole request is deep-frozen. `prepareCall()` binds those facts, detached context, and retry policy to the exact adapter generation that performs terminal dispatch, so HMR or dynamic settings cannot combine one generation's image capability with another generation's endpoint. An image-capable adapter projects durable references into route-specific request versions; `resolveImageAttachmentAccess()` separately maps an attachment provider's optional host object into the current tool execution world without changing the request image or its `variantId`. A text-only route receives deterministic per-image placeholders, including nested tool-result images, without rewriting append-only session history. Durable `FileBlock` references never reach any adapter: request assembly replaces each one, nested tool-result occurrences included, with deterministic handle text naming the file and its saved read-only path, resolved through the mounted attachment and filesystem providers. `ctx.llm.fileRequestText(ref)` exposes that exact synchronous projection to request measurement. `offloadRequestImagesWithPolicy()` removes oldest images deterministically by raw or base64 size and count or byte quanta; the pure `offloadedImagePrefixCount()` exposes that decision so route-owned request pricing can reproduce it without building the projection. Adapters that charge visual tokens declare per-route `imageRequestPricing`, which `ctx.llm.imageRequestPricing(provider, model)` resolves synchronously for the token meter. Dispatch goes through the `llm/stream` waterfall, then chunks return as token-level deltas and every adapter outcome reaches the consumer as one terminal `finish` chunk.
+A request is validated against its exact model's capability — context window, output default, reasoning efforts, input modalities, and `systemPromptUpdate` mode — and any adapter-configured defaults are materialized, then the whole request is deep-frozen. `prepareCall()` binds those facts, detached context, and retry policy to the exact adapter generation that performs terminal dispatch, so HMR or dynamic settings cannot combine one generation's image capability with another generation's endpoint. An image-capable adapter projects durable references into route-specific request versions; `resolveImageAttachmentAccess()` separately maps an attachment provider's optional host object into the current tool execution world without changing the request image or its `variantId`. A text-only route receives deterministic per-image placeholders, including nested tool-result images, without rewriting append-only session history. Durable `FileBlock` references never reach any adapter: request assembly replaces each one, nested tool-result occurrences included, with deterministic handle text naming the file and its saved read-only path, resolved through the mounted attachment and filesystem providers. `ctx.llm.fileRequestText(ref)` exposes that exact synchronous projection to request measurement. An image occurrence derived with `offloaded: true` reaches every route as placeholder text through `projectOffloadedImages()`. An image-capable route whose retained occurrences exceed its `LlmImageRequestBudget` at their exact bytes fails with `IMAGE_OFFLOAD_REQUIRED` naming the additional oldest occurrences (`requiredImageOffload()`), never with an unlogged projection; `dsh-compaction-image-offload` logs the selected occurrences in one `image/offload` event and retries. Adapters that charge visual tokens declare per-route `imageRequestPricing`, which `ctx.llm.imageRequestPricing(provider, model)` resolves synchronously for the token meter. Dispatch goes through the `llm/stream` waterfall, then chunks return as token-level deltas and every adapter outcome reaches the consumer as one terminal `finish` chunk.
 
 File detection reads current content, including nested tool results, on every request without caching message identities or freeze state. The [file-scan decision](../../../.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md) records the measured traversal cost.
 
@@ -141,7 +141,7 @@ None, as the LLM service adds no content; adapters choose when to add the shared
 
 #### KV Cache effect
 
-Reasoning-effort materialization preserves the assembled request prefix. Image identity and request-preview text are deterministic, while an optional execution-world path is resolved for each request; a changed path or image-offload boundary can prevent reuse from that image.
+Reasoning-effort materialization preserves the assembled request prefix. Image identity and request-preview text are deterministic, while an optional execution-world path is resolved for each request; a changed path or an offload decision can prevent reuse from that image.
 
 ## Known Limitations and Deferred Work
 

package/README.zh.md

@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-任何调用模型提供方的组合——agent loop、会话标题生成器、压缩（compaction）摘要器——都会通过本服务流式发起请求。与至少一个提供方适配器一起挂载它；服务本身没有任何配置，也不包含提供方协议代码。
+任何调用模型提供方的组合——agent loop（智能体循环）、会话标题生成器、压缩（compaction）摘要器——都会通过本服务流式发起请求。与至少一个提供方适配器一起挂载它；服务本身没有任何配置，也不包含提供方协议代码。
 
 ### 何时选择
 
@@ -60,10 +60,10 @@ for await (const chunk of ctx.llm.stream({
 
 - **流式发起一次模型调用**——`ctx.llm.stream(options)` 为任何已注册提供方与模型产出原始分片（token 级增量）；消费方用 `BlockAssembler` 组装。
 - **注册提供方适配器**——一个适配器拥有一个或多个提供方路由，其注册会捕获该路由的重试策略；重复注册同一路由会以 `DUPLICATE_ADAPTER` 失败。
-- **通过配置暴露并激活提供方**——适配器声明可配置提供方路由与 settings namespace，配置界面因此可以激活休眠提供方并编辑连接事实，无需重启。`LlmConfigurableProvider.error` 报告供修复的配置诊断；未受影响的模型仍可提供服务。
+- **通过配置暴露并激活提供方**——适配器声明可配置提供方路由与 settings namespace，配置界面因此可以激活休眠提供方并编辑连接信息，无需重启。`LlmConfigurableProvider.error` 报告供修复的配置诊断；未受影响的模型仍可提供服务。
 - **发现与解析模型**——列出适配器公布的模型、询问端点它提供哪些模型，并解析某个精确模型的上下文窗口、输出默认值、推理（reasoning）强度、输入模态与系统提示词更新模式：当模型把任意位置最新的 `system` 消息读作有效系统提示词时，`LlmResolvedModelInfo.systemPromptUpdate` 为 `'in-history'`；只读取开头 system 消息时该字段缺失；`normalizeModelInfo` 以 `INVALID_MODEL_INFO` 拒绝任何其他值。
 - **校验调用配置**——显式或配置的推理强度会在任何提供方 I/O 之前对照精确模型校验；请求省略输出上限时，会填入适配器配置的输出上限。
-- **不展开即读取内嵌 Assistant 流**——`assistantStreamFirstTokenTime`（首 token）、`assistantStreamHasVisibleContent`（任一可见内容）与 `assistantStreamHasVisibleText`（任一可见文本）以提前退出从紧凑记录回答各自的问题；`lastAssistantStreamChunk` 反向扫描到某一类型的最后一个原始 chunk，`assistantStreamChunks` 与 `joinAssistantStreamText` 扫描整个流，`assembleAssistantStream` 向 `BlockAssembler` 每个 run 喂一段拼接 delta，blocks／usage／replayState 与逐成员展开相同。`runFirstTokenTime` 与 `runFirstVisibleTime` 对单个打包 run 做提前退出扫描，`isTokenDelta`、`isVisibleChunk` 与 `chunkHasVisibleText` 定义单个 chunk 的 token 与可见性规则。`expandAssistantStream` 仍是持久边界读取记录的校验路径；它不被记忆化，因为保留的展开在事件生命周期内约花费紧凑流的十倍内存。
+- **不展开即读取内嵌 Assistant 流**——`assistantStreamFirstTokenTime`（首 token）、`assistantStreamHasVisibleContent`（任一可见内容）与 `assistantStreamHasVisibleText`（任一可见文本）通过可提前退出的扫描直接从紧凑记录得出结果；`lastAssistantStreamChunk` 反向扫描到某一类型的最后一个原始 chunk，`assistantStreamChunks` 与 `joinAssistantStreamText` 扫描整个流，`assembleAssistantStream` 向 `BlockAssembler` 每个 run 喂一段拼接 delta，blocks／usage／replayState 与逐成员展开相同。`runFirstTokenTime` 与 `runFirstVisibleTime` 对单个打包 run 做提前退出扫描，`isTokenDelta`、`isVisibleChunk` 与 `chunkHasVisibleText` 定义单个 chunk 的 token 与可见性规则。`expandAssistantStream` 仍是持久边界读取记录的校验路径；它不被记忆化，因为保留的展开在事件生命周期内约花费紧凑流的十倍内存。
 
 ### 失败与恢复
 
@@ -81,7 +81,7 @@ for await (const chunk of ctx.llm.stream({
 
 ### 设计理念
 
-服务建立在一个分离之上：**逻辑约定是提供方无关的，适配器拥有协议。** 它一次性地定义规范消息、内容块与流式分片词汇，每个提供方适配器只把自己的协议格式翻译为该词汇。注册表是拓扑的拥有者——适配器路由、可配置提供方条目与发现 offer 都在这里注册，并随其 fiber 一起 dispose（资源释放）——而请求始终是会话日志的纯函数：loop 构建的请求以深度冻结状态到达，因此监听器与适配器只能读取，绝不能改写。
+本服务基于一项职责分离原则：**逻辑约定是提供方无关的，适配器拥有协议。** 它一次性地定义规范消息、内容块与流式分片词汇，每个提供方适配器只把自己的协议格式翻译为该词汇。注册表是拓扑的拥有者——适配器路由、可配置提供方条目与发现 offer 都在这里注册，并随其 fiber 一起 dispose（资源释放）——而请求始终是会话日志的纯函数：loop 构建的请求以深度冻结状态到达，因此监听器与适配器只能读取，绝不能改写。
 
 ### 源码地图
 
@@ -91,17 +91,17 @@ for await (const chunk of ctx.llm.stream({
 | [`src/types.ts`](src/types.ts) | `StreamChunk` 协议、内容块映射、结束原因与共享词汇 |
 | [`src/message.ts`](src/message.ts) | 投递、历史与请求共享的不可变消息构造函数 |
 | [`src/assembler.ts`](src/assembler.ts) | `BlockAssembler`：分片到块的增量组装 |
-| [`src/assistant-stream.ts`](src/assistant-stream.ts) | 紧凑带时间 Assistant stream 的累积、严格校验、精确展开与记录级读取器 |
+| [`src/assistant-stream.ts`](src/assistant-stream.ts) | 带时间信息的紧凑 Assistant 流累积、严格校验、精确展开与记录级读取器 |
 | [`src/call-config.ts`](src/call-config.ts) | 调用配置校验、适配器默认值填入与请求冻结 |
 | [`src/retry-policy.ts`](src/retry-policy.ts) | 提供方自有重试策略解析（normal 与 always 模式） |
 | [`src/error.ts`](src/error.ts) | `HarnessError`/`LlmError` 分类体系与提供方无关失败 code |
-| [`src/content.ts`](src/content.ts) | 共享文件与图片投影辅助函数，包括请求图片卸载 |
+| [`src/content.ts`](src/content.ts) | 共享文件与图片辅助函数：内容遍历、文件投影、图片卸载计数与已卸载图片投影 |
 | [`src/api-key.ts`](src/api-key.ts) | 每个适配器共享的凭据格式校验 |
 | [`src/adapter-failure.ts`](src/adapter-failure.ts) | 把失败归一化为终止 finish 分片 |
 
 ### 主流程
 
-请求会对照其精确模型的能力——上下文窗口、输出默认值、推理强度、输入模态与 `systemPromptUpdate` 模式——校验，填入任何适配器配置的默认值，然后整个请求被深度冻结。`prepareCall()` 把这些事实、分离的上下文与重试策略绑定到执行最终分发的精确适配器代次，因此 HMR 或动态设置无法把一个代次的图片能力与另一代次的端点混用。支持图片的适配器把持久引用投影为路由专用请求版本；`resolveImageAttachmentAccess()` 会单独把附件提供方的可选宿主对象映射进当前工具执行世界，而不改变请求图片或其 `variantId`。纯文本路由接收确定性的逐图片占位符，包括嵌套工具结果图片，而不会改写仅追加会话历史。持久 `FileBlock` 引用永远不会到达任何适配器：请求组装把每个引用（包括嵌套工具结果中的出现）替换为确定性 handle 文本，指出文件与其只读保存路径，路径经由挂载的附件与文件系统提供方解析。`ctx.llm.fileRequestText(ref)` 向请求计量公开相同的同步投影。`offloadRequestImagesWithPolicy()` 按原始字节或 base64 大小以及图片数或字节步长，确定性地从最旧图片开始移除；纯函数 `offloadedImagePrefixCount()` 公开同一决策，使路由所属的请求定价无需构建投影即可复现它。对视觉 token 收费的适配器声明按路由的 `imageRequestPricing`，`ctx.llm.imageRequestPricing(provider, model)` 为 token meter 同步解析它。分发经过 `llm/stream` waterfall，随后分片以 token 级增量返回，每个适配器结果都以唯一一个终止 `finish` 分片到达消费方。
+请求会对照其精确模型的能力校验，包括上下文窗口、输出默认值、推理强度、输入模态与 `systemPromptUpdate` 模式，填入任何适配器配置的默认值，然后整个请求被深度冻结。`prepareCall()` 把这些事实、分离的上下文与重试策略绑定到执行最终分发的精确适配器代次，因此 HMR（热模块替换）或动态设置无法把一个代次的图片能力与另一代次的端点混用。支持图片的适配器把持久引用投影为路由专用请求版本；`resolveImageAttachmentAccess()` 会单独把附件提供方的可选宿主对象映射进当前工具执行世界，而不改变请求图片或其 `variantId`。纯文本路由接收确定性的逐图片占位符，包括嵌套工具结果图片，而不会改写仅追加会话历史。持久 `FileBlock` 引用永远不会到达任何适配器：请求组装把每个引用（包括嵌套工具结果中的出现）替换为确定性 句柄文本，指出文件与其只读保存路径，路径经由挂载的附件与文件系统提供方解析。`ctx.llm.fileRequestText(ref)` 向请求计量公开相同的同步投影。派生后带有 `offloaded: true` 的图片出现位置，经 `projectOffloadedImages()` 以占位文本到达每条路由。支持图片的路由在保留的出现位置按精确字节超过其 `LlmImageRequestBudget` 时，以 `IMAGE_OFFLOAD_REQUIRED` 失败并说明还需省略多少最老的出现位置（`requiredImageOffload()`），绝不发送未记录的投影；`dsh-compaction-image-offload` 用一条 `image/offload` 事件记录所选位置并重试。对视觉 token 收费的适配器声明按路由的 `imageRequestPricing`，`ctx.llm.imageRequestPricing(provider, model)` 为 token meter 同步解析它。分发经过 `llm/stream` waterfall（瀑布式事件），随后分片以 token 级增量返回，每个适配器结果都以唯一一个终止 `finish` 分片到达消费方。
 
 文件检测在每次请求时读取当前内容，包括嵌套工具结果，不缓存消息身份或冻结状态。[文件扫描决策](../../../.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md)记录了实测遍历成本。
 
@@ -111,7 +111,7 @@ for await (const chunk of ctx.llm.stream({
 - **回放状态只在同一适配器内流动**——仅当同一适配器实例同时拥有历史路由与目标路由时，assistant 回放状态才会随行；否则在分发前被丢弃。
 - **已准备调用是一次性的**——已准备调用只能分发一次，且其调用配置字段必须与准备好的配置一致。
 - **图片投影遵循捕获的路由**——只有支持图片的模型会把持久 `ImageBlock` 引用转换为路由专用请求版本；纯文本模型接收稳定占位符。
-- **文件投影无条件进行**——没有任何提供方会收到文件字节；每条路由对每个 `FileBlock` 都得到一行确定性 handle 文本，模型在需要时用文件工具读取保存的副本。
+- **文件投影无条件进行**——没有任何提供方会收到文件字节；每条路由对每个 `FileBlock` 都得到一行确定性句柄文本，模型在需要时用文件工具读取保存的副本。
 - **协议顺序**——`usage` 先于 `finish`，工具参数保持原始 JSON 字符串，终止 `finish` 之后不再有任何内容。
 - **注册表变更具有原子性**——路由与目录注册会在任何变动前整体校验候选集合，因此被拒绝的变更会让此前状态继续服务。
 
@@ -124,7 +124,7 @@ for await (const chunk of ctx.llm.stream({
 
 当包级约定不够用时阅读以下页面。它们从共享类型逐步进入具体适配器、重试执行器与计量服务。
 
-- [LLM 流式子系统](../../../docs/subsystems/llm-streaming.zh.md)——消息与块类型、紧凑 Assistant stream record、`StreamChunk` 协议与适配器约定。
+- [LLM（大语言模型）流式子系统](../../../docs/subsystems/llm-streaming.zh.md)——消息与块类型、紧凑的 Assistant 流记录、`StreamChunk` 协议与适配器约定。
 - [llm-deepseek 适配器](../llm-deepseek/README.zh.md)——DeepSeek chat-completions 直连实现。
 - [llm-pi-ai 适配器](../llm-pi-ai/README.zh.md)——基于 pi-ai 的多提供方实现。
 - [llm-retry](../llm-retry/README.zh.md)——重跑失败模型请求的重试执行器。
@@ -141,7 +141,7 @@ for await (const chunk of ctx.llm.stream({
 
 #### KV Cache 影响
 
-推理强度的具体化会保留已组装请求前缀。图片身份与请求预览文本是确定性的，可选执行世界路径则按请求解析；路径变化或图片卸载边界变化可能从该图片起阻止复用。
+推理强度的具体化会保留已组装请求前缀。图片身份与请求预览文本是确定性的，可选执行世界路径则按请求解析；路径变化或一次省略决策可能从该图片起阻止复用。
 
 ## 已知限制与延期工作
 

package/lib/index.js

@@ -219,6 +219,14 @@ function errorChain(value) {
 function isHarnessError(value) {
 	return value instanceof HarnessError;
 }
+/**
+* Canonical code for a request an image-capable route cannot send until more
+* of its images are offloaded. The failure's `offloadImages` names how many
+* more of the oldest retained occurrences must be offloaded;
+* `dsh-compaction-image-offload` records an `image/offload` selection before
+* the agent or summarizer retries with freshly derived input.
+*/
+const IMAGE_OFFLOAD_REQUIRED_CODE = "IMAGE_OFFLOAD_REQUIRED";
 //#endregion
 //#region lib/types/retry-policy.js
 /**
@@ -430,13 +438,15 @@ function failureSnapshot(value) {
 		const status = candidate.status;
 		const providerRetryAfterMs = candidate.providerRetryAfterMs;
 		const requestId = candidate.requestId;
-		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0)) return void 0;
+		const offloadImages = candidate.offloadImages;
+		if (typeof message !== "string" || message.length === 0 || typeof code !== "string" || code.length === 0 || status !== void 0 && (!Number.isInteger(status) || status < 100 || status > 599) || providerRetryAfterMs !== void 0 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0) || requestId !== void 0 && (typeof requestId !== "string" || requestId.length === 0) || offloadImages !== void 0 && (!Number.isSafeInteger(offloadImages) || offloadImages <= 0)) return void 0;
 		return Object.freeze({
 			message,
 			code,
 			...status === void 0 ? {} : { status },
 			...providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs },
-			...requestId === void 0 ? {} : { requestId }
+			...requestId === void 0 ? {} : { requestId },
+			...offloadImages === void 0 ? {} : { offloadImages }
 		});
 	} catch (_sdkFailureGetter) {
 		return;
@@ -651,19 +661,21 @@ function projectFilesToText(messages, resolvePath) {
 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);
+/**
+* Visit every image occurrence of typed content in message order, including
+* nested tool-result content.
+* @param content - typed model content blocks.
+* @param visit - called once per occurrence.
+*/
+function visitImageBlocks(content, visit) {
+	for (const block of content) if (block.type === "image") visit(block);
+	else if (block.type === "tool-result") visitImageBlocks(block.content, visit);
 }
-/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
-function replaceOldestImages(blocks, remaining, placeholder) {
+/** Replace every offloaded occurrence, including nested tool results, with its placeholder. */
+function replaceOffloadedImages(blocks, placeholder) {
 	let next;
 	for (const [index, block] of blocks.entries()) {
-		if (block.type === "image" && remaining.count > 0) {
-			remaining.count -= 1;
+		if (block.type === "image" && block.offloaded === true) {
 			next ??= blocks.slice(0, index);
 			next.push({
 				type: "text",
@@ -672,7 +684,7 @@ function replaceOldestImages(blocks, remaining, placeholder) {
 			continue;
 		}
 		if (block.type === "tool-result") {
-			const content = replaceOldestImages(block.content, remaining, placeholder);
+			const content = replaceOffloadedImages(block.content, placeholder);
 			if (content !== block.content) {
 				next ??= blocks.slice(0, index);
 				next.push({
@@ -686,6 +698,69 @@ function replaceOldestImages(blocks, remaining, placeholder) {
 	}
 	return next ?? blocks;
 }
+/**
+* Project the surface's offloaded occurrences into deterministic text for one
+* request. The offloaded set is a durable surface fact, so every route sends
+* the same set; only the placeholder text is route-owned.
+* @param messages - derived request history.
+* @param placeholder - build the model-visible replacement for one offloaded attachment.
+* @returns the original list when nothing is offloaded, otherwise shallow message copies with placeholders.
+*/
+function projectOffloadedImages(messages, placeholder) {
+	return messages.map((message) => {
+		const content = replaceOffloadedImages(message.content, placeholder);
+		return content === message.content ? message : {
+			...message,
+			content
+		};
+	});
+}
+/**
+* Number of oldest retained image occurrences one route budget removes, in
+* whole count and byte quanta, once the budget is exceeded. The result depends
+* only on the represented lengths, so every route names the count the same
+* way.
+* @param lengths - represented byte length of every retained occurrence, oldest first.
+* @param budget - count/byte budgets and removal quanta; unbounded when absent.
+* @returns how many leading occurrences to offload.
+*/
+function offloadedImagePrefixCount(lengths, budget) {
+	const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+	const excessCount = budget.maxImages === void 0 ? 0 : Math.max(0, lengths.length - budget.maxImages);
+	const excessBytes = budget.maxBytes === void 0 ? 0 : Math.max(0, total - budget.maxBytes);
+	if (excessCount === 0 && excessBytes === 0) return 0;
+	const countQuantum = budget.countQuantum ?? 1;
+	const byteQuantum = budget.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;
+	}
+	return count;
+}
+/**
+* Number of oldest retained occurrences a route must still offload before a
+* derived request fits its budget at the exact byte length the route sends;
+* zero when the request fits. A route fails with `IMAGE_OFFLOAD_REQUIRED`
+* carrying this count instead of offloading on its own.
+* @param messages - derived request history carrying the surface's `offloaded` marks.
+* @param budget - route representation, budgets, and removal quanta.
+* @param versionBytes - exact request-version byte length of one retained occurrence.
+* @returns how many more leading retained occurrences to offload.
+*/
+function requiredImageOffload(messages, budget, versionBytes) {
+	const lengths = [];
+	for (const message of messages) visitImageBlocks(message.content, (block) => {
+		if (block.offloaded === true) return;
+		const bytes = versionBytes(block);
+		lengths.push(budget.representation === "base64" ? base64Length(bytes) : bytes);
+	});
+	return offloadedImagePrefixCount(lengths, budget);
+}
 /** Replace every image occurrence, including nested tool results, for a text-only model. */
 function replaceImagesForTextModel(blocks) {
 	let next;
@@ -728,58 +803,6 @@ function projectImagesForTextModel(messages) {
 		};
 	});
 }
-/**
-* 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.
-*/
-function offloadedImagePrefixCount(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 0;
-	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;
-	}
-	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.
-*/
-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, policy.placeholder);
-		return content === message.content ? message : {
-			...message,
-			content
-		};
-	});
-}
 //#endregion
 //#region lib/types/attribution.js
 /**
@@ -1582,7 +1605,8 @@ var LlmError = class extends HarnessError {
 			code,
 			...options?.status === void 0 ? {} : { status: options.status },
 			...options?.providerRetryAfterMs === void 0 ? {} : { providerRetryAfterMs: options.providerRetryAfterMs },
-			...options?.requestId === void 0 ? {} : { requestId: options.requestId }
+			...options?.requestId === void 0 ? {} : { requestId: options.requestId },
+			...options?.offloadImages === void 0 ? {} : { offloadImages: options.offloadImages }
 		});
 	}
 };
@@ -2323,4 +2347,4 @@ function adapterFailureChunk(error, signal) {
 	};
 }
 //#endregion
-export { APP_IDENTITY, AssistantStreamAccumulator, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, HarnessError, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmAttemptId, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, ToolCallId, assembleAssistantStream, assertUsableApiKey, assistantStreamChunks, assistantStreamFirstTokenTime, assistantStreamHasVisibleContent, assistantStreamHasVisibleText, attributionHeaders, boundContextSummary, callConfigEquals, chunkHasVisibleText, contentHasFile, contentHasImage, createAssistantMessage, createMessage, createSystemMessage, createToolResultMessage, createUserMessage, errorChain, expandAssistantStream, fileHandleText, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, isVisibleChunk, joinAssistantStreamText, lastAssistantStreamChunk, markAgentLoopRequest, normalizeApiKey, offloadRequestImagesWithPolicy, offloadedImagePrefixCount, offloadedImageText, projectFilesToText, projectImagesForTextModel, requestImageHandleText, resolveImageAttachmentAccess, resolveRetryPolicy, runFirstTokenTime, runFirstVisibleTime, textOnlyImageText, userAgent };
+export { APP_IDENTITY, AssistantStreamAccumulator, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, HarnessError, IMAGE_OFFLOAD_REQUIRED_CODE, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmAttemptId, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, ToolCallId, assembleAssistantStream, assertUsableApiKey, assistantStreamChunks, assistantStreamFirstTokenTime, assistantStreamHasVisibleContent, assistantStreamHasVisibleText, attributionHeaders, boundContextSummary, callConfigEquals, chunkHasVisibleText, contentHasFile, contentHasImage, createAssistantMessage, createMessage, createSystemMessage, createToolResultMessage, createUserMessage, errorChain, expandAssistantStream, fileHandleText, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, isVisibleChunk, joinAssistantStreamText, lastAssistantStreamChunk, markAgentLoopRequest, normalizeApiKey, offloadedImageText, projectFilesToText, projectImagesForTextModel, projectOffloadedImages, requestImageHandleText, requiredImageOffload, resolveImageAttachmentAccess, resolveRetryPolicy, runFirstTokenTime, runFirstVisibleTime, textOnlyImageText, userAgent };

package/lib/typert.host.js

@@ -68,7 +68,7 @@ export const TYPERT = {
         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":628,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":631,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders',
@@ -83,7 +83,7 @@ export const TYPERT = {
         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":541,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":544,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listProviders',
@@ -98,7 +98,7 @@ export const TYPERT = {
         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":469,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":472,"column":3},
     },
   ],
   model: {
@@ -227,8 +227,8 @@ export const TYPERT = {
             "declaration": "export interface AgentMessageSource {\n    readonly kind: 'agent-message';\n    readonly form: 'relay';\n    readonly senderSessionId: SessionId;\n}"
           },
           {
-            "name": "AssistantProvenance",
-            "declaration": "export interface AssistantProvenance {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}"
+            "name": "AssistantProviderMetadata",
+            "declaration": "export interface AssistantProviderMetadata {\n    provider: string;\n    model: string;\n    replayState?: unknown;\n}"
           },
           {
             "name": "AttachmentId",
@@ -300,7 +300,7 @@ export const TYPERT = {
           },
           {
             "name": "ImageBlock",
-            "declaration": "export interface ImageBlock {\n    type: 'image';\n    attachment: ImageAttachmentRef;\n}"
+            "declaration": "export interface ImageBlock {\n    type: 'image';\n    attachment: ImageAttachmentRef;\n    offloaded?: true;\n}"
           },
           {
             "name": "ImageMediaType",
@@ -328,7 +328,7 @@ export const TYPERT = {
           },
           {
             "name": "LlmFailure",
-            "declaration": "export interface LlmFailure {\n    readonly message: string;\n    readonly code: string;\n    readonly status?: number;\n    readonly providerRetryAfterMs?: number;\n    readonly requestId?: ProviderRequestId;\n}"
+            "declaration": "export interface LlmFailure {\n    readonly message: string;\n    readonly code: string;\n    readonly status?: number;\n    readonly providerRetryAfterMs?: number;\n    readonly requestId?: ProviderRequestId;\n    readonly offloadImages?: number;\n}"
           },
           {
             "name": "LlmImageRequestPrice",
@@ -336,7 +336,7 @@ export const TYPERT = {
           },
           {
             "name": "LlmImageRequestPricing",
-            "declaration": "export interface LlmImageRequestPricing {\n    priceImages(images: readonly ImageAttachmentRef[]): readonly LlmImageRequestPrice[];\n}"
+            "declaration": "export interface LlmImageRequestPricing {\n    priceImages(images: readonly ImageBlock[]): readonly LlmImageRequestPrice[];\n}"
           },
           {
             "name": "LlmModelContext",
@@ -384,7 +384,7 @@ export const TYPERT = {
           },
           {
             "name": "ModelMessageSource",
-            "declaration": "export interface ModelMessageSource extends AssistantProvenance {\n    kind: 'model';\n}"
+            "declaration": "export interface ModelMessageSource extends AssistantProviderMetadata {\n    kind: 'model';\n}"
           },
           {
             "name": "ModelModality",

package/lib/typert.remote-client.js

@@ -65,7 +65,7 @@ export const TYPERT_REMOTE = {
         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":628,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":631,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders',
@@ -80,7 +80,7 @@ export const TYPERT_REMOTE = {
         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":541,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":544,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listProviders',
@@ -95,7 +95,7 @@ export const TYPERT_REMOTE = {
         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":469,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":472,"column":3},
     },
   ],
 }

package/lib/types/adapter-failure.js

@@ -67,12 +67,14 @@ function failureSnapshot(value) {
         const status = candidate.status;
         const providerRetryAfterMs = candidate.providerRetryAfterMs;
         const requestId = candidate.requestId;
+        const offloadImages = candidate.offloadImages;
         if (typeof message !== 'string' || message.length === 0
             || typeof code !== 'string' || code.length === 0
             || (status !== undefined && (!Number.isInteger(status) || status < 100 || status > 599))
             || (providerRetryAfterMs !== undefined
                 && (!Number.isFinite(providerRetryAfterMs) || providerRetryAfterMs <= 0))
-            || (requestId !== undefined && (typeof requestId !== 'string' || requestId.length === 0)))
+            || (requestId !== undefined && (typeof requestId !== 'string' || requestId.length === 0))
+            || (offloadImages !== undefined && (!Number.isSafeInteger(offloadImages) || offloadImages <= 0)))
             return undefined;
         return Object.freeze({
             message,
@@ -80,6 +82,7 @@ function failureSnapshot(value) {
             ...status === undefined ? {} : { status },
             ...providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs },
             ...requestId === undefined ? {} : { requestId },
+            ...offloadImages === undefined ? {} : { offloadImages },
         });
     }
     catch (_sdkFailureGetter) {

package/lib/types/content.d.ts

@@ -1,5 +1,5 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-llm/content */
-import type { ContentBlock } from './types.ts';
+import type { ContentBlock, ImageBlock, LlmImageRequestBudget } from './types.ts';
 import type { Message } from './message.ts';
 import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
 /** Execution-world path that model tools can use to read one normalized attachment. */
@@ -83,49 +83,30 @@ export declare function fileHandleText(ref: FileAttachmentRef, readonlyPath: str
  * @returns the original list without files, otherwise shallow message copies with handle text.
  */
 export declare function projectFilesToText(messages: readonly Message[], resolvePath: (ref: FileAttachmentRef) => string | undefined): readonly Message[];
-/** 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 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.
- * @param messages - complete request history.
- * @returns the original list without images, otherwise shallow message copies with stable placeholders.
+ * Project the surface's offloaded occurrences into deterministic text for one
+ * request. The offloaded set is a durable surface fact, so every route sends
+ * the same set; only the placeholder text is route-owned.
+ * @param messages - derived request history.
+ * @param placeholder - build the model-visible replacement for one offloaded attachment.
+ * @returns the original list when nothing is offloaded, otherwise shallow message copies with placeholders.
  */
-export declare function projectImagesForTextModel(messages: readonly Message[]): readonly Message[];
+export declare function projectOffloadedImages(messages: readonly Message[], placeholder: (ref: ImageAttachmentRef) => string): readonly Message[];
 /**
- * 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.
+ * Number of oldest retained occurrences a route must still offload before a
+ * derived request fits its budget at the exact byte length the route sends;
+ * zero when the request fits. A route fails with `IMAGE_OFFLOAD_REQUIRED`
+ * carrying this count instead of offloading on its own.
+ * @param messages - derived request history carrying the surface's `offloaded` marks.
+ * @param budget - route representation, budgets, and removal quanta.
+ * @param versionBytes - exact request-version byte length of one retained occurrence.
+ * @returns how many more leading retained occurrences to offload.
  */
-export declare function offloadedImagePrefixCount(lengths: readonly number[], policy: Pick<RequestImageOffloadPolicy, 'maxImages' | 'maxBytes' | 'countQuantum' | 'byteQuantum'>): number;
+export declare function requiredImageOffload(messages: readonly Message[], budget: Pick<LlmImageRequestBudget, 'representation' | 'maxBytes' | 'maxImages' | 'byteQuantum' | 'countQuantum'>, versionBytes: (block: ImageBlock) => number): 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
- * 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.
+ * 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 offloadRequestImagesWithPolicy(messages: readonly Message[], policy: RequestImageOffloadPolicy): readonly Message[];
+export declare function projectImagesForTextModel(messages: readonly Message[]): readonly Message[];
 //# sourceMappingURL=content.d.ts.map

package/lib/types/content.js

@@ -161,32 +161,31 @@ export function projectFilesToText(messages, resolvePath) {
 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);
-        }
+/**
+ * Visit every image occurrence of typed content in message order, including
+ * nested tool-result content.
+ * @param content - typed model content blocks.
+ * @param visit - called once per occurrence.
+ */
+function visitImageBlocks(content, visit) {
+    for (const block of content) {
+        if (block.type === 'image')
+            visit(block);
+        else if (block.type === 'tool-result')
+            visitImageBlocks(block.content, visit);
     }
 }
-/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
-function replaceOldestImages(blocks, remaining, placeholder) {
+/** Replace every offloaded occurrence, including nested tool results, with its placeholder. */
+function replaceOffloadedImages(blocks, placeholder) {
     let next;
     for (const [index, block] of blocks.entries()) {
-        if (block.type === 'image' && remaining.count > 0) {
-            remaining.count -= 1;
+        if (block.type === 'image' && block.offloaded === true) {
             next ??= blocks.slice(0, index);
             next.push({ type: 'text', text: placeholder(block.attachment) });
             continue;
         }
         if (block.type === 'tool-result') {
-            const content = replaceOldestImages(block.content, remaining, placeholder);
+            const content = replaceOffloadedImages(block.content, placeholder);
             if (content !== block.content) {
                 next ??= blocks.slice(0, index);
                 next.push({ ...block, content });
@@ -197,6 +196,73 @@ function replaceOldestImages(blocks, remaining, placeholder) {
     }
     return next ?? blocks;
 }
+/**
+ * Project the surface's offloaded occurrences into deterministic text for one
+ * request. The offloaded set is a durable surface fact, so every route sends
+ * the same set; only the placeholder text is route-owned.
+ * @param messages - derived request history.
+ * @param placeholder - build the model-visible replacement for one offloaded attachment.
+ * @returns the original list when nothing is offloaded, otherwise shallow message copies with placeholders.
+ */
+export function projectOffloadedImages(messages, placeholder) {
+    return messages.map((message) => {
+        const content = replaceOffloadedImages(message.content, placeholder);
+        return content === message.content ? message : { ...message, content };
+    });
+}
+/**
+ * Number of oldest retained image occurrences one route budget removes, in
+ * whole count and byte quanta, once the budget is exceeded. The result depends
+ * only on the represented lengths, so every route names the count the same
+ * way.
+ * @param lengths - represented byte length of every retained occurrence, oldest first.
+ * @param budget - count/byte budgets and removal quanta; unbounded when absent.
+ * @returns how many leading occurrences to offload.
+ */
+function offloadedImagePrefixCount(lengths, budget) {
+    const total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+    const excessCount = budget.maxImages === undefined ? 0 : Math.max(0, lengths.length - budget.maxImages);
+    const excessBytes = budget.maxBytes === undefined ? 0 : Math.max(0, total - budget.maxBytes);
+    if (excessCount === 0 && excessBytes === 0)
+        return 0;
+    const countQuantum = budget.countQuantum ?? 1;
+    const byteQuantum = budget.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;
+    }
+    return count;
+}
+/**
+ * Number of oldest retained occurrences a route must still offload before a
+ * derived request fits its budget at the exact byte length the route sends;
+ * zero when the request fits. A route fails with `IMAGE_OFFLOAD_REQUIRED`
+ * carrying this count instead of offloading on its own.
+ * @param messages - derived request history carrying the surface's `offloaded` marks.
+ * @param budget - route representation, budgets, and removal quanta.
+ * @param versionBytes - exact request-version byte length of one retained occurrence.
+ * @returns how many more leading retained occurrences to offload.
+ */
+export function requiredImageOffload(messages, budget, versionBytes) {
+    const lengths = [];
+    for (const message of messages) {
+        visitImageBlocks(message.content, (block) => {
+            if (block.offloaded === true)
+                return;
+            const bytes = versionBytes(block);
+            lengths.push(budget.representation === 'base64' ? base64Length(bytes) : bytes);
+        });
+    }
+    return offloadedImagePrefixCount(lengths, budget);
+}
 /** Replace every image occurrence, including nested tool results, for a text-only model. */
 function replaceImagesForTextModel(blocks) {
     let next;
@@ -231,59 +297,4 @@ export function projectImagesForTextModel(messages) {
         return content === message.content ? message : { ...message, content };
     });
 }
-/**
- * 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 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 0;
-    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;
-    }
-    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, policy.placeholder);
-        return content === message.content ? message : { ...message, content };
-    });
-}
 //# sourceMappingURL=content.js.map

package/lib/types/error.d.ts

@@ -70,4 +70,12 @@ export declare function errorChain(value: unknown): string;
  * @returns true only for real instances; duck-typed or cross-realm errors do not narrow.
  */
 export declare function isHarnessError(value: unknown): value is HarnessError;
+/**
+ * Canonical code for a request an image-capable route cannot send until more
+ * of its images are offloaded. The failure's `offloadImages` names how many
+ * more of the oldest retained occurrences must be offloaded;
+ * `dsh-compaction-image-offload` records an `image/offload` selection before
+ * the agent or summarizer retries with freshly derived input.
+ */
+export declare const IMAGE_OFFLOAD_REQUIRED_CODE = "IMAGE_OFFLOAD_REQUIRED";
 //# sourceMappingURL=error.d.ts.map

package/lib/types/error.js

@@ -142,4 +142,12 @@ export function errorChain(value) {
 export function isHarnessError(value) {
     return value instanceof HarnessError;
 }
+/**
+ * Canonical code for a request an image-capable route cannot send until more
+ * of its images are offloaded. The failure's `offloadImages` names how many
+ * more of the oldest retained occurrences must be offloaded;
+ * `dsh-compaction-image-offload` records an `image/offload` selection before
+ * the agent or summarizer retries with freshly derived input.
+ */
+export const IMAGE_OFFLOAD_REQUIRED_CODE = 'IMAGE_OFFLOAD_REQUIRED';
 //# sourceMappingURL=error.js.map

package/lib/types/index.d.ts

@@ -53,6 +53,8 @@ export interface LlmErrorOptions extends ErrorOptions {
     providerRetryAfterMs?: number;
     /** Non-empty opaque provider request id. */
     requestId?: ProviderRequestId;
+    /** Positive count of additional oldest retained image occurrences to offload; only with `IMAGE_OFFLOAD_REQUIRED`. */
+    offloadImages?: number;
 }
 /**
  * Typed error for LLM-related failures. Extends {@link HarnessError}, so the

package/lib/types/index.js

@@ -96,6 +96,7 @@ export class LlmError extends HarnessError {
             ...options?.status === undefined ? {} : { status: options.status },
             ...options?.providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs: options.providerRetryAfterMs },
             ...options?.requestId === undefined ? {} : { requestId: options.requestId },
+            ...options?.offloadImages === undefined ? {} : { offloadImages: options.offloadImages },
         });
     }
 }

package/lib/types/message.d.ts

@@ -2,7 +2,7 @@
 import type { MessageId, ToolCallId } from './brand.ts';
 import type { ContentBlock, ToolResultBlock } from './types.ts';
 /** Provider/model identity and adapter-private replay data for an assistant message. */
-export interface AssistantProvenance {
+export interface AssistantProviderMetadata {
     /** Provider route that produced the message. */
     provider: string;
     /** Provider model id that produced the message. */
@@ -15,7 +15,7 @@ export interface AssistantProvenance {
     replayState?: unknown;
 }
 /** Required source of an assistant message produced by a routed model. */
-export interface ModelMessageSource extends AssistantProvenance {
+export interface ModelMessageSource extends AssistantProviderMetadata {
     kind: 'model';
 }
 /** Required source of a user-role message carrying one tool result. */
@@ -25,7 +25,7 @@ export interface ToolMessageSource {
 }
 /**
  * The kind of information in producer-supplied context, declared by the
- * producer beside its provenance.
+ * producer in the same `MessageSource`.
  *
  * `MessageSource.kind` answers *who produced this*; `form` answers *what kind
  * of thing it is*, and the two axes are deliberately independent — several

package/lib/types/types.d.ts

@@ -21,7 +21,7 @@ declare module '@deepseek-ai/cordis' {
         'llm/adapters-updated'(): void;
     }
 }
-export type { AssistantMessage, AssistantProvenance, Message, MessageSource, MessageSourceMap, ModelMessageSource, ToolMessageSource, ToolResultMessage, UserMessage, } from './message.ts';
+export type { AssistantMessage, AssistantProviderMetadata, Message, MessageSource, MessageSourceMap, ModelMessageSource, ToolMessageSource, ToolResultMessage, UserMessage, } from './message.ts';
 /** Serializable provider or transport failure facts; policy decides whether they are retryable. */
 export interface LlmFailure {
     /** Human-readable provider or transport failure. */
@@ -34,6 +34,13 @@ export interface LlmFailure {
     readonly providerRetryAfterMs?: number;
     /** Opaque provider-issued request identifier for diagnostics. */
     readonly requestId?: ProviderRequestId;
+    /**
+     * With code `IMAGE_OFFLOAD_REQUIRED`: how many more of the oldest retained
+     * image occurrences the route needs offloaded before the same request fits
+     * its exact byte accounting. `dsh-compaction-image-offload` records the
+     * selected occurrences in an `image/offload` event and retries the step.
+     */
+    readonly offloadImages?: number;
 }
 /** Plain text visible to the end user. */
 export interface TextBlock {
@@ -55,6 +62,12 @@ export interface ImageBlock {
     type: 'image';
     /** Immutable bytes and intrinsic display metadata owned by the attachment service. */
     attachment: ImageAttachmentRef;
+    /**
+     * Derived from a durable image-offload decision or preserved by a message
+     * rewrite. Every route sends placeholder text naming the image and its
+     * available read-only path instead of image bytes.
+     */
+    offloaded?: true;
 }
 /**
  * A durable verbatim file reference, valid in user content. Files never reach
@@ -171,10 +184,11 @@ export interface LlmImageRequestPrice {
 export interface LlmImageRequestPricing {
     /**
      * Price every image occurrence of one request projection.
-     * @param images - durable image references in request order, one entry per occurrence.
+     * @param images - surface image blocks in request order, one entry per occurrence; an `offloaded` block
+     *   is priced as its placeholder text.
      * @returns one price per occurrence, aligned by index with `images`.
      */
-    priceImages(images: readonly ImageAttachmentRef[]): readonly LlmImageRequestPrice[];
+    priceImages(images: readonly ImageBlock[]): readonly LlmImageRequestPrice[];
 }
 /** Display metadata for one registered provider route. */
 export interface LlmProviderInfo {
@@ -291,6 +305,25 @@ export interface LlmModelContext {
     /** Maximum combined request and response context in tokens. */
     contextWindow: number;
 }
+/**
+ * Request-image budget one exact image-capable route enforces over the
+ * retained occurrences' exact request-version bytes; for the `base64`
+ * representation each byte count expands to its encoded length. A route whose
+ * retained occurrences exceed the budget fails the request with
+ * `IMAGE_OFFLOAD_REQUIRED` naming the additional occurrences to offload.
+ */
+export interface LlmImageRequestBudget {
+    /** Whether the route accounts raw file bytes or inline base64 length. */
+    representation: 'raw' | 'base64';
+    /** Accumulated represented image bytes the route accepts; absent leaves bytes unbounded. */
+    maxBytes?: number;
+    /** Image occurrences the route accepts; absent leaves the count unbounded. */
+    maxImages?: number;
+    /** Represented bytes removed as one deterministic advance step; absent removes the minimum. */
+    byteQuantum?: number;
+    /** Occurrences removed as one deterministic advance step; absent removes the minimum. */
+    countQuantum?: number;
+}
 /** Display metadata for one adapter-owned reasoning effort. */
 export interface LlmReasoningEffortInfo {
     /** Opaque stable value accepted by {@link GenerateOptions.reasoningEffort}. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm",
   "description": "Provider-neutral LLM service interface for the DeepSeek Harness",
-  "version": "0.1.5-rc.1",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -65,16 +65,16 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-crypto": "^0.1.5-rc.1",
     "@deepseek-ai/schemastery": "^3.18.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-brand": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-util-values": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-util-crypto": "^0.1.6-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.1",
-    "@deepseek-ai/dsh-attachment": "^0.1.5-rc.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.6-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }