Skip to content

feat(routing): honor lynkr-* tier ids on the OpenAI-compatible endpoints - #139

Open
officialasishkumar wants to merge 1 commit into
Fast-Editor:mainfrom
officialasishkumar:feat/openai-virtual-tier-pins
Open

officialasishkumar wants to merge 1 commit into
Fast-Editor:mainfrom
officialasishkumar:feat/openai-virtual-tier-pins

Conversation

@officialasishkumar

Copy link
Copy Markdown
Contributor

Description

Fixes #32

#32 asks how to switch model from a client, how to tell which model answered, how to change the switching rules, and how to give each CLI its own model (for example Ollama in Claude Code and GLM in opencode). Lynkr already has the pieces for most of this, but they were spread across several docs, and one of them didn't work on half of the endpoints.

The lynkr-auto / lynkr-simple / lynkr-medium / lynkr-complex / lynkr-reasoning ids (src/routing/model-slots.js) pin a tier on /v1/messages, and documentation/opencode.md says they "work from any client". The OpenAI-format handlers (/v1/chat/completions, /v1/responses) never go through router.js's pin code, though. They only know Codex's (model, reasoning.effort) mapping. So:

  • a Codex CLI, Cline, Continue or Kilo user with model = "lynkr-reasoning" got content scoring instead of the tier they asked for;
  • lynkr-auto from Codex was pinned by whatever effort Codex sends (it sends one on every request), so "auto" never meant auto there.

This PR makes the ids work on the OpenAI endpoints too, and adds one guide that answers the four questions in the issue.

Type of Change

  • Bug fix
  • New feature
  • Documentation update
  • Performance improvement
  • Refactoring

Changes Made

  • src/routing/openai-model-slots.js: new resolveOpenAIRequestPin(model, effort) returning { tier, method } or null:
    1. A virtual tier id in model (case-insensitive, same table as the Anthropic route) pins its tier with method model_id_pin, the label router.js already uses. It also takes precedence over the effort mapping. lynkr-auto means no pin and skips the effort mapping.
    2. Anything else keeps the existing (model, effort) mapping, still labelled openai_model_effort_pin.
  • src/api/openai-router.js: both /chat/completions and /responses call the new resolver. The pinned tier still goes through the existing _forceProvider / _tierModel / _tierName / _forcedMethod fields, so telemetry, headers and the badge work as before.
  • documentation/model-switching.md (new): answers the four questions in Switching not clear! #32. It covers picking a tier from Claude Code, opencode, Codex and OpenAI-compatible clients; seeing which model served a request (lynkr-statusline, the LYNKR_VISIBLE_ROUTING badge, X-Lynkr-* headers, /dashboard, lynkr route --preview); changing the rules (TIER_* in .env, reloaded on save; force patterns); and giving each CLI its own model, with the limits of that approach.
  • documentation/tier-pinning.md: the virtual ids are documented as a third mechanism next to Claude Desktop slots and the Codex effort mapping.
  • documentation/codex-cli.md: new "Pinning a Routing Tier" section (model = "lynkr-…" / codex -m).
  • documentation/faq.md, documentation/README.md: short FAQ entry and index link to the new guide.
  • test/openai-virtual-tier-pin.test.js (added to test:unit).

Testing

  • Existing tests pass
  • Added new tests
  • Manual testing performed

test/openai-virtual-tier-pin.test.js has 13 tests:

  • Resolver: precedence over effort, case-insensitive ids, lynkr-auto suppressing the effort pin, the effort mapping unchanged for real model ids, and junk input.
  • End to end: both endpoints through the real Express app with a mocked orchestrator, using the same harness as openai-ingress-tool-injection.test.js. These assert the pinned tier's provider and model reach the orchestrator. The four end-to-end pin cases fail without the router change.

I ran the full test:unit list on this branch and on main. Failures are identical on both: all of them come from better-sqlite3 not being built in my local install. The 13 new tests all pass. eslint src index.js --max-warnings 0 is clean.

Manual check: I ran Lynkr against a local mock OpenAI-compatible upstream, with each tier set to openai:mock-<tier>:

  • /v1/chat/completions with lynkr-reasoning reached the upstream as mock-reasoning.
  • lynkr-simple + reasoning_effort: "high" reached it as mock-simple.
  • /v1/responses with lynkr-medium + effort high reached it as mock-medium.
  • lynkr-auto + effort high was content-routed (SIMPLE for "hi"). Before this change it was pinned to REASONING.
  • gpt-5.6-sol + high still pins REASONING.

The badge and the headers described in the guide were checked on the same server.

Checklist

  • Code follows style guidelines
  • Documentation updated
  • Tests added/updated
  • No new warnings

The virtual tier ids lynkr-auto / lynkr-simple / lynkr-medium /
lynkr-complex / lynkr-reasoning (src/routing/model-slots.js) pinned their
tier only on the Anthropic /v1/messages route, even though the opencode
docs promise they "work from any client". /v1/chat/completions and
/v1/responses never go through router.js's pin code and only knew Codex's
(model, reasoning.effort) mapping, so a Codex CLI, Cline, Continue or Kilo
user who set `model = "lynkr-reasoning"` silently got content scoring
instead of the tier they asked for. Worse, `lynkr-auto` from Codex was
pinned by whatever effort Codex attached (it sends one on every request),
so "auto" never meant auto there.

Add resolveOpenAIRequestPin() to src/routing/openai-model-slots.js and
use it from both OpenAI handlers:

  1. A virtual tier id in `model` (case-insensitive, same table as the
     Anthropic route) pins its tier with method `model_id_pin`, the label
     router.js already uses, and outranks the effort mapping.
     `lynkr-auto` is an explicit no-pin and skips the effort mapping.
  2. Anything else keeps the existing (model, effort) mapping, still
     labelled `openai_model_effort_pin`.

The pinned tier rides the same _forceProvider/_tierModel plumbing as
before, so downstream behavior (telemetry, headers, badge) is unchanged.

Docs: new documentation/model-switching.md answers the questions from
issue Fast-Editor#32 in one place: how to pick a tier from Claude Code, opencode,
Codex and OpenAI-compatible clients; how to see which model served a
request (status line, LYNKR_VISIBLE_ROUTING badge, X-Lynkr-* headers,
dashboard, `lynkr route --preview`); how to change the rules (hot-reloaded
TIER_* in .env, force patterns); and how to give each CLI its own model.
tier-pinning.md documents the virtual ids as a third mechanism,
codex-cli.md gains a "Pinning a Routing Tier" section, and the FAQ and
documentation index link the new guide.

Tests: test/openai-virtual-tier-pin.test.js covers the resolver
(precedence, case-insensitivity, lynkr-auto suppressing the effort pin,
unchanged effort mapping, junk input) and drives both endpoints end to
end through the real Express app with a mocked orchestrator, asserting
the pinned tier's provider/model reach the orchestrator. The four
end-to-end pin cases fail without the router change.
@github-actions

Copy link
Copy Markdown
Contributor

✅ OpenCodeReview: Review complete: 0 finding(s) across 3 selected item(s).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Switching not clear!

1 participant