← graph

fix-model-prefix

Fix: model prefix should be nex: to match the handler name (deprecate local: and oai-compat:)

Metadata

Statusdone
Assignedagent-1118
Agent identityf51439356729d112a6c404803d88015d5b44832c6c584c62b96732b63c2b0c7e
Created2026-04-29T15:25:37.241654438+00:00
Started2026-04-29T15:26:00.854848275+00:00
Completed2026-04-29T15:56:27.410142803+00:00
Tagspriority-high,fix,naming,config, eval-scheduled
Eval score0.46
└ blocking impact0.35
└ completeness0.40
└ constraint fidelity0.70
└ coordination overhead0.50
└ correctness0.35
└ downstream usability0.60
└ efficiency0.75
└ intent fidelity0.89
└ style adherence0.45

Description

Description

Naming inconsistency that bites every new user. Handler-to-prefix mapping today:

HandlerUser runsModel prefix
claude CLIclaudeclaude:opus ✓
codex CLIcodexcodex:gpt-5.5 ✓
nex (in-process)wg nexlocal:* / oai-compat:* / openrouter:* ✗

The nex handler has THREE prefixes, none of which is nex:. local: is misleading (works fine for non-local Tailscale / OpenAI-hosted endpoints). oai-compat: describes a protocol, not a handler. openrouter: is its own special case (implicit endpoint).

User quote: 'but its nex. not oai compat. its nex! wg nex runs'

Goal

Add nex:<model> as the canonical prefix for the in-process nex handler. The model prefix should match the handler / subcommand name, like claude and codex do.

Scope

  1. Add nex:<model> prefix routed to the nex handler. Use any explicit endpoint set via -e or [[llm_endpoints.endpoints]].
  2. Deprecate local: and oai-compat: as prefixes:
    • One-release window: continue accepting them, with stderr deprecation warning naming the new prefix
    • Migration: wg migrate config rewrites local:X → nex:X (same with oai-compat:X)
    • Remove in release after deprecation
  3. Keep openrouter: as a special case with implicit endpoint (api.openrouter.ai). Still routes through nex but the convenience of not specifying an endpoint is worth keeping.
  4. Update routes (claude-cli, codex-cli, openrouter, local, nex-custom) to use nex: where they currently use local: or oai-compat:.
  5. Update starter profiles (~/.wg/profiles/nex.toml) — the file content should use nex: not local:.
  6. Update docs and CLAUDE.md examples — every local:qwen3-coder example becomes nex:qwen3-coder. Every oai-compat:gpt-5 becomes nex:gpt-5 if a generic example, or stays oai-compat: if specifically illustrating the protocol detection. Probably the former in all cases.

Where the handler resolution lives

src/dispatch/handler_for_model.rs — the prefix → handler mapping. Likely just a match arm to add for nex: and deprecation warnings on the legacy names.

Validation

  • Failing test written first: wg init -m nex:qwen3-coder -e https://example.com produces a config that the dispatcher loads without error and routes to the nex handler
  • Test: wg init -m local:X -e ... still works but emits a stderr deprecation warning naming nex: as the new canonical
  • Test: wg migrate config rewrites local:/oai-compat: to nex: in existing configs (with .bak backup)
  • Live smoke: starting fresh, wg init -m nex:qwen3-coder -e https://lambda01.tail334fe6.ts.net:30000 → wg service start → spawn a worker → confirm WG_EXECUTOR_TYPE=native (or whatever the nex handler reports) AND WG_MODEL=nex:qwen3-coder
  • Starter profile nex.toml uses nex: prefix internally (not local:)
  • codex-cli, claude-cli, openrouter routes unchanged (they don't use local/oai-compat); local + nex-custom routes updated to use nex:
  • Docs sweep: zero remaining local: model strings outside the deprecation back-compat layer; zero oai-compat: outside same. CLAUDE.md examples updated.
  • cargo build + cargo test pass
  • Permanent smoke scenario added that exercises nex: prefix end-to-end with this task id in owners
  • cargo install --path . was run before claiming done

Process note

This is a UX cleanup that's been bitten the user every time they look at the config. Match handler-name → prefix-name and the mental model collapses to one rule: 'the prefix is the handler.' Don't ship a half-rename like fix-complete-the / rename-wgnext-profile required two attempts to land — finish the rename here, including docs, profiles, routes, and tests.

Depends on

Required by

Log