@deepseek-ai/dsh-llm 0.1.7-rc.1 → 0.2.0-rc.1

package/README.i18n.yaml

@@ -1,6 +1,64 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# 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:
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# 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: 04de24592379dcb0d815f3b033ca2f9f22e2ff6a
-README.zh.md: bee35d4a0b62dd61a61b435dfc4eb27b62cdce69
+/:
+  en: 860509fb08c860f4
+  zh: b2c4448e8afc1f12
+/deepseek-ai-dsh-llm:
+  en: 919467ab4b4ef583
+  zh: cb5752f140e58813
+/deepseek-ai-dsh-llm/summary:
+  en: 9b9ea6fea3088244
+  zh: 09f2eb6606a030da
+/deepseek-ai-dsh-llm/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/deepseek-ai-dsh-llm/use-this-package:
+  en: 33738e61ce410ac0
+  zh: 363760460f4d4bed
+/deepseek-ai-dsh-llm/use-this-package/when-to-choose-it:
+  en: c3ecb5a1421f27db
+  zh: 4bbd3c0e513845e1
+/deepseek-ai-dsh-llm/use-this-package/minimal-composition:
+  en: 7550d716b90fcb09
+  zh: 77891a44ee623c7a
+/deepseek-ai-dsh-llm/use-this-package/what-you-can-do:
+  en: b45d7a414141734e
+  zh: a641c8ea3827cee6
+/deepseek-ai-dsh-llm/use-this-package/failures-and-recovery:
+  en: 311d8c92447b7094
+  zh: 68cf5cb1c3853cc1
+/deepseek-ai-dsh-llm/understand-the-implementation:
+  en: 9630d7e26193a512
+  zh: 94222c2a487c4b8c
+/deepseek-ai-dsh-llm/understand-the-implementation/design-philosophy:
+  en: 12d0444c18a397c7
+  zh: 9d4a5468b4bb7fcd
+/deepseek-ai-dsh-llm/understand-the-implementation/source-map:
+  en: ae1618577f4e8364
+  zh: a6e8ab1563c08dfb
+/deepseek-ai-dsh-llm/understand-the-implementation/main-flow:
+  en: 6dc955a0d80f6ca0
+  zh: f81dbcaeacd8b269
+/deepseek-ai-dsh-llm/understand-the-implementation/invariants:
+  en: 0163a050239248e5
+  zh: 885c95bedcbe2ff4
+/deepseek-ai-dsh-llm/further-exploration:
+  en: 37e1d696afef8a88
+  zh: 81f99c4507663cad
+/deepseek-ai-dsh-llm/model-experience:
+  en: fa5677003ad6bc0a
+  zh: ba33cfc860d9c37c
+/deepseek-ai-dsh-llm/model-experience/kv-cache-effect:
+  en: a81634136baef72f
+  zh: b92dda883986b0e1
+/deepseek-ai-dsh-llm/known-limitations-and-deferred-work:
+  en: d60b9121545c99ec
+  zh: 3d4434a0e427470b
+/deepseek-ai-dsh-llm/known-limitations-and-deferred-work/dev-note:
+  en: ecbc333b88e14d88
+  zh: 77c725d92efd8646
+/deepseek-ai-dsh-llm/known-limitations-and-deferred-work/dev-note/open-items:
+  en: 6b1a7e903e13ee21
+  zh: bb62f2b1cc484bd5

package/README.md

@@ -25,6 +25,8 @@ Use `@deepseek-ai/dsh-llm` to stream model calls through configured provider ada
 <a id="use-this-package"></a>
 ## Use this package
 
+`listModels` describes models offered by catalog-driven interfaces. Core resolution and streaming can still accept unlisted ids. The GUI requires catalog membership for selection and submission; adapters intended for GUI use must implement `listModels` and advertise their available models. The base implementation returns an empty list and therefore offers no GUI models.
+
 Any composition that calls a model provider — an agent loop, a session-title generator, a compaction summarizer — streams its requests through this service. Mount it together with at least one provider adapter; the service itself has no configuration and no provider wire code.
 
 ### When to choose it
@@ -37,7 +39,7 @@ Mount the service and at least one adapter, then select the provider by name in
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm'
-- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: '@deepseek-ai/dsh-llm-deepseek-api-key'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
 ```
@@ -69,7 +71,7 @@ After a successful mount, `ctx.llm.listProviders()` reports the registered route
 
 ### Failures and recovery
 
-Every stream ends in exactly one terminal `finish` chunk: `{ kind: 'error', failure }` on failure, `{ kind: 'aborted', failure }` on cancellation. Failures carry stable codes such as `NO_ADAPTER`, `MISSING_CREDENTIAL`, `AUTH`, `RATE_LIMIT`, and `CONTEXT_WINDOW_EXCEEDED`; consumers route on the code, never on message text. A request naming an unregistered provider fails with `NO_ADAPTER`, and a malformed credential fails with `INVALID_CREDENTIAL` instead of surfacing as an opaque fetch error. This service never re-runs a request: retrying is the job of `dsh-llm-retry` at the agent's failed-step extension point.
+Every stream ends in exactly one terminal `finish` chunk: `{ kind: 'error', failure }` on failure, `{ kind: 'aborted', failure }` on cancellation. Failures carry stable codes such as `NO_ADAPTER`, `MISSING_CREDENTIAL`, `AUTH`, `RATE_LIMIT`, and `CONTEXT_WINDOW_EXCEEDED`; consumers route on the code, never on message text. `QUOTA` is provider-neutral exhaustion, while `ACCOUNT_QUOTA` is reserved for a first-party account balance that the current product can replenish. A request naming an unregistered provider fails with `NO_ADAPTER`, and a malformed credential fails with `INVALID_CREDENTIAL` instead of surfacing as an opaque fetch error. This service never re-runs a request: retrying is the job of `dsh-llm-retry` at the agent's failed-step extension point.
 
 -----
 
@@ -157,7 +159,7 @@ These limits define where this service stops and other packages or future work b
 - **Variants normally require a producer** — `prefill`, per-tool `strict`, block `cache` hints, and the `agent` message-source variant have no producer ([Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)).
 - **`BlockAssembler` handles core block kinds only** — a plugin-added block type whose stream is never closed by `block-end` makes `blocks()` throw.
 - **`GenerateOptions.sessionId` is a locally-declared brand** — importing dsh-session's `SessionId` would create a dependency cycle.
-- **Session-change types are a V4 persistence exception** — `DeveloperMessage` carries incremental session changes. Additions and removals name tools; the containing Session event binds additions to a historical request header that owns their definitions. See [Session references](../../core/session/README.md) for admission and restoration. Provider serialization, deferred loading, and UI presentation remain deferred. Both DeepSeek protocols and pi-ai reject developer history and `deferLoading` requests; Chat and Trajectory reject developer events. Ordinary requests retain their existing behavior.
+- **Tool updates require session history** — `GenerateOptions.tools` contains active definitions. `toolHistory` supplies the initial declarations and historically resolved additions from `Session.toolHistory()`. At adapter dispatch, `projectToolUpdates` constructs deferred declarations and retains removed definitions for `in-history`; `addition-only` omits removed definitions and removal messages. Unsupported routes receive active tools without developer messages or `deferLoading`. Missing history or a request prefix omitting recorded updates falls back to current declarations without developer messages. Explicitly deferred baseline tools remain deferred until their first retained addition block; declaring a deferred tool does not activate it.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -25,6 +25,8 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
+`listModels` 描述目录驱动界面提供的模型。核心解析与流式调用仍可接受未列出的 ID。GUI 的模型选择与提交要求模型出现在目录中；供 GUI 使用的适配器必须实现 `listModels`，公布其可用模型。基类实现返回空列表，因此不向 GUI 提供模型。
+
 任何调用模型提供方的组合——agent loop（智能体循环）、会话标题生成器、压缩（compaction）摘要器——都会通过本服务流式发起请求。与至少一个提供方适配器一起挂载它；服务本身没有任何配置，也不包含提供方协议代码。
 
 ### 何时选择
@@ -37,7 +39,7 @@ kind: "package-reference"
 
 ```yaml
 - name: '@deepseek-ai/dsh-llm'
-- name: '@deepseek-ai/dsh-llm-deepseek'
+- name: '@deepseek-ai/dsh-llm-deepseek-api-key'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
 ```
@@ -69,7 +71,7 @@ for await (const chunk of ctx.llm.stream({
 
 ### 失败与恢复
 
-每个流都恰好以一个终止 `finish` 分片结束：失败为 `{ kind: 'error', failure }`，取消为 `{ kind: 'aborted', failure }`。失败携带稳定 code，如 `NO_ADAPTER`、`MISSING_CREDENTIAL`、`AUTH`、`RATE_LIMIT` 与 `CONTEXT_WINDOW_EXCEEDED`；消费方依据 code 路由，绝不解析消息文本。点名未注册提供方的请求会以 `NO_ADAPTER` 失败，格式错误的凭据会以 `INVALID_CREDENTIAL` 失败，而不是表现为不透明的 fetch 错误。本服务从不自行重跑请求：重试是 `dsh-llm-retry` 在 agent 失败步骤扩展点上的职责。
+每个流都恰好以一个终止 `finish` 分片结束：失败为 `{ kind: 'error', failure }`，取消为 `{ kind: 'aborted', failure }`。失败携带稳定 code，如 `NO_ADAPTER`、`MISSING_CREDENTIAL`、`AUTH`、`RATE_LIMIT` 与 `CONTEXT_WINDOW_EXCEEDED`；消费方依据 code 路由，绝不解析消息文本。`QUOTA` 表示提供方中立的额度耗尽，`ACCOUNT_QUOTA` 专用于当前产品能够充值的第一方账号余额不足。点名未注册提供方的请求会以 `NO_ADAPTER` 失败，格式错误的凭据会以 `INVALID_CREDENTIAL` 失败，而不是表现为不透明的 fetch 错误。本服务从不自行重跑请求：重试是 `dsh-llm-retry` 在 agent 失败步骤扩展点上的职责。
 
 -----
 
@@ -157,7 +159,7 @@ for await (const chunk of ctx.llm.stream({
 - **变体通常要求实际产生方**——`prefill`、逐工具 `strict`、内容块 `cache` 提示和 `agent` 消息来源变体都没有产生方（见 [Agent Note](../../../.agents/notes/archived/simplification/2026-07-04-prune-producerless-vocabulary-variants.md)）。
 - **`BlockAssembler` 只处理核心块类型**——插件添加块类型的流若从未由 `block-end` 关闭，`blocks()` 会抛出异常。
 - **`GenerateOptions.sessionId` 是本地声明的品牌类型**——导入 dsh-session 的 `SessionId` 会产生依赖循环。
-- **Session 变更类型是 V4 持久化的例外** — `DeveloperMessage` 承载增量 Session 变更。添加与移除块记录工具名称；所在的 Session 事件将添加绑定到拥有其定义的历史请求头。接纳和恢复规则见 [Session 引用](../../core/session/README.zh.md)。提供方序列化、延迟加载与 UI 展示仍留待后续实现。DeepSeek 两种协议与 pi-ai 均拒绝 developer 历史及 `deferLoading` 请求；Chat 与 Trajectory 拒绝 developer 事件。普通请求的行为不变。
+- **工具更新需要会话历史** — `GenerateOptions.tools` 包含当前有效定义。`toolHistory` 提供 `Session.toolHistory()` 派生的初始声明及已解析历史定义的添加记录。适配器分发时，`projectToolUpdates` 构造延迟声明，并在 `in-history` 模式保留已移除定义；`addition-only` 省略已移除定义和移除消息。不支持更新的路由接收有效工具，不携带 developer 消息或 `deferLoading`。缺少历史或请求前缀遗漏已记录更新时，回退为当前声明且不发送 developer 消息。 显式延迟加载的初始工具在首个保留的添加块出现前保持延迟状态；声明延迟加载工具不会使其激活。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -136,6 +136,8 @@ var HarnessError = class extends Error {
 const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
 /** Canonical provider-neutral code for an exhausted account quota or balance. */
 const QUOTA_EXCEEDED_CODE = "QUOTA";
+/** Account-token quota that can be replenished through the first-party billing page. */
+const ACCOUNT_QUOTA_EXCEEDED_CODE = "ACCOUNT_QUOTA";
 /**
 * Canonical provider-neutral code for a response that completed normally but
 * carried no content blocks at all. Providers occasionally emit a degenerate
@@ -750,6 +752,89 @@ function projectImagesForTextModel(messages) {
 		};
 	});
 }
+function withoutDeveloperMessages(messages) {
+	const retained = messages.filter((message) => message.role !== "developer");
+	return retained.length === messages.length ? messages : retained;
+}
+function toolDeclarations(tools, mode, history) {
+	const declarations = new Map(history.tools.map((tool) => [tool.name, tool]));
+	for (const update of history.updates) for (const tool of update.additions) if (!declarations.has(tool.name)) declarations.set(tool.name, {
+		...tool,
+		deferLoading: true
+	});
+	switch (mode) {
+		case "in-history": return declarations;
+		case "addition-only": {
+			const activeNames = new Set(tools?.map((tool) => tool.name));
+			for (const name of declarations.keys()) if (!activeNames.has(name)) declarations.delete(name);
+			return declarations;
+		}
+		/* v8 ignore next 2 -- closed-union exhaustiveness guard */
+		default: return assertNever(mode);
+	}
+}
+/**
+* Construct provider declarations from session-folded history without changing logged active tools.
+* Unsupported routes and incomplete history use current declarations without developer updates.
+* Explicitly deferred baseline tools become available only after their first retained addition.
+* @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+* @param tools - currently active tool schemas.
+* @param toolUpdate - the resolved route's update mode.
+* @param history - immutable state folded from committed headers and developer messages.
+* @returns provider declarations and the corresponding filtered history.
+*/
+function projectToolUpdates(messages, tools, toolUpdate, history) {
+	if (toolUpdate === void 0) {
+		let immediateTools = tools;
+		if (tools?.some((tool) => tool.deferLoading === true)) immediateTools = tools.map(({ deferLoading: _loading, ...tool }) => tool);
+		return {
+			messages: withoutDeveloperMessages(messages),
+			tools: immediateTools
+		};
+	}
+	if (history === void 0) return {
+		messages: withoutDeveloperMessages(messages),
+		tools
+	};
+	const messageIds = new Set(messages.flatMap((message) => message.role === "developer" ? [message.id] : []));
+	if (history.updates.some((update) => !messageIds.has(update.messageId))) return {
+		messages: withoutDeveloperMessages(messages),
+		tools
+	};
+	const declarations = toolDeclarations(tools, toolUpdate, history);
+	const updateIds = new Set(history.updates.map((update) => update.messageId));
+	const offered = new Set(history.tools.filter((tool) => !tool.deferLoading).map((tool) => tool.name));
+	const projectedMessages = [];
+	for (const message of messages) {
+		if (message.role !== "developer") {
+			projectedMessages.push(message);
+			continue;
+		}
+		if (!updateIds.has(message.id)) continue;
+		const content = message.content.filter((block) => {
+			switch (block.type) {
+				case "tool-addition":
+					if (!declarations.has(block.toolName) || offered.has(block.toolName)) return false;
+					offered.add(block.toolName);
+					return true;
+				case "tool-removal":
+					if (toolUpdate !== "in-history") return false;
+					return offered.delete(block.toolName);
+				default: return true;
+			}
+		});
+		if (content.length === 0) continue;
+		if (content.length === message.content.length) projectedMessages.push(message);
+		else projectedMessages.push({
+			...message,
+			content
+		});
+	}
+	return {
+		messages: projectedMessages.length === messages.length && projectedMessages.every((message, index) => message === messages[index]) ? messages : projectedMessages,
+		tools: [...declarations.values()]
+	};
+}
 //#endregion
 //#region lib/types/attribution.js
 /**
@@ -1612,8 +1697,9 @@ var LlmAdapter = class {
 	imageRequestPricing(_provider, _model) {}
 	/**
 	* List models this adapter can currently advertise for one owned provider.
-	* The result is advisory: an adapter may accept unlisted model ids, and
-	* consumers must not turn absence into request rejection.
+	* Core routing accepts unlisted model ids; catalog-driven entry points such
+	* as the GUI may require membership. Adapters used there must advertise
+	* their available models; the base empty catalog offers no GUI selection.
 	* @param _provider - one provider route owned by this adapter.
 	* @returns discoverable models in adapter-preferred order.
 	*/
@@ -1979,7 +2065,8 @@ let LlmRuntime = (() => {
 		}
 		/**
 		* Discover models advertised by one registered provider. Catalog membership
-		* is advisory and never changes routing or request validation.
+		* does not constrain core routing. Catalog-driven entry points may restrict
+		* selection and submission to the advertised models.
 		* @param provider - registered provider route to inspect.
 		* @returns detached model metadata in adapter-preferred order.
 		*/
@@ -2024,6 +2111,8 @@ let LlmRuntime = (() => {
 			const inputModalities = this.detachedModalities(resolved.inputModalities);
 			const systemPromptUpdate = resolved.systemPromptUpdate;
 			if (systemPromptUpdate !== void 0 && systemPromptUpdate !== "in-history") throw new LlmError(`adapter returned invalid system prompt update mode for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
+			const toolUpdate = resolved.toolUpdate;
+			if (toolUpdate !== void 0 && toolUpdate !== "in-history" && toolUpdate !== "addition-only") throw new LlmError(`adapter returned invalid tool update mode for provider "${provider}" model "${model}"`, "INVALID_MODEL_INFO");
 			const defaultMaxTokens = resolved.defaultMaxTokens;
 			if (defaultMaxTokens !== void 0 && (!Number.isSafeInteger(defaultMaxTokens) || defaultMaxTokens <= 0)) throw new LlmError(`adapter returned invalid default maxTokens for provider "${provider}" model "${model}"`, "INVALID_MODEL_MAX_TOKENS");
 			const info = {
@@ -2034,7 +2123,8 @@ let LlmRuntime = (() => {
 				...inputModalities === void 0 ? {} : { inputModalities },
 				...context === void 0 ? {} : { context: { contextWindow: context.contextWindow } },
 				...defaultMaxTokens === void 0 ? {} : { defaultMaxTokens },
-				...resolved.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: resolved.systemPromptUpdate }
+				...resolved.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: resolved.systemPromptUpdate },
+				...resolved.toolUpdate === void 0 ? {} : { toolUpdate: resolved.toolUpdate }
 			};
 			const reasoning = resolved.reasoning;
 			if (reasoning === void 0) return info;
@@ -2129,6 +2219,7 @@ let LlmRuntime = (() => {
 				...context === void 0 ? {} : { context },
 				...modelInfo.inputModalities === void 0 ? {} : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
 				...modelInfo.systemPromptUpdate === void 0 ? {} : { systemPromptUpdate: modelInfo.systemPromptUpdate },
+				...modelInfo.toolUpdate === void 0 ? {} : { toolUpdate: modelInfo.toolUpdate },
 				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");
@@ -2218,13 +2309,17 @@ let LlmRuntime = (() => {
 				let projectedMessages = resolvedOptions.messages;
 				if (projectedMessages.some((message) => contentHasFile(message.content))) projectedMessages = projectFilesToText(projectedMessages, (ref) => this.fileReadPath(ref));
 				if (modelInfo.inputModalities !== void 0 && !modelInfo.inputModalities.includes("image") && projectedMessages.some((message) => contentHasImage(message.content))) projectedMessages = projectImagesForTextModel(projectedMessages);
-				const projectedOptions = projectedMessages === resolvedOptions.messages ? resolvedOptions : Object.isFrozen(resolvedOptions) ? deepFreeze({
-					...resolvedOptions,
-					messages: projectedMessages
-				}) : {
-					...resolvedOptions,
-					messages: projectedMessages
-				};
+				const projectedTools = projectToolUpdates(projectedMessages, resolvedOptions.tools, modelInfo.toolUpdate, resolvedOptions.toolHistory);
+				projectedMessages = projectedTools.messages;
+				let projectedOptions = resolvedOptions;
+				if (projectedMessages !== resolvedOptions.messages || projectedTools.tools !== resolvedOptions.tools) {
+					projectedOptions = {
+						...resolvedOptions,
+						messages: projectedMessages,
+						...projectedTools.tools === void 0 ? {} : { tools: projectedTools.tools }
+					};
+					if (Object.isFrozen(resolvedOptions)) deepFreeze(projectedOptions);
+				}
 				iterator = dispatch(this.forAdapter(projectedOptions, adapter))[Symbol.asyncIterator]();
 			} catch (error) {
 				yield adapterFailureChunk(error, options.signal);
@@ -2292,4 +2387,4 @@ function adapterFailureChunk(error, signal) {
 	};
 }
 //#endregion
-export { APP_IDENTITY, AssistantStreamAccumulator, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, HarnessError, IMAGE_OFFLOAD_REQUIRED_CODE, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmAttemptId, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, ToolCallId, assembleAssistantStream, assertUsableApiKey, assistantStreamChunks, assistantStreamFirstTokenTime, assistantStreamHasVisibleContent, assistantStreamHasVisibleText, attributionHeaders, boundContextSummary, callConfigEquals, chunkHasVisibleText, contentHasFile, contentHasImage, createAssistantMessage, createDeveloperMessage, createMessage, createSystemMessage, createToolResultMessage, createUserMessage, errorChain, expandAssistantStream, fileHandleText, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, isVisibleChunk, joinAssistantStreamText, lastAssistantStreamChunk, markAgentLoopRequest, normalizeApiKey, offloadedImageText, projectFilesToText, projectImagesForTextModel, projectOffloadedImages, requestImageHandleText, requiredImageOffload, resolveImageAttachmentAccess, resolveRetryPolicy, runFirstTokenTime, runFirstVisibleTime, textOnlyImageText, userAgent };
+export { ACCOUNT_QUOTA_EXCEEDED_CODE, APP_IDENTITY, AssistantStreamAccumulator, BlockAssembler, CONTEXT_SUMMARY_MAX_CHARS, CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, HarnessError, IMAGE_OFFLOAD_REQUIRED_CODE, INVALID_CREDENTIAL_CODE, LlmAdapter, LlmAttemptId, LlmError, LlmRuntime, LlmRuntime as default, MessageId, ProviderRequestId, QUOTA_EXCEEDED_CODE, ReasoningEffortId, RetryPolicySchema, ToolCallId, assembleAssistantStream, assertUsableApiKey, assistantStreamChunks, assistantStreamFirstTokenTime, assistantStreamHasVisibleContent, assistantStreamHasVisibleText, attributionHeaders, boundContextSummary, callConfigEquals, chunkHasVisibleText, contentHasFile, contentHasImage, createAssistantMessage, createDeveloperMessage, createMessage, createSystemMessage, createToolResultMessage, createUserMessage, errorChain, expandAssistantStream, fileHandleText, freezeMessage, isAgentLoopRequest, isContextWindowExceededError, isHarnessError, isQuotaExceededError, isTokenDelta, isVisibleChunk, joinAssistantStreamText, lastAssistantStreamChunk, markAgentLoopRequest, normalizeApiKey, offloadedImageText, projectFilesToText, projectImagesForTextModel, projectOffloadedImages, projectToolUpdates, requestImageHandleText, requiredImageOffload, resolveImageAttachmentAccess, resolveRetryPolicy, runFirstTokenTime, runFirstVisibleTime, textOnlyImageText, userAgent };

package/lib/typert.host.js

@@ -74,7 +74,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/discoverModels:result',
         create: _deepseek_ai_dsh_llm_llm_discoverModels_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":633,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":638,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders',
@@ -89,7 +89,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders:result',
         create: _deepseek_ai_dsh_llm_llm_listConfigurableProviders_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":545,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":550,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listProviders',
@@ -104,7 +104,7 @@ export const TYPERT = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/listProviders:result',
         create: _deepseek_ai_dsh_llm_llm_listProviders_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":473,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":478,"column":3},
     },
   ],
   model: {
@@ -192,7 +192,7 @@ export const TYPERT = {
             "name": "listModels",
             "signature": "async listModels(provider: string): Promise<LlmModelInfo[]>",
             "summary": "Discover models advertised by one registered provider.",
-            "jsDoc": "/**\n * Discover models advertised by one registered provider. Catalog membership\n * is advisory and never changes routing or request validation.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */"
+            "jsDoc": "/**\n * Discover models advertised by one registered provider. Catalog membership\n * does not constrain core routing. Catalog-driven entry points may restrict\n * selection and submission to the advertised models.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */"
           },
           {
             "kind": "method",
@@ -310,7 +310,7 @@ export const TYPERT = {
           },
           {
             "name": "GenerateOptions",
-            "declaration": "export interface GenerateOptions {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    messages: RequestMessage[];\n    system?: string;\n    tools?: ToolSchema[];\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<'SessionId'>;\n    purpose?: 'compaction' | 'session-title';\n}"
+            "declaration": "export interface GenerateOptions {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    messages: RequestMessage[];\n    system?: string;\n    tools?: ToolSchema[];\n    toolHistory?: ToolHistory;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n    signal?: AbortSignal;\n    sessionId?: Branded<'SessionId'>;\n    purpose?: 'compaction' | 'session-title';\n}"
           },
           {
             "name": "GoalId",
@@ -390,7 +390,7 @@ export const TYPERT = {
           },
           {
             "name": "LlmResolvedModelInfo",
-            "declaration": "export interface LlmResolvedModelInfo extends LlmModelInfo {\n    context?: LlmModelContext;\n    defaultMaxTokens?: number;\n    reasoning?: LlmModelReasoningInfo;\n    systemPromptUpdate?: SystemPromptUpdate;\n}"
+            "declaration": "export interface LlmResolvedModelInfo extends LlmModelInfo {\n    context?: LlmModelContext;\n    defaultMaxTokens?: number;\n    reasoning?: LlmModelReasoningInfo;\n    systemPromptUpdate?: SystemPromptUpdate;\n    toolUpdate?: ToolUpdate;\n}"
           },
           {
             "name": "Message",
@@ -414,7 +414,7 @@ export const TYPERT = {
           },
           {
             "name": "MessageSourceMap",
-            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    'system-prompt': SystemPromptMessageSource;\n    'model-selection': { kind: 'model-selection'; } & ContextFormed;\n    'user-approval': { kind: 'user-approval'; } & ContextFormed;\n    'ptc-mode': { kind: 'ptc-mode'; };\n    'tool-registry': { kind: 'tool-registry'; };\n    'user-rpc': { kind: 'user'; rpcId: SessionRequestId; clientTimeZone?: string; };\n    'agent-message': AgentMessageSource;\n    'subagent-settled': SubagentSettledMessageSource;\n    'skill-invocation': SkillInvocationSource;\n    'cordis-host-runner': { kind: 'cordis-host-runner'; };\n    goal: GoalMessageSource;\n    'compact-checkpoint': CompactionCheckpointSource;\n    'session-reference': SessionReferenceSource;\n}"
+            "declaration": "export interface MessageSourceMap {\n    user: { kind: 'user'; };\n    model: ModelMessageSource;\n    tool: ToolMessageSource;\n    'system-prompt': SystemPromptMessageSource;\n    'model-selection': { kind: 'model-selection'; } & ContextFormed;\n    'user-approval': { kind: 'user-approval'; } & ContextFormed;\n    'ptc-mode': { kind: 'ptc-mode'; };\n    'tool-registry': { kind: 'tool-registry'; };\n    'user-rpc': { kind: 'user'; rpcId: SessionRequestId; clientTimeZone?: string; };\n    'agent-message': AgentMessageSource;\n    'subagent-settled': SubagentSettledMessageSource;\n    'skill-invocation': SkillInvocationSource;\n    'cordis-host-runner': { kind: 'cordis-host-runner'; };\n    goal: GoalMessageSource;\n    schedule: { kind: 'schedule'; } & ContextFormed;\n    'compact-checkpoint': CompactionCheckpointSource;\n    'session-reference': SessionReferenceSource;\n}"
           },
           {
             "name": "ModelMessageSource",
@@ -438,7 +438,7 @@ export const TYPERT = {
           },
           {
             "name": "PreparedLlmCall",
-            "declaration": "export interface PreparedLlmCall {\n    readonly config: LlmCallConfig;\n    readonly retryPolicy: ResolvedRetryPolicy;\n    readonly context?: LlmModelContext;\n    readonly inputModalities?: readonly ModelModality[];\n    readonly systemPromptUpdate?: SystemPromptUpdate;\n    readonly adapterDefaults: LlmCallConfigAdapterDefaults;\n    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}"
+            "declaration": "export interface PreparedLlmCall {\n    readonly config: LlmCallConfig;\n    readonly retryPolicy: ResolvedRetryPolicy;\n    readonly context?: LlmModelContext;\n    readonly inputModalities?: readonly ModelModality[];\n    readonly systemPromptUpdate?: SystemPromptUpdate;\n    readonly toolUpdate?: ToolUpdate;\n    readonly adapterDefaults: LlmCallConfigAdapterDefaults;\n    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;\n}"
           },
           {
             "name": "ProviderRequestId",
@@ -540,6 +540,10 @@ export const TYPERT = {
             "name": "ToolCallId",
             "declaration": "export type ToolCallId = Branded<'ToolCallId'>;"
           },
+          {
+            "name": "ToolHistory",
+            "declaration": "export interface ToolHistory {\n    readonly tools: readonly ToolSchema[];\n    readonly updates: readonly { readonly messageId: MessageId; readonly additions: readonly ToolSchema[]; }[];\n}"
+          },
           {
             "name": "ToolMessageSource",
             "declaration": "export interface ToolMessageSource {\n    kind: 'tool';\n    callId: ToolCallId;\n}"
@@ -556,6 +560,10 @@ export const TYPERT = {
             "name": "ToolSchema",
             "declaration": "export interface ToolSchema {\n    deferLoading?: true;\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n}"
           },
+          {
+            "name": "ToolUpdate",
+            "declaration": "export type ToolUpdate = 'in-history' | 'addition-only';"
+          },
           {
             "name": "UserMessage",
             "declaration": "export interface UserMessage extends MessageBase {\n    readonly role: 'user';\n}"

package/lib/typert.remote-client.js

@@ -71,7 +71,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/discoverModels:result',
         create: _deepseek_ai_dsh_llm_llm_discoverModels_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":633,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":638,"column":9},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders',
@@ -86,7 +86,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/listConfigurableProviders:result',
         create: _deepseek_ai_dsh_llm_llm_listConfigurableProviders_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":545,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":550,"column":3},
     },
     {
       id: '@deepseek-ai/dsh-llm#llm/listProviders',
@@ -101,7 +101,7 @@ export const TYPERT_REMOTE = {
         typeSymbol: '@deepseek-ai/dsh-llm#llm/listProviders:result',
         create: _deepseek_ai_dsh_llm_llm_listProviders_result$schema,
       },
-      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":473,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":478,"column":3},
     },
   ],
 }

package/lib/types/content.d.ts

@@ -1,5 +1,5 @@
 /** Content-block structure helpers. @module @deepseek-ai/dsh-llm/content */
-import type { ContentBlock, ImageBlock, LlmImageRequestBudget } from './types.ts';
+import type { ContentBlock, ImageBlock, LlmImageRequestBudget, ToolSchema, ToolUpdate, ToolHistory } from './types.ts';
 import type { RequestMessage } from './types.ts';
 import type { Message } from './message.ts';
 import type { AttachmentStore, FileAttachmentRef, ImageAttachmentRef, RequestImageAttachment } from '@deepseek-ai/dsh-attachment';
@@ -128,4 +128,22 @@ export declare function projectImagesForTextModel(messages: readonly Message[]):
  * @returns original inputs without images, otherwise copies with stable placeholders.
  */
 export declare function projectImagesForTextModel(messages: readonly RequestMessage[]): readonly RequestMessage[];
+/** Request messages and tools after one route's tool update projection. */
+export interface ProjectedToolUpdates {
+    /** History with only the developer updates supported by this route and declaration series. */
+    readonly messages: readonly RequestMessage[];
+    /** Provider declarations, including deferred and retained definitions when supported. */
+    readonly tools: readonly ToolSchema[] | undefined;
+}
+/**
+ * Construct provider declarations from session-folded history without changing logged active tools.
+ * Unsupported routes and incomplete history use current declarations without developer updates.
+ * Explicitly deferred baseline tools become available only after their first retained addition.
+ * @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+ * @param tools - currently active tool schemas.
+ * @param toolUpdate - the resolved route's update mode.
+ * @param history - immutable state folded from committed headers and developer messages.
+ * @returns provider declarations and the corresponding filtered history.
+ */
+export declare function projectToolUpdates(messages: readonly RequestMessage[], tools: readonly ToolSchema[] | undefined, toolUpdate: ToolUpdate | undefined, history?: ToolHistory): ProjectedToolUpdates;
 //# sourceMappingURL=content.d.ts.map

package/lib/types/content.js

@@ -245,4 +245,111 @@ export function projectImagesForTextModel(messages) {
         return content === message.content ? message : { ...message, content };
     });
 }
+function withoutDeveloperMessages(messages) {
+    const retained = messages.filter(message => message.role !== 'developer');
+    return retained.length === messages.length ? messages : retained;
+}
+function toolDeclarations(tools, mode, history) {
+    const declarations = new Map(history.tools.map(tool => [tool.name, tool]));
+    for (const update of history.updates) {
+        for (const tool of update.additions) {
+            if (!declarations.has(tool.name)) {
+                // Later additions activate these definitions at their recorded position.
+                declarations.set(tool.name, { ...tool, deferLoading: true });
+            }
+        }
+    }
+    switch (mode) {
+        case 'in-history':
+            // Removal blocks disable tools without discarding their historical definitions.
+            return declarations;
+        case 'addition-only': {
+            // Without removal support, the declaration list must omit inactive tools.
+            const activeNames = new Set(tools?.map(tool => tool.name));
+            for (const name of declarations.keys()) {
+                if (!activeNames.has(name))
+                    declarations.delete(name);
+            }
+            return declarations;
+        }
+        /* v8 ignore next 2 -- closed-union exhaustiveness guard */
+        default:
+            return assertNever(mode);
+    }
+}
+/**
+ * Construct provider declarations from session-folded history without changing logged active tools.
+ * Unsupported routes and incomplete history use current declarations without developer updates.
+ * Explicitly deferred baseline tools become available only after their first retained addition.
+ * @param messages - complete request inputs, or the prefix selected for an auxiliary call.
+ * @param tools - currently active tool schemas.
+ * @param toolUpdate - the resolved route's update mode.
+ * @param history - immutable state folded from committed headers and developer messages.
+ * @returns provider declarations and the corresponding filtered history.
+ */
+export function projectToolUpdates(messages, tools, toolUpdate, history) {
+    if (toolUpdate === undefined) {
+        // Unsupported routes need immediately available tools and no update messages.
+        let immediateTools = tools;
+        if (tools?.some(tool => tool.deferLoading === true)) {
+            immediateTools = tools.map(({ deferLoading: _loading, ...tool }) => tool);
+        }
+        return { messages: withoutDeveloperMessages(messages), tools: immediateTools };
+    }
+    if (history === undefined) {
+        // Current schemas alone cannot resolve definitions referenced by past updates.
+        return { messages: withoutDeveloperMessages(messages), tools };
+    }
+    const messageIds = new Set(messages.flatMap(message => message.role === 'developer' ? [message.id] : []));
+    if (history.updates.some(update => !messageIds.has(update.messageId))) {
+        // An auxiliary prefix may omit updates needed to activate historical declarations.
+        return { messages: withoutDeveloperMessages(messages), tools };
+    }
+    const declarations = toolDeclarations(tools, toolUpdate, history);
+    const updateIds = new Set(history.updates.map(update => update.messageId));
+    // Deferred baseline tools still need their first addition to become available.
+    const offered = new Set(history.tools.filter(tool => !tool.deferLoading).map(tool => tool.name));
+    const projectedMessages = [];
+    for (const message of messages) {
+        if (message.role !== 'developer') {
+            projectedMessages.push(message);
+            continue;
+        }
+        // Earlier declaration series do not govern the current tool set.
+        if (!updateIds.has(message.id))
+            continue;
+        const content = message.content.filter((block) => {
+            switch (block.type) {
+                case 'tool-addition':
+                    // Only declared tools that are not already available need activation.
+                    if (!declarations.has(block.toolName) || offered.has(block.toolName))
+                        return false;
+                    offered.add(block.toolName);
+                    return true;
+                case 'tool-removal':
+                    // Addition-only routes cannot deactivate a tool through history.
+                    if (toolUpdate !== 'in-history')
+                        return false;
+                    return offered.delete(block.toolName);
+                default:
+                    // Other core and plugin-defined blocks retain their content and order.
+                    return true;
+            }
+        });
+        if (content.length === 0)
+            continue;
+        if (content.length === message.content.length) {
+            projectedMessages.push(message);
+        }
+        else {
+            projectedMessages.push({ ...message, content });
+        }
+    }
+    const unchanged = projectedMessages.length === messages.length
+        && projectedMessages.every((message, index) => message === messages[index]);
+    return {
+        messages: unchanged ? messages : projectedMessages,
+        tools: [...declarations.values()],
+    };
+}
 //# sourceMappingURL=content.js.map

package/lib/types/error.d.ts

@@ -18,6 +18,8 @@ export declare class HarnessError extends Error {
 export declare const CONTEXT_WINDOW_EXCEEDED_CODE = "CONTEXT_WINDOW_EXCEEDED";
 /** Canonical provider-neutral code for an exhausted account quota or balance. */
 export declare const QUOTA_EXCEEDED_CODE = "QUOTA";
+/** Account-token quota that can be replenished through the first-party billing page. */
+export declare const ACCOUNT_QUOTA_EXCEEDED_CODE = "ACCOUNT_QUOTA";
 /**
  * Canonical provider-neutral code for a response that completed normally but
  * carried no content blocks at all. Providers occasionally emit a degenerate

package/lib/types/error.js

@@ -22,6 +22,8 @@ export class HarnessError extends Error {
 export const CONTEXT_WINDOW_EXCEEDED_CODE = 'CONTEXT_WINDOW_EXCEEDED';
 /** Canonical provider-neutral code for an exhausted account quota or balance. */
 export const QUOTA_EXCEEDED_CODE = 'QUOTA';
+/** Account-token quota that can be replenished through the first-party billing page. */
+export const ACCOUNT_QUOTA_EXCEEDED_CODE = 'ACCOUNT_QUOTA';
 /**
  * Canonical provider-neutral code for a response that completed normally but
  * carried no content blocks at all. Providers occasionally emit a degenerate

package/lib/types/index.d.ts

@@ -7,7 +7,7 @@
  */
 import { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
-import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmImageRequestPricing, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, ModelModality, StreamChunk, SystemPromptUpdate } from './types.ts';
+import type { GenerateOptions, LlmConfigurableProvider, LlmDiscoveredModel, LlmFailure, LlmImageRequestPricing, LlmModelContext, LlmModelDiscoveryRequest, LlmModelInfo, LlmResolvedModelInfo, LlmProviderInfo, ModelModality, StreamChunk, SystemPromptUpdate, ToolUpdate } from './types.ts';
 import type { ResolvedRetryPolicy } from './retry-policy.ts';
 import type { ProviderRequestId } from './brand.ts';
 import type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
@@ -101,6 +101,8 @@ export interface PreparedLlmCall {
     readonly inputModalities?: readonly ModelModality[];
     /** Exact model system prompt update mode captured with the adapter dispatch generation. */
     readonly systemPromptUpdate?: SystemPromptUpdate;
+    /** Exact model tool update mode captured with the adapter dispatch generation. */
+    readonly toolUpdate?: ToolUpdate;
     /** Config fields materialized by the captured adapter rather than proposed by the caller. */
     readonly adapterDefaults: LlmCallConfigAdapterDefaults;
     /**
@@ -150,8 +152,9 @@ export declare abstract class LlmAdapter {
     imageRequestPricing(_provider: string, _model: string): LlmImageRequestPricing | undefined;
     /**
      * List models this adapter can currently advertise for one owned provider.
-     * The result is advisory: an adapter may accept unlisted model ids, and
-     * consumers must not turn absence into request rejection.
+     * Core routing accepts unlisted model ids; catalog-driven entry points such
+     * as the GUI may require membership. Adapters used there must advertise
+     * their available models; the base empty catalog offers no GUI selection.
      * @param _provider - one provider route owned by this adapter.
      * @returns discoverable models in adapter-preferred order.
      */
@@ -339,7 +342,8 @@ export declare class LlmRuntime extends TypertRemoteService {
     private detachedModalities;
     /**
      * Discover models advertised by one registered provider. Catalog membership
-     * is advisory and never changes routing or request validation.
+     * does not constrain core routing. Catalog-driven entry points may restrict
+     * selection and submission to the advertised models.
      * @param provider - registered provider route to inspect.
      * @returns detached model metadata in adapter-preferred order.
      */

package/lib/types/index.js

@@ -47,7 +47,7 @@ import { callConfigEquals } 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 { contentHasFile, contentHasImage, fileHandleText, projectFilesToText, projectImagesForTextModel, } from "./content.js";
+import { contentHasFile, contentHasImage, fileHandleText, projectFilesToText, projectImagesForTextModel, projectToolUpdates, } from "./content.js";
 export * from "./attribution.js";
 export * from "./brand.js";
 export * from "./error.js";
@@ -169,8 +169,9 @@ export class LlmAdapter {
     }
     /**
      * List models this adapter can currently advertise for one owned provider.
-     * The result is advisory: an adapter may accept unlisted model ids, and
-     * consumers must not turn absence into request rejection.
+     * Core routing accepts unlisted model ids; catalog-driven entry points such
+     * as the GUI may require membership. Adapters used there must advertise
+     * their available models; the base empty catalog offers no GUI selection.
      * @param _provider - one provider route owned by this adapter.
      * @returns discoverable models in adapter-preferred order.
      */
@@ -547,7 +548,8 @@ let LlmRuntime = (() => {
         }
         /**
          * Discover models advertised by one registered provider. Catalog membership
-         * is advisory and never changes routing or request validation.
+         * does not constrain core routing. Catalog-driven entry points may restrict
+         * selection and submission to the advertised models.
          * @param provider - registered provider route to inspect.
          * @returns detached model metadata in adapter-preferred order.
          */
@@ -617,6 +619,11 @@ let LlmRuntime = (() => {
             if (systemPromptUpdate !== undefined && systemPromptUpdate !== 'in-history') {
                 throw new LlmError(`adapter returned invalid system prompt update mode for provider "${provider}" model "${model}"`, 'INVALID_MODEL_INFO');
             }
+            // Widened for the same reason: catalog config supplies the tool update mode as text.
+            const toolUpdate = resolved.toolUpdate;
+            if (toolUpdate !== undefined && toolUpdate !== 'in-history' && toolUpdate !== 'addition-only') {
+                throw new LlmError(`adapter returned invalid tool update mode for provider "${provider}" model "${model}"`, 'INVALID_MODEL_INFO');
+            }
             const defaultMaxTokens = resolved.defaultMaxTokens;
             if (defaultMaxTokens !== undefined
                 && (!Number.isSafeInteger(defaultMaxTokens) || defaultMaxTokens <= 0)) {
@@ -631,6 +638,7 @@ let LlmRuntime = (() => {
                 ...context === undefined ? {} : { context: { contextWindow: context.contextWindow } },
                 ...defaultMaxTokens === undefined ? {} : { defaultMaxTokens },
                 ...resolved.systemPromptUpdate === undefined ? {} : { systemPromptUpdate: resolved.systemPromptUpdate },
+                ...resolved.toolUpdate === undefined ? {} : { toolUpdate: resolved.toolUpdate },
             };
             const reasoning = resolved.reasoning;
             if (reasoning === undefined)
@@ -747,6 +755,7 @@ let LlmRuntime = (() => {
                     ? {}
                     : { inputModalities: Object.freeze([...modelInfo.inputModalities]) },
                 ...modelInfo.systemPromptUpdate === undefined ? {} : { systemPromptUpdate: modelInfo.systemPromptUpdate },
+                ...modelInfo.toolUpdate === undefined ? {} : { toolUpdate: modelInfo.toolUpdate },
                 stream: (options) => {
                     if (dispatched) {
                         throw new LlmError('a prepared LLM call can only be dispatched once', 'INVALID_PREPARED_CALL');
@@ -853,11 +862,19 @@ let LlmRuntime = (() => {
                     && projectedMessages.some(message => contentHasImage(message.content))) {
                     projectedMessages = projectImagesForTextModel(projectedMessages);
                 }
-                const projectedOptions = projectedMessages === resolvedOptions.messages
-                    ? resolvedOptions
-                    : Object.isFrozen(resolvedOptions)
-                        ? deepFreeze({ ...resolvedOptions, messages: projectedMessages })
-                        : { ...resolvedOptions, messages: projectedMessages };
+                // Tool changes are logged on every route; the route's declared mode selects what it receives.
+                const projectedTools = projectToolUpdates(projectedMessages, resolvedOptions.tools, modelInfo.toolUpdate, resolvedOptions.toolHistory);
+                projectedMessages = projectedTools.messages;
+                let projectedOptions = resolvedOptions;
+                if (projectedMessages !== resolvedOptions.messages || projectedTools.tools !== resolvedOptions.tools) {
+                    projectedOptions = {
+                        ...resolvedOptions,
+                        messages: projectedMessages,
+                        ...projectedTools.tools === undefined ? {} : { tools: projectedTools.tools },
+                    };
+                    if (Object.isFrozen(resolvedOptions))
+                        deepFreeze(projectedOptions);
+                }
                 const stream = dispatch(this.forAdapter(projectedOptions, adapter));
                 iterator = stream[Symbol.asyncIterator]();
             }

package/lib/types/types.d.ts

@@ -5,7 +5,7 @@
  */
 import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { FileAttachmentRef, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
-import type { ToolCallId, ProviderRequestId, ReasoningEffortId } from './brand.ts';
+import type { MessageId, ToolCallId, ProviderRequestId, ReasoningEffortId } from './brand.ts';
 import type { Message, UserMessage } from './message.ts';
 declare module '@deepseek-ai/cordis' {
     interface Events {
@@ -108,9 +108,8 @@ export interface ToolRemovalBlock {
 }
 /**
  * Merge-extensible content blocks keyed by `type`. New core blocks must land
- * with adapter, UI, and compaction support. Developer tool-change blocks are
- * reserved for Session V4 persistence; providers and UI reject them until
- * their producers and consumers are implemented together.
+ * with adapter, UI, and compaction support. Tool-change blocks belong to
+ * developer messages; `projectToolUpdates` selects what each route receives.
  */
 export interface ContentBlockMap {
     'text': TextBlock;
@@ -364,6 +363,16 @@ export interface LlmModelReasoningInfo {
  * can follow the cached history instead of rewriting message 0.
  */
 export type SystemPromptUpdate = 'in-history';
+/**
+ * How a model accepts native tool declarations that change mid-conversation.
+ * `'addition-only'`: the model reads a `tool-addition` block in a later
+ * developer message as activating a tool declared with `deferLoading`, so an
+ * added tool follows the cached history instead of rewriting the declaration
+ * list. `'in-history'`: the model additionally reads `tool-removal` blocks,
+ * so a removed tool keeps its declaration and the removal follows the history.
+ * Absent means every request declares the complete current tool list.
+ */
+export type ToolUpdate = 'in-history' | 'addition-only';
 /** Exact-route model metadata resolved by its owning adapter. */
 export interface LlmResolvedModelInfo extends LlmModelInfo {
     /** Provider-owned context capacity when known. */
@@ -374,6 +383,8 @@ export interface LlmResolvedModelInfo extends LlmModelInfo {
     reasoning?: LlmModelReasoningInfo;
     /** Declared mid-conversation system prompt handling; absent means only a leading system message is read. */
     systemPromptUpdate?: SystemPromptUpdate;
+    /** Declared mid-conversation tool declaration handling; absent means every request declares the complete tool list. */
+    toolUpdate?: ToolUpdate;
 }
 /**
  * Adapter-private lossless-JSON state for replaying a successful response,
@@ -462,6 +473,18 @@ export interface RequestUserInput {
 }
 /** A durable conversation message or a user input used only for one request. */
 export type RequestMessage = Message | RequestUserInput;
+/** Logged tool declarations and update identities since the last declaration reset. */
+export interface ToolHistory {
+    /** Complete active declarations at the start of this history. */
+    readonly tools: readonly ToolSchema[];
+    /** Ordered developer messages, with additions resolved from their historical headers. */
+    readonly updates: readonly {
+        /** Identity used to locate this update in the derived request history. */
+        readonly messageId: MessageId;
+        /** Added definitions resolved from the event's referenced request header. */
+        readonly additions: readonly ToolSchema[];
+    }[];
+}
 /** A single model request, fully assembled. */
 export interface GenerateOptions {
     /** Registered provider route selecting the adapter instance. */
@@ -483,6 +506,8 @@ export interface GenerateOptions {
     system?: string;
     /** Tool schemas (adapters map to the provider's `tools` field). */
     tools?: ToolSchema[];
+    /** Session-folded tool history used for route projection; omission sends complete declarations without tool updates. */
+    toolHistory?: ToolHistory;
     temperature?: number;
     maxTokens?: number;
     /**

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.7-rc.1",
+  "version": "0.2.0-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -65,16 +65,16 @@
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-crypto": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-brand": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-util-values": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-timeout": "0.1.7-rc.1",
-    "@deepseek-ai/schemastery": "~3.18.4"
+    "@deepseek-ai/dsh-util-crypto": "0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "@deepseek-ai/dsh-brand": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-timeout": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-util-values": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-attachment": "0.1.7-rc.1",
-    "@deepseek-ai/dsh-invariants": "0.1.7-rc.1",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.1",
+    "@deepseek-ai/dsh-invariants": "0.2.0-rc.1",
     "@deepseek-ai/cordis": "~4.0.4"
   }
 }