@deepseek-ai/dsh-llm 0.1.0-rc.8 → 0.1.1-rc.2

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: e6b3c4924ad4e7cf115abdbfb38d22d0f524e377
-README.zh.md: 51f034af632c19ca91c1d2f91a7c9c22714870e0
+README.md: 59c5303bdae8d6391f3bb1595a527d677e2378bc
+README.zh.md: 313fc23590de2119bf07dd5c4c4fafe9daa94c56

package/README.md

@@ -25,7 +25,7 @@ Each provider adapter supplies its resolved route policy. Omitting provider conf
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` Discover the models one registered provider currently advertises.
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` Resolve validated exact-model identity plus available context, output-default, and reasoning metadata from the owning adapter, with optional cancellation for asynchronous adapters.
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` Validate an explicit effort and materialize adapter-configured call defaults without clamping.
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context metadata and markers for fields supplied by adapter defaults in one exact-model lookup, then capture its current adapter registration and immutable retry policy as one cancellable, one-shot call.
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` Resolve a config plus detached context and modality metadata and markers for fields supplied by adapter defaults in one exact-model lookup, then capture the adapter's matching dispatch generation and immutable retry policy as one cancellable, one-shot call.
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` Stream one model call as raw chunks (token-level deltas). Consumers assemble the chunks into blocks/messages with `BlockAssembler`.
 
 `LlmRuntime` normalizes failures from final adapter selection, synchronous dispatch, iterator construction, and iteration into the stream protocol's single terminal form: `finish { kind: 'error' | 'aborted', failure }`. A failure after partial deltas may leave content blocks open; consumers discard that incomplete output. Errors from `llm/stream` middleware, nested calls, adapter cleanup, and downstream consumers remain thrown because they are plugin or consumer failures rather than model-request outcomes. A prepared call exposes the immutable retry policy captured with its exact adapter registration; a route handled entirely by middleware has no serving policy.
@@ -38,7 +38,7 @@ Every topology commit point — adapter routes registering or disposing, directo
 
 Exact-model metadata is a separate correctness query, not a catalog decoration or global LLM setting. `resolveModelInfo()` asks the adapter that owns the exact provider/model route once; an adapter can describe an unlisted dynamic model, and absent `context`, `defaultMaxTokens`, or `reasoning` fields preserve unknown capacity, provider-owned output defaults, or unavailable reasoning capability. Invalid identity, context, output default, or reasoning metadata fails with `INVALID_MODEL_INFO`, `INVALID_MODEL_CONTEXT`, `INVALID_MODEL_MAX_TOKENS`, or `INVALID_MODEL_REASONING`.
 
-`defaultMaxTokens` is an adapter-configured per-request output cap, not a model hard limit. `resolveCallConfig()` materializes it only when the request omits `maxTokens`; an explicit cap wins. Reasoning identifiers are opaque adapter-owned strings rather than a core enum: the same resolution accepts only an exact advertised identifier, materializes `defaultEffort` when present, and otherwise preserves the provider default. Asynchronous model resolvers receive the caller's signal and must settle promptly after cancellation. `prepareCall()` additionally exposes detached context metadata from the same lookup, reports which `maxTokens` and `reasoningEffort` fields it materialized in `adapterDefaults`, and retains the exact adapter registration through header logging and terminal dispatch, so HMR cannot combine one adapter's capability result with another adapter's request; reusing its one-shot handle or changing its call-config fields fails with `INVALID_PREPARED_CALL`. An unsupported explicit or configured effort fails with `UNSUPPORTED_REASONING_EFFORT` before provider I/O.
+`defaultMaxTokens` is an adapter-configured per-request output cap, not a model hard limit. `resolveCallConfig()` materializes it only when the request omits `maxTokens`; an explicit cap wins. Reasoning identifiers are opaque adapter-owned strings rather than a core enum: the same resolution accepts only an exact advertised identifier, materializes `defaultEffort` when present, and otherwise preserves the provider default. Asynchronous model resolvers receive the caller's signal and must settle promptly after cancellation. `prepareCall()` additionally exposes detached context and input-modality metadata, reports which `maxTokens` and `reasoningEffort` fields it materialized in `adapterDefaults`, and binds those facts to the adapter generation that performs terminal dispatch. HMR or dynamic settings therefore cannot combine one generation's image capability with another generation's endpoint; reusing the one-shot handle or changing its call-config fields fails with `INVALID_PREPARED_CALL`. An unsupported explicit or configured effort fails with `UNSUPPORTED_REASONING_EFFORT` before provider I/O.
 
 ### Events
 
@@ -55,7 +55,9 @@ Exact-model metadata is a separate correctness query, not a catalog decoration o
 
 `Message` is the shared immutable value used by delivery, durable history, and model requests. Every message has a required `MessageId`, role, content, and typed source from creation onward. `createMessage(input)` mints the identity and returns a detached deep-frozen value; `createUserMessage({ content, source })` fixes the user role; `createAssistantMessage({ content, source })` fixes the assistant role and model source kind; `createToolResultMessage({ callId, content, isError })` fixes the user role and couples the tool source to its result block; `freezeMessage(message)` imports an identity that already exists and never replaces it. Message rewrites preserve the identity and produce another frozen value. Browser code imports these value constructors from the dependency-minimal `@deepseek-ai/dsh-llm/message` entry instead of the service-bearing package root.
 
-Message content is an array of typed blocks: `text`, `reasoning`, `tool-call`, `tool-result`. The union is derived from the merge-extensible `ContentBlockMap`, so plugins can add block types via declaration merging. Assistant messages use a model source carrying the provider and model that produced them plus optional adapter-private replay state. Before dispatch, `LlmRuntime` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers. The core block set is limited to blocks every shipping path honors — multimodal content (images, audio, …) has no core block type; a feature that needs one adds it via the map together with the adapter/UI/compaction support that honors it.
+Message content is an array of typed blocks: `text`, `reasoning`, `image`, `tool-call`, `tool-result`. An `ImageBlock` carries only a durable `ImageAttachmentRef`; provider bytes and request dimensions are resolved later. The union remains merge-extensible through `ContentBlockMap`, so plugins can add further block types via declaration merging. Assistant messages use a model source carrying the provider and model that produced them plus optional adapter-private replay state. Before dispatch, `LlmRuntime` retains that state only when the historical provider route and target provider route are currently owned by the exact same adapter instance; the adapter then decides whether it can restore or convert the state across models/providers.
+
+Every dispatch uses the exact model modalities captured with its adapter generation. An image-capable adapter projects durable image references into route-specific request versions. A text-only route instead receives deterministic attachment placeholders, including nested tool-result images, without changing append-only session history. `offloadRequestImagesWithPolicy()` provides deterministic oldest-first image removal with raw or base64 accounting and count or byte quanta; adapters supply the exact derived-version byte length.
 
 Streaming is a raw chunk protocol (`block-start`, `text-delta`, `reasoning-delta`, `tool-call-delta`, `block-end`, `usage`, `finish`). Every adapter outcome reaches consumers as one terminal `finish`; operational failure uses its `error` or `aborted` reason rather than throwing across the stream API. `BlockAssembler` is the single shared implementation that assembles chunks into blocks/messages. A successful `finish` may carry a `ReplayEnvelope` — opaque response-level replay metadata plus optional per-block entries aligned with the emitted block sequence. Assembly makes one keep/drop decision for content and metadata together: a `max-tokens` finish drops tool calls that may have been truncated, and the envelope loses the entry at each dropped position, so stored metadata always describes stored content.
 

package/README.zh.md

@@ -25,7 +25,7 @@
 - `ctx.llm.listModels(provider: string): Promise<LlmModelInfo[]>` 发现某个已注册提供方当前公布的模型。
 - `ctx.llm.resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>` 从拥有该精确路由的适配器中，解析并校验确切模型身份，以及可用上下文、输出默认值和推理（reasoning）元数据；异步适配器可选地支持取消。
 - `ctx.llm.resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>` 校验显式推理强度，并填入适配器配置的调用默认值，但不自动调整。
-- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文元数据以及标明哪些字段由适配器默认值填入的标记，再将当前适配器注册和不可变重试策略捕获为一次可取消、一次性调用。
+- `ctx.llm.prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>` 在一次精确模型查询中解析配置、脱耦的上下文与模态元数据以及标明哪些字段由适配器默认值填入的标记，再把适配器匹配的分发世代和不可变重试策略捕获为一次可取消、一次性调用。
 - `ctx.llm.stream(options: GenerateOptions): AsyncIterable<StreamChunk>` 将一次模型调用流式输出为原始分片（token 级增量）。消费方使用 `BlockAssembler` 将分片组装为块／消息。
 
 `LlmRuntime` 将最终适配器选择、同步分发、迭代器构造和迭代期间的失败，统一转换为流协议唯一的终止形式：`finish { kind: 'error' | 'aborted', failure }`。部分增量输出后发生失败时，内容块可能仍未闭合；消费方会丢弃这些不完整输出。`llm/stream` middleware、嵌套调用、适配器清理和下游消费方的错误仍会抛出，因为它们属于插件或消费方失败，而非模型请求结果。已准备调用会暴露随其确切适配器注册一同捕获的不可变重试策略；完全由 middleware 处理的路由没有服务策略。
@@ -38,7 +38,7 @@
 
 确切模型元数据是独立的正确性查询，不是 catalog 装饰或全局 LLM 设置。`resolveModelInfo()` 会向拥有精确提供方／模型路由的适配器查询一次；适配器可以描述未列出的动态模型。缺少 `context` 表示模型容量未知；缺少 `defaultMaxTokens` 表示继续沿用提供方自身的输出默认值；缺少 `reasoning` 则表示推理能力不可用。无效的身份、上下文、输出默认值或推理元数据会以 `INVALID_MODEL_INFO`、`INVALID_MODEL_CONTEXT`、`INVALID_MODEL_MAX_TOKENS` 或 `INVALID_MODEL_REASONING` 失败。
 
-`defaultMaxTokens` 是适配器配置的单次请求输出上限，不是模型硬上限。仅当请求省略 `maxTokens` 时，`resolveCallConfig()` 才会填入该值；显式上限优先。推理标识符是由适配器定义的不透明字符串，而非核心枚举：同一次解析只接受与已公布标识符完全一致的值，在存在 `defaultEffort` 时填入它，否则保留提供方默认值。异步模型解析器会接收调用方信号，并且必须在取消后尽快结算。`prepareCall()` 还会返回同一次查询得到的、与适配器内部状态分离的上下文元数据，通过 `adapterDefaults` 标明填入了哪些 `maxTokens` 和 `reasoningEffort` 字段，并在请求头记录和最终分发期间始终保留同一项精确的适配器注册。因此，HMR（热模块替换）不会把一个适配器的能力结果与另一个适配器的请求混用；复用其一次性句柄或更改调用配置字段会以 `INVALID_PREPARED_CALL` 失败。不支持的显式或配置推理强度会在提供方 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败。
+`defaultMaxTokens` 是适配器配置的单次请求输出上限，不是模型硬上限。仅当请求省略 `maxTokens` 时，`resolveCallConfig()` 才会填入该值；显式上限优先。推理标识符是由适配器定义的不透明字符串，而非核心枚举：同一次解析只接受与已公布标识符完全一致的值，在存在 `defaultEffort` 时填入它，否则保留提供方默认值。异步模型解析器会接收调用方信号，并且必须在取消后尽快结算。`prepareCall()` 还会公开脱离内部状态的上下文和输入模态元数据，通过 `adapterDefaults` 标明填入了哪些 `maxTokens` 和 `reasoningEffort` 字段，并把这些事实绑定到执行最终分发的适配器世代。因此，HMR（热模块替换）或动态 settings 不会把一个世代的图片能力与另一个世代的端点组合；复用一次性句柄或更改调用配置字段会以 `INVALID_PREPARED_CALL` 失败。不支持的显式或配置推理强度会在提供方 I/O 前以 `UNSUPPORTED_REASONING_EFFORT` 失败。
 
 ### 事件
 
@@ -55,7 +55,9 @@
 
 `Message` 是投递、持久历史和模型请求共享的不可变值。每条消息从创建起都必须具有 `MessageId`、角色、内容和带类型的来源。`createMessage(input)` 生成标识，并返回与输入分离且深度冻结的值；`createUserMessage({ content, source })` 固定 user 角色；`createAssistantMessage({ content, source })` 固定 assistant 角色与模型来源类别；`createToolResultMessage({ callId, content, isError })` 固定 user 角色，并将工具来源与其结果块耦合；`freezeMessage(message)` 导入已有标识，绝不将其替换。改写消息时会保留标识，并产生另一个冻结值。浏览器端代码会从依赖最少的 `@deepseek-ai/dsh-llm/message` 入口导入这些值构造函数，而不是从包含服务的包根入口导入。
 
-消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带生成该消息的提供方和模型，以及可选的适配器私有回放状态。dispatch 前，`LlmRuntime` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
+消息内容是类型化内容块数组：`text`、`reasoning`、`image`、`tool-call`、`tool-result`。`ImageBlock` 只携带持久 `ImageAttachmentRef`；提供方字节和请求尺寸之后再解析。联合仍从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加其他块类型。assistant 消息使用模型来源，其中携带生成该消息的提供方和模型，以及可选的适配器私有回放状态。dispatch 前，`LlmRuntime` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型或提供方间恢复或转换该状态。
+
+每次分发都使用随适配器世代捕获的确切模型模态。支持图片的适配器把持久图片引用投影为路由专用请求版本。纯文本路由则收到确定性的附件占位文本，其中也包括嵌套工具结果图片，追加式会话历史不会改变。`offloadRequestImagesWithPolicy()` 提供确定性的从旧到新图片移除，支持按原始字节或 base64 计数，也支持图片数量或字节量步长；适配器提供确切派生版本的字节长度。
 
 流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用 `error` 或 `aborted` 作为结束原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。成功的 `finish` 可以携带 `ReplayEnvelope`——不透明的响应级回放元数据，加上与发射块序列对齐的可选逐块条目。组装对内容与元数据只做一次保留/丢弃决定：`max-tokens` 结束会丢弃可能被截断的工具调用，数据在每个被丢弃的位置同步失去对应条目，因此存储的元数据始终描述存储的内容。
 
@@ -63,9 +65,11 @@
 
 `LlmCallConfig` 记录一个会话的模型请求所使用的提供方、模型、由适配器定义的可选推理强度，以及采样参数（`provider`、`model`、`reasoningEffort`、`temperature`、`maxTokens`、`stop`，分别与同名 `GenerateOptions` 字段一一对应）。它是作为请求标头一部分记录在会话日志中的每会话状态（见 dsh-session `request/header` 事件），绝不是可静默调整的每次调用旋钮：`agent/request` waterfall 会提议替换，`prepareCall()` 在轮次 signal 控制下校验它并填入适配器默认值，loop 随后记录生效值以及标明哪些字段由适配器默认值填入的标记，再使用已准备调用中与注册绑定的流。下一次提议会省略带标记的默认值，使变更后的路由解析自身的值；未带标记的显式字段会保留。`callConfigEquals(a, b)` 是逐字段真实变更检测器；`deepFreeze(value)` 是 loop 使用的请求所有权辅助函数：每个构造完成的请求都会在分发前深度冻结；`llm/stream` 监听器和适配器只能读取，绝不能改写。`markAgentLoopRequest()` 将该精确对象标记为由进程本地 agent loop 创建，`isAgentLoopRequest()` 让观测方可以将其与同样可能冻结并关联会话、但独立记录的辅助调用区分。`GenerateOptions.purpose` 会对已记录的辅助压缩和会话标题调用进行分类，使适配器可以按调用目的应用不同的传输策略，而不改变普通会话请求。
 
+<a id="app-attribution-attributionts"></a>
+
 ### 应用归因（`attribution.ts`）
 
-每个产品适配器都会在提供方 HTTP 请求上发送应用身份。`attributionHeaders(identity?)` 构建标准 `User-Agent`，默认为公开 `APP_IDENTITY`；白标部署可以替换它，但不能抑制它。适配器会直接验证 wire 标头，或通过自身库 hook 验证。详见 [归因 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md)。
+每个产品适配器都会在提供方 HTTP 请求上发送应用身份。`attributionHeaders(identity?)` 构建标准 `User-Agent`，默认为公开 `APP_IDENTITY`；白标部署可以替换它，但不能抑制它。适配器会直接验证 wire 标头，或通过自身库 hook 验证。详见 [归因 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.zh.md)。
 
 ### API 密钥校验（`api-key.ts`）
 
@@ -85,7 +89,7 @@
 
 ### 真实适配器
 
-两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek-official` 路由使用直接 fetch 加 `eventsource-parser` SSE（Server-Sent Events）分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `types.ts` 中的 `StreamChunk` 约定：usage 先于 finish，工具参数保持原始字符串。适配器实现在内部可以抛出异常或发出失败 finish；`LlmRuntime` 会将两者都暴露为终止失败 finish。适配器理由见[双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，服务边界见[终止失败决策](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.md)。
+两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek-official` 路由使用直接 fetch 加 `eventsource-parser` SSE（Server-Sent Events）分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `types.ts` 中的 `StreamChunk` 约定：usage 先于 finish，工具参数保持原始字符串。适配器实现在内部可以抛出异常或发出失败 finish；`LlmRuntime` 会将两者都暴露为终止失败 finish。适配器理由见[双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.zh.md)，服务边界见[终止失败决策](../../../.agents/notes/implemented/architecture/2026-07-29-terminal-llm-stream-failures.zh.md)。
 
 ## 模型体验
 
@@ -95,6 +99,8 @@
 
 透传；注册表保留已组装请求前缀，cache 复用与路由边界属于所选适配器和提供方。
 
+<a id="known-limitations-and-deferred-work"></a>
+
 ## 已知限制与暂缓事项
 
 - **本服务不执行重试、缓存或速率限制**：提供方注册会存储重试策略，但 `llm/stream` 仍是单次尝试调用包装层。agent loop 会将已验证模型请求失败单独提供给 `agent/request-error`，其默认行为是保留原始失败；`@deepseek-ai/dsh-llm-retry` 是共享示例主干加载的可选执行器。

package/lib/index.js

@@ -580,72 +580,26 @@ function normalizeApiKey(raw) {
 	};
 }
 //#endregion
-//#region lib/types/attribution.js
-/**
-* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
-* adapters from drifting. See
-* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
-*
-* App-attribution vocabulary for provider requests.
-* @module @deepseek-ai/dsh-llm/attribution
-*/
-const { version } = createRequire(import.meta.url)("../package.json");
-/**
-* The harness's own identity: the default every adapter sends. Deployments
-* that need a white-label identity pass their own {@link AppIdentity} to
-* {@link attributionHeaders} — omission falls back to this default; nothing
-* can suppress attribution entirely.
-*/
-const APP_IDENTITY = {
-	product: "deepseek-harness",
-	version,
-	url: "https://github.com/deepseek-ai/deepseek-harness"
-};
+//#region lib/types/content.js
+/** Content-block structure helpers. @module @deepseek-ai/dsh-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.]";
 /**
-* The standard `User-Agent` value: `product/version (+url)`. The
-* parenthesized `+url` comment is the conventional self-identification form
-* (RFC 9110 §10.1.5 product + comment syntax).
-* @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
-* @returns the ready-to-send header value.
+* 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 userAgent(identity = APP_IDENTITY) {
-	return `${identity.product}/${identity.version} (+${identity.url})`;
+function textOnlyImageText(ref) {
+	return `[image omitted because this model accepts text only; attachment sha256:${String(ref.attachmentId).slice(7, 15)}]`;
 }
 /**
-* Build the attribution headers an adapter must send on every provider
-* request. Header names are lowercase (HTTP field names are case-insensitive
-* on the wire).
-* @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
-* @returns headers to merge into the provider request (currently just `user-agent`).
+* 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 attributionHeaders(identity = APP_IDENTITY) {
-	return { "user-agent": userAgent(identity) };
+function requestImageHandleText(version) {
+	return `Image ${version.attachment.attachmentId}; request image ${version.width}x${version.height}px.`;
 }
-//#endregion
-//#region lib/types/never.js
-/**
-* Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
-* new variant fails compilation at every required handler. Do not use it for declaration-merged
-* unions such as session events or content blocks: handle known variants and explicitly fall
-* through because plugins may add valid unknown cases.
-* @module @deepseek-ai/dsh-llm/never
-*/
-/**
-* Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
-* a value that escaped its type throws with diagnostics at runtime.
-* @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
-* @param context - optional label (e.g. the switch site) prefixed into the throw message.
-* @returns never — it always throws, with the offending value JSON-rendered in the message.
-*/
-function assertNever(value, context) {
-	const rendered = JSON.stringify(value) ?? String(value);
-	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
-}
-//#endregion
-//#region lib/types/content.js
-/** Content-block structure helpers. @module @deepseek-ai/dsh-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.]";
 /**
 * True when typed model content contains an image block, walking nested
 * tool-result content. This is the one recursive image walk shared by every
@@ -661,10 +615,12 @@ function contentHasImage(content) {
 function base64Length(bytes) {
 	return Math.ceil(bytes / 3) * 4;
 }
-/** Collect base64 payload lengths in request and nested-block order. */
-function collectImageLengths(blocks, lengths) {
-	for (const block of blocks) if (block.type === "image") lengths.push(base64Length(block.attachment.bytes));
-	else if (block.type === "tool-result") collectImageLengths(block.content, lengths);
+/** 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) {
@@ -694,6 +650,48 @@ function replaceOldestImages(blocks, remaining) {
 	}
 	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
@@ -704,17 +702,41 @@ function replaceOldestImages(blocks, remaining) {
 * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
 */
 function offloadRequestImages(messages, maxRequestImageBytes) {
-	if (maxRequestImageBytes === void 0) return messages;
+	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);
-	let total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+	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;
-	for (const bytes of lengths) {
-		if (total <= maxRequestImageBytes) break;
-		total -= bytes;
+	let removedBytes = 0;
+	for (const imageBytes of lengths) {
+		if (count >= removeCount && (removeBytes === 0 || (byteQuantum === 1 ? removedBytes >= removeBytes : removedBytes > removeBytes))) break;
+		removedBytes += imageBytes;
 		count += 1;
 	}
-	if (count === 0) return messages;
 	const remaining = { count };
 	return messages.map((message) => {
 		const content = replaceOldestImages(message.content, remaining);
@@ -725,6 +747,68 @@ function offloadRequestImages(messages, maxRequestImageBytes) {
 	});
 }
 //#endregion
+//#region lib/types/attribution.js
+/**
+* Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
+* adapters from drifting. See
+* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+*
+* App-attribution vocabulary for provider requests.
+* @module @deepseek-ai/dsh-llm/attribution
+*/
+const { version } = createRequire(import.meta.url)("../package.json");
+/**
+* The harness's own identity: the default every adapter sends. Deployments
+* that need a white-label identity pass their own {@link AppIdentity} to
+* {@link attributionHeaders} — omission falls back to this default; nothing
+* can suppress attribution entirely.
+*/
+const APP_IDENTITY = {
+	product: "deepseek-harness",
+	version,
+	url: "https://github.com/deepseek-ai/deepseek-harness"
+};
+/**
+* The standard `User-Agent` value: `product/version (+url)`. The
+* parenthesized `+url` comment is the conventional self-identification form
+* (RFC 9110 §10.1.5 product + comment syntax).
+* @param identity - the identity to render; defaults to {@link APP_IDENTITY}.
+* @returns the ready-to-send header value.
+*/
+function userAgent(identity = APP_IDENTITY) {
+	return `${identity.product}/${identity.version} (+${identity.url})`;
+}
+/**
+* Build the attribution headers an adapter must send on every provider
+* request. Header names are lowercase (HTTP field names are case-insensitive
+* on the wire).
+* @param identity - the identity to send; defaults to {@link APP_IDENTITY} — omission cannot suppress attribution.
+* @returns headers to merge into the provider request (currently just `user-agent`).
+*/
+function attributionHeaders(identity = APP_IDENTITY) {
+	return { "user-agent": userAgent(identity) };
+}
+//#endregion
+//#region lib/types/never.js
+/**
+* Exhaustiveness helper for closed core unions. Use {@link assertNever} at the default branch so a
+* new variant fails compilation at every required handler. Do not use it for declaration-merged
+* unions such as session events or content blocks: handle known variants and explicitly fall
+* through because plugins may add valid unknown cases.
+* @module @deepseek-ai/dsh-llm/never
+*/
+/**
+* Mark an unreachable closed-union branch. A newly unhandled typed variant fails at the call site;
+* a value that escaped its type throws with diagnostics at runtime.
+* @param value - the impossible value; typed `never` so an unhandled variant fails compilation at the call site.
+* @param context - optional label (e.g. the switch site) prefixed into the throw message.
+* @returns never — it always throws, with the offending value JSON-rendered in the message.
+*/
+function assertNever(value, context) {
+	const rendered = JSON.stringify(value) ?? String(value);
+	throw new Error(`unreachable variant${context ? ` in ${context}` : ""}: ${rendered}`);
+}
+//#endregion
 //#region lib/types/assembler.js
 /**
 * Incremental chunk-to-message assembler. This is the single canonical assembly
@@ -1030,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
@@ -1299,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");
@@ -1353,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
@@ -1374,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
 		};
 	}
 	/**
@@ -1387,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({
@@ -1400,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)
 				});
 			}
 		});
@@ -1447,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,
@@ -1456,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;
@@ -1523,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, 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, 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/lib/types/content.d.ts

@@ -1,8 +1,21 @@
 /** 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.]";
+/**
+ * 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
@@ -12,6 +25,27 @@ export declare const OFFLOADED_IMAGE_TEXT = "[image omitted to keep the request
  * @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
@@ -22,4 +56,16 @@ export declare function contentHasImage(content: readonly ContentBlock[]): boole
  * @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/lib/types/content.js

@@ -1,6 +1,23 @@
 /** 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.]';
+/**
+ * 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
@@ -17,14 +34,17 @@ export function contentHasImage(content) {
 function base64Length(bytes) {
     return Math.ceil(bytes / 3) * 4;
 }
-/** Collect base64 payload lengths in request and nested-block order. */
-function collectImageLengths(blocks, lengths) {
+/** Collect represented image lengths in request and nested-block order. */
+function collectImageLengths(blocks, lengths, policy) {
     for (const block of blocks) {
         if (block.type === 'image') {
-            lengths.push(base64Length(block.attachment.bytes));
+            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);
+            collectImageLengths(block.content, lengths, policy);
         }
     }
 }
@@ -50,6 +70,40 @@ function replaceOldestImages(blocks, remaining) {
     }
     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
@@ -60,21 +114,46 @@ function replaceOldestImages(blocks, remaining) {
  * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
  */
 export function offloadRequestImages(messages, maxRequestImageBytes) {
-    if (maxRequestImageBytes === undefined)
-        return messages;
+    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);
-    let total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+        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;
-    for (const bytes of lengths) {
-        if (total <= maxRequestImageBytes)
+    let removedBytes = 0;
+    for (const imageBytes of lengths) {
+        const byteTargetMet = removeBytes === 0
+            || (byteQuantum === 1 ? removedBytes >= removeBytes : removedBytes > removeBytes);
+        if (count >= removeCount && byteTargetMet)
             break;
-        total -= bytes;
+        removedBytes += imageBytes;
         count += 1;
     }
-    if (count === 0)
-        return messages;
     const remaining = { count };
     return messages.map((message) => {
         const content = replaceOldestImages(message.content, remaining);

package/lib/types/index.d.ts

@@ -6,7 +6,7 @@
  * @module @deepseek-ai/dsh-llm
  */
 import { Context, Service } from '@deepseek-ai/cordis';
-import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, StreamChunk } from './types.ts';
+import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, ModelModality, StreamChunk } from './types.ts';
 import type { ResolvedRetryPolicy } from './retry-policy.ts';
 import type { ProviderRequestId } from './brand.ts';
 import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
@@ -93,6 +93,8 @@ export interface PreparedLlmCall {
     readonly retryPolicy: ResolvedRetryPolicy;
     /** Detached context metadata resolved with the registration-bound call. */
     readonly context?: LlmModelContext;
+    /** Exact model modalities captured with the adapter dispatch generation. */
+    readonly inputModalities?: readonly ModelModality[];
     /** Config fields materialized by the captured adapter rather than proposed by the caller. */
     readonly adapterDefaults: LlmCallConfigAdapterDefaults;
     /**
@@ -104,6 +106,13 @@ export interface PreparedLlmCall {
      */
     stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
 }
+/** One adapter-owned model-resolution generation bound to its eventual stream call. */
+export interface PreparedAdapterCall {
+    /** Exact model metadata from the same adapter generation as {@link stream}. */
+    readonly model: LlmResolvedModelInfo;
+    /** Dispatch through that generation without re-reading dynamic connection facts. */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
 /**
  * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
  * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
@@ -141,6 +150,16 @@ export declare abstract class LlmAdapter {
      * @returns provider/model identity plus any context, call-default, and reasoning metadata.
      */
     resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /**
+     * 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.
+     */
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
     /**
      * Stream one model call as raw chunks. The only required method.
      * @param options - the fully-assembled request; implementations must honor `options.signal`.
@@ -293,6 +312,8 @@ export declare class LlmRuntime extends Service {
      */
     resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
     private resolveModelInfoFor;
+    /** Validate and detach one adapter-returned exact model result. */
+    private normalizeModelInfo;
     /**
      * Validate a conversation call config against its exact model capability and
      * materialize adapter-configured defaults. Unsupported explicit efforts
@@ -305,6 +326,8 @@ export declare class LlmRuntime extends Service {
      */
     resolveCallConfig(config: LlmCallConfig, signal?: AbortSignal): Promise<LlmCallConfig>;
     private resolveCallFor;
+    /** Validate request controls against one already-bound exact model result. */
+    private resolveCallWithInfo;
     /**
      * Resolve one call under its current adapter registration. The returned
      * one-shot handle keeps that registration across header logging and dispatch,

package/lib/types/index.js

@@ -12,6 +12,7 @@ import { callConfigEquals, deepFreeze } from "./call-config.js";
 import { HarnessError, INVALID_CREDENTIAL_CODE } from "./error.js";
 import { normalizeLlmFailure } from "./adapter-failure.js";
 import { normalizeApiKey } from "./api-key.js";
+import { contentHasImage, projectImagesForTextModel } from "./content.js";
 export * from "./attribution.js";
 export * from "./brand.js";
 export * from "./never.js";
@@ -140,6 +141,21 @@ export class LlmAdapter {
     resolveModel(provider, model, _signal) {
         return Promise.resolve({ provider, id: model, 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
@@ -466,8 +482,12 @@ export class LlmRuntime 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'
@@ -547,6 +567,10 @@ export class LlmRuntime 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 === undefined && info.defaultMaxTokens !== undefined
             ? { ...config, maxTokens: info.defaultMaxTokens }
             : config;
@@ -571,6 +595,7 @@ export class LlmRuntime extends Service {
         return {
             config: resolvedConfig,
             ...info.context === undefined ? {} : { context: info.context },
+            modelInfo: info,
         };
     }
     /**
@@ -583,7 +608,9 @@ export class LlmRuntime 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 === undefined
             ? undefined
@@ -602,6 +629,9 @@ export class LlmRuntime extends Service {
             retryPolicy: registration.retryPolicy,
             adapterDefaults,
             ...context === undefined ? {} : { context },
+            ...modelInfo.inputModalities === undefined
+                ? {}
+                : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
             stream: (options) => {
                 if (dispatched) {
                     throw new LlmError('a prepared LLM call can only be dispatched once', 'INVALID_PREPARED_CALL');
@@ -610,7 +640,12 @@ export class LlmRuntime extends Service {
                     throw new LlmError('prepared LLM call config changed before adapter dispatch', 'INVALID_PREPARED_CALL');
                 }
                 dispatched = true;
-                return this.streamWithRegistration(options, { registration, config: resolvedConfig });
+                return this.streamWithRegistration(options, {
+                    registration,
+                    config: resolvedConfig,
+                    modelInfo,
+                    dispatch: options => adapterCall.stream(options),
+                });
             },
         });
     }
@@ -647,9 +682,21 @@ export class LlmRuntime extends Service {
         let iterator;
         try {
             const registration = prepared?.registration ?? this.registration(options.provider);
-            const resolvedConfig = prepared === undefined
-                ? (await this.resolveCallFor(registration, options, options.signal)).config
-                : prepared.config;
+            const adapter = registration.adapter;
+            let modelInfo;
+            let resolvedConfig;
+            let dispatch;
+            if (prepared === undefined) {
+                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 !== undefined && !callConfigEquals(options, resolvedConfig)) {
                 throw new LlmError('prepared LLM call config changed before adapter dispatch', 'INVALID_PREPARED_CALL');
             }
@@ -658,8 +705,14 @@ export class LlmRuntime extends Service {
                 : Object.isFrozen(options)
                     ? deepFreeze({ ...options, ...resolvedConfig })
                     : { ...options, ...resolvedConfig };
-            const adapter = registration.adapter;
-            const stream = adapter.stream(this.forAdapter(resolvedOptions, adapter));
+            const projectedOptions = modelInfo.inputModalities !== undefined
+                && !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;
+            const stream = dispatch(this.forAdapter(projectedOptions, adapter));
             iterator = stream[Symbol.asyncIterator]();
         }
         catch (error) {

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.0-rc.8",
+  "version": "0.1.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -45,20 +45,20 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-brand": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-brand": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-timeout": "^0.1.0-rc.8",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-attachment": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
   }
 }