@deepseek-ai/dsh-llm 0.1.0-rc.7 → 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: fb6bd84240b41dd730d45b3eb34c35827dc4c991
-README.zh.md: 5c22767a7c654972cbf614505382fa4755d7d318
+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.

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([])` 合法，表示保留注册但不持有任何路由；初始注册则不得为空。

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
@@ -797,6 +872,21 @@ var BlockAssembler = class {
 	blocks() {
 		return this.assembled().blocks;
 	}
+	/**
+	* Assemble the prefix an interrupted stream can safely finalize: closed and
+	* open text/reasoning blocks with non-whitespace content, in stream order.
+	* Tool calls are omitted because interruption precedes dispatch; retaining
+	* one would require a fabricated result. Open unknown blocks are also omitted.
+	* @returns the kept blocks; empty when nothing streamed before the interruption.
+	*/
+	interruptedBlocks() {
+		return this.order.map((index) => {
+			const partial = this.mustGet(index);
+			const type = partial.block?.type ?? partial.blockType;
+			if (type !== "text" && type !== "reasoning") return void 0;
+			return this.assemble(partial, index);
+		}).filter((block) => (block?.type === "text" || block?.type === "reasoning") && block.text.trim() !== "");
+	}
 	/** Usage from the `usage` chunk; undefined until one arrives. */
 	get usage() {
 		return this._usage;
@@ -1433,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

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

package/lib/types/assembler.js

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

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