@crazx/dsh-agent-default-model 0.1.1-rc.2.zw.1 → 0.1.2-alpha.3.zw.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/agent-default-model/README.md
-README.md: b2f077fc82924b1f47ca6e202501fb81a0319af1
-README.zh.md: d6ab00a036fefcc9e8ffa6eab194f94da475938d
+README.md: 8f447c48d352406a8c3035b1ff0407367e1bc1c3
+README.zh.md: cca145bde078145505dd5718b222bbc55248ae13

package/README.md

@@ -1,10 +1,15 @@
+---
+description: "The deployment default model selection for users and maintainers choosing, configuring, or debugging which model freshly created agents start on."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-agent-default-model
 
 English | [中文](README.zh.md)
 
-The deployment default used when an entry point creates an Agent that has no session-local model selection. `AgentDefaultModelConfig` provides `ctx.agentDefaultModel`; direct entry points such as `dsh --profile headless` and Host-backed entry points such as ApiProxy read the same service instead of owning parallel provider/model defaults.
+## Summary
 
-The plugin config requires `{ provider, model }`. That composition entry is the base of the `agent-default-model` Settings section; a mounted settings provider layers the user's choice over it and changes are visible on the next `currentSelection()` read. `reasoningEffort` belongs to the Settings section but deliberately not to plugin config: a complete saved selection can clear an effort when the next selected model has none, while a composition value would be inherited again.
+`dsh-agent-default-model` supplies the deployment's default model selection — provider, model, and optional reasoning effort — that agent entry points apply when a fresh session has no selection of its own. Direct entry points such as `dsh --profile headless` and Host-backed entry points read `ctx.agentDefaultModel` instead of owning parallel defaults, so one composition entry controls which model new agents start on. A mounted settings provider layers the user's choice over the composition entry, and a saved change is visible on the next read. It is one process-wide default: per-session model selection remains the entry point's responsibility. Choose it when you want a single place to set the model new agents use.
 
 - `ctx.agentDefaultModel.currentSelection()` returns a detached `{ provider, model, reasoningEffort? }` selection for a newly created Agent.
 - `ctx.agentDefaultModel.saveSelection(selection)` saves the complete user selection. Without a settings provider it is a no-op and the composition entry remains current.
@@ -13,18 +18,118 @@ The plugin config requires `{ provider, model }`. That composition entry is the
 
 The remembered efforts live in the separate `agent-model-efforts` Settings section (an entry list keyed by provider/model), so switching the default selection never overwrites them. The service stores what it is told; the consumer that consults a memory validates it against the live model capability, because a remembered level can outlive the declaration that offered it.
 
-The service does not validate catalog membership. A provider route may serve an unadvertised model, and the consumer that actually opens a model request owns availability diagnostics.
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount this package wherever agents are created without an explicit model route. The service answers one question — which model should a fresh agent use? — so entry points that create agents consult it instead of re-implementing a default.
+
+### Configure the default
+
+The composition entry is the base of the default: it requires a provider and model and stays usable without any settings provider.
+
+```yaml
+- name: '@deepseek-ai/dsh-agent-default-model'
+  config:
+    provider: deepseek
+    model: deepseek-chat
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `provider` | required | Registered provider route for fresh agents |
+| `model` | required | Provider-owned model id for fresh agents |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-agent-default-model) is the exhaustive source for every accepted field. `reasoningEffort` is deliberately not a config field: it belongs to the settings layer, so a complete saved selection can clear an effort when the next selected model has none, while a composition value would be inherited again.
+
+### Read and change the default
+
+`currentSelection()` returns a detached `{ provider, model, reasoningEffort? }` for a newly created agent; `saveSelection()` stores the complete selection for later agents.
+
+```text
+const selection = ctx.agentDefaultModel.currentSelection()
+await ctx.agentDefaultModel.saveSelection({ provider, model, reasoningEffort: 'high' })
+```
+
+Without a settings provider, `saveSelection()` is a no-op and the composition entry remains current. The service does not validate catalog membership: a provider route may serve an unadvertised model, and the consumer that opens a model request owns availability diagnostics.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains how the service realizes the behavior above; the observable contract is covered in [Use this package](#use-this-package).
+
+### Design concept
 
+The service is a composition entry with a settings-backed source. The plugin config supplies the base `{ provider, model }`; when a settings provider is mounted, the `agent-default-model` settings section becomes the live source and every consumer reads through `currentSelection()`, so a settings write needs no registration-level rebuild. `reasoningEffort` lives only in the settings schema — the config cannot carry it, because an effort cleared by a new selection must stay cleared rather than being re-inherited from composition.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `AgentDefaultModelConfig` service, settings section install, `currentSelection`/`saveSelection` |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion |
+
+### Behavior notes
+
+Both public methods are thin reads and writes over that source: `currentSelection()` returns a fresh detached object so a caller can hold it without aliasing service state, and `saveSelection()` writes the whole selection through `ctx.settings` when present.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+The package-level contract is enough for most consumers; read these when you need the surrounding domain.
+
+- [Core subsystem](../../../docs/subsystems/core.md) — the `Agent` handle and `AgentOptions` route selection.
+- [agent-loop package](../agent-loop/README.md) — how agents resolve provider and model at request time.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-agent-default-model) — every accepted config field and its source declaration.
+- [Core group map](../README.md) — how the core packages compose.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through the provider/model selection supplied to an entry point; request assembly and adapters own the model-visible request.
+Indirectly, through the `ModelSelection` the service supplies to an entry point; request assembly and the provider adapters own the model-visible request.
 
 #### KV Cache effect
 
-Changing the default affects only Agents that subsequently resolve from it. An existing session whose request log already names a selection keeps that selection, so this service does not invalidate its established prefix.
+Changing the default affects only agents that subsequently resolve from it. An existing session whose request log already names a selection keeps that selection, so this service does not invalidate its established prefix.
 
 ## Known Limitations and Deferred Work
 
-- The service owns one process-wide default; per-session selection remains the entry point's responsibility.
-- Without a settings provider, `saveSelection()` cannot retain a selection and `rememberEffort()` cannot retain a level for a later Agent.
-- The effort memory grows one entry per route the user has explicitly tuned; it is never pruned automatically (a stale entry is dropped at consult time instead).
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define the service's scope. They are current package constraints, not a task backlog.
+
+- **One process-wide default** — the service owns a single default; per-session model selection remains the entry point's responsibility.
+- **No retention without a settings provider** — `saveSelection()` cannot keep a selection for a later agent when no settings provider is mounted, and `rememberEffort()` cannot retain a level.
+- **Effort memory is unbounded** — the memory grows one entry per route the user has explicitly tuned; it is never pruned automatically (a stale entry is dropped at consult time instead).
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -1,30 +1,135 @@
+---
+description: "面向用户与维护者的部署默认模型选择说明，用于选择、配置或调试新创建的 agent 从哪个模型开始。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-agent-default-model
 
 [English](README.md) | 中文
 
-该部署默认值供入口在创建尚无会话级模型选择的 Agent 时使用。`AgentDefaultModelConfig` 提供 `ctx.agentDefaultModel`；`dsh --profile headless` 这类直接入口与 ApiProxy 这类由 Host 支撑的入口读取同一服务，而不是分别持有平行的提供方／模型默认值。
+## 概述
 
-插件配置必须提供 `{ provider, model }`。该组合配置项构成 Settings 中 `agent-default-model` 分节的基础层；挂载的设置提供方在其上叠加用户选择，更改会在下一次调用 `currentSelection()` 时可见。`reasoningEffort` 属于该 Settings 分节，但特意不属于插件配置：完整保存的选择必须能在下一个选定模型没有推理（reasoning）强度时清除旧值，而组合配置值会再次被继承。
+`dsh-agent-default-model` 提供部署的默认模型选择——提供方、模型与可选的推理（reasoning）强度——agent 入口在全新会话没有自己的选择时应用它。`dsh --profile headless` 这类直接入口与 Host 支撑的入口读取 `ctx.agentDefaultModel`，而不是各自持有平行默认值，因此一个组合配置项就能控制新 agent 从哪个模型开始。挂载的设置提供方会把用户选择叠加在组合配置项之上，保存的更改在下一次读取时可见。它是单一的进程级默认值：按会话的模型选择仍由入口负责。想要为新建 agent 所用模型设置单一位置时，请选择本包。
 
-- `ctx.agentDefaultModel.currentSelection()` 返回一份独立的 `{ provider, model, reasoningEffort? }` 选择，供新创建的 Agent 使用。
+- `ctx.agentDefaultModel.currentSelection()` 返回一份分离的 `{ provider, model, reasoningEffort? }` 选择，供新创建的 Agent 使用。
 - `ctx.agentDefaultModel.saveSelection(selection)` 保存完整的用户选择。未挂载设置提供方时，此调用不执行任何操作，组合配置项仍为当前值。
 - `ctx.agentDefaultModel.recallEffort(provider, model)` 返回用户在该路由上最后一次显式选择的推理强度；没有记忆时返回 `undefined`。
 - `ctx.agentDefaultModel.rememberEffort(provider, model, effort?)` 记录——或在 `effort` 为 `undefined` 时清除——该路由的记忆强度。未挂载设置提供方时同样不执行任何操作。
 
 被记忆的强度存放在独立的 `agent-model-efforts` Settings 分节（以提供方／模型为键的条目列表），因此切换默认选择不会覆盖它们。该服务只保存被告知的值；咨询记忆的消费方会对照模型的实时能力校验，因为被记住的等级可能比当初提供它的声明活得更久。
 
-该服务不校验目录成员关系。提供方路由可以服务未在目录中公布的模型；实际发起模型请求的消费方负责可用性诊断。
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在创建 agent 且未显式给出模型路由的任何地方挂载本包。该服务回答一个问题——新 agent 应该使用哪个模型？——因此创建 agent 的入口查询它，而不必重新实现默认值。
+
+### 配置默认值
+
+组合配置项是默认值的基础：它要求提供方与模型，并且不依赖任何设置提供方也能使用。
+
+```yaml
+- name: '@deepseek-ai/dsh-agent-default-model'
+  config:
+    provider: deepseek
+    model: deepseek-chat
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `provider` | 必填 | 新 agent 使用的已注册提供方路由 |
+| `model` | 必填 | 新 agent 使用的、由提供方持有的模型 id |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-agent-default-model)是每个受支持字段的穷尽式真源。`reasoningEffort` 刻意不是配置字段：它属于设置层，因此完整保存的选择可以在下一个选定的模型没有推理强度时清除旧值，而组合配置值会再次被继承。
+
+### 读取与更改默认值
+
+`currentSelection()` 为新创建的 agent 返回一份独立的 `{ provider, model, reasoningEffort? }`；`saveSelection()` 为后续 agent 保存完整选择。
+
+```text
+const selection = ctx.agentDefaultModel.currentSelection()
+await ctx.agentDefaultModel.saveSelection({ provider, model, reasoningEffort: 'high' })
+```
+
+未挂载设置提供方时，`saveSelection()` 不执行任何操作，组合配置项仍为当前值。该服务不校验目录成员关系：提供方路由可以服务未在目录中公布的模型；发起模型请求的消费方负责可用性诊断。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释该服务如何实现上述行为；可观察约定已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
 
+该服务是一个带设置后援真源的组合配置项。插件配置提供基础 `{ provider, model }`；挂载设置提供方后，`agent-default-model` 设置分节成为实时真源，所有消费方都通过 `currentSelection()` 读取，因此设置写入无需重建任何注册级事实。`reasoningEffort` 只存在于设置 schema 中——配置不能携带它，因为被新选择清除的推理强度必须保持清除，而不是从组合中再次继承。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`AgentDefaultModelConfig` 服务、设置分节安装、`currentSelection`/`saveSelection` |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式配套 |
+
+### 行为说明
+
+两个公开方法都是对该真源的薄读写：`currentSelection()` 返回全新独立对象，调用方持有它不会别名化服务状态；`saveSelection()` 在存在 `ctx.settings` 时写入完整选择。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+包级约定对大多数消费方已经足够；需要周边领域时再阅读以下页面。
+
+- [Core 子系统](../../../docs/subsystems/core.zh.md)——`Agent` 句柄与 `AgentOptions` 路由选择。
+- [agent-loop 包](../agent-loop/README.zh.md)——agent 在请求时如何解析提供方与模型。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-agent-default-model)——每个受支持配置字段及其源声明。
+- [core 分组地图](../README.zh.md)——core 各包如何组合。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-通过提供给入口的提供方／模型选择间接影响；模型可见请求由请求组装与适配器负责。
+通过该服务提供给入口的 `ModelSelection` 间接影响；模型可见请求由请求组装与提供方适配器负责。
 
 #### KV Cache 影响
 
-更改默认值只影响之后从该默认值解析选择的 Agent。请求日志已经指明选择的现有会话仍沿用该选择，因此本服务不会使其已建立的前缀失效。
+更改默认值只影响之后从它解析选择的 agent。请求日志已经指明选择的现有会话仍沿用该选择，因此本服务不会使其已建立的前缀失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制界定该服务的范围。它们是当前包约束，不是任务积压。
+
+- **单一的进程级默认值**——该服务只拥有一个默认值；按会话的模型选择仍由入口负责。
+- **没有设置提供方时无法保留**——未挂载设置提供方时，`saveSelection()` 无法为后续 agent 保留选择，`rememberEffort()` 也无法记住等级。
+- **推理记忆无上界**——记忆按用户显式调过的路由各存一条，不会自动清理（陈旧条目在咨询时丢弃）。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
 
-## 已知限制与暂缓事项
+无。
 
-- 该服务只拥有一项进程级默认值；每个会话的选择仍由入口负责。
-- 未挂载设置提供方时，`saveSelection()` 无法保留选择，`rememberEffort()` 也无法为后续 Agent 保留等级。
-- 强度记忆按用户显式调过的路由各存一条，永不自动清理（陈旧条目在咨询时丢弃）。
+</details>

package/lib/index.js

@@ -1,7 +1,6 @@
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
 import { ReasoningEffortId } from "@deepseek-ai/dsh-llm";
-import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 //#region lib/types/index.js
 /**
 * Default model selection for an Agent without a session-specific selection,
@@ -11,9 +10,9 @@ import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-sett
 * @module @deepseek-ai/dsh-agent-default-model
 */
 /** Settings namespace carrying the default model selection for future Agents. */
-const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE = settingsNamespace("agent-default-model");
+const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE = "agent-default-model";
 /** Settings namespace carrying the per-route reasoning-effort memory. */
-const AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE = settingsNamespace("agent-model-efforts");
+const AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE = "agent-model-efforts";
 /** Schema of the default Agent model settings section. */
 const AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA = z.object({
 	provider: z.string().required(),
@@ -54,19 +53,23 @@ var AgentDefaultModelConfig = class extends Service {
 			model: config.model
 		};
 		this.source = () => entry;
-		installSettingsSection(ctx, AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA, entry, {
-			setSource: (current) => {
-				this.source = current;
-			},
-			onChange: () => {}
+		ctx.inject(["settings"], (settingsCtx) => {
+			settingsCtx.settings.installSection(ctx, AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE, AGENT_DEFAULT_MODEL_SETTINGS_SCHEMA, entry, {
+				setSource: (current) => {
+					this.source = current;
+				},
+				onChange: () => {}
+			});
 		});
 		const effortsEntry = { entries: [] };
 		this.effortsSource = () => effortsEntry;
-		installSettingsSection(ctx, AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE, AGENT_MODEL_EFFORTS_SETTINGS_SCHEMA, effortsEntry, {
-			setSource: (current) => {
-				this.effortsSource = current;
-			},
-			onChange: () => {}
+		ctx.inject(["settings"], (settingsCtx) => {
+			settingsCtx.settings.installSection(ctx, AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE, AGENT_MODEL_EFFORTS_SETTINGS_SCHEMA, effortsEntry, {
+				setSource: (current) => {
+					this.effortsSource = current;
+				},
+				onChange: () => {}
+			});
 		});
 	}
 	/**

package/lib/types/index.d.ts

@@ -19,9 +19,9 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /** Settings namespace carrying the default model selection for future Agents. */
-export declare const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const AGENT_DEFAULT_MODEL_SETTINGS_NAMESPACE = "agent-default-model";
 /** Settings namespace carrying the per-route reasoning-effort memory. */
-export declare const AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
+export declare const AGENT_MODEL_EFFORTS_SETTINGS_NAMESPACE = "agent-model-efforts";
 /** Stored and composed default model selection. */
 export interface AgentDefaultModelSettings {
     /** Registered provider route. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crazx/dsh-agent-default-model",
   "description": "Default model selection shared by Agent entry points",
-  "version": "0.1.1-rc.2.zw.1",
+  "version": "0.1.2-alpha.3.zw.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,20 +32,20 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-agent": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
   }
 }