feat(provider): add deepseek provider for the DeepSeek pay-per-use API

[ferminquant]

Summary

Adds a deepseek provider for map, review, and revalidate operations against the DeepSeek pay-per-use chat-completions API. The provider is intentionally read-only: fix fails before provider network or filesystem side effects with unsupported-provider and exit code 2.

Refs #134.

Live proof

Real doctor + review + revalidate runs against the live https://api.deepseek.com/v1 endpoint, captured 2026-06-14 18:40–18:41 UTC using the built CLI from this branch (pnpm build → dist/cli.js, the TypeScript port in src/provider.ts, not a locally-patched install):

• node dist/cli.js doctor --provider deepseek → providerVersion: provider=deepseek default-model=deepseek-v4-flash base=https://api.deepseek.com/v1
• node dist/cli.js review --limit 1 --provider deepseek --model deepseek-v4-flash (against /home/fermin/git/budget) → 31s, 0 findings on feat_library_4580b8205e (clean code path)
• node dist/cli.js revalidate --finding ... --provider deepseek --model deepseek-v4-flash → 4s, outcome open with non-empty provider-generated reasoning (the model examined the cited code and confirmed the bug is still present)

Full redacted transcript in docs/deepseek-live-proof.md. Build: pnpm build succeeds with 0 errors, 853/854 tests pass, oxlint 0 errors, oxfmt --check 0 issues. The branch's own TypeScript code is what makes these calls; the proof artifact is reproducible from a clean checkout.

Integration difference from minimax

DeepSeek's chat-completions API supports response_format: {type: "json_object"} but returns HTTP 400 for response_format: {type: "json_schema", ...} (with strict: true). This provider sends json_object, embeds the schema in the prompt, and relies on clawpatch's existing extractJson helper + Zod validators for shape enforcement. The choice is documented at the request-construction site and pinned by a negative-control test (expect(responseFormat.type).toBe("json_object"); expect(responseFormat.type).not.toBe("json_schema")) that fails if the wrong response_format value is sent.

Maintainer Notes

• Default endpoint: https://api.deepseek.com/v1
• Default model: deepseek-v4-flash
• Required credential: DEEPSEEK_API_KEY (pay-per-use; top up at https://platform.deepseek.com)
• Optional overrides: DEEPSEEK_BASE_URL, DEEPSEEK_MODEL, CLAWPATCH_DEEPSEEK_TIMEOUT_MS, CLAWPATCH_PROVIDER_TIMEOUT_MS
• Request transport uses undici with timeout-sized dispatchers, matching the minimax provider.
• DEEPSEEK_BASE_URL is normalized and rejects URL credentials; non-loopback HTTP is rejected.
• DeepSeek response envelopes are schema-validated locally; the request does not send response_format.json_schema.
• Provider errors are classified into auth (401/403), quota/rate-limit (429/402 pay-per-use balance), malformed output, unsupported operation, and generic provider failures without exposing auth headers or raw response bodies.

Verification

Local checks on the PR branch (matches the minimax PR gate):

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build
pnpm pack:smoke

Expected:

• pnpm test: existing tests + new deepseek tests pass (target: +N new tests in src/provider.test.ts, mirroring the describe("minimax provider", ...) block)
• Negative-control test: a test asserting requestBody.response_format === { type: "json_object" } would fail if the implementation switched to json_schema (and would also fail on main if the schema-mode guard were removed)
• pack:smoke: packaged CLI smoke runs end-to-end against packed artifacts

Live proof is bundled as docs/deepseek-live-proof.md in this branch,
captured by running the built CLI from this branch (node dist/cli.js,
not a locally-patched install) against https://api.deepseek.com/v1 on
2026-06-14 18:40–18:41 UTC. The full redacted transcript is in the proof
artifact. A locally-patched dist/provider.js on the author's machine has
been running against the same endpoint for ~7 days across 100+ features
reviewed in ferminquant/budget, completing in 50–85s/feature with the
failure-mode classification called out in the maintainer notes above
observed in production.

Negative-control test

The most load-bearing claim is response_format: {type: "json_object"} (not json_schema). The test suite pins this with a unit test that constructs a ProviderOptions and asserts the serialized request body shape. If a future change switched to json_schema, the test would fail with a clear diff. The same test would also fail on main if the schema-mode guard were removed, proving the assertion is load-bearing.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 14, 2026, 6:51 PM ET / 22:51 UTC.

Summary
The PR adds a DeepSeek HTTP provider for map, review, revalidate, and doctor, plus provider docs, tests, README/spec entries, and a redacted live proof transcript.

Reproducibility: not applicable. this is a new provider feature PR, not a broken existing behavior report. Current main lacks a deepseek provider, and the branch adds one.

Review metrics: 3 noteworthy metrics.

• Changed files: 6 files, +1086/-1. The PR spans runtime provider code, tests, docs, README/spec entries, and a proof artifact.
• Provider tests added: 358 lines added. The mocked test surface is substantial and covers the new provider's auth, request, parsing, timeout, and failure paths.
• Live proof coverage: 3 operations. The transcript exercises doctor, review, and revalidate through the branch-built CLI against the live API.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• Get explicit maintainer acceptance for adding DeepSeek as a first-party provider.

Risk before merge

• [P2] Merging creates a new first-party remote provider with its own API key, endpoint override, default model, timeout knobs, billing behavior, and support expectations before explicit maintainer product approval.
• [P1] The provider sends review inputs to a configured remote API endpoint; the PR documents this and validates the base URL, but maintainers still need to accept that core provider surface.

Maintainer options:

1. Approve the provider surface before merge (recommended)
   Maintainers can explicitly accept DeepSeek as a first-party provider with its own API key, endpoint override, model default, billing behavior, and timeout knobs before landing this PR.
2. Pause behind the feature request
   Leave this PR open but unmerged until the linked DeepSeek provider request receives a maintainer product decision.

Next step before merge

• [P2] The remaining action is maintainer product approval for first-party DeepSeek support, not an automated code repair.

Security
Cleared: No concrete security or supply-chain regression was found; the new remote provider validates base URLs, rejects URL credentials, bounds reads, and redacts provider error bodies.

Review details

Best possible solution:

Land the MiniMax-style DeepSeek provider only if maintainers explicitly approve DeepSeek as a core provider; otherwise keep the linked feature request as the product decision point.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a new provider feature PR, not a broken existing behavior report. Current main lacks a deepseek provider, and the branch adds one.

Is this the best way to solve the issue?

Unclear: the implementation is narrow and follows the existing MiniMax HTTP-provider pattern, but the best solution still depends on maintainer approval that DeepSeek belongs as a first-party provider.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8a939cc6f85e.

Label changes

Label justifications:

• P2: This is a normal-priority provider feature with bounded but meaningful auth/provider surface impact.
• merge-risk: 🚨 auth-provider: The PR introduces a new API-key-backed provider route with endpoint, model, timeout, bearer-token, and billing behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR includes redacted terminal proof from the branch-built CLI for doctor, review, and revalidate against the live DeepSeek endpoint.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR includes redacted terminal proof from the branch-built CLI for doctor, review, and revalidate against the live DeepSeek endpoint.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was present and read fully; its provider testing and secret-handling guidance applies to this remote-provider PR. (AGENTS.md:1, 8a939cc6f85e)
• Current main lacks DeepSeek provider: Current main's provider registry includes minimax and other providers but has no deepseek branch, so the PR is not already implemented on main. (src/provider.ts:269, 8a939cc6f85e)
• PR adds provider route and implementation: The PR head registers providerByName("deepseek") and adds the DeepSeek constants, URL validation, timeout/dispatcher handling, request construction, auth, response parsing, check/map/review/revalidate, and unsupported fix contract. (src/provider.ts:285, a9f6dd058777)
• DeepSeek request and safety shape: The provider validates HTTPS/loopback base URLs, rejects URL credentials, sends response_format json_object, bounds request/response sizes, redacts provider error messages, and returns unsupported-provider for fix before network calls. (src/provider.ts:1123, a9f6dd058777)
• Focused provider tests: The PR adds DeepSeek tests for dispatch, timeouts, URL validation, model override, json_object request shape, bearer auth, error classification/redaction, timeout during body reads, /models validation, unsupported fix, status mapping, JSON extraction, and response bounds. (src/provider.test.ts:2424, a9f6dd058777)
• Live behavior proof: The proof transcript shows branch-built dist/cli.js running doctor, review, and revalidate against the live DeepSeek endpoint with the API key redacted. (docs/deepseek-live-proof.md:43, a9f6dd058777)

Likely related people:

• ferminquant: GitHub commit history shows ferminquant authored the landed MiniMax provider that this DeepSeek provider closely mirrors, beyond being this PR's proposer. (role: prior adjacent HTTP-provider contributor; confidence: high; commits: 7252f7300f34; files: src/provider.ts, src/provider.test.ts, docs/providers.md)
• steipete: Local blame on the current provider registry points to the v0.6.0 release snapshot, and GitHub history shows recent provider/auth changes in the same area. (role: recent provider/auth contributor and release snapshot author; confidence: high; commits: 17944c1e97b1, a71cd414c191, 3482dacc12e6; files: src/provider.ts, src/provider.test.ts, docs/providers.md)
• aurokin: GitHub history shows adjacent Claude and Cursor provider additions and hardening in the same provider registry, tests, and docs surface. (role: provider registry contributor; confidence: medium; commits: 755186db3c63, 7cb059a6bc66, 5709e9ae063e; files: src/provider.ts, src/provider.test.ts, docs/providers.md)
• camwest: GitHub history shows recent provider timeout changes adjacent to this PR's custom timeout and undici dispatcher behavior. (role: adjacent timeout contributor; confidence: medium; commits: c8a8d44d5c04, d4ff0dbc568f; files: src/provider.ts, src/provider.test.ts, docs/providers.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[ferminquant]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Superseded
• Detail: A newer re-review for this item started before this run finished, so GitHub cancelled this older run. Check the latest ClawSweeper run for the current result.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27508108312
• Updated: 2026-06-14T18:34:23.408Z

[ferminquant]

@clawsweeper re-review

[steipete]

clawpatch should only work with coding harnesses, I do not want to start integrating API directly. use openclaw, pi or whatever to access deepseek.

[steipete]

Thanks for the thorough implementation and runtime proof. We have narrowed Clawpatch's provider boundary to coding harnesses and agent CLIs, so direct model API providers are out of scope.

The policy and removal are documented in VISION.md and landed through #137.