deepseek-harness/packages/core/agent-default-model/README.md

---

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 | 中文

Summary

dsh-agent-default-model gives newly created agents a shared default provider and model when their sessions do not specify one. Use it to choose the starting model once for all supported agent entry points, including dsh --profile headless. When settings are available, users can override the configured selection, including reasoning effort, and saved changes apply to subsequent reads. The default is process-wide; per-session model selection remains the responsibility of the entry point that creates the agent.

Table of Contents

• Use this package
• Understand the implementation
• Further Exploration
• Model Experience
• Known Limitations and Deferred Work
• Dev Note

---

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.

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

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.

---

Understand the implementation

Implementation internals — click to expand

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` | | — | No runtime invariant companion is published; settings validation owns the only mutable-value relationship. | ### 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.

---

Further Exploration

The package-level contract is enough for most consumers; read these when you need the surrounding domain.

• Core subsystem — the Agent handle and AgentOptions route selection.
• agent-loop package — how agents resolve provider and model at request time.
• Generated configuration catalog — every accepted config field and its source declaration.
• Core group map — how the core packages compose.

---

Model Experience

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.

Known Limitations and Deferred Work

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.

Dev Note

Working context for maintainers — click to expand

None.