Skip to content

docs: describe the DeepSeek pairing as a compatibility pairing, not DeepSeek's first-party harness - #695

Merged
aviggiano merged 3 commits into
release/v0.1.0from
fix/issue-660-deepseek-terminology
Aug 20, 2026
Merged

aviggiano merged 3 commits into
release/v0.1.0from
fix/issue-660-deepseek-terminology

Conversation

@aviggiano

@aviggiano aviggiano commented Aug 20, 2026 •

Copy link
Copy Markdown
Collaborator

Closes #660.

What this changes

The shipped tree asserted, in its most visible surfaces, that Claude Code is DeepSeek's official / supported coding-agent integration. It is not. What ultrafuzz ships is the Claude Code harness pointed at DeepSeek's Anthropic-compatible endpoint — a compatibility pairing. DeepSeek's first-party harness is DeepSeek Harness (dsh), as recorded in docs/explanation/provider-harness-research.md (see Recommended Pairing Policy, rules 1 and 3). Fixing the wording now keeps this claim from colliding with the real dsh binding in #661.

File Change
ultrafuzz.toml [models.deepseek] profile comment and the [agents.DeepSeekAgent] comment reworded; both instances of "official" dropped.
packages/runtime/src/templates/smithers/agents/deepseek.tsx createDeepSeekAgent doc comment reworded. Only the false first sentence changed; the accurate half about keeping credentials, model selection, telemetry semantics and pricing provenance off Anthropic defaults is kept verbatim.
docs/config.md New paragraph in the DeepSeek section stating the pairing is a compatibility pairing, that it is opt-in and non-default, and how it is actually selected.
docs/config.md "OpenRouter through Codex" now names itself a compatibility pairing and separates the two senses of "default".
CHANGELOG.md The v0.1.0 DeepSeek entry said "DeepSeek's official Claude Code endpoint"; reworded to "Anthropic-compatible", matching the correction this PR makes everywhere else.
packages/runtime/src/init.ts The pre-reword deepseek.tsx digest is registered as a stock hash, so ultrafuzz init upgrades an untouched generated adapter instead of treating it as customized.

Second pass: two false claims removed

The first pass added a ### Providers and harnesses are separate choices section to docs/config.md, with a five-row provider/harness/ref table. Both of its load-bearing claims were false, so the section is deleted.

  1. "The two are not welded together" is false for three of the four shipped refs. deepseek.tsx hardcodes DEEPSEEK_ANTHROPIC_BASE_URL = "https://api.deepseek.com/anthropic" and injects it; claude.tsx contains no base_url/baseUrl at all, so ClaudeAgent cannot be repointed; kimi.tsx is wired to Kimi Code. Only CodexAgent can be repointed, and only through a hand-authored Codex-native config.toml that ultrafuzz neither owns nor validates. Documenting a separate provider/harness boundary as shipped fact is the prose form of the parallel surface PR feat(config): add provider harness binding validation #682 was closed for — and it is Document the provider/harness pairing policy and migration paths #664 scope, which is closed.
  2. The selection rule — "Every other row has to be selected per node or group, or for a single run with --agent <Ref>" — is false for the OpenRouter row the same table introduces. The root config contains only [models.default|claude|kimi|deepseek] and [agents.CodexAgent|ClaudeAgent|KimiAgent|DeepSeekAgent]. There is no openrouter profile, no distinct ref, no OPENROUTER_API_KEY; that row is reached by editing [models.default] plus [agents.CodexAgent], not by selecting anything.

Two more corrections in the same pass:

  • The DeepSeek section said --agent DeepSeekAgent "selects this one". It does not. This page already states (Claude agent section) that --agent and --model override fields of the default profile rather than selecting a profile by id, and runtime.test.ts:5163 asserts that an --agent override carries neither the previous profile's model nor its reasoning. Selection is model_profiles = ["deepseek"] in .ultrafuzz/topology.yml; --agent DeepSeekAgent carries neither deepseek-v4-pro nor reasoning = "max".
  • "It is opt-in, not the default selection" on the OpenRouter section collapsed two different senses of "default". Now stated separately: the pairing is not selected by default, and once OpenRouter is the provider, Codex CLI is the harness this release ships for it.

Acceptance criteria

  • No shipped comment, config file, or doc page calls Claude Code DeepSeek's official/supported/first-party coding-agent integration. Verified by grep across docs/, *.md, packages/**/src, and ultrafuzz.toml. Two remaining "first-party" hits — docs/config.md "pinned to the first-party deepseek catalog entry" and docs/reference/artifacts-reports.md:481 — are about the pricing catalog entry, not the harness, and are accurate as written.
  • The pairing is described as a compatibility pairing wherever it is introduced (root TOML, adapter template, docs/config.md).
  • docs/config.md states which pairing is the default and how the opt-in ones are actually selected, in the section that documents each one.
  • No config schema, no new key on any table, no rename, no argv or routing change.

One behaviour change, deliberate

AGENT_TEMPLATES[deepseek].stockSha256 gains the pre-reword template digest (65bf43f3…). An earlier revision of this PR listed not doing this as a feature; that was wrong. Without the entry, every project already initialized keeps the false comment in its generated .smithers/agents/deepseek.ts until someone runs init --force, which defeats the point of the change. The stock-hash set exists for exactly this: claude, codex, and kimi each already carry several historical digests, and a digest match means the file is provably untouched, so nothing a user wrote is at risk. A customized adapter still does not match and is still preserved.

Explicitly not done

Tight-adapter ruling compliance

  • No new adapter file. No adapter was added; deepseek.tsx changed by one block comment, 0 executable lines.
  • No new config keys. No [providers.*] or [harnesses.*] table, no new field on any existing table. ultrafuzz.toml gains zero keys — the diff there is comment text only.
  • Nothing reimplemented from Smithers. No argv construction, prompt assembly, output interpretation, usage accounting, session/resume handling, error classification, credential storage, provider routing, or model-catalogue knowledge was touched or duplicated.
  • No fs, network, or env surface change. workflowControlChildEnvironment and workflowControlCredentialValue call sites are untouched.

Verification

  • pnpm -w format:check — pass.
  • pnpm -w lint — pass.
  • pnpm -w docs:check (audit-profile-docs.mjs --check + docs-check.mjs) — pass, exit 0.
  • packages/runtime node:test suite (node scripts/run-tests.mjs) — 658 tests, 640 pass, 0 fail, 18 skipped, exit 0, run against the tree at 47ee058f (which is the tree at HEAD apart from a CHANGELOG rewrap).

aviggiano and others added 3 commits August 20, 2026 12:54
The shipped tree asserted that Claude Code is DeepSeek's official/supported
coding-agent integration. It is not: ultrafuzz points the Claude Code harness
at DeepSeek's Anthropic-compatible endpoint, which is a compatibility pairing.
DeepSeek's first-party harness is DeepSeek Harness (dsh), as recorded in
docs/explanation/provider-harness-research.md. Correcting the wording before a
real dsh binding exists (#661) keeps the two from sharing a name or a claim.

- ultrafuzz.toml: reword the [models.deepseek] profile comment and the
  [agents.DeepSeekAgent] comment.
- packages/runtime/src/templates/smithers/agents/deepseek.tsx: reword the
  createDeepSeekAgent doc comment; the accurate half about credential, model,
  telemetry and pricing isolation is kept verbatim.
- docs/config.md: add the compatibility-pairing/opt-in paragraph to the
  DeepSeek section, and fold in the residual editorial half of #664 - a new
  "Providers and harnesses are separate choices" subsection that states
  default-selection status explicitly instead of by omission, and a note on
  the OpenRouter-through-Codex section marking it opt-in and non-default.

Comments and prose only. No code, schema, or runtime behaviour changes, no
config keys added, and no rename of the DeepSeekAgent ref or export.

Closes #660

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The #660 doc pass added a "Providers and harnesses are separate choices"
section whose central claim was false for three of the four shipped refs.
deepseek.tsx hardcodes DEEPSEEK_ANTHROPIC_BASE_URL and injects it, claude.tsx
contains no base_url/baseUrl at all so ClaudeAgent cannot be repointed, and
kimi.tsx is wired to Kimi Code. Only CodexAgent can be repointed, and only
through a hand-authored Codex-native config.toml that ultrafuzz neither owns
nor validates. The section's selection rule was false for its own OpenRouter
row too: the root config has no openrouter profile, no distinct ref and no
OPENROUTER_API_KEY, so that row can be reached by neither model_profiles nor
--agent. Documenting a separate provider/harness boundary as shipped fact is
the prose form of the parallel surface PR #682 was closed for, and it is #664
scope in any case. Removed.

- docs/config.md: delete the section and its five-row table.
- docs/config.md: correct the DeepSeek selection sentence. --agent does not
  select a profile - the same page already says so - so selection is
  model_profiles = ["deepseek"] in .ultrafuzz/topology.yml, and
  --agent DeepSeekAgent overrides only the default profile's agent, carrying
  neither deepseek-v4-pro nor reasoning = "max" (runtime.test.ts:5163).
- docs/config.md: split the two senses collapsed into "opt-in, not the default
  selection" on the OpenRouter section - the pairing is not selected by
  default, and separately Codex CLI is the harness this release ships once
  OpenRouter is the provider.
- CHANGELOG.md: "official Claude Code endpoint" -> "Anthropic-compatible
  Claude Code endpoint", matching the correction this PR makes everywhere else.
- packages/runtime/src/init.ts: register the pre-reword DeepSeek adapter hash
  as stock, so a project initialized before this PR still upgrades instead of
  being treated as customized.

Prose plus one stock-hash entry. No schema, no config keys, no renames.

Refs #660

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Keeps the amended entry inside the wrap width the surrounding v0.0.5 bullet
already uses. No wording change.

Refs #660

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@aviggiano
aviggiano merged commit a7d0abc into release/v0.1.0 Aug 20, 2026
6 checks passed
@aviggiano
aviggiano deleted the fix/issue-660-deepseek-terminology branch August 20, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants