@deepseek-ai/dsh-llm 0.2.0-rc.2 → 0.2.1-alpha.2

package/README.i18n.yaml

@@ -21,8 +21,8 @@
   en: c3ecb5a1421f27db
   zh: 4bbd3c0e513845e1
 /deepseek-ai-dsh-llm/use-this-package/minimal-composition:
-  en: 7550d716b90fcb09
-  zh: 77891a44ee623c7a
+  en: 9d481d19dc52e404
+  zh: aa09cf4462e93ba6
 /deepseek-ai-dsh-llm/use-this-package/what-you-can-do:
   en: b45d7a414141734e
   zh: a641c8ea3827cee6
@@ -39,8 +39,8 @@
   en: ae1618577f4e8364
   zh: a6e8ab1563c08dfb
 /deepseek-ai-dsh-llm/understand-the-implementation/main-flow:
-  en: 6dc955a0d80f6ca0
-  zh: f81dbcaeacd8b269
+  en: da12553c289e1705
+  zh: 28827a81cd63ff84
 /deepseek-ai-dsh-llm/understand-the-implementation/invariants:
   en: 0163a050239248e5
   zh: 885c95bedcbe2ff4

package/README.md

@@ -60,6 +60,25 @@ After a successful mount, `ctx.llm.listProviders()` reports the registered route
 
 `GenerateOptions.messages` accepts durable `Message` values and request-only `RequestUserInput` values. Request-only inputs carry user-role content with no `id` or `source`; Session writes and Agent delivery still require durable messages. Callers keep auxiliary inputs unchanged until the stream settles. A caller that records its exact request, such as session-title generation, must use durable messages.
 
+`prepareCall(config, signal, configure?)` accepts concrete `LlmCallConfig` values. The optional synchronous, pure `ConfigureCall` function receives detached, deeply frozen `LlmCallControls` and model metadata from the captured adapter generation. Callers can compose ordinary functions to choose concrete controls; later writes replace earlier ones. Preparation retains the captured route, applies defaults to omitted controls, validates the result, and returns a frozen configuration for recording and dispatch. Callback failures or cancellation reject before dispatch. Preparation requires a registered adapter.
+
+Configuration functions select controls before adapter defaults are materialized. For example, combine least-effort selection with an explicit output cap, then pass `configure(maxTokens)` as the third argument:
+
+```ts
+import type { ConfigureCall } from '@deepseek-ai/dsh-llm'
+
+const leastReasoning: ConfigureCall = (controls, model) => {
+  const first = model.reasoning?.efforts[0]
+  return first === undefined ? controls : { ...controls, reasoningEffort: first.id }
+}
+
+const outputLimit = (maxTokens: number): ConfigureCall =>
+  controls => ({ ...controls, maxTokens })
+
+const configure = (maxTokens: number): ConfigureCall =>
+  (controls, model) => outputLimit(maxTokens)(leastReasoning(controls, model), model)
+```
+
 ### What you can do
 
 - **Stream one model call** — `ctx.llm.stream(options)` yields raw chunks (token-level deltas) for any registered provider and model; consumers assemble them with `BlockAssembler`.
@@ -107,7 +126,7 @@ The service is built on one separation: **the logical contract is provider-neutr
 
 A request is validated against its exact model's capability — context window, output default, reasoning efforts, input modalities, and `systemPromptUpdate` mode — and any adapter-configured defaults are materialized. The runtime preserves freezing for already-frozen input; hand-built callers own input immutability. `prepareCall()` binds those facts, detached context, and retry policy to the exact adapter generation that performs terminal dispatch, so HMR or dynamic settings cannot combine one generation's image capability with another generation's endpoint. An image-capable adapter projects durable references into route-specific request versions; `resolveImageAttachmentAccess()` separately maps an attachment provider's optional host object into the current tool execution world without changing the request image or its `variantId`. A text-only route receives deterministic per-image placeholders, including tool-role result images, without rewriting append-only session history. Durable `FileBlock` references never reach any adapter: request assembly replaces each one, including tool-role result occurrences, with deterministic handle text naming the file and its saved read-only path, resolved through the mounted attachment and filesystem providers. `ctx.llm.fileRequestText(ref)` exposes that exact synchronous projection to request measurement. An image occurrence derived with `offloaded: true` reaches every route as placeholder text through `projectOffloadedImages()`. An image-capable route whose retained occurrences exceed its `LlmImageRequestBudget` at their exact bytes fails with `IMAGE_OFFLOAD_REQUIRED` naming the additional oldest occurrences (`requiredImageOffload()`), never with an unlogged projection; `dsh-compaction-image-offload` logs the selected occurrences in one `image/offload` event and retries. Adapters that charge visual tokens declare per-route `imageRequestPricing`, which `ctx.llm.imageRequestPricing(provider, model)` resolves synchronously for the token meter. Dispatch goes through the `llm/stream` waterfall, then chunks return as token-level deltas and every adapter outcome reaches the consumer as one terminal `finish` chunk.
 
-File detection reads current content, including tool-role result content, on every request without caching message identities or freeze state. The [file-scan decision](../../../.agents/notes/implemented/simplification/2026-09-07-file-content-scan.md) records the measured traversal cost.
+File detection reads current content, including tool-role result content, on every request without caching message identities or freeze state. The [archived file-scan decision](../../../.agents/notes/archived/simplification/2026-09-07-file-content-scan.md) records the measured traversal cost.
 
 ### Invariants
 

package/README.zh.md

@@ -60,6 +60,25 @@ for await (const chunk of ctx.llm.stream({
 
 `GenerateOptions.messages` 接受持久 `Message` 值和仅供请求使用的 `RequestUserInput` 值。仅供请求使用的输入包含 user-role 内容，不含 `id` 或 `source`；Session 写入和 Agent 投递仍然要求持久消息。调用方必须在流结束前保持辅助输入不变。会记录完整请求的调用方（例如会话标题生成）必须使用持久消息。
 
+`prepareCall(config, signal, configure?)` 接受具体的 `LlmCallConfig` 值。可选的同步纯函数 `ConfigureCall` 接收已分离且深度冻结的 `LlmCallControls`，以及捕获的适配器代次所提供的模型元数据。调用方可组合普通函数来选择具体控制项；后执行的写入替换先前的值。准备操作保留捕获的路由，为省略的控制项应用默认值，校验结果，再返回用于记录与分发的冻结配置。回调失败或取消会在分发前拒绝。准备操作要求注册适配器。
+
+配置函数在适配器默认值物化之前选择控制项。例如，将最低强度选择与显式输出上限组合，再将 `configure(maxTokens)` 作为第三个参数传入：
+
+```ts
+import type { ConfigureCall } from '@deepseek-ai/dsh-llm'
+
+const leastReasoning: ConfigureCall = (controls, model) => {
+  const first = model.reasoning?.efforts[0]
+  return first === undefined ? controls : { ...controls, reasoningEffort: first.id }
+}
+
+const outputLimit = (maxTokens: number): ConfigureCall =>
+  controls => ({ ...controls, maxTokens })
+
+const configure = (maxTokens: number): ConfigureCall =>
+  (controls, model) => outputLimit(maxTokens)(leastReasoning(controls, model), model)
+```
+
 ### 你可以做什么
 
 - **流式发起一次模型调用**——`ctx.llm.stream(options)` 为任何已注册提供方与模型产出原始分片（token 级增量）；消费方用 `BlockAssembler` 组装。
@@ -107,7 +126,7 @@ for await (const chunk of ctx.llm.stream({
 
 请求会对照其精确模型的能力校验，包括上下文窗口、输出默认值、推理强度、输入模态与 `systemPromptUpdate` 模式，并填入任何适配器配置的默认值。运行时保留已冻结输入的冻结状态；手动构建请求的调用方负责保证输入不可变。`prepareCall()` 把这些事实、分离的上下文与重试策略绑定到执行最终分发的精确适配器代次，因此 HMR（热模块替换）或动态设置无法把一个代次的图片能力与另一代次的端点混用。支持图片的适配器把持久引用投影为路由专用请求版本；`resolveImageAttachmentAccess()` 会单独把附件提供方的可选宿主对象映射进当前工具执行世界，而不改变请求图片或其 `variantId`。纯文本路由接收确定性的逐图片占位符，包括 tool-role 结果图片，而不会改写仅追加会话历史。持久 `FileBlock` 引用永远不会到达任何适配器：请求组装把每个引用（包括 tool-role 结果中的出现）替换为确定性句柄文本，指出文件与其只读保存路径，路径经由挂载的附件与文件系统提供方解析。`ctx.llm.fileRequestText(ref)` 向请求计量公开相同的同步投影。派生后带有 `offloaded: true` 的图片出现位置，经 `projectOffloadedImages()` 以占位文本到达每条路由。支持图片的路由在保留的出现位置按精确字节超过其 `LlmImageRequestBudget` 时，以 `IMAGE_OFFLOAD_REQUIRED` 失败并说明还需省略多少最老的出现位置（`requiredImageOffload()`），绝不发送未记录的投影；`dsh-compaction-image-offload` 用一条 `image/offload` 事件记录所选位置并重试。对视觉 token 收费的适配器声明按路由的 `imageRequestPricing`，`ctx.llm.imageRequestPricing(provider, model)` 为 token meter 同步解析它。分发经过 `llm/stream` waterfall（瀑布式事件），随后分片以 token 级增量返回，每个适配器结果都以唯一一个终止 `finish` 分片到达消费方。
 
-文件检测在每次请求时读取当前内容，包括 tool-role 结果内容，不缓存消息身份或冻结状态。[文件扫描决策](../../../.agents/notes/implemented/simplification/2026-09-07-file-content-scan.zh.md)记录了实测遍历成本。
+文件检测在每次请求时读取当前内容，包括 tool-role 结果内容，不缓存消息身份或冻结状态。[已归档的文件扫描决策](../../../.agents/notes/archived/simplification/2026-09-07-file-content-scan.md)记录了实测遍历成本。
 
 ### 不变式
 

package/lib/index.js

@@ -119,7 +119,7 @@ function createToolResultMessage(input) {
 */
 /**
 * Base class for all harness errors. Carries a `code` (stable, programmatic —
-* e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+* e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
 * human-readable `message`, and supports `cause` chaining via the standard
 * `ErrorOptions`. `name` defaults to the subclass constructor name.
 */
@@ -840,7 +840,7 @@ function projectToolUpdates(messages, tools, toolUpdate, history) {
 /**
 * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
 * adapters from drifting. See
-* `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+* `docs/subsystems/llm-streaming.md#appidentity--app-attribution`.
 *
 * App-attribution vocabulary for provider requests.
 * @module @deepseek-ai/dsh-llm/attribution
@@ -1802,20 +1802,14 @@ let LlmRuntime = (() => {
 		}
 		/** Notify topology observers without letting one broken listener veto the commit. */
 		emitAdaptersUpdated() {
-			let invariantFailure;
 			for (const listener of this.ctx.events.dispatch("emit", ["llm/adapters-updated"])) try {
 				const returned = listener();
 				if (returned != null && typeof returned.then === "function") Promise.resolve(returned).then(void 0, (error) => {
 					this.warnAdaptersListenerFailure(error);
 				});
 			} catch (error) {
-				if (error?.code === "INVARIANT") {
-					invariantFailure ??= error;
-					continue;
-				}
 				this.warnAdaptersListenerFailure(error);
 			}
-			if (invariantFailure !== void 0) throw invariantFailure;
 		}
 		/** Contained-listener diagnostic shared by the sync and async failure paths. */
 		warnAdaptersListenerFailure(error) {
@@ -2196,20 +2190,33 @@ let LlmRuntime = (() => {
 		* Resolve one call under its current adapter registration. The returned
 		* one-shot handle keeps that registration across header logging and dispatch,
 		* so HMR cannot combine one adapter's capability result with another adapter.
-		* @param config - provider/model route and optional request controls.
+		* An optional synchronous callback selects concrete controls using captured
+		* model metadata. Defaults and validation apply to its result. Callback
+		* failures and cancellation reject preparation before dispatch.
+		* @param config - provider/model route and optional concrete request controls.
 		* @param signal - optional cancellation for adapter-owned capability lookup.
+		* @param configure - pure control selection, called once before defaults and validation.
 		* @returns a prepared config and its registration-bound stream entry point.
 		*/
-		async prepareCall(config, signal) {
-			const registration = this.registration(config.provider);
-			const adapterCall = await registration.adapter.prepareCall(config.provider, config.model, signal);
-			const modelInfo = this.normalizeModelInfo(registration, config.model, adapterCall.model);
-			const resolved = this.resolveCallWithInfo(config, modelInfo);
+		async prepareCall(config, signal, configure) {
+			signal?.throwIfAborted();
+			const { provider, model, ...controls } = config;
+			const registration = this.registration(provider);
+			const adapterCall = await registration.adapter.prepareCall(provider, model, signal);
+			signal?.throwIfAborted();
+			const modelInfo = this.normalizeModelInfo(registration, model, adapterCall.model);
+			const proposed = configure === void 0 ? config : {
+				...configure(deepFreeze(structuredClone(controls)), deepFreeze(modelInfo)),
+				provider,
+				model
+			};
+			signal?.throwIfAborted();
+			const resolved = this.resolveCallWithInfo(proposed, modelInfo);
 			const resolvedConfig = deepFreeze(structuredClone(resolved.config));
 			const context = resolved.context === void 0 ? void 0 : deepFreeze(structuredClone(resolved.context));
 			const adapterDefaults = deepFreeze({
-				...config.reasoningEffort === void 0 && resolvedConfig.reasoningEffort !== void 0 ? { reasoningEffort: true } : {},
-				...config.maxTokens === void 0 && resolvedConfig.maxTokens !== void 0 ? { maxTokens: true } : {}
+				...proposed.reasoningEffort === void 0 && resolvedConfig.reasoningEffort !== void 0 ? { reasoningEffort: true } : {},
+				...proposed.maxTokens === void 0 && resolvedConfig.maxTokens !== void 0 ? { maxTokens: true } : {}
 			});
 			let dispatched = false;
 			return Object.freeze({

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":638,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":631,"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":550,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":543,"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":478,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":471,"column":3},
     },
   ],
   model: {
@@ -211,9 +211,9 @@ export const TYPERT = {
           {
             "kind": "method",
             "name": "prepareCall",
-            "signature": "async prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>",
+            "signature": "async prepareCall( config: LlmCallConfig, signal?: AbortSignal, configure?: ConfigureCall, ): Promise<PreparedLlmCall>",
             "summary": "Resolve one call under its current adapter registration.",
-            "jsDoc": "/**\n * Resolve one call under its current adapter registration. The returned\n * one-shot handle keeps that registration across header logging and dispatch,\n * so HMR cannot combine one adapter's capability result with another adapter.\n * @param config - provider/model route and optional request controls.\n * @param signal - optional cancellation for adapter-owned capability lookup.\n * @returns a prepared config and its registration-bound stream entry point.\n */"
+            "jsDoc": "/**\n * Resolve one call under its current adapter registration. The returned\n * one-shot handle keeps that registration across header logging and dispatch,\n * so HMR cannot combine one adapter's capability result with another adapter.\n * An optional synchronous callback selects concrete controls using captured\n * model metadata. Defaults and validation apply to its result. Callback\n * failures and cancellation reject preparation before dispatch.\n * @param config - provider/model route and optional concrete request controls.\n * @param signal - optional cancellation for adapter-owned capability lookup.\n * @param configure - pure control selection, called once before defaults and validation.\n * @returns a prepared config and its registration-bound stream entry point.\n */"
           },
           {
             "kind": "method",
@@ -264,6 +264,10 @@ export const TYPERT = {
             "name": "CompactionId",
             "declaration": "export type CompactionId = Branded<'CompactionId'>;"
           },
+          {
+            "name": "ConfigureCall",
+            "declaration": "export type ConfigureCall = (controls: Readonly<LlmCallControls>, model: Readonly<LlmResolvedModelInfo>) => LlmCallControls;"
+          },
           {
             "name": "ContentBlock",
             "declaration": "export type ContentBlock = ContentBlockMap[ContentBlockType];"
@@ -338,12 +342,16 @@ export const TYPERT = {
           },
           {
             "name": "LlmCallConfig",
-            "declaration": "export interface LlmCallConfig {\n    provider: string;\n    model: string;\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+            "declaration": "export interface LlmCallConfig extends LlmCallControls {\n    provider: string;\n    model: string;\n}"
           },
           {
             "name": "LlmCallConfigAdapterDefaults",
             "declaration": "export interface LlmCallConfigAdapterDefaults {\n    reasoningEffort?: true;\n    maxTokens?: true;\n}"
           },
+          {
+            "name": "LlmCallControls",
+            "declaration": "export interface LlmCallControls {\n    reasoningEffort?: ReasoningEffortId;\n    temperature?: number;\n    maxTokens?: number;\n    stop?: string[];\n}"
+          },
           {
             "name": "LlmConfigurableProvider",
             "declaration": "export interface LlmConfigurableProvider {\n    provider: string;\n    displayName: string;\n    settingsNs: string;\n    settingsPath: readonly string[];\n    declared?: boolean;\n    error?: string;\n}"
@@ -414,7 +422,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    schedule: { kind: 'schedule'; } & ContextFormed;\n    'compact-checkpoint': CompactionCheckpointSource;\n    'session-reference': SessionReferenceSource;\n    'user-question-reply': { kind: 'user-question-reply'; callId: ToolCallId; outcome: 'answered'; };\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    'working-directory': { kind: 'working-directory'; };\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    'compact-checkpoint': CompactionCheckpointSource;\n    'user-question-reply': { kind: 'user-question-reply'; callId: ToolCallId; outcome: 'answered'; };\n    goal: GoalMessageSource;\n    schedule: { kind: 'schedule'; } & ContextFormed;\n    'session-reference': SessionReferenceSource;\n}"
           },
           {
             "name": "ModelMessageSource",

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":638,"column":9},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":631,"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":550,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":543,"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":478,"column":3},
+      sourceLocation: {"file":"packages/llm/llm/src/index.ts","line":471,"column":3},
     },
   ],
 }

package/lib/types/attribution.d.ts

@@ -1,7 +1,7 @@
 /**
  * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
  * adapters from drifting. See
- * `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+ * `docs/subsystems/llm-streaming.md#appidentity--app-attribution`.
  *
  * App-attribution vocabulary for provider requests.
  * @module @deepseek-ai/dsh-llm/attribution

package/lib/types/attribution.js

@@ -1,7 +1,7 @@
 /**
  * Centralize the non-secret product identity every provider request sends as `User-Agent`, keeping
  * adapters from drifting. See
- * `.agents/notes/implemented/architecture/2026-06-21-mandatory-app-attribution-headers.md`.
+ * `docs/subsystems/llm-streaming.md#appidentity--app-attribution`.
  *
  * App-attribution vocabulary for provider requests.
  * @module @deepseek-ai/dsh-llm/attribution

package/lib/types/call-config.d.ts

@@ -5,22 +5,35 @@
  * changed snapshots instead of allowing silent per-call drift.
  * @module dsh-llm/call-config
  */
-import type { GenerateOptions } from './types.ts';
+import type { GenerateOptions, LlmResolvedModelInfo } from './types.ts';
 import type { ReasoningEffortId } from './brand.ts';
+/** Concrete generation settings; omitted controls use the selected route's defaults. */
+export interface LlmCallControls {
+    reasoningEffort?: ReasoningEffortId;
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}
 /**
  * Provider, model, reasoning effort, and sampling scalars of one conversation's
  * requests. Every field maps 1:1 onto the same-named `GenerateOptions` field;
  * the loop builds requests from the logged header rather than accepting these
  * per call.
  */
-export interface LlmCallConfig {
+export interface LlmCallConfig extends LlmCallControls {
     provider: string;
     model: string;
-    reasoningEffort?: ReasoningEffortId;
-    temperature?: number;
-    maxTokens?: number;
-    stop?: string[];
 }
+/**
+ * Synchronous, pure configuration of one call before defaults and validation.
+ * Compose functions in the desired order; later writes replace earlier ones.
+ * The returned controls cannot change the captured route. Errors reject
+ * preparation before dispatch; only the resolved configuration is recordable.
+ * @param controls - detached, deeply frozen proposed controls, without defaults.
+ * @param model - detached, deeply frozen metadata from the captured adapter generation.
+ * @returns concrete controls; omitted fields receive the route's defaults.
+ */
+export type ConfigureCall = (controls: Readonly<LlmCallControls>, model: Readonly<LlmResolvedModelInfo>) => LlmCallControls;
 /**
  * Effective config fields supplied by exact-model adapter resolution rather
  * than by the caller's request proposal.

package/lib/types/error.d.ts

@@ -5,7 +5,7 @@
  */
 /**
  * Base class for all harness errors. Carries a `code` (stable, programmatic —
- * e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
  * human-readable `message`, and supports `cause` chaining via the standard
  * `ErrorOptions`. `name` defaults to the subclass constructor name.
  */

package/lib/types/error.js

@@ -5,7 +5,7 @@
  */
 /**
  * Base class for all harness errors. Carries a `code` (stable, programmatic —
- * e.g. `NO_ADAPTER`, `INVALID_ARGS`, `INVARIANT`) distinct from the
+ * e.g. `NO_ADAPTER`, `INVALID_ARGS`) distinct from the
  * human-readable `message`, and supports `cause` chaining via the standard
  * `ErrorOptions`. `name` defaults to the subclass constructor name.
  */

package/lib/types/index.d.ts

@@ -10,7 +10,7 @@ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 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';
+import type { ConfigureCall, LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
 import { HarnessError } from './error.ts';
 import type { FileAttachmentRef } from '@deepseek-ai/dsh-attachment';
 export * from './attribution.ts';
@@ -24,7 +24,7 @@ export * from './message.ts';
 export * from './retry-policy.ts';
 export { BlockAssembler } from './assembler.ts';
 export { callConfigEquals, isAgentLoopRequest, markAgentLoopRequest } from './call-config.ts';
-export type { LlmCallConfig, LlmCallConfigAdapterDefaults } from './call-config.ts';
+export type { ConfigureCall, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmCallControls } from './call-config.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         llm: LlmRuntime;
@@ -379,11 +379,15 @@ export declare class LlmRuntime extends TypertRemoteService {
      * Resolve one call under its current adapter registration. The returned
      * one-shot handle keeps that registration across header logging and dispatch,
      * so HMR cannot combine one adapter's capability result with another adapter.
-     * @param config - provider/model route and optional request controls.
+     * An optional synchronous callback selects concrete controls using captured
+     * model metadata. Defaults and validation apply to its result. Callback
+     * failures and cancellation reject preparation before dispatch.
+     * @param config - provider/model route and optional concrete request controls.
      * @param signal - optional cancellation for adapter-owned capability lookup.
+     * @param configure - pure control selection, called once before defaults and validation.
      * @returns a prepared config and its registration-bound stream entry point.
      */
-    prepareCall(config: LlmCallConfig, signal?: AbortSignal): Promise<PreparedLlmCall>;
+    prepareCall(config: LlmCallConfig, signal?: AbortSignal, configure?: ConfigureCall): Promise<PreparedLlmCall>;
     private registration;
     /** Remove replay state whose historical route is owned by another adapter. */
     private forAdapter;

package/lib/types/index.js

@@ -237,30 +237,22 @@ let LlmRuntime = (() => {
         emitAdaptersUpdated() {
             // Cordis emit uses Array.map: one synchronous throw starves later
             // listeners. Registry notifications are non-vetoing, so contain each
-            // callback independently; INVARIANT-coded failures still surface.
-            let invariantFailure;
+            // callback independently.
             for (const listener of this.ctx.events.dispatch('emit', ['llm/adapters-updated'])) {
                 try {
                     const returned = listener();
                     if (returned != null && typeof returned.then === 'function') {
                         // An emit listener may still be an async function; its rejection
-                        // cannot reach the synchronous INVARIANT rethrow below, so it is
-                        // contained here instead of becoming an unhandled rejection.
+                        // is contained here instead of becoming an unhandled rejection.
                         void Promise.resolve(returned).then(undefined, (error) => {
                             this.warnAdaptersListenerFailure(error);
                         });
                     }
                 }
                 catch (error) {
-                    if (error?.code === 'INVARIANT') {
-                        invariantFailure ??= error;
-                        continue;
-                    }
                     this.warnAdaptersListenerFailure(error);
                 }
             }
-            if (invariantFailure !== undefined)
-                throw invariantFailure;
         }
         /** Contained-listener diagnostic shared by the sync and async failure paths. */
         warnAdaptersListenerFailure(error) {
@@ -724,24 +716,35 @@ let LlmRuntime = (() => {
          * Resolve one call under its current adapter registration. The returned
          * one-shot handle keeps that registration across header logging and dispatch,
          * so HMR cannot combine one adapter's capability result with another adapter.
-         * @param config - provider/model route and optional request controls.
+         * An optional synchronous callback selects concrete controls using captured
+         * model metadata. Defaults and validation apply to its result. Callback
+         * failures and cancellation reject preparation before dispatch.
+         * @param config - provider/model route and optional concrete request controls.
          * @param signal - optional cancellation for adapter-owned capability lookup.
+         * @param configure - pure control selection, called once before defaults and validation.
          * @returns a prepared config and its registration-bound stream entry point.
          */
-        async prepareCall(config, signal) {
-            const registration = this.registration(config.provider);
-            const adapterCall = await registration.adapter.prepareCall(config.provider, config.model, signal);
-            const modelInfo = this.normalizeModelInfo(registration, config.model, adapterCall.model);
-            const resolved = this.resolveCallWithInfo(config, modelInfo);
+        async prepareCall(config, signal, configure) {
+            signal?.throwIfAborted();
+            const { provider, model, ...controls } = config;
+            const registration = this.registration(provider);
+            const adapterCall = await registration.adapter.prepareCall(provider, model, signal);
+            signal?.throwIfAborted();
+            const modelInfo = this.normalizeModelInfo(registration, model, adapterCall.model);
+            const proposed = configure === undefined
+                ? config
+                : { ...configure(deepFreeze(structuredClone(controls)), deepFreeze(modelInfo)), provider, model };
+            signal?.throwIfAborted();
+            const resolved = this.resolveCallWithInfo(proposed, modelInfo);
             const resolvedConfig = deepFreeze(structuredClone(resolved.config));
             const context = resolved.context === undefined
                 ? undefined
                 : deepFreeze(structuredClone(resolved.context));
             const adapterDefaults = deepFreeze({
-                ...config.reasoningEffort === undefined && resolvedConfig.reasoningEffort !== undefined
+                ...proposed.reasoningEffort === undefined && resolvedConfig.reasoningEffort !== undefined
                     ? { reasoningEffort: true }
                     : {},
-                ...config.maxTokens === undefined && resolvedConfig.maxTokens !== undefined
+                ...proposed.maxTokens === undefined && resolvedConfig.maxTokens !== undefined
                     ? { maxTokens: true }
                     : {},
             });

package/lib/types/types.d.ts

@@ -348,7 +348,7 @@ export interface LlmReasoningEffortInfo {
 }
 /** Selectable reasoning efforts for one exact provider/model route. */
 export interface LlmModelReasoningInfo {
-    /** Supported efforts in adapter-preferred display order. */
+    /** Supported efforts from least to greatest selectable reasoning effort, not predicted token use or latency. */
     efforts: readonly LlmReasoningEffortInfo[];
     /**
      * Adapter-configured default materialized into requests when callers omit
@@ -524,8 +524,8 @@ export interface GenerateOptions {
     sessionId?: Branded<'SessionId'>;
     /**
      * Provider-neutral classification for an auxiliary model call. Adapters may
-     * map the purpose to model-hidden transport metadata or purpose-specific
-     * generation policy. Ordinary conversation requests leave it unset.
+     * map the purpose to model-hidden transport metadata. Ordinary conversation
+     * requests leave it unset.
      */
     purpose?: 'compaction' | 'session-title';
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-llm",
   "description": "Provider-neutral LLM service interface for the DeepSeek Harness",
-  "version": "0.2.0-rc.2",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -18,10 +18,6 @@
       "types": "./lib/types/index.d.ts",
       "default": "./lib/index.js"
     },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
     "./types": {
       "types": "./lib/types/types.d.ts",
       "default": "./lib/types/types.js"
@@ -51,7 +47,6 @@
   },
   "files": [
     "lib/index.js",
-    "lib/invariant.js",
     "lib/types/**/*.js",
     "lib/types/**/*.d.ts",
     "lib/typert.host.js",
@@ -61,20 +56,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "dependencies": {
+    "@deepseek-ai/dsh-util-crypto": "0.2.1-alpha.2",
+    "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-crypto": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-timeout": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-brand": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "~3.18.4",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.2.0-rc.2"
+    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-brand": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-invariants": "0.2.0-rc.2",
-    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
-    "@deepseek-ai/cordis": "~4.0.4"
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   }
 }

package/lib/invariant.js

@@ -1,84 +0,0 @@
-//#region lib/types/invariant.js
-/** Package-owned LLM stream-protocol invariants. @module @deepseek-ai/dsh-llm/invariant */
-const PACKAGE_NAME = "@deepseek-ai/dsh-llm";
-/** Cordis companion plugin name. */
-const name = "llm-invariant";
-/** Service required before the companion can reserve package ownership. */
-const inject = ["invariants"];
-/** Require one chunk index to be a non-negative safe integer. */
-function validateIndex(index, fail) {
-	if (!Number.isSafeInteger(index) || index < 0) fail(`LLM stream block index must be a non-negative safe integer, got ${index}`);
-}
-/** Require a delta to address an open block of its matching type. */
-function validateDelta(open, index, expected, fail) {
-	validateIndex(index, fail);
-	const actual = open.get(index);
-	if (actual !== expected) fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`);
-}
-/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
-async function* validateStream(source, fail) {
-	const open = /* @__PURE__ */ new Map();
-	let usageSeen = false;
-	let finished = false;
-	for await (const chunk of source) {
-		if (finished) fail(`LLM stream emitted ${chunk.type} after terminal finish`);
-		switch (chunk.type) {
-			case "block-start":
-				validateIndex(chunk.index, fail);
-				if (open.has(chunk.index)) fail(`LLM stream repeated block-start index ${chunk.index}`);
-				open.set(chunk.index, chunk.blockType);
-				break;
-			case "text-delta":
-				validateDelta(open, chunk.index, "text", fail);
-				break;
-			case "reasoning-delta":
-				validateDelta(open, chunk.index, "reasoning", fail);
-				break;
-			case "tool-call-delta":
-				validateDelta(open, chunk.index, "tool-call", fail);
-				break;
-			case "block-end": {
-				validateIndex(chunk.index, fail);
-				const blockType = open.get(chunk.index);
-				if (blockType === void 0) fail(`LLM stream block-end index ${chunk.index} has no open block`);
-				if (chunk.block.type !== blockType) fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`);
-				open.delete(chunk.index);
-				break;
-			}
-			case "usage":
-				if (usageSeen) fail("LLM stream emitted usage more than once");
-				usageSeen = true;
-				break;
-			case "finish":
-				if (open.size > 0 && chunk.reason.kind !== "error" && chunk.reason.kind !== "aborted") fail(`LLM stream finished with ${open.size} open block(s)`);
-				finished = true;
-				break;
-		}
-		yield chunk;
-	}
-	if (!finished) fail("LLM stream ended without a terminal finish chunk");
-}
-/** Install validation around every provider stream. */
-const install = (ctx, fail) => {
-	ctx.on("llm/stream", (_options, next) => validateStream(next(), fail), {
-		global: true,
-		prepend: true
-	});
-	ctx.on("llm/adapters-updated", () => {
-		const llm = ctx.get("llm");
-		if (llm === void 0) return;
-		for (const provider of llm.listProviders()) try {
-			llm.providerRetryPolicy(provider.id);
-		} catch {
-			fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`);
-		}
-	}, { global: true });
-};
-/**
-* Register the LLM invariant companion.
-* @param ctx - Cordis context carrying the invariant service.
-* @returns the installed registration's disposer after setup succeeds.
-*/
-const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//#endregion
-export { apply, inject, name };

package/lib/types/invariant.d.ts

@@ -1,13 +0,0 @@
-/** Package-owned LLM stream-protocol invariants. @module @deepseek-ai/dsh-llm/invariant */
-import type { Context } from '@deepseek-ai/cordis';
-/** Cordis companion plugin name. */
-export declare const name = "llm-invariant";
-/** Service required before the companion can reserve package ownership. */
-export declare const inject: string[];
-/**
- * Register the LLM invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export declare const apply: (ctx: Context) => Promise<() => void>;
-//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -1,100 +0,0 @@
-/** Package-owned LLM stream-protocol invariants. @module @deepseek-ai/dsh-llm/invariant */
-const PACKAGE_NAME = '@deepseek-ai/dsh-llm';
-/** Cordis companion plugin name. */
-export const name = 'llm-invariant';
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants'];
-/** Require one chunk index to be a non-negative safe integer. */
-function validateIndex(index, fail) {
-    if (!Number.isSafeInteger(index) || index < 0) {
-        fail(`LLM stream block index must be a non-negative safe integer, got ${index}`);
-    }
-}
-/** Require a delta to address an open block of its matching type. */
-function validateDelta(open, index, expected, fail) {
-    validateIndex(index, fail);
-    const actual = open.get(index);
-    if (actual !== expected) {
-        fail(`${expected} delta at index ${index} requires an open ${expected} block, got ${String(actual)}`);
-    }
-}
-/** Wrap one provider stream and enforce its grammar as chunks are consumed. */
-async function* validateStream(source, fail) {
-    const open = new Map();
-    let usageSeen = false;
-    let finished = false;
-    for await (const chunk of source) {
-        if (finished)
-            fail(`LLM stream emitted ${chunk.type} after terminal finish`);
-        switch (chunk.type) {
-            case 'block-start':
-                validateIndex(chunk.index, fail);
-                if (open.has(chunk.index))
-                    fail(`LLM stream repeated block-start index ${chunk.index}`);
-                open.set(chunk.index, chunk.blockType);
-                break;
-            case 'text-delta':
-                validateDelta(open, chunk.index, 'text', fail);
-                break;
-            case 'reasoning-delta':
-                validateDelta(open, chunk.index, 'reasoning', fail);
-                break;
-            case 'tool-call-delta':
-                validateDelta(open, chunk.index, 'tool-call', fail);
-                break;
-            case 'block-end': {
-                validateIndex(chunk.index, fail);
-                const blockType = open.get(chunk.index);
-                if (blockType === undefined)
-                    fail(`LLM stream block-end index ${chunk.index} has no open block`);
-                if (chunk.block.type !== blockType) {
-                    fail(`LLM stream block-end index ${chunk.index} closes ${chunk.block.type}, expected ${blockType}`);
-                }
-                open.delete(chunk.index);
-                break;
-            }
-            case 'usage':
-                if (usageSeen)
-                    fail('LLM stream emitted usage more than once');
-                usageSeen = true;
-                break;
-            case 'finish':
-                if (open.size > 0 && chunk.reason.kind !== 'error' && chunk.reason.kind !== 'aborted') {
-                    fail(`LLM stream finished with ${open.size} open block(s)`);
-                }
-                finished = true;
-                break;
-        }
-        yield chunk;
-    }
-    if (!finished)
-        fail('LLM stream ended without a terminal finish chunk');
-}
-/** Install validation around every provider stream. */
-const install = (ctx, fail) => {
-    ctx.on('llm/stream', (_options, next) => validateStream(next(), fail), { global: true, prepend: true });
-    ctx.on('llm/adapters-updated', () => {
-        // A disposer-time emit can outlive the service-store entry during whole-
-        // context teardown; only a live service promises a readable registry.
-        const llm = ctx.get('llm');
-        if (llm === undefined)
-            return;
-        for (const provider of llm.listProviders()) {
-            try {
-                llm.providerRetryPolicy(provider.id);
-            }
-            catch {
-                // Reaching here IS the violation: the notification promised a readable
-                // registry, and only that broken promise can make the lookup throw.
-                fail(`llm/adapters-updated fired while provider "${provider.id}" has no readable registration`);
-            }
-        }
-    }, { global: true });
-};
-/**
- * Register the LLM invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
-//# sourceMappingURL=invariant.js.map