Registry-Based Integration Architecture for Providers, Gateways, and Models

[jatmn]

Registry-Based Integration Architecture for Providers, Gateways, and Models

Closes #893

Summary

This PR implements the registry/descriptor integration architecture proposed in #893.

It changes OpenClaude from a mostly flat, overloaded "provider" model into a descriptor-backed system that separates:

• vendors/providers, such as OpenAI, Anthropic, Google, Moonshot, DeepSeek, and Z.AI
• gateways/runtimes, such as OpenRouter, Ollama, LM Studio, LiteLLM, Groq, Together, Bedrock, Vertex, and GitHub
• model families and model metadata, such as Claude, GPT, Kimi, DeepSeek, Llama, and Qwen
• Anthropic-compatible proxy routes, as a distinct future-facing integration type

The main intent is to make integration work additive, reviewable, and less conflict-prone. New vendor, gateway, and model work should now be routed through descriptors and the related documentation rather than through scattered provider switches.

Project Codename

Project codename: cheeky-cooking-moon

That name came from Kilo Code's generated project/plan name. It was weirdly memorable, so it stuck. The codename does not affect runtime behavior; it is just the planning label for this integration-architecture migration.

Executive Summary Excerpt

From plan/cheeky-cooking-moon.md:

OpenClaude currently overloads the word "provider" across several different concerns: vendor, gateway, model family, and Anthropic proxy.

That overload leaks into the codebase as duplicated switches, partially overlapping type systems, and routing behavior that is hard to extend safely.

This plan introduces a descriptor registry under src/integrations/ so that integration metadata lives in one place; runtime routing can remain transport-specific; /provider, --provider, model lookup, validation, discovery, and /usage read from the same source of truth; existing user config remains backward compatible; and future integrations can be added with additive descriptor files instead of scattered switch edits.

At a high level, this PR establishes:

• a descriptor model for vendors, gateways, models, brands, catalogs, runtime metadata, usage metadata, and future Anthropic proxy support
• registry-backed metadata and compatibility surfaces for legacy provider/profile behavior
• descriptor-backed provider flags, provider discovery, provider validation, route metadata, runtime request shaping, and model catalog resolution
• generated integration artifacts so contributor-authored descriptors stay additive while loader/UI/preset metadata remains synchronized
• documentation under /docs explaining how future contributors should add integrations in the new architecture

!!! VERY IMPORTANT INTEGRATION WARNING !!!

!!! WARNING !!!

This PR changes the core framework for how vendors, gateways, and models are added to OpenClaude.

Do not add new integrations by copying the old pattern of editing provider switch statements across many shared files.

For new integration work, read the descriptor-era documentation under /docs first, especially:

• docs/architecture/integrations.md
• docs/integrations/overview.md
• docs/integrations/glossary.md
• docs/integrations/how-to/add-vendor.md
• docs/integrations/how-to/add-gateway.md
• docs/integrations/how-to/add-model.md
• docs/integrations/how-to/add-anthropic-proxy.md
• docs/integrations/how-to/add-usage-support.md
• docs/integrations/reference-samples.md
• docs/integrations/common-pitfalls.md

In the descriptor-era flow, adding a normal gateway should usually mean:

1. Add src/integrations/gateways/<id>.ts.
2. Add src/integrations/gateways/<id>.models.ts only when the catalog/discovery logic is large enough to deserve a companion file.
3. Add descriptor preset metadata only if the gateway should appear in preset-driven /provider flows.
4. Run bun run integrations:generate.
5. Add or update focused tests.

New gateways should not normally require hand-editing:

• src/integrations/index.ts
• src/integrations/compatibility.ts
• src/integrations/providerUiMetadata.ts
• provider flag tables
• provider profile tables
• /provider UI switch logic
• /model switch logic
• /usage switch logic
• OpenAI shim base-url conditionals

If a new gateway appears to require broad switch edits, please stop and check the docs before continuing. That is almost certainly a sign that the new descriptor path should be used instead.

What Changed

• Added the descriptor/registry architecture under src/integrations/.
• Added descriptor helpers so integration files can use defineVendor, defineGateway, defineModel, defineCatalog, and related helpers instead of directly mutating registry state.
• Added generated integration artifacts and scripts so descriptor-authored metadata can feed loader, preset, and UI compatibility surfaces.
• Moved provider flags, provider/profile compatibility, route metadata, provider discovery, provider validation, model metadata, and runtime request-shaping paths toward descriptor-backed data.
• Added discovery/cache support for descriptor-backed model catalogs, including static, dynamic, and hybrid catalog patterns.
• Preserved backward compatibility for existing provider profile and preset behavior while introducing the clearer vendor/gateway/model vocabulary.
• Added docs for the new integration workflow and common pitfalls.

Backward Compatibility

This PR is intended to preserve existing user-facing behavior while changing the internal integration model.

Important compatibility goals:

• existing saved provider profiles should continue to load
• existing --provider values should continue to work
• existing provider defaults and environment variable behavior should remain stable
• current OpenAI-compatible routing should continue through the OpenAI shim
• native Anthropic-style routes should remain native rather than being collapsed into OpenAI-compatible behavior
• /usage should either resolve supported descriptor-backed usage behavior or show a clear unsupported-provider fallback

Documentation

The new docs are part of the migration, not optional follow-up polish.

Start here:

• docs/architecture/integrations.md
• docs/integrations/overview.md
• docs/integrations/glossary.md

Then use the specific how-to guide for the integration type:

• vendors: docs/integrations/how-to/add-vendor.md
• gateways: docs/integrations/how-to/add-gateway.md
• models: docs/integrations/how-to/add-model.md
• Anthropic proxies: docs/integrations/how-to/add-anthropic-proxy.md
• usage support: docs/integrations/how-to/add-usage-support.md

Reference examples and pre-PR review guidance:

• docs/integrations/reference-samples.md
• docs/integrations/common-pitfalls.md

Testing

Smoke/release checks run locally:

bun install
bun run build
bun run smoke

Observed smoke output:

0.6.0 (OpenClaude)

Build output confirmed:

Built openclaude v0.6.0 -> dist/cli.mjs

Reviewer Notes

This is a core architecture change. Please review with special attention to:

• whether every current provider route still maps cleanly through descriptors or compatibility metadata
• whether descriptor-backed route metadata preserves existing auth, base URL, model default, and startup behavior
• whether gateway/direct-vendor catalogs avoid implying support for every shared model descriptor
• whether github, bedrock, vertex, and other special routes still preserve their runtime expectations
• whether OpenAI-compatible shim behavior remains transport-specific and does not regress reasoning/thinking edge cases
• whether new docs make the future integration path obvious enough for contributors

Follow-Up Scope

This PR establishes the descriptor-era architecture and migration path. It does not need to solve every future UX refresh.

Reasonable follow-ups include:

• revisiting /provider onboarding UX once descriptor metadata has stabilized
• revisiting /model presentation and filtering once model metadata is richer
• refreshing /usage presentation around descriptor-backed usage metadata
• considering a future settings.json shape that more directly reflects vendor/gateway/model distinctions

[devNull-bootloader]

Those were currently restricted in prior reviews. I dont think they should be blockers, but I think it would be good for fast follow pr to adjust those more robustly.

Got it, thanks for the clarification. I'll track these credential-mapping gaps as a fast-follow PR to add proper host-based routing for Moonshot (.cn), DeepSeek variants, and Azure custom resource URLs, which we can plan later. That shouldn't block this one.

[Vasanthdev2004]

Targeted re-review of current head f5c3bac.

Verdict: Needs changes, but the previous registry test-order blocker is fixed.

What I rechecked:

• The exact order-isolation failure I previously called out:

bun test --max-concurrency=1 ./src/integrations/registry.test.ts ./src/integrations/index.test.ts ./src/integrations/compatibility.test.ts

Result on current head: 35 pass / 0 fail.

So from my side, the shared-registry test isolation issue is resolved.

Remaining blocker:

• GitHub still reports this PR as conflicted / not mergeable (DIRTY). Please rebase or merge latest main and resolve conflicts before we treat it as merge-ready.

Given the size of this PR, I still want us to keep the review scope honest: this comment only clears my earlier registry-order blocker. It is not a fresh full review of the whole architecture diff after conflict resolution.

[kevincodex1]

hello bro @jatmn please fix failing tests. we target to merge this before the week ends. will release new version probably on Monday

[jatmn]

@kevincodex1, please review.

[kevincodex1]

sorry bro I just merged something. please rebase and fix conflict again.

[kevincodex1]

Solid foundational refactor with clear architectural intent and strong contributor docs. Not yet a clean approve — there are six concrete items I'd ask for before merging, plus a hygiene ask about the diff itself.

---

Scope check

• 72 commits, 169 files, +18,464 / −2,875 against merge-base
• 71 new files under src/integrations/ (descriptors + registry + generator)
• ~3,094 lines of new contributor docs (welcome — and necessary for this kind of system)
• Branch is current with main (just merged); only one deletion (src/utils/zaiProvider.ts, cleanly absorbed into descriptors)

Architecture: what's good

• Descriptor types in src/integrations/descriptors.ts are clean. Vendors / gateways / anthropic-proxies / brands / models all narrow into defineX() helpers.
• scripts/generate-integrations-artifacts.ts produces a typed barrel (generated/integrationArtifacts.generated.ts) — and there's a --check mode plus a real-tree test (artifactGenerator.test.ts:46-48) that
  fails if descriptors drift from the generated file. CI runs bun test, so drift is caught. ✅
• withDiscoveryCacheLock (discoveryCache.ts:34) is correct under JS single-threaded semantics — synchronous body before the first await is atomic.
• The compatibility layer (compatibility.ts, profileResolver.ts) preserves legacy preset names.

Concerns

1. Behavior changes in getAPIProvider() priority order aren't all flagged

Refactor at src/utils/model/providers.ts swaps a hardcoded if-chain for resolveActiveRouteIdFromEnv(). Several priority orders shifted:

• NVIDIA_NIM: was top priority, now only checked in the openai/custom and anthropic/default branches. NVIDIA_NIM=1 + CLAUDE_CODE_USE_GEMINI=1 used to return 'nvidia-nim'; now returns 'gemini'.
• CLAUDE_CODE_USE_FOUNDRY: was last priority, now extracted before resolveActiveRouteIdFromEnv — effectively highest.
• MINIMAX_API_KEY: was checked before the OPENAI flag (presence check); now resolves through resolveEnvOnlyProviderRouteId which only fires when no CLAUDE_CODE_USE_* flag is set.

Some of these may be intentional cleanups — I suspect they are — but they should be called out in the PR description and have explicit precedence-conflict tests added (current providers.test.ts doesn't
cross-test NVIDIA_NIM with the other USE flags).

2. Hardcoded fallback list in openaiShim.ts:1597-1600 is dead code

const shouldStripResponsesStore =
(shimConfig.removeBodyFields ?? []).includes('store') ||
['mistral', 'gemini', 'moonshot', 'deepseek', 'zai', 'kimi-code'].includes(
runtimeShimContext.routeId ?? '',
) || ...

I checked: every one of those six routes already declares removeBodyFields: ['store'] in its descriptor, so the hardcoded array is unreachable. Either delete it (preferred — point of the descriptor system) or
comment why it's there. Worth a sweep for similar leftovers.

3. profileResolver.ts:38 hardcodes vendorId: 'openai' for any gateway

const gateway = getGateway(provider)
if (gateway) {
return { vendorId: 'openai', gatewayId: gateway.id, routeId: gateway.id }
}

That's wrong for native-protocol gateways (bedrock, vertex). Today consumers only read routeId from this, so it's not a live bug — but it's a latent footgun the next contributor will trip over. Either look up
the real vendor from the gateway descriptor, or make vendorId optional in ResolvedProfileRoute.

4. CI has to run bun test --max-concurrency=1 permanently

The branch contains 12+ "test isolation" commits (test: harden fast mode test isolation, test: prevent discovery privacy mock bleed, test: pin conversation recovery provider mock, etc.). The fix is per-file
afterAll(_clearRegistryForTesting; ensureIntegrationsLoaded). That works, but the contract is invisible — the next test author who touches the registry has no way to know they need this dance.

Suggestion: a global setupTests.ts that resets all relevant state (registry, env, discovery cache) between files, or at minimum a comment block in src/integrations/index.ts documenting the contract.

5. vendors/anthropic.ts:6-7 evaluates process.env at module load

defaultBaseUrl: process.env.ANTHROPIC_BASE_URL ?? 'https://api.anthropic.com',
defaultModel: process.env.ANTHROPIC_MODEL ?? 'claude-sonnet-4-6',

Frozen at import time. Anything that mutates ANTHROPIC_BASE_URL later (profile env application, tests) won't be reflected in the descriptor. The getProviderPresetUiMetadata path does honor live env via
preset.baseUrlEnvVars, so most callers are fine — but direct readers of descriptor.defaultBaseUrl get a stale value. Either drop the env fallback from the descriptor (let the preset metadata be the only env
source) or add a comment.

6. ModelPicker.tsx is a 788-line full rewrite that converts compiled output → source

main:src/components/ModelPicker.tsx starts with import { c as _c } from "react-compiler-runtime" (React Compiler output). The PR replaces it with hand-written source. The convention in this repo is mixed (some
.tsx are compiled, some are source), so this isn't necessarily wrong — but the diff is effectively unreviewable at the line level. It hides regressions inside the bigger refactor.

Strong suggestion: split this file's conversion into its own PR with a clear "no behavior change, source-form rewrite" commit, OR keep it as compiled output and edit minimally for this PR. Mixing it into a
169-file architectural change makes the intent ambiguous.

7. Minor: 'unknown-fallback' string sentinel

Sprinkled across routeMetadata.ts:473, providerProfiles.ts:529, providerProfiles.ts:1020. A discriminated union ({ kind: 'resolved' | 'unknown', ... }) or null return would be more type-safe than a magic
string. Cosmetic.

Diff hygiene

72 commits including planning docs, multiple "fix test isolation" attempts, and several "Merge upstream main" commits. Whatever merge strategy you use, please don't fast-forward — the history will be hard to
bisect later. Squash-merge with the PR description as the message, OR an interactive rebase preserving the Phase 1/2/3/4 boundaries.

Verdict

Request changes (gentle). The architecture is the right direction and the descriptors are well-designed. Items 1, 2, 3, and 6 are concrete cleanups; 4 and 5 are documentation/lint asks; 7 is cosmetic. None of
these are deep — most are an afternoon of work.

Please address all of this:

• delete the dead hardcoded list in openaiShim
• fix vendorId in profileResolver
• add a precedence test or two for the new getAPIProvider
• either split the ModelPicker.tsx conversion or revert it

Then this is ready.

[jatmn]

Thanks for the careful review. This was very helpful, especially given the size of the descriptor refactor and how much surface area it touches.

I have gone through the reported items and addressed the merge-blocking pieces:

• Removed the dead hardcoded route fallback list from openaiShim. Store stripping now stays descriptor-driven through removeBodyFields.
• Fixed profileResolver so gateway routes use the descriptor's real vendorId, which covers native gateways like Bedrock and Vertex correctly.
• Added explicit getAPIProvider() precedence coverage, including the intentional behavior that explicit provider flags like Gemini/OpenAI take precedence over env-only MiniMax inference.
• Removed import-time process.env reads from the Anthropic vendor descriptor so descriptor defaults remain static and live env handling stays in preset metadata.
• Reworked the ModelPicker.tsx situation so it is no longer a large source-form rewrite mixed into this architectural PR. The current diff is limited to compiled-output style changes.
• Added a regression check to keep the removed openaiShim fallback list from coming back.

I also ran the documented validation:

bun run build
bun run smoke

Both passed. Smoke output confirmed:

0.7.0 (OpenClaude)

A quick note on drift: since this PR was first opened, several other PRs have landed and the branch has had to absorb a fair amount of movement from main. I expect we will want to revisit a few PRs from the last several days after this framework lands, because some provider/runtime assumptions may no longer line up cleanly with the new descriptor-backed system.We will want to keep that follow-up focused and patch anything that no longer works against the new framework, rather than trying to fold more unrelated cleanup into this PR.

[gnanam1990]

Re-reviewed at 1b743d6. Both blockers from my last pass are resolved.

Verified locally (cheeky-cooking-moon @ 1b743d6)

bun test --max-concurrency=1
→ 1921 pass, 0 fail across 201 files [8.31s]

The exact CI command now passes deterministically locally, where it previously failed with the registry-ordering issue.

What's resolved

• ✅ src/integrations/registry.test.ts now has an afterAll that re-calls ensureIntegrationsLoaded() (17e6530) — restores the registry after the unit-test clears, so subsequent test files see a populated registry regardless of file-discovery order.
• ✅ Provider-specific model routing fix (011d541) + the precedence regression test (1b743d6) cover the routing test failures cleanly.
• ✅ plans/ directory removed (a6c4805, f5c3bac).
• ✅ Main merged in cleanly twice; no fingerprint regressions on current head.

No openclaude red flags

• No tengu_*, no USER_TYPE === 'ant', no new outbound network calls in 3P paths, no Anthropic fingerprints, no telemetry deps. Registry-based architecture is exactly the kind of refactor that makes the third-party path more maintainable.

This is a sizable change (18k+/2.5k-) but the test coverage is solid and the architecture splits cleanly along provider/gateway/model boundaries. LGTM 🚀

[Vasanthdev2004]

Targeted final re-review of current head 1b743d6 before squash merge.

Verdict: Approve-ready

What I checked:

• The previous registry test-order blocker remains fixed. The deterministic order command now passes cleanly.
• Kevin's requested cleanup items are addressed: descriptor-driven store stripping no longer has the dead route-name fallback list, gateway profile resolution now uses the descriptor vendor, provider precedence tests exist, and the Anthropic descriptor no longer depends on import-time env defaults.
• Focused provider/auth/routing surfaces still keep provider-specific credentials scoped to their resolved routes.
• CI is green on GitHub, and Gnanam's full bun test --max-concurrency=1 re-review also passed on this same head.

Verification run locally:

• bun test --max-concurrency=1 ./src/integrations/registry.test.ts ./src/integrations/index.test.ts ./src/integrations/compatibility.test.ts passed 36/36
• bun test src/utils/model/providers.test.ts src/services/api/openaiShim.test.ts src/utils/providerProfiles.test.ts passed 170/170
• bun run build passed

Given the size/history of this PR, I still strongly recommend squash merge so main receives one clean architecture commit while the PR keeps the detailed discussion and review history.

[kevincodex1]

I've done another review on this and its looking great, I would just like if possible we remove the plan folder. I think its not needed anymore?