feat(converters): centralize model field normalization across targets (#442)
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Trevin Chow
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: "Cross-platform model field normalization for target converters"
|
||||
date: 2026-03-29
|
||||
category: integration-issues
|
||||
module: src/converters
|
||||
problem_type: integration_issue
|
||||
component: tooling
|
||||
symptoms:
|
||||
- "Target platforms received raw Claude model aliases (e.g., 'sonnet') they could not resolve"
|
||||
- "Qwen converter mapped model aliases to wrong canonical names (claude-sonnet instead of claude-sonnet-4-6)"
|
||||
- "OpenClaw and Copilot passed through unnormalized model values in formats the target could not use"
|
||||
- "Duplicated CLAUDE_FAMILY_ALIASES and normalizeModel logic across converters with divergent alias values"
|
||||
root_cause: config_error
|
||||
resolution_type: code_fix
|
||||
severity: medium
|
||||
tags:
|
||||
- model-normalization
|
||||
- converters
|
||||
- cross-platform
|
||||
- opencode
|
||||
- qwen
|
||||
- droid
|
||||
- copilot
|
||||
- openclaw
|
||||
- codex
|
||||
---
|
||||
|
||||
# Cross-platform model field normalization for target converters
|
||||
|
||||
## Problem
|
||||
|
||||
Claude Code uses bare model aliases (`model: sonnet`, `model: haiku`, `model: opus`) in agent and command frontmatter. Each target platform expects a different format for the model field, but the converters handled this inconsistently — some passed through raw values, others had duplicated normalization logic with wrong alias mappings.
|
||||
|
||||
## Symptoms
|
||||
|
||||
- OpenClaw passed `model: sonnet` through raw — invalid on a platform expecting `anthropic/claude-sonnet-4-6`
|
||||
- Qwen mapped `sonnet` to `anthropic/claude-sonnet` instead of `anthropic/claude-sonnet-4-6` (wrong alias in its local copy of `CLAUDE_FAMILY_ALIASES`)
|
||||
- Copilot passed through raw Claude model IDs like `claude-sonnet-4-20250514` — Copilot uses display-name format ("Claude Opus 4.5"), not model IDs
|
||||
- Codex emitted no model field — correct behavior, but accidental (no deliberate handling)
|
||||
- Droid passed through as-is — correct behavior, but undocumented as intentional
|
||||
- Two copies of `CLAUDE_FAMILY_ALIASES` existed in OpenCode and Qwen converters with divergent values
|
||||
|
||||
## What Didn't Work
|
||||
|
||||
- **Passing model through as-is**: works for Droid (Factory natively resolves bare aliases), breaks OpenClaw/Qwen/OpenCode
|
||||
- **Mapping bare aliases to incomplete model names**: Qwen's `sonnet` -> `claude-sonnet` was wrong; correct is `claude-sonnet-4-6`
|
||||
- **Assuming all targets want the same model format**: each platform has fundamentally different expectations
|
||||
- **Assuming Codex skills support model overrides in frontmatter**: they don't — confirmed by the Rust source `SkillFrontmatter` struct which only has `name` and `description`
|
||||
- **Initial assumption that Qwen should drop model entirely**: wrong — Qwen is multi-provider and supports Anthropic models via `settings.json` with `anthropic` provider config
|
||||
- **Initial assumption that Copilot doesn't support models**: wrong — Copilot supports multi-model including Claude, but the exact format is uncertain (display names vs model IDs)
|
||||
|
||||
## Solution
|
||||
|
||||
Created `src/utils/model.ts` with shared normalization utilities:
|
||||
|
||||
```typescript
|
||||
// Single source of truth for bare Claude family aliases
|
||||
export const CLAUDE_FAMILY_ALIASES: Record<string, string> = {
|
||||
haiku: "claude-haiku-4-5",
|
||||
sonnet: "claude-sonnet-4-6",
|
||||
opus: "claude-opus-4-6",
|
||||
}
|
||||
|
||||
// Resolve bare alias without provider prefix (used by Droid)
|
||||
export function resolveClaudeFamilyAlias(model: string): string
|
||||
|
||||
// Add provider prefix based on naming conventions
|
||||
export function addProviderPrefix(model: string): string
|
||||
|
||||
// Combined: resolve + prefix (used by OpenCode, Qwen, OpenClaw)
|
||||
export function normalizeModelWithProvider(model: string): string
|
||||
```
|
||||
|
||||
Each converter now uses the appropriate shared utility:
|
||||
|
||||
| Target | Behavior | Output for `model: sonnet` |
|
||||
|--------|----------|----------------------------|
|
||||
| OpenCode | Resolve alias + add provider prefix | `anthropic/claude-sonnet-4-6` |
|
||||
| Qwen | Resolve alias + add provider prefix | `anthropic/claude-sonnet-4-6` |
|
||||
| OpenClaw | Resolve alias + add provider prefix | `anthropic/claude-sonnet-4-6` |
|
||||
| Droid | Pass through as-is | `sonnet` |
|
||||
| Copilot | Drop entirely | (omitted) |
|
||||
| Codex | Drop entirely | (omitted) |
|
||||
|
||||
---
|
||||
|
||||
## Why This Works
|
||||
|
||||
Each platform has fundamentally different model handling requirements:
|
||||
|
||||
**Platforms that normalize (OpenCode, Qwen, OpenClaw):** These are multi-provider platforms that support Anthropic, OpenAI, Google, and other model providers. They need provider-prefixed IDs like `anthropic/claude-sonnet-4-6` to route requests to the correct backend. The `normalizeModelWithProvider` function resolves bare aliases and adds the appropriate prefix.
|
||||
|
||||
**Droid (Factory) — pass-through:** Factory is multi-provider but natively resolves Claude's bare aliases (`sonnet`, `opus`, `haiku`) internally. Pass-through is correct and simpler than normalizing to a format Factory would also accept but doesn't require. Factory also accepts full dated model IDs like `claude-sonnet-4-5-20250929` and non-Anthropic models prefixed with `custom:`.
|
||||
|
||||
**Copilot — drop:** Copilot supports a `model` field in `.agent.md` frontmatter (documented in `docs/specs/copilot.md`), but the expected values are Copilot-specific display names like "Claude Opus 4.5" — not Claude model IDs like `claude-sonnet-4-20250514` or bare aliases like `sonnet`. Passing through Claude-specific values would emit a field Copilot can't use. Unlike Droid (which natively resolves `sonnet`), Copilot has no documented resolution for Claude model IDs. Dropping is safer: the spec says "If unset, inherits the default model."
|
||||
|
||||
**Codex — drop:** Codex skill frontmatter (`SKILL.md`) only supports `name` and `description` fields. This was confirmed by examining the Rust source code (`SkillFrontmatter` struct in `codex-rs/core-skills/src/loader.rs`). Model selection in Codex is global via `config.toml` or runtime `/model` command, not per-skill.
|
||||
|
||||
---
|
||||
|
||||
## Target platform model field reference
|
||||
|
||||
This reference captures research findings as of 2026-03-29.
|
||||
|
||||
### OpenCode
|
||||
- **Model format:** `provider/model-id` (e.g., `anthropic/claude-sonnet-4-6`)
|
||||
- **Provider prefixes:** `anthropic/`, `openai/`, `google/`
|
||||
- **Docs:** Agents defined in `.opencode/agents/*.md`
|
||||
|
||||
### Qwen
|
||||
- **Model format:** `provider/model-id` (e.g., `anthropic/claude-sonnet-4-6`)
|
||||
- **Multi-provider:** Yes — supports Anthropic, OpenAI, Google GenAI via `settings.json`
|
||||
- **Configuration example:** `"anthropic": [{"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4", "envKey": "ANTHROPIC_API_KEY"}]`
|
||||
- **Common misconception:** Qwen is NOT limited to its own foundation model
|
||||
|
||||
### Droid (Factory)
|
||||
- **Model format:** Bare names (`sonnet`, `claude-sonnet-4-5-20250929`) or `custom:<model>` for BYOK
|
||||
- **Native alias resolution:** Factory resolves `sonnet`, `opus`, `haiku` internally
|
||||
- **Multi-provider:** Yes — supports Anthropic, OpenAI, Google, and Factory's own `droid-core`
|
||||
- **Docs:** Custom droids defined in `.factory/droids/*.md`
|
||||
|
||||
### Copilot
|
||||
- **Model format:** Display names (e.g., "Claude Opus 4.5", "GPT-5.2"), possibly array syntax `model: ['Claude Opus 4.5', 'GPT-5.2']`
|
||||
- **Multi-provider:** Yes — supports Claude and GPT models
|
||||
- **Current converter behavior:** Drop (Claude model IDs don't map to Copilot's expected format)
|
||||
- **Note:** Spec says "may be ignored on github.com" — model selection works in IDE but may not apply on the GitHub web platform
|
||||
- **Docs:** Agents defined in `.github/agents/*.agent.md`
|
||||
|
||||
### OpenClaw
|
||||
- **Model format:** `provider/model-id` (same as OpenCode)
|
||||
- **Docs:** Skills defined in `skills/*/SKILL.md`
|
||||
|
||||
### Codex
|
||||
- **Model field in skill frontmatter:** NOT SUPPORTED
|
||||
- **Supported frontmatter fields:** `name`, `description` only
|
||||
- **Model configuration:** Global `config.toml` (`model = "gpt-5.4"`) or runtime `/model` command
|
||||
- **Valid model IDs (as of 2026-03):** `gpt-5.4` (flagship), `gpt-5.4-mini` (fast), `gpt-5.3-codex` (coding-specialized)
|
||||
- **Deprecated:** `codex-mini-latest` (removed Feb 2026)
|
||||
- **Docs:** Skills defined in `.codex/skills/*/SKILL.md` or `.agents/skills/*/SKILL.md`
|
||||
|
||||
---
|
||||
|
||||
## Prevention
|
||||
|
||||
1. **Research before implementing:** When adding a new converter target, research its model field format with external documentation before assuming pass-through or copying from another converter. The format varies significantly between platforms.
|
||||
|
||||
2. **Single source of truth:** The `CLAUDE_FAMILY_ALIASES` map in `src/utils/model.ts` is the canonical alias map. Update it there — not in individual converters — when new Claude model generations are released.
|
||||
|
||||
3. **Test coverage:** Run `bun test` after model-related changes. The test suite covers model handling across all converters (`tests/model-utils.test.ts` plus each converter's test file).
|
||||
|
||||
4. **Don't assume format from the field name:** A `model` field in frontmatter doesn't mean the format is the same across platforms. OpenCode wants `anthropic/claude-sonnet-4-6`, Factory wants `sonnet`, Copilot wants "Claude Sonnet 4", and Codex doesn't support the field at all.
|
||||
|
||||
5. **When in doubt, drop:** If you can't confidently produce the target's expected format, omit the field rather than emitting a potentially invalid value. Most platforms fall back to a sensible default when model is unset.
|
||||
|
||||
## Related Issues
|
||||
|
||||
- `docs/solutions/adding-converter-target-providers.md` — Converter architecture doc; should be updated to reference model normalization as part of the conversion pattern
|
||||
- `docs/solutions/integrations/colon-namespaced-names-break-windows-paths-2026-03-26.md` — Structural analog: same pattern of per-target boundary normalization
|
||||
- `docs/specs/codex.md` — Platform spec (last verified 2026-01-21); confirms skill frontmatter limitations
|
||||
Reference in New Issue
Block a user