@deepseek-ai/dsh-llm 0.2.1-alpha.1 → 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

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`.

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` 组装。

package/lib/index.js

@@ -2190,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

@@ -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    '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}"
+            "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/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/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

@@ -716,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.1-alpha.1",
+  "version": "0.2.1-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -59,16 +59,16 @@
     "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   },
   "dependencies": {
-    "zod": "^4.4.3",
-    "@deepseek-ai/dsh-util-crypto": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-util-crypto": "0.2.1-alpha.2",
     "@deepseek-ai/schemastery": "~3.18.5-alpha.1",
-    "@deepseek-ai/dsh-timeout": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-brand": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-util-values": "0.2.1-alpha.1",
-    "@deepseek-ai/dsh-typert-protocol": "0.2.1-alpha.1"
+    "zod": "^4.4.3",
+    "@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-attachment": "0.2.1-alpha.1",
+    "@deepseek-ai/dsh-attachment": "0.2.1-alpha.2",
     "@deepseek-ai/cordis": "~4.0.5-alpha.1"
   }
 }