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

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: 2cae9a05a58295b06d25382729a3304dbdc9a6fa
-README.zh.md: 110cc128f1c19bef1741ae59d8106139c4a72649
+README.md: e6b3c4924ad4e7cf115abdbfb38d22d0f524e377
+README.zh.md: 51f034af632c19ca91c1d2f91a7c9c22714870e0

package/README.md

@@ -8,6 +8,10 @@ Provider-neutral LLM vocabulary and abstract service. This package defines the c
 
 An adapter registry plus a single streaming call API, interceptable via a waterfall event.
 
+### Retry policy
+
+Each provider adapter supplies its resolved route policy. Omitting provider configuration uses bounded normal mode with five retries after the first request. Layered configuration may retain `maxRetries` or `retryableCodes` after changing `mode` to `always`; resolution ignores those inactive normal-mode fields and captures a pure always policy. This service stores the effective policy but does not execute retries.
+
 ### Public API
 
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle` Register one adapter instance for the given provider routes. Registration is all-or-nothing, and is disposed with the calling fiber. The returned disposer also carries `replace(providers)`: the candidate route set is validated in full before anything moves, so a conflict with another adapter leaves the current routes registered and serving, and the swap itself is one synchronous section with no observable gap. `replace([])` is legal — a registration holding zero routes — unlike an empty initial registration.
@@ -53,7 +57,7 @@ Exact-model metadata is a separate correctness query, not a catalog decoration o
 
 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.
 
-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.
+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.
 
 ### Call configuration (`call-config.ts`)
 

package/README.zh.md

@@ -8,6 +8,10 @@
 
 一个适配器注册表加单一流式调用接口，可通过 waterfall（瀑布式事件）拦截。
 
+### 重试策略
+
+每个提供方适配器都会提供解析后的路由策略。省略提供方配置时使用有界 normal mode，在首次请求后最多重试五次。分层配置把 `mode` 改为 `always` 后可能残留 `maxRetries` 或 `retryableCodes`；解析过程会忽略这些不再生效的 normal-mode 字段，并捕获纯 always 策略。本服务存储有效策略，但不执行重试。
+
 ### 公开 API
 
 - `ctx.llm.registerAdapter(providers: string[], adapter: LlmAdapter): AdapterRegistrationHandle` 为给定提供方路由注册一个适配器实例。注册要么全部成功，要么全部不生效，并且会随调用 fiber 一起 dispose（资源释放）。返回的句柄还提供 `replace(providers)`：候选路由集合会在注册状态发生任何变化前完成整体验证，因此与另一适配器发生冲突时，当前路由仍保持注册并继续提供服务。替换会在一次同步操作中完成，不会出现可观察的空档。`replace([])` 合法，表示保留注册但不持有任何路由；初始注册则不得为空。
@@ -53,7 +57,7 @@
 
 消息内容是类型化内容块数组：`text`、`reasoning`、`tool-call`、`tool-result`。联合从可合并扩展的 `ContentBlockMap` 派生，因此插件可以通过 declaration merging 添加块类型。assistant 消息使用模型来源，其中携带生成该消息的提供方和模型，以及可选的适配器私有回放状态。dispatch 前，`LlmRuntime` 只在历史提供方路由与目标提供方路由当前由完全相同的适配器实例拥有时才保留该状态；随后由适配器判定能否在模型／提供方间恢复或转换该状态。核心块集只包含每条已发布路径都支持的块。多模态内容（图像、音频等）没有核心块类型；需要它的功能会通过 map 添加，并一并添加相应的适配器／UI／压缩（compaction）支持。
 
-流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用 `error` 或 `aborted` 作为结束原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。
+流式输出是原始分片协议（`block-start`、`text-delta`、`reasoning-delta`、`tool-call-delta`、`block-end`、`usage`、`finish`）。每个适配器结果都以一个终止 `finish` 到达消费方；运行故障使用 `error` 或 `aborted` 作为结束原因，而不会跨流 API 抛出。`BlockAssembler` 是将分片组装为块／消息的唯一共享实现。成功的 `finish` 可以携带 `ReplayEnvelope`——不透明的响应级回放元数据，加上与发射块序列对齐的可选逐块条目。组装对内容与元数据只做一次保留/丢弃决定：`max-tokens` 结束会丢弃可能被截断的工具调用，数据在每个被丢弃的位置同步失去对应条目，因此存储的元数据始终描述存储的内容。
 
 ### 调用配置（`call-config.ts`）
 

package/lib/index.js

@@ -353,7 +353,7 @@ function isHarnessError(value) {
 *
 * @module @deepseek-ai/dsh-llm/retry-policy
 */
-const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRIES = 5;
 const DEFAULT_INITIAL_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 1e4;
 const DEFAULT_JITTER_RATIO = .1;
@@ -387,7 +387,12 @@ const NORMAL_POLICY_KEYS = new Set([
 	"retryableCodes",
 	"backoff"
 ]);
-const ALWAYS_POLICY_KEYS = new Set(["mode", "backoff"]);
+const ALWAYS_POLICY_KEYS = new Set([
+	"mode",
+	"maxRetries",
+	"retryableCodes",
+	"backoff"
+]);
 const BACKOFF_KEYS = new Set([
 	"initialDelayMs",
 	"maxDelayMs",
@@ -639,6 +644,8 @@ function assertNever(value, context) {
 //#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
@@ -650,6 +657,73 @@ function assertNever(value, context) {
 function contentHasImage(content) {
 	return content.some((block) => block.type === "image" || block.type === "tool-result" && contentHasImage(block.content));
 }
+/** Base64 length of raw image bytes, including padding. */
+function base64Length(bytes) {
+	return Math.ceil(bytes / 3) * 4;
+}
+/** Collect 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);
+}
+/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
+function replaceOldestImages(blocks, remaining) {
+	let next;
+	for (const [index, block] of blocks.entries()) {
+		if (block.type === "image" && remaining.count > 0) {
+			remaining.count -= 1;
+			next ??= blocks.slice(0, index);
+			next.push({
+				type: "text",
+				text: OFFLOADED_IMAGE_TEXT
+			});
+			continue;
+		}
+		if (block.type === "tool-result") {
+			const content = replaceOldestImages(block.content, remaining);
+			if (content !== block.content) {
+				next ??= blocks.slice(0, index);
+				next.push({
+					...block,
+					content
+				});
+				continue;
+			}
+		}
+		next?.push(block);
+	}
+	return next ?? blocks;
+}
+/**
+* Return transient request messages whose oldest images are replaced until
+* their accumulated base64 payload fits the configured bound. The selection
+* is deterministic from durable message order and attachment metadata; a
+* provider can serialize the returned messages without reading omitted bytes.
+* @param messages - complete request history, oldest first.
+* @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+* @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+*/
+function offloadRequestImages(messages, maxRequestImageBytes) {
+	if (maxRequestImageBytes === void 0) return messages;
+	const lengths = [];
+	for (const message of messages) collectImageLengths(message.content, lengths);
+	let total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+	let count = 0;
+	for (const bytes of lengths) {
+		if (total <= maxRequestImageBytes) break;
+		total -= bytes;
+		count += 1;
+	}
+	if (count === 0) return messages;
+	const remaining = { count };
+	return messages.map((message) => {
+		const content = replaceOldestImages(message.content, remaining);
+		return content === message.content ? message : {
+			...message,
+			content
+		};
+	});
+}
 //#endregion
 //#region lib/types/assembler.js
 /**
@@ -664,7 +738,8 @@ function contentHasImage(content) {
 * {@link ContentBlock}s and a final assistant {@link Message}.
 *
 * The agent loop feeds it while logging raw chunks for replay fidelity, then
-* reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+* reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+* or `interruptedBlocks()` when cancellation cut the stream short.
 *
 * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
 * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -675,7 +750,7 @@ var BlockAssembler = class {
 	order = [];
 	_usage;
 	_finish;
-	_replayState = void 0;
+	_replayState;
 	/**
 	* Feed one chunk into the assembly state.
 	* @param chunk - the next raw chunk, in stream order.
@@ -763,14 +838,54 @@ var BlockAssembler = class {
 		return partial;
 	}
 	/**
+	* The one shared keep/drop decision over all seen blocks: max-token
+	* truncation drops tool calls that cannot be executed safely. Emitted blocks
+	* and replay metadata both derive from this result, so they cannot disagree.
+	*/
+	assembled() {
+		const all = this.order.map((index) => this.assemble(this.mustGet(index), index));
+		const kept = this.finish.kind === "max-tokens" ? all.map((block) => block.type !== "tool-call") : void 0;
+		const blocks = kept === void 0 ? all : all.filter((_, position) => kept[position]);
+		const envelope = this._replayState;
+		if (envelope?.blocks === void 0) return {
+			blocks,
+			replay: envelope
+		};
+		if (envelope.blocks.length !== all.length) return {
+			blocks,
+			replay: void 0
+		};
+		return {
+			blocks,
+			replay: kept === void 0 || blocks.length === all.length ? envelope : {
+				response: envelope.response,
+				blocks: envelope.blocks.filter((_, position) => kept[position])
+			}
+		};
+	}
+	/**
 	* Assemble all blocks seen so far, in stream order.
 	* @returns one block per seen index, except that max-token truncation drops
 	*   tool calls that cannot be executed safely; an open block assembles from
 	*   its accumulated deltas (an unknown block type never closed by `block-end` throws).
 	*/
 	blocks() {
-		const blocks = this.order.map((index) => this.assemble(this.mustGet(index), index));
-		return this.finish.kind === "max-tokens" ? blocks.filter((block) => block.type !== "tool-call") : blocks;
+		return this.assembled().blocks;
+	}
+	/**
+	* Assemble the prefix an interrupted stream can safely finalize: closed and
+	* open text/reasoning blocks with non-whitespace content, in stream order.
+	* Tool calls are omitted because interruption precedes dispatch; retaining
+	* one would require a fabricated result. Open unknown blocks are also omitted.
+	* @returns the kept blocks; empty when nothing streamed before the interruption.
+	*/
+	interruptedBlocks() {
+		return this.order.map((index) => {
+			const partial = this.mustGet(index);
+			const type = partial.block?.type ?? partial.blockType;
+			if (type !== "text" && type !== "reasoning") return void 0;
+			return this.assemble(partial, index);
+		}).filter((block) => (block?.type === "text" || block?.type === "reasoning") && block.text.trim() !== "");
 	}
 	/** Usage from the `usage` chunk; undefined until one arrives. */
 	get usage() {
@@ -780,9 +895,13 @@ var BlockAssembler = class {
 	get finish() {
 		return this._finish ?? { kind: "stop" };
 	}
-	/** Adapter-private replay state from the terminal finish chunk, if any. */
+	/**
+	* Replay metadata from the terminal finish chunk, if any, with per-block
+	* entries pruned in step with {@link blocks}. Undefined when the envelope's
+	* entries do not align with the emitted blocks.
+	*/
 	get replayState() {
-		return this._replayState;
+		return this.assembled().replay;
 	}
 	/**
 	* The assembled assistant message.
@@ -1404,4 +1523,4 @@ function adapterFailureChunk(error, signal) {
 	};
 }
 //#endregion
-export { APP_IDENTITY, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, HarnessError, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertNever, assertUsableApiKey, attributionHeaders, boundContextSummary, callConfigEquals, contentHasImage, createAssistantMessage, createMessage, createToolResultMessage, createUserMessage, deepFreeze, errorChain, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, markAgentLoopRequest, normalizeApiKey, resolveRetryPolicy, userAgent };
+export { APP_IDENTITY, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, CallId, EMPTY_RESPONSE_CODE, HarnessError, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmError, LlmRuntime, LlmRuntime as default, MessageId, OFFLOADED_IMAGE_TEXT, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, assertNever, assertUsableApiKey, attributionHeaders, boundContextSummary, callConfigEquals, contentHasImage, createAssistantMessage, createMessage, createToolResultMessage, createUserMessage, deepFreeze, errorChain, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, markAgentLoopRequest, normalizeApiKey, offloadRequestImages, resolveRetryPolicy, userAgent };

package/lib/types/assembler.d.ts

@@ -6,13 +6,14 @@
  * @module @deepseek-ai/dsh-llm/assembler
  */
 import type { Message, MessageSource } from './message.ts';
-import type { ContentBlock, FinishReason, StreamChunk, TokenUsage } from './types.ts';
+import type { ContentBlock, FinishReason, ReplayEnvelope, StreamChunk, TokenUsage } from './types.ts';
 /**
  * Incrementally assembles raw {@link StreamChunk}s into complete
  * {@link ContentBlock}s and a final assistant {@link Message}.
  *
  * The agent loop feeds it while logging raw chunks for replay fidelity, then
- * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
  *
  * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
  * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -33,6 +34,12 @@ export declare class BlockAssembler {
     private assemble;
     /** Invariant accessor: every index in `order` has a partial. */
     private mustGet;
+    /**
+     * The one shared keep/drop decision over all seen blocks: max-token
+     * truncation drops tool calls that cannot be executed safely. Emitted blocks
+     * and replay metadata both derive from this result, so they cannot disagree.
+     */
+    private assembled;
     /**
      * Assemble all blocks seen so far, in stream order.
      * @returns one block per seen index, except that max-token truncation drops
@@ -40,12 +47,24 @@ export declare class BlockAssembler {
      *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
      */
     blocks(): ContentBlock[];
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks(): ContentBlock[];
     /** Usage from the `usage` chunk; undefined until one arrives. */
     get usage(): TokenUsage | undefined;
     /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
     get finish(): FinishReason;
-    /** Adapter-private replay state from the terminal finish chunk, if any. */
-    get replayState(): unknown;
+    /**
+     * Replay metadata from the terminal finish chunk, if any, with per-block
+     * entries pruned in step with {@link blocks}. Undefined when the envelope's
+     * entries do not align with the emitted blocks.
+     */
+    get replayState(): ReplayEnvelope | undefined;
     /**
      * The assembled assistant message.
      * @param source - producer attribution for the assembled message.

package/lib/types/assembler.js

@@ -13,7 +13,8 @@ import { createMessage } from "./message.js";
  * {@link ContentBlock}s and a final assistant {@link Message}.
  *
  * The agent loop feeds it while logging raw chunks for replay fidelity, then
- * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends,
+ * or `interruptedBlocks()` when cancellation cut the stream short.
  *
  * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
  * an index already closed by `block-end` are ignored (malformed stream) so a
@@ -24,7 +25,7 @@ export class BlockAssembler {
     order = [];
     _usage;
     _finish;
-    _replayState = undefined;
+    _replayState;
     /**
      * Feed one chunk into the assembly state.
      * @param chunk - the next raw chunk, in stream order.
@@ -112,6 +113,29 @@ export class BlockAssembler {
             throw new Error(`BlockAssembler invariant violated: no partial for index ${index}`);
         return partial;
     }
+    /**
+     * The one shared keep/drop decision over all seen blocks: max-token
+     * truncation drops tool calls that cannot be executed safely. Emitted blocks
+     * and replay metadata both derive from this result, so they cannot disagree.
+     */
+    assembled() {
+        const all = this.order.map(index => this.assemble(this.mustGet(index), index));
+        const kept = this.finish.kind === 'max-tokens'
+            ? all.map(block => block.type !== 'tool-call')
+            : undefined;
+        const blocks = kept === undefined ? all : all.filter((_, position) => kept[position]);
+        const envelope = this._replayState;
+        if (envelope?.blocks === undefined)
+            return { blocks, replay: envelope };
+        if (envelope.blocks.length !== all.length)
+            return { blocks, replay: undefined };
+        return {
+            blocks,
+            replay: kept === undefined || blocks.length === all.length
+                ? envelope
+                : { response: envelope.response, blocks: envelope.blocks.filter((_, position) => kept[position]) },
+        };
+    }
     /**
      * Assemble all blocks seen so far, in stream order.
      * @returns one block per seen index, except that max-token truncation drops
@@ -119,10 +143,25 @@ export class BlockAssembler {
      *   its accumulated deltas (an unknown block type never closed by `block-end` throws).
      */
     blocks() {
-        const blocks = this.order.map(index => this.assemble(this.mustGet(index), index));
-        return this.finish.kind === 'max-tokens'
-            ? blocks.filter(block => block.type !== 'tool-call')
-            : blocks;
+        return this.assembled().blocks;
+    }
+    /**
+     * Assemble the prefix an interrupted stream can safely finalize: closed and
+     * open text/reasoning blocks with non-whitespace content, in stream order.
+     * Tool calls are omitted because interruption precedes dispatch; retaining
+     * one would require a fabricated result. Open unknown blocks are also omitted.
+     * @returns the kept blocks; empty when nothing streamed before the interruption.
+     */
+    interruptedBlocks() {
+        return this.order
+            .map((index) => {
+            const partial = this.mustGet(index);
+            const type = partial.block?.type ?? partial.blockType;
+            if (type !== 'text' && type !== 'reasoning')
+                return undefined;
+            return this.assemble(partial, index);
+        })
+            .filter((block) => (block?.type === 'text' || block?.type === 'reasoning') && block.text.trim() !== '');
     }
     /** Usage from the `usage` chunk; undefined until one arrives. */
     get usage() {
@@ -132,9 +171,13 @@ export class BlockAssembler {
     get finish() {
         return this._finish ?? { kind: 'stop' };
     }
-    /** Adapter-private replay state from the terminal finish chunk, if any. */
+    /**
+     * Replay metadata from the terminal finish chunk, if any, with per-block
+     * entries pruned in step with {@link blocks}. Undefined when the envelope's
+     * entries do not align with the emitted blocks.
+     */
     get replayState() {
-        return this._replayState;
+        return this.assembled().replay;
     }
     /**
      * The assembled assistant message.

package/lib/types/content.d.ts

@@ -1,5 +1,8 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-llm/content */
 import type { ContentBlock } from './types.ts';
+import type { Message } from './message.ts';
+/** 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.]";
 /**
  * True when typed model content contains an image block, walking nested
  * tool-result content. This is the one recursive image walk shared by every
@@ -9,4 +12,14 @@ import type { ContentBlock } from './types.ts';
  * @returns whether any nested block is an image.
  */
 export declare function contentHasImage(content: readonly ContentBlock[]): boolean;
+/**
+ * Return transient request messages whose oldest images are replaced until
+ * their accumulated base64 payload fits the configured bound. The selection
+ * is deterministic from durable message order and attachment metadata; a
+ * provider can serialize the returned messages without reading omitted bytes.
+ * @param messages - complete request history, oldest first.
+ * @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+ * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+ */
+export declare function offloadRequestImages(messages: readonly Message[], maxRequestImageBytes: number | undefined): readonly Message[];
 //# sourceMappingURL=content.d.ts.map

package/lib/types/content.js

@@ -1,4 +1,6 @@
 /** 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.]';
 /**
  * True when typed model content contains an image block, walking nested
  * tool-result content. This is the one recursive image walk shared by every
@@ -11,4 +13,72 @@ export function contentHasImage(content) {
     return content.some(block => block.type === 'image'
         || (block.type === 'tool-result' && contentHasImage(block.content)));
 }
+/** Base64 length of raw image bytes, including padding. */
+function base64Length(bytes) {
+    return Math.ceil(bytes / 3) * 4;
+}
+/** Collect 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);
+        }
+    }
+}
+/** Replace the first `remaining.count` image occurrences without mutating durable messages. */
+function replaceOldestImages(blocks, remaining) {
+    let next;
+    for (const [index, block] of blocks.entries()) {
+        if (block.type === 'image' && remaining.count > 0) {
+            remaining.count -= 1;
+            next ??= blocks.slice(0, index);
+            next.push({ type: 'text', text: OFFLOADED_IMAGE_TEXT });
+            continue;
+        }
+        if (block.type === 'tool-result') {
+            const content = replaceOldestImages(block.content, remaining);
+            if (content !== block.content) {
+                next ??= blocks.slice(0, index);
+                next.push({ ...block, content });
+                continue;
+            }
+        }
+        next?.push(block);
+    }
+    return next ?? blocks;
+}
+/**
+ * Return transient request messages whose oldest images are replaced until
+ * their accumulated base64 payload fits the configured bound. The selection
+ * is deterministic from durable message order and attachment metadata; a
+ * provider can serialize the returned messages without reading omitted bytes.
+ * @param messages - complete request history, oldest first.
+ * @param maxRequestImageBytes - positive bound on total base64 image payload; undefined preserves every image.
+ * @returns the original messages when they already fit, otherwise shallow message copies with replaced content trees.
+ */
+export function offloadRequestImages(messages, maxRequestImageBytes) {
+    if (maxRequestImageBytes === undefined)
+        return messages;
+    const lengths = [];
+    for (const message of messages)
+        collectImageLengths(message.content, lengths);
+    let total = lengths.reduce((sum, bytes) => sum + bytes, 0);
+    let count = 0;
+    for (const bytes of lengths) {
+        if (total <= maxRequestImageBytes)
+            break;
+        total -= bytes;
+        count += 1;
+    }
+    if (count === 0)
+        return messages;
+    const remaining = { count };
+    return messages.map((message) => {
+        const content = replaceOldestImages(message.content, remaining);
+        return content === message.content ? message : { ...message, content };
+    });
+}
 //# sourceMappingURL=content.js.map

package/lib/types/retry-policy.d.ts

@@ -20,7 +20,7 @@ export interface BackoffConfig {
 export interface NormalRetryPolicyConfig {
     /** Retry only configured transient failure codes. */
     mode: 'normal';
-    /** Maximum eligible retries after the first request (default 2). */
+    /** Maximum eligible retries after the first request (default 5). */
     maxRetries?: number;
     /** Stable failure codes eligible for this policy. */
     retryableCodes?: string[];

package/lib/types/retry-policy.js

@@ -9,7 +9,7 @@
 import z from '@deepseek-ai/schemastery';
 import { MAX_TIMER_DELAY_MS } from '@deepseek-ai/dsh-timeout';
 import { EMPTY_RESPONSE_CODE } from "./error.js";
-const DEFAULT_MAX_RETRIES = 2;
+const DEFAULT_MAX_RETRIES = 5;
 const DEFAULT_INITIAL_DELAY_MS = 500;
 const DEFAULT_MAX_DELAY_MS = 10_000;
 const DEFAULT_JITTER_RATIO = 0.1;
@@ -43,7 +43,11 @@ export const RetryPolicySchema = z.union([
 const NORMAL_POLICY_KEYS = new Set([
     'mode', 'maxRetries', 'retryableCodes', 'backoff',
 ]);
-const ALWAYS_POLICY_KEYS = new Set(['mode', 'backoff']);
+// Layered configuration can retain normal-only fields after switching modes;
+// always mode ignores those inactive values while still rejecting unknown keys.
+const ALWAYS_POLICY_KEYS = new Set([
+    'mode', 'maxRetries', 'retryableCodes', 'backoff',
+]);
 const BACKOFF_KEYS = new Set(['initialDelayMs', 'maxDelayMs', 'jitterRatio']);
 function validateKeys(value, allowed, path) {
     for (const key of Object.keys(value)) {

package/lib/types/types.d.ts

@@ -256,6 +256,26 @@ export interface LlmResolvedModelInfo extends LlmModelInfo {
     /** Adapter-owned selectable reasoning levels when exposed. */
     reasoning?: LlmModelReasoningInfo;
 }
+/**
+ * Adapter-private lossless-JSON state for replaying a successful response,
+ * carried by a terminal `finish` chunk and stored on the assembled assistant
+ * message's model source. Both halves stay opaque to the harness; only the
+ * split is shared vocabulary, so assembly can keep stored metadata aligned
+ * with stored content without reading either half.
+ */
+export interface ReplayEnvelope {
+    /** Response-level adapter-private metadata (ids, native stop reason). */
+    response: unknown;
+    /**
+     * Per-block adapter-private metadata, one entry per emitted block in
+     * first-seen stream order. When assembly drops a block it drops the entry at
+     * the same position; entries whose length does not match the emitted block
+     * count discard the whole envelope. An adapter whose metadata is independent
+     * of block structure omits this field and the envelope passes through
+     * assembly unchanged.
+     */
+    blocks?: readonly unknown[];
+}
 /**
  * Raw streaming protocol emitted by adapters.
  * Block indexes correlate interleaved deltas, and `block-end` carries the
@@ -292,8 +312,8 @@ export type StreamChunk = {
 } | {
     type: 'finish';
     reason: FinishReason;
-    /** Adapter-private lossless-JSON state for replaying a successful response. */
-    replayState?: unknown;
+    /** Replay metadata for a successful response; see {@link ReplayEnvelope}. */
+    replayState?: ReplayEnvelope;
 };
 /**
  * JSON-schema description of a tool, as sent to the model.

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