feat(providers): support common providers from models.dev #860

Problem

Maka hand-maintains provider and model facts across core, runtime, Desktop, CLI, and headless. Adding a provider requires changing parallel lists, which creates inconsistent behavior and makes provider support difficult to verify.

LiteLLM would add a routing dependency without fixing ownership.

Direction

Vendor a versioned models.dev snapshot and update it deterministically during releases or major upstream changes. Do not fetch models.dev at runtime or add models.dev/LiteLLM as runtime dependencies.

Expose one provider registry composed from:

1. models.dev provider and model facts;
2. Maka's shared runtime adapters;
3. minimal provider overrides for authentication, headers, endpoints, discovery, or request differences.

Provider /models responses are authoritative for account-specific availability. The checked-in snapshot is the fallback. Exact model ids must never be rewritten.

Azure, Bedrock, and Vertex remain out of scope because IAM, project, and region configuration require separate product work. LiteLLM remains available through the generic openai-compatible connection, but Maka does not ship a dedicated LiteLLM preset or introduce LiteLLM as a routing layer.

Invariants

Every provider checkbox below represents a complete product slice:

• one stable persisted provider id;
• registry-owned defaults, catalog placement, and runtime/discovery behavior;
• credential configuration across relevant Desktop, CLI, and headless paths;
• account-specific model discovery where supported, with snapshot fallback;
• exact model-id preservation;
• model selection and an agent tool-call run;
• deterministic tests without secrets or raw provider responses;
• a sanitized live smoke before support is marked complete.

Provider-specific behavior belongs only in the registry adapter/override layer.

Contributor guardrails

Before starting a slice, check the latest issue comments and open PRs. Do not duplicate an actively claimed provider; post or update a claim so parallel work can move to an unclaimed checklist item.

Brand assets are a merge gate:

• Use a real, existing provider SVG from an official brand package or a trusted open-source source such as Lobe Icons. If Lobe Icons has no suitable mark, use the provider's official download or another established open-source repository.
• Record the source repository, released package version and/or immutable commit, exact upstream path, license, and full SHA-256. Vendor the SVG byte-for-byte. Never hand-draw, trace, AI-generate, convert a raster image to SVG, or silently rewrite the upstream SVG to make it render.
• Reuse the shared provider-logo path for catalog, detail, and first-run surfaces. Extend the packaged third-party notice inventory and keep a deterministic build check proving the notice survives into the renderer distribution; do not create another notice or header mechanism.
• An external SVG loaded through <img> does not inherit the parent's currentColor. Preserve upstream bytes and use the existing theme-aware CSS mask/currentColor seam for monochrome marks. Verify the computed mask and color in the rendered catalog and detail states; DOM visibility alone is insufficient.

Implementation guardrails:

• “OpenAI-compatible” does not prove identical authentication, discovery, request, or tool-call behavior. Confirm official documentation and exercise a deterministic two-stage loop: provider requests a tool, Maka executes it and returns the tool result, then the provider returns the final assistant response.
• A no-auth provider must omit Authorization; do not inject a dummy API key. Keep exact model IDs unchanged through discovery, persistence, selection, both tool-call turns, and fallback.
• Direct API, Coding Plan, Token Plan, and Agent Plan access paths from the same vendor remain separate persisted provider ids whenever endpoint, key, billing, model allowlist, or permitted use differs. Many subscription plans permit only interactive coding/agent tools; deterministic tests must stay fake, and any live smoke must use Maka interactively with a user-owned key.
• Start each flat PR from the latest main. Give shared files and seams one owner, then rebase dependent slices instead of implementing parallel versions.
• Local Desktop E2E may be deferred to CI; the CI E2E job remains a merge gate. When a local E2E run is needed for diagnosis or visual evidence, use one worker. Treat Electron/fixture startup timeouts as infrastructure only after log evidence and a clean serial rerun; do not change production code to mask a resource flake.

PR sizing

The checklist describes independently verifiable product slices, not mandatory one-PR phases.

Default to one provider or plan variant per PR. A small cohort may share one PR only when every member:

• uses the exact same runtime adapter;
• uses the same authentication and discovery behavior;
• requires no provider-specific override;
• can be tested and reverted as one unit.

Do not split a provider vertically into separate registry, runtime, UI, and test PRs. Each merged PR must leave the provider usable and independently revertible.

The current upper bound is 48 implementation PRs. The final number may be lower when implementation evidence proves that a small regional cohort is genuinely identical.

Delivery order

flowchart LR
  P1["Phase 1<br/>Tracer bullet"] --> P2["Phase 2<br/>Registry foundation"]
  P2 --> P3["Phase 3<br/>Hosted APIs"]
  P2 --> P4["Phase 4<br/>Model plans"]
  P2 --> P5["Phase 5<br/>Local runtimes"]
  P2 --> P6["Phase 6<br/>First run"]
  P2 --> P7["Phase 7<br/>Contract foundation"]
  P3 --> P8["Phase 8<br/>Release closeout"]
  P4 --> P8
  P5 --> P8
  P6 --> P8
  P7 --> P8

Phases 3–6 may proceed in parallel from the merged Phase 2 foundation. Phase 7 may begin once representative access paths exist for API keys, plans, aggregators, local no-auth or optional-auth runtimes, OAuth, regional endpoints, discovery and fallback, reasoning, and tool calls. Phase 7 stays additive: it may add registry- and capability-derived conformance coverage and gap reporting, but it must not remove compatibility paths or claim release completion. Phase 8 starts only after every remaining Phase 3–6 item is delivered or explicitly deferred out of the current acceptance scope.

Delivered

• Phase 1: tracer bullet and SiliconFlow vertical slice: feat(providers): add models.dev registry tracer #863
• Phase 2: generic registry foundation and migration of existing provider ids: feat(providers): centralize provider registry #866

Existing providers retain their persisted ids and observable behavior.

Phase 3: Hosted APIs

Add the remaining direct API providers and OpenRouter.

• xAI: feat(providers): add xAI support #873
• Z.AI / Zhipu direct API: feat(providers): add Xiaomi and Z.AI direct APIs #944
• Alibaba direct API: feat(providers): add Alibaba direct API support #992
• Xiaomi direct API: feat(providers): add Xiaomi and Z.AI direct APIs #944
• Tencent direct API: feat: add Tencent TokenHub direct API support #900
• StepFun direct API (China): feat: add StepFun China direct API support #902
• StepFun direct API (global): stepfun-ai: feat: add StepFun Global direct API support #906
• Mistral: feat: add Mistral hosted API support #889
• Groq: feat(providers): add Groq direct API support #978
• Cerebras: feat(providers): add Cerebras support #888
• Together: feat: add Together AI hosted provider support #890
• Fireworks: feat(providers): add Fireworks AI support #891
• NVIDIA: feat(providers): add NVIDIA hosted API support #899
• Ollama Cloud direct API: feat: add Ollama Cloud provider #937
• Volcengine Ark direct API (China): feat: add Volcengine Ark China direct API #909
• Cohere: feat: add Cohere direct API support #919
• DeepInfra: feat(providers): add DeepInfra direct API support #917
• Hugging Face Inference Providers: feat: add Hugging Face Inference Providers support #935
• Cloudflare Workers AI: feat: add Cloudflare Workers AI support #934
• Vercel AI Gateway: feat: add Vercel AI Gateway support #923
• OpenRouter: feat(providers): add OpenRouter aggregator support #987

Anthropic, OpenAI, Gemini, DeepSeek, Moonshot, MiniMax, and SiliconFlow already have registry/runtime paths. Phase 7 will include them in the final contract and smoke matrix.

Phase 4: Model plans

Kimi Coding Plan and Z.AI Coding Plan already exist and were migrated onto the shared registry path in Phase 2.

Add the remaining plan-specific variants with their own persisted ids, authentication, endpoints, and discovery behavior:

• MiniMax plan: feat(providers): add MiniMax coding plan #872
• Volcengine Ark Coding Plan (China): feat: add Volcengine Ark Coding Plan (China) #912
• Alibaba Coding Plan (China): alibaba-coding-plan-cn: feat(providers): add Alibaba Coding Plan (China + global) #1088
• Alibaba Coding Plan (global): alibaba-coding-plan: feat(providers): add Alibaba Coding Plan (China + global) #1088
• Alibaba Token Plan (China): alibaba-token-plan-cn: feat(providers): add Alibaba Token Plan (China + global) #1089
• Alibaba Token Plan (global): alibaba-token-plan: feat(providers): add Alibaba Token Plan (China + global) #1089
• Tencent Coding Plan: tencent-coding-plan: feat: add Tencent Coding Plan support #904
• Tencent Token Plan: tencent-token-plan: feat: add Tencent Token Plan support #914
• Xiaomi Token Plan (China): xiaomi-token-plan-cn: feat(providers): add Xiaomi Token Plan (China, Singapore, Europe) #1093
• Xiaomi Token Plan (Singapore): xiaomi-token-plan-sgp: feat(providers): add Xiaomi Token Plan (China, Singapore, Europe) #1093
• Xiaomi Token Plan (Europe): xiaomi-token-plan-ams: feat(providers): add Xiaomi Token Plan (China, Singapore, Europe) #1093
• StepFun Step Plan (China): stepfun-step-plan: feat: add StepFun Step Plan China support #916
• StepFun Step Plan (global): stepfun-ai-step-plan: feat: add StepFun Global Step Plan support #927

A direct API provider and its plan variant remain separate product slices even when one person implements both.

Phase 5: Local runtimes

• Validate Ollama against the complete registry contract and make only demonstrated compatibility fixes: fix(headless): support no-auth Ollama contract #874
• Validate exact :cloud model aliases through a signed-in local Ollama daemon without adding another persisted provider id: fix: preserve Ollama Cloud aliases without auth #907
• Add LM Studio, including no-auth configuration and local model discovery: feat: add LM Studio local runtime support #886
• Add LocalAI with its default local endpoint, model discovery, optional authentication, and exact model aliases: feat: add LocalAI local runtime support #915

Phase 6: First run

• Consume the registry-owned recommended provider set and route Browse all providers to the shared Settings catalog: feat(desktop): route first run to provider catalog #875

Do not maintain another onboarding provider list or redesign the connection-management flow.

Candidate watchlist (not part of Phase 3–6 acceptance)

These candidates remain intentionally outside the completion matrix until their lifecycle, public contract, or demand is strong enough:

• Baidu Qianfan Coding/Token Plan personal migration, pending an authoritative current lifecycle contract;
• Volcengine Ark Agent Plan;
• JD Cloud Coding Plan, pending an auditable first-party endpoint contract;
• Baseten, SambaNova Cloud, KUAE Cloud Coding Plan, CTYun Coding Token Plan, SCNet plans, PPIO, Infinigence GenStudio, and team-oriented Token Plans.

Explicit exclusions:

• GitHub Models, which GitHub will fully retire on 2026-07-30;
• Infini Coding Plan, which stopped service on 2026-06-26;
• a dedicated ModelScope preset while it remains a no-SLA experimental inference service;
• dedicated vLLM or arbitrary self-hosted deployment ids, which remain covered by openai-compatible;
• Replicate, whose prediction contract is not Maka's agent chat/tool-call contract;
• Baichuan and SenseNova until a current public two-stage tool-call contract exists.

Phase 7: Contract foundation

Phase 7 may begin before every Phase 3–4 provider is finished. It defines an open-world contract: provider rows may continue to be added, while shared behavior and provider-owned differences remain explicit and testable.

• Generate deterministic conformance coverage from READY_PROVIDER_TYPES, registry metadata, and declared capabilities so future ready providers enter the matrix automatically: feat(core): derive provider conformance matrix from registry declarations #974
• Report missing or inapplicable contract dimensions explicitly without hard-coding a closed provider list: feat(core): derive provider conformance matrix from registry declarations #974
• Keep provider-specific behavior in the adapter/override layer while shared credential, discovery, persistence, and product surfaces remain registry-driven: feat(core): derive provider conformance matrix from registry declarations #974

Do not use Phase 7 to remove compatibility paths, declare the release complete, or start Phase 8 cleanup.

Phase 8: Release closeout

Run Phase 8 only after the remaining Phase 3–6 scope is delivered or explicitly deferred out of the current acceptance matrix:

• Confirm that every remaining in-scope provider is covered by the generated contract matrix: refactor(providers): land the three Phase 8 conformance preconditions #1105, test(runtime): delete hand-written conformance replaced by the generated matrix #1108 (52 ready rows x 4 dimensions: 178 generated / 22 justified N/A / 8 executable overrides, 0 gaps, CI-enforced)
• Remove replaced hand-written provider/model tables and temporary migration paths while retaining persisted-id compatibility: test(runtime): delete hand-written conformance replaced by the generated matrix #1108 (hand-written coverage that remains authoritative for facts the registry cannot express was audited and retained; the codex-subscription persisted-id alias is preserved)

Final release gate:

• Record a sanitized live smoke for every target provider using at least one real model Dropped by maintainer decision (2026-07-16): maintainers do not hold keys or subscriptions for the full target matrix. The CI-enforced deterministic conformance matrix is the standing quality gate; provider-specific wire issues will be fixed on user reports.

Secrets, credentials, raw provider responses, and sensitive account data must never be committed, logged, copied into fixtures, or posted to GitHub.

Acceptance

• One deterministic command updates the checked-in models.dev snapshot (npm run sync:model-metadata)
• Settings, Desktop, CLI, runtime, and headless consume the same registry (feat(providers): centralize provider registry #866)
• No covered provider/model facts remain duplicated in hand-written tables (test(runtime): delete hand-written conformance replaced by the generated matrix #1108; remaining hand-written metadata expresses facts models.dev cannot)
• Every target provider can configure credentials or no-auth access as appropriate
• Provider model discovery is authoritative when available, with snapshot fallback
• Exact model ids survive discovery, persistence, selection, and execution unchanged (matrix exact-model-id dimension, including edge wire samples for composite ids)
• Every target provider completes an agent tool-call run (deterministic two-stage tool loop per matrix row; live smoke dropped per the decision above)
• Advertised reasoning and vision capabilities work where supported (deterministic reasoning-replay dimension; live verification dropped with the smoke gate)
• Provider-specific behavior exists only in the adapter/override layer (feat(core): derive provider conformance matrix from registry declarations #974, refactor(providers): land the three Phase 8 conformance preconditions #1105 executable override bindings)
• Existing persisted provider ids remain compatible
• CI contains deterministic conformance coverage for the target matrix (gap report fails CI on any uncovered ready-provider dimension)
• The sanitized live-smoke gate is complete Dropped by maintainer decision (2026-07-16), see the release-gate note above.