Model identity vs execution ID: what is the smartest long-term compatibility architecture?

[RaviTharuma]

@code-yeongyu I wanted to ask for your architectural take on the cleanest long-term direction here.

Context:

• #2829 moved model capability handling toward runtime metadata + models.dev instead of broad hardcoded family logic.
• #2834 adds guardrails because the remaining alias layer can silently drift over time.
• While hardening that path, one important tension became clearer:
  • broad alias magic is dangerous because it can start rewriting real canonical models.dev model IDs
  • but a strict canonical-only world can break real user setups that go through Antigravity, CLIProxyAPI / Quotio, GitHub Copilot, and other provider/proxy-specific model names

My current view is that the smartest long-term shape is probably not “canonical IDs everywhere, full stop”. I think it is closer to this:

Proposed direction

1. Keep the execution model ID

This is the exact provider-facing string that must be sent to the upstream/provider/proxy.
Examples:

• google/antigravity-claude-opus-4-5-thinking
• claude-opus-4-6-thinking
• some Copilot/CLIProxyAPI-specific runtime model name

This preserves compatibility with all the weird real-world setups users actually have.

2. Add a separate canonical capability ID

This is the internal capability lookup key used for:

• models.dev
• capability compatibility logic
• guardrails / CI
• fallbacks and reasoning about model families

Examples:

• claude-opus-4-6
• gemini-3.1-pro-preview
• kimi-k2.5

3. Normalize only at the edge

If a user/provider/proxy gives us a decorated or legacy model name, we should normalize it to a canonical capability ID for internal reasoning, without necessarily changing the execution model ID.

That means a structure more like:

• requestedModelID
• executionModelID
• canonicalModelID
• plus structured settings like variant, thinking, reasoningEffort

4. Treat aliases as compatibility-only

Aliases should stay small, explicit, and tested.
Not a general strategy.
Just a bridge for:

• historical OmO names
• provider-specific compatibility names
• temporary migration cases

5. Keep canonical IDs as the rule for built-in defaults

For shipped OmO defaults / requirements, my bias is still:

• internal built-in model requirements should be canonical where possible
• provider/proxy-specific execution strings should mostly stay at the edges or in user config/runtime resolution

Why I think this is the elegant middle ground

It seems to preserve both goals:

• correctness / maintainability / CI guardrails
• compatibility with real heterogeneous user setups

It avoids two bad extremes:

• too much alias magic
• too much canonical-only dogma

Question

Do you think the right long-term architecture is also this kind of split:

• execution model ID for transport/routing
• canonical capability ID for internal reasoning

Or do you prefer a different center of gravity?

In particular, I would love your take on what you think is the most elegant solution that still preserves compatibility for users coming through Antigravity, Copilot, CLIProxyAPI/Quotio, and similar setups.

If you have a stronger simpler model in mind, I would rather align to that now than keep hardening the wrong abstraction.